Data Processing

ProcessingContext

typedef struct fluxEngine_C_v1_ProcessingContext fluxEngine_C_v1_ProcessingContext

Processing Context.

This opaque data structure describes a processing context.

DataType

enum fluxEngine_C_v1_DataType

A scalar data type.

This enumeration lists the supported scalar data types that may be used as input for HSI data, as well as the data types of the data that may be returned.

Values:

enumerator fluxEngine_C_v1_DataType_UInt8

8bit Unsigned Integer

enumerator fluxEngine_C_v1_DataType_UInt16

16bit Unsigned Integer

enumerator fluxEngine_C_v1_DataType_UInt32

32bit Unsigned Integer

enumerator fluxEngine_C_v1_DataType_UInt64

64bit Unsigned Integer

enumerator fluxEngine_C_v1_DataType_Int8

8bit Signed Integer

enumerator fluxEngine_C_v1_DataType_Int16

16bit Signed Integer

enumerator fluxEngine_C_v1_DataType_Int32

32bit Signed Integer

enumerator fluxEngine_C_v1_DataType_Int64

64bit Signed Integer

enumerator fluxEngine_C_v1_DataType_Float32

32bit Single Precision IEEE 754 Floating Point

enumerator fluxEngine_C_v1_DataType_Float64

64bit Double Precision IEEE 754 Floating Point

DataType_size

size_t fluxEngine_C_v1_DataType_size(fluxEngine_C_v1_DataType data_type)

Get the size of a data type (in bytes)

If an invalid type is supplied, this function will return 0.

Parameters:

• data_type – The data type

Returns:

The size of the data type (in bytes)

DataType_is_integer

bool fluxEngine_C_v1_DataType_is_integer(fluxEngine_C_v1_DataType data_type)

Is a given data type an integer?

If an invalid type is supplied, this function will return false.

Parameters:

• data_type – The data type

Returns:

Whether the data type is an integer or not

DataType_is_unsigned

bool fluxEngine_C_v1_DataType_is_unsigned(fluxEngine_C_v1_DataType data_type)

Is a given data type an unsigned integer?

If an invalid type is supplied, this function will return false.

Parameters:

• data_type – The data type

Returns:

Whether the data type is an unsigned integer or not

DataType_is_signed

bool fluxEngine_C_v1_DataType_is_signed(fluxEngine_C_v1_DataType data_type)

Is a given data type a signed integer?

If an invalid type is supplied, this function will return false.

Parameters:

• data_type – The data type

Returns:

Whether the data type is a signed integer or not

DataType_is_floating_point

bool fluxEngine_C_v1_DataType_is_floating_point(fluxEngine_C_v1_DataType data_type)

Is a given data type a floating point number?

If an invalid type is supplied, this function will return false.

Parameters:

• data_type – The data type

Returns:

Whether the data type is a floating point number or not

ValueType

enum fluxEngine_C_v1_ValueType

The value type of a given input.

Determines what form the data that is supplied by the user has.

Values:

enumerator fluxEngine_C_v1_ValueType_Intensity

Intensities.

The data supplied by the user are raw intensities. If the model is set to process reflectances and/or absorbances reference data must be provided before processing can occur.

enumerator fluxEngine_C_v1_ValueType_Reflectance

Reflectances.

The data supplied by the user are reflectances.

enumerator fluxEngine_C_v1_ValueType_RelativeRadiance

Relative Radiances.

The data supplied by the user are relative radiances, i.e. intensities that have some corrections applied to them, but are not absolute (physical) radiance values.

enumerator fluxEngine_C_v1_ValueType_Radiance

Radiances.

The data supplied by the user are intensities that describe the absolute radiance that entered the detector.

ReferenceInfo

struct fluxEngine_C_v1_ReferenceInfo

Information about references.

This information structure must be supplied when creating a processing context. It specifies the input value type of the processing context, as well as any references.

There are three primary ways to handle referencing of data:

• The source in the model is set to raw intensities, and raw intensities are supplied by the user for the input data of the model while processing. In that case any references provided will be ignored

• The source in the model is set to reflectances or absorbances, and the user provides reflectances for the input data of the model while processing. In that case any references provided will be ignored

• The source in the model is set to reflectances or absorbances, and the user provides raw intensities for the input data of the model while processing. In that case a white reference must be provided to automatically reference the input data, and optionally a dark reference may be provided.

When referencing input data, if only a white reference is provided, reflectances are calculated with the following formula:

reflectance = intensity / white

If a dark reference is also present, reflectances are calculated with the following formula:

reflectance = (intensity - dark) / (white - dark)

Public Members

fluxEngine_C_v1_ValueType value_type

The value type of the input data.

void const *white_reference

The white reference data.

This must be a tensor that is contiguous in memory that contains the white reference that will be used in conjunction with the input data.

Since it is advantageous to average multiple reference measurements, this tensor has to have an additional dimension to denote a list of input frames.

• For HSI cubes in BIP order, this means the dimensionality of this tensor has to be (N, height, width, bands).

• For HSI cubes in BIL order the dimensionality of the tensor has to be (N, height, bands, width)

• For HSI cubes in BSQ order the dimensionality of the tensor has to be (N, bands, height, width)

• For PushBoom frames in LambdaX order the dimensionality of the tensor has to be (N, width, bands)

• For PushBroom frames in LambdaY order the dimensionality of the tensor has to be (N, bands, width)

The number of averages, N, may be 1, indicating that no average is to be calculated.

int64_t white_reference_dimensions[5]

The dimensions of the white reference.

Not all elements may be used, depending on the order of the tensor that is required.

void const *dark_reference

The dark reference data.

int64_t dark_reference_dimensions[5]

The dimensions of the dark reference.

HSICube_StorageOrder

enum fluxEngine_C_v1_HSICube_StorageOrder

Hyperspectral data cube storage order.

Hyperspectral cubes consist of three dimensions, and the storage order defines how these dimensions are mapped into linear memory.

The introductory documentation also contains a visual depiction of the various storage orders of HSI cubes.

Values:

enumerator fluxEngine_C_v1_HSICube_StorageOrder_BIP

Band Interleaved by Pixel Storage Order.

In this storage order all wavelengths of each pixel are next to each other in memory. This means that the linear memory address of an element may be caluclated by the following formula (assuming the cube is contiguous in memory, see fluxEngine_ProcessingContext_set_source_data_hsi_cube_ex() for more complicated cases):

(y * width + x) * band_count + band_index

A cube stored in this storage order can be considered a row-major tensor of order 3 indexed as (y, x, band).

enumerator fluxEngine_C_v1_HSICube_StorageOrder_BIL

Band Interleaved by Line Storage Order.

In this storage order all pixels of a line are next to each other in memory, and wavelengths are grouped by line. This means that the linear memory address of an element may be by the following formula (assuming the cube is contiguous in memory, see fluxEngine_ProcessingContext_set_source_data_hsi_cube_ex() for more complicated cases):

(y * band_count + band_index) * width + x

A cube stored in this storage order can be considered a row-major tensor of order 3 indexed as (y, band, x).

enumerator fluxEngine_C_v1_HSICube_StorageOrder_BSQ

Band Sequential Storage Order.

In this storage order all pixels of an individual band are next to each other in memory, and wavelengths are grouped by image. This means that the linear memory address of an element may be by the following formula (assuming the cube is contiguous in memory, see fluxEngine_ProcessingContext_set_source_data_hsi_cube_ex() for more complicated cases):

(band_index * height + y) * width + x

A cube stored in this storage order can be considered a row-major tensor of order 3 indexed as (band, y, x).

ExtendedReferenceInfo

struct fluxEngine_C_v1_ExtendedReferenceInfo

Information about references (extended version)

This information structure must be supplied when creating a processing context. It specifies the input value type of the processing context, as well as any references.

There are five primary ways to handle referencing of data:

• The source in the model is set to raw intensities, and raw intensities (or relative radiances or radiances) are supplied by the user for the input data of the model while processing. In that case any references provided will be ignored

• The source in the model is set to reflectances or absorbances, and the user provides reflectances for the input data of the model while processing. In that case any references provided will be ignored

• The source in the model is set to reflectances or absorbances, and the user provides raw intensities (or relative radiances or radiances) for the input data of the model while processing. In that case a white reference must be provided to automatically reference the input data, and optionally a dark reference may be provided.

• The source in the model is set to raw intensities, but with the requirement of the data being illumination corrected, and raw intensities (or relative radiances or radiances) are supplied by the user for the input data of the model while processing. In that case an illumination reference must be provided to perform the illumination correction. (Any dark reference that is present will also be applied optionally.)

• The source in the model is set to raw intensities, but with the requirement of the data being illumination corrected, and raw intensities (or relative radiances or radiances) are supplied by the user for the input data of the model while processing, but the intensities are already illumination corrected. In that case any references provided will be ignored.

When converting from intensities (or radiances) to reflectances (or absorbances), if only a white reference is provided, reflectances are calculated with the following formula:

reflectance = intensity / white

If a dark reference is also present, reflectances are calculated with the following formula:

reflectance = (intensity - dark) / (white - dark)

When performing the illumination correction, the corrected intensities will be calculated by

corrected = intensity * avg_illumination / illumination

or

corrected = (intensity = dark) * (avg_illumination - avg_dark) / (illumination - dark)

depending on whether a dark reference is also supplied or not. avg_illumination is the illumination reference averaged over all wavelengths / channels (but not averaged over the spatial direction).

To use the API properly, the user should initialize the structure via

fluxEngine_C_v1_ExtendedReferenceInfo info; memset(&info, 0, sizeof(info)); input.structure_size = sizeof(info);

and then set the corresponding field values. This ensures future compatibility of the code in both API and ABI.

ContextInputDataInfo

struct fluxEngine_C_v1_ContextInputDataInfo

Context Input Data Info.

This structure contains information about the input data when creating a processing context.

To use the API properly, the user should initialize the structure via

fluxEngine_C_v1_ContextInputDataInfo info; memset(&info, 0, sizeof(info)); input.structure_size = sizeof(info);

and then set the corresponding field values. This ensures future compatibility of the code in both API and ABI.

ProcessingContext_create_hsi_cube

int fluxEngine_C_v1_ProcessingContext_create_hsi_cube(fluxEngine_C_v1_Model *model, fluxEngine_C_v1_HSICube_StorageOrder storage_order, fluxEngine_C_v1_DataType data_type, int64_t max_height, int64_t height, int64_t max_width, int64_t width, double const *wavelengths, size_t wavelength_count, fluxEngine_C_v1_ReferenceInfo const *reference_info, fluxEngine_C_v1_ProcessingContext **context, fluxEngine_C_v1_Error **error)

Create a new processing context for HSI cubes.

This function creates a new processing context that may be used to process HSI data cubes. The context may be used to process multiple cubes, as long as they have the same structure.

The cube will be processed as a whole, and depending on the complexity of the model a lot of temporary storage may be required to store all the intermediate processing results.

The following information must be known in advance to properly setup a fluxEngine processing context that can be used to process this type of HSI data:

• The scalar data type

• The storage order of the data in memory

• The wavelengths

• The maximum spatial dimensions that will be processed with this context

The user may choose to process cubes of the same size, or cubes of varying sizes. In the case of cubes that all have the same size, the user should specify the same value for both max_height and height, and for max_width and width, respectively. In the case the cube sizes vary, the user should specify -1 for both height and width, and specify the size of the largest cube they will ever want to process in max_height and max_width.

Larger values for max_height and max_width will lead to more RAM being required to fully process the data.

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_LicenseDongleRemoved

• fluxEngine_C_v1_ErrorCode_LicenseDeviceNotConnected

• fluxEngine_C_v1_ErrorCode_ModelNoLongerValid

• fluxEngine_C_v1_ErrorCode_ModelWrongSourceType

• fluxEngine_C_v1_ErrorCode_InputDimensionError

• fluxEngine_C_v1_ErrorCode_InputWavelengthValueError

• fluxEngine_C_v1_ErrorCode_FilterCreationError

• fluxEngine_C_v1_ErrorCode_WavelengthRangeDeterminationError

• fluxEngine_C_v1_ErrorCode_WhiteReferenceMissingError

• fluxEngine_C_v1_ErrorCode_WhiteReferenceDimensionError

• fluxEngine_C_v1_ErrorCode_DarkReferenceDimensionError

• fluxEngine_C_v1_ErrorCode_PreprocessingSetupError

• fluxEngine_C_v1_ErrorCode_ProcessingSetupError

Parameters:

• model – The model to create the processing context for

• storage_order – The storage order the input data will have when it is supplied to the processing context

• data_type – The scalar data type of the input data when it is supplied to the processing context

• max_height – The maximum height of a cube that will be processed using this context

• height – Specify -1 here to leave the cube height dynamic (which might not be as efficient at runtime for some models), or the same value as maxHeight to fix the height and indicate it will always be the same for every cube that is being processed.

• max_width – The maximum width of a cube that will be processed using this context

• width – Specify -1 here to leave the cube width dynamic (which might not be as efficient at runtime for some models), or the same value as maxWidth to fix the width and indicate it will always be the same for every cube that is being processed.

• wavelengths – A C array of wavelengths, stored as double precision floating point numbers, in the unit of nanometers.

• wavelength_count – The number of wavelengths.

• reference_info – How the data should be referenced

• context – [out] The resulting processing context

• 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

ProcessingContext_create_hsi_cube_pqs

int fluxEngine_C_v1_ProcessingContext_create_hsi_cube_pqs(fluxEngine_C_v1_Model *model, fluxEngine_C_v1_ProcessingQueueSet *processing_queue_set, fluxEngine_C_v1_HSICube_StorageOrder storage_order, fluxEngine_C_v1_DataType data_type, int64_t max_height, int64_t height, int64_t max_width, int64_t width, double const *wavelengths, size_t wavelength_count, fluxEngine_C_v1_ReferenceInfo const *reference_info, fluxEngine_C_v1_ProcessingContext **context, fluxEngine_C_v1_Error **error)

Create a new processing context for HSI cubes.

This function is identical in behavior to fluxEngine_C_v1_ProcessingContext_create_hsi_cube(), but allows the user to specify a processing queue set to create the context in. If processing_queue_set is NULL, it will use the default processing queue set of the handle, which is identical to calling fluxEngine_C_v1_ProcessingContext_create_hsi_cube() directly.

The handle of the processing queue set (if supplied) must match the handle of the model.

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_LicenseDongleRemoved

• fluxEngine_C_v1_ErrorCode_LicenseDeviceNotConnected

• fluxEngine_C_v1_ErrorCode_ModelNoLongerValid

• fluxEngine_C_v1_ErrorCode_ModelWrongSourceType

• fluxEngine_C_v1_ErrorCode_InputDimensionError

• fluxEngine_C_v1_ErrorCode_InputWavelengthValueError

• fluxEngine_C_v1_ErrorCode_FilterCreationError

• fluxEngine_C_v1_ErrorCode_WavelengthRangeDeterminationError

• fluxEngine_C_v1_ErrorCode_WhiteReferenceMissingError

• fluxEngine_C_v1_ErrorCode_WhiteReferenceDimensionError

• fluxEngine_C_v1_ErrorCode_DarkReferenceDimensionError

• fluxEngine_C_v1_ErrorCode_PreprocessingSetupError

• fluxEngine_C_v1_ErrorCode_ProcessingSetupError

Parameters:

• model – The model to create the processing context for

• processing_queue_set – The processing queue set to use

• storage_order – The storage order the input data will have when it is supplied to the processing context

• data_type – The scalar data type of the input data when it is supplied to the processing context

• max_height – The maximum height of a cube that will be processed using this context

• height – Specify -1 here to leave the cube height dynamic (which might not be as efficient at runtime for some models), or the same value as maxHeight to fix the height and indicate it will always be the same for every cube that is being processed.

• max_width – The maximum width of a cube that will be processed using this context

• width – Specify -1 here to leave the cube width dynamic (which might not be as efficient at runtime for some models), or the same value as maxWidth to fix the width and indicate it will always be the same for every cube that is being processed.

• wavelengths – A C array of wavelengths, stored as double precision floating point numbers, in the unit of nanometers.

• wavelength_count – The number of wavelengths.

• reference_info – How the data should be referenced

• context – [out] The resulting processing context

• 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

ProcessingContext_create_hsi_cube_calib

int fluxEngine_C_v1_ProcessingContext_create_hsi_cube_calib(fluxEngine_C_v1_Model *model, fluxEngine_C_v1_ProcessingQueueSet *processing_queue_set, fluxEngine_C_v1_HSICube_StorageOrder storage_order, fluxEngine_C_v1_DataType data_type, int64_t max_height, int64_t height, int64_t max_width, int64_t width, double const *wavelengths, size_t wavelength_count, fluxEngine_C_v1_ReferenceInfo const *reference_info, struct fluxEngine_C_v1_CalibrationInfo const *calibration_info, fluxEngine_C_v1_ProcessingContext **context, fluxEngine_C_v1_Error **error)

Create a new processing context for HSI cubes.

This function is identical in behavior to fluxEngine_C_v1_ProcessingContext_create_hsi_cube(), but allows the user to specify a processing queue set to create the context in, as well as specify calibration information of the source data. If processing_queue_set is NULL, it will use the default processing queue set of the handle. If calibration_info is NULL, no calibration information will be assumed for the source data.

The handle of the processing queue set (if supplied) must match the handle of the model.

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_LicenseDongleRemoved

• fluxEngine_C_v1_ErrorCode_LicenseDeviceNotConnected

• fluxEngine_C_v1_ErrorCode_ModelNoLongerValid

• fluxEngine_C_v1_ErrorCode_ModelWrongSourceType

• fluxEngine_C_v1_ErrorCode_InputDimensionError

• fluxEngine_C_v1_ErrorCode_InputWavelengthValueError

• fluxEngine_C_v1_ErrorCode_FilterCreationError

• fluxEngine_C_v1_ErrorCode_WavelengthRangeDeterminationError

• fluxEngine_C_v1_ErrorCode_WhiteReferenceMissingError

• fluxEngine_C_v1_ErrorCode_WhiteReferenceDimensionError

• fluxEngine_C_v1_ErrorCode_DarkReferenceDimensionError

• fluxEngine_C_v1_ErrorCode_PreprocessingSetupError

• fluxEngine_C_v1_ErrorCode_ProcessingSetupError

Parameters:

• model – The model to create the processing context for

• processing_queue_set – The processing queue set to use

• storage_order – The storage order the input data will have when it is supplied to the processing context

• data_type – The scalar data type of the input data when it is supplied to the processing context

• max_height – The maximum height of a cube that will be processed using this context

• height – Specify -1 here to leave the cube height dynamic (which might not be as efficient at runtime for some models), or the same value as maxHeight to fix the height and indicate it will always be the same for every cube that is being processed.

• max_width – The maximum width of a cube that will be processed using this context

• width – Specify -1 here to leave the cube width dynamic (which might not be as efficient at runtime for some models), or the same value as maxWidth to fix the width and indicate it will always be the same for every cube that is being processed.

• wavelengths – A C array of wavelengths, stored as double precision floating point numbers, in the unit of nanometers.

• wavelength_count – The number of wavelengths.

• reference_info – How the data should be referenced

• calibration_info – The calibration information to apply to the processing context

• context – [out] The resulting processing context

• 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

ProcessingContext_create_hsi_cube_ext

int fluxEngine_C_v1_ProcessingContext_create_hsi_cube_ext(fluxEngine_C_v1_Model *model, fluxEngine_C_v1_ProcessingQueueSet *processing_queue_set, fluxEngine_C_v1_HSICube_StorageOrder storage_order, fluxEngine_C_v1_DataType data_type, int64_t max_height, int64_t height, int64_t max_width, int64_t width, double const *wavelengths, size_t wavelength_count, fluxEngine_C_v1_ContextInputDataInfo const *info, fluxEngine_C_v1_ProcessingContext **context, fluxEngine_C_v1_Error **error)

Create a new processing context for HSI cubes.

This function is identical in behavior to fluxEngine_C_v1_ProcessingContext_create_hsi_cube(), but allows the user to specify a processing queue set to create the context in, as well as specify extended reference and calibration information of the source data. If processing_queue_set is NULL, it will use the default processing queue set of the handle.

The handle of the processing queue set (if supplied) must match the handle of the model.

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_LicenseDongleRemoved

• fluxEngine_C_v1_ErrorCode_LicenseDeviceNotConnected

• fluxEngine_C_v1_ErrorCode_ModelNoLongerValid

• fluxEngine_C_v1_ErrorCode_ModelWrongSourceType

• fluxEngine_C_v1_ErrorCode_InputDimensionError

• fluxEngine_C_v1_ErrorCode_InputWavelengthValueError

• fluxEngine_C_v1_ErrorCode_FilterCreationError

• fluxEngine_C_v1_ErrorCode_WavelengthRangeDeterminationError

• fluxEngine_C_v1_ErrorCode_WhiteReferenceMissingError

• fluxEngine_C_v1_ErrorCode_WhiteReferenceDimensionError

• fluxEngine_C_v1_ErrorCode_DarkReferenceDimensionError

• fluxEngine_C_v1_ErrorCode_PreprocessingSetupError

• fluxEngine_C_v1_ErrorCode_ProcessingSetupError

Parameters:

• model – The model to create the processing context for

• processing_queue_set – The processing queue set to use

• storage_order – The storage order the input data will have when it is supplied to the processing context

• data_type – The scalar data type of the input data when it is supplied to the processing context

• max_height – The maximum height of a cube that will be processed using this context

• height – Specify -1 here to leave the cube height dynamic (which might not be as efficient at runtime for some models), or the same value as maxHeight to fix the height and indicate it will always be the same for every cube that is being processed.

• max_width – The maximum width of a cube that will be processed using this context

• width – Specify -1 here to leave the cube width dynamic (which might not be as efficient at runtime for some models), or the same value as maxWidth to fix the width and indicate it will always be the same for every cube that is being processed.

• wavelengths – A C array of wavelengths, stored as double precision floating point numbers, in the unit of nanometers.

• wavelength_count – The number of wavelengths.

• info – Information about the value type of the input data, and optionally any references and calibration information.

• context – [out] The resulting processing context

• 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

PushBroomFrame_StorageOrder

enum fluxEngine_C_v1_PushBroomFrame_StorageOrder

Hyperspectral PushBroom frame storage order.

A PushBroom camera is a hyperspectral camera that uses a 2D sensor to image a single line, where the optics project different wavelengths of the incoming light onto one of the sensor dimensions. The other sensor dimension is used to spatially resolve the line that is being imaged.

There are two possible orientations of the optics: the wavelengths could be mapped onto the x- or the y-direction of the camera sensor. This enumeration allows the user to select which of these storage orders is actually used.

Values:

enumerator fluxEngine_C_v1_PushBroomFrame_StorageOrder_LambdaX

Wavelengths are in X-direction.

The y direction of the frame contains the spatial information.

enumerator fluxEngine_C_v1_PushBroomFrame_StorageOrder_LambdaY

Wavelengths are in Y-direction.

The x direction of the frame contains the spatial information.

ProcessingContext_create_pushbroom_frame

int fluxEngine_C_v1_ProcessingContext_create_pushbroom_frame(fluxEngine_C_v1_Model *model, fluxEngine_C_v1_PushBroomFrame_StorageOrder storage_order, fluxEngine_C_v1_DataType data_type, int64_t width, double const *wavelengths, size_t wavelength_count, fluxEngine_C_v1_ReferenceInfo const *reference_info, fluxEngine_C_v1_ProcessingContext **context, fluxEngine_C_v1_Error **error)

Create a new processing context for PushBroom frames.

This function creates a new processing context that may be used to sequentially process PushBroom frames. Each consecutive frame is considered to be part of a stream of lines that in principle could be used to construct a cube if concatenated.

The following information must be known in advance to properly setup a fluxEngine processing context that can be used to process this type of HSI data:

• The scalar data type

• The storage order of the data in memory

• The wavelengths

• The exact spatial dimension that will be processed with this context; as PushBroom frames should be able to be concatenated, the size of the frame may not be variable, but the number of frames being processed may vary

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_LicenseDongleRemoved

• fluxEngine_C_v1_ErrorCode_LicenseDeviceNotConnected

• fluxEngine_C_v1_ErrorCode_ModelNoLongerValid

• fluxEngine_C_v1_ErrorCode_ModelWrongSourceType

• fluxEngine_C_v1_ErrorCode_InputDimensionError

• fluxEngine_C_v1_ErrorCode_InputWavelengthValueError

• fluxEngine_C_v1_ErrorCode_FilterCreationError

• fluxEngine_C_v1_ErrorCode_WavelengthRangeDeterminationError

• fluxEngine_C_v1_ErrorCode_WhiteReferenceMissingError

• fluxEngine_C_v1_ErrorCode_WhiteReferenceDimensionError

• fluxEngine_C_v1_ErrorCode_DarkReferenceDimensionError

• fluxEngine_C_v1_ErrorCode_PreprocessingSetupError

• fluxEngine_C_v1_ErrorCode_ProcessingSetupError

Parameters:

• model – The model to create the processing context for

• storage_order – The storage order the input data will have when it is supplied to the processing context

• data_type – The scalar data type of the input data when it is supplied to the processing context

• width – The spatial dimension of each PushBroom frame that is supplied (if the storage order indicates that wavelengths are across the x direction of the frame, this indicates the size of the frame in the y direction, and vice-versa)

• wavelengths – A C array of wavelengths, stored as double precision floating point numbers, in the unit of nanometers.

• wavelength_count – The number of wavelengths.

• reference_info – How the data should be referenced

• context – [out] The resulting processing context

• 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

ProcessingContext_create_pushbroom_frame_pqs

int fluxEngine_C_v1_ProcessingContext_create_pushbroom_frame_pqs(fluxEngine_C_v1_Model *model, fluxEngine_C_v1_ProcessingQueueSet *processing_queue_set, fluxEngine_C_v1_PushBroomFrame_StorageOrder storage_order, fluxEngine_C_v1_DataType data_type, int64_t width, double const *wavelengths, size_t wavelength_count, fluxEngine_C_v1_ReferenceInfo const *reference_info, fluxEngine_C_v1_ProcessingContext **context, fluxEngine_C_v1_Error **error)

Create a new processing context for PushBroom frames.

This function is identical in behavior to fluxEngine_C_v1_ProcessingContext_create_pushbroom_frame(), but allows the user to specify a processing queue set to create the context in. If processing_queue_set is NULL, it will use the default processing queue set of the handle, which is identical to calling fluxEngine_C_v1_ProcessingContext_create_pushbroom_frame() directly.

The handle of the processing queue set (if supplied) must match the handle of the model.

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_LicenseDongleRemoved

• fluxEngine_C_v1_ErrorCode_LicenseDeviceNotConnected

• fluxEngine_C_v1_ErrorCode_ModelNoLongerValid

• fluxEngine_C_v1_ErrorCode_ModelWrongSourceType

• fluxEngine_C_v1_ErrorCode_InputDimensionError

• fluxEngine_C_v1_ErrorCode_InputWavelengthValueError

• fluxEngine_C_v1_ErrorCode_FilterCreationError

• fluxEngine_C_v1_ErrorCode_WavelengthRangeDeterminationError

• fluxEngine_C_v1_ErrorCode_WhiteReferenceMissingError

• fluxEngine_C_v1_ErrorCode_WhiteReferenceDimensionError

• fluxEngine_C_v1_ErrorCode_DarkReferenceDimensionError

• fluxEngine_C_v1_ErrorCode_PreprocessingSetupError

• fluxEngine_C_v1_ErrorCode_ProcessingSetupError

Parameters:

• model – The model to create the processing context for

• processing_queue_set – The processing queue set to use

• storage_order – The storage order the input data will have when it is supplied to the processing context

• data_type – The scalar data type of the input data when it is supplied to the processing context

• width – The spatial dimension of each PushBroom frame that is supplied (if the storage order indicates that wavelengths are across the x direction of the frame, this indicates the size of the frame in the y direction, and vice-versa)

• wavelengths – A C array of wavelengths, stored as double precision floating point numbers, in the unit of nanometers.

• wavelength_count – The number of wavelengths.

• reference_info – How the data should be referenced

• context – [out] The resulting processing context

• 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

ProcessingContext_create_pushbroom_frame_calib

int fluxEngine_C_v1_ProcessingContext_create_pushbroom_frame_calib(fluxEngine_C_v1_Model *model, fluxEngine_C_v1_ProcessingQueueSet *processing_queue_set, fluxEngine_C_v1_PushBroomFrame_StorageOrder storage_order, fluxEngine_C_v1_DataType data_type, int64_t width, double const *wavelengths, size_t wavelength_count, fluxEngine_C_v1_ReferenceInfo const *reference_info, struct fluxEngine_C_v1_CalibrationInfo const *calibration_info, fluxEngine_C_v1_ProcessingContext **context, fluxEngine_C_v1_Error **error)

Create a new processing context for PushBroom frames.

This function is identical in behavior to fluxEngine_C_v1_ProcessingContext_create_pushbroom_frame(), but allows the user to specify a processing queue set to create the context in, as well as specify calibration information of the source data. If processing_queue_set is NULL, it will use the default processing queue set of the handle. If calibration_info is NULL, no calibration information will be assumed for the source data.

The handle of the processing queue set (if supplied) must match the handle of the model.

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_LicenseDongleRemoved

• fluxEngine_C_v1_ErrorCode_LicenseDeviceNotConnected

• fluxEngine_C_v1_ErrorCode_ModelNoLongerValid

• fluxEngine_C_v1_ErrorCode_ModelWrongSourceType

• fluxEngine_C_v1_ErrorCode_InputDimensionError

• fluxEngine_C_v1_ErrorCode_InputWavelengthValueError

• fluxEngine_C_v1_ErrorCode_FilterCreationError

• fluxEngine_C_v1_ErrorCode_WavelengthRangeDeterminationError

• fluxEngine_C_v1_ErrorCode_WhiteReferenceMissingError

• fluxEngine_C_v1_ErrorCode_WhiteReferenceDimensionError

• fluxEngine_C_v1_ErrorCode_DarkReferenceDimensionError

• fluxEngine_C_v1_ErrorCode_PreprocessingSetupError

• fluxEngine_C_v1_ErrorCode_ProcessingSetupError

Parameters:

• model – The model to create the processing context for

• processing_queue_set – The processing queue set to use

• storage_order – The storage order the input data will have when it is supplied to the processing context

• data_type – The scalar data type of the input data when it is supplied to the processing context

• width – The spatial dimension of each PushBroom frame that is supplied (if the storage order indicates that wavelengths are across the x direction of the frame, this indicates the size of the frame in the y direction, and vice-versa)

• wavelengths – A C array of wavelengths, stored as double precision floating point numbers, in the unit of nanometers.

• wavelength_count – The number of wavelengths.

• reference_info – How the data should be referenced

• calibration_info – The calibration information of the input data

• context – [out] The resulting processing context

• 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

ProcessingContext_create_pushbroom_frame_ext

int fluxEngine_C_v1_ProcessingContext_create_pushbroom_frame_ext(fluxEngine_C_v1_Model *model, fluxEngine_C_v1_ProcessingQueueSet *processing_queue_set, fluxEngine_C_v1_PushBroomFrame_StorageOrder storage_order, fluxEngine_C_v1_DataType data_type, int64_t width, double const *wavelengths, size_t wavelength_count, fluxEngine_C_v1_ContextInputDataInfo const *info, fluxEngine_C_v1_ProcessingContext **context, fluxEngine_C_v1_Error **error)

Create a new processing context for PushBroom frames.

This function is identical in behavior to fluxEngine_C_v1_ProcessingContext_create_pushbroom_frame(), but allows the user to specify a processing queue set to create the context in, as well as specify extended reference and calibration information of the source data. If processing_queue_set is NULL, it will use the default processing queue set of the handle.

The handle of the processing queue set (if supplied) must match the handle of the model.

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_LicenseDongleRemoved

• fluxEngine_C_v1_ErrorCode_LicenseDeviceNotConnected

• fluxEngine_C_v1_ErrorCode_ModelNoLongerValid

• fluxEngine_C_v1_ErrorCode_ModelWrongSourceType

• fluxEngine_C_v1_ErrorCode_InputDimensionError

• fluxEngine_C_v1_ErrorCode_InputWavelengthValueError

• fluxEngine_C_v1_ErrorCode_FilterCreationError

• fluxEngine_C_v1_ErrorCode_WavelengthRangeDeterminationError

• fluxEngine_C_v1_ErrorCode_WhiteReferenceMissingError

• fluxEngine_C_v1_ErrorCode_WhiteReferenceDimensionError

• fluxEngine_C_v1_ErrorCode_DarkReferenceDimensionError

• fluxEngine_C_v1_ErrorCode_PreprocessingSetupError

• fluxEngine_C_v1_ErrorCode_ProcessingSetupError

Parameters:

• model – The model to create the processing context for

• processing_queue_set – The processing queue set to use

• storage_order – The storage order the input data will have when it is supplied to the processing context

• data_type – The scalar data type of the input data when it is supplied to the processing context

• width – The spatial dimension of each PushBroom frame that is supplied (if the storage order indicates that wavelengths are across the x direction of the frame, this indicates the size of the frame in the y direction, and vice-versa)

• wavelengths – A C array of wavelengths, stored as double precision floating point numbers, in the unit of nanometers.

• wavelength_count – The number of wavelengths.

• info – Information about the value type of the input data, and optionally any references and calibration information.

• context – [out] The resulting processing context

• 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

ProcessingContext_set_use_extended_objects

int fluxEngine_C_v1_ProcessingContext_set_use_extended_objects(fluxEngine_C_v1_ProcessingContext *context, bool use_extended, fluxEngine_C_v1_Error **error)

Alter a processing context: set use of extended objects.

Objects may be returned in two different manners: either via the fluxEngine_C_v1_OutputObject structure (default) or the fluxEngine_C_v1_OutputExtendedObject structure. This function controls which variant is to be used.

This setting may only be changed while processing is currently not active on this context. Changing this setting may take a bit of processing time. Ideally it should be done immediately after the context has been created and then not changed anymore.

Parameters:

• context – The processing context for which to list the output sinks

• use_extended – Whether extended objects are to be returned (true), of the standard objects are (false).

• 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

ProcessingContext_num_output_sinks

int fluxEngine_C_v1_ProcessingContext_num_output_sinks(fluxEngine_C_v1_ProcessingContext *context, fluxEngine_C_v1_Error **error)

Obtain the number of output sinks in the model.

To retrieve data that has been processed via fluxEngine the designer of the model must add output sinks to the places where data is to be extracted.

This function returns the number of output sinks within the given model. This may be used to iterate over the output sinks and determine their data structure given the input data structure that is supplied.

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_ProcessingContextNoLongerValid

Parameters:

• context – The processing context for which to list the output sinks

• 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:

The number of output sinks on success, -1 on failure

ProcessingContext_find_output_sink

int fluxEngine_C_v1_ProcessingContext_find_output_sink(fluxEngine_C_v1_ProcessingContext *context, int output_id, fluxEngine_C_v1_Error **error)

Find the output sink with a given output id.

If there is exactly one output sink in the model with a given output id, this will return the index of that sink. If there are no output sinks with that id, or that output id is used multiple times, this will return an error.

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_ProcessingContextNoLongerValid

• fluxEngine_C_v1_ErrorCode_OutputIdNotPresent

• fluxEngine_C_v1_ErrorCode_OutputIdNotUnique

Parameters:

• context – The processing context for which to list the output sinks

• output_id – The output_id of the output sink

• 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:

The index of the output sink (that may be used as a sink_index for other calls) on success, -1 on failure

OutputStorageType

enum fluxEngine_C_v1_OutputStorageType

The storage type of data at a given output sink.

When extracting data from fluxEngine, the data at a given output sink may be stored in different formats. This enumeration describes the possible formats the data is stored in. Please refer to the introductory information for a more detailed introduction on how data is returned from processing, and what kind of forms it may take.

Values:

enumerator fluxEngine_C_v1_OutputStorageType_Tensor

Tensor data.

This is the most common case, where data at the end of processing is available as a tensor. For HSI data tensors will typically be of order 3, having a y dimension, x dimension and an additional dimension for e.g. spectral (wavelength) information.

enumerator fluxEngine_C_v1_OutputStorageType_ObjectList

Object list.

A list of objects that is stored as an array of fluxEngine_C_v1_OutputObject objects.

ProcessingContext_get_output_sink_meta_info

int fluxEngine_C_v1_ProcessingContext_get_output_sink_meta_info(fluxEngine_C_v1_ProcessingContext *context, int sink_index, int *output_id, char **name, fluxEngine_C_v1_OutputStorageType *output_storage_type, int64_t *input_delay, fluxEngine_C_v1_Error **error)

Obtain meta information about a given output sink.

For a given output sink index that ranges between 0 and one less than the value returned by fluxEngine_C_v1_ProcessingContext_num_output_sinks(), this function will return meta information about the output sink.

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_ProcessingContextNoLongerValid

• fluxEngine_C_v1_ErrorCode_IndexOutOfRange

Parameters:

• context – The processing context for which to introspect the output sink

• sink_index – The index of the output sink to introspect

• output_id – [out] The output id that is set for the the sink. This is purely for informational purposes

• name – [out] The name of the output sink will be stored here; the result must be freed with fluxEngine_C_v1_string_free(). If NULL is provided here, no name will be returned.

• output_storage_type – [out] The storage type of the data at this output sink

• input_delay – [out] The delay of this output sink relative to the input data given. See the advanced topics section of the documentation for more details.

• 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

ProcessingContext_get_output_sink_tensor_structure

int fluxEngine_C_v1_ProcessingContext_get_output_sink_tensor_structure(fluxEngine_C_v1_ProcessingContext *context, int sink_index, fluxEngine_C_v1_DataType *data_type, int *order, int64_t max_sizes[5], int64_t fixed_sizes[5], fluxEngine_C_v1_Error **error)

Obtain information about the tensor structure of a given output sink.

For an output sink with data of tensor type (see fluxEngine_C_v1_OutputStorageType_Tensor for details), this function will return the tensor structure of the data that will be returned via the output sink.

If the storage type does not match, this function will return an error.

Please see the documentation for fluxEngine_C_v1_ProcessingContext_get_output_sink_data() for more information how to process tensor data.

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_ProcessingContextNoLongerValid

• fluxEngine_C_v1_ErrorCode_IndexOutOfRange

• fluxEngine_C_v1_ErrorCode_ProcessingContextTypeMismatch

See also

fluxEngine_C_v1_ProcessingContext_get_output_sink_data

Parameters:

• context – The processing context for which to introspect the output sink

• sink_index – The index of the output sink to introspect

• data_type – [out] The data type of the data returned by the sink

• order – [out] The order of the tensor that is being returned. This will typically be 2 or 3.

• max_sizes – [out] The maximum dimensions of the tensor that may be returned. Only elements up to order are filled in, the rest will be 0.

• fixed_sizes – [out] For each dimension within the order of the tensor, the entry here may either be -1 to indicate that that dimension is variable, or the same value as the corresponding entry in maxSizes to indicate that the dimension is static and will always be the same

• 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

ProcessingContext_get_output_sink_object_list_structure

int fluxEngine_C_v1_ProcessingContext_get_output_sink_object_list_structure(fluxEngine_C_v1_ProcessingContext *context, int sink_index, int64_t *max_object_count, int64_t *additional_data_size, fluxEngine_C_v1_DataType *additional_data_type, fluxEngine_C_v1_Error **error)

Obtain information about the object structure of a given output sink.

For any output sink with data of object list type (see fluxEngine_C_v1_OutputStorageType_ObjectList for details), this function will return information about the object list that is returned.

This function may always be called on output sinks that return objects, regardless of whether extended objects are to be returned or not.

If the storage type does not match, this function will return an error.

Please see the documentation for fluxEngine_C_v1_ProcessingContext_get_output_sink_data() for more information how to process object list data.

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_ProcessingContextNoLongerValid

• fluxEngine_C_v1_ErrorCode_IndexOutOfRange

• fluxEngine_C_v1_ErrorCode_ProcessingContextTypeMismatch

See also

fluxEngine_C_v1_ProcessingContext_get_output_sink_data

Parameters:

• context – The processing context for which to introspect the output sink

• sink_index – The index of the output sink to introspect

• max_object_count – [out] The maximum number of objects that will be returned after a single execution

• additional_data_size – [out] The number of additional data entries present per object (may be 0 to indicate no additional data is present)

• additional_data_type – [out] The scalar type of the additional data entries per object

• 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

ProcessingContext_get_output_sink_object_list_statistics_structure_count

int fluxEngine_C_v1_ProcessingContext_get_output_sink_object_list_statistics_structure_count(fluxEngine_C_v1_ProcessingContext *context, int sink_index, size_t *count, fluxEngine_C_v1_Error **error)

Get the number of statistics data associated with this object.

For any output sink with data of object list type (see fluxEngine_C_v1_OutputStorageType_ObjectList), this function will return the number of statistics data that will be returned for each object.

The count returned here corresponds to the number of per-object statistics filters the user has placed in the chain before the output sink that is being queried.

If the output sink does not have any statistics data associated with it at all, this function will still succeed, but set the parameter count to 0.

Use fluxEngine_C_v1_ProcessingContext_get_output_sink_object_list_statistics_structure_ex() to query information about specific statistics data.

If the storage type does not match (the output sink does not return objects), this function will return an error.

Please see the documentation for fluxEngine_C_v1_ProcessingContext_get_output_sink_data() for more information how to process object list data.

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_ProcessingContextNoLongerValid

• fluxEngine_C_v1_ErrorCode_IndexOutOfRange

• fluxEngine_C_v1_ErrorCode_ProcessingContextTypeMismatch

See also

fluxEngine_C_v1_ProcessingContext_get_output_sink_data

Parameters:

• context – The processing context for which to introspect the output sink

• sink_index – The index of the output sink to introspect

• count – [out] The number of different statistics data associated with this object output

• 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 statistics data is present, 0 if it is not, -1 on failure

ProcessingContext_get_output_sink_object_list_statistics_structure

int fluxEngine_C_v1_ProcessingContext_get_output_sink_object_list_statistics_structure(fluxEngine_C_v1_ProcessingContext *context, int sink_index, fluxEngine_C_v1_DataType *data_type, int *order, int64_t dimensions[5], fluxEngine_C_v1_Error **error)

Obtain information about the structure of the first statistics data associated with objects returned by a given output sink.

For any output sink with data of object list type (see fluxEngine_C_v1_OutputStorageType_ObjectList) that also carries statistics data, this function will return information about the first statistics data that is returned. (Statistics data is only returned if use of the extended object structure is active.)

If no statistics data is present, this will return 0 and not fill any of the output parameters.

If statistics data is present, this will return 1 and fill the corresponding output parameters.

If multiple different statistics data are present, this will return the information for the first statistics data present in the object. Use fluxEngine_C_v1_ProcessingContext_get_output_sink_object_list_statistics_structure_count() and fluxEngine_C_v1_ProcessingContext_get_output_sink_object_list_statistics_structure_ex() to obtain information when more than one statistics data is present.

If the storage type does not match (the output sink does not return objects), this function will return an error.

Please see the documentation for fluxEngine_C_v1_ProcessingContext_get_output_sink_data() for more information how to process object list data.

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_ProcessingContextNoLongerValid

• fluxEngine_C_v1_ErrorCode_IndexOutOfRange

• fluxEngine_C_v1_ErrorCode_ProcessingContextTypeMismatch

See also

fluxEngine_C_v1_ProcessingContext_get_output_sink_data

Parameters:

• context – The processing context for which to introspect the output sink

• sink_index – The index of the output sink to introspect

• data_type – [out] The data type of the statistics data, this will either be fluxEngine_C_v1_DataType_Float32 or fluxEngine_C_v1_DataType_Float64.

• order – [out] The tensor order of the statistics data. This will typically be 1, but may differ.

• dimensions – [out] The dimensions of the statistics data. Only the dimensions up to order will have valid 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:

1 if statistics data is present, 0 if it is not, -1 on failure

ProcessingContext_get_output_sink_object_list_statistics_structure_ex

int fluxEngine_C_v1_ProcessingContext_get_output_sink_object_list_statistics_structure_ex(fluxEngine_C_v1_ProcessingContext *context, int sink_index, size_t statistics_index, char **prefix, fluxEngine_C_v1_DataType *data_type, int *order, int64_t dimensions[5], fluxEngine_C_v1_Error **error)

Obtain information about the structure of a specific set of statistics data associated with objects returned by a given output sink.

For any output sink with data of object list type (see fluxEngine_C_v1_OutputStorageType_ObjectList) that also carries statistics data, this function will return information about the statistics data with index statistics_index that is returned. (Statistics data is only returned if use of the extended object structure is active.)

Use fluxEngine_C_v1_ProcessingContext_get_output_sink_object_list_statistics_structure_count() to obtain the number of different statistics data first before calling this method. If statistics_index is out of range (for example because there are no statistics data available for the object at all), this method will fail.

If the storage type does not match (the output sink does not return objects), this function will return an error.

Please see the documentation for fluxEngine_C_v1_ProcessingContext_get_output_sink_data() for more information how to process object list data.

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_ProcessingContextNoLongerValid

• fluxEngine_C_v1_ErrorCode_IndexOutOfRange

• fluxEngine_C_v1_ErrorCode_ProcessingContextTypeMismatch

See also

fluxEngine_C_v1_ProcessingContext_get_output_sink_data

Parameters:

• context – The processing context for which to introspect the output sink

• sink_index – The index of the output sink to introspect

• statistics_index – The index of the statistics data (must be at least 0, and at most one less than the value returned by fluxEngine_C_v1_ProcessingContext_get_output_sink_object_list_statistics_structure_count())

• prefix – [out] The prefix of the statistics data that the user specified in their model. This string must be freed by fluxEngine_C_v1_string_free().

• data_type – [out] The data type of the statistics data, this will either be fluxEngine_C_v1_DataType_Float32 or fluxEngine_C_v1_DataType_Float64.

• order – [out] The tensor order of the statistics data. This will typically be 1, but may differ.

• dimensions – [out] The dimensions of the statistics data. Only the dimensions up to order will have valid 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

ProcessingContext_get_output_sink_object_list_region_count

int fluxEngine_C_v1_ProcessingContext_get_output_sink_object_list_region_count(fluxEngine_C_v1_ProcessingContext *context, int sink_index, size_t *count, fluxEngine_C_v1_Error **error)

Get the number of regions associated with this object.

For any output sink with data of object list type (see fluxEngine_C_v1_OutputStorageType_ObjectList), this function will return the number of regions that will be returned for each object.

The count returned here corresponds to the regions defined by any object region averaging filter the user has placed in the chain before the output sink that is being queried.

If the output sink does not have any regions associated with it at all, this function will still succeed, but set the parameter count to 0.

Use fluxEngine_C_v1_ProcessingContext_get_output_sink_object_list_region_structure() to query information about specific regions.

If the storage type does not match (the output sink does not return objects), this function will return an error.

Please see the documentation for fluxEngine_C_v1_ProcessingContext_get_output_sink_data() for more information how to process object list data.

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_ProcessingContextNoLongerValid

• fluxEngine_C_v1_ErrorCode_IndexOutOfRange

• fluxEngine_C_v1_ErrorCode_ProcessingContextTypeMismatch

See also

fluxEngine_C_v1_ProcessingContext_get_output_sink_data

Parameters:

• context – The processing context for which to introspect the output sink

• sink_index – The index of the output sink to introspect

• count – [out] The number of different regions associated with this object output

• 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 statistics data is present, 0 if it is not, -1 on failure

ProcessingContext_get_output_sink_object_list_region_structure

int fluxEngine_C_v1_ProcessingContext_get_output_sink_object_list_region_structure(fluxEngine_C_v1_ProcessingContext *context, int sink_index, size_t region_index, char **prefix, char **name, fluxEngine_C_v1_DataType *data_type, int *order, int64_t dimensions[5], fluxEngine_C_v1_Error **error)

Obtain information about the structure of a specific region associated with objects returned by a given output sink.

For any output sink with data of object list type (see fluxEngine_C_v1_OutputStorageType_ObjectList) that also carries regions, this function will return information about the region with index region_index that is returned. (Region data is only returned if use of the extended object structure is active.)

Use fluxEngine_C_v1_ProcessingContext_get_output_sink_object_list_region_count() to obtain the number of different regions first before calling this method. If region_index is out of range (for example because there are no statistics data available for the object at all), this method will fail.

If the storage type does not match (the output sink does not return objects), this function will return an error.

Please see the documentation for fluxEngine_C_v1_ProcessingContext_get_output_sink_data() for more information how to process object list data.

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_ProcessingContextNoLongerValid

• fluxEngine_C_v1_ErrorCode_IndexOutOfRange

• fluxEngine_C_v1_ErrorCode_ProcessingContextTypeMismatch

See also

fluxEngine_C_v1_ProcessingContext_get_output_sink_data

Parameters:

• context – The processing context for which to introspect the output sink

• sink_index – The index of the output sink to introspect

• region_index – The index of the region (must be at least 0, and at most one less than the value returned by fluxEngine_C_v1_ProcessingContext_get_output_sink_object_list_region_count())

• prefix – [out] The string describing the prefix of the region. At the moment this will always return an empty string, but exists for future expansion. This string must always be freed with fluxEngine_C_v1_string_free().

• name – [out] The name of the region the user has specified when defining the regions. This string must always be freed with fluxEngine_C_v1_string_free().

• data_type – [out] The data type of the region’s average

• order – [out] The order of the region’s average (this will typically be 1)

• dimensions – [out] The dimensions of the region’s average; only the first order entries will be filled by this function

• 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

ProcessingContext_get_output_sink_object_list_region_channel_labels

int fluxEngine_C_v1_ProcessingContext_get_output_sink_object_list_region_channel_labels(fluxEngine_C_v1_ProcessingContext *context, int sink_index, size_t region_index, double **labels, size_t *count, fluxEngine_C_v1_Error **error)

Obtain information about the channel labels of a specific set of statistics data associated with objects returned by a given output sink.

For any output sink with data of object list type (see fluxEngine_C_v1_OutputStorageType_ObjectList) that also carries regions, this function will return channel labels of the averages for the region with index region_index. (Region data is only returned if use of the extended object structure is active.)

Use fluxEngine_C_v1_ProcessingContext_get_output_sink_object_list_region_count() to obtain the number of different regions first before calling this method. If region_index is out of range (for example because there are no statistics data available for the object at all), this method will fail.

If the storage type does not match (the output sink does not return objects), this function will return an error.

Please see the documentation for fluxEngine_C_v1_ProcessingContext_get_output_sink_data() for more information how to process object list data.

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_ProcessingContextNoLongerValid

• fluxEngine_C_v1_ErrorCode_IndexOutOfRange

• fluxEngine_C_v1_ErrorCode_ProcessingContextTypeMismatch

See also

fluxEngine_C_v1_ProcessingContext_get_output_sink_data

Parameters:

• context – The processing context for which to introspect the output sink

• sink_index – The index of the output sink to introspect

• region_index – The index of the region (must be at least 0, and at most one less than the value returned by fluxEngine_C_v1_ProcessingContext_get_output_sink_object_list_region_count())

• labels – [out] The resulting labels. This may be NULL if count is returned as 0. If not it must be freed by fluxEngine_C_v1_wavelengths_free().

• count – [out] The resulting number of labels

• 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

ProcessingContext_get_output_sink_object_list_quality_structure

int fluxEngine_C_v1_ProcessingContext_get_output_sink_object_list_quality_structure(fluxEngine_C_v1_ProcessingContext *context, int sink_index, fluxEngine_C_v1_DataType *data_type, int64_t *count, fluxEngine_C_v1_Error **error)

Obtain information about the structure of the quality data associated with objects returned by a given output sink.

For any output sink with data of object list type (see fluxEngine_C_v1_OutputStorageType_ObjectList) that also carries quality data, this function will return information about the quality data that is returned. (Quality data is only returned if use of the extended object structure is active.)

If no quality data is present, this will return 0 and not fill any of the output parameters.

If quality data is present, this will return 1 and fill the corresponding output parameters.

If the storage type does not match (the output sink does not return objects), this function will return an error.

Please see the documentation for fluxEngine_C_v1_ProcessingContext_get_output_sink_data() for more information how to process object list data.

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_ProcessingContextNoLongerValid

• fluxEngine_C_v1_ErrorCode_IndexOutOfRange

• fluxEngine_C_v1_ErrorCode_ProcessingContextTypeMismatch

See also

fluxEngine_C_v1_ProcessingContext_get_output_sink_data

Parameters:

• context – The processing context for which to introspect the output sink

• sink_index – The index of the output sink to introspect

• data_type – [out] The data type of the quality data. This will be an integer data type, but the specific integer type will depend on the model.

• count – [out] The number of quality entries. Quality data will always be a tensor of order 1, i.e. a vector.

• 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 statistics data is present, 0 if it is not, -1 on failure

ProcessingContext_set_source_data_hsi_cube

int fluxEngine_C_v1_ProcessingContext_set_source_data_hsi_cube(fluxEngine_C_v1_ProcessingContext *context, int64_t height, int64_t width, void const *data, fluxEngine_C_v1_Error **error)

Set the next input data to be processed (HSI cube)

Set the next input data that should be processed by fluxEngine. The user must supply a pointer to a memory region that contains the input data stored contiguously in memory. (For non-contiguously stored data the user may use the alternative fluxEngine_C_v1_ProcessingContext_set_source_data_hsi_cube_ex().)

The user must ensure that the memory region that contains the input data is not altered while fluxEngine_C_v1_ProcessingContext_process_next() is active. (It may be altered after setting it here and before calling it though, as long as the dimensions don’t change.)

If the input cube size was fixed during the creation of the processing context, the height and width parameters must match the height and width specified during creation of the context, or an error will be thrown.

If the input cube size was variable during the creation of the processing context, the height and width parameters must be smaller than or equal to the maximum size specified during the creation of the context.

The storage order of the cube that has been specified during the creation of the processing context will be used. This means that the height and width parameters may refer to different dimensions of the cube depending on the storage order:

• For a BIP cube, the cube will be indexed via (y, x, band), meaning the height parameter referes to the dimension 0, the width parameter to dimension 1 and the wavelength count supplied during creation of the cube to the dimension 2 of the cube.

• For a BIL cube, the cube will be indexed via (y, band, x), meaning the height parameter referes to the dimension 0, the width parameter to dimension 2 and the wavelength count supplied during creation of the cube to the dimension 1 of the cube.

• For a BSQ cube, the cube will be indexed via (band, y, x), meaning the height parameter referes to the dimension 1, the width parameter to dimension 2 and the wavelength count supplied during creation of the cube to the dimension 0 of the cube.

Between calls to fluxEngine_C_v1_ProcessingContext_process_next() this function may be used to change the source data region that is to be used during the next processing call.

If the processing context was not set up to process HSI cubes (e.g. because it was set up to process PushBroom frames), 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_LicenseDongleRemoved

• fluxEngine_C_v1_ErrorCode_LicenseDeviceNotConnected

• fluxEngine_C_v1_ErrorCode_ProcessingContextNoLongerValid

• fluxEngine_C_v1_ErrorCode_ProcessingContextTypeMismatch

• fluxEngine_C_v1_ErrorCode_InputDimensionError

Parameters:

• context – The processing context for which to set the source data region

• height – The height of the HSI cube to process

• width – The width of the HSI cube to process

• data – A pointer to a region of memory that contains the HSI cube stored contiguously, and must be of size width * height * band_count * scalar_size in bytes.

• 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

ProcessingContext_set_source_data_hsi_cube_ex

int fluxEngine_C_v1_ProcessingContext_set_source_data_hsi_cube_ex(fluxEngine_C_v1_ProcessingContext *context, int64_t height, int64_t width, int64_t stride1, int64_t stride2, void const *data, fluxEngine_C_v1_Error **error)

Set the next input data to be processed (HSI cube, non-contiguous)

This is an extended version of the fluxEngine_C_v1_ProcessingContext_set_source_data_hsi_cube() function. Please see the documentation of that function for details that do not pertain to the strides.

It is possible to lay out cubes non-contiguously in memory. For example, take a 2x2x2 cube with the following 8 elements:

cube(0, 0, 0) = 0
cube(0, 0, 1) = 1
cube(0, 1, 0) = 2
cube(0, 1, 1) = 3
cube(1, 0, 0) = 4
cube(1, 0, 1) = 5
cube(1, 1, 0) = 6
cube(1, 1, 1) = 7

When layed out contiguously in memory, the cube will have the following structure:

 dimension 2
(increment by 1)   dimension 0
  +---+          (increment by 4)
  |   |       +---------------+
  |   |       |               |
  |   v       |               v
+---+---+---+---+---+---+---+---+
| 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 |
+---+---+---+---+---+---+---+---+
  |       ^
  |       |
  +-------+
 dimension 1
(increment by 2)

To increment dimension 2 (the inner-most dimension) the element pointer must be incremented by 1. To increment dimension 1 (the middle dimension) the element pointer must be incremented by 2. To increment dimension 0 (the outer-most dimension) the element pointer has to be incremented by 4.

For cubes that reside contiguously in memory the increments here are always given by the dimensions of the cube. For example, a contiguous cube of dimensions (A, B, C) will have a stride structure of (B * C, C, 1).

However, it is possible that the cube is not contiguous in memory. In the above example, the stride structure for the contiguous cube was (4, 2, 1) due to the size of the cube - but if the stride structure is chosen as (9, 3, 1) the memory layout of the cube would look differently:

 dimension 2
(increment by 1)   dimension 0
  +---+          (increment by 9)
  |   |       +-----------------------------------+
  |   |       |                                   |
  |   v       |                                   v
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
| 0 | 1 | _ | 2 | 3 | _ | _ | _ | _ | 4 | 5 | _ | 6 | 7 |
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
  |           ^
  |           |
  +-----------+
 dimension 1
(increment by 3)

For the HSI cube that is passed to this method, it will have the stride structure (stride1, stride2, 1).

As an example, if the cube is contiguous in memory (and fluxEngine_C_v1_ProcessingContext_set_source_data_hsi_cube() could have been used instead), the following stride structure is assumed:

• For contiguous BIP cubes (dimensions (y, x, band)) stride1 would be width * band_count, stride2 would be band_count.

• For contiguous BIP cubes (dimensions (y, band, x)) stride1 would be band_count * width, stride2 would be width.

• For contiguous BSQ cubes (dimensions (band, y, x)) stride1 would be height * width, stride2 would be width.

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_LicenseDongleRemoved

• fluxEngine_C_v1_ErrorCode_LicenseDeviceNotConnected

• fluxEngine_C_v1_ErrorCode_ProcessingContextNoLongerValid

• fluxEngine_C_v1_ErrorCode_ProcessingContextTypeMismatch

• fluxEngine_C_v1_ErrorCode_InputDimensionError

• fluxEngine_C_v1_ErrorCode_InputStrideError

Parameters:

• context – The processing context for which to set the source data region

• height – The height of the HSI cube to process

• width – The width of the HSI cube to process

• stride1 – The number of scalar elements to skip to increment the left-most dimension of the cube by 1

• stride2 – The number of scalar elements to skip to increment the middle dimension of the cube by 1

• data – A pointer to a region of memory that contains the HSI cube, and must be of size height * stride1 * scalar_size (BIP and BIL storage orders) or band_count * stride1 * scalar_size (BSQ storage order) in bytes

• 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

ProcessingContext_set_source_data_pushbroom_frame

int fluxEngine_C_v1_ProcessingContext_set_source_data_pushbroom_frame(fluxEngine_C_v1_ProcessingContext *context, void const *data, fluxEngine_C_v1_Error **error)

Set the next input data to be processed (PushBroom frame)

Set the next input data that should be processed by fluxEngine. The user must supply a pointer to a memory region that contains the input data stored contiguously in memory. (For non-contiguously stored data the user may use the alternative fluxEngine_C_v1_ProcessingContext_set_source_data_pushbroom_frame_ex().)

The user must ensure that the memory region that contains the input data is not altered while fluxEngine_C_v1_ProcessingContext_process_next() is active. (It may be altered after setting it here and before calling it though, as long as the dimensions don’t change.)

The input PushBroom frame size had to be fixed during the creation of the processing context, and the size of the frame must be equal to width and band_count.

The storage order of the cube that has been specified during the creation of the processing context will be used. The supplied frame must be a 2D image with the following dimensions:

• For LambdaX storage order, the width of the image must be equal to the wavelength count specified during the creation of the processing context, while the height of the image must be equal to the specified spatial width.

• For LambdaY storage order, the height of the image must be equal to the wavelength count specified during the creation of the processing context, while the width of the image must be equal to the specified spatial width.

Between calls to fluxEngine_C_v1_ProcessingContext_process_next() this function may be used to change the source data region that is to be used during the next processing call.

If the processing context was not set up to process PushBroom frames (e.g. because it was set up to process HSI cubes), 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_LicenseDongleRemoved

• fluxEngine_C_v1_ErrorCode_LicenseDeviceNotConnected

• fluxEngine_C_v1_ErrorCode_ProcessingContextNoLongerValid

• fluxEngine_C_v1_ErrorCode_ProcessingContextTypeMismatch

Parameters:

• context – The processing context for which to set the source data region

• data – A pointer to a region of memory that contains the PushBroom frame stored contiguously, and must be of size width * band_count * scalar_size in bytes.

• 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

ProcessingContext_set_source_data_pushbroom_frame_seqid

int fluxEngine_C_v1_ProcessingContext_set_source_data_pushbroom_frame_seqid(fluxEngine_C_v1_ProcessingContext *context, void const *data, int64_t sequence_id, fluxEngine_C_v1_Error **error)

Set the next input data to be processed (PushBroom frame, manual sequence id specification)

This is an extended version of the fluxEngine_C_v1_ProcessingContext_set_source_data_pushbroom_frame() function. Please see the documentation of that function for details that do not pertain to sequence id handling.

This function allows the user to specify the sequence id to use for the pushbroom frame. The sequence id is a number that has to increase between individual frames that are being processed. In an ideal world the sequence id will be incremented by 1 between each frame that is being processed. If the sequence id increases by more than one, the processing logic assumes that frames have been skipped (because they were lost, for example), and will act accordingly.

If the sequence id increases by a large amount between frames (on the order of 100) the processing logic may implicitly reset any internal state that it keeps between frames.

Supplying a sequence id that is lower than a previous sequence id may lead to undefined results.

When supplying data through either fluxEngine_C_v1_ProcessingContext_set_source_data_pushbroom_frame_ex() or fluxEngine_C_v1_ProcessingContext_set_source_data_pushbroom_frame() the sequence id of the data is considered to be one after the last used sequence id (starting at 0 for the first sequence id after context creation or a reset).

If a negative number is specified for the sequence id, it is assumed that the user wants to have the same behavior as fluxEngine_C_v1_ProcessingContext_set_source_data_pushbroom_frame() and the last used sequence id plus 1 will be used as the sequence id for the data that was supplied here.

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_LicenseDongleRemoved

• fluxEngine_C_v1_ErrorCode_LicenseDeviceNotConnected

• fluxEngine_C_v1_ErrorCode_ProcessingContextNoLongerValid

• fluxEngine_C_v1_ErrorCode_ProcessingContextTypeMismatch

• fluxEngine_C_v1_ErrorCode_InputStrideError

Parameters:

• context – The processing context for which to set the source data region

• data – A pointer to a region of memory that contains the PushBroom frame, and must be of size stride * band_count * scalar_size (LambdaY case) or stride * width * scalar_size (LambdaX case) in bytes.

• sequence_id – The sequence id of the data provided

• 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

ProcessingContext_set_source_data_pushbroom_frame_ex

int fluxEngine_C_v1_ProcessingContext_set_source_data_pushbroom_frame_ex(fluxEngine_C_v1_ProcessingContext *context, int64_t stride, void const *data, fluxEngine_C_v1_Error **error)

Set the next input data to be processed (PushBroom frame, non-contiguous)

This is an extended version of the fluxEngine_C_v1_ProcessingContext_set_source_data_pushbroom_frame() function. Please see the documentation of that function for details that do not pertain to the strides.

An image may be layed out non-contiguously in memory. For example, take a 2x2 image with the following data:

image(y = 0, x = 0) = 0
image(y = 0, x = 1) = 1
image(y = 1, x = 0) = 2
image(y = 1, x = 1) = 3

This will have the following contiguous representation in memory:

 dimension 1
(increment by 1)
  +---+
  |   |
  |   |
  |   v
+---+---+---+---+
| 0 | 1 | 2 | 3 |
+---+---+---+---+
  |       ^
  |       |
  +-------+
 dimension 0
(increment by 2)

However, the memory may also be stored non-contiguously. For example, if 3 scalar elements are to be skipped whenever the y dimension of the image is incremented, the layout would look like this:

 dimension 1
(increment by 1)
  +---+
  |   |
  |   |
  |   v
+---+---+---+---+---+
| 0 | 1 | _ | 2 | 3 |
+---+---+---+---+---+
  |           ^
  |           |
  +-----------+
 dimension 0
(increment by 3)

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_LicenseDongleRemoved

• fluxEngine_C_v1_ErrorCode_LicenseDeviceNotConnected

• fluxEngine_C_v1_ErrorCode_ProcessingContextNoLongerValid

• fluxEngine_C_v1_ErrorCode_ProcessingContextTypeMismatch

• fluxEngine_C_v1_ErrorCode_InputStrideError

Parameters:

• context – The processing context for which to set the source data region

• data – A pointer to a region of memory that contains the PushBroom frame, and must be of size stride * band_count * scalar_size (LambdaY case) or stride * width * scalar_size (LambdaX case) in bytes.

• stride – The number of scalar elements to skip to get to the next line within the PushBroom frame

• 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

ProcessingContext_set_source_data_pushbroom_frame_ex_seqid

int fluxEngine_C_v1_ProcessingContext_set_source_data_pushbroom_frame_ex_seqid(fluxEngine_C_v1_ProcessingContext *context, int64_t stride, void const *data, int64_t sequence_id, fluxEngine_C_v1_Error **error)

Set the next input data to be processed (PushBroom frame, non-contiguous, manual sequence id specification)

This is an extended version of the fluxEngine_C_v1_ProcessingContext_set_source_data_pushbroom_frame_ex() function. Please see the documentation of that function for details that do not pertain to sequence id handling.

This function allows the user to specify the sequence id to use for the pushbroom frame. The sequence id is a number that has to increase between individual frames that are being processed. In an ideal world the sequence id will be incremented by 1 between each frame that is being processed. If the sequence id increases by more than one, the processing logic assumes that frames have been skipped (because they were lost, for example), and will act accordingly.

If the sequence id increases by a large amount between frames (on the order of 100) the processing logic may implicitly reset any internal state that it keeps between frames.

Supplying a sequence id that is lower than a previous sequence id may lead to undefined results.

When supplying data through either fluxEngine_C_v1_ProcessingContext_set_source_data_pushbroom_frame_ex() or fluxEngine_C_v1_ProcessingContext_set_source_data_pushbroom_frame() the sequence id of the data is considered to be one after the last used sequence id (starting at 0 for the first sequence id after context creation or a reset).

If a negative number is specified for the sequence id, it is assumed that the user wants to have the same behavior as fluxEngine_C_v1_ProcessingContext_set_source_data_pushbroom_frame_ex() and the last used sequence id plus 1 will be used as the sequence id for the data that was supplied here.

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_LicenseDongleRemoved

• fluxEngine_C_v1_ErrorCode_LicenseDeviceNotConnected

• fluxEngine_C_v1_ErrorCode_ProcessingContextNoLongerValid

• fluxEngine_C_v1_ErrorCode_ProcessingContextTypeMismatch

• fluxEngine_C_v1_ErrorCode_InputStrideError

Parameters:

• context – The processing context for which to set the source data region

• data – A pointer to a region of memory that contains the PushBroom frame, and must be of size stride * band_count * scalar_size (LambdaY case) or stride * width * scalar_size (LambdaX case) in bytes.

• stride – The number of scalar elements to skip to get to the next line within the PushBroom frame

• sequence_id – The sequence id of the data provided

• 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

ProcessingContext_set_source_data_tensor

int fluxEngine_C_v1_ProcessingContext_set_source_data_tensor(fluxEngine_C_v1_ProcessingContext *context, fluxEngine_C_v1_DataType data_type, int order, int64_t dimensions[5], int64_t strides[5], void const *data, fluxEngine_C_v1_Error **error)

Set the next input data to be processed (tensor)

Set the next input data that should be processed by fluxEngine. The user must supply a pointer to a memory region that contains the input data. This function variant requires the user to also supply tensor metadata for the data region they are providing. The medata is checked against what the context expects, and if it doesn’t match, an error occurrs.

The user must ensure that the memory region that contains the input data is not altered while fluxEngine_C_v1_ProcessingContext_process_next() is active. (It may be altered after setting it here and before calling fluxEngine_C_v1_ProcessingContext_process_next() again though, as long as the dimensions don’t change.)

Parameters:

• context – The processing context for which to set the source data region

• data_type – The data type of the tensor

• order – The order of the tensor

• dimensions – The dimensions of the tensor (only the first order elements will be accessed)

• strides – The strides of the tensor (only the first order elements will be accessed)

• data – A pointer to the data region containing the tensor

• 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

ProcessingContext_set_source_data_tensor_seqid

int fluxEngine_C_v1_ProcessingContext_set_source_data_tensor_seqid(fluxEngine_C_v1_ProcessingContext *context, fluxEngine_C_v1_DataType data_type, int order, int64_t dimensions[5], int64_t strides[5], void const *data, int64_t sequence_id, fluxEngine_C_v1_Error **error)

Set the next input data to be processed (tensor, manual sequence id specification)

This is an extended version of the fluxEngine_C_v1_ProcessingContext_set_source_data_tensor() function. Please see the documentation of that function for details that do not pertain to sequence id handling.

This function allows the user to specify the sequence id to use for the input data. The sequence id is a number that has to increase between individual input block that are being processed. In an ideal world the sequence id will be incremented by 1 between each block that is being processed. If the sequence id increases by more than one, the processing logic assumes that blocks have been skipped (because they were lost, for example), and will act accordingly.

If the sequence id increases by a large amount between blocks (on the order of 100) the processing logic may implicitly reset any internal state that it keeps between blocks.

Supplying a sequence id that is lower than a previous sequence id may lead to undefined results.

When supplying data through fluxEngine_C_v1_ProcessingContext_set_source_data_tensor() the sequence id of the data is considered to be one after the last used sequence id (starting at 0 for the first sequence id after context creation or a reset).

If a negative number is specified for the sequence id, it is assumed that the user wants to have the same behavior as fluxEngine_C_v1_ProcessingContext_set_source_data_tensor() and the last used sequence id plus 1 will be used as the sequence id for the data that was supplied here.

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_LicenseDongleRemoved

• fluxEngine_C_v1_ErrorCode_LicenseDeviceNotConnected

• fluxEngine_C_v1_ErrorCode_ProcessingContextNoLongerValid

• fluxEngine_C_v1_ErrorCode_ProcessingContextTypeMismatch

• fluxEngine_C_v1_ErrorCode_InputStrideError

Parameters:

• context – The processing context for which to set the source data region

• data_type – The data type of the tensor

• order – The order of the tensor

• dimensions – The dimensions of the tensor (only the first order elements will be accessed)

• strides – The strides of the tensor (only the first order elements will be accessed)

• data – A pointer to the data region containing the tensor

• sequence_id – The sequence id of the data provided

• 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

ProcessingContext_process_next

int fluxEngine_C_v1_ProcessingContext_process_next(fluxEngine_C_v1_ProcessingContext *context, fluxEngine_C_v1_Error **error)

Process the next piece of data.

Processes the next piece of data. The source data must have previously been set via one of the following functions:

• fluxEngine_C_v1_ProcessingContext_set_source_data_hsi_cube()

• fluxEngine_C_v1_ProcessingContext_set_source_data_hsi_cube_ex()

• fluxEngine_C_v1_ProcessingContext_set_source_data_pushbroom_frame()

• fluxEngine_C_v1_ProcessingContext_set_source_data_pushbroom_frame_ex()

This method will return once processing of the current data has completed or an error has occurred. The current thread will be used as the thread 0 for parallelization purposes.

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_LicenseDongleRemoved

• fluxEngine_C_v1_ErrorCode_LicenseDeviceNotConnected

• fluxEngine_C_v1_ErrorCode_ProcessingContextNoLongerValid

• fluxEngine_C_v1_ErrorCode_ProcessingSourceDataMissing

• fluxEngine_C_v1_ErrorCode_ProcessingUnknownError

• fluxEngine_C_v1_ErrorCode_ProcessingInternalError

• fluxEngine_C_v1_ErrorCode_ProcessingAborted

Parameters:

• context – The processing context to use

• 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

ProcessingContext_reset_state

int fluxEngine_C_v1_ProcessingContext_reset_state(fluxEngine_C_v1_ProcessingContext *context, fluxEngine_C_v1_Error **error)

Reset the state of the processing context.

This function may only be called in between calls of fluxEngine_C_v1_ProcessingContext_process_next().

When the data to be processed is in the form of entire HSI cubes, that is, the context was created via the fluxEngine_C_v1_ProcessingContext_create_hsi_cube() function, this function will have no effect. (Unless processing was aborted via fluxEngine_C_v1_ProcessingContext_abort(), in which case this must be called to clean up the state.)

When the data to be processed is in the form of consecutive PushBroom frames, that is, the context was created via the fluxEngine_C_v1_ProcessingContext_create_pushbroom_frame() function, this function will reset the internal state and make the context appear as if it had been freshly created. This means that any operation that remembers past state to gain spatial information in the y direction will be reset to the beginning. This affects mostly object-based operations.

This would typically be called when a system with a PushBroom camera is started up again after a pause, and the previously processed data has no direct relation to the data to be processed from this point onwards.

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_ProcessingContextNoLongerValid

Parameters:

• context – The processing context to use

• 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

ProcessingContext_clear_source_data

int fluxEngine_C_v1_ProcessingContext_clear_source_data(fluxEngine_C_v1_ProcessingContext *context, fluxEngine_C_v1_Error **error)

Clear the source data from the processing context.

This function may only be called in between calls of fluxEngine_C_v1_ProcessingContext_process_next().

The input data of the processing context will be reset, so that any reference to the previously set input data is lost. If the user calls fluxEngine_C_v1_ProcessingContext_process_next() immediately after a call to this function, the processing call will fail in the same manner as if context had just been created.

This method is useful to ensure that the processing context will never in the future attempt to touch memory that was previously set as source data (because that memory is no longer valid, for example).

Note that no ouptut sink data should be requested from the processing context after a call to this method until new data has been processed.

In contrast to fluxEngine_C_v1_ProcessingContext_reset_state() this function will not reset the state of the processing context. It is only meant as a memory lifetime managemet helper.

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_LicenseDongleRemoved

• fluxEngine_C_v1_ErrorCode_LicenseDeviceNotConnected

• fluxEngine_C_v1_ErrorCode_ProcessingContextNoLongerValid

Parameters:

• context – The processing context to use

• 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

ProcessingContext_abort

int fluxEngine_C_v1_ProcessingContext_abort(fluxEngine_C_v1_ProcessingContext *context, fluxEngine_C_v1_Error **error)

Abort processing.

This function may be called from a different thread while processing is currently active. It will signal the processing context to abort processing. This function will return immediately, but the processing context is likely still active. Use the fluxEngine_C_v1_ProcessingContext_wait() function to wait until the processing context is no longer active.

After a call to this function the processing context needs to be reset via the function fluxEngine_C_v1_ProcessingContext_reset_state() before it may be used again.

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_ProcessingContextNoLongerValid

Parameters:

• context – The processing context to use

• 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

ProcessingContext_wait

int fluxEngine_C_v1_ProcessingContext_wait(fluxEngine_C_v1_ProcessingContext *context, fluxEngine_C_v1_Error **error)

Wait until processing or an abort is complete.

This function may be called from a different thread while processing is currently active. It will wait until the processing context is not in use anymore, either because processing has completed in the mean time, or an abort was requested and the abort has completed.

Note that fluxEngine_C_v1_ProcessingContext_process_next() already blocks and this method must only be used from different threads that also want to wait for the processing of a specific context to complete.

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_ProcessingContextNoLongerValid

Parameters:

• context – The processing context to use

• 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

OutputObject

struct fluxEngine_C_v1_OutputObject

An object that is output.

If an output sink is configured to output object data, it will be an array of this structure, containing the information related to each object.

Subclassed by fluxEngine::OutputObject

Public Members

int64_t bounding_box_x

The object’s bounding box: x coordinate of the left boundary.

int64_t bounding_box_y

The object’s bounding box: y coordinate of the top boundary.

For PushBroom frames this will indicate the starting frame of the object since the last reset.

int64_t bounding_box_width

The object’s bounding box: total width.

int64_t bounding_box_height

The object’s bounding box: total height.

double gravity_center_x

The object’s center of gravity: x coordinate.

The following equation will always be true:

boundung_box_x <= gravity_center_x &&
    gravity_center_x < (bounding_box_x + bounding_box_width)

double gravity_center_y

The object’s center of gravity: y coordinate.

The following equation will always be true:

boundung_box_y <= gravity_center_y &&
    gravity_center_y < (bounding_box_y + bounding_box_height)

int64_t area

The object’s area in pixels.

int8_t const *mask

A pointer to the object’s mask.

This may not be present, in which case this will be NULL. If this is present this will point to a 2D matrix (row-major storage order, contiguous in memory) that has the size of the bounding box specified in this object, where a value of 0 indicates that a given pixel belongs to the object, and a value of -1 indicates that it does not belong to the object.

The following function demonstrates how to interpret the mask, by returning true if a given pixel is part of the object and false otherwise, where x and y are counted relative to the start of the object’s bounding box:

bool is_part_of_object(fluxEngine_C_v1_OutputObject* object,
                       int64_t x, int64_t y)
{
    if (x < 0 || x >= object->bounding_box_width
        || y < 0 || y >= object->bounding_box_height)
        return false;
    return object->mask[y * object->bounding_box_width + x] == 0;
}

int16_t primary_class

The primary class of the object.

If the object was subject to a classifier, this will contain the primary class of the object. Classes within a model are counted beginning at 0. A negative class indicates that the classifier could not find a primary class for the object.

This is only valid if primary_class_present is non-zero.

uint8_t primary_class_present

Is a primary class present?

If this is non-zero, it indicates that the object has a primary class and the value stored in primary_class is valid. Otherwise the value stored in primary_class should be ignored.

void const *additional_data

Additional data for the object.

This is an array of scalar values, the size being fixed after creation of the processing context, that contain additional data that is passed together with the object.

If this is not present it will be NULL.

Tensor

struct fluxEngine_C_v1_Tensor

Tensor.

This data structure describes a tensor that is returned in the extended object data structure. It consists of a base pointer that points to the first element of the tensor, the tensor’s dimensions, the tensor’s strides, and the data type of the tensor.

If the base pointer is NULL all other fields of the tensor are irrelevant and this indicates that the tensor is not present. (This may happen when some tensors may optionally be present.)

The lifetime of the memory behind base_pointer depends on the method that returned the data structure containing the tensor.

The order parameter describes how many dimensions are actually used by the tensor — only those dimensions (and strides) are relevant.

The tensor order may be 0, in which case only a single scalar value will be stored in the tensor.

The following code demonstrates accessing the single scalar value of a tensor of order 0 with data type unsigned 8 bit integer:

uint8_t value = *((uint8_t const*) tensor.base_pointer);

The following code demonstrates accessing the i-th array element (0 <= i < tensor.dimensions[0]) of a one-dimensional tensor of type float:

float value = ((float const*) tensor.base_pointer)[tensor.strides[0] * i];

The following code demonstrates accessing the element in row i and column j of a matrix of type double, where 0 <= i < tensor.dimensions[0] and 0 <= j < tensor.dimensions[1]:

double value = ((double const*) tensor.base_pointer)[tensor.strides[0] * i + tensor.strides[1] * j];

Subclassed by fluxEngine::TensorData

Public Members

void const *base_pointer

The pointer to the first element of the tensor.

int64_t dimensions[5]

The dimensions of the tensor.

Only those dimensions are valid that are within the order of the tensor. For example, for a tensor of order 3, only the first 3 elements of this array will contain valid information, namely the dimensions of the tensor.

int64_t strides[5]

The strides of the tensor.

Only those strides are valid that are within the order of the tensor. For example, for a tensor of order 3, only the first 3 elements of this array will contain valid information, namely the strides of the tensor.

The strides describe how many elements need to be skipped to advance a specific dimension by one.

int order

The order of the tensor.

This number must be at least 0 (a scalar tensor) and at most 5 (the largest order of tensor supported by fluxEngine).

fluxEngine_C_v1_DataType data_type

The data type of the elements in the tensor.

OutputExtendedObjectStatistics

struct fluxEngine_C_v1_OutputExtendedObjectStatistics

Individual statistics data associated with objects.

Objects return multiple statistics data for a given object (one for each per-object statistics filter in the chain), and this structure describes one of those statistics data.

Note that the first statistics data is also always returned directly in the fluxEngine_C_v1_OutputExtendedObject structure for compatibility purposes with older versions of fluxEngine.

Public Members

fluxEngine_C_v1_Tensor mean

Mean.

This is a tensor of scalar values (possibly only a single scalar value) that contains mean values calculated for a given object, depending on the model used. The tensor structure and the amount of means calculated depends on the model.

This may be unset (the base pointer being NULL) if this is not present for the given object.

fluxEngine_C_v1_Tensor stdev

Standard deviation.

This is a tensor of scalar values (possibly only a single scalar value) that contains the standard deviation corresponding to the mean values. It will have the same tensor structure as the mean values described by the statistics_mean field.

This may be unset (the base pointer being NULL) if this is not present for the given object.

fluxEngine_C_v1_Tensor min_value

Minimum value.

This is a tensor of scalar values (possibly only a single scalar value) that contains the minimum values that were calculated on the same per-object data as the mean values provided. It will have the same tensor structure as the mean values described by the statistics_mean field.

This may be unset (the base pointer being NULL) if this is not present for the given object.

fluxEngine_C_v1_Tensor max_value

Maximum value.

This is a tensor of scalar values (possibly only a single scalar value) that contains the maximum values that were calculated on the same per-object data as the mean values provided. It will have the same tensor structure as the mean values described by the mean field.

This may be unset (the base pointer being NULL) if this is not present for the given object.

fluxEngine_C_v1_Tensor min_x

Minimum x positions.

For each minimum value provided in the min_value field this will contain the x position (relative to the left border of the object) of where the minimum was found. It will have the same tensor structure as the mean values described by the mean field, but always be of the data type fluxEngine_C_v1_DataType_Int64.

This may be unset (the base pointer being NULL) if this is not present for the given object.

fluxEngine_C_v1_Tensor min_y

Minimum y positions.

For each minimum value provided in the min_value field this will contain the y position (relative to the top border of the object) of where the minimum was found. It will have the same tensor structure as the mean values described by the mean field, but always be of the data type fluxEngine_C_v1_DataType_Int64.

This may be unset (the base pointer being NULL) if this is not present for the given object.

fluxEngine_C_v1_Tensor max_x

Maximum x positions.

For each maximum value provided in the min_value field this will contain the x position (relative to the left border of the object) of where the maximum was found. It will have the same tensor structure as the mean values described by the mean field, but always be of the data type fluxEngine_C_v1_DataType_Int64.

This may be unset (the base pointer being NULL) if this is not present for the given object.

fluxEngine_C_v1_Tensor max_y

Maximum y positions.

For each maximum value provided in the min_value field this will contain the y position (relative to the top border of the object) of where the maximum was found. It will have the same tensor structure as the mean values described by the mean field, but always be of the data type fluxEngine_C_v1_DataType_Int64.

This may be unset (the base pointer being NULL) if this is not present for the given object.

union fluxEngine_C_v1_OutputExtendedObjectStatistics reserved__

Reserved fields.

These bytes are reserved for the future use of this structure. (It is defined as a union to ensure the proper alignment.)

ObjectRegionShape

enum fluxEngine_C_v1_ObjectRegionShape

The shape of a given object region.

Values:

enumerator fluxEngine_C_v1_ObjectRegionShape_Rectangle

The object region is a rectangle.

enumerator fluxEngine_C_v1_ObjectRegionShape_Ellipse

The object region is an ellipse.

OutputExtendedObjectRegion

struct fluxEngine_C_v1_OutputExtendedObjectRegion

Regions associated with objects.

This structure describes an object region for which averages were calculated.

Public Members

fluxEngine_C_v1_ObjectRegionShape shape

The shape of the region.

double centerX

The X coordinate of the center of the region within the object’s bounding box.

This is measured from the top-left of the object’s bounding box, and is in pixels, regardless of how the region was defined by the user.

double centerY

The Y coordinate of the center of the region within the object’s bounding box.

This is measured from the top-left of the object’s bounding box, and is in pixels, regardless of how the region was defined by the user.

double sizeX

The width of the region.

This is measured in pixels, regardless of how the region was defined by the user.

double sizeY

The height of the region.

This is measured in pixels, regardless of how the region was defined by the user.

fluxEngine_C_v1_Tensor mean

Mean.

This is a tensor of scalar values (possibly only a single scalar value) that contains mean values calculated for the given region of the object.

union fluxEngine_C_v1_OutputExtendedObjectRegion reserved__

Reserved fields.

These bytes are reserved for the future use of this structure. (It is defined as a union to ensure the proper alignment.)

OutputExtendedObject

struct fluxEngine_C_v1_OutputExtendedObject

An object with extended data that is output.

If a processing context is configured to output extended object data for object-based output sinks, it will be an array of this structure, containing the information related to each object.

Subclassed by fluxEngine::OutputExtendedObject

Public Members

int64_t bounding_box_x

The object’s bounding box: x coordinate of the left boundary.

int64_t bounding_box_y

The object’s bounding box: y coordinate of the top boundary.

For PushBroom frames this will indicate the starting frame of the object since the last reset.

int64_t bounding_box_width

The object’s bounding box: total width.

int64_t bounding_box_height

The object’s bounding box: total height.

double gravity_center_x

The object’s center of gravity: x coordinate.

The following equation will always be true:

boundung_box_x <= gravity_center_x &&
    gravity_center_x < (bounding_box_x + bounding_box_width)

double gravity_center_y

The object’s center of gravity: y coordinate.

The following equation will always be true:

boundung_box_y <= gravity_center_y &&
    gravity_center_y < (bounding_box_y + bounding_box_height)

int64_t area

The object’s area in pixels.

fluxEngine_C_v1_Tensor mask

The object’s mask as a tensor.

This may not be present, in which case the base pointer of the tensor will be NULL. If this is present this will reference a 2D matrix (row-major storage order, contiguous in memory) that has the size of the bounding box specified in this object, where a value of 0 indicates that a given pixel belongs to the object, and a value of -1 indicates that it does not belong to the object.

The tensor will always have a data type of fluxEngine_C_v1_DataType_UInt8.

The following function demonstrates how to interpret the mask, by returning true if a given pixel is part of the object and false otherwise, where x and y are counted relative to the start of the object’s bounding box:

bool is_part_of_object(fluxEngine_C_v1_OutputObject* object,
                       int64_t x, int64_t y)
{
    uint8_t const* mask;
    if (x < 0 || x >= object->bounding_box_width
        || y < 0 || y >= object->bounding_box_height)
        return false;
    mask = (uint8_t const*) object->mask.base_pointer;
    return mask[y * object->mask.strides[0] + x * object->mask.strides[1]] == 0;
}

int16_t primary_class

The primary class of the object.

If the object was subject to a classifier, this will contain the primary class of the object. Classes within a model are counted beginning at 0. A negative class indicates that the classifier could not find a primary class for the object.

This is only valid if primary_class_present is non-zero.

uint8_t primary_class_present

Is a primary class present?

If this is non-zero, it indicates that the object has a primary class and the value stored in primary_class is valid. Otherwise the value stored in primary_class should be ignored.

fluxEngine_C_v1_Tensor additional_data

Additional data for the object.

If this is not present it will be an unset tensor (the base pointer being NULL).

fluxEngine_C_v1_Tensor statistics_mean

Statistics: mean.

This is a tensor of scalar values (possibly only a single scalar value) that contains mean values calculated for a given object, depending on the model used. The tensor structure and the amount of means calculated depends on the model.

This may be unset (the base pointer being NULL) if this is not present for the given object.

fluxEngine_C_v1_Tensor statistics_stdev

Statistics: standard deviation.

This is a tensor of scalar values (possibly only a single scalar value) that contains the standard deviation corresponding to the mean values. It will have the same tensor structure as the mean values described by the statistics_mean field.

This may be unset (the base pointer being NULL) if this is not present for the given object.

fluxEngine_C_v1_Tensor statistics_min

Statistics: minimum value.

This is a tensor of scalar values (possibly only a single scalar value) that contains the minimum values that were calculated on the same per-object data as the mean values provided. It will have the same tensor structure as the mean values described by the statistics_mean field.

This may be unset (the base pointer being NULL) if this is not present for the given object.

fluxEngine_C_v1_Tensor statistics_max

Statistics: maximum value.

This is a tensor of scalar values (possibly only a single scalar value) that contains the maximum values that were calculated on the same per-object data as the mean values provided. It will have the same tensor structure as the mean values described by the statistics_mean field.

This may be unset (the base pointer being NULL) if this is not present for the given object.

fluxEngine_C_v1_Tensor statistics_min_x

Statistics: minimum x positions.

For each minimum value provided in the statistics_min field this will contain the x position (relative to the left border of the object) of where the minimum was found. It will have the same tensor structure as the mean values described by the statistics_mean field, but always be of the data type fluxEngine_C_v1_DataType_Int64.

This may be unset (the base pointer being NULL) if this is not present for the given object.

fluxEngine_C_v1_Tensor statistics_min_y

Statistics: minimum y positions.

For each minimum value provided in the statistics_min field this will contain the y position (relative to the top border of the object) of where the minimum was found. It will have the same tensor structure as the mean values described by the statistics_mean field, but always be of the data type fluxEngine_C_v1_DataType_Int64.

This may be unset (the base pointer being NULL) if this is not present for the given object.

fluxEngine_C_v1_Tensor statistics_max_x

Statistics: maximum x positions.

For each maximum value provided in the statistics_max field this will contain the x position (relative to the left border of the object) of where the maximum was found. It will have the same tensor structure as the mean values described by the statistics_mean field, but always be of the data type fluxEngine_C_v1_DataType_Int64.

This may be unset (the base pointer being NULL) if this is not present for the given object.

fluxEngine_C_v1_Tensor statistics_max_y

Statistics: maximum y positions.

For each maximum value provided in the statistics_max field this will contain the y position (relative to the top border of the object) of where the maximum was found. It will have the same tensor structure as the mean values described by the statistics_mean field, but always be of the data type fluxEngine_C_v1_DataType_Int64.

This may be unset (the base pointer being NULL) if this is not present for the given object.

fluxEngine_C_v1_Tensor quality

Statistics: quality values.

This will contain the user-defined quality values for the given object. The structure of this tensor will will depend on the user’s configuration, but the order of the tensor will always be 1, making it a one-dimensional array.

This may be unset (the base pointer being NULL) if this is not present for the given object.

fluxEngine_C_v1_OutputExtendedObjectStatistics *statistics_list

Statistics list.

When multiple statistics are present for the same object this will point to an array of statistics values. This may be NULL if there are no statistics associated with the object.

The amount of entries in this array will be given by the count returned by fluxEngine_C_v1_ProcessingContext_get_output_sink_object_list_statistics_structure_count(). The user must ensure that they never attempt to access memory that exceeds those bounds.

fluxEngine_C_v1_OutputExtendedObjectRegion *region_list

Region list.

If object regions are present for the given object (using the object region averaging filter), this will reference an array of regions that are in use. This may be NULL if there are no object regions passed to the output sink.

The amount of entries in this array will be given by the count returned by fluxEngine_C_v1_ProcessingContext_get_output_sink_object_list_region_count(). The user must ensure that they never attempt to access memory that exceeds those bounds.

union fluxEngine_C_v1_OutputExtendedObject reserved__

Reserved fields.

These bytes are reserved for the future use of this structure. (It is defined as a union to ensure the proper alignment.)

ProcessingContext_get_output_sink_data

int fluxEngine_C_v1_ProcessingContext_get_output_sink_data(fluxEngine_C_v1_ProcessingContext *context, int sink_index, int64_t actual_sizes[5], void const **data, fluxEngine_C_v1_Error **error)

Get the resulting output sink data of a given processing context.

For tensor data it is recommended to use the fluxEngine_C_v1_ProcessingContext_get_output_sink_data_s() function instead of this function, as that will provide more information about the tensor structure to the user.

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_ProcessingContextNoLongerValid

• fluxEngine_C_v1_ErrorCode_IndexOutOfRange

Parameters:

• context – The processing context to obtain the output results from

• sink_index – The index of the output sink to obtain the output data from

• actual_sizes – [out] The actual amount of data at the output sink will be stored in this user-supplied array. For tensor data the array only the first N elements of the array, where N is the order of the tensor, will be filled. For object list data, the first element of the array will contain the number of objects. Any unused element of this array may be filled with an arbitrary value or left untouched by this method.

• data – [out] A pointer to the start of the data region will be stored in this user-supplied array. A memory region returned by this function will be invalidated the next time the user performs data processing again, resets the state of the context, or destroys the context

• 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

ProcessingContext_get_output_sink_data_s

int fluxEngine_C_v1_ProcessingContext_get_output_sink_data_s(fluxEngine_C_v1_ProcessingContext *context, int sink_index, int *data_type, int *order, int64_t actual_sizes[5], int64_t strides[5], void const **data, fluxEngine_C_v1_Error **error)

Get the resulting output sink data of a given processing context (with structure 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_ProcessingContextNoLongerValid

• fluxEngine_C_v1_ErrorCode_IndexOutOfRange

Parameters:

• context – The processing context to obtain the output results from

• sink_index – The index of the output sink to obtain the output data from

• data_type – [out] The scalar data type of the output data, cast to int. If the sink returns objects this will be set to -1. If the sink returns a tensor, this will be set to the tensor’s data type, see the fluxEngine_C_v1_DataType enumeration.

• order – [out] The order of the output data. If the sink returns an object list, this will always be set to 1.

• actual_sizes – [out] The actual amount of data at the output sink will be stored in this user-supplied array. For tensor data the array only the first N elements of the array, where N is the order of the tensor, will be filled. For object list data, the first element of the array will contain the number of objects. Any unused element of this array may be filled with an arbitrary value or left untouched by this method.

• strides – [out] The actual strides of the data. If the result is an object list, this will be set to all zeros. If the result is a tensor this will be set to the strides of that tensor.

• data – [out] A pointer to the start of the data region will be stored in this user-supplied array. A memory region returned by this function will be invalidated the next time the user performs data processing again, resets the state of the context, or destroys the context

• 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

ProcessingContext_destroy

void fluxEngine_C_v1_ProcessingContext_destroy(fluxEngine_C_v1_ProcessingContext *context)

Destroy a processing cotext.

Destroy a processing context, freeing its resources.

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

Parameters:

• context – The context to destroy