libics: Usage

libics v.1.6.6 Online Documentation. ©2000-2010 by Cris Luengo and others.

# Usage of libics

The recommended way of using this library is through the top-level interface. It is also possible to use some of the low-level functions, together with the `Ics_Header` structure, to create ICS files. This is however not recommended since both are subject to change.

Below are two sample functions that use the basic functionality in this library. The first one reads an ICS file, the second one writes one. These examples use only the top-level interface

For both reading and writing, the `ICS` data structure serves as a kind of `FILE` structure. It contains all the information on the open file. All library functions have it as their first parameter. In the low-level interface functions, this structure is called `Ics_Header`, which is just an alias.

## Reading ICS

This sample code shows how to use the top-level interface to read an ICS file. First, `IcsOpen` is called to open the file. Then some functions can be used to gain knowledge of the image stored in the file. This can be used to allocate memory for the image data. Finally, `IcsGetData` is used to read in the data. Note that this library allows to read only parts of the image data (see `IcsGetROIData`). To clean up, `IcsClose` must be called, it releases some memory allocated by the call to `IcsOpen`.

    #include "libics.h"

    ICS* ip;
    Ics_DataType dt;
    int ndims;
    size_t dims[ICS_MAXDIM];
    size_t bufsize;
    void* buf;
    Ics_Error retval;

    retval = IcsOpen (&ip, "file.ics", "r");
    if (retval != IcsErr_Ok)
       /* Flag error condition */ ;

    IcsGetLayout (ip, &dt, &ndims, dims);
    bufsize = IcsGetDataSize (ip);
    buf = malloc (bufsize);
    if (buf == NULL)
       /* Flag error condition*/ ;
    retval = IcsGetData (ip, buf, bufsize);
    if (retval != IcsErr_Ok)
       /* Flag error condition */ ;

    /*
     * There are some other functions available to get
     * more info on the image in the .ics file.
     */

    retval = IcsClose (ip);
    if (retval != IcsErr_Ok)
       /* Flag error condition*/ ;

## Writing ICS

This sample code shows how to use the top-level interface to write an ICS file. First, `IcsOpen` is called to open the file. What this does is allocate the `ICS` structure. Then a series of functions can be used to specify information on the image to be written. Finally, `IcsClose` is called to write the data to a file. This call also cleans up allocated memory.

    #include "libics.h"

    ICS* ip;
    Ics_DataType dt = Ics_uint8;
    int ndims = 3;
    size_t dims[3] = {256, 256, 256};
    size_t bufsize = 256*256*256;
    void* buf = image_data;
    Ics_Error retval;

    retval = IcsOpen (&ip, "file.ics", "w2");
    if (retval != IcsErr_Ok)
       /* Flag error condition */ ;

    IcsSetLayout (ip, dt, ndims, dims);
    IcsSetData (ip, buf, bufsize);
    IcsSetCompression (ip, IcsCompr_gzip, 6);
    IcsAddHistoryString (ip, "author", "M.Y. Name");

    /*
     * There are some other functions available to set
     * image parameters in the .ics file.
     */

    retval = IcsClose (ip);
    if (retval != IcsErr_Ok)
       /* Flag error condition */ ;