ZMAT: A portable data compression/decompression toolbox for MATLAB/Octave
Precompiled mex download URL: https://github.com/fangq/zmat/releases/tag/v0.5
ZMat is a portable mex function to enable zlib/gzip based data compression/decompression and base64 encoding/decoding support in MATLAB and GNU Octave. It is fast and portable, can compress a large array within a fraction of a second.
ZMat accepts 3 types of inputs: char-based strings, uint8 arrays or vectors, or int8 arrays/vectors. Any other input format will result in an error unless you typecast the input into int8/uint8 format. A multi-dimensional char/int8/uint8 array is accepeted but will be processed as a 1D vector. One can reshape the output after decoding using the 2nd output "info" from zmat.
ZMat uses zlib - an open-source and widely used library for data compression. On Linux/Mac OSX, you need to have libz.so or libz.dylib installed in your system library path (defined by the environment variables LD_LIBRARY_PATH or DYLD_LIBRARY_PATH, respectively).
The pre-compiled mex binaries for both MATLAB and Octave are provided in a separate github repository
If you do not want to compile zmat yourself, you can download the precompiled package by either clicking on the "Download ZIP" button on the above URL, or use the below git command:
git clone https://github.com/fangq/zmat_mex.git
== Installation ==
The installation of ZMat is no different from any other simple MATLAB toolboxes. You only need to download/unzip the package to a folder, and add the folder's path to MATLAB/Octave's path list by using the following command:
If you want to add this path permanently, you need to type "pathtool", browse to the zmat root folder and add to the list, then click "Save". Then, run "rehash" in MATLAB, and type "which zmat", if you see an output, that means ZMax is installed for MATLAB/Octave.
If you use MATLAB in a shared environment such as a Linux server, the best way to add path is to type
and type addpath('/path/to/zmax') in this file, save and quit the editor. MATLAB will execute this file every time it starts. For Octave, the file you need to edit is ~/.octaverc , where "~" is your home directory.
== Using ZMat ==
ZMat provides a single mex function, zmat.mex* -- for both compressing/encoding or decompresing/decoding data streams. The help info of the function is shown below
== Help info ==
[output, info]=zmat(input, iscompress, method)
A portable data compression/decompression toolbox for MATLAB/GNU Octave
author: Qianqian Fang <q.fang at neu.edu>
date for initial version: 04/30/2019
input: a string, int8 or uint8 array
iscompress: (optional) if iscompress is 1, zmat compresses the input,
if 0, it decompresses the input. Default value is 1.
method: (optional) compression method, currently, zmat supports the below methods
'zlib': zlib/zip based data compression (default)
'gzip': gzip formatted data compression
'base64': encode or decode use base64 format
output: a uint8 row vector, storing the compressed or decompressed data
info: (optional) a struct storing additional info regarding the input data, may have
'type': the class of the input array
'size': the dimensions of the input array
'status': the zlib function return value, including potential error codes (<0)
[ss, info]=zmat(uint8(eye(5))) % compress an 5x5 identity matrix
orig=zmat(ss,0) % decompress the compressed matrix
orig=reshape(orig, info.size) % restore the original size using info output
ss=char(zmat('zmat test',1,'base64')) % encode a string using base64
orig=char(zmat(ss,0,'base64')) % decode the base64 string
-- this function is part of the zmat toolbox (http://github.com/fangq/zmat)
=== examples ===
Under the "example" folder, you can find a demo script showing the basic utilities of ZMat. Running the "demo_zmat_basic.m" script, you can see how to compress/decompress a simple array, as well as apply base64 encoding/decoding to strings.
Please run these examples and understand how ZMat works before you use it to process your data.
== Contribution and feedback ==
ZMat is an open-source project. This means you can not only use it and modify it as you wish, but also you can contribute your changes back to JSONLab so that everyone else can enjoy the improvement. For anyone who want to contribute, please download JSONLab source code from its source code repositories by using the following command:
git clone https://github.com/fangq/zmat.git zmat
or browsing the github site at
Qianqian Fang (2019). ZMat (https://www.github.com/fangq/zmat), GitHub. Retrieved .
* first public release
Create scripts with code, output, and formatted text in a single executable document.