libics: ICS and Ics_Header structures

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

## Microscopy parameter tokens

Every microscopy parameter has a token that can be used in the generic Set and Get functions to change the value(s). The possible tokens are: `
ICS_SENSOR_IMAGING_DIRECTION
ICS_SENSOR_NUMERICAL_APERTURE
ICS_SENSOR_OBJECTIVE_QUALITY
ICS_SENSOR_MEDIUM_REFRACTIVE_INDEX
ICS_SENSOR_LENS_REFRACTIVE_INDEX
ICS_SENSOR_PINHOLE_RADIUS
ICS_SENSOR_ILL_PINHOLE_RADIUS
ICS_SENSOR_PINHOLE_SPACING
ICS_SENSOR_EXCITATION_BEAM_FILL
ICS_SENSOR_LAMBDA_EXCITATION
ICS_SENSOR_LAMBDA_EMISSION
ICS_SENSOR_PHOTON_COUNT
ICS_SENSOR_INTERFACE_PRIMARY
ICS_SENSOR_INTERFACE_SECONDARY
ICS_SENSOR_DESCRIPTION
ICS_SENSOR_DETECTOR_MAGN
ICS_SENSOR_DETECTOR_PPU
ICS_SENSOR_DETECTOR_BASELINE
ICS_SENSOR_DETECTOR_LINE_AVG_COUNT
ICS_SENSOR_DETECTOR_NOISE_GAIN
ICS_SENSOR_DETECTOR_OFFSET
ICS_SENSOR_DETECTOR_SENSITIVITY
ICS_SENSOR_DETECTOR_RADIUS
ICS_SENSOR_DETECTOR_SCALE
ICS_SENSOR_DETECTOR_STRETCH
ICS_SENSOR_DETECTOR_ROT
ICS_SENSOR_DETECTOR_MIRROR
ICS_SENSOR_DETECTOR_MODEL
ICS_SENSOR_DETECTOR_REDUCEHIST
ICS_SENSOR_STED_DEPLETION_MODE
ICS_SENSOR_STED_LAMBDA
ICS_SENSOR_STED_SATURATION_FACTOR
ICS_SENSOR_STED_IMM_FRACTION
ICS_SENSOR_STED_VPPM
ICS_SENSOR_SPIM_EXCITATION_TYPE
ICS_SENSOR_SPIM_FILL_FACTOR
ICS_SENSOR_SPIM_PLANE_NA
ICS_SENSOR_SPIM_PLANE_GAUSS_WIDTH
ICS_SENSOR_SPIM_PLANE_PROP_DIR
ICS_SENSOR_SPIM_PLANE_CENTER_OFF
ICS_SENSOR_SPIM_PLANE_FOCUS_OFF
ICS_SENSOR_SCATTER_MODEL
ICS_SENSOR_SCATTER_FREE_PATH
ICS_SENSOR_SCATTER_REL_CONTRIB
ICS_SENSOR_SCATTER_BLURRING
`

## Microscopy parameter states

Every microscopy parameter has a state indicating where the parameter came from / the level of confidence we have in the parameter. Possible values:
`IcsSensorState_default`
`IcsSensorState_estimated`
`IcsSensorState_reported`
`IcsSensorState_verified`