What is this?
=============

This is an Matlab/Octave library implementing an arithmetic coder.  It
is based on a modified version of the C implementation in ac.c.

How do I install it?
====================

Simply put all the files/directories in the archive in some directory
searched by Matlab/Octave.  The MEX file will be automatically
installed the first time you use the library.

What do I find here?
====================

From a user-lever point of view, the library provides the following
functions/classes (see the online help for more details)

Very High-level functions
-------------------------

Those functions allow the user to save and load integer matrices
without explicitly handling encoder/decoder.

  * Function save_arith_compressed(x, filename, [mode])

      Save the INTEGER matrix X, compressed with the arithmetic coder,
      to file FILENAME.  Matrix X can be reloaded with function
      load_arith_compressed.  File FILENAME is opened with mode MODE
      which must be a valid "fopen mode".

  * Function load_arith_compressed(filename, [skip])

      Load from FILENAME a matrix saved with save_arith_compressed.
      If the second parameter is given, skip the first SKIP bytes of
      FILENAME.

High-level functions
--------------------

These functions allow the user to create/use/destroy coders and
decoders. The I/O can be done to/from file or to/from memory buffers.  

Usage example for file I/O:

    %
    % Encode 4096 integers and write the result to file /tmp/data
    %
    N = 4096; data = floor(rand(1,N)*1024);

    enc = new_arithmetic_encoder('/tmp/data', 1024);
    arith_encode(enc, data);
    arith_close(enc);

    %
    % Decode 
    %
    dec = new_arithmetic_decoder('/tmp/data', 1024);
    data_decod = arith_decode(dec, N);
    arith_close(dec);

Usage example for memory I/O:

    %
    % Encode 4096 integers and write the result to memory buffer
    %
    N = 4096; data = floor(rand(1,N)*1024);

    enc = new_arithmetic_encoder(1024);
    arith_encode(enc, data);
    bitstream_buf = arith_close(enc);

    %
    % Decode 
    %
    dec = new_arithmetic_decoder(bitstream_buf);
    data_decod = arith_decode(dec, N);
    arith_close(dec);


    * Function enc=new_arithmetic_encoder([filename,] alphabet_size, [mode])
 
       Create a new arithmetic encoder for an alphabet of size
       ALPHABET_SIZE.  ALPHABET_SIZE must be less or equal of 8191 =
       2^13-1. The alphabet elements are integers between 0 and
       ALPHABET_SIZE-1.  The bitstream will be written to file
       FILENAME opened with mode MODE which can assume values 'a' (for
       append) or 'w' (for rewrite).  By default MODE='w'.  If
       FILENAME is omitted the bitstream will be written to a memory
       buffer which will be returned by the function arith_close().

       The function returns a handler for the newly created encoder. 

     * Function dec = new_arithmetic_decoder(filename, alphabet_size, [skip])
                dec = new_arithmetic_decoder(bindata)
                dec = new_arithmetic_decoder(buffer, alphabet_size)

       Create a new arithmetic decoder for an alphabet of size
       ALPHABET_SIZE.  The alphabet elements are integers between
       0 and ALPHABET_SIZE-1.  The bitstream will be read from
       file FILENAME. If the third parameter is given, skip the
       first SKIP bytes of FILENAME.

       If new_arithmetic_decoder() is called with only one parameter,
       MEMORY_BUF must be the value returned by arith_close() when
       closing an encoder with no FILENAME associated.


     * Function arith_encode(enc, x)

       Encode the data in matrix X.  The data in X are read
       column-wise (as usual in Octave/Matlab).  No information about the
       size of X is stored.

       NOTE: ---> Each entry in X   MUST BE   a NON-NEGATIVE INTEGER
             ---> less than AB_SIZE, where AB_SIZE is the alphabet 
             ---> size (second parameter of NEW_ARITHMETIC_ENCODER)

     * Function N = arith_info(enc)

       Return the number of bits used so far by the encoder.


     * Function y = arith_decode(dec, size)

       Decode PROD(SIZE) values from the file and return them in Y
       as matrix with dimensions SIZE.  For example,

             Y = arith_decode(dec, [3, 4])

       return a 3x4 matrix.  If SIZE is a scalar, return a column
       vector with SIZE rows.


     * Function arith_close(dec)
                arith_close(enc)
		bindata = arith_close(enc)
                arith_close('all')

       Stop encoding/decoding. Close the output/input file and destroy
       the encoder/decoder. If  FILENAME was omitted from the call to 
       new_arithmetic_encoder(), returns the final bitstream in an
       Matlab/Octave struct.


Low-level stuff
---------------

The following are very low-level functions and usually they are not of
much interest to the end user.  They are briefly documented for the
sake of completeness.  Low level functions have at least one "double
underscore" ('__') in their name.

  * Function arith__coder__gateway(what, varargin)

       Gateway to the MEX function.  This function check if the MEX
       file is present and if it is not, compile and install it.
       Successively, call the MEX function with a copy of WHAT and
       VARARGIN.   See the .m file for details.

  * Function arith__check_handler(handler, encod_flag, valid)

       Check that HANDLER is a valid handler.

  * Function arith__cleanup()   

       Called at exit time (in the Octave implementation) to perform
       cleanups 

  * File arith_coder_mex.c

       MEX interface to the arithmetic coder.  This is the file called
       by function arith_coder.

  * Files ac.c, ac.h

       C implementation of the arithmetic coder.  This is a modified
       version of the C implementation found (on May 2005) at 

               http://www.cipr.rpi.edu/~wheeler/ac/