Manual Access of Calibration Files

Note

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

CalibrationFile

class CalibrationFile

A parsed calibration file.

Public Types

enum class CameraType

The type of camera the calibration file describes.

Currently only PushBroom cameras are supported.

Values:

enumerator Unknown

The camera type is unknown.

enumerator PushBroom

The file describes a PushBroom camera.

enum class 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 X

Wavelengths are along the X direction.

enumerator Y

Wavelengths are along the Y direction.

enum MapFlags

Flags that influence obtaining smile/keystone maps.

Values:

enumerator 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.

enum SelectedCorrections

Selected corrections to apply.

Values:

enumerator SelectedCorrection_Smile

Enable Smile correction.

enumerator SelectedCorrection_Keystone

Enable Keystone correction.

Public Functions

CalibrationFile() = default

Default constructor.

This does not wrap any object.

inline CalibrationFile(CalibrationFile &&other) noexcept

Move constructor.

Parameters:

other – The wrapper to move

inline CalibrationFile &operator=(CalibrationFile &&other) noexcept

Move assignment operator.

Parameters:

other – The wrapper to move

Returns:

A reference to *this

inline ~CalibrationFile() noexcept

Destructor.

inline std::vector<std::string> warnings() const

Get the warnings that occurred during parsing.

Some calibration files may be parseable but contain information that can be unintuitive when applied. In that case the parse() method will still be successful, but the resulting object will have a couple of warning messages, which can be retrieved by this method.

Returns:

The warnings (if any) that occurred during parsing

inline bool getCameraModel(std::string &result) const

Get the camera model specified in the calibration file (if present)

If C++17 or newer is used to compile this header, there is also a method cameraModel(), which returns a std::optional<std::string>.

Parameters:

result – The string to store the value in

Returns:

Whether the requested information was specified in the calibration file. If not, result is unmodified

inline bool getCameraSerial(std::string &result) const

Get the camera serial number specified in the calibration file (if present)

If C++17 or newer is used to compile this header, there is also a method cameraSerial(), which returns a std::optional<std::string>.

Parameters:

result – The string to store the value in

Returns:

Whether the requested information was specified in the calibration file. If not, result is unmodified

inline bool getOpticsSerial(std::string &result) const

Get the optics serial number specified in the calibration file (if present)

If C++17 or newer is used to compile this header, there is also a method opticsSerial(), which returns a std::optional<std::string>.

Parameters:

result – The string to store the value in

Returns:

Whether the requested information was specified in the calibration file. If not, result is unmodified

inline bool getCalibrationProcessVersion(std::string &result) const

Get the calibration process version specified in the calibration file (if present)

If C++17 or newer is used to compile this header, there is also a method calibrationProcessVersion(), which returns a std::optional<std::string>.

Parameters:

result – The string to store the value in

Returns:

Whether the requested information was specified in the calibration file. If not, result is unmodified

inline bool getCalibrationDataVersion(std::string &result) const

Get the calibration data version specified in the calibration file (if present)

If C++17 or newer is used to compile this header, there is also a method calibrationDataVersion(), which returns a std::optional<std::string>.

Parameters:

result – The string to store the value in

Returns:

Whether the requested information was specified in the calibration file. If not, result is unmodified

inline std::optional<std::string> cameraModel() const

Get the camera model specified in the calibration file (if any)

Returns:

The camera model specified in the calibration file, or std::nullopt, if none was.

inline std::optional<std::string> cameraSerial() const

Get the camera serial number specified in the calibration file (if any)

Returns:

The camera serial number specified in the calibration file, or std::nullopt, if none was.

inline std::optional<std::string> opticsSerial() const

Get the optics serial number specified in the calibration file (if any)

Returns:

The optics serial number specified in the calibration file, or std::nullopt, if none was.

inline std::optional<std::string> calibrationProcessVersion() const

Get the calibration process version specified in the calibration file (if any)

Returns:

The calibration process version specified in the calibration file, or std::nullopt, if none was.

inline std::optional<std::string> calibrationDataVersion() const

Get the calibration data version specified in the calibration file (if any)

Returns:

The calibration data version specified in the calibration file, or std::nullopt, if none was.

inline CameraType cameraType() const

Get the camera type the calibration file was created for.

Returns:

The camera type the calibration file was created for

inline EffectiveActiveArea activeArea() const

Get the effective active area.

If the calibration file is not for a PushBroom camera this will throw an error.

Returns:

The effective active area

inline WavelengthAxis wavelengthAxis() const

Get the wavelength axis.

If the calibration file is not for a PushBroom camera this will throw an error.

Returns:

The axis along which the wavelengths are represented in the raw sensor image

inline std::vector<ListOrCoefficients> wavelengthCalibrations() const

Get all wavelength calibration information specified in the calibration file.

If the calibration file is not for a PushBroom camera this will throw an error.

Returns:

All wavelength calibration information specified in the calibration file

inline std::vector<ListOrCoefficients> fwhmCalibrations() const

Get all FWHM calibration information specified in the calibration file.

If the calibration file is not for a PushBroom camera this will throw an error.

Returns:

All FWHM calibration information specified in the calibration file

inline std::vector<ListOrCoefficients> nominalWavelengthLists() const

Get all nominal wavelength lists specified in the calibration file.

If the calibration file is not for a PushBroom camera this will throw an error.

Returns:

All nominal wavelength lists specified in the calibration file

inline std::vector<Coefficients2D> smileCorrections() const

Get all smile correction coefficients specified in the calibration file.

If the calibration file is not for a PushBroom camera this will throw an error.

Returns:

All smile correction coefficients specified in the calibration file

inline std::vector<Coefficients2D> keystoneCorrections() const

Get all keystone correction coefficients specified in the calibration file.

If the calibration file is not for a PushBroom camera this will throw an error.

Returns:

All keystone correction coefficients specified in the calibration file

inline std::vector<double> getEffectiveWavelengths(Handle &handle, ROIInput const &roi) const

Get the effective wavelengths of a raw image for a given ROI/binning setting.

If the calibration file is not for a PushBroom camera this will throw an error.

Parameters:

• handle – The fluxEngine handle

• roi – The selected ROI for which to obtain this information

Returns:

The list of effective wavelengths for that chosen ROI for each pixel along the spectral axis

inline std::vector<double> getEffectiveFWHM(Handle &handle, ROIInput const &roi) const

Get the effective FWHM of a raw image for a given ROI/binning setting.

If the calibration file is not for a PushBroom camera this will throw an error.

If the calibration file does not have FWHM information, this will throw an error.

Parameters:

• handle – The fluxEngine handle

• roi – The selected ROI for which to obtain this information

Returns:

The list of effective FWHM for that chosen ROI for each pixel along the spectral axis

inline std::vector<double> getEffectiveNominalWavelengths(Handle &handle, ROIInput const &roi) const

Get the nominal wavelength list of a raw image for a given ROI/binning setting.

If the calibration file is not for a PushBroom camera this will throw an error.

If the calibration file does not have nominal wavelength information, this will throw an error.

Parameters:

• handle – The fluxEngine handle

• roi – The selected ROI for which to obtain this information

Returns:

The list of effective nominal wavelengths for that chosen ROI. The list will in general not have the same size as the size of the spectral axis; but ROI will have an effect on which parts of the nominal wavelength list will be selected.

inline void getSmileMapInto(Handle &handle, ROIInput const &roi, std::uint64_t flags, MutableTensorData &map) const

Obtain a map of the smile shifts / absolute source coordinates for a given ROI/binning setting.

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 MapFlags for details on the possible flags.

If the calibration file is not for a PushBroom camera this will throw an error.

Parameters:

• handle – The fluxEngine handle

• roi – The selected ROI for which to obtain this information

• flags – Flags that influence the behavior of this method; see MapFlags for a list of possible flags. (This may be 0 to indicate that the default behavior is to be used.)

• map – A tensor that was pre-allocated by the user where to write the map into. This must be a tensor of order 2 with the 0th dimension being equal to the chosen ROI height, and the 1st dimension being equal to the chosen ROI width, and the data type must be either DataType::Float32 or DataType::Float64.

inline void getKeystoneMapInto(Handle &handle, ROIInput const &roi, std::uint64_t flags, MutableTensorData &map) const

Obtain a map of the keystone shifts / absolute source coordinates for a given ROI/binning setting.

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 MapFlags for details on the possible flags.

If the calibration file is not for a PushBroom camera this will throw an error.

Parameters:

• handle – The fluxEngine handle

• roi – The selected ROI for which to obtain this information

• flags – Flags that influence the behavior of this method; see MapFlags for a list of possible flags. (This may be 0 to indicate that the default behavior is to be used.)

• map – A tensor that was pre-allocated by the user where to write the map into. This must be a tensor of order 2 with the 0th dimension being equal to the chosen ROI height, and the 1st dimension being equal to the chosen ROI width, and the data type must be either DataType::Float32 or DataType::Float64.

inline void getXMapInto(Handle &handle, ROIInput const &roi, std::uint64_t flags, MutableTensorData &map) const

Obtain a map of the shifts / absolute source coordinates along the X axis for a given ROI/binning setting.

For each pixel in the target image, the X correction map determines the offset along the X 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 MapFlags for details on the possible flags.

This will be identical to either getSmileMapInto() or getKeystoneMapInto(), depending on whether the wavelength axis is in X or Y direction.

If the calibration file is not for a PushBroom camera this will throw an error.

Parameters:

• handle – The fluxEngine handle

• roi – The selected ROI for which to obtain this information

• flags – Flags that influence the behavior of this method; see MapFlags for a list of possible flags. (This may be 0 to indicate that the default behavior is to be used.)

• map – A tensor that was pre-allocated by the user where to write the map into. This must be a tensor of order 2 with the 0th dimension being equal to the chosen ROI height, and the 1st dimension being equal to the chosen ROI width, and the data type must be either DataType::Float32 or DataType::Float64.

inline void getYMapInto(Handle &handle, ROIInput const &roi, std::uint64_t flags, MutableTensorData &map) const

Obtain a map of the shifts / absolute source coordinates along the Y axis for a given ROI/binning setting.

For each pixel in the target image, the Y correction map determines the offset along the Y 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 MapFlags for details on the possible flags.

This will be identical to either getSmileMapInto() or getKeystoneMapInto(), depending on whether the wavelength axis is in X or Y direction.

If the calibration file is not for a PushBroom camera this will throw an error.

Parameters:

• handle – The fluxEngine handle

• roi – The selected ROI for which to obtain this information

• flags – Flags that influence the behavior of this method; see MapFlags for a list of possible flags. (This may be 0 to indicate that the default behavior is to be used.)

• map – A tensor that was pre-allocated by the user where to write the map into. This must be a tensor of order 2 with the 0th dimension being equal to the chosen ROI height, and the 1st dimension being equal to the chosen ROI width, and the data type must be either DataType::Float32 or DataType::Float64.

inline void applyCorrections(Handle &handle, ROIInput const &roi, std::uint64_t selectedCorrections, TensorData const &inputImage, MutableTensorData &outputImage) const

Apply camera corrections to a source image.

Apply all camera corrections selected in selectedCorrections to the provided source image. The corrected image will be written into the memory area provided by the user in outputImage.

If the calibration file is not for a PushBroom camera this will throw an error.

Parameters:

• handle – The fluxEngine handle

• roi – The selected ROI for which to perform the correction (i.e. the ROI with which the input image was obtained)

• selectedCorrections – Which corrections to apply to the input image. If 0 is supplied the input image is copied into the output image. Otherwise, any bitwise OR combination of the SelectedCorrections enumeration may be specified here.

• inputImage – The input image to correct. This may be of any data type supported by fluxEngine (it will automatically be converted internally if necessary), but it must be a tensor of order 2 with the 0th dimension being equal to the chosen ROI height, and the 1st dimension being equal to the chosen ROI width.

• outputImage – A tensor that was pre-allocated by the user where to write the corrected image into. This must be a tensor of order 2 with the 0th dimension being equal to the chosen ROI height, and the 1st dimension being equal to the chosen ROI width, and the data type must be either DataType::Float32 or DataType::Float64.

Public Static Functions

static inline CalibrationFile parse(Handle &handle, void const *contents, size_t contentsSizeBytes, ParserOptions const &options)

Parse a calibration file.

Parameters:

• handle – The fluxEngine handle

• contents – A pointer to the first byte of the calibration file contents

• contentsSizeBytes – The number of bytes that make up the calibration file

• options – Options that influence the parsing and validation process

Returns:

The parsed calibration file

struct Coefficients2D

2D Coefficients for Smile/Keystone Correction

This structure is returned when querying the smile/keystone correction coefficients specified in the calibration file.

Public Members

std::vector<double> coefficients

The coefficients.

A set of coefficients for a 2D polyonmial describing the relative coordinate shift in the direction for which these coefficients were returned

std::int64_t binningSpectral = {}

The spectral binning for which these coefficients are valid.

std::int64_t binningSpatial = {}

The spatial binning for which these coefficients are valid.

struct EffectiveActiveArea

The active area on the sensor.

This structure describes the active area of the sensor that is used to actually capture data. This may be less than the total size of the sensor, because the optics may not project onto the full sensor.

Public Members

std::int64_t offsetX = {}

The X offset (on the unbinned sensor image)

std::int64_t offsetY = {}

The Y offset (on the unbinned sensor image)

std::int64_t width = {}

The width (on the unbinned sensor image)

std::int64_t height = {}

The height (on the unbinned sensor image)

bool explicitlySpecified = {}

Whether the active area was explicitly specified.

If this is true the calibration file contained an explicit mention of the active area.

If this is false, offsetX and offsetY will be 0, and the width and height will correspond to the entire size of the sensor. (Implicit active area that covers the full sensor.)

(Note that an explicitly specified active area may still cover the entire sensor.)

struct ListOrCoefficients

1D List or Coefficients

This structure describes a 1D list of values, or a set of coefficients that may be used to generate a list of values.

The primary usage of this data structure is for the wavelength calibration of a PushBroom camera. Either this contains a list of values (the size of the active area of the sensor), or it contains a set of polyonmial coefficients that can be used to reconstruct this list.

Public Members

std::vector<double> list

Either the list of values, or the set of polynomial coefficients.

std::int64_t binning = {}

The binning factor (in spectral direction) for which this information is provided.

bool areCoefficients = {}

Whether the values in list are coefficients (true) or just individual values (false)

struct 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.

Public Members

std::int64_t sensorWidth = {}

The width of the entire sensor in pixels.

std::int64_t sensorHeight = {}

The height of the entire sensor in pixels.

std::vector<std::int64_t> binningHorizontalValues

The supported horizontal binning values.

If this is an empty array, it is assumed that there is only one horizontal binning that is supported, which is 1.

If the array is non-empty, an element with the value of 1 must be present.

std::vector<std::int64_t> binningVerticalValues

The supported vertical binning values.

If this is an empty array, it is assumed that there is only one vertical binning that is supported, which is 1.

If the array is non-empty, an element with the value of 1 must be present.

struct 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.

Public Members

std::int64_t binningHorizontal = {1}

The horizontal binning factor.

This must be a value supported by the sensor.

std::int64_t binningVertical = {1}

The vertical binning factor.

This must be a value supported by the sensor.

std::int64_t offsetX = {}

The offset X value of the ROI (applied to the binned active area) in pixels.

std::int64_t offsetY = {}

The offset Y value of the ROI (applied to the binned active area) in pixels.

std::int64_t width = {}

The width of the ROI (applied to the binned active area) in pixels.

std::int64_t height = {}

The height of the ROI (applied to the binned active area) in pixels.