Manual Access of Calibration Files

Note

Support for parsing calibration files is only available with special licenses for fluxEngine.

CalibrationFile

typedef struct fluxEngine_C_v1_CalibrationFile fluxEngine_C_v1_CalibrationFile: Opaque handle to a parsed calibration file.

CalibrationFile_ParserOptions

struct fluxEngine_C_v1_CalibrationFile_ParserOptions

Options that influence the calibration file parser.

These options must be specified to allow the calibration file parser to provide the appropriate diagnostics. The options are mostly information that describes properties of the underlying sensor, so that it can be verified that the calibration file can be used in conjunction with the sensor.

CalibrationFile_CameraType

enum fluxEngine_C_v1_CalibrationFile_CameraType

The type of camera the calibration file describes.

Currently only PushBroom cameras are supported.

Values:

enumerator fluxEngine_C_v1_CalibrationFile_CameraType_Unknown: The camera type is unknown.

enumerator fluxEngine_C_v1_CalibrationFile_CameraType_PushBroom: The file describes a PushBroom camera.

CalibrationFile_WavelengthAxis

enum fluxEngine_C_v1_CalibrationFile_WavelengthAxis

Which axis is the wavelength axis.

For PushBroom cameras this determines which axis is the wavelength axis. (The other axis will then be the spatial axis.)

Values:

enumerator fluxEngine_C_v1_CalibrationFile_WavelengthAxis_X: Wavelengths are stored in the X direction.

enumerator fluxEngine_C_v1_CalibrationFile_WavelengthAxis_Y: Wavelengths are stored in the Y direction.

CalibrationFile_ROIInput

struct fluxEngine_C_v1_CalibrationFile_ROIInput

Calibration File ROI Input.

There are two types of query functions for the calibration file: those that query the exact information that was stored, and those that query effective information.

When querying effective information this structure must be passed so that the user-specified information about binning and ROI can be considered before returning effective data.

If NULL is supplied instead of this structure, a binning factor of 1 in both directions, as well as the maximum possible ROI, are assumed.

CalibrationFile_MapFlags

enum fluxEngine_C_v1_CalibrationFile_MapFlags

Flags that influence obtaining smile/keystone maps.

Values:

enumerator fluxEngine_C_v1_CalibrationFile_MapFlag_AbsoluteCoordinates

Get absolute coordinates instead of shifts.

Smile/keystone maps typically only contain the relative shifts to the pixel coordinate. By activating this flag, absolute source pixel coordinates will be returned in the map instead.

CalibrationFile_SelectedCorrections

enum fluxEngine_C_v1_CalibrationFile_SelectedCorrections

Selected corrections to apply.

Values:

enumerator fluxEngine_C_v1_CalibrationFile_SelectedCorrection_Smile: Enable Smile correction.

enumerator fluxEngine_C_v1_CalibrationFile_SelectedCorrection_Keystone: Enable Keystone correction.

CalibrationFile_parse

int fluxEngine_C_v1_CalibrationFile_parse(fluxEngine_C_v1_Handle *handle, void const *contents, size_t contents_size_bytes, fluxEngine_C_v1_CalibrationFile_ParserOptions const *options, fluxEngine_C_v1_CalibrationFile **result_file, fluxEngine_C_v1_Error **error)

Parse a calibration file.

This function parses a calibration file.

This is advanced functionality for camera makers that want to test calibration files they create. A special license is required to use this functionality.

Parameters:

handle – The fluxEngine handle
contents – A pointer pointing to the start of the memory region containing the calibration file contents
contents_size_bytes – The size of the calibration file contents, in bytes
options – The options used for parsing the calibration file
result_file – [out] The resulting parsed calibration file
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

CalibrationFile_get_warning_count

int fluxEngine_C_v1_CalibrationFile_get_warning_count(fluxEngine_C_v1_CalibrationFile *file, size_t *count, fluxEngine_C_v1_Error **error)

Get the number of warnings that occurred while parsing the calibration file.

This can provide useful diagnostics such as the active area coordinates not being commensurate with the binning values, which is supported (albeit by reducing the active area when binning is active), but causes very confusing user interactions.

Parameters:

file – The parsed calibration file
count – [out] The number of warnings
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

CalibrationFile_get_warning

int fluxEngine_C_v1_CalibrationFile_get_warning(fluxEngine_C_v1_CalibrationFile *file, size_t index, char **warning, fluxEngine_C_v1_Error **error)

Get a warning that occurred while parsing the calibration file.

Retrieves one of the warnings (up to the count returned by fluxEngine_C_v1_CalibrationFile_get_warning_count()) that was produced while parsing the calibration file.

Parameters:

file – The parsed calibration file
index – The index of the warning, starting at 0 for the first warning, up to one less than the number of warnings for the last warning.
warning – [out] The warning message. The resulting string must be freed with 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

CalibrationFile_get_camera_model

int fluxEngine_C_v1_CalibrationFile_get_camera_model(fluxEngine_C_v1_CalibrationFile *file, char **value, fluxEngine_C_v1_Error **error)

Get the camera model.

This returns the string contents of the <CameraModel> element in the calibration file.

Parameters:

file – The parsed calibration file
value – [out] The string in the calibration file, or NULL if it was not specified. The resulting string (if returned) must be freed with 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

CalibrationFile_get_camera_serial

int fluxEngine_C_v1_CalibrationFile_get_camera_serial(fluxEngine_C_v1_CalibrationFile *file, char **value, fluxEngine_C_v1_Error **error)

Get the camera serial number.

This returns the string contents of the <CameraSerial> element in the calibration file.

Parameters:

file – The parsed calibration file
value – [out] The string in the calibration file, or NULL if it was not specified. The resulting string (if returned) must be freed with 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

CalibrationFile_get_optics_serial

int fluxEngine_C_v1_CalibrationFile_get_optics_serial(fluxEngine_C_v1_CalibrationFile *file, char **value, fluxEngine_C_v1_Error **error)

Get the optics serial number.

This returns the string contents of the <OpticsSerial> element in the calibration file.

Parameters:

file – The parsed calibration file
value – [out] The string in the calibration file, or NULL if it was not specified. The resulting string (if returned) must be freed with 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

CalibrationFile_get_calibration_process_version

int fluxEngine_C_v1_CalibrationFile_get_calibration_process_version(fluxEngine_C_v1_CalibrationFile *file, char **value, fluxEngine_C_v1_Error **error)

Get the calibration process version.

This returns the string contents of the <CalibrationProcessVersion> element in the calibration file.

Parameters:

file – The parsed calibration file
value – [out] The string in the calibration file, or NULL if it was not specified. The resulting string (if returned) must be freed with 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

CalibrationFile_get_calibration_data_version

int fluxEngine_C_v1_CalibrationFile_get_calibration_data_version(fluxEngine_C_v1_CalibrationFile *file, char **value, fluxEngine_C_v1_Error **error)

Get the calibration data version.

This returns the string contents of the <CalibrationDataVersion> element in the calibration file.

Parameters:

file – The parsed calibration file
value – [out] The string in the calibration file, or NULL if it was not specified. The resulting string (if returned) must be freed with 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

CalibrationFile_get_camera_type

int fluxEngine_C_v1_CalibrationFile_get_camera_type(fluxEngine_C_v1_CalibrationFile *file, fluxEngine_C_v1_CalibrationFile_CameraType *value, fluxEngine_C_v1_Error **error)

Get the camera type described by the calibration file.

Parameters:

file – The parsed calibration file
value – [out] The camera type the calibration file was written for
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

CalibrationFile_PushBroom_get_active_area

int fluxEngine_C_v1_CalibrationFile_PushBroom_get_active_area(fluxEngine_C_v1_CalibrationFile *file, int64_t *offset_x, int64_t *offset_y, int64_t *width, int64_t *height, bool *explicitly_specified, fluxEngine_C_v1_Error **error)

Get the active area of the sensor that is used to collect data.

Parameters:

file – The parsed calibration file
offset_x – [out] The X offset of the active area in pixels (starting at 0 for the left-most pixel of the sensor)
offset_y – [out] The Y offset of the active area in pixels (starting at 0 for the top-most pixel of the sensor)
width – [out] The width of the active area in pixels
height – [out] The height of the active area in pixels
explicitly_specified – [out] true if the calibration file contained an explicit specification of the active area, false otherwise (in which case the offsets will be 0 and the width and height be that of the sensor)
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

CalibrationFile_PushBroom_get_wavelength_axis

int fluxEngine_C_v1_CalibrationFile_PushBroom_get_wavelength_axis(fluxEngine_C_v1_CalibrationFile *file, fluxEngine_C_v1_CalibrationFile_WavelengthAxis *value, fluxEngine_C_v1_Error **error)

Get the wavelength axis.

The wavelength axis of a PushBroom specifies which axis is used to encode the spectral information of the system; the axis encoding spatial information will hence be the remaining one.

Parameters:

file – The parsed calibration file
value – [out] The wavelength axis
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

CalibrationFile_PushBroom_get_wavelength_calibration_count

int fluxEngine_C_v1_CalibrationFile_PushBroom_get_wavelength_calibration_count(fluxEngine_C_v1_CalibrationFile *file, size_t *count, fluxEngine_C_v1_Error **error)

Get the number of wavelength calibrations in the calibration file.

A calibration file may contain multiple wavelength calibrations due to different spectral binning values. This function will retrieve the amount of calibrations in the file. This is not the number of wavelengths, but rather the number of distinct binning factors for which an explicit calibration was specified.

Parameters:

file – The parsed calibration file
count – [out] The number of wavelength calibrations in the file
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

CalibrationFile_PushBroom_get_wavelength_calibration_for_index

int fluxEngine_C_v1_CalibrationFile_PushBroom_get_wavelength_calibration_for_index(fluxEngine_C_v1_CalibrationFile *file, size_t index, double **wavelengths_nm, size_t *count, int64_t *binning, bool *are_coefficients, fluxEngine_C_v1_Error **error)

Get the wavelength calibration for a given index.

Returns the wavelength calibration for a given index. This can have two different forms:

A list of wavelengths the size of the active area (divided by the binning factor)
A list of coefficients that are used to create a polynomial that calculates the wavelengths

The argument of the polynomial is the pixel index in the wavelength axis, where 0 indicates the top- or left-most pixel of the active area.

The first polynomial coefficient is the global offset, the second coefficient is the linear term, the third the quadratic term, etc.

A valid calibration file will always have a wavelength calibration for a binning value of 1. Even if the sensor supports binning, it is optional to specify explicitly derived values and/or coefficients for higher binning values. The software can infer the calibration for higher binning values itself (though that may not be as accurate as an explicit calibration). The automatic inference for higher binning values is NOT done by this function though, it will only return what is actually in the calibration file. To obtain efffective values, see fluxEngine_C_v1_CalibrationFile_PushBroom_get_effective_wavelengths().

Parameters:

file – The parsed calibration file
index – The index of the wavelength calibration, starting at 0 for the first calibration, ending at one less than the count returned by fluxEngine_C_v1_CalibrationFile_PushBroom_get_wavelength_calibration_count() for the last calibration.
wavelengths_nm – [out] The list of wavelengths or the list of coefficients for that specific wavelength calibration. This must be freed by the user with fluxEngine_C_v1_wavelengths_free().
count – [out] The number of wavelengths or number of coefficients
binning – [out] The binning factor (along the wavelength axis) for which these wavelengths or coefficients were obtained
are_coefficients – [out] true if the values stored in wavelengths_nm are coefficients, false if they are a list of wavelengths
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

CalibrationFile_PushBroom_get_fwhm_calibration_count

int fluxEngine_C_v1_CalibrationFile_PushBroom_get_fwhm_calibration_count(fluxEngine_C_v1_CalibrationFile *file, size_t *count, fluxEngine_C_v1_Error **error)

Get the number of FWHM calibrations in the calibration file.

A calibration file may contain multiple full-width half-maximum (FWHM) calibrations due to different spectral binning values. This function will retrieve the amount of calibrations in the file. This is not the number of FWHM values, but rather the number of distinct binning factors for which an explicit calibration was specified.

This may be zero if the calibration file does not specify FWHM values.

Parameters:

file – The parsed calibration file
count – [out] The number of FWHM calibrations in the file
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

CalibrationFile_PushBroom_get_fwhm_calibration_for_index

int fluxEngine_C_v1_CalibrationFile_PushBroom_get_fwhm_calibration_for_index(fluxEngine_C_v1_CalibrationFile *file, size_t index, double **fwhm_nm, size_t *count, int64_t *binning, bool *are_coefficients, fluxEngine_C_v1_Error **error)

Get the FWHM calibration for a given index.

Returns the FWHM calibration for a given index. This can have two different forms:

A list of FWHM values the size of the active area (divided by the binning factor)
A list of coefficients that are used to create a polynomial that calculates the FWHM values

The argument of the polynomial is the pixel index in the wavelength axis, where 0 indicates the top- or left-most pixel of the active area.

The first polynomial coefficient is the global offset, the second coefficient is the linear term, the third the quadratic term, etc.

A valid calibration file will either have no FWHM values at all, but if it does have such values, it will always have a FWHM calibration for a binning value of 1. Even if the sensor supports binning, it is optional to specify explicitly derived values and/or coefficients for higher binning values. The software can infer the calibration for higher binning values itself (though that may not be as accurate as an explicit calibration). The automatic inference for higher binning values is NOT done by this function though, it will only return what is actually in the calibration file. To obtain efffective values, see fluxEngine_C_v1_CalibrationFile_PushBroom_get_effective_fwhm().

Parameters:

file – The parsed calibration file
index – The index of the FWHM calibration, starting at 0 for the first calibration, ending at one less than the count returned by fluxEngine_C_v1_CalibrationFile_PushBroom_get_fwhm_calibration_count() for the last calibration.
fwhm_nm – [out] The list of FWHM values or the list of coefficients for that specific FWHM calibration. This must be freed by the user with fluxEngine_C_v1_wavelengths_free().
count – [out] The number of FWHM values or number of coefficients
binning – [out] The binning factor (along the wavelength axis) for which these FWHM values or coefficients were obtained
are_coefficients – [out] true if the values stored in fwhm_nm are coefficients, false if they are a list of FWHM values
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

CalibrationFile_PushBroom_get_nominal_wavelength_list_count

int fluxEngine_C_v1_CalibrationFile_PushBroom_get_nominal_wavelength_list_count(fluxEngine_C_v1_CalibrationFile *file, size_t *count, fluxEngine_C_v1_Error **error)

Get the number of nominal wavelength lists in the calibration file.

A calibration file may optionally specify a nominal wavelength list. This information may be used by software to later abstract away wavelength calibration differences between individual cameras.

For example a HSI PushBroom camera in the visible light might have a calibration file that specifies nominal wavelengths starting at 400 nm, in a step size of 4 nm, up to 1000 nm.

Multiple such nominal wavelength lists may exist in the calibration file due to different spectral binning values. This function will retrieve the amount of such lists in the file. This is not the number of nominal wavelengths, but rather the number of distinct binning factors for which an explicit list was specified.

This may be zero if no nominal wavelength list is specified in the calibration file.

Parameters:

file – The parsed calibration file
count – [out] The number of nominal wavelength lists specified in the calibration file
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

CalibrationFile_PushBroom_get_nominal_wavelength_list_for_index

int fluxEngine_C_v1_CalibrationFile_PushBroom_get_nominal_wavelength_list_for_index(fluxEngine_C_v1_CalibrationFile *file, size_t index, double **wavelengths_nm, size_t *count, int64_t *binning, fluxEngine_C_v1_Error **error)

Get the nominal wavelength list for a given index.

Returns the nominal wavelength list for a given index. This will always be a list of wavelengths, and the number of wavelengths may not have any direct correspondence in the size of the active area (or similar).

A valid calibration file will either have no nominal wavelengths, but if it does, it will always have a nominal wavelengths list for a binning value of 1. Even if the sensor supports binning, it is optional to specify explicitly derived values and/or coefficients for higher binning values. The software can infer the lists for higher binning values itself (though that may not be as accurate as an explicit list). The automatic inference for higher binning values is NOT done by this function though, it will only return what is actually in the calibration file. To obtain efffective values, see fluxEngine_C_v1_CalibrationFile_PushBroom_get_effective_nominal_wavelengths().

Parameters:

file – The parsed calibration file
index – The index of the nominal wavelength list, starting at 0 for the first list, ending at one less than the count returned by fluxEngine_C_v1_CalibrationFile_PushBroom_get_nominal_wavelength_list_count() for the last list.
wavelengths_nm – [out] The list of nominal wavelengths for the given binning factor. This must be freed by the user with fluxEngine_C_v1_wavelengths_free().
count – [out] The number of wavelengths (this may be completely different from the active area and/or ROI)
binning – [out] The binning factor (along the wavelength axis) for which these wavelength list was obtained
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

CalibrationFile_PushBroom_get_smile_calibration_count

int fluxEngine_C_v1_CalibrationFile_PushBroom_get_smile_calibration_count(fluxEngine_C_v1_CalibrationFile *file, size_t *count, fluxEngine_C_v1_Error **error)

Get the number of smile correction calibrations in the calibration file.

A calibration file may contain zero or more smile correction calibrations that describe how the smile of a PushBroom image is corrected in software. If one or more such corrections are present, at least one must be available with a spectral and spatial binning factor of 1.

Note that this is not the number of smile coefficients, this is rather the number of binning combinations for which the smile coefficients are present in the calibration file. (This number may be 0 if the calibration file does not contain any smile correction information).

It is possible for the software to automatically reconstruct smile correction information for higher binning values if they are not explicitly specified in the calibration file; but this function can only return values that are actually present in the calibration file. Use fluxEngine_C_v1_CalibrationFile_PushBroom_get_smile_map() to obtain an explicit 2D map for arbitrary binning values (as long as at least one smile correction calibration is present).

Parameters:

file – The parsed calibration file
count – [out] The number of smile correction calibrations in the calibration file.
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

CalibrationFile_PushBroom_get_smile_calibration_for_index

int fluxEngine_C_v1_CalibrationFile_PushBroom_get_smile_calibration_for_index(fluxEngine_C_v1_CalibrationFile *file, size_t index, double **coeffs, size_t *count, int64_t *binning_spectral, int64_t *binning_spatial, fluxEngine_C_v1_Error **error)

Get the smile correction coefficients for a given index.

Get one set of smile correction coefficients stored in the calibration file. The smile correction coefficients are always a 2D polynomial. See the calibration file specification for details.

Parameters:

file – The parsed calibration file
index – The index of the smile correction coefficients.
coeffs – [out] The smile correction coefficients. This must be freed by the user with fluxEngine_C_v1_wavelengths_free().
count – [out] The number of smile correction coefficients.
binning_spectral – [out] The spectral binning factor for which the coefficients have been specified
binning_spatial – [out] The spatial binning factor for which the coefficients have been specified
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

CalibrationFile_PushBroom_get_keystone_calibration_count

int fluxEngine_C_v1_CalibrationFile_PushBroom_get_keystone_calibration_count(fluxEngine_C_v1_CalibrationFile *file, size_t *count, fluxEngine_C_v1_Error **error)

Get the number of keystone correction calibrations in the calibration file.

A calibration file may contain zero or more keystone correction calibrations that describe how the keystone of a PushBroom image is corrected in software. If one or more such corrections are present, at least one must be available with a spectral and spatial binning factor of 1.

Note that this is not the number of keystone coefficients, this is rather the number of binning combinations for which the keystone coefficients are present in the calibration file. (This number may be 0 if the calibration file does not contain any keystone correction information).

It is possible for the software to automatically reconstruct keystone correction information for higher binning values if they are not explicitly specified in the calibration file; but this function can only return values that are actually present in the calibration file. Use fluxEngine_C_v1_CalibrationFile_PushBroom_get_keystone_map() to obtain an explicit 2D map for arbitrary binning values (as long as at least one keystone correction calibration is present).

Parameters:

file – The parsed calibration file
count – [out] The number of keystone correction calibrations in the calibration file.
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

CalibrationFile_PushBroom_get_keystone_calibration_for_index

int fluxEngine_C_v1_CalibrationFile_PushBroom_get_keystone_calibration_for_index(fluxEngine_C_v1_CalibrationFile *file, size_t index, double **coeffs, size_t *count, int64_t *binning_spectral, int64_t *binning_spatial, fluxEngine_C_v1_Error **error)

Get the keystone correction coefficients for a given index.

Get one set of keystone correction coefficients stored in the calibration file. The keystone correction coefficients are always a 2D polynomial. See the calibration file specification for details.

Parameters:

file – The parsed calibration file
index – The index of the keystone correction coefficients.
coeffs – [out] The keystone correction coefficients. This must be freed by the user with fluxEngine_C_v1_wavelengths_free().
count – [out] The number of keystone correction coefficients.
binning_spectral – [out] The spectral binning factor for which the coefficients have been specified
binning_spatial – [out] The spatial binning factor for which the coefficients have been specified
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

CalibrationFile_PushBroom_get_effective_wavelengths

int fluxEngine_C_v1_CalibrationFile_PushBroom_get_effective_wavelengths(fluxEngine_C_v1_Handle *handle, fluxEngine_C_v1_CalibrationFile *file, fluxEngine_C_v1_CalibrationFile_ROIInput const *roi_input, double **wavelengths_nm, size_t *count, fluxEngine_C_v1_Error **error)

Get the effective wavelengths for given ROI/binning settings.

Calculates the list of wavelengths associated with a given ROI/binning setting. If the wavelengths are specified as coefficients in the calibration file, the coefficients will be evaluated; ROI will be applied.

If no wavelength calibration is present in the calibration file for the specified spectral binning value, the wavelengths will be calculated automatically from the unbinned case.

Parameters:

handle – The fluxEngine handle
file – The parsed calibration file
roi_input – The camera settings to use
wavelengths_nm – [out] The wavelength values corresponding to each pixel along the wavelength axis for the specified ROI. This must be freed by the user with fluxEngine_C_v1_wavelengths_free().
count – [out] The number of wavelengths. This will be equal to the width or the height of the ROI, depending on the wavelength axis
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

CalibrationFile_PushBroom_get_effective_fwhm

int fluxEngine_C_v1_CalibrationFile_PushBroom_get_effective_fwhm(fluxEngine_C_v1_Handle *handle, fluxEngine_C_v1_CalibrationFile *file, fluxEngine_C_v1_CalibrationFile_ROIInput const *roi_input, double **fwhm_nm, size_t *count, fluxEngine_C_v1_Error **error)

Get the effective FWHM values for given ROI/binning settings.

Calculates the list of FWHM values associated with a given ROI/binning setting. If the FWHM values are specified as coefficients in the calibration file, the coefficients will be evaluated; ROI will be applied.

If no FWHM values are present in the calibration file for the specified spectral binning value, the FWHM values will be calculated automatically from the unbinned case.

If no FWHM values are present in the calibration file at all, an error will occur.

Parameters:

handle – The fluxEngine handle
file – The parsed calibration file
roi_input – The camera settings to use
fwhm_nm – [out] The FWHM values corresponding to each pixel along the wavelength axis for the specified ROI. This must be freed by the user with fluxEngine_C_v1_wavelengths_free().
count – [out] The number of FWHM values. This will be equal to the width or the height of the ROI, depending on the wavelength axis
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

CalibrationFile_PushBroom_get_effective_nominal_wavelengths

int fluxEngine_C_v1_CalibrationFile_PushBroom_get_effective_nominal_wavelengths(fluxEngine_C_v1_Handle *handle, fluxEngine_C_v1_CalibrationFile *file, fluxEngine_C_v1_CalibrationFile_ROIInput const *roi_input, double **wavelengths_nm, size_t *count, fluxEngine_C_v1_Error **error)

Get the nominal wavelengths for given ROI/binning settings.

Calculates the list of nominal wavelengths associated with a given ROI/binning setting.

If no nominal wavelength list is present in the calibration file for the specified spectral binning value, but a base list for a binning value of 1 is present, the binned nominal wavelengths list will be calculated automatically.

If no nominal wavelength lists are present in the calibration file at all, an error will occur.

Parameters:

handle – The fluxEngine handle
file – The parsed calibration file
roi_input – The camera settings to use
wavelengths_nm – [out] The nominal wavelengths restricted to the actual wavelength range within the ROI. This must be freed by the user with fluxEngine_C_v1_wavelengths_free().
count – [out] The number of nominal wavelengths. This may be entirely different from the size of the ROI
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

CalibrationFile_PushBroom_get_smile_map

int fluxEngine_C_v1_CalibrationFile_PushBroom_get_smile_map(fluxEngine_C_v1_Handle *handle, fluxEngine_C_v1_CalibrationFile *file, fluxEngine_C_v1_CalibrationFile_ROIInput const *roi_input, uint64_t flags, fluxEngine_C_v1_MutableTensor *map, fluxEngine_C_v1_Error **error)

Get the smile correction map for given ROI/binning settings.

Calculates the smile correction map for given ROI/bining settings.

For each pixel in the target image, the smile correction map determines the offset along the wavelength axis required to reach the coordinates this pixel has in the source image.

Depending on flags the resulting map will either contain relative offsets, or it will contain absolute coordinates. See fluxEngine_C_v1_CalibrationFile_MapFlags for details on the possible flags.

Parameters:

handle – The fluxEngine handle
file – The parsed calibration file
roi_input – The camera settings to use
flags – The flags that influence the behavior of this function (use 0 for the default behavior)
map – [out] A user-allocated tensor of the correct size (order 2, dimension 0 being the height, dimension 1 being the width), of either float32 or float64 type, where the map will be stored 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

CalibrationFile_PushBroom_get_keystone_map

int fluxEngine_C_v1_CalibrationFile_PushBroom_get_keystone_map(fluxEngine_C_v1_Handle *handle, fluxEngine_C_v1_CalibrationFile *file, fluxEngine_C_v1_CalibrationFile_ROIInput const *roi_input, uint64_t flags, fluxEngine_C_v1_MutableTensor *map, fluxEngine_C_v1_Error **error)

Get the keystone correction map for given ROI/binning settings.

Calculates the keystone correction map for given ROI/bining settings.

For each pixel in the target image, the keystone correction map determines the offset along the spatial axis required to reach the coordinates this pixel has in the source image.

Depending on flags the resulting map will either contain relative offsets, or it will contain absolute coordinates. See fluxEngine_C_v1_CalibrationFile_MapFlags for details on the possible flags.

Parameters:

handle – The fluxEngine handle
file – The parsed calibration file
roi_input – The camera settings to use
flags – The flags that influence the behavior of this function (use 0 for the default behavior)
map – [out] A user-allocated tensor of the correct size (order 2, dimension 0 being the height, dimension 1 being the width), of either float32 or float64 type, where the map will be stored 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

CalibrationFile_PushBroom_get_x_map

int fluxEngine_C_v1_CalibrationFile_PushBroom_get_x_map(fluxEngine_C_v1_Handle *handle, fluxEngine_C_v1_CalibrationFile *file, fluxEngine_C_v1_CalibrationFile_ROIInput const *roi_input, uint64_t flags, fluxEngine_C_v1_MutableTensor *map, fluxEngine_C_v1_Error **error)

Get the X correction map for given ROI/binning settings.

This will be identical to either fluxEngine_C_v1_CalibrationFile_PushBroom_get_smile_map(), or to fluxEngine_C_v1_CalibrationFile_PushBroom_get_keystone_map(), depending on which the wavelength axis is.

It exists so the user can call just this method (and the corresponding method for the y axis) to obtain the shift along the axis of the image, without having to take care of which the wavelength axis is.

Depending on flags the resulting map will either contain relative offsets, or it will contain absolute coordinates. See fluxEngine_C_v1_CalibrationFile_MapFlags for details on the possible flags.

Parameters:

handle – The fluxEngine handle
file – The parsed calibration file
roi_input – The camera settings to use
flags – The flags that influence the behavior of this function (use 0 for the default behavior)
map – [out] A user-allocated tensor of the correct size (order 2, dimension 0 being the height, dimension 1 being the width), of either float32 or float64 type, where the map will be stored 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

CalibrationFile_PushBroom_get_y_map

int fluxEngine_C_v1_CalibrationFile_PushBroom_get_y_map(fluxEngine_C_v1_Handle *handle, fluxEngine_C_v1_CalibrationFile *file, fluxEngine_C_v1_CalibrationFile_ROIInput const *roi_input, uint64_t flags, fluxEngine_C_v1_MutableTensor *map, fluxEngine_C_v1_Error **error)

Get the Y correction map for given ROI/binning settings.

This will be identical to either fluxEngine_C_v1_CalibrationFile_PushBroom_get_smile_map(), or to fluxEngine_C_v1_CalibrationFile_PushBroom_get_keystone_map(), depending on which the wavelength axis is.

It exists so the user can call just this method (and the corresponding method for the x axis) to obtain the shift along the axis of the image, without having to take care of which the wavelength axis is.

Depending on flags the resulting map will either contain relative offsets, or it will contain absolute coordinates. See fluxEngine_C_v1_CalibrationFile_MapFlags for details on the possible flags.

Parameters:

handle – The fluxEngine handle
file – The parsed calibration file
roi_input – The camera settings to use
flags – The flags that influence the behavior of this function (use 0 for the default behavior)
map – [out] A user-allocated tensor of the correct size (order 2, dimension 0 being the height, dimension 1 being the width), of either float32 or float64 type, where the map will be stored 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

CalibrationFile_PushBroom_apply_corrections

int fluxEngine_C_v1_CalibrationFile_PushBroom_apply_corrections(fluxEngine_C_v1_Handle *handle, fluxEngine_C_v1_CalibrationFile *file, fluxEngine_C_v1_CalibrationFile_ROIInput const *roi_input, void const *reserved__arg0, uint64_t selected_corrections, fluxEngine_C_v1_Tensor const *input_image, fluxEngine_C_v1_MutableTensor *output_image, fluxEngine_C_v1_Error **error)

Apply the selected corrections to the source image.

This function applies the selected camera corrections to the source image.

See fluxEngine_C_v1_CalibrationFile_SelectedCorrections for a list of corrections that may be applied to the image. If no information is present in the calibration file for a given correction, this function will still succeed, but that particular correction will not be applied.

If selected_corrections is 0 the image data will just be copied from the source buffer to the target buffer.

IMPORTANT: this function is NOT designed for performance; it will apply the same corrections as the

Parameters:

handle – The fluxEngine handle
file – The parsed calibration file
roi_input – The camera settings to use
reserved__arg0 – Reserved (must be set to NULL)
selected_corrections – A bitfield containing the selected corrections
input_image – A tensor containing the input image to be corrected. The data type can be any that is supported by fluxEngine. The order of the tensor must be 2; its 0th dimension must be the height of the image, its 1st dimension must be the width.
output_image – [out] A user-allocated tensor of the correct size (order 2, dimension 0 being the height, dimension 1 being the width), of either float32 or float64 type, where the result will be stored 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

CalibrationFile_free

void fluxEngine_C_v1_CalibrationFile_free(fluxEngine_C_v1_CalibrationFile *calibration_file)

Free a calibration file.

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

Parameters:

calibration_file – The structure to free