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 */ ;