Devices

DeviceType

enum LuxFlux.fluxEngineNET.DeviceType

The type of the device.

Values:

Instrument

Instrument device

The device in question is an instrument, e.g. a camera or a spectrometer.

LightControl: Light control device

ConnectionSettings

class LuxFlux.fluxEngineNET.ConnectionSettings

Connection settings

This structure must be passed to DeviceGroup.connect() and contains the required information to connect to a given device.

Public Members

string DriverName

The name of the driver

This should be the value taken from the EnumeratedDriver.Name field.

DriverType DriverType

The type of the driver

This should be the value taken from the EnumeratedDriver.Type field.

byte[] Id

The id of the device to connect to

This should be the value taken from the EnumeratedDevice.Id field.

Note that while it may be tempting to hard-code this id instead of reenumerating devices each time, and even if it appears to be the case right now, there is no guarantee that the id is stable across reboots of the machine or even different versions of fluxEngine.

Dictionary<string, string> ConnectionParameters

The connection parameters to use

The key of this dictionary is the name of the parameter; it must be identical to the name of the parameter returned by ParameterInfo.ParameterNames() or the ParameterInfo.Parameter.Name field.

The value of this map is the serialized string of the value of the parameter:

For boolean this must be "True", "On", "Yes", or "1" for true; and "False", "Off", "No", or "0" for false.
For integer parameters this must be the integer converted to a string, e.g. "123" or "-1".
For floating point parameters this must be the floating point value serialized as a string. Scientific notation with e is allowed. The decimal separator is .. The following are valid floating point values: "123", "42.6", and "-146.1468e-43".
For enumeration parameters this must contain the name (not the display name!) of the selected enumeration entry. The name is case-sensitive.
For file parameters (e.g. calibration files) the file name must be specified as a string.

If a parameter is not specified here, its default will be used. There are no defaults for file parameters, and if a file is required for the connection process, the connection attempt will fail.

TimeSpan Timeout

The connection timeout

Typically a value of 60 seconds is a good option here; some devices may be able to connect in less time, but anything less than 10 seconds will nearly always be too short, and for some cameras even 10 seconds is not enough. The actual time required to connect can vary, so it is prudent to use at least three times the amount of time that it takes in a lab environment to connect to a specific device.

If this timeout occurs while the connection is still in progress, the driver subprocess will be terminated (as there is no other way to abort the connection attempt), which could leave the device in an undefined state. It is therefore not recommended to make this extremely short.

bool PassThroughErrorOutput = false

Pass through error output

By default the stderr output stream of the driver will not be passed through to the user. If this is set to true though the error output will be passed through to the error output of the application. This may be useful for debugging.

DeviceGroup

class LuxFlux.fluxEngineNET.DeviceGroup : IDisposable 

Device Group

This structure describes a device group, the result of a connection process. When connecting to a device the actual result of a connection is a device group: the device itself and potentially some subdevices. For example, an instrument device might have a subdevice that is actually a light control device.

Each device group has a primary device that can be obtained via the DeviceGroup.PrimaryDevice property. The primary device will have the type correpsonding to the driver’s primary type. A subdevice may be of a completely different type.

It is possible to completely ignore subdevices.

Public Types

enum NotificationType

Device notification type

This enumeration describes the various types of notifications that devices can generate. Notifications must be retrieved by the user manually via DeviceGroup.NextNotification(), but the handle provided in DeviceGroup.NativeNotificationEventHandle may be used to add notifications to the event loop.

Values:

IrrecoverableError

Irrecoverable error

This notification is generated whenever the device switches into an irrecoverable error state.

Device

class LuxFlux.fluxEngineNET.Device

A device

This base class describes a device that has been connected. The actual class of the device object will be a subclass of this class, depending on the precise type of device.

In addition to attempting to dynamically cast the object to a subclass of the Device class, it is also possible to use the Device.Type property to obtain the device type as an enumeration value.

Pointers to device objects are only valid as long as the device group is still connected. Once the device group is disconnected or the driver unloaded, all device handles will cease to be valid. Accessing them will result in a ObjectNoLongerValidError exception.

Subclassed by LuxFlux.fluxEngineNET.InstrumentDevice, LuxFlux.fluxEngineNET.LightControlDevice

Public Types

enum ParameterListType

Parameter list type

While all device parameters live in the same namespace, there are specific lists of parameters for different purposes. This enumeration describes the different purposes, and parameter information lists can be queried for each type.

When reading and/or writing a parameter it is of no consequence to which type of list the parameter belongs to. A parameter could also be a part of multiple lists.

Values:

Parameter

A standard parameter

This list will contain the parameters that change the behavior of a device. This could be the exposure time of a camera, or the intensity of a light control device.

MetaInfo

Meta information

This list will contain the read-only meta information that is fixed and won’t change while the device is connected. This could be calibration data for the device, but also information about the manufacturer and similar items.

Status

Status information

This list will contain read-only parameters that describe the device’s current status, such as built-in temperature sensors that allow the user to verify the device is in its correct operating range.

Public Functions

void Ping ()

Ping a device

This method ensures that the device is still responsive, without actually performing an action.

This may be used by the user to verify that everything is still OK with the device without performing an action that change something on the device. The user should query the state of the device after this method, even if it is successful.

Throws OutOfMemoryException:
Throws ArgumentException:
Throws Error:
Throws ObjectNoLongerValidError:
Throws DeviceError:

void ResetError ()

Reset a recoverable error

Reset a recoverable error of a device. This method will only work if the device is in a recoverable error state and the error condition has since disappeared.

Throws OutOfMemoryException:
Throws ArgumentException:
Throws Error:
Throws ObjectNoLongerValidError:
Throws DeviceError:

ParameterList ParameterList (ParameterListType type)

Get a specific parameter list of the device

The resulting parameter list is dynamically tied to this device; changing a parameter may change the limits of other parameters and the list will always return the most current data.

Param type:: The type of parameter list to get
Throws OutOfMemoryException:
Throws ArgumentException:
Throws Error:
Throws ObjectNoLongerValidError:
Throws ParameterError:
Return:: The parameter list

ParameterList.Type ParameterType (string name)

Get the type of a parameter

In order to not have to query all parameter lists (and obtain the types of all parameters), this helper method allows the user to quickly determine the type of a parameter by the parameter’s name.

Param name:: The name of the parameter
Throws OutOfMemoryException:
Throws ArgumentException:
Throws Error:
Throws ObjectNoLongerValidError:
Throws ParameterError:
Return:: The parameter’s type

string GetParameterString (string name)

Get a parameter (as a string)

This will return the parameter’s value as a string.

This method will fail for parameters that are inaccessible or write-only (the latter being the case for most command parameters).

If the parameter type is not iself of string type, the value will be converted into a string. See the documentation of ConnectionSettings.ConnectionParameters for details on how this conversion takes place.

Param name:: The name of the parameter
Throws OutOfMemoryException:
Throws ArgumentException:
Throws Error:
Throws ObjectNoLongerValidError:
Throws DeviceError:
Throws ParameterError:
Return:: The parameter’s value (as a string)

Int64 GetParameterInteger (string name)

Get a parameter (as an integer)

This will work for integer and enumeration parameters. In the case of a enumeration parameter this will return the value of the current enumeration entry.

Param name:: The name of the parameter
Throws OutOfMemoryException:
Throws ArgumentException:
Throws Error:
Throws ObjectNoLongerValidError:
Throws DeviceError:
Throws ParameterError:
Return:: The parameter’s integer value

double GetParameterFloat (string name)

Get a parameter (as an floating point value)

This will only work for floating point parameters.

Param name:: The name of the parameter
Throws OutOfMemoryException:
Throws ArgumentException:
Throws Error:
Throws ObjectNoLongerValidError:
Throws DeviceError:
Throws ParameterError:
Return:: The parameter’s float value

bool GetParameterBoolean (string name)

Get a parameter (as an boolean value)

This will only work for boolean parameters.

Param name:: The name of the parameter
Throws OutOfMemoryException:
Throws ArgumentException:
Throws Error:
Throws ObjectNoLongerValidError:
Throws DeviceError:
Throws ParameterError:
Return:: The parameter’s boolean value

bool IsParameterCommandComplete (string name)

Is a command parameter complete

Some commands can be executed in the background (returning from the execute command call earlier than execution is done) and whether they are done can be queried with this method. If the command has already completed, is always executed synchronously (and thus has completed after the command execution function returned), or has never been executed, this method will return as if the command has completed.

Param name:: The name of the parameter
Throws OutOfMemoryException:
Throws ArgumentException:
Throws Error:
Throws ObjectNoLongerValidError:
Throws DeviceError:
Throws ParameterError:
Return:: Whether the command parameter has completed execution

void SetParameterString (string name, string value)

Set a parameter to a string value

If the parameter type is not iself of string type, the value will be converted from a string into its target type. See ConnectionSettings.ConnectionParameters for rules on how different types of parameters are converted.

Note that changing some parameters will cause instrument devices to internally stop acquisition. In that case the status of the device will switch to InstrumentDevice.Status.ForcedStop to indicate this. The user must then call InstrumentDevice.StopAcquisition() to stop acquisition on fluxEngine’s side and may then use InstrumentDevice.StartAcquisition() to restart acquisition in that case. This will definitely happen when a parameter changes the size or structure of the buffer that is returned, but some drivers may require this to be the case for all parameters. To avoid having to check for this state it is therefore recommended that parameters be changed only when acquisition is stopped, although that is not a requirement.

Param name:: The name of the parameter to set
Param value:: The new value of the parameter
Throws OutOfMemoryException:
Throws ArgumentException:
Throws Error:
Throws ObjectNoLongerValidError:
Throws DeviceError:
Throws ParameterError:

void SetParameterInteger (string name, Int64 value)

Set a parameter to an integer value

This only works for integer and enumeration parameters. In the case of an enumeration parmaeter the value of the selected enumeration entry must be provided, and there must be an enumeration entry with that value.

Note that changing some parameters will cause instrument devices to internally stop acquisition. In that case the status of the device will switch to InstrumentDevice.Status.ForcedStop to indicate this. The user must then call InstrumentDevice.StopAcquisition() to stop acquisition on fluxEngine’s side and may then use InstrumentDevice.StartAcquisition() to restart acquisition in that case. This will definitely happen when a parameter changes the size or structure of the buffer that is returned, but some drivers may require this to be the case for all parameters. To avoid having to check for this state it is therefore recommended that parameters be changed only when acquisition is stopped, although that is not a requirement.

Param name:: The name of the parameter to set
Param value:: The new value of the parameter
Throws OutOfMemoryException:
Throws ArgumentException:
Throws Error:
Throws ObjectNoLongerValidError:
Throws DeviceError:
Throws ParameterError:

void SetParameterFloat (string name, double value)

Set a parameter to a floating point value

This only works for floating point parameters.

Note that changing some parameters will cause instrument devices to internally stop acquisition. In that case the status of the device will switch to InstrumentDevice.Status.ForcedStop to indicate this. The user must then call InstrumentDevice.StopAcquisition() to stop acquisition on fluxEngine’s side and may then use InstrumentDevice.StartAcquisition() to restart acquisition in that case. This will definitely happen when a parameter changes the size or structure of the buffer that is returned, but some drivers may require this to be the case for all parameters. To avoid having to check for this state it is therefore recommended that parameters be changed only when acquisition is stopped, although that is not a requirement.

Param name:: The name of the parameter to set
Param value:: The new value of the parameter
Throws OutOfMemoryException:
Throws ArgumentException:
Throws Error:
Throws ObjectNoLongerValidError:
Throws DeviceError:
Throws ParameterError:

void SetParameterBoolean (string name, bool value)

Set a parameter to a boolean value

This only works for boolean parameters.

Note that changing some parameters will cause instrument devices to internally stop acquisition. In that case the status of the device will switch to InstrumentDevice.Status.ForcedStop to indicate this. The user must then call InstrumentDevice.StopAcquisition() to stop acquisition on fluxEngine’s side and may then use InstrumentDevice.StartAcquisition() to restart acquisition in that case. This will definitely happen when a parameter changes the size or structure of the buffer that is returned, but some drivers may require this to be the case for all parameters. To avoid having to check for this state it is therefore recommended that parameters be changed only when acquisition is stopped, although that is not a requirement.

Param name:: The name of the parameter to set
Param value:: The new value of the parameter
Throws OutOfMemoryException:
Throws ArgumentException:
Throws Error:
Throws ObjectNoLongerValidError:
Throws DeviceError:
Throws ParameterError:

void ExecuteParameterCommand (string name)

Execute a command parameter

Note that changing some parameters will cause instrument devices to internally stop acquisition. In that case the status of the device will switch to InstrumentDevice.Status.ForcedStop to indicate this. The user must then call InstrumentDevice.StopAcquisition() to stop acquisition on fluxEngine’s side and may then use InstrumentDevice.StartAcquisition() to restart acquisition in that case. This will definitely happen when a parameter changes the size or structure of the buffer that is returned, but some drivers may require this to be the case for all parameters. To avoid having to check for this state it is therefore recommended that parameters be changed only when acquisition is stopped, although that is not a requirement.

Param name:: The name of the command parameter to execute
Throws OutOfMemoryException:
Throws ArgumentException:
Throws Error:
Throws ObjectNoLongerValidError:
Throws DeviceError:
Throws ParameterError:

Properties

Device[] SubDevices { get; set; }

All subdevices of this device

This is likely an empty list.

DeviceType Type { get; set; }

The device type

Throws OutOfMemoryException:
Throws ArgumentException:
Throws Error:
Throws ObjectNoLongerValidError:
Throws DeviceError:

string Manufacturer { get; set; }

The device’s manufacturer

Throws OutOfMemoryException:
Throws ArgumentException:
Throws Error:
Throws ObjectNoLongerValidError:

string Model { get; set; }

The device model.

Throws OutOfMemoryException:
Throws ArgumentException:
Throws Error:
Throws ObjectNoLongerValidError:

string Description { get; set; }

The device description

Some devices may have an additional description that they may return. If that is not present, this will be null.

Throws OutOfMemoryException:
Throws ArgumentException:
Throws Error:
Throws ObjectNoLongerValidError:

string SerialNumber { get; set; }

The device’s serial number

Some devices may have no serial number (in which case this will be null), but instrument devices will typically all have one.

If a serial number is available during device enumeration it will be identical to the serial number returned here. However it is possible for a device to have a serial number that cannot be obtained during enumeration, so that it is only accessible after the device has already been connected.

Throws OutOfMemoryException:
Throws ArgumentException:
Throws Error:
Throws ObjectNoLongerValidError:

InstrumentDevice

class LuxFlux.fluxEngineNET.InstrumentDevice : LuxFlux.fluxEngineNET.Device 

Instrument Device

An instrument device is a device that allows the user to perform measurements and use the measured data. This includes spectrometers, cameras, but also other sensors.

Each measurement result is stored in a buffer (see the Buffer class for details) that can be retrieved from the instrument. The measurements are added to a queue, and the user may retrieve each measurement from that queue, use that data, and then return the buffer to the system so it may be used for future measurements.

In order to obtain data from an instrument device, the following steps need to be taken:

The buffers need to be set up initially. This may be done via the InstrumentDevice.SetupInternalBuffers() method.
The user starts acquisition using the InstrumentDevice.StartAcquisition() method.
In a loop the user first retrieves a buffer via the InstrumentDevice.RetrieveBuffer() method, then uses that buffer, and finally returns the buffer via the InstrumentDevice.ReturnBuffer() method
The user may stop data acquisition via the InstrumentDevice.StopAcquisition() method

Public Types

enum Status

Instrument device status.

Values:

Invalid

The device handle is invalid

This can happen if the fluxEngine handle is closed while the device was still connected. In that case the device is forcibly disconnected and will have this status.

IrrecoverableError

Irrecoverable error occurred

An error occurred that can’t be easily recovered from. For example, if a device is unplugged mid-use, this will be the status the device will have.

Note that it may be possible to reconnect to the device in that case, but the device group must be disconnected first if the state of a device changes in this manner.

RecoverableError

Recoverable error occurred

If an error occurred (for example a strict temperature limit has been exceeded) that can be recovered from (by resetting the device via Device.ResetError()) then this will be the status the device will have.

Idle

The instrument is idle

The instrument is idle and not returning data.

Busy

The instrument is busy with an operation

This state will never last very long, but in some cases a parameter change may trigger an operation that happens on the device in the background, and during that operation this will be the state of the device. The device will automatically return to its previous state after the operation has completed. (This is rare.)

Streaming

The instrument is streaming data

The instrument is streaming data to the user.

ForcedStop

The instrument was forced to stop

A parameter change caused the instrument to stop. In that case the user must also stop acquisition on their end and start it again. The structure of the individual buffers that the instrument returns may have changed.

Any processing context created for use with the instrument may not be applicable anymore. (It may still be possible to supply the device’s data to the processing context if the size and scalar type match, but the processing context will likely not perform the correct operations.)

Public Functions

DimensionLabelInfo RawBufferDimensionLabels (int dimension)

Get the labels associated with a dimension of the raw buffer of an instrument device

This information may be useful if the raw image of the camera is to be displayed to the user. For example, if the instrument is a HSI PushBroom type camera, one of the two dimensions of the raw frame will correspond to the wavelengths (before corrections are applied) of the device. While corrections may be applied during the pre-processing steps on top of this, it may still be useful to give the user an indication of what they are looking at at the moment.

See the DimensionLabelInfo structure for further details.

Param dimension:: Which dimension to obtain the label information for. It must be between 0 and one less than the tensor order of the raw data, as may be obtained via the size of the InstrumentDevice.RawBufferDimensions array.
Throws OutOfMemoryException:
Throws ArgumentException:
Throws Error:
Throws ObjectNoLongerValidError:
Throws DeviceError:
Throws InstrumentDeviceError:
Return:: The labels associated with the selected dimensions

PersistentBuffer AllocatePersistentBuffer ()

Allocate a persistent buffer info

Allocate a memory region that is large enough to fit a buffer that is returned by the instrument upon acquisition. This may be used by the user to pre-allocate memory to later copy data into.

Note that the allocated PersistentBuffer will have the size of the instrument with respect to the current set of parameters — if a parameter is changed that causes the size to change, the buffers returned by the instrument will no longer match the persistent buffer.

The contents of the persistent buffer will be initialized with zero and the buffer number will be set to -1.

Throws OutOfMemoryException:
Throws ArgumentException:
Throws Error:
Throws ObjectNoLongerValidError:
Throws DeviceError:
Throws InstrumentDeviceError:
Return:: The newly allocated persistent buffer

void SetupInternalBuffers (int count)

Setup internal buffers for the device

This will allocate the shared memory region that is used by the driver and fluxEnigne to transfer data from the instrument. The number of buffers can be specified in the count parameter, but must be at least 5. The size of the shared memory region will be buffer_size_page * count + overhead, where buffer_size_page is the size InstrumentDevice.MaxBufferSize rounded up to the minimal size of a virtual memory mapping (on Windows this will always be 65536 bytes, on other operating systems this will be the page size, which is typically between 4096 bytes and 65536 bytes), and overhead is as comparatively small overhead used for bookkeeping. As the amount of shared memory in the system is limited, the user should never specify an excessively large number of buffers, but numbers ranging from 5 to 100 are typically considered acceptable in their memory consumption, assuming that a buffer will only have a size of at most a couple of MB.

Important: this method may only be called once and the device group has to be disconnected to choose a different number of buffers. It is recommended to use the largest number that may be requried here, because the number of buffers that is actually used can be varied when starting acquisition.

Param count:: The number of buffers to allocate
Throws OutOfMemoryException:
Throws ArgumentException:
Throws Error:
Throws ObjectNoLongerValidError:
Throws DeviceError:
Throws InstrumentDeviceError:

void StartAcquisition (AcquisitionParameters parameters)

Start acquisition

Starts acquisition on the device. Once data is received from the driver the internal buffer queue will start to fill and data may be retrieved via the InstrumentDevice.RetrieveBuffer() method.

Param parameters:: The parameters for starting acquisition, such as the number of buffers to use for this specific acquisition. See the documentation of AcquisitionParameters for details.
Throws OutOfMemoryException:
Throws ArgumentException:
Throws Error:
Throws ObjectNoLongerValidError:
Throws DeviceError:
Throws InstrumentDeviceError:

void StopAcquisition ()

Stop acquisition

It is safe to call this method if acquisition is not active, in which case this method will not do anything.

Throws OutOfMemoryException:
Throws ArgumentException:
Throws Error:
Throws ObjectNoLongerValidError:
Throws DeviceError:
Throws InstrumentDeviceError:

Buffer RetrieveBuffer (TimeSpan timeout)

Retrieve a buffer from the device

Acquisition must be active for this to succeed.

If the device did not queue any new buffers withing the specified timeout, the method will return null to indicate that there is no buffer present.

The buffer retrieved here must be returned via InstrumentDevice.ReturnBuffer() after the user has no more use for it, otherwise data acquisition from the device will stall.

Param timeout:: How long to wait before returning without a buffer. The actual wait might be larger than this, depending on the scheduler of the operating system.
Throws OutOfMemoryException:
Throws ArgumentException:
Throws Error:
Throws ObjectNoLongerValidError:
Throws DeviceError:
Throws InstrumentDeviceError:
Return:: The buffer that was retrieved. The user must check whether the result is null, as that will indicate that no buffer was returned within the specified timeout.

Buffer RetrieveBuffer (TimeSpan timeout, Func<bool> abortCheckFunction)

Retrieve a buffer from the device

Acquisition must be active for this to succeed.

The buffer retrieved here must be returned via InstrumentDevice.ReturnBuffer() after the user has no more use for it, otherwise data acquisition from the device will stall.

This method will call an abort check function during the wait time to see if the user has externally aborted acquisition in the mean time. That function will be called quite often and should be light-weight, such as reading an atomic flag.

Param timeout:: How long to wait before returning without a buffer. The actual wait might be larger than this, depending on the scheduler of the operating system.
Param abortCheckFunction:: The function that checks whether an external abort of the wait has been initiated. If the function returns true an external abort has been requested. (If a function that returns only false is provided, this method will behave identical to the overload without the abort function.)
Throws OutOfMemoryException:
Throws ArgumentException:
Throws Error:
Throws ObjectNoLongerValidError:
Throws DeviceError:
Throws InstrumentDeviceError:
Return:: The buffer that was retrieved. The user must check whether the result is null, as that will indicate that no buffer was returned within the specified timeout.

void ReturnBuffer (Buffer buffer)

Return a buffer to the instrument

This returns a buffer to the instrument device. The user must not attempt to access the buffer after they have returned it via this method.

Param buffer:: The buffer to return
Throws OutOfMemoryException:
Throws ArgumentException:
Throws Error:
Throws ObjectNoLongerValidError:
Throws DeviceError:
Throws InstrumentDeviceError:

void SetCalibrationInfo (CalibrationInfo calibrationInfo)

Set the current calibration info for an instrument device

The calibration info is not used immediately, but stored, so that any processing context that is created for this device in the future will use that calibration info.

This will not affect any processing context that has already been created.

Param calibrationInfo:: The calibration information to set for the device
Throws OutOfMemoryException:
Throws ArgumentException:
Throws Error:
Throws ObjectNoLongerValidError:
Throws DeviceError:
Throws InstrumentDeviceError:

Properties

Status CurrentStatus { get; set; }

The current status of an instrument device.

Throws OutOfMemoryException:
Throws ArgumentException:
Throws Error:
Throws DeviceError:
Throws InstrumentDeviceError:

UInt64 MaxBufferSize { get; set; }

The maximum buffer size (in bytes) that the instrument may return

This is the maximum size (in bytes) that the device may require to return data to the user. This size is guaranteed to be large enough that regardless of how the device is parametrized it will always be able to hold the data of a single buffer.

Throws OutOfMemoryException:
Throws ArgumentException:
Throws Error:
Throws ObjectNoLongerValidError:
Throws DeviceError:
Throws InstrumentDeviceError:

int RecommendedBufferCount { get; set; }

The number of recommended buffers

This is a number that the driver recommends the user use for operating the device. This does not apply to recording mode, where it is convenient to use a larger number of buffers.

Throws OutOfMemoryException:
Throws ArgumentException:
Throws Error:
Throws ObjectNoLongerValidError:
Throws DeviceError:
Throws InstrumentDeviceError:

Int64[] RawBufferDimensions { get; set; }

The current dimensions of the buffer returned by an instrument

The tensor order will correspond to the number of elements in the array. An empty array is a valid result: there can be instruments that just return a single scalar value.

Throws OutOfMemoryException:
Throws ArgumentException:
Throws Error:
Throws ObjectNoLongerValidError:
Throws DeviceError:
Throws InstrumentDeviceError:
Return:: The current dimensions of the buffer

float > RawBufferValueRange { get; set; }

The value range associated with the data in the raw buffer of an instrument device

This will return the lowest possible value (which will likely be 0) and the highest possible value that a given instrument device may return in a raw buffer.

This information may be used to provide automatic scaling of raw data of the instrument that is being shown to the user, for example.

Note that this information must be provided by the driver and it may not always be possible to obtain it. In that case the limits will be set to exactly the same value to indicate this. (For example both may be set to 0 or 1 would indicate that the driver cannot provide this information.)

The result will be stored in a tuple, where the first item is the lower limit, and the second item is the upper limit.

Throws OutOfMemoryException:
Throws ArgumentException:
Throws Error:
Throws ObjectNoLongerValidError:
Throws DeviceError:
Throws InstrumentDeviceError:

BufferScalarType RawBufferScalarType { get; set; }

the current scalar type of the buffer returned by an instrument

Throws OutOfMemoryException:
Throws ArgumentException:
Throws Error:
Throws ObjectNoLongerValidError:
Throws DeviceError:
Throws InstrumentDeviceError:

class AcquisitionParameters

Acquisition parameters

These parameters are to be supplied when starting acquisition. They may influence the acquisition process in some manner.

Public Members

string ReferenceName

The name of the reference to measure

Some drivers may react differently when they know a reference is to be measured during the next acquisition. For example, the virtual pushbroom camera driver will return the data of the reference cubes instead of the main cube when a reference is to be measured. But even drivers for real hardware may react differently: some cameras may have an integrated shutter that they can close, and during dark reference measurement this is what will happen in that case.

If this is null this indicates that a normal (non-reference) measurement is to be performed.

Otherwise this must be either "WhiteReference", "IlluminationReference", or "DarkReference".

In most cases it does not make any difference whether a reference measurement is to be performed or not, and there is no effect of this setting. The user is also not required to perform the reference measurements in this manner — if the special functionality associated (e.g. shutter for dark reference measurements) is not required (because the user just shuts off the light, for example), then the user may perform the reference measurement by just normal acquisition.

UInt64 BufferCount = 0

The number of buffers to use

If this is 0, all of the buffers that have been created in the shared memory region will be used during acquisition. If this is non-zero only this amount of buffers will be used, instead. If this is larger than the amount of buffers allocated in shared memory, starting acquisition will fail.

This may be useful to allocate more buffers for recording purposes while setting up the shared memory, but only use a lesser amount during processing.

The amount of buffers trades off latency for dropped buffers: the more buffers are used in shared memory, the less likely it is that a buffer may be dropped due to timing issues, as more buffers are available. For recording data it is generally useful to use more buffers. (Though too many buffers will result in too much RAM usage.) Unfortunately more buffers increases the latency of data processing, so if a low latency is required it is better to use less buffers.

The minimum number of buffers that may be used is 5; if the number is lower 5 buffers will be used regardless.

BufferScalarType

enum LuxFlux.fluxEngineNET.BufferScalarType

Buffer scalar data type

Buffers that are retrieved from instruments may have a specific scalar type associated with them. This is a superset of the DataType enumeration, which only covers the data types that can be used in processing.

However, some drivers may write the transported data directly into the buffer — and sometimes the transported data is of a specific packed type.

There are currently no drivers that return data of a type that is not also a standard scalar type, and the enumeration currently does not contain any types other than those also in the DataType enumeration, this will change in future versions.

Values:

Unsupported

The scalar type is not supported by the public API

The type that the driver returns is not supported by the public API of fluxEngine. This could be because fluxEngine does not support the type yet due to being older than the driver, or because support to the public API has not been added yet.

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

Buffer

class LuxFlux.fluxEngineNET.Buffer

Buffer.

This structure describes a buffer the user has retrieved from an instrument device during acquisition.

Any buffer that has been successfully retrieved must be returned to the instrument via InstrumentDevice.ReturnBuffer().

Public Functions

unsafe void CopyInto (IntPtr memory, DataType dataType, Int64[] strides)

Copy and expand the raw data of the buffer into a user-supplied memory area

Calling this method is useful if the user wants to use the raw data of the buffer, but does not want to handle all possible scalar types (especially packed types) that fluxEngine supports. In that case the user may set the dataType parameter to a floating point type (32bit or 64bit) and the data will automatically be converted into that format.

This method takes a direct memory pointer as an argument, so its use is considered unsafe. The target memory supplied must be pinned so that the .NET garbage collector does not automatically move it around while it is being accessed by this method, otherwise this could cause the program to crash.

Param memory:: A pointer into memory where the data is to be stored. It is assumed that the user has allocated a region of sufficient size where this will be stored. (The size is given by the total number of elements in this buffer, multiplied by size of the requested scalar type.)
Param dataType:: The target data type of the memory area provided by the user. An automatic conversion will take place if the type is not the same as the type of the data in the buffer.
Param strides:: The stride structure of the user-supplied memory area.

unsafe void CopyInto (IntPtr memory, DataType dataType)

Copy and expand the raw data of the buffer into a user-supplied memory area

Calling this method is useful if the user wants to use the raw data of the buffer, but does not want to handle all possible scalar types (especially packed types) that fluxEngine supports. In that case the user may set the dataType parameter to a floating point type (32bit or 64bit) and the data will automatically be converted into that format.

This method takes a direct memory pointer as an argument, so its use is considered unsafe. The target memory supplied must be pinned so that the .NET garbage collector does not automatically move it around while it is being accessed by this method, otherwise this could cause the program to crash.

This overload of the method assumes that the strides of the target memory area are trivial (i.e. the tensor will be stored contiguously in that area).

Param memory:: A pointer into memory where the data is to be stored. It is assumed that the user has allocated a region of sufficient size where this will be stored. (The size is given by the total number of elements in this buffer, multiplied by size of the requested scalar type.)
Param dataType:: The target data type of the memory area provided by the user. An automatic conversion will take place if the type is not the same as the type of the data in the buffer.

void CopyInto (PersistentBuffer target)

Copy the contents of the buffer into a persistent buffer

This function copies the data of a buffer into a persistent buffer. The user must ensure that the dimensions and type of the target buffer match the source buffer.

All data in the target will be overwritten.

Important: it is up to the user to ensure that this function is not called while the target persistent buffer is accessed from another thread.

Param target:: The persistent buffer to copy the data into

PersistentBuffer Copy ()

Copy the contents of the buffer into a new persistent buffer

This method allocates a new persistent buffer that has the correct size and type for the data in the buffer and returns the result.

Return:: The new persistent buffer

GenericTensor TensorCopy ()

Create a copy of data in this buffer

This copies the data in this buffer and returns it in tensor form. In contrast to the TensorView property this method is safe, since the buffer may be returned after the tensor has been returned.

Return:: A tensor that contains a copy of the data in this buffer

void CopyInto (GenericTensor tensor)

Copy the data of this buffer into a pre-existing tensor

The tensor must have the correct structure for this copy to work. No allocations will be performed by this method, as the existing storage will be reused.

Param tensor:: The tensor to copy the data into

Properties

Int64 Number { get; set; }

The number of the buffer.

For cameras this corresponds to the frame number of the recorded frame. This may be used to detect frame drops.

BufferScalarType ScalarType { get; set; }: The scalar type of the data in the buffer.

int Order { get; set; }: The tensor order of the data in the buffer.

Int64[] Dimensions { get; set; }

The dimensions of the data in the buffer

The length of this array will be the same as Order.

Int64[] Strides { get; set; }

The strides of the data in the buffer

The length of this array will be the same as Order.

unsafe IntPtr RawDataPointer { get; set; }

The pointer to the first element in the buffer

This is a pointer directly into memory for efficient access to the data in the buffer. Use this for maximum performance in unsafe code.

UIntPtr RawDataByteCount { get; set; }

The number of bytes in the buffer

This is useful if the user wants to make a copy of the data in the buffer for later use, without having to care about the specific data type.

unsafe ReadOnlyTensorView TensorView { get; set; }

A tensor view of the data in this buffer

If the data in this buffer is stored in a non-packed scalar type, this will contain a tensor view of the data that the user may use to access the values directly. The tensor view wraps the buffer’s raw storage directly, which is why this property is marked as unsafe. It is up to the user to ensure that the tensor view is not used anymore after the buffer is returned.

PersistentBuffer

class LuxFlux.fluxEngineNET.PersistentBuffer : IDisposable 

Persistent Buffer Info

This structure describes a buffer that was copied into is own allocated memory region from a device buffer.

The user will never create such a buffer directly, but will obtain it via one of the following methods:

InstrumentDevice.AllocatePersistentBuffer()
Buffer.Copy()
PersistentBuffer.Clone()
BufferContainer.CopyBuffer()

A persistent buffer will remain valid even after any other object has been freed. It is possible to close the last fluxEngine handle and still access a persistent buffer.

The structure of a persistent buffer cannot be changed, but new data can be copied into it, assuming it has the correct structure.

Public Functions

PersistentBuffer Clone ()

Clone a persistent buffer

This will create a copy of the current persistent buffer, including the data contained in it.

unsafe void CopyInto (IntPtr memory, DataType dataType, Int64[] strides)

Copy and expand the raw data of the buffer into a user-supplied memory area

Calling this method is useful if the user wants to use the raw data of the buffer, but does not want to handle all possible scalar types (especially packed types) that fluxEngine supports. In that case the user may set the dataType parameter to a floating point type (32bit or 64bit) and the data will automatically be converted into that format.

This method takes a direct memory pointer as an argument, so its use is considered unsafe. The target memory supplied must be pinned so that the .NET garbage collector does not automatically move it around while it is being accessed by this method, otherwise this could cause the program to crash.

Param memory:: A pointer into memory where the data is to be stored. It is assumed that the user has allocated a region of sufficient size where this will be stored. (The size is given by the total number of elements in this buffer, multiplied by size of the requested scalar type.)
Param dataType:: The target data type of the memory area provided by the user. An automatic conversion will take place if the type is not the same as the type of the data in the buffer.
Param strides:: The stride structure of the user-supplied memory area.

unsafe void CopyInto (IntPtr memory, DataType dataType)

Copy and expand the raw data of the buffer into a user-supplied memory area

Calling this method is useful if the user wants to use the raw data of the buffer, but does not want to handle all possible scalar types (especially packed types) that fluxEngine supports. In that case the user may set the dataType parameter to a floating point type (32bit or 64bit) and the data will automatically be converted into that format.

This method takes a direct memory pointer as an argument, so its use is considered unsafe. The target memory supplied must be pinned so that the .NET garbage collector does not automatically move it around while it is being accessed by this method, otherwise this could cause the program to crash.

This overload of the method assumes that the strides of the target memory area are trivial (i.e. the tensor will be stored contiguously in that area).

Param memory:: A pointer into memory where the data is to be stored. It is assumed that the user has allocated a region of sufficient size where this will be stored. (The size is given by the total number of elements in this buffer, multiplied by size of the requested scalar type.)
Param dataType:: The target data type of the memory area provided by the user. An automatic conversion will take place if the type is not the same as the type of the data in the buffer.

void CopyInto (PersistentBuffer target)

Copy the contents of the persistent buffer into a different persistent buffer

This function copies the data of a buffer into a persistent buffer. The user must ensure that the dimensions and type of the target buffer match the source buffer.

All data in the target will be overwritten.

Important: it is up to the user to ensure that this function is not called while the target persistent buffer is accessed from another thread.

Param target:: The persistent buffer to copy the data into

GenericTensor TensorCopy ()

Create a copy of the data in this buffer

Return:: A tensor that contains a copy of the data in this buffer

void CopyInto (GenericTensor tensor)

Copy the data of this buffer into a pre-existing tensor

The tensor must have the correct structure for this copy to work. No allocations will be performed by this method, as the existing storage will be reused.

Param tensor:: The tensor to copy the data into

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

Int64 Number { get; set; }

The number of the buffer

For cameras this corresponds to the frame number of the recorded frame. This may be used to detect frame drops.

int Order { get; set; }

The tensor order of the buffer

For raw buffers of spectrometers this will be 1.

For raw buffers of cameras this will be 2.

Int64[] Dimensions { get; set; }

The dimensions of the data in the buffer

The length of this array will be identical to Order of this buffer.

Int64[] Strides { get; set; }

The strides of the data in the buffer

The length of this array will be identical to Order of this buffer.

BufferScalarType ScalarType { get; set; }: The scalar type of the data in the buffer.

unsafe IntPtr RawDataPointer { get; set; }

The pointer to the first element in the buffer

This is a pointer directly into memory for efficient access to the data in the buffer. Use this for maximum performance in unsafe code.

UIntPtr RawDataByteCount { get; set; }

The number of bytes in the buffer

This is useful if the user wants to make a copy of the data in the buffer for later use, without having to care about the specific data type.

ReadOnlyTensorView TensorView { get; set; }

A tensor view of this persistent buffer

The tensor view will reference this object, so the memory can only be freed once all tensor views have been freed.

If the buffer stores data in a packed scalar type (that can not be directly mapped onto a DataType, an exception will be thrown.

BufferContainer

class LuxFlux.fluxEngineNET.BufferContainer : IDisposable 

Buffer Container

This structure describes a buffer that may be used to record multiple buffers itself. It abstracts away the required data type handling and may be supplied as reference data when creating processing contexts for device processing.

To create a BufferContainer the user should use the Util.CreateBufferContainer() method that creates a buffer container for the current buffer size of a given instrument device.

Public Functions

void Clear ()

Clear the buffer container

This remove all data in the buffer container, allowing it to be reused.

void Add (Buffer buffer)

Add a device buffer to the buffer container

Add a device buffer to the buffer container. This will increase the count of the buffer container by 1.

The data in the buffer is copied into the container. The device buffer may be returned to the device afterwards without affecting this object.

Param buffer:: The buffer to add

void Add (PersistentBuffer buffer)

Add a persistent buffer to the buffer container

Add a persistent buffer to the buffer container. This will increase the count of the buffer container by 1.

The data in the buffer is copied into the container. The persistent buffer may be modified and/or destroyed afterwards without affecting this object.

unsafe void AddRaw (IntPtr data, BufferScalarType type, Int64[] dimensions, Int64[] strides)

Add raw data to the buffer container

This exists mainly for the case where the user wants to copy the data of a device buffer into internal memory and then later add it to a buffer container object.

This method takes a direct memory pointer as an argument, so its use is considered unsafe. The target memory supplied must be pinned so that the .NET garbage collector does not automatically move it around while it is being accessed by this method, otherwise this could cause the program to crash.

The data provided is copied into the container.

Param data:: A pointer to the data to add. The pointer must point to a memory region that is large enough to contain the data that is to be added.
Param type:: The scalar type of the data to add
Param dimensions:: The dimensions of the data to add. This must match what the buffer container expects
Param strides:: The strides of the data to add. The length of the stride array must be equal to the lenth of the dimensions array.

unsafe void AddRaw (IntPtr data, BufferScalarType type, Int64[] dimensions)

Add raw data to the buffer container

This exists mainly for the case where the user wants to copy the data of a device buffer into internal memory and then later add it to a buffer container object.

This method takes a direct memory pointer as an argument, so its use is considered unsafe. The target memory supplied must be pinned so that the .NET garbage collector does not automatically move it around while it is being accessed by this method, otherwise this could cause the program to crash.

The data provided is copied into the container.

This overload assumes that the data is stored contiguously in memory and has a trivial stride structure.

Param data:: A pointer to the data to add. The pointer must point to a memory region that is large enough to contain the data that is to be added.
Param type:: The scalar type of the data to add
Param dimensions:: The dimensions of the data to add. This must match what the buffer container expects

void AddLastResult (ProcessingContext context)

Add the last result of a recording context to a BufferContainer

Given a buffer container that was allocated via the overload of Util.CreateBufferContainer() that accepts a ProcessingContext, add the last result of data standardization to the buffer container. The processing context provided here must either be the same as the one used to create the buffer container, or at the very least have exactly the same output structure.

Param context:: The processing context whose data to add

unsafe void CopyInto (IntPtr data, UIntPtr dataSize)

Copy the data of the entire buffer container into a new memory region

This will copy all data in the buffer container into a new memory region. If the buffer container is empty this function will have no effect.

This method takes a direct memory pointer as an argument, so its use is considered unsafe. The target memory supplied must be pinned so that the .NET garbage collector does not automatically move it around while it is being accessed by this method, otherwise this could cause the program to crash.

Param data:: A pointer into memory where the data is to be stored. It is assumed that the user has allocated a region of sufficient size where this will be stored.
Param dataSize:: The size of the target memory region, in bytes. This is used to check if the region is large enough to copy the data into.

GenericTensor TensorCopy ()

Create a tensor copy of the contents of the entire buffer container

Return:: The tensor that is a copy of the entire buffer container

unsafe void CopyBufferInto (UInt64 bufferId, IntPtr data, UIntPtr dataSize)

Copy the data of an individual buffer stored in the buffer container into a new memory region

This will copy all data of an individual buffer stored in the buffer container into a new memory region. The specified buffer id must be smaller than the number of buffers stored in the container.

The memory region the data is copied into will hold the data of the buffer with a trivial stride structure, i.e. no holes in memory at all.

This method takes a direct memory pointer as an argument, so its use is considered unsafe. The target memory supplied must be pinned so that the .NET garbage collector does not automatically move it around while it is being accessed by this method, otherwise this could cause the program to crash.

Param bufferId:: The id of the buffer within this container to copy. The id is a consecutive index starting at 0, up to one less than Count.
Param data:: A pointer into memory where the data is to be stored. It is assumed that the user has allocated a region of sufficient size where this will be stored.
Param dataSize:: The size of the target memory region, in bytes. This is used to check if the region is large enough to copy the data into.

PersistentBuffer CopyBuffer (UInt64 bufferId, Int64 overrideBufferNumber = -1)

Copy a buffer stored in a buffer container into a new persistent buffer

Allocates a new persistent buffer and copies the data of a single buffer stored in the buffer container into it. The specified buffer id must be smaller than the number of buffers stored in the container.

Param bufferId:: The id of the buffer within this container to copy. The id is a consecutive index starting at 0, up to one less than Count.
Param overrideBufferNumber:: The buffer number to store in the new persistent buffer. If -1 is specified, the buffer id will be used as the buffer number.
Return:: The copied individual buffer

PersistentBuffer AllocateBuffer ()

Allocate a new persistent buffer object that may hold data from this ring buffer

The newly allocated persistent buffer will be empty.

Return:: The newly allocated persistent buffer

void CopyInto (PersistentBuffer buffer, UInt64 bufferId, Int64 overrideBufferNumber = -1)

Copy a buffer stored in a buffer container into an existing persistent buffer

Copies the data of a single buffer stored in the buffer container into an existing persistent buffer. The specified buffer id must be smaller than the number of buffer stored in the container. The user must ensure that the dimensions and type of the target buffer match that of an individual buffer of the buffer container.

Important: it is up to the user to ensure that this function is not called while the target persistent buffer is accessed from another thread.

Param buffer:: The persistent buffer to overwrite
Param bufferId:: The id of the buffer within this container to copy. The id is a consecutive index starting at 0, up to one less than Count.
Param overrideBufferNumber:: The buffer number to store in the persistent buffer. If -1 is specified, the buffer id will be used as the buffer number.

unsafe void AverageInto (Handle handle, DataType targetDataType, IntPtr data, Int64[] strides)

Average the contents of a buffer container into a memory region provided by the user

Calculates the average of all buffers in a buffer container and stores the average buffer in a memory region provided by the user.

This may be useful when measung references (e.g. a white reference) and an average over all measured buffers is to be displayed to the user.

The resulting data will effectively be a single buffer that contains the average over all buffers stored in the buffer container.

This method takes a direct memory pointer as an argument, so its use is considered unsafe. The target memory supplied must be pinned so that the .NET garbage collector does not automatically move it around while it is being accessed by this method, otherwise this could cause the program to crash.

Param handle:: The fluxEngine handle. The implicit processing queues of the handle are used as the thread pool that will perform the averaging.
Param targetDataType:: The data type of the averaged data. Note that if an integer type is specified here (even though the original data is an integer) this may result in a loss of precision as the fractional part of values will be truncated.
Param data:: A pointer into memory where the averaged data is to be stored. It is assumed that the user has allocated a region of sufficient size where this will be stored.
Param strides:: The stride structure of the user-supplied memory area.

unsafe void AverageInto (Handle handle, DataType targetDataType, IntPtr data)

Average the contents of a buffer container into a memory region provided by the user

Calculates the average of all buffers in a buffer container and stores the average buffer in a memory region provided by the user.

This may be useful when measung references (e.g. a white reference) and an average over all measured buffers is to be displayed to the user.

The resulting data will effectively be a single buffer that contains the average over all buffers stored in the buffer container.

This overload assumes that the stride structure of the target memory area is trivial, i.e. the averages will be layed out contiguously in that memory area.

This method takes a direct memory pointer as an argument, so its use is considered unsafe. The target memory supplied must be pinned so that the .NET garbage collector does not automatically move it around while it is being accessed by this method, otherwise this could cause the program to crash.

Param handle:: The fluxEngine handle. The implicit processing queues of the handle are used as the thread pool that will perform the averaging.
Param targetDataType:: The data type of the averaged data. Note that if an integer type is specified here (even though the original data is an integer) this may result in a loss of precision as the fractional part of values will be truncated.
Param data:: A pointer into memory where the averaged data is to be stored. It is assumed that the user has allocated a region of sufficient size where this will be stored.

unsafe void AverageInto (ProcessingQueueSet queueSet, DataType targetDataType, IntPtr data, Int64[] strides)

Average the contents of a buffer container into a memory region provided by the user

Calculates the average of all buffers in a buffer container and stores the average buffer in a memory region provided by the user.

This may be useful when measung references (e.g. a white reference) and an average over all measured buffers is to be displayed to the user.

The resulting data will effectively be a single buffer that contains the average over all buffers stored in the buffer container.

This method takes a direct memory pointer as an argument, so its use is considered unsafe. The target memory supplied must be pinned so that the .NET garbage collector does not automatically move it around while it is being accessed by this method, otherwise this could cause the program to crash.

Param queueSet:: The processing queue set. The queues of that set will be used as the thread pool that will perform the averaging.
Param targetDataType:: The data type of the averaged data. Note that if an integer type is specified here (even though the original data is an integer) this may result in a loss of precision as the fractional part of values will be truncated.
Param data:: A pointer into memory where the averaged data is to be stored. It is assumed that the user has allocated a region of sufficient size where this will be stored.
Param strides:: The stride structure of the user-supplied memory area.

unsafe void AverageInto (ProcessingQueueSet queueSet, DataType targetDataType, IntPtr data)

Average the contents of a buffer container into a memory region provided by the user

Calculates the average of all buffers in a buffer container and stores the average buffer in a memory region provided by the user.

This may be useful when measung references (e.g. a white reference) and an average over all measured buffers is to be displayed to the user.

The resulting data will effectively be a single buffer that contains the average over all buffers stored in the buffer container.

This overload assumes that the stride structure of the target memory area is trivial, i.e. the averages will be layed out contiguously in that memory area.

This method takes a direct memory pointer as an argument, so its use is considered unsafe. The target memory supplied must be pinned so that the .NET garbage collector does not automatically move it around while it is being accessed by this method, otherwise this could cause the program to crash.

Param queueSet:: The processing queue set. The queues of that set will be used as the thread pool that will perform the averaging.
Param targetDataType:: The data type of the averaged data. Note that if an integer type is specified here (even though the original data is an integer) this may result in a loss of precision as the fractional part of values will be truncated.
Param data:: A pointer into memory where the averaged data is to be stored. It is assumed that the user has allocated a region of sufficient size where this will be stored.

PersistentBuffer AverageIntoNewBuffer (Handle handle, DataType targetDataType)

Average the contents of a buffer container into a newly allocated persistent buffer

Calculates the average of all buffers in a buffer container and stores the average buffer in a newly allocated persistent buffer.

This may be useful when measung references (e.g. a white reference) and an average over all measured buffers is to be displayed to the user.

The resulting data will effectively be a single buffer that contains the average over all buffers stored in the buffer container.

Param handle:: The fluxEngine handle. The implicit processing queues of the handle are used as the thread pool that will perform the averaging.
Param targetDataType:: The data type of the averaged data. Note that if an integer type is specified here (even though the original data is an integer) this may result in a loss of precision as the fractional part of values will be truncated.

PersistentBuffer AverageIntoNewBuffer (ProcessingQueueSet queueSet, DataType targetDataType)

Average the contents of a buffer container into a newly allocated persistent buffer

Calculates the average of all buffers in a buffer container and stores the average buffer in a newly allocated persistent buffer.

This may be useful when measung references (e.g. a white reference) and an average over all measured buffers is to be displayed to the user.

The resulting data will effectively be a single buffer that contains the average over all buffers stored in the buffer container.

Param queueSet:: The processing queue set. The queues of that set will be used as the thread pool that will perform the averaging.
Param targetDataType:: The data type of the averaged data. Note that if an integer type is specified here (even though the original data is an integer) this may result in a loss of precision as the fractional part of values will be truncated.

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

UInt64 Count { get; set; }

The number of buffers stored in the buffer container

mmediately after creation or after a call to BufferContainer.Clear() this will be 0.

If the buffer container was created as a ring buffer this will be equal to the total number of entries added, even if some older entries have since been overwritten.

int Order { get; set; }

The tensor order of the buffer container

This will be one more than the tensor order of the device buffers that can be added to this buffer container.

BufferScalarType ScalarType { get; set; }: The scalar type of the buffer container.

Int64[] Dimensions { get; set; }

The dimensions of the buffer container

Note that a buffer container always has a trivial stride structure (data is stored contiguously in memory) and hence does not provide a means to query these.

UInt64 BytesPerBuffer { get; set; }

The number of bytes for an individual buffer

This is the number of bytes an individual buffer would take up if its data were to be copied out without any holes (trivial stride structure). This information is available even if there are currently no buffers in the buffer container.

UInt64 BytesTotal { get; set; }

Get the number of bytes required to copy the all data in the buffer container

This will change when Count changes.

This is the number of bytes required to copy the data of all buffers stored in this container into memory, assuming the target memory has a trivial stride structure. If no buffers are in the container this will return zero.

DimensionLabelInfo

class LuxFlux.fluxEngineNET.DimensionLabelInfo

Dimension Label Information

Contains the information about a dimension’s labels that may be queried from fluxEngine. This is the return value of InstrumentDevice.RawBufferDimensionLabels() that indicates how dimensions of a raw buffer returned from an instrument may roughly be interpreted.

Properties

string Type { get; set; }

The label type

This may be null, or one of the following strings:

"" (empty string): indicates that there is no special type for this specific dimension
"YPixel": the buffer dimension describes the y dimension of an image. For example, a simple grayscale imager camera will return a raw buffer with 2 dimensions, the first having the type "YPixel" and the second having the type "XPixel".
"XPixel": the buffer dimension describes the x dimension of an image or a line. For example, a simple grayscale imager camera will return a raw buffer with 2 dimensions, the first having the type "YPixel" and the second having the type "XPixel". On the other hand, a grayscale line camera will return one dimension with just the type "XPixel". Finally, a HSI PushBroom camera will return two dimensions, one having the type "XPixel", and the other having the type "Wavelength". (Which one is which in the case of a PushBroom camera will depend on the specific camera model; the preprocessing steps done by processing contexts in fluxEngine will ensure that the data will be normalized.)
"Wavelength": the dimension describes the wavelengths of a spectrometer or a HSI camera

string Unit { get; set; }

The label values’ unit

This may be null, or one of the following strings:

"" (empty string): indicates that the dimension labels have no unit. In this case it is likely that no specific label values are provided.
"px": indicates that the dimension labels are pixels. In this case it is likely that no specific label values are provided, as pixels are typically always just integers that correspond to the index

double[] Values { get; set; }

The values of the labels

This will either contain numeric values that label the dimension in question, or it may be empty or null, indicating that the user should consider an ascending list of indices, e.g. {0, 1, 2, ...} the labels of that specific dimension.

ReferenceMeasurement

class LuxFlux.fluxEngineNET.ReferenceMeasurement : IDisposable 

Resulting Reference Measurement (Recording Processing Contexts)

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

Public Functions

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

ReadOnlyTensorView TensorView { get; set; }: A tensor view of the normalized reference data.

CalibrationInfo CalibrationInfo { get; set; }: The calibration information of the reference data.

HSIRecordingResult

class LuxFlux.fluxEngineNET.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.)

Properties

ProcessingContext Context { get; set; }: The resulting processing context.

double[] Wavelengths { get; set; }

The list of wavelengths of the recorded data

This contains the wavelengths associated with the last dimension of the data being recorded.

ReferenceMeasurement WhiteReference { get; set; }

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.

ReferenceMeasurement DarkReference { get; set; }

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 may contain the normalized dark reference that the user may save in addition to the data they will record. (It is however possible that the dark reference has been pre-applied to even intensity data if specific camera correction algorithms are active.)

ReferenceMeasurement IlluminationReference { get; set; }

Normalized illumination reference

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

CalibrationInfo CalibrationInfo { get; set; }

The calibration information

Calibration information for any recordings created with this context.

ValueType ActualValueType { get; set; }

The actual value type of the output

When requesting ValueType.Intensity as the recording value type, the instrument may actually still return radiances or relative radiances; in that case this field is filled by the actual type. (The data will still be intensity-like in all of those cases.)

Util (Creating buffer containers)

class LuxFlux.fluxEngineNET.Util

Utility methods

This class provides utility methods that don’t fit elsewehere.

Public Static Functions

BufferContainer CreateBufferContainer (InstrumentDevice device, int bufferCount)

Create a buffer container

A buffer container is an object that the user may use to automatically copy data from device buffers into to create a multi-buffer measurement. That may be passed to newly created device processing contexts as reference data, or may later be used to extract individual measurements.

A buffer container is always created with the current dimensions and scalar type of the instrument; if the user changes the instrument’s parameters it may be the case that it does not fit the buffers of the device anymore.

A buffer container can hold at most the data of bufferCount device buffers.

Param device:: The device to create the buffer container for
Param bufferCount:: The capacity of the buffer container in number of device buffers. A larger number will lead to the usage of more RAM.
Return:: The newly created buffer container

BufferContainer CreateRingBufferContainer (InstrumentDevice device, int capacity)

Create a ring buffer container

A buffer container is an object that the user may use to automatically copy data from device buffers into to create a multi-buffer measurement. That may be passed to newly created device processing contexts as reference data, or may later be used to extract individual measurements.

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

A buffer container is always created with the current dimensions and scalar type of the instrument; if the user changes the instrument’s parameters it may be the case that it does not fit the buffers of the device anymore.

When passing a ring buffer into fluxEngine (e.g. as a white reference), if less than capacity 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 capacity elements will be used.

Param device:: The device to create the buffer container for
Param capacity:: The capacity of the buffer container in number of device buffers. A larger number will lead to the usage of more RAM.
Return:: The newly created buffer container

BufferContainer CreateBufferContainer (ProcessingContext context, int bufferCount)

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 ProcessingContext.CreateForInstrumentHSIRecording()) 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 BufferContainer.AddLastResult() to add the last result of a recording context (after processing a device buffer) to the current buffer container.

Param 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.
Param bufferCount:: 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.
Return:: The newly created buffer container

BufferContainer CreateRingBufferContainer (ProcessingContext context, int capacity)

Create a ring 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 ProcessingContext.CreateForInstrumentHSIRecording()) to record the standardized data.

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

This function creates a container that is a ring buffer, so that data may be added continually. Only the last capacity 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 capacity 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 capacity elements will be used.

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

Param 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.
Param capacity:: 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.
Return:: The newly created buffer container

LightControlDevice

class LuxFlux.fluxEngineNET.LightControlDevice : LuxFlux.fluxEngineNET.Device 

Light control device

A light control device allows the user to control whether a light source is active and possibly also the intensity of that light source. This may be helpful for measuring a dark reference (by disabling the light source before the start of the measurement).

As this is a subclass of the Device class it provides all of the functionality of that class (especially when it comes to changing parameters) as well as functionality specific to light control devices.

Light control devices are controlled in two manners:

The parameters indicate the normal setting of the device. This should typically be configured by the end user for the specific use case.
In addition a “force state” may be set programmatically that allows the user to force the light control device to be either off (regardless of the current parameter settings) or to perform a ramp that starts the light at the off and then gradually increase the light intensity to the setting in the parameters. This may be used for nonlinearity correction reference measurements. (See the documentation about advanced features for more details on this topic.)

Public Types

enum Status

Light control device status.

Values:

Invalid

The device handle is invalid

This can happen if the fluxEngine handle is closed while the device was still connected. In that case the device is forcibly disconnected and will have this status.

IrrecoverableError

Irrecoverable error occurred

An error occurred that can’t be easily recovered from. For example, if a device is unplugged mid-use, this will be the status the device will have.

Note that it may be possible to reconnect to the device in that case, but the device group must be disconnected first if the state of a device changes in this manner.

RecoverableError

Recoverable error occurred

If an error occurred (for example a strict temperature limit has been exceeded) that can be recovered from (by resetting the device via Device.ResetError()) then this will be the status the device will have.

Off

The light is off

Some light control devices are initialized to be off by default, for example because they could be a hazard if automatically switched on during connection. In that case the use must explicitly set a parameter to turn the light on.

This can only be the status of the light after initial connection to indicate this. If the light is on by default after connecting to it, it will be in the state LightControlDevice.Status.Parametrized instead. If the light is switched off again via parameters it will still remain in the LightControlDevice.Status.Parametrized state.

Parametrized

The light is controlled via parameters

Various settings control whether the light is on or off; if there are multiple lights potentially whether each individual light is on or off; and if lights can be dimmed, what their intensity is.

ForcedOff

The light has been forced off

The light has been forced off regardless of the parametrization settings.

ForcedRamp

The light has been forced into a ramp

The light has been forced to perform a ramp from being switched off completely to being on up to the intensity specified by the settings. This can be used to record references for non-linearity corrections.

This state will always be temporary, after the ramp is complete the device will automatically switch back into the LightControlDevice.Status.Parametrized state.

enum ForceState

The force state of the light control device

This describes whether / how the parameters of the device are to be overwritten temporarily.

Values:

None

The device should be parametrized

The light will be on or off depending on its parameters.

Off

The light should be forced off

The light will be forced off, regardless of its parameters, and can only be turned on again by changing the force state.

Ramp

The light should perform a ramp-up

The should perform a ramp-up from being off to going to the level of intensity described by its parameters. This force state will automatically reset to LightControlDevice.ForceState.None once the ramp has completed.

Not all devices support this force state.

Public Functions

void SetForceState (ForceState state, TimeSpan rampDuration)

Set the force state of the light control device.

Param state:: The new force state
Param rampDuration:: The ramp duration in milliseconds, if the device supports it. If the device can only switch the light on and off (but not vary its intensity) this will be ignored and the light will just be switched on; the duration of that process will be fixed within the driver (as that will depend on the hardware and can’t be influenced). If the light’s intensity can be modified the driver will gradually adjust the intensity from zero to the parametrized value with a speed that is adjusted to this time. If the user has not requested a ramp, this paramter will be ignored.
Throws OutOfMemoryException:
Throws ArgumentException:
Throws Error:
Throws ObjectNoLongerValidError:
Throws DeviceError:
Throws LightControlDeviceError:

bool WaitForRamp ()

Wait for the device to complete its ramp

This may be called after setting a ramp force state to wait until the ramp is complete.

If the ramp has already completed (or no ramp has been set) this method will return false immediately. If the ramp is active when this method is called it will return only once the ramp has completed.

Throws OutOfMemoryException:
Throws ArgumentException:
Throws Error:
Throws ObjectNoLongerValidError:
Throws DeviceError:
Throws LightControlDeviceError:
Return:: false if the ramp was not active when this was first called (potentially because the ramp was already over), true if the ramp was active when this method was called.

Properties

Status CurrentStatus { get; set; }

The current status of the light control device.

Throws OutOfMemoryException:
Throws ArgumentException:
Throws Error:
Throws DeviceError:
Throws LightControlDeviceError: