ofxAddons
Compress and decompress data using a large range of compression codecs supplied by libsquash
Branches ahead of master
These branches have commits not yet on master — could be unmerged fixes or work in progress worth a look.
README
ofxSquash
Squash is an open source library for compressing data, and comes with a range of compression algorithms. ofxSquash is a C++ wrapper for that libary for use with openFrameworks and supports both simple and stream API's.
Comprsesion algorithms
Squash ships with plugin implementations for the following algorithms:
brieflz brotli bsc bzip2 copy (no compression) crush csc density doboz fari fastlz gipfeli heatshrink libdeflate lz4 lzf lzg lzham lzjb lzma lzo miniz ms-compress ncompress pithy quicklz snappy wflz yalz77 zlib-ng zlib zling zpaq zstd
There's a really helpful system at https://quixdb.github.io/squash-benchmark/ which can help you choose which algorithm to pick for your data.
Unsupported algorithms
The following plugins do not work on these platforms:
OSX
csc ncompress quicklz
Windows
csc doboz pithy
Usage
Basic API
To get a list of available algorithms:
``
c++ auto codecs = ofxSquash::getCodecList(); cout << "Squash found " << codecs.size() << " codecs." << endl; for(auto & codec : codecs) { cout << " " << codec.getName() << endl; }
Generally we use the class ofxSquash::Codec for most of our work, e.g.:
c++ // create a Density codec object auto codec = ofxSquash::Codec("density");
//make something to compress string text = "Something to compress";
// compress the text using our codec auto compressedText = codec.compress(text);
// uncompress the text again, resulting in our original string auto uncompressedText = codec.uncompress(compressedText);
Stream API
Often whilst we're compressing, we might not want to pass the entire data to the codec at once, for example:
We're compressing from one file to another, and don't want to keep the entire contents in memory
Latency is an issue, and we want the next process to begin before compression is completed (e.g. transmit to the network whilst compression is still ongoing).
Check exampleStreamSimple for help on how to use this (note you need to provide a lambda function to ofxSquash::Stream. This function is called whenever there is data available to write).
c++ //initialise the codec auto codec = ofxSquash::Codec("density");//initialise the stream ofxSquash::Stream compressStream(codec, ofxSquash::Direction::Compress);
// Setup a WriteFunction for compression. // This function is called whenever the stream wants // to write to an output (e.g. a file or a network // stream). This function will be called periodically // as the stream compresses the data. compressStream.setWriteFunction([&decompressStream](const ofxSquash::WriteFunctionArguments & args) { // In this example, our 'write' code for the compressor just dumps the output to console auto compressedPacketString = string((const char)args.data, args.size); cout << compressedPacketString << endl; });
// Stream something into the compressor. string text = " \n\ ....XXXXXXXX \n\ ..XXX..ooooXXX \n\ ..X....oooo..X \n\ .X....oooooo..X \n\ XX...oo....oo.XX \n\ Xooooo......oooX \n\ Xo..oo......oooX \n\ X....o......oo.X \n\ X....oo....oo..X \n\ Xo..ooooooooo..X \n\ XoooXXXXXXXXoo.X \n\ .XXX..X..X..XXX \n\ ..X...X..X...X \n\ ..X..........X \n\ ...X........X \n\ ....XXXXXXXX \n\ "; compressStream << text;
// Important!! // We also need to send Finish to the stream compressStream << ofxSquash::Stream::Finish();
// The stream is now closed. It will reopen if you stream any more data into it `
Troubleshooting
ofxSquash doesn't find any plugins
Try:
Make sure you have a folder which can be found by ofToDataPath (we use this function when navigating to the plugins folder, so the bin/data path must exist even if it is empty). Make sure that the plugins are copied so that the directory structure is bin/plugins/squash/[codec name]/.
Compatability
This addon is tested and working with :
openFrameworks 0.9.0+ Visual Studio 2015 x64 (Windows 10) - XCode 7.2 x64 (OSX 10.11)
Note : On OSX, the ncompress` plugin crashes, so remove it from the plugins folder.License
ofxSquash
Copyright (c) 2015, Kimchi and Chips
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Squash
Squash is licensed under the MIT License, which is highly permissive and allows Squash to be integrated into any application virtually without restriction. That said, please keep in mind that some plugins use libraries which are subject to more restrictive terms (such as the GNU GPL), and using Squash as an intermediary does not release you from the obligations of those licenses if you choose to actually use plugins which use those libraries. Squash includes an API for programmatically determining the license of a plugin, and it is possible to use it to avoid any GPL'd plugins even if they are installed. Each plugin's page in the C documentation lists the license of the library, or libraries, it uses.
Several of the GPL libraries used by Squash plugins are also available for integration with proprietary software under commercial licenses.