Package: tamp
TampTamp is a low-memory, DEFLATE-inspired lossless compression library.FeaturesVarious implementations available:Pure Python:tamp/compressor.py,tamp/decompressor.pyWhen available, Tamp will use a python-bound C implementation for speed.C library:tamp/_c_src/High compression ratios and low memory use.Compact compression and decompression implementations.Compiled C library is <4KB (compressor + decompressor).Mid-stream flushing.Allows for submission of messages while continuing to compress subsequent data.Customizable dictionary for greater compression of small messages.Convenient CLI interface.InstallationTamp contains 3 implementations:A desktop Cpython implementation that is optimized for readabilityA micropython viper implementation that is optimized for runtime performance.A C implementation (with python bindings) for accelerated desktop use and to be used in C projects.Desktop PythonThe Tamp library and CLI requires Python>=3.8and can be installed via:pipinstalltampMicroPythonFor micropython use, there are 3 main files:tamp/__init__.py- Always required.tamp/decompressor_viper.py- Required for on-device decompression.tamp/compressor_viper.py- Required for on-device compression.For example, if on-device decompression isn’t used, then do not includedecompressor_viper.py.
If manually installing, just copy these files to your microcontroller’s/lib/tampfolder.If usingmip, tamp can be installed by specifying the appropriatepackage-*.jsonfile.mipinstallgithub:brianpugh/tamp# Defaults to package.json: Compressor & Decompressormipinstallgithub:brianpugh/tamp/package-compressor.json# Compressor onlymipinstallgithub:brianpugh/tamp/package-decompressor.json# Decompressor onlyIf usingBelay, tamp can be installed by adding the following topyproject.toml.[tool.belay.dependencies]tamp=["https://github.com/BrianPugh/tamp/blob/main/tamp/__init__.py","https://github.com/BrianPugh/tamp/blob/main/tamp/compressor_viper.py","https://github.com/BrianPugh/tamp/blob/main/tamp/decompressor_viper.py",]CCopy thetamp/_c_src/tampfolder into your project.
For more information, seethe documentation.UsageTamp works on desktop python and micropython. On desktop, Tamp is bundled with thetampcommand line tool for compressing and decompressing tamp files.CLICompressionUsetamp compressto compress a file or stream.
If no input file is specified, data from stdin will be read.
If no output is specified, the compressed output stream will be written to stdout.$tampcompress--helpUsage:tampcompress[OPTIONS][INPUT_PATH]Compressaninputfileorstream.╭─Arguments────────────────────────────────────────────────────────────────────────╮│input_path[INPUT_PATH]Inputfiletocompressordecompress.Defaultsto││stdin.│╰────────────────────────────────────────────────────────────────────────────────────╯╭─Options──────────────────────────────────────────────────────────────────────────╮│--output-oPATHOutputfile.Defaultstostdout.││--window-wINTEGERRANGE[8<=x<=15]Numberofbitsusedtorepresentthe││dictionarywindow.││[default:10]││--literal-lINTEGERRANGE[5<=x<=8]Numberofbitsusedtorepresenta││literal.││[default:8]││--helpShowthismessageandexit.│╰────────────────────────────────────────────────────────────────────────────────────╯Example usage:tampcompressenwik8-oenwik8.tamp# Compress a fileecho"hello world"|tampcompress|wc-c# Compress a stream and print the compressed size.The following options can impact compression ratios and memory usage:window-2^windowplaintext bytes to look back to try and find a pattern.
A larger window size will increase the chance of finding a longer pattern match,
but will use more memory, increase compression time, and cause each pattern-token
to take up more space. Try smaller window values if compressing highly repetitive
data, or short messages.literal- Number of bits used in each plaintext byte. For example, if all input
data is 7-bit ASCII, then setting this to 7 will improve literal compression
ratios by 11.1%. The default, 8-bits, can encode any binary data.DecompressionUsetamp decompressto decompress a file or stream.
If no input file is specified, data from stdin will be read.
If no output is specified, the compressed output stream will be written to stdout.$tampdecompress--helpUsage:tampdecompress[OPTIONS][INPUT_PATH]Decompressaninputfileorstream.╭─Arguments────────────────────────────────────────────────────────────────────────╮│input_path[INPUT_PATH]Inputfile.Ifnotprovided,readsfromstdin.│╰────────────────────────────────────────────────────────────────────────────────────╯╭─Options──────────────────────────────────────────────────────────────────────────╮│--output-oPATHOutputfile.Defaultstostdout.││--helpShowthismessageandexit.│╰────────────────────────────────────────────────────────────────────────────────────╯Example usage:tampdecompressenwik8.tamp-oenwik8echo"hello world"|tampcompress|tampdecompressPythonThe python library can perform one-shot compression, as well as operate on files/streams.importtamp# One-shot compressionstring=b"I scream, you scream, we all scream for ice cream."compressed_data=tamp.compress(string)reconstructed=tamp.decompress(compressed_data)assertreconstructed==string# Streaming compressionwithtamp.open("output.tamp","wb")asf:for_inrange(10):f.write(string)# Streaming decompressionwithtamp.open("output.tamp","rb")asf:reconstructed=f.read()BenchmarkIn the following section, we compare Tamp against:zlib, a python builtin gzip-compatible DEFLATE compression library.heatshrink, a data compression library for embedded/real-time systems.
Heatshrink has similar goals as Tamp.All of these are LZ-based compression algorithms, and tests were performed using a 1KB (10 bit) window.
Since zlib already uses significantly more memory by default, the lowest memory level (memLevel=1) was used in
these benchmarks. It should be noted that higher zlib memory levels will having greater compression ratios than Tamp.
Currently, there is no micropython-compatible zlib or heatshrink compression implementation, so these numbers are
provided simply as a reference.Compression RatioThe following table shows compression algorithm performance over a variety of input data sourced from theSilesia CorpusandEnwik8. This should give a general idea of how these algorithms perform over a variety of input data types.datasetrawtampzlibheatshrinkenwik8100,000,00051,635,63356,205,16656,110,394build/silesia/dickens10,192,4465,546,7616,049,1696,155,768build/silesia/mozilla51,220,48025,121,38525,104,96625,435,908build/silesia/mr9,970,5645,027,0324,864,7345,442,180build/silesia/nci33,553,4458,643,6105,765,5218,247,487build/silesia/ooffice6,152,1923,814,9384,077,2773,994,589build/silesia/osdb10,085,6848,520,8358,625,1598,747,527build/silesia/reymont6,627,2022,847,9812,897,6612,910,251build/silesia/samba21,606,4009,102,5948,862,4239,223,827build/silesia/sao7,251,9446,137,7556,506,4176,400,926build/silesia/webster41,458,70318,694,17220,212,23519,942,817build/silesia/x-ray8,474,2407,510,6067,351,7508,059,723build/silesia/xml5,345,2801,681,6871,586,9851,665,179Tamp usually out-performs heatshrink, and is generally very competitive with zlib.
While trying to be an apples-to-apples comparison, zlib still uses significantly more
memory during both compression and decompression (see next section). Tamp accomplishes
competitive performance while using around 10x less memory.Memory UsageThe following table shows approximately how much memory each algorithm uses during compression and decompression.ActiontampzlibheatshrinkCompression(1 << windowBits)(1 << (windowBits+2)) + 7 KB(1 << windowBits)Decompression(1 << windowBits)(1 << windowBits) + 7 KB(1 << windowBits)Both tamp and heatshrink have a few dozen bytes of overhead in addition to the primary window buffer, but are implementation-specific and ignored for clarity here.RuntimeAs a rough benchmark, here is the performance (in seconds) of these different compression algorithms on the 100MB enwik8 dataset.
These tests were performed on an M1 Macbook Air.Actiontamp
(Python Reference)tamp
(C)zlibheatshrink
(with index)heatshrink
(without index)Compression109.516.454.846.2241.729Decompression54.00.700.980.820.82Heatshrink v0.4.1 was used in these benchmarks.
When heathshrink uses an index, an additional(1 << (windowBits + 1))bytes of memory are used, tripling the memory requirement.
Tamp could use a similar indexing to increase compression speed, but has chosen not to to focus on the primary goal of a low-memory compressor.To give an idea of Tamp’s speed on an embedded device, the following table shows compression/decompression inbytes/second of the first 100KB of enwik8 on a pi pico (rp2040)at the default 125MHz clock rate.
This isn’t exactly an apples-to-apples comparison because the C benchmark does not use a filesystem (and thusly, reduced overhead) nor dynamic memory allocation, but is good enough to get the idea across.Actiontamp
(Micropython Viper)tamp
(C)Compression~4,300~28,500Decompression~42,000~1,042,524Binary SizeTo give an idea on the resulting binary sizes, Tamp and other libraries were compiled for the Pi Pico (armv6m).
All libraries were compiled with-O3.
Numbers reported in bytes.LibraryCompressorDecompressorCompressor + DecompressorTamp (micropython)442942057554Tamp (C)200819723864Heatshrink295638766832uzlib235539636318Heatshrink doesn’t include a high level API; in an apples-to-apples comparison the Tamp library would be even smaller.