{"id":13812865,"url":"https://github.com/atomicobject/heatshrink","last_synced_at":"2025-05-15T16:05:47.149Z","repository":{"id":37759439,"uuid":"8751126","full_name":"atomicobject/heatshrink","owner":"atomicobject","description":"data compression library for embedded/real-time systems","archived":false,"fork":false,"pushed_at":"2024-05-19T06:44:22.000Z","size":201,"stargazers_count":1408,"open_issues_count":37,"forks_count":197,"subscribers_count":64,"default_branch":"master","last_synced_at":"2025-05-11T02:57:11.311Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/atomicobject.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2013-03-13T11:55:08.000Z","updated_at":"2025-05-08T01:12:15.000Z","dependencies_parsed_at":"2024-01-31T09:02:32.101Z","dependency_job_id":"63bcaa30-3675-474d-9c3e-e18cb6117954","html_url":"https://github.com/atomicobject/heatshrink","commit_stats":{"total_commits":106,"total_committers":8,"mean_commits":13.25,"dds":"0.34905660377358494","last_synced_commit":"7d419e1fa4830d0b919b9b6a91fe2fb786cf3280"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atomicobject%2Fheatshrink","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atomicobject%2Fheatshrink/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atomicobject%2Fheatshrink/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atomicobject%2Fheatshrink/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/atomicobject","download_url":"https://codeload.github.com/atomicobject/heatshrink/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254374427,"owners_count":22060611,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-04T04:00:56.890Z","updated_at":"2025-05-15T16:05:47.130Z","avatar_url":"https://github.com/atomicobject.png","language":"C","readme":"# heatshrink\n\nA data compression/decompression library for embedded/real-time systems.\n\n\n## Key Features:\n\n- **Low memory usage (as low as 50 bytes)**\n    It is useful for some cases with less than 50 bytes, and useful\n    for many general cases with \u003c 300 bytes.\n- **Incremental, bounded CPU use**\n    You can chew on input data in arbitrarily tiny bites.\n    This is a useful property in hard real-time environments.\n- **Can use either static or dynamic memory allocation**\n    The library doesn't impose any constraints on memory management.\n- **ISC license**\n    You can use it freely, even for commercial purposes.\n\n\n## Getting Started:\n\nThere is a standalone command-line program, `heatshrink`, but the\nencoder and decoder can also be used as libraries, independent of each\nother. To do so, copy `heatshrink_common.h`, `heatshrink_config.h`, and\neither `heatshrink_encoder.c` or `heatshrink_decoder.c` (and their\nrespective header) into your project. For projects that use both,\nstatic libraries are built that use static and dynamic allocation.\n\nDynamic allocation is used by default, but in an embedded context, you\nprobably want to statically allocate the encoder/decoder. Set\n`HEATSHRINK_DYNAMIC_ALLOC` to 0 in `heatshrink_config.h`.\n\n\n### Basic Usage\n\n1. Allocate a `heatshrink_encoder` or `heatshrink_decoder` state machine\nusing their `alloc` function, or statically allocate one and call their\n`reset` function to initialize them. (See below for configuration\noptions.)\n\n2. Use `sink` to sink an input buffer into the state machine. The\n`input_size` pointer argument will be set to indicate how many bytes of\nthe input buffer were actually consumed. (If 0 bytes were conusmed, the\nbuffer is full.)\n\n3. Use `poll` to move output from the state machine into an output\nbuffer. The `output_size` pointer argument will be set to indicate how\nmany bytes were output, and the function return value will indicate\nwhether further output is available. (The state machine may not output\nany data until it has received enough input.)\n\nRepeat steps 2 and 3 to stream data through the state machine. Since\nit's doing data compression, the input and output sizes can vary\nsignificantly. Looping will be necessary to buffer the input and output\nas the data is processed.\n\n4. When the end of the input stream is reached, call `finish` to notify\nthe state machine that no more input is available. The return value from\n`finish` will indicate whether any output remains. if so, call `poll` to\nget more.\n\nContinue calling `finish` and `poll`ing to flush remaining output until\n`finish` indicates that the output has been exhausted.\n\nSinking more data after `finish` has been called will not work without\ncalling `reset` on the state machine.\n\n\n## Configuration\n\nheatshrink has a couple configuration options, which impact its resource\nusage and how effectively it can compress data. These are set when\ndynamically allocating an encoder or decoder, or in `heatshrink_config.h`\nif they are statically allocated.\n\n- `window_sz2`, `-w` in the CLI: Set the window size to 2^W bytes.\n\nThe window size determines how far back in the input can be searched for\nrepeated patterns. A `window_sz2` of 8 will only use 256 bytes (2^8),\nwhile a `window_sz2` of 10 will use 1024 bytes (2^10). The latter uses\nmore memory, but may also compress more effectively by detecting more\nrepetition.\n\nThe `window_sz2` setting currently must be between 4 and 15.\n\n- `lookahead_sz2`, `-l` in the CLI: Set the lookahead size to 2^L bytes.\n\nThe lookahead size determines the max length for repeated patterns that\nare found. If the `lookahead_sz2` is 4, a 50-byte run of 'a' characters\nwill be represented as several repeated 16-byte patterns (2^4 is 16),\nwhereas a larger `lookahead_sz2` may be able to represent it all at\nonce. The number of bits used for the lookahead size is fixed, so an\noverly large lookahead size can reduce compression by adding unused\nsize bits to small patterns.\n\nThe `lookahead_sz2` setting currently must be between 3 and the\n`window_sz2` - 1.\n\n- `input_buffer_size` - How large an input buffer to use for the\ndecoder. This impacts how much work the decoder can do in a single\nstep, and a larger buffer will use more memory. An extremely small\nbuffer (say, 1 byte) will add overhead due to lots of suspend/resume\nfunction calls, but should not change how well data compresses.\n\n\n### Recommended Defaults\n\nFor embedded/low memory contexts, a `window_sz2` in the 8 to 10 range is\nprobably a good default, depending on how tight memory is. Smaller or\nlarger window sizes may make better trade-offs in specific\ncircumstances, but should be checked with representative data.\n\nThe `lookahead_sz2` should probably start near the `window_sz2`/2, e.g.\n-w 8 -l 4 or -w 10 -l 5. The command-line program can be used to measure\nhow well test data works with different settings.\n\n\n## More Information and Benchmarks:\n\nheatshrink is based on [LZSS], since it's particularly suitable for\ncompression in small amounts of memory. It can use an optional, small\n[index] to make compression significantly faster, but otherwise can run\nin under 100 bytes of memory. The index currently adds 2^(window size+1)\nbytes to memory usage for compression, and temporarily allocates 512\nbytes on the stack during index construction (if the index is enabled).\n\nFor more information, see the [blog post] for an overview, and the\n`heatshrink_encoder.h` / `heatshrink_decoder.h` header files for API\ndocumentation.\n\n[blog post]: http://spin.atomicobject.com/2013/03/14/heatshrink-embedded-data-compression/\n[index]: http://spin.atomicobject.com/2014/01/13/lightweight-indexing-for-embedded-systems/\n[LZSS]: http://en.wikipedia.org/wiki/Lempel-Ziv-Storer-Szymanski\n\n\n## Build Status\n\n  [![Build Status](https://travis-ci.org/atomicobject/heatshrink.png)](http://travis-ci.org/atomicobject/heatshrink)\n","funding_links":[],"categories":["Compression","压缩","Data processing","compression"],"sub_categories":["Compression","Tracer"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fatomicobject%2Fheatshrink","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fatomicobject%2Fheatshrink","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fatomicobject%2Fheatshrink/lists"}