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

# ICS structure and Ics_Header structure

The `ICS` data structure, which is the same as the `Ics_Header` data structure, contains the fields described below.

All arrays are already allocated (static arrays). This determines the maximum sizes allowed. If larger sizes are required, you must change some values defined in "`libics.h`" and re-compile the library.

Warning: The `Ics_Header` structure is likely to change in the future. It is recommended that you only use the top-level interface functions to access this structure. This information is provided to help you understand libics, not to help you mess around with its internals.

## General information on the open file

These are used by the library to store the current state of the ICS "stream". They don't influence what is written to the file.

### BlockRead

When data is read in blocks (using `IcsGetDataBlock` and `IcsSkipDataBlock`) this pointer is set to a structure that contains information on the open data file.

type: `void`*

### Filename

Contains the name of the ICS file, including extension and path. If the ICS file in question is an ICS version 1.0, it is also used to locate the corresponding .ids file (data file).

type: `char` [`ICS_MAXPATHLEN`]

### FileMode

Specifies whether the ICS "stream" is open for reading or writing.

type: `Ics_FileMode`

## ICS format

These values determine how the files are written (or how to read them).

### Version

ICS version.

type: `int`

value: 1 for ICS version 1.0, 2 to ICS version 2.0.

### Dimensions

Number of dimensions of the data, not including the pixel depth. Its maximum value is `ICS_MAXDIM`, and determines the amount of useful values in `Dim`.

type: `int`

access: `IcsGetLayout`, `IcsSetLayout`.

### Data

Pointer to the image data to be written. Not used when reading.

type: `void const*`

access: `IcsSetData`, `IcsSetDataWithStrides`.

### DataLength

Size of the image data pointed to by `Data`. Not used when reading.

type: `size_t`

access: `IcsSetData`, `IcsSetDataWithStrides`.

### DataStrides

Pointer to an array with distance in pixels to the neighbors. Not used when reading.

type: `ptrdiff_t const*`

access: `IcsSetDataWithStrides`.

### Compression

Compression technique used.

type: `Ics_Compression`

access: `IcsSetCompression`.

### CompLevel

Parameter for the compression. Not set when reading.

type: `int`

access: `IcsSetCompression`.

### History

Pointer to a structure with "history" lines read or to be written to the ICS file. The structure itself is hidden from the library user. Use the top-level interface to add, delete, replace or retrieve history lines. `IcsAddHistoryString` automatically allocates this structure as needed, and `IcsClose` frees the memory associated with this structure. If not using the high-level interface to write the ICS header, use `IcsFreeHistory`.

type: `void`*

access: `IcsAddHistory`, `IcsDeleteHistory`, `IcsDeleteHistoryStringI`, `IcsGetHistoryKeyValue`, `IcsGetHistoryKeyValueI`, `IcsGetHistoryString`, `IcsGetHistoryStringI`, `IcsGetNumHistoryStrings`, `IcsNewHistoryIterator`, `IcsReplaceHistoryStringI`, `IcsFreeHistory`.

### WriteSensor

Determines if the Special microscopy parameters will be written or not.

type: `int`

value: zero to ignore parameters, non-zero to write them.

## ICS data

These are values that are read from or written to the ICS file, and define the image data. These are vital to the interpretation of the image.

### ByteOrder

The storage order of the bytes is written here. Ignored when writing. Don't change the values when reading.

type: `int` [`ICS_MAX_IMEL_SIZE`]

### Dim

Contains the dimension-specific data. There are `Dimensions` valid entries.

The `Size` field is the only vital element, and gives the dimensions of the image data. The other fields are described below.

type: `Ics_DataRepresentation` [`ICS_MAXDIM`]

access: `IcsGetLayout`, `IcsSetLayout`.

### Imel

Contains the imel-specific data.

The `DataType` is the only vital element, and specifies the data representation. Without this field it is not possible to use the `Data`. The `SigBits` field can be used additionally to indicate how many of the bits are significant (or actually used). The other fields are described below.

type: `Ics_ImelRepresentation`

access: `IcsGetImelSize`, `IcsGetLayout`, `IcsSetLayout`, `IcsGetSignificantBits`, `IcsSetSignificantBits`.

### ScilType

This parameter is used only by SCIL_Image. If you want to read your image with SCIL_Image, there must be a valid string here.

type: `char` [`ICS_STRLEN_TOKEN`]

value: `"g2d"`, `"g3d"`, `"f2d"`, `"f3d"`, `"c2d"`, `"c3d"`, `"b2d"`, `"b3d"`, `"l2d"`, `"l3d"`, `"col2d"` or `"col3d"`.

access: `IcsGetScilType`, `IcsGuessScilType`, `IcsSetScilType`.

### SrcFile

Source file name.

When writing an ICS version 2 file, set this to the name of the file that contains the image data. If this string is not empty, `Data` is ignored, and `IdsWrite` does nothing. If it is empty, the data pointed to by `Data` is written to the end of the ICS file.

When reading, this is set to the name of the file that contains the image data, even if the data is in the ICS file itself.

type: `char` [`ICS_MAXPATHLEN`]

access: `IcsSetSource`.

### SrcOffset

Offset into source file. This is ignored when writing and `SrcFile` is empty.

type: `size_t`

access: `IcsSetSource`.

## ICS parameters

These values are copied as-is to the ICS file, and define the circumstances under which the image was taken. None of these are vital to understand the image data, but can be very useful.

### Coord

The coordinate system used.

type: `char` [`ICS_STRLEN_TOKEN`]

value: `"video"`, `"cartesian"` or anything else you can come up with. The default is `"video"`, which means that the origin is the upper left pixel.

access: `IcsGetCoordinateSystem`, `IcsSetCoordinateSystem`.

### Dim

Contains the dimension-specific data. There are `Dimensions` valid entries.

The `Origin`, `Scale` and `Unit` fields give information on the position of the image in the real world.

The `Order` and `Label` fields define the meaning of each of the dimensions in the image.

type: `Ics_DataRepresentation` [`ICS_MAXDIM`]

access: `IcsGetOrder`, `IcsGetPosition`, `IcsSetOrder`, `IcsSetPosition`.

### Imel

Contains the imel-specific data.

The `Origin`, `Scale` and `Unit` fields specify the physical meaning of the values in the image.

type: `Ics_ImelRepresentation`

access: `IcsGetImelUnits`, `IcsSetImelUnits`.

## Special microscopy parameters

These values are also copied as-is to the ICS file, under the token 'sensor'. This is a token not defined in the standard, and provides specialized information for certain applications. All microscope parameters can be coded in here. If you want these values to be written to the file you need to set `WriteSensor` to a non-zero value. The recommended way to access these parameters is to use the `Sensor` functions.

### ExPhotonCnt

Number of excitation photons.

type: `int` [`ICS_MAX_LAMBDA`]

### LambdaEm

Excitation wavelength in nm.

type: `double` [`ICS_MAX_LAMBDA`]

### LambdaEx

Emission wavelength in nm.

type: `double` [`ICS_MAX_LAMBDA`]

### Model

Model or make.

type: `char` [`ICS_STRLEN_OTHER`]

### NumAperture

Numerical Aperture.

type: `double`

### PinholeRadius

Back projected microns.

type: `double` [`ICS_MAX_LAMBDA`]

### PinholeSpacing

Nipkow Disk pinhole spacing.

type: `double`

### RefrInxLensMedium

Refractive index of design medium.

type: `double`

### RefrInxMedium

Refractive index of embedding medium.

type: `double`

### SensorChannels

Number of channels. Defines the number of useful entries in `PinholeRadius`, `LambdaEx`, `LambdaEm` and `ExPhotonCnt`.

type: `int`

### StedDepletionMode

STED depletion mode.

type: `char` [`ICS_STRLEN_TOKEN`]

### StedImmFraction

STED immunity fraction.

type: `double`

### StedLambda

STED wavelength in nm.

type: `double`

### StedPPMode

STED phase plate mode.

type: `char` [`ICS_STRLEN_TOKEN`]

### StedSatFactor

STED saturation factor.

type: `double`

### StedVPPM

STED vortex to phase plate mix.

type: `double`

### Type

Sensor type.

type: `char` [`ICS_STRLEN_TOKEN`]