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

# Top-level interface to libics

The functions below represent the recommended way of reading and writing ICS files using this library. You need to add `#include "libics.h"` to your source files.

Most functions return an `Ics_Error` value. For these functions we have listed the values this function could return. If the function completes its task successfully, it returns `IcsErr_Ok`. Some of the error codes (like `IcsErr_NotValidAction`) are returned when "asserts" fail. These shouldn't happen if you wrote your program correctly. See "Error codes returned by the library functions" for a detailed description of each error code.

This functions in this page are organized in the following categories, and sorted alphabetically:

- General library functions
- Reading image data
- Writing image data
- Image metadata functions
- History metadata functions
- Sensor metadata functions
- Testing functions

## General library functions

### IcsClose

Ics_Error IcsClose (ICS* ics);

Close the ICS file. The ics 'stream' is no longer valid after this. No files are actually written until this function is called.

errors: `IcsErr_Alloc`, `IcsErr_CompressionProblem`, `IcsErr_DecompressionProblem`, `IcsErr_FailWriteLine`, `IcsErr_FCloseIcs`, `IcsErr_FCloseIds`, `IcsErr_FCopyIds`, `IcsErr_FOpenIcs`, `IcsErr_FOpenIds`, `IcsErr_FTempMoveIcs`, `IcsErr_FWriteIcs`, `IcsErr_FWriteIds`, `IcsErr_MissingData`, `IcsErr_NoLayout`, `IcsErr_NotValidAction`, `IcsErr_TooManyChans`, `IcsErr_TooManyDims`, `IcsErr_UnknownCompression`, `IcsErr_UnknownDataType`.

### IcsGetErrorText

char const* IcsGetErrorText (Ics_Error error);

Returns a pointer to a textual representation of the error message in `error`.

### IcsGetLibVersion

char const* IcsGetLibVersion (void);

Returns a string that can be used to compare against `ICSLIB_VERSION` to check if the version of the library is the same as that of the headers.

### IcsLoadPreview

Ics_Error IcsLoadPreview (char const* filename, size_t planenumber, void** dest, size_t* xsize, size_t* ysize);

Read a 2D preview image out of an ICS file. `*dest` is set to a buffer that you should `free` yourself. `*xsize` and `*ysize` are set to the image size, and the buffer is filled with a 2D slice out of the image, converted to 8-bit unsigned integers. The slice is chosen with `planenumber` (see `IcsGetPreviewData`).

This function does currently not work when the data is compressed with `IcsCompr_compress`.

errors: `IcsErr_Alloc`, `IcsErr_BitsVsSizeConfl`, `IcsErr_BlockNotAllowed`, `IcsErr_BufferTooSmall`, `IcsErr_CompressionProblem`, `IcsErr_CorruptedStream`, `IcsErr_DecompressionProblem`, `IcsErr_EndOfStream`, `IcsErr_FailWriteLine`, `IcsErr_FCloseIcs`, `IcsErr_FCloseIds`, `IcsErr_FOpenIcs`, `IcsErr_FOpenIds`, `IcsErr_FReadIcs`, `IcsErr_FReadIds`, `IcsErr_FWriteIcs`, `IcsErr_FWriteIds`, `IcsErr_IllegalROI`, `IcsErr_LineOverflow`, `IcsErr_MissBits`, `IcsErr_MissCat`, `IcsErr_MissingData`, `IcsErr_MissLayoutSubCat`, `IcsErr_MissParamSubCat`, `IcsErr_MissRepresSubCat`, `IcsErr_MissSensorSubSubCat`, `IcsErr_NoLayout`, `IcsErr_NotIcsFile`, `IcsErr_NotValidAction`, `IcsErr_OutputNotFilled`, `IcsErr_TooManyChans`, `IcsErr_TooManyDims`, `IcsErr_UnknownCompression`, `IcsErr_UnknownDataType`.

### IcsOpen

Ics_Error IcsOpen (ICS** ics, char const* filename, char const* mode);

Open an ICS file for reading (`mode` = `"r"`) or writing (`mode` = `"w"`) or updating (`mode` = `"rw"`). When writing, append a `"2"` to `mode` to create an ICS version 2.0 file, or a `"1"` for ICS v.1.0 (the default version is 2.0). When reading or updating, append an `"f"` to `mode` to avoid the file extension to be forced to `".ics"`.

In the `"rw"` mode, it is possible to change all of the meta-data in the file, but not the actual data. To change the data, read in the image in the normal way, change it and then write it out.

The standard requires the `"C"` locale to be in effect when writing the ICS header, which means that numbers are written using a dot as a decimal separator, and no separator for thousands. If you happen to have an ICS file written using, e.g., the German locale, which would contain a number written as `5.755,34` instead of `5755.34`, you can read this file by setting the locale (in C this is done with `setlocale`) to German, then opening the file with an `"l"` appended to the `mode` string:

IcsOpen (&ics, `"germanfile.ics"`, `"rl"`)

Note that this option does not work when writing a file: all ICS files written by this library use the locale specified in the standard. Consequently, when updating such an ICS file, it will be converted to the `"C"` locale.

errors: `IcsErr_Alloc`, `IcsErr_FCloseIcs`, `IcsErr_FOpenIcs`, `IcsErr_FReadIcs`, `IcsErr_IllParameter`, `IcsErr_LineOverflow`, `IcsErr_MissBits`, `IcsErr_MissCat`, `IcsErr_MissLayoutSubCat`, `IcsErr_MissParamSubCat`, `IcsErr_MissRepresSubCat`, `IcsErr_MissSensorSubSubCat`, `IcsErr_NotIcsFile`, `IcsErr_TooManyChans`, `IcsErr_UnknownCompression`.

### IcsVersion

int IcsVersion (char const* filename, int forcename);

Returns 0 if the file specified by name is not an ICS file, or the version number if it is. When `forcename` is non-zero, the `".ics"` extension is not added.

## Reading image data

These functions are available on files opened for reading.

### IcsGetData

Ics_Error IcsGetData (ICS* ics, void* dest, size_t n);

Read the actual image data from an ICS file, as a single block. `n` is the size of the buffer `dest`, which must be the exact same size as reported by `IcsGetDataSize`

errors: `IcsErr_Alloc`, `IcsErr_BitsVsSizeConfl`, `IcsErr_CorruptedStream`, `IcsErr_DecompressionProblem`, `IcsErr_EndOfStream`, `IcsErr_FCloseIds`, `IcsErr_FOpenIds`, `IcsErr_FReadIds`, `IcsErr_MissingData`, `IcsErr_NotValidAction`, `IcsErr_UnknownCompression`.

### IcsGetDataBlock

Ics_Error IcsGetDataBlock (ICS* ics, void* dest, size_t n);

Read a portion of the actual image data from an ICS file. `n` is the size of the buffer `dest` in bytes.

When the data is compressed with `IcsCompr_compress`, this function can only be called once. That is, only one block of data, starting at the beginning, can be read from the file.

errors: `IcsErr_Alloc`, `IcsErr_BitsVsSizeConfl`, `IcsErr_BlockNotAllowed`, `IcsErr_CorruptedStream`, `IcsErr_DecompressionProblem`, `IcsErr_EndOfStream`, `IcsErr_FOpenIds`, `IcsErr_FReadIds`, `IcsErr_MissingData`, `IcsErr_NotValidAction`, `IcsErr_UnknownCompression`.

### IcsGetDataSize

size_t IcsGetDataSize (ICS const* ics);

Returns the size of the data block in bytes.

### IcsGetDataWithStrides

Ics_Error IcsGetDataWithStrides (ICS* ics, void const* src, size_t n, ptrdiff_t const* strides, int ndims);

Same as `IcsGetData`, except a pointer to an array `strides` is also given. `ndims` is the length of this array and should be equal to the dimensionality of the data as returned by `IcsGetLayout`

This function does currently not work when the data is compressed with `IcsCompr_compress`.

The parameter `n` is ignored.

errors: `IcsErr_Alloc`, `IcsErr_BitsVsSizeConfl`, `IcsErr_BlockNotAllowed`, `IcsErr_CorruptedStream`, `IcsErr_DecompressionProblem`, `IcsErr_EndOfStream`, `IcsErr_FCloseIds`, `IcsErr_FOpenIds`, `IcsErr_FReadIds`, `IcsErr_IllParameter`, `IcsErr_MissingData`, `IcsErr_UnknownCompression`.

### IcsGetImageSize

size_t IcsGetImageSize (ICS const* ics);

Returns the size of the image in imels.

### IcsGetImelSize

size_t IcsGetImelSize (ICS const* ics);

Returns the size of imels in bytes.

### IcsGetLayout

Ics_Error IcsGetLayout (ICS const* ics, Ics_DataType* dt, int* ndims, size_t* dims);

Retrieve the layout of an ICS image.

errors: `IcsErr_NotValidAction`.

### IcsGetPreviewData

Ics_Error IcsGetPreviewData (ICS* ics, void* dest, size_t n, size_t planenumber);

Read a plane of the actual image data from an ICS file, and convert it to 8-bit unsigned integers. `n` is the size of the buffer `dest` in bytes, and should be equal to `dims[0]*dims[1]`, as returned by `IcsGetLayout`. `planenumber` is the number of the 2D plane in the file. For example, to read the plane defined by `[:,:,m,n,k]`, set `planenumber` to `m + n*dims[2] + k*dims[2]*dims[3]`.

This function does currently not work when the data is compressed with `IcsCompr_compress`.

errors: `IcsErr_Alloc`, `IcsErr_BitsVsSizeConfl`, `IcsErr_BlockNotAllowed`, `IcsErr_BufferTooSmall`, `IcsErr_CorruptedStream`, `IcsErr_DecompressionProblem`, `IcsErr_EndOfStream`, `IcsErr_FCloseIds`, `IcsErr_FOpenIds`, `IcsErr_FReadIds`, `IcsErr_IllegalROI`, `IcsErr_MissingData`, `IcsErr_NotValidAction`, `IcsErr_OutputNotFilled`, `IcsErr_UnknownCompression`, `IcsErr_UnknownDataType`.

### IcsGetROIData

Ics_Error IcsGetROIData (ICS* ics, size_t const* offset, size_t const* size, size_t const* sampling, void* dest, size_t n);

Read a square region of the actual image from an ICS file. The region is defined by `offset` and `size`, both of which are integer arrays with `ndims` elements (as reported by `IcsGetLayout`). `sampling` allows you to sub-sample the image. It also is an array with `ndims` elements. If any of these parameters is set to `NULL`, the default is used (the offset is 0, the size is equal to the image size, and the sampling is 1 in each direction).

This function does currently not work when the data is compressed with `IcsCompr_compress`.

errors: `IcsErr_Alloc`, `IcsErr_BitsVsSizeConfl`, `IcsErr_BlockNotAllowed`, `IcsErr_BufferTooSmall`, `IcsErr_CorruptedStream`, `IcsErr_DecompressionProblem`, `IcsErr_EndOfStream`, `IcsErr_FCloseIds`, `IcsErr_FOpenIds`, `IcsErr_FReadIds`, `IcsErr_IllegalROI`, `IcsErr_MissingData`, `IcsErr_NotValidAction`, `IcsErr_OutputNotFilled`, `IcsErr_UnknownCompression`.

### IcsGetSignificantBits

Ics_Error IcsGetSignificantBits (ICS const* ics, size_t* nbits);

Get the number of significant bits.

errors: `IcsErr_NotValidAction`.

### IcsSkipDataBlock

Ics_Error IcsSkipDataBlock (ICS* ics, size_t n);

Skip a portion of the actual image data in an ICS file. `n` is the number of bytes to skip. Use this function together with `IcsGetDataBlock` to read in the portion of the image you are interested in. Note the function `IcsGetROIData`, which might simplifies this task.

This function does currently not work when the data is compressed with `IcsCompr_compress`.

errors: `IcsErr_Alloc`, `IcsErr_BlockNotAllowed`, `IcsErr_CorruptedStream`, `IcsErr_DecompressionProblem`, `IcsErr_EndOfStream`, `IcsErr_FOpenIds`, `IcsErr_FReadIds`, `IcsErr_MissingData`, `IcsErr_NotValidAction`, `IcsErr_UnknownCompression`.

## Writing image data

These functions are available on files opened for writing.

### IcsSetCompression

Ics_Error IcsSetCompression (ICS* ics, Ics_Compression compression, int level);

Set the compression method and compression parameter. Data is written uncompressed by default. If you try to set the compression to `IcsCompr_compress`, you'll get `IcsCompr_gzip` instead. See available methods and significance of the parameter at the `Ics_Compression`.

errors: `IcsErr_NotValidAction`.

### IcsSetData

Ics_Error IcsSetData (ICS* ics, void const* src, size_t n);

Set the image data for an ICS image. The pointer to this data must be accessible until `IcsClose` has been called. If the size `n` of the data is not equal to what is expected according to the image sizes set previously by `IcsSetLayout`, a value of `IcsErr_FSizeConflict` is returned.

errors: `IcsErr_DuplicateData`, `IcsErr_FSizeConflict`, `IcsErr_NoLayout`, `IcsErr_NotValidAction`.

### IcsSetDataWithStrides

Ics_Error IcsSetDataWithStrides (ICS* ics, void const* src, size_t n, ptrdiff_t const* strides, int ndims);

Same as `IcsSetData`, except a pointer to an array `strides` is also given. This array must be accesible until `IcsClose` has been called. `ndims` is the length of this array and should be equal to the dimensionality of the data as specified earlier through `IcsSetLayout`

The parameter `n` is ignored.

errors: `IcsErr_DuplicateData`, `IcsErr_FSizeConflict`, `IcsErr_IllParameter`, `IcsErr_NoLayout`, `IcsErr_NotValidAction`.

### IcsSetLayout

Ics_Error IcsSetLayout (ICS* ics, Ics_DataType dt, int ndims, size_t const* dims);

Set the layout for an ICS image.

errors: `IcsErr_NotValidAction`, `IcsErr_TooManyDims`.

### IcsSetSignificantBits

Ics_Error IcsSetSignificantBits (ICS* ics, size_t nbits);

Set the number of significant bits.

errors: `IcsErr_NoLayout`, `IcsErr_NotValidAction`.

### IcsSetSource

Ics_Error IcsSetSource (ICS* ics, char const* fname, size_t offset);

Set the image source parameter for an ICS version 2.0 file.

errors: `IcsErr_DuplicateData`, `IcsErr_NotValidAction`.

## Image metadata functions

### IcsGetCoordinateSystem

Ics_Error IcsGetCoordinateSystem (ICS const* ics, char* coord);

Get the coordinate system used in the positioning of the pixels. Related to `IcsGetPosition`. The default is `"video"`.

errors: `IcsErr_NotValidAction`.

### IcsGetImelUnits

Ics_Error IcsGetImelUnits (ICS const* ics, double* origin, double* scale, char* units);

Set the position of the pixel values: the offset and scaling, and the units in which to measure. If you are not interested in one of the parameters, set the pointer to `NULL`.

errors: `IcsErr_NotValidAction`.

### IcsGetImelUnitsF

Ics_Error IcsGetImelUnitsF (ICS const* ics, double* origin, double* scale, const char** units);

Same as `IcsGetImelUnits`, but doesn't copy the units string. Output pointer `units` is set to the internal buffer, which will be valid until `IcsClose` is called.

errors: `IcsErr_NotValidAction`.

### IcsGetOrder

Ics_Error IcsGetOrder (ICS const* ics, int dimension, char* order, char* label);

Get the ordering of the dimensions in the image. The ordering is defined by names and labels for each dimension. The defaults are x, y, z, t (time) and p (probe). Dimensions start at 0.

errors: `IcsErr_NotValidAction`.

### IcsGetOrderF

Ics_Error IcsGetOrderF (ICS const* ics, int dimension, const char** order, const char** label);

Same as `IcsGetOrder`, but doesn't copy the order or label strings. Output pointers `order` and `label` are set to the internal buffers, which will be valid until `IcsClose` is called.

errors: `IcsErr_NotValidAction`.

### IcsGetPosition

Ics_Error IcsGetPosition (ICS const* ics, int dimension, double* origin, double* scale, char* units);

Get the position of the image in the real world: the origin of the first pixel, the distances between pixels and the units in which to measure. If you are not interested in one of the parameters, set the pointer to `NULL`. Dimensions start at 0.

errors: `IcsErr_NotValidAction`.

### IcsGetPositionF

Ics_Error IcsGetPositionF (ICS const* ics, int dimension, double* origin, double* scale, const char** units);

Same as `IcsGetPosition`, but doesn't copy the units string. Output pointer `units` is set to the internal buffer, which will be valid until `IcsClose` is called.

errors: `IcsErr_NotValidAction`.

### IcsGetScilType

Ics_Error IcsGetScilType (ICS const* ics, char* sciltype);

Get the string for the SCIL_TYPE parameter. This string is used only by SCIL_Image.

errors: `IcsErr_NotValidAction`.

### IcsGuessScilType

Ics_Error IcsGuessScilType (ICS* ics);

As `IcsSetScilType`, sets the string for the SCIL_TYPE parameter. This function creates a string according to the values previously specified using `IcsSetLayout`. It can create any of these strings: `"g2d"`, `"g3d"`, `"f2d"`, `"f3d"`, `"c2d"` and `"c3d"`. This string is used only by SCIL_Image, and is required if you want to read the image using SCIL_Image.

errors: `IcsErr_NoScilType`, `IcsErr_NotValidAction`.

### IcsSetCoordinateSystem

Ics_Error IcsSetCoordinateSystem (ICS* ics, char const* coord);

Set the coordinate system used in the positioning of the pixels. Related to `IcsSetPosition`. The default is `"video"`.

errors: `IcsErr_NotValidAction`.

### IcsSetImelUnits

Ics_Error IcsSetImelUnits (ICS* ics, double origin, double scale, char const* units);

Set the position of the pixel values: the offset and scaling, and the units in which to measure. If units is `NULL` or empty, it is set to the default value of `"relative"`.

errors: `IcsErr_NotValidAction`.

### IcsSetPosition

Ics_Error IcsSetPosition (ICS* ics, int dimension, double origin, double scale, char const* units);

Set the position of the image in the real world: the origin of the first pixel, the distances between pixels and the units in which to measure. If `units` is `NULL` or empty, it is set to the default value of `"undefined"`. Dimensions start at 0.

errors: `IcsErr_NotValidAction`.

### IcsSetOrder

Ics_Error IcsSetOrder (ICS* ics, int dimension, char const* order, char const* label);

Set the ordering of the dimensions in the image. The ordering is defined by providing names and labels for each dimension. The defaults are x, y, z, t (time) and p (probe). Dimensions start at 0.

errors: `IcsErr_NotValidAction`.

### IcsSetScilType

Ics_Error IcsSetScilType (ICS* ics, char const* sciltype);

Set the string for the SCIL_TYPE parameter. This string is used only by SCIL_Image, and is required if you want to read the image using SCIL_Image.

errors: `IcsErr_NotValidAction`.

## History metadata functions

The functions below give access to the history lines. The structure where these are stored is hidden from the user, making these functions the only method of access. A history line in an ICS file starts with the token "history", then has an optional key token, and then any string. These three parts are separated by tab characters, but the string can contain tab characters also, effectively allowing the user even more subdivisions in the hierarchy. The history lines can contain any information the user wishes to put into the file.

Some functions below use `Ics_HistoryIterator`, a struct initialized by `IcsNewHistoryIterator`. It is always set to point to the next available string, and also contains the index to the previously retrieved string. It is possible to set up an iterator to fetch each of the history strings in turn, or to fetch only those that have a particular key.

### IcsAddHistoryString

Ics_Error IcsAddHistoryString (ICS* ics, char const* key, char const* value);

Add history lines to the ICS file. `key` can be `NULL` or `""`, but value must point to a string. Neither strings can contain newline characters, and `key` cannot contain tab characters either.

`IcsAddHistory` is defined as an alias for this function, for backwards compatability.

errors: `IcsErr_Alloc`, `IcsErr_IllParameter`, `IcsErr_LineOverflow`, `IcsErr_NotValidAction`.

### IcsDeleteHistory

Ics_Error IcsDeleteHistory (ICS* ics, char* key);

Delete all history lines with key `key`. If `key` is `NULL` or `""`, it deletes all the history lines.

errors: none.

### IcsDeleteHistoryStringI

Ics_Error IcsDeleteHistoryStringI (ICS* ics, Ics_HistoryIterator* it);

Delete the last history lines retrieved through `it`.

errors: none.

### IcsGetHistoryKeyValue

Ics_Error IcsGetHistoryKeyValue (ICS* ics, char* key, char* value, Ics_HistoryWhich which);

Get the history lines from the ICS file. `key` must have at least `ICS_STRLEN_TOKEN` characters allocated, and `value` at least `ICS_LINE_LENGTH`. `key` can be `NULL`, in which case the key will be discarded. The `which` parameter must be set to `IcsWhich_First` to read the first string in the buffer, and to `IcsWhich_Next` in subsequent calls to get the other strings.

`IcsGetHistoryKeyValue` shares and internal iterator with `IcsGetHistoryString`, and calls `IcsGetHistoryKeyValueI`.

errors: `IcsErr_EndOfHistory`, `IcsErr_NotValidAction`.

### IcsGetHistoryKeyValueI

Ics_Error IcsGetHistoryKeyValueI (ICS* ics, Ics_HistoryIterator* it, char* key, char* value);

Get the history lines from the ICS file. `key` must have at least `ICS_STRLEN_TOKEN` characters allocated, and `value` at least `ICS_LINE_LENGTH`. `key` can be `NULL`, in which case the key will be discarded. The `it` parameter must point to a `Ics_HistoryIterator` structure initialized by `IcsNewHistoryIterator`.

errors: `IcsErr_EndOfHistory`, `IcsErr_NotValidAction`.

### IcsGetHistoryKeyValueIF

Ics_Error IcsGetHistoryKeyValueIF (ICS* ics, Ics_HistoryIterator* it, char* key, const char** value);

Same as `IcsGetHistoryKeyValueI`, but doesn't copy the value string. Output pointer `value` is set to the internal buffer, which will be valid until `IcsClose` or `IcsFreeHistory` are called.

errors: `IcsErr_EndOfHistory`, `IcsErr_NotValidAction`.

### IcsGetHistoryString

Ics_Error IcsGetHistoryString (ICS* ics, char* string, Ics_HistoryWhich which);

Get the history lines from the ICS file. `string` must have at least `ICS_LINE_LENGTH` characters allocated. The `which` parameter must be set to `IcsWhich_First` to read the first string in the buffer, and to `IcsWhich_Next` in subsequent calls to get the other strings.

`IcsGetHistoryString` shares and internal iterator with `IcsGetHistoryKeyValue`, and calls `IcsGetHistoryStringI`.

errors: `IcsErr_EndOfHistory`, `IcsErr_NotValidAction`.

### IcsGetHistoryStringI

Ics_Error IcsGetHistoryStringI (ICS* ics, Ics_HistoryIterator* it, char* string);

Get the history lines from the ICS file. `string` must have at least `ICS_LINE_LENGTH` characters allocated. The `it` parameter must point to a `Ics_HistoryIterator` structure initialized by `IcsNewHistoryIterator`.

errors: `IcsErr_EndOfHistory`, `IcsErr_NotValidAction`.

### IcsGetHistoryStringIF

Ics_Error IcsGetHistoryStringIF (ICS* ics, Ics_HistoryIterator* it, const char** string);

Same as `IcsGetHistoryKeyValueI`, but doesn't copy the string. Output pointer `string` is set to the internal buffer, which will be valid until `IcsClose` or `IcsFreeHistory` are called.

errors: `IcsErr_EndOfHistory`, `IcsErr_NotValidAction`.

### IcsGetNumHistoryStrings

Ics_Error IcsGetNumHistoryStrings (ICS* ics, int* num);

Get the number of history lines from the ICS file. `num` is the number of times you can call `IcsGetHistoryString`.

errors: `IcsErr_NotValidAction`.

### IcsNewHistoryIterator

Ics_Error IcsNewHistoryIterator (ICS* ics, Ics_HistoryIterator* it, char* key);

Initializes a history iterator. `key` can be `NULL`.

errors: `IcsErr_EndOfHistory`, `IcsErr_NotValidAction`.

### IcsReplaceHistoryStringI

Ics_Error IcsReplaceHistoryStringI (ICS* ics, Ics_HistoryIterator* it, char const* key, char const* value);

Replace the last history lines retrieved through `it`. `key` can be `NULL` or `""`, but value must point to a string. Neither strings can contain newline characters, and `key` cannot contain tab characters either.

errors: `IcsErr_Alloc`, `IcsErr_IllParameter`, `IcsErr_LineOverflow`, `IcsErr_NotValidAction`.

## Sensor metadata functions

The functions below give access to the sensor parameters. For each parameter both a Get and a Set function are provided. The Set functions all perform error checking and insist that the ICS structure is in writing or updating mode. Please note that `IcsEnableWriteSensor` must be called to enable writing the sensor parameters to file. To use these functions you need to add `#include "libics_sensor.h"` to your source files.

### IcsEnableWriteSensor

Ics_Error IcsEnableWriteSensor (ICS* ics, int enable);

Enable (or disable) writing the sensor parameters to disk. The second parameter must be non-zero for enable, or zero for disable.

### IcsGetSensorChannels

int IcsGetSensorChannels (ICS const* ics);

Return the number of sensor channels.

### IcsGetSensorEmissionWavelength

double IcsGetSensorEmissionWavelength (ICS const* ics, int channel);

Return the emission wavelength for a given channel.

### IcsGetSensorExcitationWavelength

double IcsGetSensorExcitationWavelength (ICS const* ics, int channel);

Return the excitation wavelength for a given channel.

### IcsGetSensorLensRI

double IcsGetSensorLensRI (ICS const* ics);

Return the design medium refractive index.

### IcsGetSensorMediumRI

double IcsGetSensorMediumRI (ICS const* ics);

Return the embedding medium refractive index.

### IcsGetSensorModel

char const* IcsGetSensorModel (ICS const* ics);

Return a pointer to the sensor model string.

### IcsGetSensorNumAperture

double IcsGetSensorNumAperture (ICS const* ics);

Return the sensor numerical apperture.

### IcsGetSensorPhotonCount

int IcsGetSensorPhotonCount (ICS const* ics, int channel);

Return the excitation photon count for a given channel.

### IcsGetSensorPinholeRadius

double IcsGetSensorPinholeRadius (ICS const* ics, int channel);

Return the pinhole radius for a given channel.

### IcsGetSensorPinholeSpacing

double IcsGetSensorPinholeSpacing (ICS const* ics);

Return the Nipkow Disk pinhole spacing.

### IcsGetSensorSTEDDepletionMode

char const* IcsGetSensorSTEDDepletionMode (ICS const* ics, int channel);

Return a pointer to the STED depletion mode string for a given channel.

### IcsGetSensorSTEDImmFraction

double IcsGetSensorSTEDImmFraction (ICS const* ics, int channel);

Return the STED immunity fraction for a given channel.

### IcsGetSensorSTEDLambda

double IcsGetSensorSTEDLambda (ICS const* ics, int channel);

Return the STED wavelength for a given channel.

### IcsGetSensorSTEDPPMode

char const* IcsGetSensorSTEDPPMode (ICS const* ics, int channel);

Return a pointer to the STED phase plate mode string for a given channel.

### IcsGetSensorSTEDSatFactor

double IcsGetSensorSTEDSatFactor (ICS const* ics, int channel);

Return the STED saturation factor for a given channel.

### IcsGetSensorSTEDVPPM

double IcsGetSensorSTEDVPPM (ICS const* ics, int channel);

Return the STED vortex to phase plate mix for a given channel.

### IcsGetSensorDetectorPPU

double IcsGetSensorDetectorPPU (ICS const* ics, int channel);

Return photons per unit for a given channel.

### IcsGetSensorDetectorBaseline

double IcsGetSensorDetectorBaseline (ICS const* ics, int channel);

Return the baseline for a given channel.

### IcsGetSensorDetectorLineAvgCnt

double IcsGetSensorDetectorLineAvgCnt (ICS const* ics, int channel);

Return the amount of line averaging for a given channel.

### IcsGetSensorType

char const* IcsGetSensorType (ICS const* ics, int channel);

Return a pointer to the sensor type string for a given channel.

### IcsSetSensorChannels

Ics_Error IcsSetSensorChannels (ICS* ics, int channels);

Set the number of sensor channels. This number may not exceed `ICS_MAX_LAMBDA`.

### IcsSetSensorEmissionWavelength

Ics_Error IcsSetSensorEmissionWavelength (ICS* ics, int channel, double wl);

Set the emission wavelength for a given channel. The channel index must be less than the number of sensor channels.

### IcsSetSensorExcitationWavelength

Ics_Error IcsSetSensorExcitationWavelength (ICS* ics, int channel, double wl);

Set the excitation wavelength for a given channel. The channel index must be less than the number of sensor channels.

### IcsSetSensorLensRI

Ics_Error IcsSetSensorLensRI (ICS* ics, double ri);

Set the design medium refractive index.

### IcsSetSensorMediumRI

Ics_Error IcsSetSensorMediumRI (ICS* ics, double ri);

Set the embedding medium refractive index.

### IcsSetSensorModel

Ics_Error IcsSetSensorModel (ICS* ics, char const* sensor_model);

Set the sensor model string.

### IcsSetSensorNumAperture

Ics_Error IcsSetSensorNumAperture (ICS* ics, double na);

Set the sensor numerical apperture.

### IcsSetSensorPhotonCount

Ics_Error IcsSetSensorPhotonCount (ICS* ics, int channel, int cnt);

Set the excitation photon count for a given channel. The channel index must be less than the number of sensor channels.

### IcsSetSensorPinholeRadius

Ics_Error IcsSetSensorPinholeRadius (ICS* ics, int channel, double radius);

Set the pinhole radius for a given channel. The channel index must be less than the number of sensor channels.

### IcsSetSensorPinholeSpacing

Ics_Error IcsSetSensorPinholeSpacing (ICS* ics, double spacing);

Set the Nipkow Disk pinhole spacing.

### IcsSetSensorSTEDDepletionMode

Ics_Error IcsSetSensorSTEDDepletionMode (ICS* ics, int channel, char const* depletion_mode);

Set the STED depletion mode for a given channel.

### IcsSetSensorSTEDImmFraction

Ics_Error IcsSetSensorSTEDImmFraction (ICS* ics, int channel, double fraction);

Set the STED immunity fraction for a given channel.

### IcsSetSensorSTEDLambda

Ics_Error IcsSetSensorSTEDLambda (ICS* ics, int channel, double lambda);

Set the STED wavelength for a given channel.

### IcsSetSensorSTEDPPMode

Ics_Error IcsSetSensorSTEDPPMode (ICS* ics, int channel, char const* pp_mode);

Set the STED phase plate mode for a given channel.

### IcsSetSensorSTEDSatFactor

Ics_Error IcsSetSensorSTEDSatFactor (ICS* ics, int channel, double factor);

Set the STED saturation factor for a given channel.

### IcsSetSensorSTEDVPPM

Ics_Error IcsSetSensorSTEDVPPM (ICS* ics, int channel, double vppm);

Set the STED vortex to phase plate mix for a given channel.

### IcsSetSensorDetectorPPU

Ics_Error IcsSetSensorDetectorPPU (ICS* ics, int channel, double ppu);

Set the photons per unit for a given channel.

### IcsSetSensorDetectorBaseline

Ics_Error IcsSetSensorDetectorBaseline (ICS* ics, int channel, double baseline);

Set the baseline for a given channel.

### IcsSetSensorDetectorLineAvgCnt

Ics_Error IcsSetSensorDetectorLineAvgCnt (ICS* ics, int channel, double lineAvgCnt);

Set the amount of line averaging for a given channel.

### IcsSetSensorType

Ics_Error IcsSetSensorType (ICS* ics, int channel, char const* sensor_type);

Set the sensor type string for a given channel.

## Testing functions

The functions below allow the user to see what is happening inside libics. You need to add `#include "libics_test.h"` to your source files.

### IcsPrintError

void IcsPrintError (Ics_Error error);

Prints a textual representation of the error message in `error` to `stdout`. Uses `IcsGetErrorText` and `printf`.

### IcsPrintIcs

void IcsPrintIcs (ICS const* ics);

Prints the contents of the `ICS` structure in `ics` to `stdout`. Uses only `printf`.