Processing Contexts

DataType

enum LuxFlux.fluxEngineNET.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:

UInt8

8bit unsigned integer

UInt16

16bit unsigned integer

UInt32

32bit unsigned integer

UInt64

64bit unsigned integer

Int8

8bit signed integer

Int16

16bit signed integer

Int32

32bit signed integer

Int64

64bit signed integer

Float32

32bit IEEE 754 single-precision floating point number

Float64

64bit IEEE 754 double-precision floating point number

ValueType

enum LuxFlux.fluxEngineNET.ValueType

The value type of a given input

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

Values:

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.

Reflectance

Reflectances

The data supplied by the user are reflectances.

RelativeRadiance

Relative Radiances

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

Radiance

Radiances

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

HSICube_StorageOrder

enum LuxFlux.fluxEngineNET.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:

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 the various overloads of ProcessingContext.SetSourceData() 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).

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 the various overloads of ProcessingContext.SetSourceData() 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).

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 the various overloads of ProcessingContext.SetSourceData() 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).

PushBroomFrame_StorageOrder

enum LuxFlux.fluxEngineNET.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:

LambdaX

Wavelengths are in X-direction

The y direction of the frame contains the spatial information.

LambdaY

Wavelengths are in Y-direction

The x direction of the frame contains the spatial information.

TypeConv

class LuxFlux.fluxEngineNET.TypeConv

Type conversion utilities

This class contains static functions that handle data type interactions with the .NET runtime.

Public Static Functions

DataType DataTypeFor (byte unused)

Get the DataType for 8bit unsigned integers

This overload set exists so that the author of a generic method may pass a value of that type to this overload set and obtain the correct data type value.

DataType DataTypeFor (UInt16 unused)

Get the DataType for 16bit unsigned integers

This overload set exists so that the author of a generic method may pass a value of that type to this overload set and obtain the correct data type value.

DataType DataTypeFor (UInt32 unused)

Get the DataType for 32bit unsigned integers

This overload set exists so that the author of a generic method may pass a value of that type to this overload set and obtain the correct data type value.

DataType DataTypeFor (UInt64 unused)

Get the DataType for 64bit unsigned integers

This overload set exists so that the author of a generic method may pass a value of that type to this overload set and obtain the correct data type value.

DataType DataTypeFor (sbyte unused)

Get the DataType for 8bit signed integers

This overload set exists so that the author of a generic method may pass a value of that type to this overload set and obtain the correct data type value.

DataType DataTypeFor (Int16 unused)

Get the DataType for 16bit signed integers

This overload set exists so that the author of a generic method may pass a value of that type to this overload set and obtain the correct data type value.

DataType DataTypeFor (Int32 unused)

Get the DataType for 32bit signed integers

This overload set exists so that the author of a generic method may pass a value of that type to this overload set and obtain the correct data type value.

DataType DataTypeFor (Int64 unused)

Get the DataType for 64bit signed integers

This overload set exists so that the author of a generic method may pass a value of that type to this overload set and obtain the correct data type value.

DataType DataTypeFor (float unused)

Get the DataType for 32bit floating point numbers

This overload set exists so that the author of a generic method may pass a value of that type to this overload set and obtain the correct data type value.

DataType DataTypeFor (double unused)

Get the DataType for 64bit floating point numbers

This overload set exists so that the author of a generic method may pass a value of that type to this overload set and obtain the correct data type value.

DataType DataTypeFor (Type t)

Get the DataType corresponding to a given scalar .NET type

Throws ArgumentException:

BufferScalarType BufferScalarTypeFor (DataType dataType)

Get the BufferScalarType that corresponds to the given DataType

All DataType values will have a corresponding BufferScalarType.

Throws ArgumentException:

DataType Expand (BufferScalarType bufferScalarType)

Expand a BufferScalarType to the closest DataType

If the BufferScalarType is a type that exactly matches a DataType, that will be returned. Otherwise the closest DataType that can hold all values of the given BufferScalarType will be returned. For example, a packed 10bit BufferScalarType would expand to DataType.UInt16.

int SizeOf (DataType dataType)

Get the number of bytes a value of a given data type requires

ProcessingContext

class LuxFlux.fluxEngineNET.ProcessingContext : IDisposable

Processing Context

To process any data with fluxEngine, a processing context is needed. It may be created in various ways using the static methods that start with CreateFor.

After context creation, in general the processing context will work as follows:

• The user calls one of the overloads of ProcessingContext.SetSourceData() to supply the processing context with the next data to process.

• The user calls ProcessingContext.ProcessNext(), to process the source data provided.

• The user then calls ProcessingContext.OutputSinkData() for each output sink in the model they want to access the processing result of. (For instrument recording an/or preview models the output sinks are fixed.)

The user may query metadata of output sinks via the OutputSinkInfos property or the OutputSinkInfoById() method.

Public Types

enum DeviceContextCreationFlags

Device Context Creation Flags

This enumeration contains a list of flags that a user may supply when creating processing contexts for instrument devices. These flags influence the behavior of the context creation. They are specified in the ProcessingContext.InstrumentParameters.CreationFlags field.

Values:

None

No flags set (use default behavior)

AdditionalPreview

Create an additional output sink that generates a preview image after the immediate preprocessing step

Create an additional output sink that generates a preview image after the immediate preprocessing step. This is only allowed for recording processing contexts, where the output sink with index (and id) 1 will be an additional sink that is as if a preview context had been created.

Public Functions

void SetSourceData (Buffer buffer, Int64 overrideSequenceId = -1)

Set the next input data to be processed from instrument device buffer

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.

Param buffer:

The instrument device buffer to use. It must not have been returned by the user to the instrument

Param overrideSequenceId:

The sequence id to use, or -1 if the buffer number stored in the buffer is to be used instead

void SetSourceData (PersistentBuffer buffer, Int64 overrideSequenceId = -1)

Set the next input data to be processed from persistent buffer

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.

Param buffer:

The persistent buffer to use

Param overrideSequenceId:

The sequence id to use, or -1 if the buffer number stored in the buffer is to be used instead

void SetSourceData (MeasurementList measurementList, int measurementIndex)

Set processing context source data from a specific measurement

Sets the source data of a processing context from a given measurement.

This method will typically be called on processing contexts that were created with the ProcessingContext.CreateForMeasurement() method, but it is possible to use it with contexts created via the ProcessingContext.CreateForHSICube method if the measurement is a HSI cube and has the correct structure (same scalar type, same wavelengths, same value type). Note that since all HSI cube measurements are stored in BIP storage order in fluxEngine (even if they were stored in another storage order on disk before they were loaded), contexts created for other storage orders will not be compatible with this method. In that case the user must provide the cube data manually via the SetSourceData() overload that accepts a tensor (and transpose the data outside of fluxEngine beforehand).

Object lifetime note: it is safe to free the measurement list after calling this method, even if processing has not started yet. The data of the measurement will remain in memory (though no copy will be created) until any overload of ProcessingContext.SetSourceData() is called again successfully, ProcessingContext.ResetState() is called, ProcessingContext.ClearSourceData() is called, or the processing context is destroyed.

Param measurementList:

The measurement list

Param measurementIndex:

Indicates which measurement in the list should be used. The first measurement is at index 0.

OutputSinkInfo OutputSinkInfoById (int id)

Get structure and metadata information for an output sink based on its id

If an output sink with that id exists in the model, and the id is unique, this will return the information for that sink. Otherwise an exception will be thrown.

Param id:

The id of the output sink

Return:

The output sink structure and metadata

void SetSourceData (ReadOnlyTensorView data, Int64 sequenceId = -1)

Set the source data of the processing context (tensor)

Sets the source data that should be processed next to the specified tensor. Only a reference to the tensor will be stored in the sink by using this method, to process the data ProcessNext() must be called.

If the tensor’s structure does not match the expected input structure of this context, and exception will be thrown.

Param data:

The tensor to set as the source data

Param sequenceId:

The sequence id to use. If not specified the next sequence id (beyond the one currently set) will be assigned automatically. Sequence ids are mostly revelevant when processing in line-based mode, such as PushBroom cameras, so that dropped frames can be detected and handled appropriately.

void ProcessNext ()

Process the next piece of data

Processes the next piece of data. The source data must have set via one of the overloads of SetSourceData().

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 with index 0 for parallelization purposes.

void ClearSourceData ()

Clear the source data from the processing context

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

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

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

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

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

void ResetState ()

Reset the state of the processing context

This method may only be called in between calls of ProcessNext().

When the data to be processed is in the form of entire HSI cubes, that is, the context was created via the overload of the constructor that indicates HSI cubes should be processed, this method will have no effect. (Unless processing was aborted via 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 overload of the constructor that indicates PushBroom frames should be processed, this method 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.

void Abort ()

Abort processing

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

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

void Wait ()

Wait until processing or an abort is complete

This method 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 ProcessingContext.ProcessNext() 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.

OutputSinkData OutputSinkData (int sinkIndex)

Get the resulting output sink data of a given processing context

See the documentation of the OutputSinkData structure for a detailed discussion on how to interpret the resulting data.

A memory region returned by this method will be invalidated the next time the user performs data processing again, resets the state of the context, or destroys the context

void Dispose ()

Dispose of this object

This will free all resources associated with this object. The object should not be used anymore after a call to this method.

Properties

int OutputSinkCount { get; set; }

The number of output sinks in the processing context.

OutputSinkInfo[] OutputSinkInfos { get; set; }

The structure and metadata of all output sinks in the processing context

The order of the sinks is non-deterministic; it is only stable for the lifetime of a given processing context. Recreating a context from the same model may result in a different order.

Public Static Functions

ProcessingContext CreateForInstrumentPreview (InstrumentDevice device)

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 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 the overload of ProcessingContext.SetSourceData() that takes a Buffer or a PersistentBuffer.

Param device:

The device to create the processing context for

Return:

The processing context that can generate preview data for the instrument device

ProcessingContext CreateForInstrumentPreview (InstrumentDevice device, ProcessingQueueSet processingQueueSet)

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 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 the overload of ProcessingContext.SetSourceData() that takes a Buffer or a PersistentBuffer.

This overload allows the user to specify a processing queue set.

Param device:

The device to create the processing context for

Param processingQueueSet:

The processing queue set to use

Return:

The processing context that can generate preview data for the instrument device

HSIRecordingResult CreateForInstrumentHSIRecording (InstrumentDevice device, ValueType valueType, InstrumentParameters instrumentParameters, double[] wavelengthGrid = null)

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 wavelengthGrid parameter), 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 field of the result will contain the user-requested wavelength grid. If no wavelength grid is provided (the parameter set to null) the Wavelengths member of the result 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 intensity data.

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

• The user requests data in intensities (using the 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 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 the overload of ProcessingContext.SetSourceData() that takes a Buffer or a PersistentBuffer.

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.

Param device:

The instrument device

Param valueType:

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

Param instrumentParameters:

The instrument parameters, mainly the previously measured reference data.

Param wavelengthGrid:

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.

Return:

A result structure containing the processing context as well as the normalized references.

HSIRecordingResult CreateForInstrumentHSIRecording (InstrumentDevice device, ProcessingQueueSet processingQueues, ValueType valueType, InstrumentParameters instrumentParameters, double[] wavelengthGrid = null)

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 wavelengthGrid parameter), 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 field of the result will contain the user-requested wavelength grid. If no wavelength grid is provided (the parameter set to null) the Wavelengths member of the result 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 intensity data.

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

• The user requests data in intensities (using the 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 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 the overload of ProcessingContext.SetSourceData() that takes a Buffer or a PersistentBuffer.

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.

This overload allows the user to specify a processing queue set.

Param device:

The instrument device

Param processingQueues:

The processing queue set to use

Param valueType:

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

Param instrumentParameters:

The instrument parameters, mainly the previously measured reference data.

Param wavelengthGrid:

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.

Return:

A result structure containing the processing context as well as the normalized references.

ProcessingContext CreateForInstrumentProcessing (InstrumentDevice device, Model model, InstrumentParameters instrumentParameters)

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.

Param device:

The instrument device

Param model:

The model to create the processing context for

Param instrumentParameters:

The instrument parameters, mainly the previously measured reference data.

Return:

The processing context that will process data from the instrument with the given model

ProcessingContext CreateForInstrumentProcessing (InstrumentDevice device, ProcessingQueueSet processingQueues, Model model, InstrumentParameters instrumentParameters)

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 overload allows the user to specify a processing queue set.

Param device:

The instrument device

Param processingQueues:

The processing queue set to use

Param model:

The model to create the processing context for

Param instrumentParameters:

The instrument parameters, mainly the previously measured reference data.

Return:

The processing context that will process data from the instrument with the given model

ProcessingContext CreateForMeasurement (MeasurementList measurementList, int measurementIndex, Model model, MeasurementProcessingContextFlag flags)

Create a processing context from a measurement

This will create a processing context from a measurement so that the measurement (and other measurements of the same structure) can be processed with a given model.

This is useful if the user wants to load a measurement from disk, and then immediately process the data. The following example shows how this may be used to process data:

MeasurementList measurements = IO.LoadMeasurementList(handle, format, fileName);
var context = ProcessingContext.CreateForMeasurement(measurements, 0, model,
    MeasurementProcessingContextFlag.None);
context.SetSourceData(measurements, 0);
Context.ProcessNext();

After this code the user may extract the data from the output sinks in the model via the ProcessingContext.OutputSinkData() method.

Note that if the measurement is a HSI cube, the context created by this function will be equivalent to a context created by the standard constructors of the ProcessingContext class, if the structure of the measurement had been specified manually. For this reason the user my also use the ProcessingContext.SetSourceData() overloads that take a tensor to set the source data for a processing context created by this method, not just the overloads that take a MeasurementList.

Param measurementList:

The measurement list

Param measurementIndex:

Indicates which measurement in the list should be used to initialize the processing context. If -1 is specified it will be assumed that the context should be capable of processing all measurements in the list, and an error will occur if the list contains mutually incompatible measurements. The first measurement is at index 0.

Param model:

The model to process the data with

Param flags:

Flags that influence the context creation. This may be MeasurementProcessingContextFlag.None or an arbitrary bitwise or of flags defined in the MeasurementProcessingContextFlag enumeration.

ProcessingContext CreateForMeasurement (MeasurementList measurementList, int measurementIndex, Model model, ProcessingQueueSet queueSet, MeasurementProcessingContextFlag flags)

Create a processing context from a measurement

This will create a processing context from a measurement so that the measurement (and other measurements of the same structure) can be processed with a given model.

This is useful if the user wants to load a measurement from disk, and then immediately process the data. The following example shows how this may be used to process data:

MeasurementList measurements = IO.LoadMeasurementList(handle, format, fileName);
var context = ProcessingContext.CreateForMeasurement(measurements, 0, model,
    processingQueueSet, MeasurementProcessingContextFlag.None);
context.SetSourceData(measurements, 0);
Context.ProcessNext();

After this code the user may extract the data from the output sinks in the model via the ProcessingContext.OutputSinkData() method.

Note that if the measurement is a HSI cube, the context created by this function will be equivalent to a context created by the standard constructors of the ProcessingContext class, if the structure of the measurement had been specified manually. For this reason the user my also use the ProcessingContext.SetSourceData() overloads that take a tensor to set the source data for a processing context created by this method, not just the overloads that take a MeasurementList.

This overload allows the user to specify a processing queue set.

Param measurementList:

The measurement list

Param measurementIndex:

Indicates which measurement in the list should be used to initialize the processing context. If -1 is specified it will be assumed that the context should be capable of processing all measurements in the list, and an error will occur if the list contains mutually incompatible measurements. The first measurement is at index 0.

Param model:

The model to process the data with

Param queueSet:

The processing queue set

Param flags:

Flags that influence the context creation. This may be MeasurementProcessingContextFlag.None or an arbitrary bitwise or of flags defined in the MeasurementProcessingContextFlag enumeration.

ProcessingContext CreateForHSICube (Model model, HSICube_StorageOrder storageOrder, DataType dataType, Int64 height, Int64 width, double[] inputWavelengths, ExplicitInputConfiguration inputConfiguration)

Create a new processing context for HSI cubes

This method 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

This overload will create a context that can only process cubes of the same size.

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

Param model:

The model to use to process data

Param storageOrder:

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

Param dataType:

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

Param height:

The height of the cubes to process

Param width:

The width of the cubes to process

Param inputWavelengths:

The list of wavelengths of the input cubes being processed, in the unit of nanometers

Param inputConfiguration:

Additional information about the input data (the value type, what references are present, the (optional) calibration information of the input)

ProcessingContext CreateForHSICube (Model model, HSICube_StorageOrder storageOrder, DataType dataType, Int64 maxHeight, Int64 height, Int64 maxWidth, Int64 width, double[] inputWavelengths, ExplicitInputConfiguration inputConfiguration)

Create a new processing context for HSI cubes

This method 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

This overload allows the user to use the processing context to process cubes of varying sizes.

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 maxHeight and height , and for maxWidth 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 maxHeight and maxWidth . Note though that if the width and/or the height are not fixed, any supplied white reference will be averaged over that dimension to ensure that it can be applied to any size of cube.

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

Param model:

The model to use to process data

Param storageOrder:

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

Param dataType:

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

Param maxHeight:

The maximum height of a cube that will be processed using this processing context

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

Param maxWidth:

The maximum width of a cube that will be processed using this processing context

Param 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 width to fix the width and indicate it will always be the same for every cube that is being processed.

Param inputWavelengths:

The list of wavelengths of the input cubes being processed, in the unit of nanometers

Param inputConfiguration:

Additional information about the input data (the value type, what references are present, the (optional) calibration information of the input)

ProcessingContext CreateForHSICube (Model model, ProcessingQueueSet processingQueues, HSICube_StorageOrder storageOrder, DataType dataType, Int64 height, Int64 width, double[] inputWavelengths, ExplicitInputConfiguration inputConfiguration)

Create a new processing context for HSI cubes

This method 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

This overload will create a context that can only process cubes of the same size.

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

This overload allows the user to specify a processing queue set to use for processing of this context.

Param model:

The model to use to process data

Param processingQueues:

The processing queue set to use

Param storageOrder:

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

Param dataType:

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

Param height:

The height of the cubes to process

Param width:

The width of the cubes to process

Param inputWavelengths:

The list of wavelengths of the input cubes being processed, in the unit of nanometers

Param inputConfiguration:

Additional information about the input data (the value type, what references are present, the (optional) calibration information of the input)

ProcessingContext CreateForHSICube (Model model, ProcessingQueueSet processingQueues, HSICube_StorageOrder storageOrder, DataType dataType, Int64 maxHeight, Int64 height, Int64 maxWidth, Int64 width, double[] inputWavelengths, ExplicitInputConfiguration inputConfiguration)

Create a new processing context for HSI cubes

This method 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

This overload allows the user to use the processing context to process cubes of varying sizes.

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 maxHeight and height , and for maxWidth 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 maxHeight and maxWidth . Note though that if the width and/or the height are not fixed, any supplied white reference will be averaged over that dimension to ensure that it can be applied to any size of cube.

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

This overload allows the user to specify a processing queue set to use for processing of this context.

Param model:

The model to use to process data

Param processingQueues:

The processing queue set to use

Param storageOrder:

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

Param dataType:

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

Param maxHeight:

The maximum height of a cube that will be processed using this processing context

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

Param maxWidth:

The maximum width of a cube that will be processed using this processing context

Param 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 width to fix the width and indicate it will always be the same for every cube that is being processed.

Param inputWavelengths:

The list of wavelengths of the input cubes being processed, in the unit of nanometers

Param inputConfiguration:

Additional information about the input data (the value type, what references are present, the (optional) calibration information of the input)

ProcessingContext CreateForPushBroomFrame (Model model, PushBroomFrame_StorageOrder storageOrder, DataType dataType, Int64 width, double[] inputWavelengths, ExplicitInputConfiguration inputConfiguration)

Create a new processing context for PushBroom frames

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

Param model:

The model to use to process data

Param storageOrder:

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

Param dataType:

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

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

Param inputWavelengths:

The list of wavelengths of the input cubes being processed, in the unit of nanometers

Param inputConfiguration:

Additional information about the input data (the value type, what references are present, the (optional) calibration information of the input)

ProcessingContext CreateForPushBroomFrame (Model model, ProcessingQueueSet processingQueues, PushBroomFrame_StorageOrder storageOrder, DataType dataType, Int64 width, double[] inputWavelengths, ExplicitInputConfiguration inputConfiguration)

Create a new processing context for PushBroom frames

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

This overload allows the user to specify a processing queue set to use for processing of this context.

Param model:

The model to use to process data

Param processingQueues:

The processing queue set to use

Param storageOrder:

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

Param dataType:

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

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

Param inputWavelengths:

The list of wavelengths of the input cubes being processed, in the unit of nanometers

Param inputConfiguration:

Additional information about the input data (the value type, what references are present, the (optional) calibration information of the input)

class BufferReferenceInput

Device Context Creation: Reference Input in form of Buffer Containers

This structure may be used when the white, dark, and/or illumination references are present in the form of buffer containers and the user wants to specify them in this manner for device creation. This is an alternative to the MemoryReferenceInput that the user may also provide when creating a device processing context.

See also

MemoryReferenceInput

Public Members

BufferContainer WhiteReference = null

The white reference, or null if none is to be used.

BufferContainer DarkReference = null

The darke reference, or null if none is to be used.

BufferContainer IlluminationReference = null

The illumination reference, or null if none is to be used.

class ExplicitInputConfiguration

Explicit Input Configuration

This class describes information about the input data when creating a processing context by explicitly specifying the input structure. (Instead of relying on a loaded meausrement or an instrument device.)

Public Members

ValueType InputValueType = ValueType.Intensity

The value type of the input data.

bool InputIsIlluminationCorrected = false

brief Whether the input data was already illumination corrected

MemoryReferenceInput ReferenceInput = null

The information about the provided references.

CalibrationInfo CalibrationInfo = null

The calibration information of the input data.

class InstrumentParameters

Instrument parameters

These parameters influence how processing contexts related to instruments are created. Primarily the references (white, dark, illumination) are provided by means of this structure.

Public Members

dynamic ReferenceInput = null

The references to use

This may be null if no references are to be provided.

Otherwise this may be either a MemoryReferenceInput structure (that can also be used to create a manual processing context), or a BufferReferenceInput structure.

DeviceContextCreationFlags CreationFlags = DeviceContextCreationFlags.None

The flags that influence the processing context.

class MemoryReferenceInput

Reference Input

This structure describes what reference data is provided when creating a processing context with explicit specification of the data structures.

There are five primary ways to handle referencing of data:

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

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

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

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

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

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

reflectance = intensity / white

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

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

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

corrected = intensity * avg_illumination / illumination

or

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

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

Public Members

ReadOnlyTensorView WhiteReference = null

The white reference data.

ReadOnlyTensorView DarkReference = null

The dark reference data.

ReadOnlyTensorView IlluminationReference = null

The illumination reference data.

class OutputSinkInfo

Output Sink Information

This structure provides metadata for what an output sink returns.

Properties

int Index { get; set; }

The index of the output sink

The index of the output sink is a number between 0 and one less than ProcessingContext.OutputSinkCount that identifies the output sink for this context. Note that the order of the output sinks is not deterministic between context creations (it will only remain stable for the lifetime of the specific processing context), and the user should only use this index to select the correct output sink data, and use the other fields to identify the correct sink. (Unless the model only has one output sink, in which case the index of that sink will always be 0.)

int Id { get; set; }

The id of the output sink

The user may set an id for each output sink when creating the model. The purpose of the id is to help identify the correct output sink when using fluxEngine.

string Name { get; set; }

The name of the output sink

This will contain the user-provided name of the output sink node. If the user did not set their own name, this will typically be something like "Output", "Output 2", or similar.

Int64 InputDelay { get; set; }

The input delay of the output sink

This is only relevant when processing sequences of PushBroom frames, please see advanced topics chapter in the documentation for further details.

dynamic Structure { get; set; }

The structure of the output sink

This will contain either a OutputSinkTensorStructure or a OutputSinkObjectListStructure object, depending on the type of output sink.

OutputSinkTensorStructure TensorStructure { get; set; }

The output sink’s tensor structure

If the output sink does not return tensor data, accessing this property will result in null.

OutputSinkObjectListStructure ObjectListStructure { get; set; }

The output sink’s object list structure

If the output sink does not return object list data, accessing this property will result in null.

class OutputSinkObjectListStructure

Information about the object list structure of an output sink.

Properties

Int64 MaxObjectCount { get; set; }

The maximum number of objects this output sink could return

Note that this number is typically much larger than what will be returned in practice, as this is calculated to capture an absolute limit, taking into account unrealistic geometries.

bool AdditionalDataPresent { get; set; }

Whether additional per-object data is present in the result

Each object may carry additional per-object data with it that has been connected to a second input of the output sink.

Int64? AdditionalDataCount { get; set; }

The number of entries in the additional object data vector

Each object may carry additional per-object data with it that has been connected to a second input of the output sink.

Additional object data will always be a vector of scalar values, whose size is always fixed.

This may be null if there is no additional object data present.

DataType? AdditionalDataType { get; set; }

The scalar data type of additional object data

This may be null if there is no additional object data present.

StatisticsStructure[] Statistics { get; set; }

The per-object statistics structure

For each per-object statistics filter in the chain leading up to the output sink this will contain an entry. The resulting object will have a corresponding entry for each of these entries.

This may be null if no statistics structure is present in the model at this output sink.

QualityStructure Quality { get; set; }

The object’s quality structure

This may be null if no quality data is returned for each object at all.

RegionStructure[] Regions { get; set; }

The region metadata defined for each object

For each region defined in a per-object region averaging filter in the chain leading up to the output sink there will be an entry in this array. The resulting object will have a corresponding entry for each of these entries.

This may be null if no regions are defined in the model at this output sink.

class QualityStructure

Information about the quality data structure of the object list of an output sink.

Properties

DataType DataType { get; set; }

The data type of the quality data

This will be an integer data type that depends on the model that is being processed.

Int64 Count { get; set; }

The number of quality entries present.

Quality data will always be a one-dimensional array.

class RegionStructure

Information about a single region of the object list of an output sink.

Properties

string Prefix { get; set; }

The prefix of the region

This will likely be an empty string at the moment.

string Name { get; set; }

The name of the region as defined by the user

DataType DataType { get; set; }

The data type of the region’s average values

int Order { get; set; }

The tensor order of the region’s average values

This will typically be 1, but not necessarily so.

Int64[] Dimensions { get; set; }

The tensor dimensions of the region’s average values.

double[] ChannelLabels { get; set; }

The channel labels

If the channels of the region are labeled, this will contain the labels of those channels. For example, if spectra are averaged for each region, this will contain the wavelengths of those spectra.

If this is not null then order will be 1 and Dimensions[0] will be equal to the size of this vector. However, this may be empty even if a non-zero amount of channels are returned, in case the channels don’t have numerical labels, or they aren’t unique.

class StatisticsStructure

Information about the statistics data structure of the object list of an output sink

Properties

string Prefix { get; set; }

The prefix specified by the user in the per-object statistics filter.

DataType DataType { get; set; }

The data type of all statistics quantities

This will be either DataType.Float32 or DataType.Float64. The position data of the minima and maxima will always have a data type DataType.Int64, regardless of this value.

int Order { get; set; }

The tensor order of the statistics quantities

This will typically be 1, but not necessarily so.

Int64[] Dimensions { get; set; }

The dimensions of the statistics quantities

class OutputSinkTensorStructure

Information about the tensor structure of an output sink.

Properties

int Order { get; set; }

The order of the tensor.

Int64[] MaxSizes { get; set; }

The maximum sizes.

Indicates the maximum dimensions of the tensor data returned by the output sink.

Int64[] Sizes { get; set; }

The fixed sizes

This will always have the same number of entries as MaxSizes, indicating the order of the tensor. Any entry here that has a positive value indicates that that dimension will always be of that size when the output sink data is read. Otherwise a value of -1 indicates that the size is dynamic and may change at runtime.

Once exception here is when processing PushBroom frames and the output sink is not put after any object operation, then the first entry here will always be 1 (and the other two entries will be positive as well), indicating that for each PushBroom frame there will always be data present, but if the output sink has an input delay (see OutputSinkInfo.InputDelay) the output sink may return no data at all until that input delay has pased.

DataType DataType { get; set; }

The scalar data type of the tensor returned here*.

OutputSinkData

class LuxFlux.fluxEngineNET.OutputSinkData

Output sink data

This structure describes the data that is returned by fluxEngine through output sinks of a model. Currently this may either be tensor data or object list data. This structure has properties and methods that allow the user to access either the tensor or the object list, depending on the output sink.

Public Functions

GenericTensor AsTensorCopy ()

Create a tensor that is a copy of the tensor data in the output sink

Return:

A tensor that is a copy of the output sink data of the output sink’s result

Properties

Int64[] Sizes { get; set; }

The actual sizes of the output data

For object lists this will be a 1D array that only contains the number of objects as its only element. (May be 0.)

For tensors it will contain the dimensions of the tensor.

Int64[] Strides { get; set; }

The actual strides of the output data

For object lists this should be ignored. For tensors it will contain the strides of the tensor.

DataType DataType { get; set; }

The tensor data type of the output data

If the output sink contains object sink data, accessing this property will result in an exception.

unsafe ReadOnlyTensorView AsTensor { get; set; }

A read-only tensor view of the tensor data

If the output sink did not return tensor data, accessing this property will result in an error.

This property is unsafe as it is up to the user to ensure they only access the tensor as long as the processing context is still available and has not yet been used for processing the next batch of data.

OutputObject[] AsObjectList { get; set; }

The list of object’s that were the result of this output sink

Accessing this property when the output sink did not return tensor data will result in an exception.

The size of the result may be 0 if no objects were detected. (When processing data line by line, after processing most lines no objects will have been detected; only when a line has been processed that allowed the detector to detect the end of the object will this array contain one or more entries.)

OutputObject

class LuxFlux.fluxEngineNET.OutputObject

Detected Object

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.

Public Types

enum RegionShape

The shape of an object region.

Values:

Rectangle

The object region is a rectangle.

Ellipse

The object region is an ellipse.

Properties

Int64 BoundingBoxX { get; set; }

The object’s bounding box’s X coordinate of the left boundary (in pixels)

Int64 BoundingBoxY { get; set; }

The object’s bounding box’s Y coordinate of the top boundary (in pixels)

Int64 BoundingBoxWidth { get; set; }

The object’s bounding box’s width (in pixels)

Int64 BoundingBoxHeight { get; set; }

The object’s bounding box’s height (in pixels)

Int64 Area { get; set; }

The object’s area (in pixels)

double GravityCenterX { get; set; }

The object’s center of gravity’s X coordinate (in pixels)

double GravityCenterY { get; set; }

The object’s center of gravity’s Y coordinate (in pixels)

GenericTensor Mask { get; set; }

The object’s mask

This will be a 2D matrix the size of the object’s bounding box, as signed 8bit integers (sbyte in C#). The first dimension describes the Y coordinate, the second the X coordinate. A value of 0 indicates that the object is present in this pixel within the bounding box, a value of -1 indicates that it is not.

The following code demonstrates how to check that a specific pixel within the bounding box is part of the object:

bool present = (obj.Mask.Value<sbyte>(relativeY, relativeX) == (sbyte)0);

Int16? PrimaryClass { get; set; }

The object’s primary class

This may be null if the object has not been classified. But if it has (due to the object detector, or an Object Reclassification Filter), this will contain the numerical index of the group that the object was classified as. A value 0 indicates the first group in the model, a value 1 the second group, etc. A value of -1 indicates that the model was unable to assign a valid class to the object.

StatisticsData[] Statistics { get; set; }

The Per-Object Statistics data of the object

For each Per-Object Statistics Filter in the chain leading up to the output sink this will contain an entry. Each entry will have a corresponding entry in the OutputSinkObjectListStructure.Statistics array in the corresponding output sink information that will contain additional metadata that may be of use.

If no statistics filter is present at all, this may be null.

GenericTensor QualityValues { get; set; }

The object’s quality values

If a Per-Object Decision Graph filter that generates quality values is present in the chain leading up to the output sink this will contain the quality values of the object. If no such filter is present (or the filter does not generate quality values), this will be null.

RegionData[] Regions { get; set; }

The regions within the object

For each region defined in a Object Region Averaging Filter in the chain leading up to the output sink this will contain an entry. Each entry will have a corresponding entry in the OutputSinkObjectListStructure.Regions array in the corresponding output sink information that will contain additional metadata that may be of use.

If no region filter is present at all, this may be null.

class RegionData

The data of a region within the object

When the Per-Object Region Average Filter is used in the chain that lead to the output sink, this structure contains the data for one of the regions that has been averaged within the object.

Properties

RegionShape Shape { get; set; }

The shape of the region.

double CenterX { get; set; }

The X coordinate of the center of the region (in pixels)

This quantity is relative to the top-left of the object’s bounding box.

double CenterY { get; set; }

The Y coordinate of the center of the region (in pixels)

This quantity is relative to the top-left of the object’s bounding box.

double SizeX { get; set; }

The width of the region (in pixels)

double SizeY { get; set; }

The height of the region (in pixels)

GenericTensor Mean { get; set; }

The average data of the region

Typically this tensor will have order 1 and contain a vector of values, one for each channel of the input pixels that were averaged.

This tensor will always contain either 32bit or 64bit floating point numbers, depending on the model.

class StatisticsData

Per-Object Statistics Data

When a Per-Object Statistics Filter was in the chain of filters that lead to the object output, this structure contains the statistics results for that filter.

Properties

GenericTensor Mean { get; set; }

The mean value across the object

Typically this tensor will have order 1 and contain a vector of values, one for each channel of the input pixels that were averaged.

This tensor will always contain either 32bit or 64bit floating point numbers, depending on the model.

GenericTensor StandardDeviation { get; set; }

The standard deviation across the object

Typically this tensor will have order 1 and contain a vector of values, one for each channel of the input pixels that were averaged.

This tensor will always contain either 32bit or 64bit floating point numbers, depending on the model.

GenericTensor Minimum { get; set; }

The minimum values across the object

Typically this tensor will have order 1 and contain a vector of values, one for each channel of the input pixels that were averaged.

This tensor will always contain either 32bit or 64bit floating point numbers, depending on the model.

GenericTensor MinimumX { get; set; }

The X positions of the minimum values across the object (in pixels)

The position is measured relative to the top-left of the object’s bounding box.

Typically this tensor will have order 1 and contain a vector of values, one for each channel of the input pixels that were averaged.

This tensor will always contain 64bit signed integers.

GenericTensor MinimumY { get; set; }

The Y positions of the minimum values across the object (in pixels)

The position is measured relative to the top-left of the object’s bounding box.

Typically this tensor will have order 1 and contain a vector of values, one for each channel of the input pixels that were averaged.

This tensor will always contain 64bit signed integers.

GenericTensor Maximum { get; set; }

The maximum values across the object

Typically this tensor will have order 1 and contain a vector of values, one for each channel of the input pixels that were averaged.

This tensor will always contain either 32bit or 64bit floating point numbers, depending on the model.

GenericTensor MaximumX { get; set; }

The X positions of the maximum values across the object (in pixels)

The position is measured relative to the top-left of the object’s bounding box.

Typically this tensor will have order 1 and contain a vector of values, one for each channel of the input pixels that were averaged.

This tensor will always contain 64bit signed integers.

GenericTensor MaximumY { get; set; }

The Y positions of the maximum values across the object (in pixels)

The position is measured relative to the top-left of the object’s bounding box.

Typically this tensor will have order 1 and contain a vector of values, one for each channel of the input pixels that were averaged.

This tensor will always contain 64bit signed integers.

MeasurementProcessingContextFlag

enum LuxFlux.fluxEngineNET.MeasurementProcessingContextFlag

Flags that influence measurement processing context creation.

Values:

None

Use the default behavior.

VariableSpatialSize

Variable spatial size

When creating a processing context from a measurement that contains something with spatial dimensions (a HSI cube, an image, etc.), this will indicate that the context should accept inputs of sizes that may differ from the measurement that was used to create the context. This is useful if the measurement is only there to provide the same structure (type of measurement, scalar data type, references), but that differently-sized measurements should be accepted for data processing with this context.

Note that the size of the measurement will be used as the maximum size that may be specified, so it is up to the user to create the context from the largest possible measurement.

This is in contrast to the default which assumes that the inputs of the processing context will always have the exact same (fixed) size as the measurement.

IgnoreReferences

Ignore References

Ignore any white and/or dark references when creating the processing context. This is only relevant if the value type of the measurement is either ValueType.Intensity, ValueType.RelativeRadiance, or ValueType.Radiance, as references will be ignored for all other value types anyway.