Calibration Information

CalibrationInfo

typedef struct fluxEngine_C_v1_CalibrationInfo fluxEngine_C_v1_CalibrationInfo

Calibration Information.

This structure contains calibration information that influences how data is processed. Some fluxEngine filters that process data may use information such as the angle of the instrument to perform more accurate calculations.

There are two types of information stored here: simple quantities that consist of a value and a unit, as well as more complex quantities. All simple quantities may be set by a common set of getter and setter functions, while the more complex pieces of information have specific methods of their own.

For the available simple quantities take a look at the fluxEngine_C_v1_CalibrationSettingType structure.

All fluxEngine filters will have a default behavior if a certain piece of information is not set. For example, the angle of the instrument is assumed to be perpendicular to the sample if nothing else has been set.

Units are treated as strings in this API to allow for future extensibility. The following units are currently supported:

Unitless: "" (empty string)
Kilometers: "Kilometers", "km"
Meters: "Meters", "m"
Centimeters: "Centimeters", "cm"
Millimeters: "Millimeters", "mm"
Micrometers: "Micrometers", "µm" (U+00B5), "μm" (U+03BC)
Nanometers: "Nanometers", "nm"
Angstroms: "Angstroms", "Angstrom", "Å" (U+212B), "Å" (U+00C5)
Picometers: "Picometers", "pm"
Miles (imperial, 5280 feet): "Miles", "mi"
Yards (imperial, 3 feet): "Yards", "yd"
Feet (imperial, 12 iches): "Feet", "ft"
Inches (imperial, 2.54 cm): "Inches", "in"
Thou (imperial, 1/1000 inch): "Thou", "th"
Degrees (Angle): "deg"
Radians (Angle): "rad"

Please note that units are case sensitive, because SI prefixes are case sensitive!

Reminder: all strings in fluxEngine are encoded as UTF-8.

To create an empty information structure, use the fluxEngine_C_v1_CalibrationInfo_create() function. When not used anymore structures have to be freed via the fluxEngine_C_v1_CalibrationInfo_free() function.

See also

fluxEngine_C_v1_CalibrationSettingType

See also

fluxEngine_C_v1_CalibrationInfo_create

See also

fluxEngine_C_v1_CalibrationInfo_copy

See also

fluxEngine_C_v1_CalibrationInfo_free

CalibrationSettingType

enum fluxEngine_C_v1_CalibrationSettingType

Simple calibration setting type.

This enumeration lists the simple settings (that consist of a value and a unit) that describe a given measurement setup.

See also

fluxEngine_C_v1_CalibrationInfo

Values:

enumerator fluxEngine_C_v1_CalibrationSettingType_PixelSizeX

The pixel size in x direction.

How large is a pixel in x direction when looking at the measurement target. (This is not the size of the pixel in the sensor chip!) The quantity associated with this must have a length unit (e.g. 3 mm). This applies equally to line cameras and imager cameras; in the case of imager cameras this will also be used for the size in y direction.

Note that this may be quite large; when processing satellite images this may be of the order of kilometers.

This quantity only makes sense if the target that is looked at is relatively flat.

enumerator fluxEngine_C_v1_CalibrationSettingType_InstrumentBaseDistance

The distance of the instrument to the sample.

The quantity associated with this must have a length unit (e.g. 10 cm).

This quantity only makes sense if the target that is looked at is relatively flat.

enumerator fluxEngine_C_v1_CalibrationSettingType_InstrumentAngleX

The angle of the instrument in the y-z plane.

An angle of 0 indicates perpendicularity to the measurement sample, any deviation indicates that the instrument has been rotated relative to the sample along an axis aligned with the x direction.

CalibrationInfo_create

int fluxEngine_C_v1_CalibrationInfo_create(fluxEngine_C_v1_CalibrationInfo **calibration_info, fluxEngine_C_v1_Error **error)

Create a new (empty) calibration information structure.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument

Parameters:

calibration_info – [out] The newly created calibration information structure
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

CalibrationInfo_copy

int fluxEngine_C_v1_CalibrationInfo_copy(fluxEngine_C_v1_CalibrationInfo *source, fluxEngine_C_v1_CalibrationInfo **calibration_info, fluxEngine_C_v1_Error **error)

Create a copy of a calibration information structure.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument

Parameters:

source – The calibration information strucutre to copy
calibration_info – [out] The newly created calibration information structure
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

CalibrationInfo_set_setting

int fluxEngine_C_v1_CalibrationInfo_set_setting(fluxEngine_C_v1_CalibrationInfo *calibration_info, fluxEngine_C_v1_CalibrationSettingType type, double value, char const *unit, fluxEngine_C_v1_Error **error)

Set a simple calibration setting.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument

Parameters:

calibration_info – The information structure to set it in
type – The setting type
value – The value of the setting
unit – The unit of the setting. For a list of units, please see the documentation of the fluxEngine_C_v1_CalibrationInfo structure. This unit must be of the right type (length unit, angle unit, etc.) for the given setting.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

CalibrationInfo_clear_setting

int fluxEngine_C_v1_CalibrationInfo_clear_setting(fluxEngine_C_v1_CalibrationInfo *calibration_info, fluxEngine_C_v1_CalibrationSettingType type, fluxEngine_C_v1_Error **error)

Clear a simple calibration setting.

This will remove the setting from the calibration information structure, if present. If the setting was not present, this function will have no effect.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument

Parameters:

calibration_info – The information structure to set it in
type – The setting type
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

CalibrationInfo_is_setting_present

int fluxEngine_C_v1_CalibrationInfo_is_setting_present(fluxEngine_C_v1_CalibrationInfo *calibration_info, fluxEngine_C_v1_CalibrationSettingType type, fluxEngine_C_v1_Error **error)

Check whether a simple calibration setting is present.

This will check whether a simple calibration setting is present in the given calibration information structure.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument

Parameters:

calibration_info – The information structure to set it in
type – The setting type
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

1 if the setting is present, 0 if it is not, and -1 on failure

CalibrationInfo_get_setting_unit

int fluxEngine_C_v1_CalibrationInfo_get_setting_unit(fluxEngine_C_v1_CalibrationInfo *calibration_info, fluxEngine_C_v1_CalibrationSettingType type, char **unit, fluxEngine_C_v1_Error **error)

Get the unit of the stored calibration setting.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_IndexOutOfRange

Parameters:

calibration_info – The information structure to set it in
type – The setting type
unit – [out] The unit of the calibration setting. The user must free the resulting string with fluxEngine_C_v1_string_free(). The unit string will be one of the strings documented in the fluxEngine_C_v1_CalibrationInfo structure. For units that have multiple representations the first abbreviated representation will be returned. For example, micrometers will return a string containing 2 characters, the first being the unicode symbol for micro, U+00B5, the second being ‘m’. Since all strings in fluxEngine are considered to be UTF-8 that example will be 3 bytes long, as U+00B5 will be encoded as 0xC2 0xB5 in UTF-8.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

CalibrationInfo_get_setting_value

int fluxEngine_C_v1_CalibrationInfo_get_setting_value(fluxEngine_C_v1_CalibrationInfo *calibration_info, fluxEngine_C_v1_CalibrationSettingType type, char const *unit, double *value, fluxEngine_C_v1_Error **error)

Get the value of the stored calibration setting.

The value will be converted to the specified unit automatically.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_IndexOutOfRange

Parameters:

calibration_info – The information structure to set it in
type – The setting type
unit – The unit to convert the value into. This must be a compatible unit (e.g. a length unit for lengths). See the documentation of the fluxEngine_C_v1_CalibrationInfo structure for details on how to specify units.
value – [out] A pointer where to store the value in
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

CalibrationInfo_set_white_reference_reflectivity

int fluxEngine_C_v1_CalibrationInfo_set_white_reference_reflectivity(fluxEngine_C_v1_CalibrationInfo *calibration_info, size_t count, double const *wavelengths, double const *reflectivities, char const *wavelength_unit, fluxEngine_C_v1_Error **error)

Set the white reference reflectivity.

This special setting may be used to supply a reflectance curve for the white reference that is used in the measurement setup. The white reference measurement will automatically be corrected by fluxEngine by this reflectance curve to more closely be able to calculate the true reflectance of the sample.

If a previous white reference reflectivity curve was present in the calibration information structure, it will be replaced.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_IndexOutOfRange

Parameters:

calibration_info – The calibration info to store this in
count – The number of entries in the curve
wavelengths – A vector of wavelengths (x labels) of the curve
reflectivities – The reflectance values of the white reference, corresponding to the supplied wavelengths. The values must fall between 0.0 (no reflectivity) and 1.0 (full reflectivity). A good white reference typically has a relatively flat reflectivity that is larger than 0.9 for all relevant wavelengths.
wavelength_unit – The unit of the wavelengths, see the documentation of the fluxEngine_C_v1_CalibrationInfo structure for a list of possible units. Typically this will be "nm" to indicate that the curve has been specified in nanometers.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

CalibrationInfo_clear_white_reference_reflectivity

int fluxEngine_C_v1_CalibrationInfo_clear_white_reference_reflectivity(fluxEngine_C_v1_CalibrationInfo *calibration_info, fluxEngine_C_v1_Error **error)

Clear the white reference reflectivity curve.

Removes any existing white reference reflectivity curve in the calibration information structure. If no such curve was present this function has no effect.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_IndexOutOfRange

Parameters:

calibration_info – The calibration info to store this in
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

CalibrationInfo_is_white_reference_reflectivity_present

int fluxEngine_C_v1_CalibrationInfo_is_white_reference_reflectivity_present(fluxEngine_C_v1_CalibrationInfo *calibration_info, fluxEngine_C_v1_Error **error)

Determine whether a white reference reflectivity curve was stored in the calibration information.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_IndexOutOfRange

Parameters:

calibration_info – The calibration info to store this in
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

1 if the white reference reflectivity is present, 0 if it is not, and -1 on failure

CalibrationInfo_get_white_reference_reflectivity

int fluxEngine_C_v1_CalibrationInfo_get_white_reference_reflectivity(fluxEngine_C_v1_CalibrationInfo *calibration_info, size_t *count, double **wavelengths, double **reflectivities, char **wavelength_unit, fluxEngine_C_v1_Error **error)

Get the white reference reflectivity curve.

This will retrieve the white reference reflectivity curve stored in the calibration information. If no such curve has been stored, an error will be returned.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_IndexOutOfRange

Parameters:

calibration_info – The calibration info to store this in
count – [out] Where to store the number of points in the curve in
wavelengths – [out] A pointer to the array of wavelengths (x values) will be stored in this memory area. The resulting array must be freed via fluxEngine_C_v1_wavelengths_free() by the user.
reflectivities – [out] A pointer to the array of reflectivities (y values) will be stored in this memory area. The resulting array must be freed via fluxEngine_C_v1_wavelengths_free() by the user.
wavelength_unit – [out] The unit of the wavelengths as a string. See the documentation of the fluxEngine_C_v1_CalibrationInfo structure for a list of units. The resulting string must be freed by the user via fluxEngine_C_v1_string_free().
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

CalibrationInfo_compare

int fluxEngine_C_v1_CalibrationInfo_compare(fluxEngine_C_v1_CalibrationInfo const *info1, fluxEngine_C_v1_CalibrationInfo const *info2, double relative_value_precision, fluxEngine_C_v1_Error **error)

Compare two fluxEngine_C_v1_CalibrationInfo structures.

This may be used to determine if both structures describe the same data. Since calibration information is provided in the form of floating point data, this comparison routine will also provide feedback in case both structures are not exactly (bitwise) identical, but are close enough in relative precision that they should be considerd equivalent. (The threshold for this may be specified by the user.)

Parameters:

info1 – The first calibration info structure
info2 – The second calibration info structure
relative_value_precision – The relative precision to which to compare various values to. Specify 0 here to always force absolute comparisons. A good default is 1e-7.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 if both calibration information structures are exactly equal, 1 if they have the same settings and the values of those settings are close to the given relative_value_precision, and 2 if they have different settings and/or differ in the values by more than the given relative precision. On failure -1 will be returned.

CalibrationInfo_free

void fluxEngine_C_v1_CalibrationInfo_free(fluxEngine_C_v1_CalibrationInfo *calibration_info)

Free a calibration information structure.

If NULL is passed to this method, it will do nothing.

Parameters:

calibration_info – The structure to free