libics: Top-Level Interface

libics v.1.6.6 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

const char *IcsGetErrorText (Ics_Error error);

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

### IcsGetLibVersion

const char *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 (const char *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, const char *filename, const char *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 (const char *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 (const ICS *ics);

Returns the size of the data block in bytes.

### IcsGetDataWithStrides

Ics_Error IcsGetDataWithStrides (ICS *ics, const void *src, size_t n, const ptrdiff_t *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 (const ICS *ics);

Returns the size of the image in imels.

### IcsGetImelSize

size_t IcsGetImelSize (const ICS *ics);

Returns the size of imels in bytes.

### IcsGetLayout

Ics_Error IcsGetLayout (const ICS *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 (const ICS *ics, const size_t *offset, const size_t *size, const size_t *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 (const ICS *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, const void *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, const void *src, size_t n, const ptrdiff_t *strides, int ndims);

Same as `IcsSetData`, except a pointer to an array `strides` is also given. This array must be accessible 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, const size_t *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, const char *fname, size_t offset);

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

errors: `IcsErr_DuplicateData`, `IcsErr_NotValidAction`.

### IcsSetByteOrder

Ics_Error IcsSetByteOrder (ICS *ics, Ics_ByteOrder *order);

Set the image source byte order for an ICS version 2.0 file. Only valid if writing, and only valid after calling `IcsSetSource`. If the data type is changed after this call, the byte order information written to file might not be correct.

errors: `IcsErr_NotValidAction`, `IcsErr_IllParameter`.

## Image metadata functions

### IcsGetCoordinateSystem

Ics_Error IcsGetCoordinateSystem (const ICS *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 (const ICS *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 (const ICS *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 (const ICS *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 (const ICS *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 (const ICS *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 (const ICS *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, const char *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, const char *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, const char *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, const char *order, const char *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, const char *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, const char *key, const char *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 compatibility.

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, const char *key, const char *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 most parameters dedicated Set and Get functions are provided. However, some parameters can only be accessed using generic Set and Get functions, along with a `token` specifying the parameter. 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 (const ICS *ics);

Return the number of sensor channels.

### IcsGetSensorDetectors

int IcsGetSensorDetectors (const ICS *ics);

Return the number of sensor detectors.

### IcsGetSensorParameter

Ics_Error IcsGetSensorParameter (const ICS *ics, Ics_SensorParameter parameter, int channel, double *value, Ics_SensorState *state);

Generic get function for parameters represented by doubles.

errors: `IcsErr_NotValidAction`.

### IcsGetSensorParameterVector

Ics_Error IcsGetSensorParameterVector (const ICS *ics, Ics_SensorParameter parameter, int channel, const double **values, Ics_SensorState *state);

Generic get function for parameters represented by a vector of doubles. The double **values represents a pointer to an array of doubles, which is set by the function.

errors: `IcsErr_NotValidAction`.

### IcsGetSensorParameterMatrix

Ics_Error IcsGetSensorParameterMatrix (const ICS *ics, Ics_SensorParameter parameter, int channel, const double **values, Ics_SensorState *state);

Generic get function for parameters represented by a matrix of doubles. The double **values represents a pointer to a flattened array of doubles, which is set by the function.

errors: `IcsErr_NotValidAction`.

### IcsGetSensorParameterInt

Ics_Error IcsGetSensorParameterInt (const ICS *ics, Ics_SensorParameter parameter, int channel, int *value, Ics_SensorState *state);

Generic get function for parameters represented by ints.

errors: `IcsErr_NotValidAction`.

### IcsGetSensorParameterString

Ics_Error IcsGetSensorParameterString (const ICS *ics, Ics_SensorParameter parameter, int channel, const char **value, Ics_SensorState *state);

Generic get function for parameters represented by a string. The char **value represents a pointer to a char array, which is set by the function.

errors: `IcsErr_NotValidAction`.

### IcsGetSensorEmissionWavelength

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

Return the emission wavelength for a given channel.

### IcsGetSensorExcitationWavelength

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

Return the excitation wavelength for a given channel.

### IcsGetSensorLensRI

double IcsGetSensorLensRI (const ICS *ics);

Return the design medium refractive index.

### IcsGetSensorMediumRI

double IcsGetSensorMediumRI (const ICS *ics);

Return the embedding medium refractive index.

### IcsGetSensorModel

const char* IcsGetSensorModel (const ICS *ics);

Return a pointer to the sensor model string.

### IcsGetSensorNumAperture

double IcsGetSensorNumAperture (const ICS *ics);

Return the sensor numerical apperture.

### IcsGetSensorPhotonCount

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

Return the excitation photon count for a given channel.

### IcsGetSensorPinholeRadius

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

Return the pinhole radius for a given channel.

### IcsGetSensorPinholeSpacing

double IcsGetSensorPinholeSpacing (const ICS *ics);

Return the Nipkow Disk pinhole spacing.

### IcsGetSensorSTEDDepletionMode

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

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

### IcsGetSensorSTEDImmFraction

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

Return the STED immunity fraction for a given channel.

### IcsGetSensorSTEDLambda

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

Return the STED wavelength for a given channel.

### IcsGetSensorSTEDPPMode

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

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

### IcsGetSensorSTEDSatFactor

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

Return the STED saturation factor for a given channel.

### IcsGetSensorSTEDVPPM

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

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

### IcsGetSensorDetectorPPU

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

Return photons per unit for a given channel.

### IcsGetSensorDetectorBaseline

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

Return the baseline for a given channel.

### IcsGetSensorDetectorLineAvgCnt

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

Return the amount of line averaging for a given channel.

### IcsGetSensorType

const char* IcsGetSensorType (const ICS *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`.

### IcsSetSensorDetectors

Ics_Error IcsSetSensorDetectors (ICS* ics, int detectors);

Set the number of sensor detectors. This number may not exceed `ICS_MAX_DETECT`.

### IcsSetSensorParameter

Ics_Error IcsSetSensorParameter (ICS *ics, Ics_SensorParameter parameter, int channel, double value, Ics_SensorState state);

Generic set function for parameters represented by doubles. Note that you must also set the state of the parameter.

errors: `IcsErr_NotValidAction`.

### IcsSetSensorParameterVector

Ics_Error IcsSetSensorParameterVector (ICS *ics, Ics_SensorParameter parameter, int channel, int nValues, double *values, Ics_SensorState state);

Generic set function for parameters represented by a vector of doubles. Double *values represents an array of doubles and nValues specifies the size of the vector. Note that you must also set the state of the parameter.

errors: `IcsErr_NotValidAction`.

### IcsSetSensorParameterMatrix

Ics_Error IcsSetSensorParameterMatrix (ICS *ics, Ics_SensorParameter parameter, int channel, int nValues, int mValues, double *values, Ics_SensorState state);

Generic set function for parameters represented by a matrix of doubles. Double *values represents a flattened array of doubles and (nValues, mValues) specifies the size of the matrix. Note that you must also set the state of the parameter.

errors: `IcsErr_NotValidAction`.

### IcsSetSensorParameterInt

Ics_Error IcsSetSensorParameterInt (ICS *ics, Ics_SensorParameter parameter, int channel, int value, Ics_SensorState state);

Generic set function for parameters represented by ints. Note that you must also set the state of the parameter.

errors: `IcsErr_NotValidAction`.

### IcsSetSensorParameterString

Ics_Error IcsSetSensorParameterString (ICS *ics, Ics_SensorParameter parameter, int channel, const char *value, Ics_SensorState state);

Generic set function for parameters represented by a string. Note that you must also set the state of the parameter.

errors: `IcsErr_NotValidAction`.

### 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, const char* sensor_model);

Set the sensor model string.

### IcsSetSensorNumAperture

Ics_Error IcsSetSensorNumAperture (ICS* ics, double na);

Set the sensor numerical aperture.

### 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, const char* 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, const char* 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, const char* 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`.