zmat

ZMat: A portable C-library and MATLAB/Octave toolbox for zlib/gzip/lzma/lz4/lz4hc data compression

ZMAT: A portable data compression/decompression toolbox for MATLAB/Octave

v0.9.8 (Archie-the-goat - bet) URL: https://github.com/fangq/zmat/releases/tag/v0.9.8

--------------------------------

ZMat is a portable mex function to enable zlib/gzip/lzma/lzip/lz4/lz4hc based data compression/decompression and base64 encoding/decoding support in MATLAB and GNU Octave. It is fast and compact, can process a large array within a fraction of a second.

Among the 6 supported compression methods, lz4 is the fastest for compression/decompression; lzma is the slowest but has the highest compression ratio; zlib/gzip have the best balance between speed and compression time.

ZMat accepts 3 types of inputs: char-based strings, numerical arrays or vectors, or logical arrays/vectors. Any other input format will result in an error unless you typecast the input into `int8/uint8` format. A multi-dimensional numerical array is accepted, and the original input's type/dimension info is stored in the 2nd output "info". If one calls zmat with both the encoded data (in byte vector) and the "info" structure, zmat will first decode the binary data and then restore the original input's type and size.

The pre-compiled mex binaries for MATLAB are stored inside the subfolder named "private". Those precompiled for GNU Octave are stored in the subfolder named "octave", with one operating system per subfolder.

== 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 (that contains zmat.m and the "private" folder) to MATLAB's path list by using the following command:

addpath('/path/to/zmat');

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

mkdir ~/matlab/
nano ~/matlab/startup.m

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=zmat(input)
or
[output, info]=zmat(input, iscompress, method)
output=zmat(input, info)

A portable data compression/decompression toolbox for MATLAB/GNU Octave

author: Qianqian Fang <q.fang at neu.edu>

input:
input: a char, non-complex numeric or logical vector or array
iscompress: (optional) if iscompress is 1, zmat compresses/encodes the input,
if 0, it decompresses/decodes the input. Default value is 1.
if one defines iscompress as the info struct (2nd output of
zmat) during encoding, zmat will perform a
decoding/decompression operation and recover the original
input using the info stored in the info structure.
method: (optional) compression method, currently, zmat supports the below methods
'zlib': zlib/zip based data compression (default)
'gzip': gzip format
'lzip': lzip format
'lzma': lzma-alone format
'lz4': real-time lz4 compression
'lz4hc': lz4hc compression
'base64': encode or decode use base64 format

output:
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
'byte': the number of bytes per element in the input array
'method': a copy of the 3rd input indicating the encoding method
'status': the zlib function return value, including potential error codes (<0)

=== 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 ZMat so that everyone else can enjoy the improvement. For anyone who want to contribute, please download ZMat 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

https://github.com/fangq/zmat