C++ Reference Documentation

Version Information

std::string fluxEngine::versionString()

Get the version string for the currently loaded fluxEngine.

The string returned should not be parsed by the user, and the user should not make any assumptions based on the format of the string. It is purely for informational purposes, if the user of fluxEngine wants to show that string to the end-user, for example. If version-based checks are to be done, please use versionMajor() and versionMinor() instead.

This function can only fail if the allocation of a std::string fails, in which case std::bad_alloc will be thrown.

Return
The version string for the currently loaded fluxEngine

int fluxEngine::versionMajor()

Get the major version of the currently loaded fluxEngine.

This function will never fail.

Return
The major version of fluxEngine

int fluxEngine::versionMinor()

Get the minor version of the currently loaded fluxEngine.

This function will never fail.

Return
The minor version of fluxEngine

Error Handling

enum fluxEngine::ErrorCode

Error Codes.

This enumeration describes possible error codes that give an indication what went wrong when calling specific functions.

Any exception thrown by fluxEngine that is a subclass of the Error class will contain one of these codes.

This does not include a mapping of all C error codes, as some of them are mapped onto the exception classes of the standard library. See the Error class for details.

See
Error

Values:

Unknown = fluxEngine_C_v1_ErrorCode_Unknown

Unknown error.

If an error occurred that has not yet been categorized with a specific error code, this code will be returned.

HandleNoLongerValid = fluxEngine_C_v1_ErrorCode_HandleNoLongerValid

The handle is no longer valid.

If an operation is performed on a handle that has been destroyed, but where the metadata is still kept in memory because one or more models and/or processing contexts have not yet been freed, this error will be returned.

If this error occurs this indicates undefined behavior, as this essentially amounts to a use-after-free of the handle structure.

This error code will always be set in a subclass of Error, ObjectNoLongerValidError, to allow the user to polymorphically catch this kind of error.

See
ObjectNoLongerValidError

ModelNoLongerValid = fluxEngine_C_v1_ErrorCode_ModelNoLongerValid

The model is no longer valid.

If an operation is performed on a model whose handle has already been destroyed, this error will be returned.

In contrast to ErrorCode::HandleNoLongerValid occurring, this is not an indication of undefined behavior.

This error code will always be set in a subclass of Error, ObjectNoLongerValidError, to allow the user to polymorphically catch this kind of error.

See
ObjectNoLongerValidError

ProcessingContextNoLongerValid = fluxEngine_C_v1_ErrorCode_ProcessingContextNoLongerValid

The processing context is no longer valid.

If an operation is performed on a model whose handle has already been destroyed, this error will be returned.

It is also possible that this error is returned if the number of processing threads of a given handle was changed after creating the processing context.

In contrast to ErrorCode::HandleNoLongerValid occurring, this is not an indication of undefined behavior.

This error code will always be set in a subclass of Error, ObjectNoLongerValidError, to allow the user to polymorphically catch this kind of error.

See
ObjectNoLongerValidError

FileAccessError = fluxEngine_C_v1_ErrorCode_FileAccessError

Generic File I/O error.

If accessing a file fails, and the implementation cannot currently determine the precise type of error, this code will be returned to indciate any type of error related to accessing a given file.

This error code will always be set in a subclass of Error, FileAccessError, to allow the user to polymorphically catch this kind of error.

See
FileAccessError

FileNotFoundError = fluxEngine_C_v1_ErrorCode_FileNotFoundError

File Not Found.

This error code is returned if a file was not found when trying to access it.

This error code will always be set in an indirect subclass of Error, FileNotFoundError, which itself is a direct subclass of FileAccessError, to allow the user to polymorphically catch this kind of error.

Note that if the precise cause of failing to open a file could not be determined, the more generic ErrorCode::FileAccessError could also be returned.

See
FileAccessError
See
FileNotFoundError

FileAccessDeniedError = fluxEngine_C_v1_ErrorCode_FileAccessDeniedError

File Access Denied.

This error code is returned if a file could not be opened due to a lack of permissions for either the file itself, or a directory leading up to the file.

This error code will always be set in an indirect subclass of Error, FileAccessDeniedError, which itself is a direct subclass of FileAccessError, to allow the user to polymorphically catch this kind of error.

Note that if the precise cause of failing to open a file could not be determined, the more generic ErrorCode::FileAccessError could also be returned.

See
FileAccessError
See
FileAccessDeniedError

FileTypeError = fluxEngine_C_v1_ErrorCode_FileTypeError

File Type Error.

This error code is returned if the specified file is not actually a file, but for example a directory (or some other filesystem object that is not considered a file).

This error code will always be set in an indirect subclass of Error, FileTypeError, which itself is a direct subclass of FileAccessError, to allow the user to polymorphically catch this kind of error.

Note that if the precise cause of failing to open a file could not be determined, the more generic ErrorCode::FileAccessError could also be returned.

See
FileAccessError
See
FileTypeError

FileInUseError = fluxEngine_C_v1_ErrorCode_FileInUseError

File Is In Use.

This error code is returned if a file could not be opened because it is in use by another program.

This error code will always be set in an indirect subclass of Error, FileInUseError, which itself is a direct subclass of FileAccessError, to allow the user to polymorphically catch this kind of error.

Note that if the precise cause of failing to open a file could not be determined, the more generic ErrorCode::FileAccessError could also be returned.

See
FileAccessError
See
FileInUseError

ReadOnlyFilesystem = fluxEngine_C_v1_ErrorCode_ReadOnlyFilesystem

Read-Only Filesystem.

This error code is reserved for future use.

(Currently there are no functions in fluxEngine that write files.)

IOError = fluxEngine_C_v1_ErrorCode_IOError

I/O Error.

This error code is returned if a file could not be opened or an I/O operation could not be perfomed due to an I/O error. This could be due to a hardware device malfunctioning, or a network drive suddenly becoming inaccessible.

This error code will always be set in a subclass of Error, IOError, to allow the user to polymorphically catch this kind of error.

See
IOError

HandleAlreadyCreated = fluxEngine_C_v1_ErrorCode_HandleAlreadyCreated

A handle has already been created.

Current limitations of the fluxEngine library allow only for the creation of a single handle. If the user attempts to create a second handle, this error code will be returned.

InvalidLicense = fluxEngine_C_v1_ErrorCode_InvalidLicense

Invalid license.

The supplied license is invalid, and could either not be parsed, or the parsed data did not make any sense. This is typically the case if something other than the correct license file is passed to fluxEngine_C_v1_init().

This error code will always be set in a subclass of Error, LicenseError, to allow the user to polymorphically catch this kind of error.

See
LicenseError

LicenseWrongProduct = fluxEngine_C_v1_ErrorCode_LicenseWrongProduct

License is for wrong product.

The supplied license is for the wrong product (for example, fluxTrainer), but not for fluxEngine.

This error code will always be set in a subclass of Error, LicenseError, to allow the user to polymorphically catch this kind of error.

See
LicenseError

LicenseExpired = fluxEngine_C_v1_ErrorCode_LicenseExpired

License has expired.

If the license was issued only up to a certain date, and that date has passed, the license is expired and this error will be returned.

This error code will always be set in a subclass of Error, LicenseError, to allow the user to polymorphically catch this kind of error.

See
LicenseError

LicenseUpdateExpired = fluxEngine_C_v1_ErrorCode_LicenseUpdateExpired

License is for previous versions of the software.

The supplied license is only valid for versions of fluxEngine that were built before a specific date, and the current version of fluxEngine has passed that date.

This error code will always be set in a subclass of Error, LicenseError, to allow the user to polymorphically catch this kind of error.

See
LicenseError

LicenseIdentifierMismatch = fluxEngine_C_v1_ErrorCode_LicenseIdentifierMismatch

License identifier mismatch.

The supplied license does not match the current system. For example, when a license issued to the mainboard serial number of a given system is run on a system with a different mainboard serial number, this error will be returned.

This error code will always be set in a subclass of Error, LicenseError, to allow the user to polymorphically catch this kind of error.

See
LicenseError

LicenseDongleRemoved = fluxEngine_C_v1_ErrorCode_LicenseDongleRemoved

The license dongle has been removed.

The license was tied to a dongle and that dongle has since been removed from the computer.

ThreadCreationError = fluxEngine_C_v1_ErrorCode_ThreadCreationError

Unable to create a background processing thread.

A background processing thread could not be created by fluxEngine, possibly due to resource exhaustion or an operating system limit.

This error code will always be set in a subclass of Error, InitializationError, to allow the user to polymorphically catch this kind of error.

See
InitializationError

ThreadInitFunctionError = fluxEngine_C_v1_ErrorCode_ThreadInitFunctionError

The user-supplied thread initialization function returned a non-zero return code.

This error code exists for completeness sake, as the C++ wrapper code will propagate exceptions from the thread initialization function directly to the user.

InvalidModelData = fluxEngine_C_v1_ErrorCode_InvalidModelData

Invalid Model Data.

When loading a model (either from memory or from a file) this error code is returned if the model could not be loaded, for example because the data of the model was corrupt, or the file that was passed was not a LuxFlux Runtime Model (.fluxmdl).

This could also be the result of an I/O error that could not be properly caught.

This error code will always be set in a subclass of Error, ModelLoadError, to allow the user to polymorphically catch this kind of error.

See
ModelLoadError

ModelContainsUnsupportedFilter = fluxEngine_C_v1_ErrorCode_ModelContainsUnsupportedFilter

Model Contains Unsupported Filter.

The supplied model contains a filter that is not supported by the current version of fluxEngine. It was likely created with a newer version of fluxTrainer.

This error code will always be set in a subclass of Error, ModelLoadError, to allow the user to polymorphically catch this kind of error.

See
ModelLoadError

ModelContainsUnlicensedFilter = fluxEngine_C_v1_ErrorCode_ModelContainsUnlicensedFilter

Model Contains Unlicensed Filter.

The supplied model contains a filter that is not allowed by the currently loaded license, and can hence not be loaded.

This error code will always be set in a subclass of Error, ModelLoadError, to allow the user to polymorphically catch this kind of error.

See
ModelLoadError

ModelNotConsistent = fluxEngine_C_v1_ErrorCode_ModelNotConsistent

The supplied model is not consistent.

The model that was loaded is not in a consistent state. This indicates a problem during the export of the model.

This error code will always be set in a subclass of Error, ModelLoadError, to allow the user to polymorphically catch this kind of error.

See
ModelLoadError

ModelSourceTypeUnsupported = fluxEngine_C_v1_ErrorCode_ModelSourceTypeUnsupported

The supplied model is for unsupported data.

The model that was loaded is for processing data of a type that is currently not supported by fluxEngine. Currently only hyperspectral data (Cubes or PushBroom frames) are supported.

This error code will always be set in a subclass of Error, ModelLoadError, to allow the user to polymorphically catch this kind of error.

See
ModelLoadError

ModelWrongSourceType = fluxEngine_C_v1_ErrorCode_ModelWrongSourceType

The loaded model is not a HSI model.

When creating a processing context for HSI data, if the loaded model is not a HSI model, this error code will be returned.

At the moment, this will never happen, as only HSI models can be loaded. Future versions might return this error code though.

This error code will always be set in a subclass of Error, ProcessingContextCreationError, to allow the user to polymorphically catch this kind of error.

See
ProcessingContextCreationError

FilterCreationError = fluxEngine_C_v1_ErrorCode_FilterCreationError

Could not create required filter.

When creating a processing context, several filters are automatically created and added to the model to ensure that they can properly transform the input data to the format the model expects. This error is returned if one of these filters could not be created for any reason.

This error code will always be set in a subclass of Error, ProcessingContextCreationError, to allow the user to polymorphically catch this kind of error.

See
ProcessingContextCreationError

WavelengthRangeDeterminationError = fluxEngine_C_v1_ErrorCode_WavelengthRangeDeterminationError

Could not determine wavelength range of model.

The wavelength setting of the source node in a given model could not be read during the creation of a processing context.

This error code will always be set in a subclass of Error, ProcessingContextCreationError, to allow the user to polymorphically catch this kind of error.

See
ProcessingContextCreationError

InputDimensionError = fluxEngine_C_v1_ErrorCode_InputDimensionError

The supplied dimensions of the input do not make sense.

The dimensions of the input supplied while either creating a processing context or providing the next input data pointer do not make sense, for example because a negative number was provided.

This error code will always be set in a subclass of Error, InputDimensionError, to allow the user to polymorphically catch this kind of error.

See
InputDimensionError

InputStrideError = fluxEngine_C_v1_ErrorCode_InputStrideError

The supplied stride of the input does not fit.

The stride of the input supplied while providing the next input data pointer does not fit the dimension structure of the input data.

For example, if an entire cube is being processed, and the dimension structure of the cube is (500, 300, 200), then a stride structure of (60000, 200, 1) would be acceptable, but a stride structure of (50000, 200, 1) would not be, as the first stride is smaller than the second stride times the second dimension.

This error code will always be set in a subclass of Error, InputStrideError, to allow the user to polymorphically catch this kind of error.

See
InputStrideError

WhiteReferenceMissingError = fluxEngine_C_v1_ErrorCode_WhiteReferenceMissingError

No white reference provided.

When creating a processing context for a model that is given in reflectances or absorbances, but the data provided by the user will be in raw intensities, a white reference must exist for fluxEngine to be able to automatically reference the input data. If no white reference is provided during processing context creation in that circumstance, this error will be returned.

Note: this error will not occur if the data provided by the user is already reflectance data or the model is set to process raw intensities and the user provides intensity data.

This error code will always be set in a subclass of Error, ProcessingContextCreationError, to allow the user to polymorphically catch this kind of error.

See
ProcessingContextCreationError

WhiteReferenceDimensionError = fluxEngine_C_v1_ErrorCode_WhiteReferenceDimensionError

The provided dimensions of the white reference are not acceptable.

When providing a white reference while setting up a processing context, the dimension of the provided reference must be supplied. If those dimensions are not congruent to the input dimensions, this error code will be returned.

Please note that references always have an additional dimension that allows fluxEngine to average over multiple reference measurements, so the reference for processing entire HSI cubes will be a tensor of order 4, for example.

This error code will always be set in a subclass of Error, ProcessingContextCreationError, to allow the user to polymorphically catch this kind of error.

See
ProcessingContextCreationError

DarkReferenceDimensionError = fluxEngine_C_v1_ErrorCode_DarkReferenceDimensionError

The provided dimensions of the dark reference are not acceptable.

When providing a dark reference while setting up a processing context, the dimension of the provided reference must be supplied. If those dimensions are not congruent to the input dimensions, this error code will be returned.

Please note that references always have an additional dimension that allows fluxEngine to average over multiple reference measurements, so the reference for processing entire HSI cubes will be a tensor of order 4, for example.

This error code will always be set in a subclass of Error, ProcessingContextCreationError, to allow the user to polymorphically catch this kind of error.

See
ProcessingContextCreationError

PreprocessingSetupError = fluxEngine_C_v1_ErrorCode_PreprocessingSetupError

An error occurred while setting up preprocessing.

While performing the final actions required to initialize the preprocessing steps for the input data, an error occurred.

This error code will always be set in a subclass of Error, ProcessingContextCreationError, to allow the user to polymorphically catch this kind of error.

See
ProcessingContextCreationError

ProcessingSetupError = fluxEngine_C_v1_ErrorCode_ProcessingSetupError

An error occurred while setting up processing.

While performing the final actions required to initialize the processing sequence, an error occurred.

This error code will always be set in a subclass of Error, ProcessingContextCreationError, to allow the user to polymorphically catch this kind of error.

See
ProcessingContextCreationError

InputWavelengthValueError = fluxEngine_C_v1_ErrorCode_InputWavelengthValueError

Input wavelength value error.

One of the wavelengths supplied as the input data did not have a finite value. This happens if the list of input wavelengths contain NaN or infinities.

This error code will always be set in a subclass of Error, ProcessingContextCreationError, to allow the user to polymorphically catch this kind of error.

See
ProcessingContextCreationError

OutputIdNotPresent = fluxEngine_C_v1_ErrorCode_OutputIdNotPresent

No output sink with the given output id is present.

This error will be returned by ProcessingContext::findOutputSink() if there is no output sink in the loaded model with the requested output id.

This error code will always be set in a subclass of Error, OutputIntrospectionError, to allow the user to polymorphically catch this kind of error.

See
OutputIntrospectionError

OutputIdNotUnique = fluxEngine_C_v1_ErrorCode_OutputIdNotUnique

Multiple outuput sinks with the given output id are present.

This error will be returned by ProcessingContext::findOutputSink() if there is more than one output sink in the loaded model with the requested output id.

This error code will always be set in a subclass of Error, OutputIntrospectionError, to allow the user to polymorphically catch this kind of error.

See
OutputIntrospectionError

StorageTypeMismatch = fluxEngine_C_v1_ErrorCode_StorageTypeMismatch

Storage type mismatch while introspecting an output sink.

When using either ProcessingContext::outputSinkTensorStructure() or ProcessingContext::outputSinkObjectListStructure() to obtain more detailed information about an output sink, if the output sink has a different storage type, this error will be returned.

For example, calling ProcessingContext::outputSinkTensorStructure() for an output sink that will return a list of detected objects would result in this error.

This error code will always be set in a subclass of Error, OutputIntrospectionError, to allow the user to polymorphically catch this kind of error.

See
OutputIntrospectionError

ProcessingContextTypeMismatch = fluxEngine_C_v1_ErrorCode_ProcessingContextTypeMismatch

The processing context is of the wrong type.

When setting the next input pointer by calling ProcessingContext::setSourceData() in the wrong variant, because the context was created for a different type of data, this error will be returned.

For example, calling ProcessingContext::setSourceData() in the ProcessingContext::HSICube variant on a context that was created to process PushBroom frames will result in this error.

This error code will always be set in a subclass of Error, ProcessingContextTypeMismatchError, to allow the user to polymorphically catch this kind of error.

See
ProcessingContextTypeMismatchError

ProcessingUnknownError = fluxEngine_C_v1_ErrorCode_ProcessingUnknownError

An unknown error occurred during processing.

This happens when the actual processing step during a call to ProcessingContext::processNext() fails in an unknown manner.

This error code will always be set in a subclass of Error, ProcessingError, to allow the user to polymorphically catch this kind of error.

See
ProcessingError

ProcessingInternalError = fluxEngine_C_v1_ErrorCode_ProcessingInternalError

An internal error occurred during processing.

An internal error occurred during data processing.

This error code will always be set in a subclass of Error, ProcessingError, to allow the user to polymorphically catch this kind of error.

See
ProcessingError

ProcessingAborted = fluxEngine_C_v1_ErrorCode_ProcessingAborted

Processing was aborted by the user.

This error code will always be set in a subclass of Error, ProcessingError, to allow the user to polymorphically catch this kind of error.

See
ProcessingError

ProcessingSourceDataMissing = fluxEngine_C_v1_ErrorCode_ProcessingSourceDataMissing

The source data for processing was not set by the user.

If the user has never called ProcessingContext::setSourceData() before a call to ProcessingContext::processNext() this error will occur.

This also occurs if the user has not set the source data again after a call to ProcessingContext::resetState().

This error code will always be set in a subclass of Error, ProcessingError, to allow the user to polymorphically catch this kind of error.

See
ProcessingError

using fluxEngine::OSErrorCode = typedef fluxEngine_C_v1_OsErrorCode

Operating system error code.

This typedef aliases the operating system’s type to report errors. On Windows systems this is DWORD, as that is returned by GetLastError(), on all other systems it is int, as that is the type of the errno variable.

class Error : public runtime_error

Base exception class for fluxEngine errors.

When fluxEngine throws an exception, it will always throw one of the following exceptions:

  • This class or a subclass of it to describe an error that is specific to fluxEngine
  • std::bad_alloc to describe allocation failures
  • std::invalid_argument if an invalid argument was passed to any fluxEngine method
  • std::out_of_range to indicate an index was out of range (for example, when introspecting groups of a model, if the group id is invalid, this will be thrown)
  • During thread creation any exception in the thread initialization callback the user supplies will be forwarded to the user

Subclassed by fluxEngine::FileAccessError, fluxEngine::InitializationError, fluxEngine::InputDimensionError, fluxEngine::InputStrideError, fluxEngine::IOError, fluxEngine::LicenseError, fluxEngine::ModelLoadError, fluxEngine::ObjectNoLongerValidError, fluxEngine::OutputIntrospectionError, fluxEngine::ProcessingContextCreationError, fluxEngine::ProcessingContextTypeMismatchError, fluxEngine::ProcessingError

Public Functions

Error(std::string message, ErrorCode errorCode, OSErrorCode osErrorCode = {})

Constructor.

The error message may be retrieved by the standard what() method of all std::exception subclasses.

Parameters
  • message: The error message
  • errorCode: The error code, see ErrorCode for details
  • osErrorCode: The operating system error code if an OS function was responsibly for the specific error

Error(Error const&)

Copy constructor.

Error(Error&&)

Move constructor.

Error &operator=(Error const&)

Copy assignment operator.

Error &operator=(Error&&)

Move assignment operator.

ErrorCode errorCode() const

Get the error code of this exception.

Return
The error code of this exception

OSErrorCode osErrorCode() const

Get the underlying operating system error code.

Not all methods invoke operating system functions, in which case this will be 0. It may also be 0 if it was not possible to obtain the operating system’s internal error code for a given operation.

Return
The underlying operating system error code

Public Static Functions

void throwFromErrorStruct(fluxEngine_C_v1_Error *error)

Throw an error from a C struct.

Given an error structure returned by the wrapped C API, create the correct subclass of Error and throw it. Also free the C struct to avoid memory leaks.

Parameters
  • error: The C error struct

class ObjectNoLongerValidError : public fluxEngine::Error

Object No Longer Valid Error.

This error class exists to allow the user to polymorphically catch all exceptions that relate to fluxEngine objects no longer being valid. This includes the following error codes:

class FileAccessError : public fluxEngine::Error

File Access Error.

This error class exists to allow the user to polymorphically catch all exceptions that relate to errors in accessing files. There are also further subclasses of this error. The following error codes will be assigned this class or a subclass thereof:

Subclassed by fluxEngine::FileAccessDeniedError, fluxEngine::FileInUseError, fluxEngine::FileNotFoundError, fluxEngine::FileTypeError, fluxEngine::ReadOnlyFilesystemError

class FileNotFoundError : public fluxEngine::FileAccessError

File Not Found Error.

This error class exists to allow the user to polymorphically catch all exceptions that relate to a file not existing. This will always correspond to the error code ErrorCode::FileNotFoundError.

class FileAccessDeniedError : public fluxEngine::FileAccessError

File Access Denied Error.

This error class exists to allow the user to polymorphically catch all exceptions that relate to not being able to access a file due to the file’s permissions. This will always correspond to the error code ErrorCode::FileAccessDeniedError.

class FileTypeError : public fluxEngine::FileAccessError

File Type Error.

This error class exists to allow the user to polymorphically catch all exceptions that relate to not being able to access a file because it is not a file, but a directory, or some other filesystem object. This will always correspond to the error code ErrorCode::FileTypeError.

class FileInUseError : public fluxEngine::FileAccessError

File In Use Error.

This error class exists to allow the user to polymorphically catch all exceptions that relate to a file being in use by another program. This will always correspond to the error code ErrorCode::FileInUseError.

class ReadOnlyFilesystemError : public fluxEngine::FileAccessError

Read-Only Filesystem.

This error class exists to allow the user to polymorphically catch all exceptions that relate to a file not being writable due to the underlying filesystem being read-only. This will always correspond to the error code ErrorCode::ReadOnlyFilesystemError.

This class will currently never be thrown, as there is no part of fluxEngine that opens files for writing.

class IOError : public fluxEngine::Error

I/O Error.

This error class exists to allow the user to polymorphically catch all exceptions that relate to an underlying I/O error while performing an I/O operation. This will always correspond to the error code ErrorCode::IOError.

class LicenseError : public fluxEngine::Error

License Error.

This error class exists to allow the user to polymorphically catch all exceptions that relate to the license being rejected by fluxEngine. This includes the following error codes:

class InitializationError : public fluxEngine::Error

Initialization Error.

This error class exists to allow the user to polymorphically catch all exceptions that relate to initialization issues in fluxEngine. This includes the following error codes:

class ModelLoadError : public fluxEngine::Error

Model Load Error.

This error class exists to allow the user to polymorphically catch all exceptions that relate to loading and parsing models in fluxEngine. This includes the following error codes:

class ProcessingContextCreationError : public fluxEngine::Error

Processing Context Creation Error.

This error class exists to allow the user to polymorphically catch most exceptions that relate to the creation of processing contexts in fluxEngine. This includes the following error codes:

class InputDimensionError : public fluxEngine::Error

Input Dimension Error.

This error class exists to allow the user to polymorphically catch all exceptions that relate to the input dimensions not being specified correctly, either while creating a processing context, or while setting the source data before execution. This always corresponds to the error code ErrorCode::InputDimensionError.

class InputStrideError : public fluxEngine::Error

Input Stride Error.

This error class exists to allow the user to polymorphically catch all exceptions that relate to the input strides not being specified correctly while setting the source data before execution. This always corresponds to the error code ErrorCode::InputStrideError.

class OutputIntrospectionError : public fluxEngine::Error

Output Introspection Error.

This error class exists to allow the user to polymorphically catch most exceptions that relate to the introspection of output sinks in a given processing context. This includes the following error codes:

class ProcessingContextTypeMismatchError : public fluxEngine::Error

Processing Context Type Error.

This error class exists to allow the user to polymorphically catch if they accidentally try to set the wrong type of input data for a given processing context. This always corresponds to the error code ErrorCode::ProcessingContextTypeMismatch.

class ProcessingError : public fluxEngine::Error

Processing Error.

This error class exists to allow the user to polymorphically catch most exceptions that relate to the actual processing of data. This includes the following error codes:

Library Setup

class Handle

fluxEngine Handle

This class represents a handle to fluxEngine’s functionality. It is required to perform any operation with fluxEngine.

The default constructor does not actually create an object, the user must use one of the other constructors to actually create and initialize a handle.

Currently only one initialized handle may be created at a time. (This restriction will be relaxed in a future version.)

Each handle is associated with a number of processing threads that the user can manage. A handle may only be used to process a single model at the same time, though multiple models may be loaded for a given handle.

Public Functions

Handle()

Default constructor.

This does not actually create a handle, but allows the user to create variables that can be used to move a handle around.

Handle(void const *licenseData, std::size_t licenseDataSize)

Initialize fluxEngine.

This constructor initializes fluxEngine. Valid license data must be passed to this function, otherwise fluxEngine will not initialize itself. It is up to the user to read the license data from the given license file, if they choose to store it in a file.

If the call is successful a handle will be created. The following example shows a typical usage: 

{
    fluxEngine::Handle handle(licenseData, licenseDataSize);
    // do something with handle
}
// handle has fallen out of scope and is destroyed

The resulting handle has move semantics, see the following example: 

fluxEngine::Handle handle(licenseData, licenseDataSize);
// do some initial things
someObject.setHandle(std::move(handle));

If an error occurs (for example, because the license was not valid), an exception will be thrown. The following exceptions may be thrown by this constructor:

Parameters
  • licenseData: The raw bytes of the license
  • licenseDataSize: The number of raw bytes of the license

Handle(std::vector<std::byte> const &licenseData)

Initialize fluxEngine (convenience wrapper)

If the license data is present as a std::vector<std::byte> this convenience wrapper exists to allow the user to use that to construct a fluxEngine handle.

This wrapper is only available when compiling with a compiler that supports C++17.

See the documentation for the primary constructor for more details.

Parameters
  • licenseData: The raw bytes of the license

Handle(Handle &&other)

Move constructor.

Parameters
  • other: The handle to move into the newly created object

Handle &operator=(Handle &&other)

Move assignment operator.

Return
A reference to this object
Parameters
  • other: The handle to move into this object

~Handle()

Destructor.

Destroy a library handle, freeing its resources. All background threads will be stopped in the same manner as if stopProcessingThreads() had been called.

Any processing context associated with this handle will be marked as invalid and may hence not be used anymore. However, some memory associated with remaining processing contexts that have not been freed previous to a call to this method may still be in use until each remaining processing context is freed by the user.

void createProcessingThreads(int count)

Create processing threads.

fluxEngine may use parallization to speed up processing. In order to achieve this background threads must be created to run on additional CPU cores.

Calling this method is optional: by default processing will be single-threaded.

This method will start count - 1 threads when called, as the thread that asks for processing is always considered to be the first thread (with id 0). For example, if 4 is supplied to count this function will start 3 threads that run in the background. The thread that the user uses to call ProcessingContext::processNext() will be considered the thread with id 0, making processing use a total of 4 threads, which is the value supplied for count.

This method may only be called if there are currently no background threads associated with this handle. Otherwise stopProcessingThreads() must be called first to change the number of threads.

Any processing context that was created before a call to this method was made is marked as invalid and can only be destroyed, but not used anymore.

If an error occurs, an exception will be thrown. The following exceptions may be thrown by this method:

Parameters
  • count: The number of threads to use for parallel processing (one less than this number will be created by this method, see the description for details)

template <typename T>
void createProcessingThreads(int count, T &&initFunction)

Create processing threads (extended version)

Please read the documentation of the primary overload of createProcessingThreads() for a general overview.

This extended method allows the user to supply a thread initialization function that will be called at the beginning of the newly created background threads. This allows the user to customize the thread properties (such as the thread priority or the CPU affinity) themselves.

This function will only return once all thread initialization functions have run.

The thread initialization functions are only called for the backgronud threads that are started by this method; this means that for a count of 4 the initialization function will be called in 3 background threads, and it is up to the user to alter the thread in which they call ProcessingContext::processNext() to process data with fluxEngine.

The threads will be created sequentially, the next thread being created only after the previous thread’s initialization function has completed. This allows the user to directly modify global data structures in the initialization functions without the need for locking.

An example call to this method could be something like this: 

handle.createProcessingThreads(4, [&] (int threadId, int threadCount) {
    (void) threadCount;
    // Run thread 1 on core 1, thread 2 on core 2, etc.
    int cpuCoreId = threadId;
    pinCurrentThreadCPUCoreWithId(cpuCoreId);
    setCurrentThreadPriority(ThreadPriority::High);
    // The thread 0 will be the thread that calls
    // processNext() on a processing context, and will have
    // to have these settings applied elsewhere
});

(The functions called within the initialization function are just example names. It would be up to the user to implement them.)

If the user detects an error condition during thread initialization and wants to abort, they should throw an exception in the initialization function they supplied, which will be propagated out of the call to this method.

Important: any attempt to call a method that accesses this handle inside the initialization functions will create a deadlock.

This method may only be called if there are currently no background threads associated with this handle. Otherwise stopProcessingThreads() must be called first to change the number of threads.

Any processing context that was created before a call to this method was made is marked as invalid and can only be destroyed, but not used anymore.

If an error occurs, an exception will be thrown. The following exceptions may be thrown by this method:

Parameters
  • count: The number of threads to use for parallel processing (one less than this number will be created by this method, see the description for details)
  • initFunction: The thread initialization function. This may be a lambda function

void stopProcessingThreads()

Stop all existing processing threads.

This will stop any background threads that are currently associated with a given handle. If processing is currently active on the handle, it will be aborted, as if ProcessingContext::abort() had been called. In that case this method may take a bit of time, as abort operations are not immediate, and this method will wait until the abort has completed.

Any processing context that was created before a call to this method was made is marked as invalid and can only be destroyed, but not used anymore.

This method is always successful: the only errors that could occur when calling this method would be non-recoverable.

This method may safely be called on an invalid handle, that would have no effect.

operator bool() const

Boolean conversion operator.

This allows the user to easily check if a variable of this type currently holds a valid handle. For example: 

if (handle) {
    // the handle is valid
}

void setDriverBaseDirectory(std::string const &directory)

Set the driver base directory.

When loading drivers this sets the base directory where the drivers may be found. If this method is not called, or an empty value is passed, the directory drivers one level above the directory of the currently running executable will be used. For example, if the executable is C:\App\bin\engine_test.exe, the default drivers directory would be C:\App\drivers. (This is the case on all platforms.)

Note that if this method is not used the user can also override the default via an environment variable per driver type. (See the introductory documentation for more details.)

The directory specified here must exist, otherwise it will not be used and an error will be raised.

Windows note: this will accept a path in the 8bit local file name encoding, which will not be able to represent all possible Unicode characters that may be used on Windows. Please use the override that accepts a std::wstring instead if possible, in order to supply a wide name.

Parameters
  • directory: The driver base directory

void setDriverBaseDirectory(std::wstring const &directory)

Set the driver base directory (wide/Unicode variant for Windows)

When loading drivers this sets the base directory where the drivers may be found. If this method is not called, or an empty value is passed, the directory drivers one level above the directory of the currently running executable will be used. For example, if the executable is C:\App\bin\engine_test.exe, the default drivers directory would be C:\App\drivers. (This is the case on all platforms.)

Note that if this method is not used the user can also override the default via an environment variable per driver type. (See the introductory documentation for more details.)

The directory specified here must exist, otherwise it will not be used and an error will be raised.

This variant is only available on Windows to specify wide/Unicode paths.

Parameters
  • directory: The driver base directory

void setDriverIsolationExecutable(std::string const &executable)

Set the path to the driver isolation executable.

Drivers are loaded via the fluxDriverIsolation executable (on Windows fluxDriverIsolation.exe), in case the default is not where the executable is deployed. The defaults are:

On Windows and macOS the fluxDriverIsolation executable is assumed to be in the same directory as the current executable by default. For example, if the executable is C:\App\bin\engine_test.exe on Windows, the default driver isolation path is assumed to be C:\App\bin\fluxDriverIsolation.exe. Similarly, on macOS, if the main executable is in /Applications/engine_test.app/Contents/MacOS/engine_test, the driver isolation executable is assumed to be in /Applications/engine_test.app/Contents/MacOS/fluxDriverIsolation.

On all other platforms (Linux) the executable is assumed to be in ../libexec/fluxDriverIsolation relative to the current executable path. For example, if the executable is in /opt/engine_test/bin/engine_test, the driver isolation executable will be looked for in /opt/engine_test/libexec/fluxDriverIsolation by default.

Windows note: this will accept a path in the 8bit local file name encoding, which will not be able to represent all possible Unicode characters that may be used on Windows. Please use the override that accepts a std::wstring instead if possible, in order to supply a wide name.

Parameters
  • executable: The path to the fluxDriverIsolation executable

void setDriverIsolationExecutable(std::wstring const &executable)

Set the path to the driver isolation executable (wide/Unicode variant for Windows)

Drivers are loaded via the fluxDriverIsolation executable (on Windows fluxDriverIsolation.exe), in case the default is not where the executable is deployed. The defaults are:

On Windows and macOS the fluxDriverIsolation executable is assumed to be in the same directory as the current executable by default. For example, if the executable is C:\App\bin\engine_test.exe on Windows, the default driver isolation path is assumed to be C:\App\bin\fluxDriverIsolation.exe. Similarly, on macOS, if the main executable is in /Applications/engine_test.app/Contents/MacOS/engine_test, the driver isolation executable is assumed to be in /Applications/engine_test.app/Contents/MacOS/fluxDriverIsolation.

On all other platforms (Linux) the executable is assumed to be in ../libexec/fluxDriverIsolation relative to the current executable path. For example, if the executable is in /opt/engine_test/bin/engine_test, the driver isolation executable will be looked for in /opt/engine_test/libexec/fluxDriverIsolation by default.

This variant is only available on Windows to specify wide/Unicode paths.

Parameters
  • executable: The path to the fluxDriverIsolation executable

Models

class Model

A runtime model.

This class wraps a runtime model that has been loaded into fluxEngine.

The default constructor does not actually create an object, the user must use one of the other constructors to actually load a model.

Public Functions

Model()

Default constructor.

The object created by this constructor is not a valid model.

Model(Handle &handle, void const *modelData, std::size_t modelDataSize)

Load a model from memory.

This constructor allows the user to supply fluxEngine with a serialized runtime model that the user has already loaded into memory.

If the user destroys the library handle while this object still exists, this object will be marked as invalid. It must still be destroyed to avoid resource leaks.

If an error occurs, an exception will be thrown. The following exceptions may be thrown by this constructor:

Parameters
  • handle: The fluxEngine handle. This is required as the loaded license determines whether specific features within a model are allowed
  • modelData: The raw binary data of the model
  • modelDataSize: The raw binary size of the model, in bytes

Model(Handle &handle, std::vector<std::byte> const &modelData)

Load a model from memory (convenience wrapper)

If the runtime model binary data is present as a std::vector<std::byte> this convenience wrapper exists to allow the user to use that to load the model.

This wrapper is only available when compiling with a compiler that supports C++17.

See the documentation for the primary constructor for more details.

Parameters
  • handle: The fluxEngine handle. This is required as the loaded license determines whether specific features within a model are allowed
  • modelData: The raw binary data of the model

Model(Handle &handle, FromFile_Tag, std::string fileName)

Load a model from disk.

This contructor allows the user to load a runtime model from a file. Example usage: 

Model model(handle, Model::FromFile, "model.fluxmdl");

Note to Windows users: the file path specified here must be encoded in the local codepage, which is not able to encode all possible file names that Windows supports. It is highly recommended to use the wide string overload of this constructor on Windows, which accepts a wide (“Unicode”) file name and does support all possible file names that Windows supports. If this 8bit version is used on Windows with an encoding different from the local codepage, this constructor will very likely fail.

If the user destroys the library handle while this object still exists, this object will be marked as invalid. It must still be destroyed to avoid resource leaks.

If an error occurs, an exception will be thrown. The following exceptions may be thrown by this constructor:

Parameters
  • handle: The fluxEngine handle. This is required as the loaded license determines whether specific features within a model are allowed
  • fileName: The name of the file to load

Model(Handle &handle, FromFile_Tag, std::wstring fileName)

Load a model from disk (Windows wide “Unicode” variant)

This contructor is identical to the other constructor that loads a file, but it takes a wide (“Unicode”) filename of Windows systems, to support opening files that can’t be encoded in the local codepage. Example usage: 

Model model(handle, Model::FromFile, L"model.fluxmdl");

Note

This function is only available on Windows and does not exist on other operating systems.

Please refer to the documentation of the constructor for standard 8bit filenames for details on the behavior of this function beyond the encoding of the filename.

Parameters
  • handle: The fluxEngine handle. This is required as the loaded license determines whether specific features within a model are allowed
  • fileName: The name of the file to load, as a wide (“Unicode”) string

Model(Model &&other)

Move constructor.

Parameters
  • other: The model to move into the newly created object

Model &operator=(Model &&other)

Move assginment operator.

Return
A reference to this
Parameters
  • other: The model to move into this object

~Model()

Destructor.

Destroys a model, freeing its resources.

int numGroups() const

Get the number of groups in a model.

If an error occurs, one of the following exceptions may be thrown:

Return
The number of groups

GroupInfo groupInfo(int groupId) const

Get the group information for a given group.

Returns information about a group in a model. This consists of the name of the group (encoded as UTF-8) as well as a color value as a 32bit integer. See the GroupInfo structure for further details.

The group id must be within 0 and one less than the number of groups in the model. For example, a model with 5 groups will have the ids 0, 1, 2, 3, and 4.

Another method, groupInfos(), will return a std::vector of all groups in the model.

If an error occurs, one of the following exceptions may be thrown:

Return
The information about that group
Parameters
  • groupId: The id of the group to obtain the information about

std::vector<GroupInfo> groupInfos() const

Get the information about all groups in a model.

This helper function obtains the information about all groups in the current model and returns them as a vector. The index of that vector is the id of the group.

If an error occurs, one of the following exceptions may be thrown:

Return
A vector of the information of all groups in the model

operator bool() const

Boolean conversion operator.

This allows the user to easily check if a variable of this type currently holds a valid model. For example: 

if (model) {
    // the model is valid
}

struct FromFile_Tag

Tag structure to differentiate constructors.

This structure allows the user to indicate they want to call a constructor that will load a file from disk.

struct GroupInfo

Group information.

This structure contains the information about a group that is stored within a given runtime model.

Public Functions

uint8_t colorRedComponentValue() const

Obtain the red color component value.

Obtains the red component value of the color of the group, in a range of 0 through 255.

This helper function exists to make interpreting a given color simpler.

Return
The red color component value

uint8_t colorGreenComponentValue() const

Obtain the green color component value.

Obtains the green component value of the color of the group, in a range of 0 through 255.

This helper function exists to make interpreting a given color simpler.

Return
The green color component value

uint8_t colorBlueComponentValue() const

Obtain the blue color component value.

Obtains the blue component value of the color of the group, in a range of 0 through 255.

This helper function exists to make interpreting a given color simpler.

Return
The blue color component value

Public Members

std::string name

The name of the group.

This is encoded as UTF-8.

uint32_t color = {0xff0000u}

The color of the group.

This is encoded in the format 0xffRRGGBB. To obtain the red, green and blue values of the color one may use the helper methods that are part of this structure.

Data Processing

enum fluxEngine::DataType

A scalar data type.

This enumeration lists the supported scalar data types that may be used as input for HSI data, as well as the data types of the data that may be returned.

Values:

UInt8 = fluxEngine_C_v1_DataType_UInt8

8bit Unsigned Integer

UInt16 = fluxEngine_C_v1_DataType_UInt16

16bit Unsigned Integer

UInt32 = fluxEngine_C_v1_DataType_UInt32

32bit Unsigned Integer

UInt64 = fluxEngine_C_v1_DataType_UInt64

64bit Unsigned Integer

Int8 = fluxEngine_C_v1_DataType_Int8

8bit Signed Integer

Int16 = fluxEngine_C_v1_DataType_Int16

16bit Signed Integer

Int32 = fluxEngine_C_v1_DataType_Int32

32bit Signed Integer

Int64 = fluxEngine_C_v1_DataType_Int64

64bit Signed Integer

Float32 = fluxEngine_C_v1_DataType_Float32

32bit Single Precision IEEE 754 Floating Point

Float64 = fluxEngine_C_v1_DataType_Float64

64bit Double Precision IEEE 754 Floating Point

enum fluxEngine::ValueType

The value type of a given input.

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

Values:

Intensity = fluxEngine_C_v1_ValueType_Intensity

Intensities.

The data supplied by the user are raw intensities. If the model is set to process reflectances and/or absorbances reference data must be provided before processing can occur.

Reflectance = fluxEngine_C_v1_ValueType_Reflectance

Reflectances.

The data supplied by the user are reflectances.

struct ReferenceInfo

Information about references.

This information structure must be supplied when creating a processing context. It specifies the input value type of the processing context, as well as any references.

There are three primary ways to handle referencing of data:

  • The source in the model is set to raw intensities, and raw intensities are supplied by the user for the input data of the model while processing. In that case any references provided will be ignored
  • The source in the model is set to reflectances or absorbances, and the user provides reflectances for the input data of the model while processing. In that case any references provided will be ignored
  • The source in the model is set to reflectances or absorbances, and the user provides raw intensities for the input data of the model while processing. In that case a white reference must be provided to automatically reference the input data, and optionally a dark reference may be provided.

When referencing input data, if only a white reference is provided, reflectances are calculated with the following formula: 

reflectance = intensity / white

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

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

Public Members

ValueType valueType = {ValueType::Intensity}

The value type of the input data.

void const *whiteReference = {nullptr}

The white reference data.

This must be a tensor that is contiguous in memory that contains the white reference that will be used in conjunction with the input data.

Since it is advantageous to average multiple reference measurements, this tensor has to have an additional dimension to denote a list of input frames.

  • For HSI cubes in BIP order, this means the dimensionality of this tensor has to be (N, height, width, bands).
  • For HSI cubes in BIL order the dimensionality of the tensor has to be (N, height, bands, width)
  • For HSI cubes in BSQ order the dimensionality of the tensor has to be (N, bands, height, width)
  • For PushBoom frames in LambdaX order the dimensionality of the tensor has to be (N, width, bands)
  • For PushBroom frames in LambdaY order the dimensionality of the tensor has to be (N, bands, width)

The number of averages, N, may be 1, indicating that no average is to be calculated.

std::vector<std::int64_t> whiteReferenceDimensions

The dimensions of the white reference.

This must have the correct number of entries depending on the type of processing context that is being created; when creating a processing context for HSI cubes this must contain four entries (see the documentation for ReferenceInfo::whiteReference for further details), when creating a processing context for PushBroom frames this must contain three entries.

void const *darkReference = {nullptr}

The dark reference data.

std::vector<std::int64_t> darkReferenceDimensions

The dimensions of the dark reference.

enum fluxEngine::HSICube_StorageOrder

Hyperspectral data cube storage order.

Hyperspectral cubes consist of three dimensions, and the storage order defines how these dimensions are mapped into linear memory.

The introductory documentation also contains a visual depiction of the various storage orders of HSI cubes.

Values:

BIP = fluxEngine_C_v1_HSICube_StorageOrder_BIP

Band Interleaved by Pixel Storage Order.

In this storage order all wavelengths of each pixel are next to each other in memory. This means that the linear memory address of an element may be caluclated by the following formula (assuming the cube is contiguous in memory, see the various overloads of ProcessingContext::setSourceData() for more complicated cases): 

(y * width + x) * band_count + band_index

A cube stored in this storage order can be considered a row-major tensor of order 3 indexed as (y, x, band).

BIL = fluxEngine_C_v1_HSICube_StorageOrder_BIL

Band Interleaved by Line Storage Order.

In this storage order all pixels of a line are next to each other in memory, and wavelengths are grouped by line. This means that the linear memory address of an element may be by the following formula (assuming the cube is contiguous in memory, see the various overloads of ProcessingContext::setSourceData() for more complicated cases): 

(y * band_count + band_index) * width + x

A cube stored in this storage order can be considered a row-major tensor of order 3 indexed as (y, band, x).

BSQ = fluxEngine_C_v1_HSICube_StorageOrder_BSQ

Band Sequential Storage Order.

In this storage order all pixels of an individual band are next to each other in memory, and wavelengths are grouped by image. This means that the linear memory address of an element may be by the following formula (assuming the cube is contiguous in memory, see the various overloads of ProcessingContext::setSourceData() for more complicated cases): 

(band_index * height + y) * width + x

A cube stored in this storage order can be considered a row-major tensor of order 3 indexed as (band, y, x).

enum fluxEngine::PushBroomFrame_StorageOrder

Hyperspectral PushBroom frame storage order.

A PushBroom camera is a hyperspectral camera that uses a 2D sensor to image a single line, where the optics project different wavelengths of the incoming light onto one of the sensor dimensions. The other sensor dimension is used to spatially resolve the line that is being imaged.

There are two possible orientations of the optics: the wavelengths could be mapped onto the x- or the y-direction of the camera sensor. This enumeration allows the user to select which of these storage orders is actually used.

Values:

LambdaX = fluxEngine_C_v1_PushBroomFrame_StorageOrder_LambdaX

Wavelengths are in X-direction.

The y direction of the frame contains the spatial information.

LambdaY = fluxEngine_C_v1_PushBroomFrame_StorageOrder_LambdaY

Wavelengths are in Y-direction.

The x direction of the frame contains the spatial information.

enum fluxEngine::OutputStorageType

The storage type of data at a given output sink.

When extracting data from fluxEngine, the data at a given output sink may be stored in different formats. This enumeration describes the possible formats the data is stored in. Please refer to the introductory information for a more detailed introduction on how data is returned from processing, and what kind of forms it may take.

Values:

Tensor = fluxEngine_C_v1_OutputStorageType_Tensor

Tensor data.

This is the most common case, where data at the end of processing is available as a tensor. For HSI data tensors will typically be of order 3, having a y dimension, x dimension and an additional dimension for e.g. spectral (wavelength) information.

ObjectList = fluxEngine_C_v1_OutputStorageType_ObjectList

Object list.

A list of objects that is stored as an array of OutputObject objects.

struct OutputObject : fluxEngine_C_v1_OutputObject

An object that is output.

If an output sink is configured to output object data, it will be an array of this structure, containing the information related to each object.

This object is actually just a wrapper around the original C structure that has the same binary data layout, but a lot of helper methods to extract information from the model.

After a processing step has completed, for every output sink that returns an object list, the following code can be used to extract this: 

auto sinkData = context.outputSinkData(sinkIndex);
auto beginPointer = static_cast<OutputObject const*>(sinkData.data);
auto endPointer = beginPointer + sinkData.sizes[0];
for (auto it = beginPointer; it != endPointer; ++it) {
    // it points to an object that was detected
}

Public Functions

std::int64_t boundingBoxX() const

Get the object’s bounding box: x coordinate of the left boundary.

Return
The object’s bounding box: x coordinate of the left boundary

std::int64_t boundingBoxY() const

Get the object’s bounding box: y coordinate of the top boundary.

For PushBroom frames this will indicate the starting frame of the object since the last reset.

Return
The object’s bounding box: y coordinate of the top boundary

std::int64_t boundingBoxWidth() const

Get the object’s bounding box: total width.

Return
The object’s bounding box: total width

std::int64_t boundingBoxHeight() const

Get the object’s bounding box: total height.

Return
The object’s bounding box: total height

double gravityCenterX() const

Get the object’s center of gravity: x coordinate.

The following equation will always be true: 

boundungBoxX() <= gravityCenterX() &&
    gravityCenterX() < (boundingBoxX() + boundingBoxWidth())

The object’s center of gravity: x coordinate

double gravityCenterY() const

Get the object’s center of gravity: y coordinate.

The following equation will always be true: 

boundungBoxY() <= gravityCenterY() &&
    gravityCenterY() < (boundingBoxY() + boundingBoxHeight())

The object’s center of gravity: y coordinate

std::int64_t area() const

Get the object’s area in pixels.

Return
The object’s area in pixels

std::int8_t const *mask() const

A pointer to the object’s mask.

This may not be present, in which case this will be nullptr. If this is present this will point to a 2D matrix (row-major storage order, contiguous in memory) that has the size of the bounding box specified in this object, where a value of 0 indicates that a given pixel belongs to the object, and a value of -1 indicates that it does not belong to the object.

A helper method isObjectPresentAt() exists to determine if a given pixel is part of the object.

See
isObjectPresentAt()
See
isObjectPresentAtAbsolute()
Return
A pointer to the object’s mask

bool isObjectPresentAt(std::int64_t x, std::int64_t y) const

Determine if a given pixel is part of the detected object.

For a given set of coordinates for a pixel that are measured relative to the top-left corner of the bounding box this method will determine if that pixel belongs to the object or not.

If the object does not contain any mask information, this will always return false.

Return
Whether a pixel is part of the object
Parameters
  • x: The x coordinate relative to the top-left corner of the bounding box of the object to check
  • y: The y coordinate relative to the top-left corner of the bounding box of the object to check

bool isObjectPresentAtAbsolute(std::int64_t x, std::int64_t y) const

Determine if a given pixel is part of the detected object.

For a given set of coordinates for a pixel that are measured absolutely to the start of the cube this method will determine if that pixel belongs to the object or not. For sequences of PushBroom frames that are being processed the y coordinate is measured in the number of frames since the last reset via ProcessingContext::resetState().

If the object does not contain any mask information, this will always return false.

Return
Whether a pixel is part of the object
Parameters
  • x: The absolute x coordinate
  • y: The absolute y coordinate

bool hasPrimaryClass() const

Does the object have a primary class?

Note that the presence of a primary class is only an indication of whether the object was subject to a classifier in the processing chain. It does not mean that the classifier has actually found a class that matches the object. The primary class of an object may be present, but negative, indicating that a classifier was run, but that no class could be assigned to the object.

Return
Whether the object has a primary class

std::int16_t primaryClassValue() const

Get the primary class of the object.

If hasPrimaryClass() is false the return value here will have no meaning and might be uninitialized memory.

Note that the presence of a primary class is only an indication of whether the object was subject to a classifier in the processing chain. It does not mean that the classifier has actually found a class that matches the object. The primary class of an object may be present, but negative, indicating that a classifier was run, but that no class could be assigned to the object.

Return
The primary class of the object

std::optional<std::int16_t> primaryClass() const

Get the primary class of the object.

This method only exists when compiling with a C++17 compiler. It returns a std::optional result, which will be std::nullopt if the object was not subject to a classifier, and a valid integer if it was.

Note that the presence of a primary class is only an indication of whether the object was subject to a classifier in the processing chain. It does not mean that the classifier has actually found a class that matches the object. The primary class of an object may be present, but negative, indicating that a classifier was run, but that no class could be assigned to the object.

Return
The primary class of the object, or std::nullopt if the object has no primary class

void const *additionalData() const

Get additional data for the object.

This is an array of scalar values, the size being fixed after creation of the processing context, that contain additional data that is passed together with the object.

Return
Additional data for the object

class ProcessingContext

Processing Context.

This class wraps a processing context, the main interface to processing data with fluxEngine.

The default constructor does not actually create an object, the user must use one of the other constructors to actually load a model.

Public Functions

ProcessingContext()

Default constructor.

The object created by this constructor is not a valid processing context.

ProcessingContext(Model &model, HSICube_Tag, HSICube_StorageOrder storageOrder, DataType dataType, std::int64_t maxHeight, std::int64_t height, std::int64_t maxWidth, std::int64_t width, std::vector<double> const &wavelengths, ReferenceInfo const &referenceInfo)

Create a new processing context for HSI cubes.

This method creates a new processing context that may be used to process HSI data cubes. The context may be used to process multiple cubes, as long as they have the same structure.

The cube will be processed as a whole, and depending on the complexity of the model a lot of temporary storage may be required to store all the intermediate processing results.

The following information must be known in advance to properly setup a fluxEngine processing context that can be used to process this type of HSI data:

  • The scalar data type
  • The storage order of the data in memory
  • The wavelengths
  • The maximum spatial dimensions that will be processed with this context

The user may choose to process cubes of the same size, or cubes of varying sizes. In the case of cubes that all have the same size, the user should specify the same value for both maxHeight and height, and for maxWidth and width, respectively. In the case the cube sizes vary, the user should specify -1 for both height and width, and specify the size of the largest cube they will ever want to process in maxHeight and maxWidth.

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

If creating the processing context fails, one of the following exceptions may be thrown:

Parameters
  • model: The model to use to process data
  • storageOrder: The storage order the input data will have when it is supplied to the processing context
  • dataType: The scalar data type of the input data when it is supplied to the processing context
  • maxHeight: The maximum height of a cube that will be processed using this processing context
  • height: Specify -1 here to leave the cube height dynamic (which might not be as efficient at runtime for some models), or the same value as maxHeight to fix the height and indicate it will always be the same for every cube that is being processed.
  • maxWidth: The maximum width of a cube that will be processed using this processing context
  • width: Specify -1 here to leave the cube width dynamic (which might not be as efficient at runtime for some models), or the same value as maxWidth to fix the width and indicate it will always be the same for every cube that is being processed.
  • wavelengths: The list of wavelengths of the input cubes being processed, in the unit of nanometers
  • referenceInfo: How the data should be referenced, see the ReferenceInfo structure for more details

ProcessingContext(Model &model, PushBroomFrame_Tag, PushBroomFrame_StorageOrder storageOrder, DataType dataType, std::int64_t width, std::vector<double> const &wavelengths, ReferenceInfo const &referenceInfo)

Create a new processing context for PushBroom frames.

This constructor creates a new processing context that may be used to sequentially process PushBroom frames. Each consecutive frame is considered to be part of a stream of lines that in principle could be used to construct a cube if concatenated.

The following information must be known in advance to properly setup a fluxEngine processing context that can be used to process this type of HSI data:

  • The scalar data type
  • The storage order of the data in memory
  • The wavelengths
  • The exact spatial dimension that will be processed with this context; as PushBroom frames should be able to be concatenated, the size of the frame may not be variable, but the number of frames being processed may vary

If creating the processing context fails, one of the following exceptions may be thrown:

Parameters
  • model: The model to use to process data
  • storageOrder: The storage order the input data will have when it is supplied to the processing context
  • dataType: The scalar data type of the input data when it is supplied to the processing context
  • width: The spatial dimension of each PushBroom frame that is supplied (if the storage order indicates that wavelengths are across the x direction of the frame, this indicates the size of the frame in the y direction, and vice-versa)
  • wavelengths: The list of wavelengths of the input cubes being processed, in the unit of nanometers
  • referenceInfo: How the data should be referenced, see the ReferenceInfo structure for more details

ProcessingContext(ProcessingContext &&other)

Move constructor.

Parameters
  • other: The processing context to move into the newly created object

ProcessingContext &operator=(ProcessingContext &&other)

Move assignment operator.

Return
A reference to this
Parameters
  • other: The processing context to move into this variable

~ProcessingContext()

Destructor.

Destroys the processing context.

int numOutputSinks() const

Obtain the number of output sinks in the model.

To retrieve data that has been processed via fluxEngine the designer of the model must add output sinks to the places where data is to be extracted.

This function returns the number of output sinks within the given model. This may be used to iterate over the output sinks and determine their data structure given the input data structure that is supplied.

If an error occurs, this method may throw one of the following exceptions:

Return
The number of output sinks in the model

int findOutputSink(int outputId) const

Find the output sink with a given output id.

If there is exactly one output sink in the model with a given output id, this will return the index of that sink. If there are no output sinks with that id, or that output id is used multiple times, this will return an error.

If an error occurs, this method may throw one of the following exceptions:

Return
The index of the output sink with a given output id
Parameters
  • outputId: The output sink of the output sink to look for

OutputSinkMetaInfo outputSinkMetaInfo(int sinkIndex) const

Obtain meta information about a given output sink.

For a given output sink index that ranges between 0 and one less than the value returned by numOutputSinks() this method will return meta information about the output sink.

If an error occurs, this method may throw one of the following exceptions:

Return
The meta information about the given output sink
Parameters
  • sinkIndex: The index of the output sink to introspect

std::vector<OutputSinkMetaInfo> outputSinkMetaInfos() const

Obtain a list of meta information about all output sinks.

This convenience method returns a list of meta information for all output sinks in the model. The index of the vector is the corresponding sink index.

If an error occurs, this method may throw one of the following exceptions:

Return
A list of meta information about all output sinks

OutputSinkTensorStructure outputSinkTensorStructure(int sinkIndex) const

Obtain information about the tensor structure of a given output sink.

For an output sink with data of tensor type (see OutputStorageType::Tensor for details), this function will return the tensor structure of the data that will be returned via the output sink.

If the storage type does not match, this function will throw an exception.

Please see the documentation for outputSinkData() for more information on how to process tensor data.

If an error occurs, this method may throw one of the following exceptions:

Return
The tensor structure of the given output sink
Parameters
  • sinkIndex: The index of the output sink to introspect

OutputSinkObjectListStructure outputSinkObjectListStructure(int sinkIndex) const

Obtain information about the object structure of a given output sink.

For any output sink with data of object list type (see OutputStorageType::ObjectList for details), this method will return information about the object list that is returned.

If the storage type does not match, this function will throw an exception.

Please see the documentation for outputSinkData() for more information on how to process object list data.

If an error occurs, this method may throw one of the following exceptions:

Return
Information about the object structure of a given output sink
Parameters
  • sinkIndex: The index of the output sink to introspect

OutputSinkInfo outputSinkInfo(int sinkIndex) const

Obtain output sink information for a given sink index.

This convenience wrapper is only available when compiling with a C++17 compiler. It provides a convenient method of obtaining all the metadata of an output sink in form of a single structure.

See the documentation of the OutputSinkInfo structure for further details.

If an error occurs, this method may throw one of the following exceptions:

Return
The information and structure of the output sink
Parameters
  • sinkIndex: The index of the output sink to introspect

std::vector<OutputSinkInfo> outputSinkInfos() const

Obtain information about all output sinks.

This convenience wrapper is only available when compiling with a C++17 compiler. It provides a convenient method of obtaining all information about all output sinks as a vector. The index of the vector is the output sink index.

See the documentation of the OutputSinkInfo structure for further details.

Return
A vector of information structures for every output sink in the model

void setSourceData(HSICube_Tag, std::int64_t height, std::int64_t width, void const *data)

Set the next input data to be processed (HSI cube)

Set the next input data that should be processed by fluxEngine. The user must supply a pointer to a memory region that contains the input data stored contiguously in memory. (For non-contiguously stored data the user may use the alternative overload of this method that also accepts strides.)

The user must ensure that the memory region that contains the input data is not altered while ProcessingContext::processNext() is active. (It may be altered after setting it here and before calling it though, as long as the dimensions don’t change.)

If the input cube size was fixed during the creation of the processing context, the height and width parameters must match the height and width specified during creation of the context, or an error will be thrown.

If the input cube size was variable during the creation of the processing context, the height and width parameters must be smaller than or equal to the maximum size specified during the creation of the context.

The storage order of the cube that has been specified during the creation of the processing context will be used. This means that the height and width parameters may refer to different dimensions of the cube depending on the storage order:

  • For a BIP cube, the cube will be indexed via (y, x, band), meaning the height parameter referes to the dimension 0, the width parameter to dimension 1 and the wavelength count supplied during creation of the cube to the dimension 2 of the cube.
  • For a BIL cube, the cube will be indexed via (y, band, x), meaning the height parameter referes to the dimension 0, the width parameter to dimension 2 and the wavelength count supplied during creation of the cube to the dimension 1 of the cube.
  • For a BSQ cube, the cube will be indexed via (band, y, x), meaning the height parameter referes to the dimension 1, the width parameter to dimension 2 and the wavelength count supplied during creation of the cube to the dimension 0 of the cube.

Between calls to ProcessingContext::processNext() this method may be used to change the source data region that is to be used during the next processing call.

If the processing context was not set up to process HSI cubes (e.g. because it was set up to process PushBroom frames), an exception will be thrown.

If an error occurs, this method may throw one of the following exceptions:

Parameters
  • height: The height of the HSI cube to process
  • width: The width of the HSI cube to process
  • data: A pointer to a region of memory that contains the HSI cube stored contiguously, and must be of size width * height * band_count * scalar_size in bytes.

void setSourceData(HSICube_Tag, std::int64_t height, std::int64_t width, std::int64_t stride1, std::int64_t stride2, void const *data)

Set the next input data to be processed (HSI cube, non-contiguous)

This is an extended version of the standard overload of this method. Please see the documentation of that method for details that do not pertain to the strides.

It is possible to lay out cubes non-contiguously in memory. For example, take a 2x2x2 cube with the following 8 elements: 

cube(0, 0, 0) = 0
cube(0, 0, 1) = 1
cube(0, 1, 0) = 2
cube(0, 1, 1) = 3
cube(1, 0, 0) = 4
cube(1, 0, 1) = 5
cube(1, 1, 0) = 6
cube(1, 1, 1) = 7

When layed out contiguously in memory, the cube will have the following structure: 

 dimension 2
(increment by 1)   dimension 0
  +---+          (increment by 4)
  |   |       +---------------+
  |   |       |               |
  |   v       |               v
+---+---+---+---+---+---+---+---+
| 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 |
+---+---+---+---+---+---+---+---+
  |       ^
  |       |
  +-------+
 dimension 1
(increment by 2)

To increment dimension 2 (the inner-most dimension) the element pointer must be incremented by 1. To increment dimension 1 (the middle dimension) the element pointer must be incremented by 2. To increment dimension 0 (the outer-most dimension) the element pointer has to be incremented by 4.

For cubes that reside contiguously in memory the increments here are always given by the dimensions of the cube. For example, a contiguous cube of dimensions (A, B, C) will have a stride structure of (B * C, C, 1).

However, it is possible that the cube is not contiguous in memory. In the above example, the stride structure for the contiguous cube was (4, 2, 1) due to the size of the cube - but if the stride structure is chosen as (9, 3, 1) the memory layout of the cube would look differently: 

 dimension 2
(increment by 1)   dimension 0
  +---+          (increment by 9)
  |   |       +-----------------------------------+
  |   |       |                                   |
  |   v       |                                   v
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
| 0 | 1 | _ | 2 | 3 | _ | _ | _ | _ | 4 | 5 | _ | 6 | 7 |
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
  |           ^
  |           |
  +-----------+
 dimension 1
(increment by 3)

For the HSI cube that is passed to this method, it will have the stride structure (stride1, stride2, 1).

As an example, if the cube is contiguous in memory (and the other overload of setSourceData() could have been used instead), the following stride structure is assumed:

  • For contiguous BIP cubes (dimensions (y, x, band)) stride1 would be width * band_count, stride2 would be band_count.
  • For contiguous BIP cubes (dimensions (y, band, x)) stride1 would be band_count * width, stride2 would be width.
  • For contiguous BSQ cubes (dimensions (band, y, x)) stride1 would be height * width, stride2 would be width.

If an error occurs, this method may throw one of the following exceptions:

Parameters
  • height: The height of the HSI cube to process
  • width: The width of the HSI cube to process
  • stride1: The number of scalar elements to skip to increment the left-most dimension of the cube by 1
  • stride2: The number of scalar elements to skip to increment the middle dimension of the cube by 1
  • data: A pointer to a region of memory that contains the HSI cube, and must be of size height * stride1 * scalar_size (BIP and BIL storage orders) or band_count * stride1 * scalar_size (BSQ storage order) in bytes

void setSourceData(PushBroomFrame_Tag, void const *data)

Set the next input data to be processed (PushBroom frame)

Set the next input data that should be processed by fluxEngine. The user must supply a pointer to a memory region that contains the input data stored contiguously in memory. (For non-contiguously stored data the user may use alternative overload of this method that also accepts a stride.)

The user must ensure that the memory region that contains the input data is not altered while ProcessingContext::processNext() is active. (It may be altered after setting it here and before calling it though, as long as the dimensions don’t change.)

The input PushBroom frame size had to be fixed during the creation of the processing context, and the size of the frame must be equal to width and band_count.

The storage order of the cube that has been specified during the creation of the processing context will be used. The supplied frame must be a 2D image with the following dimensions:

  • For LambdaX storage order, the width of the image must be equal to the wavelength count specified during the creation of the processing context, while the height of the image must be equal to the specified spatial width.
  • For LambdaY storage order, the height of the image must be equal to the wavelength count specified during the creation of the processing context, while the width of the image must be equal to the specified spatial width.

Between calls to ProcessingContext::processNext() this function may be used to change the source data region that is to be used during the next processing call.

If the processing context was not set up to process PushBroom frames (e.g. because it was set up to process HSI cubes), an exception will be thrown.

If an error occurs, this method may throw one of the following exceptions:

Parameters
  • data: A pointer to a region of memory that contains the PushBroom frame stored contiguously, and must be of size width * band_count * scalar_size in bytes.

void setSourceData(PushBroomFrame_Tag, std::int64_t stride, void const *data)

Set the next input data to be processed (PushBroom frame, non-contiguous)

This is an extended version of the standard overload of this method. Please see the documentation of that method for details that do not pertain to the strides.

An image may be layed out non-contiguously in memory. For example, take a 2x2 image with the following data: 

image(y = 0, x = 0) = 0
image(y = 0, x = 1) = 1
image(y = 1, x = 0) = 2
image(y = 1, x = 1) = 3

This will have the following contiguous representation in memory: 

 dimension 1
(increment by 1)
  +---+
  |   |
  |   |
  |   v
+---+---+---+---+
| 0 | 1 | 2 | 3 |
+---+---+---+---+
  |       ^
  |       |
  +-------+
 dimension 0
(increment by 2)

However, the memory may also be stored non-contiguously. For example, if 3 scalar elements are to be skipped whenever the y dimension of the image is incremented, the layout would look like this: 

 dimension 1
(increment by 1)
  +---+
  |   |
  |   |
  |   v
+---+---+---+---+---+
| 0 | 1 | _ | 2 | 3 |
+---+---+---+---+---+
  |           ^
  |           |
  +-----------+
 dimension 0
(increment by 3)

If an error occurs, this method may throw one of the following exceptions:

Parameters
  • stride: The number of scalar elements to skip to get to the next line within the PushBroom frame
  • data: A pointer to a region of memory that contains the PushBroom frame, and must be of size stride * band_count * scalar_size (LambdaY case) or stride * width * scalar_size (LambdaX case) in bytes.

void processNext()

Process the next piece of data.

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

This method will return once processing of the current data has completed or an error has occurred. The current thread will be used as the thread 0 for parallelization purposes.

If an error occurs, this method may throw one of the following exceptions:

void resetState()

Reset the state of the processing context.

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

When the data to be processed is in the form of entire HSI cubes, that is, the context was created via the overload of the constructor that indicates HSI cubes should be processed, this method will have no effect. (Unless processing was aborted via abort(), in which case this must be called to clean up the state.)

When the data to be processed is in the form of consecutive PushBroom frames, that is, the context was created via the overload of the constructor that indicates PushBroom frames should be processed, this method will reset the internal state and make the context appear as if it had been freshly created. This means that any operation that remembers past state to gain spatial information in the y direction will be reset to the beginning. This affects mostly object-based operations.

This would typically be called when a system with a PushBroom camera is started up again after a pause, and the previously processed data has no direct relation to the data to be processed from this point onwards.

If an error occurs, this method may throw one of the following exceptions:

void abort()

Abort processing.

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

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

If an error occurs, this method may throw one of the following exceptions:

void wait()

Wait until processing or an abort is complete.

This method may be called from a different thread while processing is currently active. It will wait until the processing context is not in use anymore, either because processing has completed in the mean time, or an abort was requested and the abort has completed.

Note that ProcessingContext::processNext() already blocks and this method must only be used from different threads that also want to wait for the processing of a specific context to complete.

If an error occurs, this method may throw one of the following exceptions:

OutputSinkData outputSinkData(int sinkIndex) const

Get the resulting output sink data of a given processing context.

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

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

Return
The output data of the chosen output sink from the last processing operation that was performed
Parameters
  • sinkIndex: The index of the output sink to obtain the output data from

operator bool() const

Boolean conversion operator.

This allows the user to easily check if a variable of this type currently holds a valid processing context. For example: 

if (context) {
    // the context is valid
}

void setSourceData(BufferInfo const &deviceBuffer)

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

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

void setSourceData(PersistentBufferInfo const &persistentBuffer)

Set the next input data to be processed from persistent buffer.

Parameters
  • persistentBuffer: The persistent buffer to use

Public Static Functions

ProcessingContext createInstrumentPreviewContext(InstrumentDevice *device)

Create a processing context for previewing instrument data.

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

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

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

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

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

  • For a spectrometer this will result in a single vector of intensities. (Tensor of order 1.)
  • For a HSI PushBroom camera this will result in a tensor of order 3, with the first dimension always being 1 (because the y direction only has a single entry), the second dimension being the spatial dimension, and the final dimension being the spectral dimension, regardless of spectrograph orientation.
  • For HSI imager cameras this will result in a tensor of order 3, with the first dimension corresponding to the y dimension, the second to the x dimension, and the third to the spectral dimension, regardless of how the cube has been obtained by the camera (mosaic pattern, filter wheel, etc.).
  • For a monochrome polarization camera this will result in a tensor of order 3, with the first dimension corresponding to the y dimension, the second to the x dimension, and the third to the various polarization directions for that camera, regardless of the exact construction (mosaic imager, beam-split multi-camera with various polarization filters, etc.).

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

Data must be supplied to this processing context via the overload of ProcessingContext::setSourceData() that takes a BufferInfo or a PersistentBufferInfo.

Return
The preview processing context
Parameters
  • device: The instrument device

ProcessingContext::HSIRecordingResult createInstrumentHSIRecordingContext(InstrumentDevice *device, ValueType valueType, InstrumentParameters const &instrumentParameters, std::vector<double> const &targetWavelengths = {})

Create a processing context (HSI and spectrometer data recording)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  • For a spectrometer this will result in a single vector of intensities. (Tensor of order 1.)
  • For a HSI PushBroom camera this will result in a tensor of order 3, with the first dimension always being 1 (because the y direction only has a single entry), the second dimension being the spatial dimension, and the final dimension being the spectral dimension, regardless of spectrograph orientation.
  • For HSI imager cameras this will result in a tensor of order 3, with the first dimension corresponding to the y dimension, the second to the x dimension, and the third to the spectral dimension, regardless of how the cube has been obtained by the camera (mosaic pattern, filter wheel, etc.).

Data must be supplied to this processing context via the overload of ProcessingContext::setSourceData() that takes a BufferInfo or a PersistentBufferInfo.

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

Return
A result structure containing the processing context as well as the normalized references.
Parameters
  • device: The instrument device
  • valueType: The requested value type of the data that is to be returned.
  • instrumentParameters: The instrument parameters, mainly the previously measured reference data.
  • targetWavelengths: Optional: a list of wavelengths to regularize the wavelengths to. Supply an empty vector in case the wavelengths of the instrument are to be used and the data should not normalized in this manner.

ProcessingContext::HSIRecordingResult createInstrumentHSIRecordingContext(InstrumentDevice *device, ValueType valueType, InstrumentParametersEx const &instrumentParameters, std::vector<double> const &targetWavelengths = {})

Create a processing context (HSI and spectrometer data recording)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  • For a spectrometer this will result in a single vector of intensities. (Tensor of order 1.)
  • For a HSI PushBroom camera this will result in a tensor of order 3, with the first dimension always being 1 (because the y direction only has a single entry), the second dimension being the spatial dimension, and the final dimension being the spectral dimension, regardless of spectrograph orientation.
  • For HSI imager cameras this will result in a tensor of order 3, with the first dimension corresponding to the y dimension, the second to the x dimension, and the third to the spectral dimension, regardless of how the cube has been obtained by the camera (mosaic pattern, filter wheel, etc.).

Data must be supplied to this processing context via the overload of ProcessingContext::setSourceData() that takes a BufferInfo or a PersistentBufferInfo.

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

Return
A result structure containing the processing context as well as the normalized references.
Parameters
  • device: The instrument device
  • valueType: The requested value type of the data that is to be returned.
  • instrumentParameters: The instrument parameters, mainly the previously measured reference data.
  • targetWavelengths: Optional: a list of wavelengths to regularize the wavelengths to. Supply an empty vector in case the wavelengths of the instrument are to be used and the data should not normalized in this manner.

ProcessingContext createInstrumentProcessingContext(InstrumentDevice *device, Model &model, InstrumentParameters const &parameters)

Create a processing context (instrument device data processing)

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

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

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

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

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

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

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

This method accepts a structure that contains pointers to BufferContainer objects that contain the actual raw reference data that must be used when the user wants to specify a white reference. There is also an overload which supports reference data provided in raw form by the user.

Return
The processing context that will process data from the instrument with the given model
Parameters
  • device: The instrument device
  • model: The model to process the data with
  • instrumentParameters: The instrument parameters, mainly the previously measured reference data.

ProcessingContext createInstrumentProcessingContext(InstrumentDevice *device, Model &model, InstrumentParametersEx const &parameters)

Create a processing context (instrument device data processing)

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

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

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

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

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

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

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

This method accepts a structure that the user can fill with pointers to the raw data of the measured references when they want to specify a white reference. There is also an overload that supports reference data in the form of BufferContainer objects.

Return
The processing context that will process data from the instrument with the given model
Parameters
  • device: The instrument device
  • model: The model to process the data with
  • instrumentParameters: The instrument parameters, mainly the previously measured reference data.

struct HSICube_Tag

Tag structure to differentiate constructors.

This structure allows the user to indicate they want to call a constructor that will create a processing context for entire HSI cubes.

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

Public Members

ProcessingContext context

The resulting processing context.

std::vector<double> wavelengths

The list of wavelengths of the recorded data.

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

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

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

struct InstrumentParameters

Instrument parameters.

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

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

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

Public Members

BufferContainer *whiteReference = {}

The white reference buffer.

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

BufferContainer *darkReference = {}

The dark reference buffer.

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

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

struct InstrumentParametersEx

Instrument parameters (explicit version)

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

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

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

Public Members

int referenceOrder = {}

The order of the reference tensors.

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

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

void const *whiteReference = {}

The white reference data.

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

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

std::array<int64_t, 5> whiteReferenceDimensions = {}

The dimensions of the white reference.

Only the first referenceOrder entries will be considered.

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

std::array<int64_t, 5> whiteReferenceStrides = {}

The strides of the white reference.

Only the first referenceOrder entries will be considered.

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

void const *darkReference = {}

The dark reference data.

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

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

std::array<int64_t, 5> darkReferenceDimensions = {}

The dimensions of the dark reference.

Only the first referenceOrder entries will be considered.

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

std::array<int64_t, 5> darkReferenceStrides = {}

The strides of the dark reference.

Only the first referenceOrder entries will be considered.

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

struct OutputSinkData

Output sink data.

This structure is returned by outputSinkData() and contains a pointer to the actual data of the output sink.

Public Members

void const *data

The actual data that is being returned.

If the total size is 0 (see the sizes member) then this field might also be nullptr.

This is to be interpreted in two differnt manners:

  • For tensor data this is a tensor of the scalar type of the output sink that is contiguous in memory. The order of the tensor can be obtained from the tensor structure of the output sink (and will not change), the actual sizes might change and will be present in the sizes member. To obtain the pointer to the first elemnt of the tensor one may use (assuming the data type of the tensor is a signed 16bit integer for this example): 
    auto sinkData = context.outputSinkData(sinkId);
auto p = static_cast<std::int16_t const*>(sinkData.data);
  • For object list data this is a pointer to the first element of a vector of OutputObject elements. It may be accessed in the following manner: 
    auto sinkData = context.outputSinkData(sinkId);
auto beginPointer = static_cast<OutputObject const*>(sinkData.data);

std::int64_t sizes[5]

The actual sizes of the data that is being returned.

  • For tensor data this will contain the actual sizes of the tensor being returned. The order of the tensor may be obtained from the tensor structure of the output sink. For example, a tensor of order 3 will have sizes[0], sizes[1] and sizes[2] containing the actual dimension of the data that is being returned here; all other entries in the sizes field must be ignored by the user and may contain arbitrary data.
  • For object list data only the first element is relevant and contains the actual number of objects being returned. All other elements must be ignored.

struct OutputSinkInfo

Output sink information.

This convenience data structure is returned by outputSinkInfo() and outputSinkInfos() when compiling with a C++17 compiler. In that case this contains the meta information about and output together with its structure put together in this single structure.

Public Members

OutputSinkMetaInfo metaInfo

The meta information of the output sink.

std::variant<std::monostate, OutputSinkTensorStructure, OutputSinkObjectListStructure> structure

The structure of the output sink.

This uses std::variant to contain one of the following types, depending on the storage type of the output sink:

struct OutputSinkMetaInfo

Meta Information about an Output Sink.

This structure contains generic information about a given output sink. It is returned by outputSinkMetaInfo() and outputSinkMetaInfos() methods, and when compiling with a C++17 compiler is part of the OutputSinkInfo structure.

Public Members

int outputId = {}

The output id of the output sink.

This was configured during model creation in fluxTrainer.

OutputStorageType storageType = {}

The storage type of the output sink.

This determines what kind of data the output sink returns, depending on where in the processing chain it is connected.

std::string name

The name of the output sink.

This is encoded as UTF-8

std::int64_t inputDelay = {}

The input delay of the input sink.

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

struct OutputSinkObjectListStructure

Information about the object list structure of an output sink.

This is returned by the outputSinkObjectListStructure() method.

Public Members

std::int64_t maxObjectCount = {}

The maximum number of objects this output sink could return.

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

std::int64_t additionalDataCount = {}

The number of entries in the additional object data vector.

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

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

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

DataType additionalDataType = {}

The scalar data type of additional object data.

If additionalDataCount is zero this field does not have any meaning.

struct OutputSinkTensorStructure

Information about the tensor structure of an output sink.

This is returned by the outputSinkTensorStructure() method.

Public Members

std::vector<std::int64_t> maxSizes

The maximum sizes.

Indicates the maximum dimensions of the tensor data returned by the output sink. The order of the tensor is given by the number of entries in this vector.

std::vector<std::int64_t> fixedSizes

The fixed sizes.

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

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

DataType dataType = {}

The scalar data type of the tensor returned here.

This corresponds to the data type configured in the output sink during model creation.

struct PushBroomFrame_Tag

Tag structure to differentiate constructors.

This structure allows the user to indicate they want to call a constructor that will create a processing context for a sequence of PushBroom frames.

class ReferenceMeasurement

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.

This class acts somewhat like a shared pointer and an explicit boolean conversion operator to allow the user to determine whether it holds an actual measurement, or is empty.

See
ProcessingContext::createInstrumentHSIRecordingContext

Parameter Information

class ParameterInfo

Parameter information / list.

This class contains information about available parameters that may be updated by the user. It is used in two places:

  • During device connection this describes the available connection parameters. The user must provide a string -> string map with the values of these parameters during the connection process.
  • When connected to a device this describes the parameters the device provides. Getting/setting parameters occurs via separate methods of the Device class though.

Accessor methods of this class provide information about the various parameters represented. There are no explicit method sto read or write parameter values, as these are highly context-dependent. For connection parameters there are no getters and setters, as the user must provide a list to the connect function. For device parameters there are various methods that will get or set a specific parameter value.

Note that in the case of device parameters this structure is dynamic - changing a device parameter might change the access mode of other parameters. See ParameterInfo::affectedParameters() for details.

Each accessor is available in both an indexed variant, as well as a named variant (except for the accessor that obtains the name itself), depending on the type of the argument. For example, one may call ParameterInfo::parameterAccessMode() with an integer parameter, specifying an index into the list of parameters, starting at 0, ending at one less of the parameter count. But one may also provide the name of the parameter as a string argument to that method, to obtain the access mode of that parameter by name.

Additionally there is also the ParameterInfo::parameter() method, which returns a ParameterInfo::Parameter structure. That structure contains all the information about a specific parameter at once, and doesn’t require the user to obtain information about parameters one accessor at a time. If only a specific piece of information is required, though, it may be more efficient to simply ask for that specific piece of information directly via an accessor. Note that this method is only available if the compiler and the standard library support C++17, as std::variant and std::optional are used extensively in this structure.

For reading parameter information that optionally may contain a string value, such as the display name, or the short and long descriptions, there are two types of accessors:

  • C++11 compatible accessors whose method name starts with a get. They return a boolean value to indicate whether the value was present, and take a reference argument where the result will be stored if the value was present. (If the value was not present the second argument will remain untouched.)
  • C++17 accessors that rely on std::optional that return a std::optional<std::string> that don’t contain a get prefix in their name.

Public Types

enum Type

The type of the parameter.

Values:

Unknown = ::fluxEngine_C_v1_ParameterType_Unknown

Unknown type.

This is returned if a specific parameter does not fall into one of the other parameter types.

Boolean = ::fluxEngine_C_v1_ParameterType_Boolean

Boolean.

The parameter can either be true or false.

Integer = ::fluxEngine_C_v1_ParameterType_Integer

Integer.

The parameter is an integer value. There may be additional limits imposed on the range of the integer value.

Float = ::fluxEngine_C_v1_ParameterType_Float

Floating Point.

The parameter is a floating point value. There may be additional limits imposed on the range of the floating point value.

Enumeration = ::fluxEngine_C_v1_ParameterType_Enumeration

Enumeration.

The parameter can be chosen from a set of predetermined values. Each predetermined value is associated with an integer value as well as a unique name.

String = ::fluxEngine_C_v1_ParameterType_String

String.

The parameter is a string value. Note that strings have to be encoded as UTF-8.

File = ::fluxEngine_C_v1_ParameterType_File

File.

The parameter is the path to a file in the filesystem. The path can be accessed like a string.

Windows: as string-like parameters are always represented in UTF-8, the path here must also be encoded as UTF-8, not the local 8bit encoding. The UTF-8 representation will internally be converted to wide strings that will be used to access the actual file.

All other platforms: the local 8bit encoding should be used.

Command = ::fluxEngine_C_v1_ParameterType_Command

Command.

A command parameter is a parmaeter that can be used to trigger an action on the device.

enum AccessMode

The access mode of a given parameter.

The access mode describes whether a parameter may be read from or written to.

Values:

NotAvailable = ::fluxEngine_C_v1_ParameterAccessMode_NotAvailable

The parameter is not available.

This indicates that the parameter can currently neither be read nor written.

ReadOnly = ::fluxEngine_C_v1_ParameterAccessMode_ReadOnly

The parameter is read-only.

WriteOnly = ::fluxEngine_C_v1_ParameterAccessMode_WriteOnly

The parameter is write-only.

This is typically only the case for ParameterInfo::Type::Command type parameters.

ReadWrite = ::fluxEngine_C_v1_ParameterAccessMode_ReadWrite

The parameter may be read from and written to.

This is the case for most parameters.

Public Functions

ParameterInfo()

Default constructor.

Calling accessors to a default-initialized structure will result in an exception being thrown.

ParameterInfo(ParameterInfo const &other)

Copy constructor.

Parameters
  • other: The object to copy

ParameterInfo(ParameterInfo &&other)

Move constructor.

Parameters
  • other: The object to move

ParameterInfo &operator=(ParameterInfo const &other)

Copy assignment operator.

Return
A reference to *this
Parameters
  • other: The object to copy

ParameterInfo &operator=(ParameterInfo &&other)

Move assignment operator.

Return
A reference to *this
Parameters
  • other: The object to move

~ParameterInfo()

Destructor.

std::size_t parameterCount() const

Get the number of parameters.

Return
The number of parameters

std::vector<std::string> parameterNames() const

Get the list of parameter names.

Return
The list of parameter names

Parameter parameter(std::size_t n) const

Get all information about a specific parameter by index.

If a parameter with that index does not exist, an error will be thrown.

This requires C++17 support for std::optional and std::variant.

See
ParameterInfo::Parameter
Return
The full information about a specific parameter.
Parameters
  • n: The index of the parameter, must be at most one smaller than the result of parameterCount().

Parameter parameter(std::string const &name) const

Get all information about a specific parameter by name.

If a parameter with that name does not exist, and error will be thrown.

This requires C++17 support for std::optional and std::variant.

See
ParameterInfo::Parameter
Return
The full information about a specific parameter.
Parameters
  • name: The name of the parameter

std::vector<Parameter> parameters() const

Get a list of all parameters.

This requires C++17 support for std::optional and std::variant.

Return
A list of all parameters

Type parameterType(std::size_t i) const

Get the type of the parameter by index.

Return
The type of the parameter
Parameters
  • i: The index of the parameter, must be at most one less than the value returned by parameterCount().

Type parameterType(std::string const &name) const

Get the type of the parameter by name.

Return
The type of the parameter
Parameters
  • name: The name of the parameter

AccessMode parameterAccessMode(std::size_t i) const

Get the access mode of the parameter by index.

Return
The access mode of the parameter
Parameters
  • i: The index of the parameter, must be at most one less than the value returned by parameterCount().

AccessMode parameterAccessMode(std::string const &name) const

Get the access mode of the parameter by name.

Return
The access mode of the parameter
Parameters
  • name: The name of the parameter

bool getParameterDisplayName(std::size_t i, std::string &result) const

Get the display name of the parameter by index.

A display name is an optional more human-readable name of a parameter.

Return
true if a display name was set for the parameter (with the result argument being updated to that value), false otherwise.
Parameters
  • i: The index of the parameter, must be at most one less than the value returned by parameterCount().
  • result: Where to store the result. This will only be touched if this method returns true.

bool getParameterDisplayName(std::string const &name, std::string &result) const

Get the display name of the parameter by name.

A display name is an optional more human-readable name of a parameter.

Return
true if a display name was set for the parameter (with the result argument being updated to that value), false otherwise.
Parameters
  • name: The name of the parameter
  • result: Where to store the result. This will only be touched if this method returns true.

std::string parameterEffectiveDisplayName(std::size_t i) const

Get the effective display name of a parameter by index.

This will return the parameter’s display name, if set, or otherwise the parameter’s name. This is a convenient accessor to always obtain a name that may be shown to the user, but that will show a more human-readable name if possible.

Return
The effective display name of a parameter
Parameters
  • i: The index of the parameter, must be at most one less than the value returned by parameterCount().

std::string parameterEffectiveDisplayName(std::string const &name) const

Get the effective display name of a parameter by name.

This will return the parameter’s display name, if set, or otherwise the parameter’s name. This is a convenient accessor to always obtain a name that may be shown to the user, but that will show a more human-readable name if possible.

Return
The effective display name of a parameter
Parameters
  • name: The name of the parameter

bool getParameterShortDescription(std::size_t i, std::string &result) const

Get the short description of the parameter by index.

If set a short description is often displayed in form of a tool-tip to the user.

There is also a C++17 version of this method that returns a std::optional<std::string> for convenience, ParameterInfo::parameterShortDescription().

Return
true if a short description was set for the parameter (with the result argument being updated to that value), false otherwise.
Parameters
  • i: The index of the parameter, must be at most one less than the value returned by parameterCount().
  • result: Where to store the result. This will only be touched if this method returns true.

bool getParameterShortDescription(std::string const &name, std::string &result) const

Get the short description of the parameter by name.

If set a short description is often displayed in form of a tool-tip to the user.

There is also a C++17 version of this method that returns a std::optional<std::string> for convenience, ParameterInfo::parameterShortDescription().

Return
true if a short description was set for the parameter (with the result argument being updated to that value), false otherwise.
Parameters
  • name: The name of the parameter
  • result: Where to store the result. This will only be touched if this method returns true.

bool getParameterLongDescription(std::size_t i, std::string &result) const

Get the long description of the parameter by index.

There is also a C++17 version of this method that returns a std::optional<std::string> for convenience, ParameterInfo::parameterLongDescription().

Return
true if a long description was set for the parameter (with the result argument being updated to that value), false otherwise.
Parameters
  • i: The index of the parameter, must be at most one less than the value returned by parameterCount().
  • result: Where to store the result. This will only be touched if this method returns true.

bool getParameterLongDescription(std::string const &name, std::string &result) const

Get the long description of the parameter by name.

There is also a C++17 version of this method that returns a std::optional<std::string> for convenience, ParameterInfo::parameterLongDescription().

Return
true if a long description was set for the parameter (with the result argument being updated to that value), false otherwise.
Parameters
  • name: The name of the parameter
  • result: Where to store the result. This will only be touched if this method returns true.

bool getParameterUnit(std::size_t i, std::string &result) const

Get the unit of the parameter by index.

Numeric parameters (ParameterInfo::Type::Integer and ParameterInfo::Type::Float) may have a unit assigned to them that describes the physical unit of the parameter, such as “ms” or “Hz.

There is also a C++17 version of this method that returns a std::optional<std::string> for convenience, ParameterInfo::parameterUnit().

Return
true if a long description was set for the parameter (with the result argument being updated to that value), false otherwise.
Parameters
  • i: The index of the parameter, must be at most one less than the value returned by parameterCount().
  • result: Where to store the result. This will only be touched if this method returns true.

bool getParameterUnit(std::string const &name, std::string &result) const

Get the unit of the parameter by name.

Numeric parameters (ParameterInfo::Type::Integer and ParameterInfo::Type::Float) may have a unit assigned to them that describes the physical unit of the parameter, such as “ms” or “Hz.

There is also a C++17 version of this method that returns a std::optional<std::string> for convenience, ParameterInfo::parameterUnit().

Return
true if a long description was set for the parameter (with the result argument being updated to that value), false otherwise.
Parameters
  • name: The name of the parameter
  • result: Where to store the result. This will only be touched if this method returns true.

std::optional<std::string> parameterDisplayName(std::size_t i) const

Get a parameter’s display name by index.

A display name is an optional more human-readable name of a parameter.

This accessor is only available with a C++17 compiler that supports std::optional. For compilers without such aupport, please take a look at the ParameterInfo::getParameterDisplayName() method.

Return
The parameter’s display name, or std::nullopt if that is not set.
Parameters
  • i: The index of the parameter, must be at most one less than the value returned by parameterCount().

std::optional<std::string> parameterDisplayName(std::string const &name) const

Get a parameter’s display name by name.

A display name is an optional more human-readable name of a parameter.

This accessor is only available with a C++17 compiler that supports std::optional. For compilers without such aupport, please take a look at the ParameterInfo::getParameterDisplayName() method.

Return
The parameter’s display name, or std::nullopt if that is not set.
Parameters
  • name: The name of the parameter

std::optional<std::string> parameterShortDescription(std::size_t i) const

Get a parameter’s short description by index.

If set a short description is often displayed in form of a tool-tip to the user.

This accessor is only available with a C++17 compiler that supports std::optional. For compilers without such aupport, please take a look at the ParameterInfo::getParameterShortDescription() method.

Return
The parameter’s short description, or std::nullopt if that is not set.
Parameters
  • i: The index of the parameter, must be at most one less than the value returned by parameterCount().

std::optional<std::string> parameterShortDescription(std::string const &name) const

Get a parameter’s short description by name.

If set a short description is often displayed in form of a tool-tip to the user.

This accessor is only available with a C++17 compiler that supports std::optional. For compilers without such aupport, please take a look at the ParameterInfo::getParameterShortDescription() method.

Return
The parameter’s short description, or std::nullopt if that is not set.
Parameters
  • name: The name of the parameter

std::optional<std::string> parameterLongDescription(std::size_t i) const

Get a parameter’s long description by index.

This accessor is only available with a C++17 compiler that supports std::optional. For compilers without such aupport, please take a look at the ParameterInfo::getParameterLongDescription() method.

Return
The parameter’s long description, or std::nullopt if that is not set.
Parameters
  • i: The index of the parameter, must be at most one less than the value returned by parameterCount().

std::optional<std::string> parameterLongDescription(std::string const &name) const

Get a parameter’s long description by name.

If set a short description is often displayed in form of a tool-tip to the user.

This accessor is only available with a C++17 compiler that supports std::optional. For compilers without such aupport, please take a look at the ParameterInfo::getParameterLongDescription() method.

Return
The parameter’s long description, or std::nullopt if that is not set.
Parameters
  • name: The name of the parameter

std::optional<std::string> parameterUnit(std::size_t i) const

Get a parameter’s unit by index.

Numeric parameters (ParameterInfo::Type::Integer and ParameterInfo::Type::Float) may have a unit assigned to them that describes the physical unit of the parameter, such as “ms” or “Hz.

This accessor is only available with a C++17 compiler that supports std::optional. For compilers without such aupport, please take a look at the ParameterInfo::getParameterUnit() method.

Return
The parameter’s unit, or std::nullopt if that is not set.
Parameters
  • i: The index of the parameter, must be at most one less than the value returned by parameterCount().

std::optional<std::string> parameterUnit(std::string const &name) const

Get a parameter’s unit by name.

Numeric parameters (ParameterInfo::Type::Integer and ParameterInfo::Type::Float) may have a unit assigned to them that describes the physical unit of the parameter, such as “ms” or “Hz.

This accessor is only available with a C++17 compiler that supports std::optional. For compilers without such aupport, please take a look at the ParameterInfo::getParameterUnit() method.

Return
The parameter’s unit, or std::nullopt if that is not set.
Parameters
  • name: The name of the parameter

std::vector<std::string> affectedParameters(std::size_t i) const

Get the parameters affected by changes to a given parameter (by index)

Given the index of a parameter, determine the list of parameters that might change if the value of the chosen parameter changes. For example, when changing the BinningHorizontal parameter of a camera, the value and limits of the OffsetX and Width parameters of that camera may change as a result of the change in binning. The parameters that may be affected by a change in parameter values are listed here.

Return
The names of the parameters that may be affected by changes to the value of the selected parameter.
Parameters
  • i: The index of the parameter, must be at most one less than the value returned by parameterCount().

std::vector<std::string> affectedParameters(std::string const &name) const

Get the parameters affected by a given parameter (by name)

Given the name of a parameter, determine the list of parameters that might change if the value of the chosen parameter changes. For example, when changing the BinningHorizontal parameter of a camera, the value and limits of the OffsetX and Width parameters of that camera may change as a result of the change in binning. The parameters that may be affected by a change in parameter values are listed here.

Return
The names of the parameters that may be affected by changes to the value of the selected parameter.
Parameters
  • name: The name of the parameter

std::string parameterDefaultStringValue(std::size_t i) const

Get the default value of a parameter (string type, by index)

For parameters of ParameterInfo::Type::String or ParameterInfo::Type::File type obtain the default value of the parameter. The default value of a string-like parameter may be an empty string.

For device parameters there is no default value, there is only the currently set value. (As well as potentially the initial value after a connection to the device is established, and it would be up to the user to determine that though it is not guaranteed that the initial value hasn’t been affected by previous connections while the device has been powered on.) In that case this method will throw an error.

For parameters describing how to connect to a specific device there may be a default value, and that will be returned by this method.

If the parameter is not of the correct type an error will be thrown.

Return
The default value of the parameter
Parameters
  • i: The index of the parameter, must be at most one less than the value returned by parameterCount().

std::string parameterDefaultStringValue(std::string const &name) const

Get the default value of a parameter (string type, by name)

For parameters of ParameterInfo::Type::String or ParameterInfo::Type::File type obtain the default value of the parameter. The default value of a string-like parameter may be an empty string.

For device parameters there is no default value, there is only the currently set value. (As well as potentially the initial value after a connection to the device is established, and it would be up to the user to determine that though it is not guaranteed that the initial value hasn’t been affected by previous connections while the device has been powered on.) In that case this method will throw an error.

For parameters describing how to connect to a specific device there may be a default value, and that will be returned by this method.

If the parameter is not of the correct type an error will be thrown.

Return
The default value of the parameter
Parameters
  • name: The name of the parameter

int64_t parameterDefaultIntegerValue(std::size_t i) const

Get the default value of a parameter (integer type, by index)

For parameters of ParameterInfo::Type::Integer or ParameterInfo::Type::Enumeration type obtain the default value of the parameter.

For device parameters there is no default value, there is only the currently set value. (As well as potentially the initial value after a connection to the device is established, and it would be up to the user to determine that though it is not guaranteed that the initial value hasn’t been affected by previous connections while the device has been powered on.) In that case this method will throw an error.

For parameters describing how to connect to a specific device there may be a default value, and that will be returned by this method.

If the parameter is not of the correct type an error will be thrown.

Return
The default value of the parameter
Parameters
  • i: The index of the parameter, must be at most one less than the value returned by parameterCount().

int64_t parameterDefaultIntegerValue(std::string const &name) const

Get the default value of a parameter (integer type, by name)

For parameters of ParameterInfo::Type::Integer or ParameterInfo::Type::Enumeration type obtain the default value of the parameter.

For device parameters there is no default value, there is only the currently set value. (As well as potentially the initial value after a connection to the device is established, and it would be up to the user to determine that though it is not guaranteed that the initial value hasn’t been affected by previous connections while the device has been powered on.) In that case this method will throw an error.

For parameters describing how to connect to a specific device there may be a default value, and that will be returned by this method.

If the parameter is not of the correct type an error will be thrown.

Return
The default value of the parameter
Parameters
  • name: The name of the parameter

double parameterDefaultFloatValue(std::size_t i) const

Get the default value of a parameter (float type, by index)

For parameters of ParameterInfo::Type::Float type obtain the default value of the parameter.

For device parameters there is no default value, there is only the currently set value. (As well as potentially the initial value after a connection to the device is established, and it would be up to the user to determine that though it is not guaranteed that the initial value hasn’t been affected by previous connections while the device has been powered on.) In that case this method will throw an error.

For parameters describing how to connect to a specific device there may be a default value, and that will be returned by this method.

If the parameter is not of the correct type an error will be thrown.

Return
The default value of the parameter
Parameters
  • i: The index of the parameter, must be at most one less than the value returned by parameterCount().

double parameterDefaultFloatValue(std::string const &name) const

Get the default value of a parameter (float type, by name)

For parameters of ParameterInfo::Type::Float type obtain the default value of the parameter.

For device parameters there is no default value, there is only the currently set value. (As well as potentially the initial value after a connection to the device is established, and it would be up to the user to determine that though it is not guaranteed that the initial value hasn’t been affected by previous connections while the device has been powered on.) In that case this method will throw an error.

For parameters describing how to connect to a specific device there may be a default value, and that will be returned by this method.

If the parameter is not of the correct type an error will be thrown.

Return
The default value of the parameter
Parameters
  • name: The name of the parameter

bool parameterDefaultBooleanValue(std::size_t i) const

Get the default value of a parameter (bool type, by index)

For parameters of ParameterInfo::Type::Boolean type obtain the default value of the parameter.

For device parameters there is no default value, there is only the currently set value. (As well as potentially the initial value after a connection to the device is established, and it would be up to the user to determine that though it is not guaranteed that the initial value hasn’t been affected by previous connections while the device has been powered on.) In that case this method will throw an error.

For parameters describing how to connect to a specific device there may be a default value, and that will be returned by this method.

If the parameter is not of the correct type an error will be thrown.

Return
The default value of the parameter
Parameters
  • i: The index of the parameter, must be at most one less than the value returned by parameterCount().

bool parameterDefaultBooleanValue(std::string const &name) const

Get the default value of a parameter (bool type, by name)

For parameters of ParameterInfo::Type::Boolean type obtain the default value of the parameter.

For device parameters there is no default value, there is only the currently set value. (As well as potentially the initial value after a connection to the device is established, and it would be up to the user to determine that though it is not guaranteed that the initial value hasn’t been affected by previous connections while the device has been powered on.) In that case this method will throw an error.

For parameters describing how to connect to a specific device there may be a default value, and that will be returned by this method.

If the parameter is not of the correct type an error will be thrown.

Return
The default value of the parameter
Parameters
  • name: The name of the parameter

std::vector<std::string> enumerationEntryNames(std::size_t i) const

Get the names of all enumeration entries of an enumeration parameter (parameter by index)

For a parameter of type ParameterInfo::Type::Enumeration return a list of the names of all enumeration entries of that parameter.

If the parameter is not of enumeration type, an error will be thrown.

Return
The enumeration entries of the parameter
Parameters
  • i: The index of the parameter, must be at most one less than the value returned by parameterCount().

std::vector<std::string> enumerationEntryNames(std::string const &name) const

Get the names of all enumeration entries of an enumeration parameter (parameter by name)

For a parameter of type ParameterInfo::Type::Enumeration return a list of the names of all enumeration entries of that parameter.

If the parameter is not of enumeration type, an error will be thrown.

Return
The enumeration entries of the parameter
Parameters
  • name: The name of the parameter

int64_t enumerationEntryValue(std::size_t parameterIndex, std::size_t entryIndex) const

Get the value of an enumeration entry of an enumeration parameter (parameter by index, entry by index)

For a parameter of type ParameterInfo::Type::Enumeration return the value of a specific enumeration entry.

If the parameter is not of enumeration type, or the specified entry does not exist, an error will be thrown.

Return
The value of the enumeration entry
Parameters
  • parameterIndex: The index of the parameter, must be at most one less than the value returned by parameterCount().
  • entryIndex: The index of the entry, must be at most one less than the size of the vector returned by enumerationEntryNames().

int64_t enumerationEntryValue(std::size_t parameterIndex, std::string const &entryName) const

Get the value of an enumeration entry of an enumeration parameter (parameter by index, entry by name)

For a parameter of type ParameterInfo::Type::Enumeration return the value of a specific enumeration entry.

If the parameter is not of enumeration type, or the specified entry does not exist, an error will be thrown.

Return
The value of the enumeration entry
Parameters
  • parameterIndex: The index of the parameter, must be at most one less than the value returned by parameterCount().
  • entryName: The name of the enumeration entry

int64_t enumerationEntryValue(std::string const &parameterName, std::size_t entryIndex) const

Get the value of an enumeration entry of an enumeration parameter (parameter by name, entry by index)

For a parameter of type ParameterInfo::Type::Enumeration return the value of a specific enumeration entry.

If the parameter is not of enumeration type, or the specified entry does not exist, an error will be thrown.

Return
The value of the enumeration entry
Parameters
  • parameterName: The name of the parameter
  • entryIndex: The index of the entry, must be at most one less than the size of the vector returned by enumerationEntryNames().

int64_t enumerationEntryValue(std::string const &parameterName, std::string const &entryName) const

Get the value of an enumeration entry of an enumeration parameter (parameter by name, entry by name)

For a parameter of type ParameterInfo::Type::Enumeration return the value of a specific enumeration entry.

If the parameter is not of enumeration type, or the specified entry does not exist, an error will be thrown.

Return
The value of the enumeration entry
Parameters
  • parameterName: The name of the parameter
  • entryName: The name of the enumeration entry

bool getEnumerationEntryDisplayName(std::size_t parameterIndex, std::size_t entryIndex, std::string &result) const

Get the display name of an enumeration entry of an enumeration parameter (parameter by index, entry by index)

For a parameter of type ParameterInfo::Type::Enumeration return the display name of a specific enumeration entry.

If the parameter is not of enumeration type, or the specified entry does not exist, an error will be thrown.

There is also a C++17 version of this method that returns a std::optional<std::string> for convenience, ParameterInfo::enumerationEntryDisplayName().

Return
true if a display name was set for the enumeration entry (with the result argument being updated to that value), false otherwise.
Parameters
  • parameterIndex: The index of the parameter, must be at most one less than the value returned by parameterCount().
  • entryIndex: The index of the entry, must be at most one less than the size of the vector returned by enumerationEntryNames().
  • result: Where to store the result. This will only be touched if this method returns true.

bool getEnumerationEntryDisplayName(std::size_t parameterIndex, std::string const &entryName, std::string &result) const

Get the display name of an enumeration entry of an enumeration parameter (parameter by index, entry by name)

For a parameter of type ParameterInfo::Type::Enumeration return the display name of a specific enumeration entry.

If the parameter is not of enumeration type, or the specified entry does not exist, an error will be thrown.

There is also a C++17 version of this method that returns a std::optional<std::string> for convenience, ParameterInfo::enumerationEntryDisplayName().

Return
true if a display name was set for the enumeration entry (with the result argument being updated to that value), false otherwise.
Parameters
  • parameterIndex: The index of the parameter, must be at most one less than the value returned by parameterCount().
  • entryName: The name of the enumeration entry
  • result: Where to store the result. This will only be touched if this method returns true.

bool getEnumerationEntryDisplayName(std::string const &parameterName, std::size_t entryIndex, std::string &result) const

Get the display name of an enumeration entry of an enumeration parameter (parameter by name, entry by index)

For a parameter of type ParameterInfo::Type::Enumeration return the display name of a specific enumeration entry.

If the parameter is not of enumeration type, or the specified entry does not exist, an error will be thrown.

There is also a C++17 version of this method that returns a std::optional<std::string> for convenience, ParameterInfo::enumerationEntryDisplayName().

Return
true if a display name was set for the enumeration entry (with the result argument being updated to that value), false otherwise.
Parameters
  • parameterName: The name of the parameter
  • entryIndex: The index of the entry, must be at most one less than the size of the vector returned by enumerationEntryNames().
  • result: Where to store the result. This will only be touched if this method returns true.

bool getEnumerationEntryDisplayName(std::string const &parameterName, std::string const &entryName, std::string &result) const

Get the display name of an enumeration entry of an enumeration parameter (parameter by name, entry by name)

For a parameter of type ParameterInfo::Type::Enumeration return the display name of a specific enumeration entry.

If the parameter is not of enumeration type, or the specified entry does not exist, an error will be thrown.

There is also a C++17 version of this method that returns a std::optional<std::string> for convenience, ParameterInfo::enumerationEntryDisplayName().

Return
true if a display name was set for the enumeration entry (with the result argument being updated to that value), false otherwise.
Parameters
  • parameterName: The name of the parameter
  • entryName: The name of the enumeration entry
  • result: Where to store the result. This will only be touched if this method returns true.

std::optional<std::string> enumerationEntryDisplayName(std::size_t parameterIndex, std::size_t entryIndex) const

Get the display name of an enumeration entry of an enumeration parameter (parameter by index, entry by index)

For a parameter of type ParameterInfo::Type::Enumeration return the display name of a specific enumeration entry.

If the parameter is not of enumeration type, or the specified entry does not exist, an error will be thrown.

There is also a version of this method that doesn’t require support for std::optional, ParameterInfo::getEnumerationEntryDisplayName().

Return
The display name of the enumeration entry if set, or otherwise std::nullopt.
Parameters
  • parameterIndex: The index of the parameter, must be at most one less than the value returned by parameterCount().
  • entryIndex: The index of the entry, must be at most one less than the size of the vector returned by enumerationEntryNames().

std::optional<std::string> enumerationEntryDisplayName(std::size_t parameterIndex, std::string const &entryName) const

Get the display name of an enumeration entry of an enumeration parameter (parameter by index, entry by name)

For a parameter of type ParameterInfo::Type::Enumeration return the display name of a specific enumeration entry.

If the parameter is not of enumeration type, or the specified entry does not exist, an error will be thrown.

There is also a version of this method that doesn’t require support for std::optional, ParameterInfo::getEnumerationEntryDisplayName().

Return
The display name of the enumeration entry if set, or otherwise std::nullopt.
Parameters
  • parameterIndex: The index of the parameter, must be at most one less than the value returned by parameterCount().
  • entryName: The name of the enumeration entry

std::optional<std::string> enumerationEntryDisplayName(std::string const &parameterName, std::size_t entryIndex) const

Get the display name of an enumeration entry of an enumeration parameter (parameter by name, entry by index)

For a parameter of type ParameterInfo::Type::Enumeration return the display name of a specific enumeration entry.

If the parameter is not of enumeration type, or the specified entry does not exist, an error will be thrown.

There is also a version of this method that doesn’t require support for std::optional, ParameterInfo::getEnumerationEntryDisplayName().

Return
The display name of the enumeration entry if set, or otherwise std::nullopt.
Parameters
  • parameterName: The name of the parameter
  • entryIndex: The index of the entry, must be at most one less than the size of the vector returned by enumerationEntryNames().

std::optional<std::string> enumerationEntryDisplayName(std::string const &parameterName, std::string const &entryName) const

Get the display name of an enumeration entry of an enumeration parameter (parameter by name, entry by name)

For a parameter of type ParameterInfo::Type::Enumeration return the display name of a specific enumeration entry.

If the parameter is not of enumeration type, or the specified entry does not exist, an error will be thrown.

There is also a version of this method that doesn’t require support for std::optional, ParameterInfo::getEnumerationEntryDisplayName().

Return
The display name of the enumeration entry if set, or otherwise std::nullopt.
Parameters
  • parameterName: The name of the parameter
  • entryName: The name of the enumeration entry

std::string enumerationEntryEffectiveDisplayName(std::size_t parameterIndex, std::size_t entryIndex) const

Get the effective display name of an enumeration entry of an enumeration parameter (parameter by index, entry by index)

For a parameter of type ParameterInfo::Type::Enumeration return the effective display name of a specific enumeration entry.

If the parameter is not of enumeration type, or the specified entry does not exist, an error will be thrown.

There is also a version of this method that doesn’t require support for std::optional, ParameterInfo::getEnumerationEntryDisplayName().

Return
The display name of the enumeration entry if set, or otherwise the name of the entry.
Parameters
  • parameterIndex: The index of the parameter, must be at most one less than the value returned by parameterCount().
  • entryIndex: The index of the entry, must be at most one less than the size of the vector returned by enumerationEntryNames().

std::string enumerationEntryEffectiveDisplayName(std::size_t parameterIndex, std::string const &entryName) const

Get the effective display name of an enumeration entry of an enumeration parameter (parameter by index, entry by name)

For a parameter of type ParameterInfo::Type::Enumeration return the effective display name of a specific enumeration entry.

If the parameter is not of enumeration type, or the specified entry does not exist, an error will be thrown.

There is also a version of this method that doesn’t require support for std::optional, ParameterInfo::getEnumerationEntryDisplayName().

Return
The display name of the enumeration entry if set, or otherwise the name of the entry.
Parameters
  • parameterIndex: The index of the parameter, must be at most one less than the value returned by parameterCount().
  • entryName: The name of the enumeration entry

std::string enumerationEntryEffectiveDisplayName(std::string const &parameterName, std::size_t entryIndex) const

Get the effective display name of an enumeration entry of an enumeration parameter (parameter by name, entry by index)

For a parameter of type ParameterInfo::Type::Enumeration return the effective display name of a specific enumeration entry.

If the parameter is not of enumeration type, or the specified entry does not exist, an error will be thrown.

There is also a version of this method that doesn’t require support for std::optional, ParameterInfo::getEnumerationEntryDisplayName().

Return
The display name of the enumeration entry if set, or otherwise the name of the entry.
Parameters
  • parameterName: The name of the parameter
  • entryIndex: The index of the entry, must be at most one less than the size of the vector returned by enumerationEntryNames().

std::string enumerationEntryEffectiveDisplayName(std::string const &parameterName, std::string const &entryName) const

Get the effective display name of an enumeration entry of an enumeration parameter (parameter by name, entry by name)

For a parameter of type ParameterInfo::Type::Enumeration return the effective display name of a specific enumeration entry.

If the parameter is not of enumeration type, or the specified entry does not exist, an error will be thrown.

There is also a version of this method that doesn’t require support for std::optional, ParameterInfo::getEnumerationEntryDisplayName().

Return
The display name of the enumeration entry if set, or otherwise the name of the entry.
Parameters
  • parameterName: The name of the parameter
  • entryName: The name of the enumeration entry

int64_t parameterIntegerIncrement(std::size_t parameterIndex) const

Get the integer increment of a parameter (by index)

For ParameterInfo::Type::Integer type parameters this will return the increment value required to obtain a valid value of this parameter. Specifically, a valid value for the given integer must take the form value = minimum + N * increment, where N is an arbitrary positive integer.

If the parameter is not of integer type, an error will be thrown.

Return
The increment of the integer parameter
Parameters
  • parameterIndex: The index of the parameter, must be at most one less than the value returned by parameterCount().

int64_t parameterIntegerIncrement(std::string const &parameterName) const

Get the integer increment of a parameter (by name)

For ParameterInfo::Type::Integer type parameters this will return the increment value required to obtain a valid value of this parameter. Specifically, a valid value for the given integer must take the form value = minimum + N * increment, where N is an arbitrary positive integer.

If the parameter is not of integer type, an error will be thrown.

Return
The increment of the integer parameter
Parameters
  • parameterName: The name of the parameter

int64_t parameterIntegerMinimum(std::size_t parameterIndex) const

Get the integer minimum value of a parameter (by index)

If the parameter is not of integer type, an error will be thrown.

Return
The minimum of the integer parameter
Parameters
  • parameterIndex: The index of the parameter, must be at most one less than the value returned by parameterCount().

int64_t parameterIntegerMinimum(std::string const &parameterName) const

Get the integer minimum value of a parameter (by name)

If the parameter is not of integer type, an error will be thrown.

Return
The minimum of the integer parameter
Parameters
  • parameterName: The name of the parameter

int64_t parameterIntegerMaximum(std::size_t parameterIndex) const

Get the integer maximum value of a parameter (by index)

If the parameter is not of integer type, an error will be thrown.

Return
The maximum of the integer parameter
Parameters
  • parameterIndex: The index of the parameter, must be at most one less than the value returned by parameterCount().

int64_t parameterIntegerMaximum(std::string const &parameterName) const

Get the integer maximum value of a parameter (by name)

If the parameter is not of integer type, an error will be thrown.

Return
The maximum of the integer parameter
Parameters
  • parameterName: The name of the parameter

double parameterFloatIncrement(std::size_t parameterIndex) const

Get the floating point increment of a parameter (by index)

For ParameterInfo::Type::Float type parameters this will return an indication of the increment to use while the user is editing this parameter. If an increment is actually enforced for floating point values, it means that the supplied value will be rounded to the nearest allowed value upon write.

If the parameter is not of floating point, an error will be thrown.

Return
The increment of the floating point parameter
Parameters
  • parameterIndex: The index of the parameter, must be at most one less than the value returned by parameterCount().

double parameterFloatIncrement(std::string const &parameterName) const

Get the floating point increment of a parameter (by name)

For ParameterInfo::Type::Float type parameters this will return an indication of the increment to use while the user is editing this parameter. If an increment is actually enforced for floating point values, it means that the supplied value will be rounded to the nearest allowed value upon write.

If the parameter is not of floating point, an error will be thrown.

Return
The increment of the floating point parameter
Parameters
  • parameterName: The name of the parameter

double parameterFloatMinimum(std::size_t parameterIndex) const

Get the floating point minimum of a parameter (by index)

If the parameter is not of floating point, an error will be thrown.

Return
The minimum of the floating point parameter
Parameters
  • parameterIndex: The index of the parameter, must be at most one less than the value returned by parameterCount().

double parameterFloatMinimum(std::string const &parameterName) const

Get the floating point minimum of a parameter (by name)

If the parameter is not of floating point, an error will be thrown.

Return
The minimum of the floating point parameter
Parameters
  • parameterName: The name of the parameter

double parameterFloatMaximum(std::size_t parameterIndex) const

Get the floating point maximum of a parameter (by index)

If the parameter is not of floating point, an error will be thrown.

Return
The maximum of the floating point parameter
Parameters
  • parameterIndex: The index of the parameter, must be at most one less than the value returned by parameterCount().

double parameterFloatMaximum(std::string const &parameterName) const

Get the floating point maximum of a parameter (by name)

If the parameter is not of floating point, an error will be thrown.

Return
The maximum of the floating point parameter
Parameters
  • parameterName: The name of the parameter

ParameterInfo(fluxEngine_C_v1_ParameterInfo *wrapped)

Wrapping constructor.

This constructor wraps the underlying C handle and takes ownership of it. This means that once this object is destroyed the C handle will be freed.

Users will typically not need to call this constructor, as the C++ wrappers for other objects will return this structure directly.

Parameters
  • wrapped: The C handle to wrap

struct EnumerationEntry

Enumeration entry.

This structure describes an enumeration entry. It is only available on systems with C++17 support (requiring std::optional). It is part of the ParameterInfo::Parameter structure for ParameterInfo::Type::Enumeration type parameters.

Public Functions

std::string effectiveDisplayName() const

Get the effective display name of the enumeration entry.

If the display name is not set, the entry’s name will be returned instead.

Return
The effective display name of the enumeration entry

Public Members

std::string name

The name of the enumeration entry.

This will be unique within the enumeration parameter.

int64_t value

The value of the enumeration entry.

This should be unique within the enumeration parameter, but aliases for the same value may exist. (The first entry in the list is the canonical name.)

std::optional<std::string> displayName

The display name of the enumeration entry.

If this is available this contains a more user-friendly string that describes this entry. If this is not available for the given enumeration entry this will be std::nullopt.

struct Parameter

Complete parameter information.

This structure contains all of the information of a given parameter collected into a single structure. It is returned by both ParameterInfo::parameter() and ParameterInfo::parameters().

As std::variant as well as std::optional are present in this structure C++17 support is required for it to be available.

Public Functions

std::string effectiveDisplayName() const

Get the effective display name of the parameter.

If the display name is not set, the parameter’s name will be returned instead.

Return
The effective display name of the parameter

std::optional<int64_t> integerIncrement() const

Get the integer increment of the parameter.

Returns the integer increment of the parameter, or std::nullopt if this is not an integer parameter. This accessor exists for convenience reasons to make accessing this information in case of a known integer parameter easier.

Return
The integer increment of the parameter

std::optional<int64_t> integerMinimum() const

Get the integer minimum of the parameter.

Returns the integer minimum of the parameter, or std::nullopt if this is not an integer parameter. This accessor exists for convenience reasons to make accessing this information in case of a known integer parameter easier.

Return
The integer minimum of the parameter

std::optional<int64_t> integerMaximum() const

Get the integer maximum of the parameter.

Returns the integer maximum of the parameter, or std::nullopt if this is not an integer parameter. This accessor exists for convenience reasons to make accessing this information in case of a known integer parameter easier.

Return
The integer maximum of the parameter

std::optional<double> floatIncrement() const

Get the floating point increment of the parameter.

Returns the floating point increment of the parameter, or std::nullopt if this is not an integer parameter. This accessor exists for convenience reasons to make accessing this information in case of a known integer parameter easier.

Return
The floating point increment of the parameter

std::optional<double> floatMinimum() const

Get the floating point minimum of the parameter.

Returns the floating point minimum of the parameter, or std::nullopt if this is not an integer parameter. This accessor exists for convenience reasons to make accessing this information in case of a known integer parameter easier.

Return
The floating point minimum of the parameter

std::optional<double> floatMaximum() const

Get the floating point maximum of the parameter.

Returns the floating point maximum of the parameter, or std::nullopt if this is not an integer parameter. This accessor exists for convenience reasons to make accessing this information in case of a known integer parameter easier.

Return
The floating point maximum of the parameter

Public Members

std::string name

The name of the parameter.

This will be unique within the parameter information structure.

Type type = {}

The type of the parameter.

AccessMode accessMode = {}

The access mode of the parameter.

The access mode determines if a parameter can be read from or written to or, in case of commands, if it can be executed.

std::optional<std::string> displayName

The display name of the parameter.

If set this is a more human-readable name of the parameter.

std::optional<std::string> shortDescription

A short description of the parameter.

If set this is typically shown in form of a tool-tip when hovering over a parameter.

std::optional<std::string> longDescription

A long description of the parameter.

std::vector<std::string> affectedParameters

A list of affected parameters.

If the value of this parameter is changed by the user, this list of parameter names indicates which parameters may also change due to that write. Affected parameters may have a different value, access mode, minmum, maximum or increment when a parameter changes.

The names in this list denote the unique name of each affected parameter, not the display name.

It is not necessary that a change to this parameter actually changes one of the affected parameters, it only indicates that such a change is possible.

std::variant<std::monostate, std::string, int64_t, double, bool> defaultValue

The default value of a parameter.

For device parameters there is no default value, there is only the currently set value. (As well as potentially the initial value after a connection to the device is established, and it would be up to the user to determine that though it is not guaranteed that the initial value hasn’t been affected by previous connections while the device has been powered on.)

For parameters describing how to connect to a specific device there may be a default value, and this field will contain that value.

If the field is of std::monostate type there is no default value present.

If the field is of any other type it will contain the default value depending on the type of the parameter. String and file parameters will have default values in the form of a std::string, integer and enumeration parameters will have default values in form of an int64_t, floating point parmaeters will have default values in form of a double, and boolean parameters will have default values in form of a bool.

std::optional<std::string> unit

The unit of the value.

Numeric (integer and floating point) parameters may have a unit associated with them, such as “ms” or “Hz”. If present this will contain that unit.

Note that the unit is encoded as UTF-8, and the unit prefix for “microseconds” is represented with a greek mu, which is not part of the ASCII subset of UTF-8.

This will always be std::nullopt for parameters that do not have a unit (because it is either not set or they are of a type that doesn’t have units).

std::vector<EnumerationEntry> enumerationEntries

The list of available enumeration entries.

For ParameterInfo::Type::Enumeration type parameters this will contain the list of all entries in the given enumeration.

std::variant<std::monostate, int64_t, double> minimum

The minimum value.

For numeric (integer and floating point) parameters this will contain the lowest value that the parameter accepts.

In all other cases this will be std::nullopt.

std::variant<std::monostate, int64_t, double> maximum

The maximum value.

For numeric (integer and floating point) parameters this will contain the largest value that the parameter accepts.

In all other cases this will be std::nullopt.

std::variant<std::monostate, int64_t, double> increment

The increment value.

For ParameterInfo::Type::Integer type parameters this will contain the increment value required to obtain a valid value of this parameter. Specifically, a valid value for the given integer must take the form value = minimum + N * increment, where N is an arbitrary positive integer.

For ParameterInfo::Type::Float type parameters this will give an indication of the increment to use while the user is editing this parameter. If an increment is actually enforced for floating point values, it means that the supplied value will be rounded to the nearest allowed value upon write.

In all other cases this will be std::nullopt.

Device Enumeration

enum fluxEngine::DriverType

Driver type.

Values:

Instrument = ::fluxEngine_C_v1_DriverType_Instrument

Instrument driver.

This driver accesses instrument devices, such as cameras, spectrometers, and other sensors.

LightControl = ::fluxEngine_C_v1_DriverType_LightControl

Light control device.

This driver accesses light control devices that can be used to switch a light on and off, and possibly set the light intensity.

enum fluxEngine::DriverState

Driver state.

Describes the state of the driver at the end of the enumeration process. This can be used to detect issues with the driver.

Values:

Unknown = ::fluxEngine_C_v1_DriverState_Unknown

The state is unknown.

This likely indicates an internal error during enumeration.

OK = ::fluxEngine_C_v1_DriverState_OK

OK.

The driver could successfully perform the enumeration. This is a valid state even if the driver didn’t find any device.

LoadTimeout = ::fluxEngine_C_v1_DriverState_LoadTimeout

Driver load timeout.

The driver didn’t respond at all within the specified enumeration timeout, indicating that it didn’t load in time. If a sufficiently long timeout has been provided (e.g. more than 3 seconds) this is typically an indication that there is an issue with the driver.

LoadError = ::fluxEngine_C_v1_DriverState_LoadError

Driver load error.

The driver could not be loaded, for example because the driver file is not valid, or the isolation executable could not be found (in which case all drivers will suffer from this error).

EnumerationError = ::fluxEngine_C_v1_DriverState_EnumerationError

Enumeration error.

The driver generated an error message during the enumeration process. That error can be queried from the enumeration result.

Crashed = ::fluxEngine_C_v1_DriverState_Crashed

Driver crashed.

The driver crashed during enumeration. This typically indicates that there is an issue with a missing dependency of the driver.

EnumerationResult fluxEngine::enumerateDevices(Handle &h, int driverType, std::chrono::milliseconds timeout)

Enumerate devices.

This method enumerates all devices that are connected to the system for which drivers have been installed. Please note that Handle::setDriverIsolationExecutable() and Handle::setDriverBaseDirectory() should be called before this method if the driver directory or the directory of the isolation executable are in non-standard paths.

The result of this function contains interconnected pointers, and all pointers within the result will become invalid once the result has been destroyed.

Return
The enumerated devices
Parameters
  • h: The fluxEngine handle
  • driverType: The type of driver to enumerate. Specify -1 to indicate all driver types should be enumerated, or the driver type static-cast to integer for a specific driver type.
  • timeout: How long to enumerate. This method will always wait this long for the enumeration process to complete and will then return all devices that were found within that given timespan. It is recommended to set this to at least 3.5 seconds.

struct EnumerationResult

The result of an enumeration process.

This structure contains the result of an enumeration process. The individual members are interconnected via pointers, so once the result object is destroyed, all pointers to internal members also become invalid.

Public Members

std::vector<std::unique_ptr<EnumeratedDevice>> devices

The devices that were found.

std::vector<std::unique_ptr<EnumeratedDriver>> drivers

The drivers that were used during enumeration.

std::vector<EnumerationWarning> warnings

Warnings that occurred during enumeration.

std::vector<EnumerationError> errors

Errors that occurred during enumeration.

struct EnumeratedDevice

Enumerated device.

Describes a device that was found during enumeration.

Note that some drivers can’t actually enumerate the available devices in the system, and rely on probing to actually connect to a device. In that case a device entry will appear regardless of whether the device is actually present, and connection failure is the only way of ascertaining that the device is not actually present.

This structure is allocated as part of the EnumerationResult structure, and will automatically be freed when that structure is freed by the user. The individual sub-structures are inter-linked by pointers that reference each other for this reason their lifetime is coupled to the entire EnumerationResult structure.

Public Members

std::vector<std::uint8_t> id

A driver-specific id of the device.

This id must be provided in combination with the type and name of the driver for a connection attempt.

The id is guaranteed to be stable for a short period of time after enumeration so that it may be used for connection purposes.

It is not guaranteed to be stable across reboots, software updates, etc. The user should never rely on the specific content of this id, even if it appars to be stable at the moment.

EnumeratedDriver *driver = {}

The driver that enumerated the device.

std::string displayName

The display name of the device.

This is a human-readable text that is of the format Vendor Model (Serial Number), but in such a manner that if one or more of these strings is empty a sensible text will still be generated for example, if a device has no serial number, the format will be Vendor Model instead.

std::string manufacturer

The manufacturer of the device.

std::string model

The model of the device.

std::string serialNumber

The serial number of the device.

This may be empty, which can mean two things: either the device has no serial number, or the serial number could not be obtained during device enumeration and requires the user to connect to the device to actually read it.

ParameterInfo parameterInfo

The parameter info for the connection parameters.

Contains information about all connection parameters of the device. For some devices it is necessary to set the some parameters (such as the path to a calibration file) when connecting to the device. This contains the available parameters.

struct EnumeratedDriver

Enumerated driver.

Describes a driver that was used during enumeration. Failed drivers will also have such a structure, even though they will not have any associated devices.

This structure is allocated as part of the EnumerationResult structure, and will automatically be freed when that structure is freed by the user. The individual sub-structures are inter-linked by pointers that reference each other for this reason their lifetime is coupled to the entire EnumerationResult structure.

Public Members

std::string name

The name of the driver.

This is the filename component of the driver and may be used to identify the driver for connection purposes.

DriverType type = {}

The type of the driver.

This is required for identifying the driver for connection purposes.

std::string description

A human-readable name of the driver.

std::string version

A human-readable version of the driver.

DriverState state = {}

The state of the driver.

std::vector<EnumeratedDevice *> devices

The devices the driver has found.

This list may be empty if a specific driver has found no devices.

struct EnumerationWarning

Enumeration Warning.

Describes a warning that was encountered during enumeration. This could be a USB device that could not be accessed because the correct kernel driver is not installed, or a network device that was found but was on the wrong subnet for a given network interface.

This structure is allocated as part of the EnumerationResult structure, and will automatically be freed when that structure is freed by the user. The individual sub-structures are inter-linked by pointers that reference each other for this reason their lifetime is coupled to the entire EnumerationResult structure.

Public Members

EnumeratedDriver *driver = {}

The driver for which the warning occurred.

std::string message

The warning message.

struct EnumerationError

Enumeration Error.

Describes an error that occurred during enumeration, for example a driver that crashed.

This structure is allocated as part of the EnumerationResult structure, and will automatically be freed when that structure is freed by the user. The individual sub-structures are inter-linked by pointers that reference each other for this reason their lifetime is coupled to the entire EnumerationResult structure.

Public Members

EnumeratedDriver *driver = {}

the driver for which the error occurred

This may be nullptr if an error occurred that was not specific to an individual driver.

std::string message

The error message.

Devices

enum fluxEngine::DeviceType

The type of the device.

Values:

Instrument = ::fluxEngine_C_v1_DeviceType_Instrument

Instrument device.

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

LightControl = ::fluxEngine_C_v1_DeviceType_LightControl

Light control device.

enum fluxEngine::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.

See
expandedDataType()

Values:

Unsupported = fluxEngine_C_v1_BufferScalarType_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 = fluxEngine_C_v1_BufferScalarType_UInt8

8bit unsigned integer

UInt16 = fluxEngine_C_v1_BufferScalarType_UInt16

16bit unsigned integer

UInt32 = fluxEngine_C_v1_BufferScalarType_UInt32

32bit unsigned integer

UInt64 = fluxEngine_C_v1_BufferScalarType_UInt64

64bit unsigned integer

Int8 = fluxEngine_C_v1_BufferScalarType_Int8

8bit signed integer

Int16 = fluxEngine_C_v1_BufferScalarType_Int16

16bit signed integer

Int32 = fluxEngine_C_v1_BufferScalarType_Int32

32bit signed integer

Int64 = fluxEngine_C_v1_BufferScalarType_Int64

64bit signed integer

Float32 = fluxEngine_C_v1_BufferScalarType_Float32

32bit IEEE 754 single-precision floating point number

Float64 = fluxEngine_C_v1_BufferScalarType_Float64

64bit IEEE 754 double-precision floating point number

struct ConnectionSettings

Connection settings.

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

The contents of this structure may be freed after the connect function has completed.

Public Members

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

std::vector<std::uint8_t> 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.

std::unordered_map<std::string, std::string> connectionParameters

The connection parameters to use.

The key of this map 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, 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 in the following manner:
    • On Windows it must be encoded as UTF-8 (not the local 8bit encoding), so that it can be converted back to a wide (Unicode) file name internally before being accessed.
    • On all other platforms the local 8bit encoding of the file name must be used.

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.

std::chrono::milliseconds 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.

DeviceGroup fluxEngine::connectDeviceGroup(Handle &h, ConnectionSettings const &settings)

Connect to a device (group)

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.

Return
The device group after a successful connection
Parameters
  • h: The fluxEngine handle
  • settings: The settings that select the device and the connection parameters.

class DeviceGroup

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.

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

Values:

None = fluxEngine_C_v1_DeviceNotificationType_None

No notification.

This type is returned by DeviceGroup::nextNotification() if there currently is no notification pending for the device.

IrrecoverableError = fluxEngine_C_v1_DeviceNotificationType_IrrecoverableError

Irrecoverable error.

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

See
LightControlDevice::Status::IrrecoverableError
See
InstrumentDevice::Status::IrrecoverableError

RecoverableError = fluxEngine_C_v1_DeviceNotificationType_RecoverableError

Recoverable error.

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

See
LightControlDevice::Status::RecoverableError
See
InstrumentDevice::Status::RecoverableError

Warning = fluxEngine_C_v1_DeviceNotificationType_Warning

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.

Public Functions

DeviceGroup()

Default constructor.

This will create an invalid object that exists mainly to later have a valid object moved into.

DeviceGroup(DeviceGroup &&other)

Move constructor.

Parameters
  • other: The device group to move

DeviceGroup &operator=(DeviceGroup &&other)

Move assignment operator.

Return
A reference to *this
Parameters
  • other: The device group to move

~DeviceGroup()

Destructor.

Note that this will forcibly unload the driver instead of performing an orderly disconnect. The user should call DeviceGroup::disconnect() to perform a proper disconnect from the device.

void disconnect(std::chrono::milliseconds timeout)

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 notification event handle of the device group

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

Device *primaryDevice()

Get the primary device of the device group.

Return
The primary device of the device group. The handle of this device will be valid as long as the device group is not disconnected. Multiple calls to this method will result in the same device pointer.

std::string driverName() const

Get the name of the driver.

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

Return
The name of the driver.

DriverType driverType() const

Get the type of the driver.

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

Return
The type of the driver.

std::string driverDescription() const

Get the driver description.

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

Return
The driver description

std::string driverVersion() const

Get the driver version.

Returns a human-readable version string of the driver.

Return
The driver version

EventHandle notificationEventHandle() const

Get a notification event handle.

This will return an operating system event handle that may be used to integrate device notifications into the user’s native event loop. This is optional, the user may also decide to periodically query whether a notification occurred via DeviceGroup::nextNotification().

Windows systems: this will return a HANDLE of a manually resetting event object (create via CreateEvent()) that may be used in an event loop, e.g. via WaitForMultipleObjects. Important: the event handle must not be closed by the user and must not be reset by the user. Whenever this event handle is set the user should call DeviceGroup::nextNotification() to determine the device notification. When the last notification has been retrieved the event handle is reset automatically.

Other systems: this will return a file descriptor (int) that can be polled (via select(2), poll(2) or epoll/kqueue or similar) for read events. (The file descriptor is opened with O_CLOEXEC flags on operating systems that support it.) Important: the user must not close the file descriptor and must not read from it themselves. Whenever the file descriptor is ready to be read the user should call DeviceGroup::nextNotification() to determine the device notification. When the last notification has been retrieved the file descriptor will not be ready to be read from anymore. (Internally this is implemented via an eventfd() on Linux systems and an anonymous pipe on other operating systems.)

Return
The event handle. Important: when the device group is disconnected the event handle is no longer valid (and automatically closed), so the user should always remove the event handle from their event loop before disconnecting a device group handle.

Notification nextNotification() const

Retrieve the last notification.

Retrieves the last notification in the internal notification buffer of the device group. If the type retrieved is DeviceGroup::NotificationType::None then no notification is currently present in the notification buffer, and the DeviceGroup::Notification::device and DeviceGroup::Notification::message parameters will not be set.

The event handle that can be obtained via DeviceGroup::notificationEventHandle() is automatically reset by this function once the last event in the internal event buffer has been retrieved.

Return
The next notification in the internal notification buffer

struct Notification

Device notification.

Public Members

Device *device = {}

The device the notification has occurred for.

This will be the same pointer that can also be obtained by either DeviceGroup::primaryDevice() or Device::subDevices().

NotificationType type = {}

The type of the notification.

If this is DeviceGroup::NotificationType::None this indicates that no notification was queued for the device group.

std::string message

The notification message.

class 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() method 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 undefined behavior.

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

Subclassed by fluxEngine::InstrumentDevice, fluxEngine::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 = fluxEngine_C_v1_ParameterListType_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 = fluxEngine_C_v1_ParameterListType_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 = fluxEngine_C_v1_ParameterListType_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

~Device()

Destructor.

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.

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.

DeviceType type() const

Get the device type.

Return
The device type

std::string manufacturer() const

Get the device’s manufacturer.

Return
The device’s manufacturer

std::string model() const

Get the device model.

Return
The device model

std::string description() const

Get the device’s description.

Some devices may have an additional description that they may return.

This may be empty.

Return
The device’s description.

std::string serialNumber() const

Get the device’s serial number.

Some devices may have no serial number (in which case this will be empty), 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.

Return
The device’s serial number

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

Return
The parameter list
Parameters
  • type: The type of parameter list to get

ParameterInfo::Type parameterType(std::string const &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.

Return
The parameter’s type
Parameters
  • name: The name of the parameter

std::string getParameterString(std::string const &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.

Return
The parameter’s value, as a string
Parameters
  • name: The name of the parameter

int64_t getParameterInteger(std::string const &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.

Return
The parameter’s value, as an integer
Parameters
  • name: The name of the parameter

double getParameterFloat(std::string const &name)

Get a parameter (as an floating point value)

This will only work for floating point parameters.

Return
The parameter’s value, as an floating point value
Parameters
  • name: The name of the parameter

bool getParameterBoolean(std::string const &name)

Get a parameter (as an boolean value)

This will only work for boolean parameters.

Return
The parameter’s value, as an boolean
Parameters
  • name: The name of the parameter

bool isParameterCommandComplete(std::string const &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.

Return
Whether the command has completed
Parameters
  • name: The name of the parameter

void setParameterString(std::string const &name, std::string const &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.

Parameters
  • name: The name of the parameter
  • value: The new value of the parameter

void setParameterInteger(std::string const &name, int64_t 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.

Parameters
  • name: The name of the parameter
  • value: The new value of the parameter

void setParameterFloat(std::string const &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.

Parameters
  • name: The name of the parameter
  • value: The new value of the parameter

void setParameterBoolean(std::string const &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.

Parameters
  • name: The name of the parameter
  • value: The new value of the parameter

void executeParameterCommand(std::string const &name)

Execute a command parameter.

Parameters
  • name: The name of the parameter

class LightControlDevice : public fluxEngine::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 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 = fluxEngine_C_v1_LightControlDeviceStatus_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 = fluxEngine_C_v1_LightControlDeviceStatus_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 = fluxEngine_C_v1_LightControlDeviceStatus_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 = fluxEngine_C_v1_LightControlDeviceStatus_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 = fluxEngine_C_v1_LightControlDeviceStatus_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 = fluxEngine_C_v1_LightControlDeviceStatus_ForcedOff

The light has been forced off.

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

ForcedRamp = fluxEngine_C_v1_LightControlDeviceStatus_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 = fluxEngine_C_v1_LightControlDeviceForceState_None

The device should be parametrized.

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

Off = fluxEngine_C_v1_LightControlDeviceForceState_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 = fluxEngine_C_v1_LightControlDeviceForceState_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.

Public Functions

Status status() const

Get the status of a light control device.

Return
The status of the light control device

void setForceState(ForceState state, std::chrono::milliseconds rampDuration)

Set the force state of the light control device.

Parameters
  • state: The new force state
  • 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.

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.

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.

class InstrumentDevice : public fluxEngine::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 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:

Public Types

enum Status

Instrument device status.

Values:

Invalid = fluxEngine_C_v1_InstrumentDeviceStatus_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 = fluxEngine_C_v1_InstrumentDeviceStatus_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 = fluxEngine_C_v1_InstrumentDeviceStatus_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 = fluxEngine_C_v1_InstrumentDeviceStatus_Idle

The instrument is idle.

The instrument is idle and not returning data.

Busy = fluxEngine_C_v1_InstrumentDeviceStatus_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 = fluxEngine_C_v1_InstrumentDeviceStatus_Streaming

The instrument is streaming data.

The instrument is streaming data to the user.

ForcedStop = fluxEngine_C_v1_InstrumentDeviceStatus_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

Status status() const

Get the status of an instrument device.

Return
The status of the instrument device

std::size_t maxBufferSize() const

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.

Return
The maximum buffer size the instrument may return

std::size_t recommendedBufferCount() const

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.

Return
The number of recommended buffers

std::vector<int64_t> rawBufferDimensions() const

Get the current dimensions of the buffer returned by an instrument.

The tensor order will correspond to the number of elements in the resulting vector. An empty vector is a valid result: there can be insetruments that just retun a single scalar value.

Return
The current dimensions of the buffer

void getRawBufferDimensions(std::array<int64_t, 5> &dimensions, int &order) const

Get the current dimensions of the buffer returned by an instrument (non-allocating override)

This exists as a means to obtain the same information as InstrumentDevice::rawBufferDimensions() without having to allocate a std::vector.

Parameters
  • dimensions: Where to store the dimensions
  • order: Where to store the tensor order

BufferScalarType rawBufferScalarType() const

Get the current scalar type of the buffer returned by an instrument.

Return
The scalar type of the buffer

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

Return
The newly allocated persistent buffer

void setupInternalBuffers(std::size_t 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: The number of buffers to allocate

void startAcquisition(AcquisitionParameter const &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.

Parameters
  • parameters: 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.

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.

BufferInfo retrieveBuffer(std::chrono::milliseconds timeout)

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.

Return
The buffer that was retrieved. The user must check if the BufferInfo::ok member is true before using the buffer. If that member is false this indicates that no buffer was returned within the specified timeout.
Parameters
  • 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.

template <typename Callable>
BufferInfo retrieveBuffer(std::chrono::milliseconds timeout, Callable &&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.

Return
The buffer that was retrieved. The user must check if the BufferInfo::ok member is true before using the buffer. If that member is false this indicates that no buffer was returned within the specified timeout, or the abort check function returned true.
Parameters
  • 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.
  • abortCheckFunction: The function that checks whether an external abort has been initiated. If the function returns true an external abort has been requested.

void returnBuffer(void *bufferId)

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
  • bufferId: The id of the buffer to return. This must correspond to the BufferInfo::id field.

struct AcquisitionParameter

Acquisition parameters.

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

Public Members

std::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" 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.

std::size_t 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.

struct BufferInfo

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

Note that InstrumentDevice::retrieveBuffer always returns this structure, even if no buffer could be retrieved, and the user should first check the BufferInfo::ok field to verify that a buffer was actually retrieved. (If the BufferInfo::ok field is false then no buffer was retrieved and all other fields are invalid.)

Public Functions

void copyRawData(void *memory, DataType dataType, std::array<int64_t, 5> 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.

Parameters
  • memory: Where to store the data of the buffer. The user must have preallocated it to have the correct size for the given data type (given the dimensions of this buffer)
  • 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
  • strides: The stride structure of the user-supplied memory area

PersistentBufferInfo copy() const

Copy the contents of the buffer into a 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 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

void copyInto(PersistentBufferInfo &target) const

Copy the contents of the buffer into a 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 function copies the data of a buffer into a pre-allocated persistent buffer. The user must ensure that the dimensions and type of the persistent buffer match the source buffer.

All data in the persistent buffer 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.

Parameters
  • target: The persistent buffer to copy the data into

Public Members

void *id = {}

The id of the buffer.

This must be passed to InstrumentDevice::returnBuffer() to return the buffer.

int64_t number = {}

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 = {}

The scalar type of the data in the buffer.

int order = {}

The tensor order of the buffer.

For spectrometers this will be 1.

For cameras this will be 2.

std::array<int64_t, 5> dimensions = {}

The dimensions of the data in the buffer.

Only the first BufferInfo::order entries will have valid values.

std::array<int64_t, 5> strides = {}

The strides of the data in the buffer.

Only the first BufferInfo::order entries will have valid values.

void const *dataPointer = {}

The pointer to the first element in the buffer.

size_t dataByteCount = {}

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.

bool ok = false

Whether the buffer was actually retrieved.

All other fields will not contain valid data if this is false.

class PersistentBufferInfo

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:

The persistent buffer has move-only semantics, even though it may be copied via the PersistentBufferInfo::copy() and PersistentBufferInfo::copyInto() methods. This is due to the fact that we wrap a native C handle and use move semantics to follow the movement of the ownership of the handle, and not the movement of the contained data.

Public Functions

PersistentBufferInfo()

Default constructor.

Creates an invalid persistent buffer handle. This exists only so that the user may create a variable that will hold a persistent buffer at a later point in time.

PersistentBufferInfo(PersistentBufferInfo &&other)

Move constructor.

Parameters
  • other: The persistent buffer to move

PersistentBufferInfo &operator=(PersistentBufferInfo &&other)

Move assignment operator.

Return
A reference to *this
Parameters
  • other: The persistent buffer to move

~PersistentBufferInfo()

Destructor.

int64_t number() const

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.

Return
The number of the buffer

int order() const

Get the tensor order of the buffer.

For spectrometers this will be 1.

For cameras this will be 2.

Return
The tensor order of the buffer

std::array<int64_t, 5> dimensions() const

Get the dimensions of the data in the buffer.

Only the first PersistentBufferInfo::order() entries will have valid values.

Return
The dimensions of the data in the buffer

std::array<int64_t, 5> strides() const

Get the strides of the data in the buffer.

Only the first PersistentBufferInfo::order() entries will have valid values.

Return
The strides of the data in the buffer

BufferScalarType scalarType() const

Get the scalar type of the data in the buffer.

Return
The scalar type of the data in the buffer

void const *rawData() const

Get the pointer to the first element in the buffer.

Return
The pointer to the first element in the buffer

size_t rawDataByteCount() const

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

Return
The number of bytes in the buffer

void copyRawData(void *memory, DataType dataType, std::array<int64_t, 5> 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.

Parameters
  • memory: Where to store the data of the buffer. The user must have preallocated it to have the correct size for the given data type (given the dimensions of this buffer)
  • 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
  • strides: The stride structure of the user-supplied memory area

PersistentBufferInfo copy() const

Copy the contents of the persistent buffer into a new persistent buffer.

This effectively clones the 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

void copyInto(PersistentBufferInfo &target) const

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

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

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.

Parameters
  • target: The persistent buffer to copy the data into

class BufferContainer

Buffer Container.

This structure describes a buffer that may be used to record multiple measurements. 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 createBufferContainer() function that creates a buffer container for the current buffer size of a given instrument device.

Public Functions

BufferContainer()

Default constructor.

BufferContainer(BufferContainer &&other)

Move constructor.

Parameters
  • other: The object to move

BufferContainer &operator=(BufferContainer &&other)

Move assignment operator.

Return
A reference to *this
Parameters
  • other: The object to move

~BufferContainer()

Destructor.

std::size_t count() const

Get the number of buffers stored in the buffer container.

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

Return
The number of buffers in the container

void clear()

Clear the buffer container.

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

void add(BufferInfo const &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.

Parameters
  • buffer: The buffer to add

void add(PersistentBufferInfo const &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.

Parameters
  • buffer: The persistent buffer to add

void addRaw(void const *data, BufferScalarType type, int order, std::array<int64_t, 5> dimensions, std::array<int64_t, 5> 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.

The data provided is copied into the container.

Parameters
  • data: A pointer to the data to add
  • type: The scalar type of the data to add
  • order: The order of the data to add. This must match what the buffer container expects
  • dimensions: The dimensions of the data to add. This must match what the buffer container expects
  • strides: The strides of the data to add.

void addRaw(void const *data, BufferScalarType type, std::vector<int64_t> dimensions, std::vector<int64_t> 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.

The data provided is copied into the container.

Parameters
  • data: A pointer to the data to add
  • type: The scalar type of the data to add
  • dimensions: The dimensions of the data to add. This must match what the buffer container expects
  • strides: The strides of the data to add. If this is empty the stride structure will be calculated under the assumption that the data is contiguous in memory

int order() const

Get the tensor order of the buffer container.

The tensor order will be one more than the tensor order of the device buffers.

Return
The tensor order of the buffer container

BufferScalarType scalarType() const

Get the scalar type of the buffer container.

Return
The scalar type of the buffer container

std::array<int64_t, 5> dimensions() const

Get the dimensions of the buffer container.

Only the first BufferContainer::order() entries will have a valid value.

Return
The dimensions of the buffer container

std::size_t bytesPerBuffer() const

Get the number of bytes for an individual buffer.

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

Return
The number of bytes for an individual buffer

std::size_t bytesTotal() const

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

This will change if the BufferContainer::count() changes.

Returns the number of bytes required to copy the data of all buffers that are stored in the buffer container into memory, assuming the target memory does not have any holes (trivial stride structure). If no buffers are in the container this will return zero.

Return
The number of total bytes required for the data in the container

void copyData(void *data, size_t dataSize)

Copy the data of the 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.

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

Parameters
  • data: The memory region to copy the data into
  • dataSize: The size of the memory region. This must be provided so that this function can check the region is large enough to hold the data

void copySingleData(size_t bufferId, void *data, size_t 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.

Parameters
  • bufferId: The id of the buffer to copy
  • data: The memory region to copy the data into
  • dataSize: The size of the memory region. This must be provided so that this function can check the region is large enough to hold the data

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

Return
The new persistent buffer
Parameters
  • bufferId: The id of the buffer to copy
  • overrideBufferNumber: If this is non-negative it will be stored as the buffer number of the persistent buffer; otherwise the value of bufferId will be used as the buffer number

void copyIntoBuffer(size_t bufferId, int64_t overrideBufferNumber, PersistentBufferInfo &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.

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.

Parameters
  • bufferId: The id of the buffer to copy
  • overrideBufferNumber: If this is non-negative it will be stored as the buffer number of the persistent buffer; otherwise the value of bufferId will be used as the buffer number
  • target: The persistent buffer to copy the data into