Devices

ConnectionSettings

class fluxEngine.ConnectionSettings(driverName, driverType, id)

Connection settings

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

The constructor of this class takes the minimum required information for connecting to any device. If the device requires additional settings, the user should modify the corresponding attributes directly.

Parameters:

driverName (str) –
The name of the driver

This should be the value taken from the EnumeratedDriver.name
driverType (DriverType) –
The type of the driver

This should be the value taken from the EnumeratedDriver.type
id (bytes) –
The id of the device to connect to

This should be the value taken from the EnumeratedDevice::id

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.

driverName

The name of the driver

This should be the value taken from the EnumeratedDriver.name

Type:: str

driverType

The type of the driver

This should be the value taken from the EnumeratedDriver.type

Type:: DriverType

id

The id of the device to connect to

This should be the value taken from the EnumeratedDevice::id

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.

Type:: bytes

connectionParameters

The connection parameters to use

This is a dictionary with keys of type str and values of type str.

The key of this dict is the name of the parameter; it must be identical to the name of the parameter returned by ParameterInfo.parameterNames() or ParameterInfo.Parameter.name.

The value of this dict 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, using . as the decimal separator; 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 str (unicode) object, bytes and/or other path-like objects will not be accepted.

For integer, floating point and boolean values converting it to a string directly in Python should suffice, for example:

connectionSettings.connectionParameters[‘Key’] = str(42.67)

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.

Type:: dict

timeout

The connection timeout in milliseconds

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.

Type:: int

passThroughErrorOutput

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.

Type:: bool

DeviceGroup

class fluxEngine.DeviceGroup(handle, connectionSettings)

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

Note: currently there are no drivers that actually provide subdevices.

This method attempts to connect to a device (group). If successful a device group handle is returned to the user.

If the fluxEngine license was tied to a instrument device serial number, and the connected device is an instrument, a license check will be performed at this point. If it fails the device will be disconnected again. If it succeeds the user will be able to create processing contexts and process data, even if the data is not from the device. When the device group is disconnected the user will not be able to continue processing at this point.

Parameters:

handle (Handle) – The fluxEngine handle
connectionSettings (ConnectionSettings) – The settings that select the device and the connection parameters.

class Notification(type_, device, message)

Device notification

Parameters:

type (DeviceGroup.NotificationType) – The type of the notification
device (Device) – The device the notification has occurred for
message (str) – The notification message

type

The type of the notification

Type:: DeviceGroup.NotificationType

device

The device the notification has occurred for

Type:: Device

message

The notification message

Type:: str

class NotificationType(value)

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 returned by DeviceGroup::notificationEventHandle() may be used to add notifications to the event loop.

IrrecoverableError = 0

Irrecoverable error

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

See also: - LightControlDevice.Status.IrrecoverableError - InstrumentDevice.Status.IrrecoverableError

RecoverableError = 1

Recoverable error

This notification is generated whenever the device switches into a recoverable error state.

See also: - LightControlDevice.Status.RecoverableError - InstrumentDevice.Status.RecoverableError

Warning = 2

Warning

This notification is generated whenever the device encounters a warning. This could for example be that the temperature is outside of the operating range in the specifications. For example, if an instrument requires a stabilized sensor, and that temperature should be at 20C, if the device measures a value that is not around that value, the device could generate a warning.

disconnect(timeout=5000)

Disconnect from the device group

This method attempts to disconnect from a device group. If that does not succeed within the specified timeout, the driver isolation process is force-unloaded.

Important: all handles of the device group and all devices in the group will no longer be valid after this point. This means the user must not access any of the following objects belonging to this device group after a call to this function:

The device group itself

Any device within the device group

Any instrument buffer retrieved from the device

The user does, however, need to explicitly free any processing contexts they created for a device in this group, any reference buffer and any parameter list.

Parameters:: timeout (int) – The timeout in milliseconds, after which the device will be forcibly disconnected by terminating the driver isolation process. A sensible value here is 5 seconds.

driverDescription()

Get the driver description

Returns a human-readable name/description of the driver.

Returns:: The driver description
Return type:: str

driverName()

Get the name of the driver

The driver name is the same that was supplied with the connection settings.

Returns:: The name of the driver
Return type:: str

driverType()

Get the type of the driver

The driver type is the same that was supplied with the connection settings.

Returns:: The type of the driver
Return type:: DriverType

driverVersion()

Get the driver version

Returns a human-readable version string of the driver.

Returns:: The driver version
Return type:: str

nextNotification()

Retrieve the last notification

Retrieves the last notification in the internal notification buffer of the device group. If no notification is present this will be None.

The user may use this to poll the device for notifications.

Returns:: The next notification in the internal notification buffer
Return type:: DeviceGroup.Notification or None

primaryDevice()

Get the primary device of the device group

Returns:: The primary device of the device group. The handle of this device will be valid as long as the device group is not disconnected.
Return type:: Device

DeviceType

class fluxEngine.DeviceType(value)

The type of the device

Instrument = 0

Instrument device

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

LightControl = 2: Light control device

Unknown = -1

Unknown device type

The device in question is of a type that is not supported by fluxEngine.

Device

class fluxEngine.Device(wrapped)

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 checking whether an object is an instance of a specific subclass of the Device class it is also possible to use the Device.type() method to obtain the device type as an enumeration value.

Device objects are only valid as long as the device group remains connected. Once the device group is disconnected or the driver unloaded, all device objects will cease to be valid. Accessing them will result in an error being raised.

A device object should never be created by the user directly, it is always returned by other methods.

LightControlDevice

class fluxEngine.LightControlDevice(wrapped)

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

class ForceState(value)

The force state of the light control device

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

None_ = 0

The device should be parametrized

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

Off = 1

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 = 2

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.

class Status(value)

Light control device status

ForcedOff = 2

The light has been forced off

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

ForcedRamp = 3

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.

Invalid = -3

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 = -2

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.

Off = 0

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 = 1

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.

RecoverableError = -1

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.

setForceState(state, rampDuration)

Set the force state of the light control device

Parameters:

state (LightControlDevice.ForceState) – The new force state
rampDuration (int) – 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.

status()

Get the status of a light control device

Returns:: The status of the light control device
Return type:: LightControlDevice.Status

waitForRamp()

Wait for the device to complete its ramp

This may be called after setting a ramp force state to wait

BufferScalarType

class fluxEngine.BufferScalarType(value)

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 data types supported by processing contexts (represented via numpy types in the Python API), which are only the data types that fluxEngine can use for 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.

InstrumentDevice

class fluxEngine.InstrumentDevice(wrapped)

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 BufferInfo structure 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 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

class AcquisitionParameters(bufferCount=0, referenceName=None)

Acquisition parameters

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

Parameters:

bufferCount (int) –
The number of buffers to use

This will be used to initialize the bufferCount attribute.
referenceName (str) –
The name of the reference to measure

This will be used to initialize the referenceName attribute.

bufferCount

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.

Type:: int

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 None this indicates that a normal (non-reference) measurement is to be performed.

Otherwise this must be either “WhiteReference” 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 of the light, for example), then the user may perform the reference measurement by just normal acquisition.

Type:: str

class Status(value)

Instrument device status

Busy = 1

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

ForcedStop = 3

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

Idle = 0

The instrument is idle

The instrument is idle and not returning data.

Invalid = -3

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 = -2

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 = -1

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.

Streaming = 2

The instrument is streaming data

The instrument is streaming data to the user.

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

Returns:: The newly allocated persistent buffer
Return type:: PersistentBufferInfo

maxBufferSize()

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

This will return 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.

Returns:: The maximum buffer size the instrument may return
Return type:: int

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

Parameters:: dimension (int) – Which dimension to obtain the label information for. It must be between 0 and the number of dimensions of the raw data, i.e. the size of the shape that may be obtained via InstrumentDevice.rawBufferShape().
Returns:: The information about the raw buffer dimension’s labels
Return type:: DimensionLabelInfo

rawBufferScalarType()

Get the scalar type of buffers returned by the device

Given the current settings of the device return the scalar type of buffers that would be returned by the device.

Returns:: The current scalar type of buffers returned by the device
Return type:: BufferScalarType

rawBufferShape()

Get the shape of buffers returned by the device

Given the current settings of the device return the shape of buffers that would be returned by the device.

Returns:: The current shape of buffers returned by the device
Return type:: tuple

rawBufferValueRange()

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

Returns:: A tuple that contains the value range of the device. The first entry is the lower limit, the second entry is the upper limit of the value range.
Return type:: (float, float)

recommendedBufferCount()

Get the number of recommended buffers

This will return 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.

Returns:: The number of recommended buffers
Return type:: int

retrieveBuffer(timeout, abortCheck=None)

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.

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

Parameters:

timeout (int) – 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.
abortCheck (callable or None) –
The function that checks whether an external abort has been initiated. If the function returns true an external abort has been requested.

If this is None no abort check is performed.

Returns:

The buffer that was retrieved. If None is returned this indicates that no buffer was returned within the specified timeout, or the abort check function returned True.

Return type:

BufferInfo or None

returnBuffer(bufferInfo)

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.

Parameters:: bufferInfo (BufferInfo) – The buffer to return

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

Parameters:: calibrationInfo (CalibrationInfo) – The calibration information to set for the device

setupInternalBuffers(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 returned by 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.

Parameters:: count (int) – The number of buffers to allocate

startAcquisition(acquisitionParameters)

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.

Parameters:: acquisitionParameters (AcquisitionParameters) – The parameters for starting acquisition, such as the number of buffers to use for this specific acquisition. See the documentation of the structure on the various parameters.

status()

Get the status of an instrument device

Returns:: The status of the instrument device
Return type:: InstrumentDevice.Status

stopAcquisition()

Stop acquisition

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

BufferInfo

class fluxEngine.BufferInfo(wrapped)

Instrument Buffer Info

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

The user should never create an object of this type themselves, they should always use InstrumentDevice.retrieveBuffer() to obtain such an object.

copy()

Copy the data into a new persistent buffer

As instrument buffers must be returned to the device, in order to keep the data of a buffer around for longer, its data may be copied into a persistent buffer.

Returns:: The new persistent buffer that contains a copy of the data
Return type:: PersistentBufferInfo

copyInto(target)

Copy the data into an existing persistent buffer

As instrument buffers must be returned to the device, in order to keep the data of a buffer around for longer, its data may be copied into a persistent buffer.

This method copies the data of a persistent buffer into another 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.

Parameters:: target (PersistentBufferInfo) – The persistent buffer to copy the data into

getData(targetType=None)

Get the raw data in the buffer

The Python API of fluxEngine doesn’t expose the raw data of the buffer. If data is to be retrieved, it will automatically be copied into a numpy array. If the scalar type of the buffer has a corresponding processing type that fluxEngine supports directly, that type may be used for the numpy array, in which case no conversion will take place. If the data in the buffer is present in a packed format, the data will be converted to a data type that may be used for processing. By default this will be the next larger data type relative to the packed type, but the user may request a different type for the result of the conversion.

Parameters:

targetType (numpy.dtype) –

The numpy type to convert the data to. If not specified this will be the result of expandedType() applied to the scalar type of the data in the buffer.

Note that converting floating point values into an integer is unlikely to be sensible. For example, when converting a floating point value that lies between 0 and 1 into an integer, each element will then be either 0 or 1, which is unlikely to be useful.

Returns:

The raw data in the buffer

Return type:

numpy.ndarray

number()

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

Returns:: The buffer number
Return type:: int

PersistentBufferInfo

class fluxEngine.PersistentBufferInfo(wrapped)

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

BufferInfo.copy()

PersistentBufferInfo.copy()

BufferContainer.copyBuffer()

copy()

Copy the data into a new persistent buffer

Returns:: The new persistent buffer that contains a copy of the data
Return type:: PersistentBufferInfo

copyInto(target)

Copy the data into an existing persistent buffer

This method copies the data of a persistent buffer into another 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.

Parameters:: target (PersistentBufferInfo) – The persistent buffer to copy the data into

getData(targetType=None)

Get the raw data in the buffer

The Python API of fluxEngine doesn’t expose the raw data of the buffer. If data is to be retrieved, it will automatically be copied into a numpy array. If the scalar type of the buffer has a corresponding processing type that fluxEngine supports directly, that type may be used for the numpy array, in which case no conversion will take place. If the data in the buffer is present in a packed format, the data will be converted to a data type that may be used for processing. By default this will be the next larger data type relative to the packed type, but the user may request a different type for the result of the conversion.

Parameters:

targetType (numpy.dtype) –

The numpy type to convert the data to. If not specified this will be the result of expandedType() applied to the scalar type of the data in the buffer.

Note that converting floating point values into an integer is unlikely to be sensible. For example, when converting a floating point value that lies between 0 and 1 into an integer, each element will then be either 0 or 1, which is unlikely to be useful.

Returns:

The raw data in the buffer

Return type:

numpy.ndarray

number()

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

Returns:: The buffer number
Return type:: int

BufferContainer

class fluxEngine.BufferContainer(*args, **kwargs)

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 the specified bufferCount device buffers.

Parameters:

device (InstrumentDevice) – The device to create the buffer container for
bufferCount (int) – The capacity of the buffer container in number of device buffers. A larger number will lead to the usage of more RAM.

Keyword Arguments:

ringBuffer (bool) – Whether the buffer container should be a ring buffer.

add(bufferInfo)

Add a buffer to the buffer container

Add a device or 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.

Parameters:: bufferInfo (BufferInfo or PersistentBufferInfo) – The buffer to add

addLastResult(recordingContext)

Add the last result of a recording context to the buffer container

Given a buffer container that was allocated via the createBufferContainerForRecordingContext() function, 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.

Parameters:: recordingContext (ProcessingContext) – The processing context whose data to add

average(handleOrQueueSet, dataType)

Average all buffers stored in a buffer container

Calculates the average of all buffers in a buffer container and returns the average buffer as a numpy array.

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.

Parameters:

handleOrQueueSet (Handle or ProcessingQueueSet) – The processing queue set to perform the calculation with. If the handle is specified, the default processing queue set will be used.
dataType (numpy.dtype) – 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.

clear()

Clear the buffer container

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

copyBuffer(bufferId, 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.

Parameters:

bufferId (int) – The id of the buffer to copy
overrideBufferNumber (int) – If this is non-negative it will be stored as the buffer number of the persistent buffer; otherwise the value of the bufferId parameter will be used as the buffer number.

Returns:

The new persistent buffer

Return type:

PersistentBufferInfo

copyBufferInto(bufferId, overrideBufferNumber, target)

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.

Parameters:

bufferId (int) – The id of the buffer to copy
overrideBufferNumber (int) – If this is non-negative it will be stored as the buffer number of the persistent buffer; otherwise the value of the bufferId parameter will be used as the buffer number.
target (PersistentBufferInfo) – The persistent buffer to copy the data into

count()

Get the number of buffers stored in the buffer container

Immediately after creation or after a call to BufferContainer.clear() this will be 0.

Returns:: The number of buffers in the container
Return type:: int

HSIRecordingResult

class fluxEngine.HSIRecordingResult(wrapped)

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

wavelengths

The list of wavelengths of the recorded data

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

Type:: list(float)

whiteReference

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.

Type:: numpy.ndarray or None

darkReference

Normalized dark reference

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

Type:: numpy.ndarray or None

illuminationReference

Normalized illumination reference

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

Type:: numpy.ndarray or None

calibrationInfo

Calibration information

Calibration information for any recordings created with this context.

Type:: CalibrationInfo

InstrumentParameters

class fluxEngine.InstrumentParameters(whiteReference=None, darkReference=None, illuminationReference=None)

Instrument parameters

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

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

This structure allows the user to supply the references in form of either BufferContainer objects or numpy arrays. Note that all references must be of the same type – it is not possible to mix them. If numpy arrays are specified they will first be converted into the correct scalar type.

Parameters:

whiteReference (BufferContainer or numpy.ndarray or None) – The white reference data
darkReference (BufferContainer or numpy.ndarray or None) – The dark reference data
illuminationReference (BufferContainer or numpy.ndarray or None) – The illumination reference data

whiteReference

The white reference data

Type:: BufferContainer or numpy.ndarray or None

darkReference

The dark reference data

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

Type:: BufferContainer or numpy.ndarray or None

illuminationReference

The illumination reference data

Type:: BufferContainer or numpy.ndarray or None

flags

Flags that influence the creation of a processing context for device data

Type:: DeviceProcessingContextCreationFlag

DeviceProcessingContextCreationFlag

class fluxEngine.DeviceProcessingContextCreationFlag(value)

Flags that influence device processing context creation

This enumeration contains flags that may be passed to the constructor of ProcessingContext() when creating a context from an instrument device for recording and/or processing purposes that will influence the behavior of that constructor.

AdditionalPreview = 1

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.

DimensionLabelInfo

class fluxEngine.DimensionLabelInfo(type=None, unit=None, values=[])

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.

type

The label type. This may be one of the following values:

None: the type could not be determined or the current version of fluxEngine does not understand the type provided by the driver

"" (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

Type:: str or None

unit

The label unit. This may be one of the following values:

None: the unit could not be determined or the current version of fluxEngine does not understand the unit provided by the driver

"" (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

"nm": the labels of this dimension are measured in nanometers.

Type:: str or None

values

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

Type:: list(float)

createBufferContainerForRecordingContext

fluxEngine.createBufferContainerForRecordingContext(recordingContext, count, ringBuffer=False)

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

Parameters:

recordingContext (ProcessingContext) – The processing context to create the buffer container for. It must be a recording context, and the device must be a line camera or similar.
count (int) – 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.
ringBuffer (bool) – Whether the buffer container should be a ring buffer. (Default: no)

Returns:

The newly created buffer container

Return type:

BufferContainer