Data Processing¶

typedef struct fluxEngine_C_v1_ProcessingContext fluxEngine_C_v1_ProcessingContext¶

Processing Context.

This opaque data structure describes a processing context.

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

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.

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.

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

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

Return

0 on success, -1 on failure

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
[out] context: The resulting processing context
[out] error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

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.

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

Return

0 on success, -1 on failure

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
[out] context: The resulting processing context
[out] error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

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

Return

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

Parameters

context: The processing context for which to list the output sinks
[out] error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

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

Return

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

Parameters

context: The processing context for which to list the output sinks
output_id: The output_id of the output sink
[out] error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

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.

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

Return

0 on success, -1 on failure

Parameters

context: The processing context for which to introspect the output sink
sink_index: The index of the output sink to introspect
[out] output_id: The output id that is set for the the sink. This is purely for informational purposes
[out] name: 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.
[out] output_storage_type: The storage type of the data at this output sink
[out] input_delay: The delay of this output sink relative to the input data given. See the advanced topics section of the documentation for more details.
[out] error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

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

fluxEngine_C_v1_ProcessingContext_get_output_sink_data

Return

0 on success, -1 on failure

Parameters

context: The processing context for which to introspect the output sink
sink_index: The index of the output sink to introspect
[out] data_type: The data type of the data returned by the sink
[out] order: The order of the tensor that is being returned. This will typically be 2 or 3.
[out] max_sizes: The maximum dimensions of the tensor that may be returned. Only elements up to order are filled in, the rest will be 0.
[out] fixed_sizes: 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
[out] error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

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.

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

fluxEngine_C_v1_ProcessingContext_get_output_sink_data

Return

0 on success, -1 on failure

Parameters

context: The processing context for which to introspect the output sink
sink_index: The index of the output sink to introspect
[out] max_object_count: The maximum number of objects that will be returned after a single execution
[out] additional_data_size: The number of additional data entries present per object (may be 0 to indicate no additional data is present)
[out] additional_data_type: The scalar type of the additional data entries per object
[out] error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

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

Return

0 on success, -1 on failure

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.
[out] error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

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

Return

0 on success, -1 on failure

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
[out] error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

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

Return

0 on success, -1 on failure

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.
[out] error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

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

Return

0 on success, -1 on failure

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
[out] error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

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

Return

0 on success, -1 on failure

Parameters

context: The processing context to use
[out] error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

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

Return

0 on success, -1 on failure

Parameters

context: The processing context to use
[out] error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

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

Return

0 on success, -1 on failure

Parameters

context: The processing context to use
[out] error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

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

Return

0 on success, -1 on failure

Parameters

context: The processing context to use
[out] error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

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

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

Return

0 on success, -1 on failure

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
[out] actual_sizes: 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.
[out] data: 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
[out] error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

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

Return

0 on success, -1 on failure

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
[out] data_type: 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.
[out] order: The order of the output data. If the sink returns an object list, this will always be set to 1.
[out] actual_sizes: 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.
[out] strides: 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.
[out] data: 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
[out] error: The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

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