Instrument Data Standardization And Processing

int fluxEngine_C_v1_ProcessingContext_create_instrument_preview(fluxEngine_C_v1_Device *device, fluxEngine_C_v1_ProcessingContext **context, fluxEngine_C_v1_Error **error)

Create a processing context for previewing instrument data.

When processing data from an instrument the raw buffer data will often not be in a form that is very useful to perform processing with. For example, PushBroom HSI cameras can have multiple different orientations for the spectrograph, making it camera-depenent how the data is to be interpreted. Furthermore some cameras may return data in a packed buffer scalar type (see fluxEngine_C_v1_BufferScalarType for further details) that may not be easily interpretable by the user.

When recording data, or using data for processing in a model, a set of preprocessing steps will be taken automatically to ensure that the data is normalized. These steps may carry some expenses though, and if the user simply wants to obtain a data to display as a preview, it might be useful.

Instrument drivers that don’t provide information about how to perform the minimally necessary normalization steps will fall back on the preprocessing steps required for data recording here, with some default settings, such as no wavelength normalization.

The normalized data of the resulting processing context can be obtained by querying the output sink with index 0. (There is no actual output sink with that index, as the processing context does not have an associated model, but the result of the preprocessing steps will be returned in this manner.)

How the data is normalized will depend on the type of instrument:

  • For a spectrometer this will result in a single vector of intensities. (Tensor of order 1.)

  • For a HSI PushBroom camera this will result in a tensor of order 3, with the first dimension always being 1 (because the y direction only has a single entry), the second dimension being the spatial dimension, and the final dimension being the spectral dimension, regardless of spectrograph orientation.

  • For HSI imager cameras this will result in a tensor of order 3, with the first dimension corresponding to the y dimension, the second to the x dimension, and the third to the spectral dimension, regardless of how the cube has been obtained by the camera (mosaic pattern, filter wheel, etc.).

  • For a monochrome polarization camera this will result in a tensor of order 3, with the first dimension corresponding to the y dimension, the second to the x dimension, and the third to the various polarization directions for that camera, regardless of the exact construction (mosaic imager, beam-split multi-camera with various polarization filters, etc.).

Note that corrections might not have been applied to the data at this point. For example, the spectral dimension of a HSI camera (be it PushBroom or imager) may not correspond to actual physical wavelengths yet. Also, any software-based post-processing, such as software binning, has not been applied to this data.

Data must be supplied to this processing context via either the fluxEngine_C_v1_ProcessingContext_set_source_data_buffer() method or the fluxEngine_C_v1_ProcessingContext_set_source_data_persistent_buffer() method.

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_DeviceNoLongerValid

  • fluxEngine_C_v1_ErrorCode_DeviceTypeError

  • fluxEngine_C_v1_ErrorCode_DeviceParameterNotFound

  • fluxEngine_C_v1_ErrorCode_DeviceProcessingInformationMissing

  • fluxEngine_C_v1_ErrorCode_InstrumentDeviceIncompatibleError

  • fluxEngine_C_v1_ErrorCode_DeviceProcessingPreprocessingSetupError

Parameters

  • device – The instrument device

  • context – [out] The preview 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

int fluxEngine_C_v1_ProcessingContext_create_instrument_preview_pqs(fluxEngine_C_v1_Device *device, fluxEngine_C_v1_ProcessingQueueSet *processing_queue_set, fluxEngine_C_v1_ProcessingContext **context, fluxEngine_C_v1_Error **error)

Create a processing context for previewing instrument data.

This function is identical to fluxEngine_C_v1_ProcessingContext_create_instrument_preview(), but allows the user to specify the processing queue set to use, instead of using the default processing queue set of the handle. Specifying NULL for processing_queue_set will use the default processing queue set of the handle, though.

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_DeviceNoLongerValid

  • fluxEngine_C_v1_ErrorCode_DeviceTypeError

  • fluxEngine_C_v1_ErrorCode_DeviceParameterNotFound

  • fluxEngine_C_v1_ErrorCode_DeviceProcessingInformationMissing

  • fluxEngine_C_v1_ErrorCode_InstrumentDeviceIncompatibleError

  • fluxEngine_C_v1_ErrorCode_DeviceProcessingPreprocessingSetupError

Parameters

  • device – The instrument device

  • processing_queue_set – The processing queue set to use

  • context – [out] The preview 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

struct fluxEngine_C_v1_ProcessingContext_ReferenceMeasurement

Resulting Reference Measurement (Recording Processing Contexts)

This structure describes a reference measurement result in a normalized form (for HSI cameras this would be in form of a HSI cube, for example) that was obtained while creating a recording processing context. It will be stored within a fluxEngine_C_v1_ProcessingContext_HSIRecordingResult structure to return the normalized references that can be used in conjunction with the data the user records. (These could be used to later initialize an offline processing context.)

When data in referenced form (no intensities) is requested, no reference measurements will be returned while creating such a recording context.

Regardless of whether the user uses these structures, they must free them via the fluxEngine_C_v1_ProcessingContext_ReferenceMeasurement_free() function.

See also

fluxEngine_C_v1_ProcessingContext_create_instrument_hsi_recording

See also

fluxEngine_C_v1_ProcessingContext_create_instrument_hsi_recording_ex

Public Members

void const *data

A pointer to the normalized reference data.

fluxEngine_C_v1_DataType data_type

The scalar type of the reference data.

This will be the same scalar type as the recording result.

int order

The tensor order of the reference data.

This will be 3 for all current types of HSI cameras, resulting in a HSI cube in BIP storage order. (y, x, wavelengths)

For spectrometers this will be 1 (the dimension for the wavelengths).

int64_t dimensions[5]

The dimensions of the tensor.

Only the first order dimensions will contain valid values. The user must ignore other values in this array and must not rely on them.

int64_t strides[5]

The strides of the tensor.

Only the first order strides will contain valid values. The user must ignore other values in this array and must not rely on them.

fluxEngine_C_v1_CalibrationInfo *calibration_info

Optional: calibration info.

If not NULL this will contain calibration information that may be stored in conjunction with the reference measurements.

IMPORTANT: the structure this points to will be freed by fluxEngine_C_v1_ProcessingContext_ReferenceMeasurement_free() if the pointer is set when calling that function.

This field was added in fluxEngine 4.10.

void fluxEngine_C_v1_ProcessingContext_ReferenceMeasurement_free(fluxEngine_C_v1_ProcessingContext_ReferenceMeasurement *measurement)

Free a reference measurement.

This frees a reference measurement that was returned by either fluxEngine_C_v1_ProcessingContext_create_instrument_hsi_recording() or fluxEngine_C_v1_ProcessingContext_create_instrument_hsi_recording_ex() in their result parameter.

Parameters

  • measurement – The measurement to free

struct fluxEngine_C_v1_ProcessingContext_HSIRecordingResult

HSI Recording result.

This structure is the return value of the methods that create processing contexts for recording HSI data from a camera. It contains the resulting processing context, as well as further information describing the recording:

  • The wavelengths of the normalized data that is being returned.

  • If intensity data is requested, and references where specified during the creation of the processing context, the normalized reference data will also be returned. (Most notably a white reference cube will be present.)

The additional data that is returned in this structure must be freed in addition to the processing context, even if it is not being used.

Important: before supplying this structure to the functions that create the recording processing contexts, the structure_size parameter must be initialized with the current size of this structure. All other members of the structure will be overwritten upon a successful call to the context creation functions. The user must not access or free any data in this structure in case the context creation function fails.

Public Members

size_t structure_size

The size of the structure.

Must be set to sizeof(fluxEngine_C_v1_ProcessingContext_HSIRecordingResult) by the user.

fluxEngine_C_v1_ProcessingContext *context

The resulting processing context.

The context must be freed by the user via the fluxEngine_C_v1_ProcessingContext_destroy() function after it is no longer required.

double *wavelengths

The list of wavelengths of the recorded data.

This contains the wavelengths associated with the last dimension of the data being recorded. It must be freed via the fluxEngine_C_v1_wavelengths_free() function.

int wavelength_count

The number of wavelengths.

This will be identical to the size of the last dimension of the only output sink in the processing context.

fluxEngine_C_v1_ProcessingContext_ReferenceMeasurement *white_reference

Normalized white reference.

If a white reference was supplied during the creation of a recording processing context, and the user has requested intensity data, this will contain the normalized white reference that the user may save in addition to the data they will record.

The user must always free this via the fluxEngine_C_v1_ProcessingContext_ReferenceMeasurement_free() function after this structure has been returned.

fluxEngine_C_v1_ProcessingContext_ReferenceMeasurement *dark_reference

Normalized dark reference.

If a dark reference was supplied during the creation of a recording processing context, and the user has requested intensity data, this will contain the normalized dark reference that the user may save in addition to the data they will record.

The user must always free this via the fluxEngine_C_v1_ProcessingContext_ReferenceMeasurement_free() function after this structure has been returned.

bool calibration_info_requested

Calibration info requested.

If the user wants to obtain calibration information for any measurement recording made with this context, this should be set to 1 before the call to the context-creating function. Afterwards the calibration_info structure will be filled in, which the user must then free.

If this is not set the calibration_info structure is never filled.

fluxEngine_C_v1_CalibrationInfo *calibration_info

Calibration info.

If not NULL this will contain calibration information that may be stored in conjunction with the reference measurements. For compatibility reasons with code written against older versions of fluxEngine, this will only be populated if the calibration_info_requested field is set to true.

The user must always free this via the fluxEngine_C_v1_CalibrationInfo_free() function after this structure has been returned.

This field was added in fluxEngine 4.10.

struct fluxEngine_C_v1_ProcessingContext_InstrumentParameters

Instrument parameters.

This structure describes common instrument parameters that may be supplied while creating a processing context for recording instrument data or processing it via a fluxEngine/fluxRuntime model.

Currently this exists to allow the user to supply a previously measured white and dark reference measurement.

This structure allows the user to supply the references in form of fluxEngine_C_v1_BufferContainer objects. There is also a second structure, fluxEngine_C_v1_ProcessingContext_InstrumentParametersEx, that allows the user to specify the references as raw data directly.

Important: the user must initialize the structure entirely with zero bytes and thereafter set the structure_size member to the size of this structure. Only then may they set the rest of the structure members as they desire. This exists for allowing future versions of fluxEngine to expand the possible values of this structure, while maintaining both source and binary compatibility.

Public Members

size_t structure_size

The size of the structure.

Must be set to sizeof(fluxEngine_C_v1_ProcessingContext_InstrumentParameters) by the user.

fluxEngine_C_v1_BufferContainer *white_reference_buffer

The white reference buffer.

Supply NULL here to indicate that no white reference is present.

fluxEngine_C_v1_BufferContainer *dark_reference_buffer

The dark reference buffer.

Supply NULL here to indicate that no dark reference is present.

Note that in the absence of a white reference a dark reference is currently ignored. (This may change in later versions of fluxEngine.)

uint64_t flags

Flags related to the creation of the processing context.

This must be either 0 or a bitwise or’d combination of flags defined in the fluxEngine_C_v1_DeviceProcessingContext_CreationFlags enumeration.

struct fluxEngine_C_v1_ProcessingContext_InstrumentParametersEx

Instrument parameters (explicit version)

This structure describes common instrument parameters that may be supplied while creating a processing context for recording instrument data or processing it via a fluxEngine/fluxRuntime model.

Currently this exists to allow the user to supply a previously measured white and dark reference measurement.

This structure allows the user to supply the references in form of raw data. The data must have the same buffer scalar type as buffers the instrument currently returns. The dimensions must be of the form (N, dims...), where N is the number of reference measurements, and dims... are the exact same dimensions as the instrument currently returns while providing a buffer.

Important: the user must initialize the structure entirely with zero bytes and thereafter set the structure_size member to the size of this structure. Only then may they set the rest of the structure members as they desire. This exists for allowing future versions of fluxEngine to expand the possible values of this structure, while maintaining both source and binary compatibility.

Public Members

size_t structure_size

The size of the structure.

Must be set to sizeof(fluxEngine_C_v1_ProcessingContext_InstrumentParametersEx) by the user.

int reference_order

The order of the reference tensors.

This must be exactly one more than the order of the buffer that the device returns.

If no references are set at all (both the white_reference and dark_reference fields are NULL), this may be 0 instead.

void const *white_reference

The white reference data.

A pointer to the start of the raw data containing the white reference.

If no white reference is provided by the user, this must be set to NULL.

int64_t white_reference_dimensions[5]

The dimensions of the white reference.

Only the first reference_order entries will be considered.

If no white reference is provided by the user (the white_reference field is set to NULL), the values here will be ignored completely.

int64_t white_reference_strides[5]

The strides of the white reference.

Only the first reference_order entries will be considered.

If no white reference is provided by the user (the white_reference field is set to NULL), the values here will be ignored completely.

void const *dark_reference

The dark reference data.

A pointer to the start of the raw data containing the dark reference.

If no dark reference is provided by the user, this must be set to NULL.

int64_t dark_reference_dimensions[5]

The dimensions of the dark reference.

Only the first reference_order entries will be considered.

If no dark reference is provided by the user (the dark_reference field is set to NULL), the values here will be ignored completely.

int64_t dark_reference_strides[5]

The strides of the dark reference.

Only the first reference_order entries will be considered.

If no dark reference is provided by the user (the dark_reference field is set to NULL), the values here will be ignored completely.

uint64_t flags

Flags related to the creation of the processing context.

This must be either 0 or a bitwise or’d combination of flags defined in the fluxEngine_C_v1_DeviceProcessingContext_CreationFlags enumeration.

int fluxEngine_C_v1_ProcessingContext_create_instrument_hsi_recording(fluxEngine_C_v1_Device *device, fluxEngine_C_v1_ValueType valueType, fluxEngine_C_v1_ProcessingContext_InstrumentParameters const *instrument_parameters, double const *wavelength_grid, size_t wavelength_count, fluxEngine_C_v1_ProcessingContext_HSIRecordingResult *result, fluxEngine_C_v1_Error **error)

Create a processing context (HSI and spectrometer data recording)

Creates a processing context that may be used to record HSI from an instrument, this includes spectrometers.

Processing contexts of this type may be used to record data from a spectrometer or HSI camera.

The user may request normalization to a regularized wavelength grid (see the wavelength_grid and wavelength_count parameters), otherwise the instrument’s raw wavelengths will be returned. For example, a HSI camera that has a typical spectral range from 400 to 1000 nanometers might actually have wavelengths of the form 400.21, 402.35, etc. If a regularized wavelength grid is specified, all values will be interpolated before the data is returned to the user.

If a wavelength grid is provided, the wavelengths member of the result parameter will contain the user-requested wavelength grid. If no wavelength grid is provided (the parameter set to NULL) the wavelengths member of the result parameter will contain the unregularized wavelengths of the instrument device itself.

The user may optionally provide a white and dark reference to reference the data or normalize the references to be stored next to the intesnsity data. This method accepts a structure that contains pointers to fluxEngine_C_v1_BufferContainer objects that contain the actual raw reference data. There is also fluxEngine_C_v1_ProcessingContext_create_instrument_hsi_recording_ex(), which supports reference data provided by the user.

The user must specify what value type they want the data in. The following options exist:

  • The user requests data in intensities (using the fluxEngine_C_v1_ValueType_Intensity value type), and provides no white reference: the data will be provided in intensities and the user can only store the intensity data.

    In case of instruments that can only return pre-referenced data (such as virtual devices that return reflectances, or devices that perform the referencing already in hardware) attempting to create such a context will result in an error.

  • The user requests data in intensities (using the fluxEngine_C_v1_ValueType_Intensity value type), but nevertheless provides a white reference: the recording data itself will still be in intensities, but a normalized white reference will be returned that may be saved next to the measurement data.

    In case of instruments that can only return pre-referenced data (such as virtual devices that return reflectances, or devices that perform the referencing already in hardware) attempting to create such a context will result in an error.

  • The user requests data in reflectances or absorbances, but provides no white reference: if the instrument returns pre-referenced data (such as virtual devices that return reflectances, or devices that perform the referencing already in hardware) this will succeed. If the device only provides its data in intensities (most devices), but no white reference is provided, context creation will fail.

  • The user requests data in reflectances or absorbances, and provides a white reference measurement: the data returned by the processing context will be of the value type the user selected, and referencing will occur before the data is returned to the user.

The normalized data of the resulting processing context can be obtained by querying the output sink with index 0. (There is no actual output sink with that index, as the processing context does not have an associated model, but the result of the preprocessing steps will be returned in this manner.)

How the data is normalized will depend on the type of instrument:

  • For a spectrometer this will result in a single vector of intensities. (Tensor of order 1.)

  • For a HSI PushBroom camera this will result in a tensor of order 3, with the first dimension always being 1 (because the y direction only has a single entry), the second dimension being the spatial dimension, and the final dimension being the spectral dimension, regardless of spectrograph orientation.

  • For HSI imager cameras this will result in a tensor of order 3, with the first dimension corresponding to the y dimension, the second to the x dimension, and the third to the spectral dimension, regardless of how the cube has been obtained by the camera (mosaic pattern, filter wheel, etc.).

Data must be supplied to this processing context via either the fluxEngine_C_v1_ProcessingContext_set_source_data_buffer() method or the fluxEngine_C_v1_ProcessingContext_set_source_data_persistent_buffer() method.

Note that the instrument_parameters and result structures must be allocated by the user (for example on the stack) and the structure_size field must be initialized with the size of the respective structure.

Memory management: all information passed by the user to this function in the instrument_parameters and wavelength_grid parameters will only be accessed while this function is active; any required information is copied into the resulting processing context upon its creation. The use is free to release the memory associated with these parameters after the call to this method has completed.

The processing context only uses the device parameter to obtain the required information to create the context; the context is independent of the device. However, it will be associated with the fluxEngine handle of the device, and it will require that the data provided will be in the format that device currently produces. This means that reconnecting to the same device and setting the same settings allows the user to reuse the processing context. Also, if the data returned by the device is structurally the same (because it has the same buffer dimensions), but does not match the context semantically — for example the user selecting a different ROI in the spectral dimension, but of the same size, the context will still process the data, even though the result will not be sensible.

Note that the user must free all allocated fields in the result structure if this function is successful, even if they choose not to use all of them. See the documentation fo the fluxEngine_C_v1_ProcessingContext_InstrumentParameters type for further details. (If the function is not successful the contents of the result parameter should not be used at all by 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_LicenseDongleRemoved

  • fluxEngine_C_v1_ErrorCode_LicenseDeviceNotConnected

  • fluxEngine_C_v1_ErrorCode_DeviceNoLongerValid

  • fluxEngine_C_v1_ErrorCode_DeviceTypeError

  • fluxEngine_C_v1_ErrorCode_DeviceParameterNotFound

  • fluxEngine_C_v1_ErrorCode_DeviceProcessingInformationMissing

  • fluxEngine_C_v1_ErrorCode_InstrumentDeviceIncompatibleError

  • fluxEngine_C_v1_ErrorCode_DeviceProcessingPreprocessingSetupError

  • fluxEngine_C_v1_ErrorCode_DeviceProcessingInvalidReferenceError

See also

fluxEngine_C_v1_ProcessingContext_create_instrument_hsi_recording_pqs()

See also

fluxEngine_C_v1_ProcessingContext_create_instrument_hsi_recording_ex()

See also

fluxEngine_C_v1_ProcessingContext_create_instrument_hsi_recording_pqs_ex()

Parameters

  • device – The instrument device

  • valueType – The requested value type of the data that is to be returned.

  • instrument_parameters – The instrument parameters, mainly the previously measured reference data. The structure must be initialized with zeros, then the structure_size field must be set to the size of the structure, before providing this structure to this function.

  • wavelength_grid – Optional: a list of wavelengths to regularize the wavelengths to. Supply NULL in case the wavelengths of the instrument are to be used and the data should not normalized in this manner.

  • wavelength_count – The number of wavelengths stored in the wavelength_grid parameter. The value here will be ignored if that parameter is set to NULL.

  • result – [out] Where to store the result in. The structure should be initialized with zeros before passing it to this function, but for the structure_size field, which must have been set by the user to the size of the structure.

  • 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

int fluxEngine_C_v1_ProcessingContext_create_instrument_hsi_recording_pqs(fluxEngine_C_v1_Device *device, fluxEngine_C_v1_ProcessingQueueSet *processing_queue_set, fluxEngine_C_v1_ValueType valueType, fluxEngine_C_v1_ProcessingContext_InstrumentParameters const *instrument_parameters, double const *wavelength_grid, size_t wavelength_count, fluxEngine_C_v1_ProcessingContext_HSIRecordingResult *result, fluxEngine_C_v1_Error **error)

Create a processing context (HSI and spectrometer data recording)

This function is identical to fluxEngine_C_v1_ProcessingContext_create_instrument_hsi_recording(), but allows the user to specify the processing queue set to use, instead of using the default processing queue set of the handle. Specifying NULL for processing_queue_set will use the default processing queue set of the handle, though.

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_DeviceNoLongerValid

  • fluxEngine_C_v1_ErrorCode_DeviceTypeError

  • fluxEngine_C_v1_ErrorCode_DeviceParameterNotFound

  • fluxEngine_C_v1_ErrorCode_DeviceProcessingInformationMissing

  • fluxEngine_C_v1_ErrorCode_InstrumentDeviceIncompatibleError

  • fluxEngine_C_v1_ErrorCode_DeviceProcessingPreprocessingSetupError

  • fluxEngine_C_v1_ErrorCode_DeviceProcessingInvalidReferenceError

See also

fluxEngine_C_v1_ProcessingContext_create_instrument_hsi_recording()

See also

fluxEngine_C_v1_ProcessingContext_create_instrument_hsi_recording_ex()

See also

fluxEngine_C_v1_ProcessingContext_create_instrument_hsi_recording_pqs_ex()

Parameters

  • device – The instrument device

  • processing_queue_set – The processing queue set to use

  • valueType – The requested value type of the data that is to be returned.

  • instrument_parameters – The instrument parameters, mainly the previously measured reference data. The structure must be initialized with zeros, then the structure_size field must be set to the size of the structure, before providing this structure to this function.

  • wavelength_grid – Optional: a list of wavelengths to regularize the wavelengths to. Supply NULL in case the wavelengths of the instrument are to be used and the data should not normalized in this manner.

  • wavelength_count – The number of wavelengths stored in the wavelength_grid parameter. The value here will be ignored if that parameter is set to NULL.

  • result – [out] Where to store the result in. The structure should be initialized with zeros before passing it to this function, but for the structure_size field, which must have been set by the user to the size of the structure.

  • 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

int fluxEngine_C_v1_ProcessingContext_create_instrument_hsi_recording_ex(fluxEngine_C_v1_Device *device, fluxEngine_C_v1_ValueType valueType, fluxEngine_C_v1_ProcessingContext_InstrumentParametersEx const *instrument_parameters, double const *wavelength_grid, size_t wavelength_count, fluxEngine_C_v1_ProcessingContext_HSIRecordingResult *result, fluxEngine_C_v1_Error **error)

Create a processing context (HSI and spectrometer data recording)

Creates a processing context that may be used to record HSI from an instrument, this includes spectrometers.

Processing contexts of this type may be used to record data from a spectrometer or HSI camera.

The user may request normalization to a regularized wavelength grid (see the wavelength_grid and wavelength_count parameters), otherwise the instrument’s raw wavelengths will be returned. For example, a HSI camera that has a typical spectral range from 400 to 1000 nanometers might actually have wavelengths of the form 400.21, 402.35, etc. If a regularized wavelength grid is specified, all values will be interpolated before the data is returned to the user.

If a wavelength grid is provided, the wavelengths member of the result parameter will contain the user-requested wavelength grid. If no wavelength grid is provided (the parameter set to NULL) the wavelengths member of the result parameter will contain the unregularized wavelengths of the instrument device itself.

The user may optionally provide a white and dark reference to reference the data or normalize the references to be stored next to the intesnsity data. This method accepts a structure that the user can fill with pointers to the raw data of the measured references. There is also fluxEngine_C_v1_ProcessingContext_create_instrument_hsi_recording(), which supports reference data in form of fluxEngine_C_v1_BufferContainer objects.

The user must specify what value type they want the data in. The following options exist:

  • The user requests data in intensities (using the fluxEngine_C_v1_ValueType_Intensity value type), and provides no white reference: the data will be provided in intensities and the user can only store the intensity data.

    In case of instruments that can only return pre-referenced data (such as virtual devices that return reflectances, or devices that perform the referencing already in hardware) attempting to create such a context will result in an error.

  • The user requests data in intensities (using the fluxEngine_C_v1_ValueType_Intensity value type), but nevertheless provides a white reference: the recording data itself will still be in intensities, but a normalized white reference will be returned that may be saved next to the measurement data.

    In case of instruments that can only return pre-referenced data (such as virtual devices that return reflectances, or devices that perform the referencing already in hardware) attempting to create such a context will result in an error.

  • The user requests data in reflectances or absorbances, but provides no white reference: if the instrument returns pre-referenced data (such as virtual devices that return reflectances, or devices that perform the referencing already in hardware) this will succeed. If the device only provides its data in intensities (most devices), but no white reference is provided, context creation will fail.

  • The user requests data in reflectances or absorbances, and provides a white reference measurement: the data returned by the processing context will be of the value type the user selected, and referencing will occur before the data is returned to the user.

The normalized data of the resulting processing context can be obtained by querying the output sink with index 0. (There is no actual output sink with that index, as the processing context does not have an associated model, but the result of the preprocessing steps will be returned in this manner.)

How the data is normalized will depend on the type of instrument:

  • For a spectrometer this will result in a single vector of intensities. (Tensor of order 1.)

  • For a HSI PushBroom camera this will result in a tensor of order 3, with the first dimension always being 1 (because the y direction only has a single entry), the second dimension being the spatial dimension, and the final dimension being the spectral dimension, regardless of spectrograph orientation.

  • For HSI imager cameras this will result in a tensor of order 3, with the first dimension corresponding to the y dimension, the second to the x dimension, and the third to the spectral dimension, regardless of how the cube has been obtained by the camera (mosaic pattern, filter wheel, etc.).

Data must be supplied to this processing context via either the fluxEngine_C_v1_ProcessingContext_set_source_data_buffer() method or the fluxEngine_C_v1_ProcessingContext_set_source_data_persistent_buffer() method.

Note that the instrument_parameters and result structures must be allocated by the user (for example on the stack) and the structure_size field must be initialized with the size of the respective structure.

Memory management: all information passed by the user to this function in the instrument_parameters and wavelength_grid parameters will only be accessed while this function is active; any required information is copied into the resulting processing context upon its creation. The use is free to release the memory associated with these parameters after the call to this method has completed.

The processing context only uses the device parameter to obtain the required information to create the context; the context is independent of the device. However, it will be associated with the fluxEngine handle of the device, and it will require that the data provided will be in the format that device currently produces. This means that reconnecting to the same device and setting the same settings allows the user to reuse the processing context. Also, if the data returned by the device is structurally the same (because it has the same buffer dimensions), but does not match the context semantically — for example the user selecting a different ROI in the spectral dimension, but of the same size, the context will still process the data, even though the result will not be sensible.

Note that the user must free all allocated fields in the result structure if this function is successful, even if they choose not to use all of them. See the documentation fo the fluxEngine_C_v1_ProcessingContext_InstrumentParametersEx type for further details. (If the function is not successful the contents of the result parameter should not be used at all by 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_LicenseDongleRemoved

  • fluxEngine_C_v1_ErrorCode_LicenseDeviceNotConnected

  • fluxEngine_C_v1_ErrorCode_DeviceNoLongerValid

  • fluxEngine_C_v1_ErrorCode_DeviceTypeError

  • fluxEngine_C_v1_ErrorCode_DeviceParameterNotFound

  • fluxEngine_C_v1_ErrorCode_DeviceProcessingInformationMissing

  • fluxEngine_C_v1_ErrorCode_InstrumentDeviceIncompatibleError

  • fluxEngine_C_v1_ErrorCode_DeviceProcessingPreprocessingSetupError

  • fluxEngine_C_v1_ErrorCode_DeviceProcessingInvalidReferenceError

  • fluxEngine_C_v1_ErrorCode_WhiteReferenceDimensionError

  • fluxEngine_C_v1_ErrorCode_DarkReferenceDimensionError

See also

fluxEngine_C_v1_ProcessingContext_create_instrument_hsi_recording()

Parameters

  • device – The instrument device

  • valueType – The requested value type of the data that is to be returned.

  • instrument_parameters – The instrument parameters, mainly the previously measured reference data. The structure must be initialized with zeros, then the structure_size field must be set to the size of the structure, before providing this structure to this function.

  • wavelength_grid – Optional: a list of wavelengths to regularize the wavelengths to. Supply NULL in case the wavelengths of the instrument are to be used and the data should not normalized in this manner.

  • wavelength_count – The number of wavelengths stored in the wavelength_grid parameter. The value here will be ignored if that parameter is set to NULL.

  • result – [out] Where to store the result in. The structure should be initialized with zeros before passing it to this function, but for the structure_size field, which must have been set by the user to the size of the structure.

  • 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

int fluxEngine_C_v1_ProcessingContext_create_instrument_hsi_recording_pqs_ex(fluxEngine_C_v1_Device *device, fluxEngine_C_v1_ProcessingQueueSet *processing_queue_set, fluxEngine_C_v1_ValueType valueType, fluxEngine_C_v1_ProcessingContext_InstrumentParametersEx const *instrument_parameters, double const *wavelength_grid, size_t wavelength_count, fluxEngine_C_v1_ProcessingContext_HSIRecordingResult *result, fluxEngine_C_v1_Error **error)

Create a processing context (HSI and spectrometer data recording)

This function is identical to fluxEngine_C_v1_ProcessingContext_create_instrument_hsi_recording_ex(), but allows the user to specify the processing queue set to use, instead of using the default processing queue set of the handle. Specifying NULL for processing_queue_set will use the default processing queue set of the handle, though.

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_DeviceNoLongerValid

  • fluxEngine_C_v1_ErrorCode_DeviceTypeError

  • fluxEngine_C_v1_ErrorCode_DeviceParameterNotFound

  • fluxEngine_C_v1_ErrorCode_DeviceProcessingInformationMissing

  • fluxEngine_C_v1_ErrorCode_InstrumentDeviceIncompatibleError

  • fluxEngine_C_v1_ErrorCode_DeviceProcessingPreprocessingSetupError

  • fluxEngine_C_v1_ErrorCode_DeviceProcessingInvalidReferenceError

  • fluxEngine_C_v1_ErrorCode_WhiteReferenceDimensionError

  • fluxEngine_C_v1_ErrorCode_DarkReferenceDimensionError

See also

fluxEngine_C_v1_ProcessingContext_create_instrument_hsi_recording()

See also

fluxEngine_C_v1_ProcessingContext_create_instrument_hsi_recording_pqs()

See also

fluxEngine_C_v1_ProcessingContext_create_instrument_hsi_recording_ex()

Parameters

  • device – The instrument device

  • processing_queue_set – The processing queue set to use

  • valueType – The requested value type of the data that is to be returned.

  • instrument_parameters – The instrument parameters, mainly the previously measured reference data. The structure must be initialized with zeros, then the structure_size field must be set to the size of the structure, before providing this structure to this function.

  • wavelength_grid – Optional: a list of wavelengths to regularize the wavelengths to. Supply NULL in case the wavelengths of the instrument are to be used and the data should not normalized in this manner.

  • wavelength_count – The number of wavelengths stored in the wavelength_grid parameter. The value here will be ignored if that parameter is set to NULL.

  • result – [out] Where to store the result in. The structure should be initialized with zeros before passing it to this function, but for the structure_size field, which must have been set by the user to the size of the structure.

  • 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

int fluxEngine_C_v1_ProcessingContext_create_instrument_processing(fluxEngine_C_v1_Device *device, fluxEngine_C_v1_Model *model, fluxEngine_C_v1_ProcessingContext_InstrumentParameters const *instrument_parameters, fluxEngine_C_v1_ProcessingContext **context, fluxEngine_C_v1_Error **error)

Create a processing context (instrument device data processing)

Create a processing context that may be used to directly process data obtained from an instrument with a model.

The model must be of a compatible type to the data returned from the instrument.

The handle associated with the device and the model must be the same.

If the instrument provides data in intensities and the model requires referenced data (the common case) the user must provide a white reference, otherwise context creation will fail.

If the instrument provides data in intensities and the model requires intensity data, any white reference will be ignored.

If the instrument provides pre-referenced data (because it is a virtual instrument returning reflectances, or referencing is performed in hardware) the model must require referenced data (such as reflectances or absorbances), otherwise the context creation will fail.

For HSI cameras and spectrometers: the wavelengths will automatically be regularized onto the grid specified in the model.

This method accepts a structure that contains pointers to fluxEngine_C_v1_BufferContainer objects that contain the actual raw reference data that must be used when the user wants to specify a white reference. There is also fluxEngine_C_v1_ProcessingContext_create_instrument_processing_ex(), which supports reference data provided by 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_LicenseDongleRemoved

  • fluxEngine_C_v1_ErrorCode_LicenseDeviceNotConnected

  • fluxEngine_C_v1_ErrorCode_DeviceNoLongerValid

  • fluxEngine_C_v1_ErrorCode_DeviceTypeError

  • fluxEngine_C_v1_ErrorCode_DeviceParameterNotFound

  • fluxEngine_C_v1_ErrorCode_DeviceProcessingInformationMissing

  • fluxEngine_C_v1_ErrorCode_InstrumentDeviceIncompatibleError

  • fluxEngine_C_v1_ErrorCode_DeviceProcessingPreprocessingSetupError

  • fluxEngine_C_v1_ErrorCode_DeviceProcessingInvalidReferenceError

  • fluxEngine_C_v1_ErrorCode_ProcessingSetupError

See also

fluxEngine_C_v1_ProcessingContext_create_instrument_processing_ex()

Parameters

  • device – The instrument device

  • model – The model to process the data with

  • instrument_parameters – The instrument parameters, mainly the previously measured reference data. The structure must be initialized with zeros, then the structure_size field must be set to the size of the structure, before providing this structure to this function.

  • 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

int fluxEngine_C_v1_ProcessingContext_create_instrument_processing_pqs(fluxEngine_C_v1_Device *device, fluxEngine_C_v1_ProcessingQueueSet *processing_queue_set, fluxEngine_C_v1_Model *model, fluxEngine_C_v1_ProcessingContext_InstrumentParameters const *instrument_parameters, fluxEngine_C_v1_ProcessingContext **context, fluxEngine_C_v1_Error **error)

Create a processing context (instrument device data processing)

This function is identical to fluxEngine_C_v1_ProcessingContext_create_instrument_processing(), but allows the user to specify the processing queue set to use, instead of using the default processing queue set of the handle. Specifying NULL for processing_queue_set will use the default processing queue set of the handle, though.

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_DeviceNoLongerValid

  • fluxEngine_C_v1_ErrorCode_DeviceTypeError

  • fluxEngine_C_v1_ErrorCode_DeviceParameterNotFound

  • fluxEngine_C_v1_ErrorCode_DeviceProcessingInformationMissing

  • fluxEngine_C_v1_ErrorCode_InstrumentDeviceIncompatibleError

  • fluxEngine_C_v1_ErrorCode_DeviceProcessingPreprocessingSetupError

  • fluxEngine_C_v1_ErrorCode_DeviceProcessingInvalidReferenceError

  • fluxEngine_C_v1_ErrorCode_ProcessingSetupError

See also

fluxEngine_C_v1_ProcessingContext_create_instrument_processing_ex()

Parameters

  • device – The instrument device

  • processing_queue_set – The processing queue set to use

  • model – The model to process the data with

  • instrument_parameters – The instrument parameters, mainly the previously measured reference data. The structure must be initialized with zeros, then the structure_size field must be set to the size of the structure, before providing this structure to this function.

  • 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

int fluxEngine_C_v1_ProcessingContext_create_instrument_processing_ex(fluxEngine_C_v1_Device *device, fluxEngine_C_v1_Model *model, fluxEngine_C_v1_ProcessingContext_InstrumentParametersEx const *instrument_parameters, fluxEngine_C_v1_ProcessingContext **context, fluxEngine_C_v1_Error **error)

Create a processing context (instrument device data processing)

Create a processing context that may be used to directly process data obtained from an instrument with a model.

The model must be of a compatible type to the data returned from the instrument.

The handle associated with the device and the model must be the same.

If the instrument provides data in intensities and the model requires referenced data (the common case) the user must provide a white reference, otherwise context creation will fail.

If the instrument provides data in intensities and the model requires intensity data, any white reference will be ignored.

If the instrument provides pre-referenced data (because it is a virtual instrument returning reflectances, or referencing is performed in hardware) the model must require referenced data (such as reflectances or absorbances), otherwise the context creation will fail.

For HSI cameras and spectrometers: the wavelengths will automatically be regularized onto the grid specified in the model.

method accepts a structure that the user can fill with pointers to the raw data of the measured references. There is also fluxEngine_C_v1_ProcessingContext_create_instrument_processing(), which supports reference data in form of fluxEngine_C_v1_BufferContainer objects.

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_DeviceNoLongerValid

  • fluxEngine_C_v1_ErrorCode_DeviceTypeError

  • fluxEngine_C_v1_ErrorCode_DeviceParameterNotFound

  • fluxEngine_C_v1_ErrorCode_DeviceProcessingInformationMissing

  • fluxEngine_C_v1_ErrorCode_InstrumentDeviceIncompatibleError

  • fluxEngine_C_v1_ErrorCode_DeviceProcessingPreprocessingSetupError

  • fluxEngine_C_v1_ErrorCode_DeviceProcessingInvalidReferenceError

  • fluxEngine_C_v1_ErrorCode_WhiteReferenceDimensionError

  • fluxEngine_C_v1_ErrorCode_DarkReferenceDimensionError

  • fluxEngine_C_v1_ErrorCode_ProcessingSetupError

See also

fluxEngine_C_v1_ProcessingContext_create_instrument_processing()

Parameters

  • device – The instrument device

  • model – The model to process the data with

  • instrument_parameters – The instrument parameters, mainly the previously measured reference data. The structure must be initialized with zeros, then the structure_size field must be set to the size of the structure, before providing this structure to this function.

  • 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

int fluxEngine_C_v1_ProcessingContext_create_instrument_processing_pqs_ex(fluxEngine_C_v1_Device *device, fluxEngine_C_v1_ProcessingQueueSet *processing_queue_set, fluxEngine_C_v1_Model *model, fluxEngine_C_v1_ProcessingContext_InstrumentParametersEx const *instrument_parameters, fluxEngine_C_v1_ProcessingContext **context, fluxEngine_C_v1_Error **error)

Create a processing context (instrument device data processing)

This function is identical to fluxEngine_C_v1_ProcessingContext_create_instrument_processing_ex(), but allows the user to specify the processing queue set to use, instead of using the default processing queue set of the handle. Specifying NULL for processing_queue_set will use the default processing queue set of the handle, though.

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_DeviceNoLongerValid

  • fluxEngine_C_v1_ErrorCode_DeviceTypeError

  • fluxEngine_C_v1_ErrorCode_DeviceParameterNotFound

  • fluxEngine_C_v1_ErrorCode_DeviceProcessingInformationMissing

  • fluxEngine_C_v1_ErrorCode_InstrumentDeviceIncompatibleError

  • fluxEngine_C_v1_ErrorCode_DeviceProcessingPreprocessingSetupError

  • fluxEngine_C_v1_ErrorCode_DeviceProcessingInvalidReferenceError

  • fluxEngine_C_v1_ErrorCode_WhiteReferenceDimensionError

  • fluxEngine_C_v1_ErrorCode_DarkReferenceDimensionError

  • fluxEngine_C_v1_ErrorCode_ProcessingSetupError

See also

fluxEngine_C_v1_ProcessingContext_create_instrument_processing()

Parameters

  • device – The instrument device

  • model – The model to process the data with

  • processing_queue_set – The processing queue set to use

  • instrument_parameters – The instrument parameters, mainly the previously measured reference data. The structure must be initialized with zeros, then the structure_size field must be set to the size of the structure, before providing this structure to this function.

  • 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

int fluxEngine_C_v1_ProcessingContext_set_source_data_buffer(fluxEngine_C_v1_ProcessingContext *context, fluxEngine_C_v1_BufferInfo const *buffer_info, fluxEngine_C_v1_Error **error)

Set processing context source data from instrument data buffer.

Set the source data for the next processing step of the instrument device to the provided instrument data buffer. The buffer must not be returned to the device until processing with that source data has completed. (It is allowed to set a different source data and return the buffer without processing it at all though.)

Typically this function will be called in a loop of the following form: 

while (acquisition_active()) {
    r = fluxEngine_C_v1_InstrumentDevice_retrieve_buffer(device, &buffer, timeout, &error);
    if (r < 0) {
        handle_error(error);
        break;
    }
    if (r == 0)
        continue;
    r = fluxEngine_C_v1_ProcessingContext_set_source_data_buffer(context, buffer, &error);
    if (r < 0) {
        (void) fluxEngine_C_v1_InstrumentDevice_return_buffer(device, buffer, NULL);
        handle_error(error);
        break;
    }
    r = fluxEngine_C_v1_ProcessingContext_process_next(context, &error);
    (void) fluxEngine_C_v1_InstrumentDevice_return_buffer(device, buffer, NULL);
    if (r < 0) {
        handle_error_during_processing(error);
        break;
    }
}
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_ProcessingContextTypeMismatch

  • fluxEngine_C_v1_ErrorCode_BufferAlreadyReturned

  • fluxEngine_C_v1_ErrorCode_ProcessingContextNoLongerValid

  • fluxEngine_C_v1_ErrorCode_DeviceProcessingBufferIncompatible

Parameters

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

  • buffer_info – The buffer containing the instrument data

  • 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

int fluxEngine_C_v1_ProcessingContext_set_source_data_buffer_seqid(fluxEngine_C_v1_ProcessingContext *context, fluxEngine_C_v1_BufferInfo const *buffer_info, int64_t sequence_id, fluxEngine_C_v1_Error **error)

Set processing context source data from instrument data buffer (custom sequence id)

This is a specialized version of fluxEngine_C_v1_ProcessingContext_set_source_data_buffer() that allows the user to specify a custom sequence id, instead of using the buffer number as the sequence id.

This method 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 buffers that are being processed. In an ideal world the sequence id will be incremented by 1 between each buffer that is being processed. If the sequence id increases by more than one, the processing logic assumes that buffers have been skipped (because they were lost, for example), and will act accordingly. (This only affects processing when state is tracked between invocations, such as when processing data from pushbroom cameras, which allows filters such as object detectors to work.)

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

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

If a negative number is specified for the sequence id, it is assumed that the user wants to use the frame number stored in the buffer, which will be used in that case.

Parameters

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

  • buffer_info – The buffer containing the instrument data

  • sequence_id – The sequence id to use instead of the frame number

  • 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

int fluxEngine_C_v1_ProcessingContext_set_source_data_persistent_buffer(fluxEngine_C_v1_ProcessingContext *context, fluxEngine_C_v1_PersistentBufferInfo const *persistent_buffer_info, fluxEngine_C_v1_Error **error)

Set processing context source data from persistent data buffer.

This is analogous to fluxEngine_C_v1_ProcessingContext_set_source_data_buffer(), but takes a persistent buffer instead of an instrument buffer as its argument.

Here the user must take care not to deallocate the persistent buffer while it is still set as the source data of the processing context.

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_ProcessingContextTypeMismatch

  • fluxEngine_C_v1_ErrorCode_ProcessingContextNoLongerValid

  • fluxEngine_C_v1_ErrorCode_DeviceProcessingBufferIncompatible

Parameters

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

  • persistent_buffer_info – The persistent buffer containing the source data to process

  • 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

int fluxEngine_C_v1_ProcessingContext_set_source_data_persistent_buffer_seqid(fluxEngine_C_v1_ProcessingContext *context, fluxEngine_C_v1_PersistentBufferInfo const *persistent_buffer_info, int64_t sequence_id, fluxEngine_C_v1_Error **error)

Set processing context source data from persistent data buffer (custom sequence id)

This is a specialized version of fluxEngine_C_v1_ProcessingContext_set_source_data_persistent_buffer() that allows the user to specify a custom sequence id, instead of using the frame number as the sequence id.

This method 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 buffers that are being processed. In an ideal world the sequence id will be incremented by 1 between each buffer that is being processed. If the sequence id increases by more than one, the processing logic assumes that buffers have been skipped (because they were lost, for example), and will act accordingly. (This only affects processing when state is tracked between invocations, such as when processing data from pushbroom cameras, which allows filters such as object detectors to work.)

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

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

If a negative number is specified for the sequence id, it is assumed that the user wants to use the frame number stored in the buffer, which will be used in that case.

Parameters

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

  • persistent_buffer_info – The persistent buffer containing the source data to process

  • sequence_id – The sequence id to use instead of the frame number

  • 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

int fluxEngine_C_v1_BufferContainer_create_from_recording_context(fluxEngine_C_v1_ProcessingContext *context, size_t count, fluxEngine_C_v1_BufferContainer **buffer_container, fluxEngine_C_v1_Error **error)

Create a buffer container from a recording context.

This allows the user to create a buffer container that may be used in conjunction with recording processing contexts (created via fluxEngine_C_v1_ProcessingContext_create_instrument_hsi_recording_ex() or fluxEngine_C_v1_ProcessingContext_create_instrument_hsi_recording()) to record the standardized data.

For example, this may be used to record a HSI cube from a hyperspectral camera, and later save it.

Use fluxEngine_C_v1_BufferContainer_add_last_result() to add the last result of a recording context (after processing a device buffer) to the current buffer container.

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_DeviceNoLongerValid

  • fluxEngine_C_v1_ErrorCode_DeviceTypeError

Parameters

  • context – The processing context to create the buffer container for. It must be a recording context, and the device must be a line camera or similar.

  • count – The capacity of the buffer container in number of results of the recording context. A larger number will lead to the usage of more RAM.

  • buffer_container – [out] The newly created buffer container, which must be freed via fluxEngine_C_v1_BufferContainer_free().

  • error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_BufferContainer_create_from_recording_context_rb(fluxEngine_C_v1_ProcessingContext *context, size_t count, fluxEngine_C_v1_BufferContainer **buffer_container, fluxEngine_C_v1_Error **error)

Create a buffer container from a recording context (ring buffer)

This allows the user to create a buffer container that may be used in conjunction with recording processing contexts (created via fluxEngine_C_v1_ProcessingContext_create_instrument_hsi_recording_ex() or fluxEngine_C_v1_ProcessingContext_create_instrument_hsi_recording()) to record the standardized data.

For example, this may be used to record a HSI cube from a hyperspectral camera, and later save it.

Use fluxEngine_C_v1_BufferContainer_add_last_result() to add the last result of a recording context (after processing a device buffer) to the current buffer container.

This function creates a container that is a ring buffer, so that data may be added continually. Only the last count entries may be retrieved, but the index will always increase.

When passing a ring buffer into fluxEngine (e.g. when creating a measurement), if less than count elements have been added to the ring buffer since the last reset, the buffer behaves identically to a standard buffer container. Otherwise only the last count elements will be used.

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_DeviceNoLongerValid

  • fluxEngine_C_v1_ErrorCode_DeviceTypeError

Parameters

  • context – The processing context to create the buffer container for. It must be a recording context, and the device must be a line camera or similar.

  • count – The capacity of the buffer container in number of results of the recording context. A larger number will lead to the usage of more RAM.

  • buffer_container – [out] The newly created buffer container, which must be freed via fluxEngine_C_v1_BufferContainer_free().

  • error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_BufferContainer_add_last_result(fluxEngine_C_v1_BufferContainer *buffer_container, fluxEngine_C_v1_ProcessingContext *context, fluxEngine_C_v1_Error **error)

Add the last result of a recording context to a BufferContainer.

Given a buffer container that was allocated via fluxEngine_C_v1_BufferContainer_create_from_recording_context() for the same recording context (or a context with the same structure) as the supplied context, add the last result of data standardization to the buffer container.

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_BufferAlreadyReturned

  • fluxEngine_C_v1_ErrorCode_BufferContainerFull

  • fluxEngine_C_v1_ErrorCode_BufferStructureMismatch

Parameters

  • buffer_container – The buffer container

  • context – The processing context whose data to add

  • 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