Manual Access of Calibration Files

CalibrationFile

Note

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

class fluxEngine.CalibrationFile(handle, fileData, options)

A parsed calibration file

This functionality is typically only available with a specialized license.

Parameters:

  • handle (Handle) – The fluxEngine handle

  • fileData (bytes) – The contents of the calibration file

  • options (CalibrationFile.ParserOptions) – Options that influence the parsing and validation process

class CameraType(value)

The type of camera the calibration file describes

Currently only PushBroom cameras are supported.

PushBroom = 0

The file describes a PushBroom camera

Unknown = 1

The camera type is unknown

class Coefficients2D(coefficients, binningSpectral, binningSpatial)

2D Coefficients for Smile/Keystone Correction

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

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

Type:

list(float)

binningSpectral

The spectral binning for which these coefficients are valid

Type:

int

binningSpatial

The spatial binning for which these coefficients are valid

Type:

int

class EffectiveActiveArea(offsetX, offsetY, width, height, explicitlySpecified=True)

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.

offsetX

The X offset (on the unbinned sensor image)

Type:

int

offsetY

The Y offset (on the unbinned sensor image)

Type:

int

width

The width (on the unbinned sensor image)

Type:

int

height

The height (on the unbinned sensor image)

Type:

int

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

Type:

bool

class ListOrCoefficients(valuesOrCoefficients, binning, areCoefficients)

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.

valuesOrCoefficients

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

Type:

list(float)

binning

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

Type:

int

areCoefficients

Whether the values in list are coefficients (True) or just individual values (False)

Type:

bool

class MapFlag(value)

Flags that influence obtaining smile/keystone maps

AbsoluteCoordinates = 1

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.

class ParserOptions(sensorWidth, sensorHeight)

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.

sensorWidth

The width of the entire sensor in pixels

Type:

int

sensorHeight

The height of the entire sensor in pixels

Type:

int

binningHorizontalValues

The supported horizontal binning values

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

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

Type:

list(int)

binningVerticalValues

The supported vertical binning values

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

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

Type:

list(int)

Parameters:

  • sensorWidth (int) – The width of the entire sensor in pixels

  • sensorHeight (int) – The height of the entire sensor in pixels

class ROIInput(offsetX, offsetY, width, height)

Calibration File ROI Input

There are two types of query methods 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.

binningHorizontal

The horizontal binning factor

This must be a value supported by the sensor.

Type:

int

binningVertical

The vertical binning factor

This must be a value supported by the sensor.

Type:

int

offsetX

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

Type:

int

offsetY

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

Type:

int

width

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

Type:

int

height

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

Type:

int

class SelectedCorrection(value)

Selected corrections to apply

Keystone = 2

Enable Keystone correction

Smile = 1

Enable Smile correction

class WavelengthAxis(value)

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

X = 0

Wavelengths are along the X direction

Y = 1

Wavelengths are along the Y direction

activeArea()

Get the effective active area

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

Returns:

The effective active area

Return type:

CalibrationFile.EffectiveActiveArea

applyCorrections(handle, roi, selectedCorrections, inputImage)

Apply camera corrections to a source image

Apply all camera corrections selected in selectedCorrections to the provided source image. The corrected image will be returned to the user as a new numpy array.

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

Parameters:

  • handle (Handle) – The fluxEngine handle

  • roi (CalibrationFile.ROIInput) – The selected ROI for which to obtain this information

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

  • inputImage (numpay.array) – The input image to correct. This may be of any data type supported by fluxEngine (it will automatically be converted internally if necessary), but its shape must contain exactly 2 elements, the first being the chosen ROI height, and the second the chosen ROI width.

Returns:

The corrected image

Return type:

numpy.array

calibrationDataVersion()

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

Returns:

The calibration data version specified in the calibration file, or None, if none was.

Return type:

str or None

calibrationProcessVersion()

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

Returns:

The calibration process version specified in the calibration file, or None, if none was.

Return type:

str or None

cameraModel()

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

Returns:

The camera model specified in the calibration file, or None, if none was.

Return type:

str or None

cameraSerial()

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

Returns:

The camera serial number specified in the calibration file, or None, if none was.

Return type:

str or None

cameraType()

Get the camera type the calibration file was created for

Returns:

The camera type the calibration file was created for

Return type:

CalibrationFile.CameraType

fwhmCalibrations()

Get all FWHM calibration information specified in the calibration file

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

Returns:

All FWHM calibration information specified in the calibration file

Return type:

list(CalibrationFile.ListOrCoefficients)

getEffectiveFWHM(handle, roi)

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 raise an error.

Parameters:
Returns:

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

Return type:

list(float)

getEffectiveNominalWavelengths(handle, roi)

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 raise an error.

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

Parameters:
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 selected.

Return type:

list(float)

getEffectiveWavelengths(handle, roi)

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 raise an error.

Parameters:
Returns:

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

Return type:

list(float)

getKeystoneMap(handle, roi, flags)

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 the flags the resulting map will either contain relative offsets, or it will contain absolute coordinates. See MapFlag for details on the possible flags.

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

Parameters:

  • handle (Handle) – The fluxEngine handle

  • roi (CalibrationFile.ROIInput) – The selected ROI for which to obtain this information

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

Returns:

The requested map

Return type:

numpy.array

getSmileMap(handle, roi, flags)

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 the flags the resulting map will either contain relative offsets, or it will contain absolute coordinates. See MapFlag for details on the possible flags.

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

Parameters:

  • handle (Handle) – The fluxEngine handle

  • roi (CalibrationFile.ROIInput) – The selected ROI for which to obtain this information

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

Returns:

The requested map

Return type:

numpy.array

getXMap(handle, roi, flags)

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 the flags the resulting map will either contain relative offsets, or it will contain absolute coordinates. See MapFlag for details on the possible flags.

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

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

Parameters:

  • handle (Handle) – The fluxEngine handle

  • roi (CalibrationFile.ROIInput) – The selected ROI for which to obtain this information

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

Returns:

The requested map

Return type:

numpy.array

getYMap(handle, roi, flags)

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 the flags the resulting map will either contain relative offsets, or it will contain absolute coordinates. See MapFlag for details on the possible flags.

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

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

Parameters:

  • handle (Handle) – The fluxEngine handle

  • roi (CalibrationFile.ROIInput) – The selected ROI for which to obtain this information

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

Returns:

The requested map

Return type:

numpy.array

keystoneCalibrations()

Get all keystone correction coefficients specified in the calibration file

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

Returns:

All keystone correction coefficients specified in the calibration file

Return type:

list(CalibrationFile.Coefficients2D)

nominalWavelengthLists()

Get all nominal wavelength lists specified in the calibration file

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

Returns:

All nominal wavelength lists specified in the calibration file

Return type:

list(CalibrationFile.ListOrCoefficients)

opticsSerial()

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

Returns:

The optics serial number specified in the calibration file, or None, if none was.

Return type:

str or None

smileCalibrations()

Get all smile correction coefficients specified in the calibration file

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

Returns:

All smile correction coefficients specified in the calibration file

Return type:

list(CalibrationFile.Coefficients2D)

warnings()

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 constructor 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

Return type:

list(str)

wavelengthAxis()

Get the wavelength axis

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

Returns:

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

Return type:

CalibrationFile.WavelengthAxis

wavelengthCalibrations()

Get all wavelength calibration information specified in the calibration file

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

Returns:

All wavelength calibration information specified in the calibration file

Return type:

list(CalibrationFile.ListOrCoefficients)