File I/O

Measurements (HSI Cubes, etc.)

typedef struct fluxEngine_C_v1_MeasurementList fluxEngine_C_v1_MeasurementList

A measurement list.

This contains a list of measurements.

Objects of this type must be freed by the user via the fluxEngine_C_v1_MeasurementList_free() method.

Currently objects of this type can only be created by loading data from disk.

struct fluxEngine_C_v1_MeasurementHSICubeInput

Input data for creating a HSI cube measurement.

This structure describes the information required to create a HSI cube measurement from user-supplied data.

To use the API properly, the user should initialize the structure via

fluxEngine_C_v1_MeasurementHSICubeInput input; memset(&input, 0, sizeof(input)); input.structure_size = sizeof(input);

and then set the corresponding field values. This ensures future compatibility of the code in both API and ABI.

Public Members

size_t structure_size

The size of the structure.

This should always be initialized by the user to have sizeof(fluxEngine_C_v1_MeasurementHSICubeInput) as its value. It exists to enable future extensions of the C API that are binary compatible.

char const *name

The name of the measurement.

If NULL this indicates the measurement has no specific name.

fluxEngine_C_v1_DataType data_type: The data type of the data.

fluxEngine_C_v1_ValueType value_type

The value type of the measurement.

This indicates if the measurement was made in intensities or reflectances.

fluxEngine_C_v1_HSICube_StorageOrder storage_order

The storage order of the user-supplied data.

Note that internally the storage order will always be converted to BIP storage order. This here indicates only the order in which the user has stored the data.

int64_t lines

The number of lines in the HSI cube.

In BIP and BIL storage order this will correspond to the outer (left-most) dimension of the cube, in BSQ storage order to the middle dimension of the cube.

int64_t samples

The number of samples in the HSI cube.

In BIP storage order this will correspond to the middle dimension of the cube, in BIL and BSQ storage order to the inner (right-most) dimension of the cube.

int64_t bands

The number of bands in the HSI cube.

In BIP storage order this will correspond to the inner (right-most) dimension of the cube, in BIL storage order to the middle dimension of the cube, and in BSQ storage order to the outer (left-most) dimension of the cube.

int64_t strides[3]

The strides of the cube.

These must be the strides ordered according to the actual memory layout.

For example, if the data resides contiguously in memory (without any holes) and hence has a trivial stride structure, and a cube with 512 lines, 320 samples and 256 bands is to be saved, the strides should be specified as follows:

BIP storage order: dimensions are {512, 320, 256}, hence strides should be {81920, 256, 1}
BIL storage order: dimensions are {512, 256, 320}, hence strides should be {81920, 320, 1}
BSQ storage order: dimensions are {256, 512, 320}, hence strides should be {163840, 320, 1}

void const *data: A pointer to the first element of the cube data.

double const *wavelengths

A vector of the wavelengths of the cube.

The number of wavelengths are specified by the bands member.

struct fluxEngine_C_v1_MeasurementHSICubeInput const *white_reference

Optional: the white reference measurement.

If not NULL this should point to a structure of the same type that contains the data of the white reference.

struct fluxEngine_C_v1_MeasurementHSICubeInput const *dark_reference

Optional: the dark reference measurement.

If not NULL this should point to a structure of the same type that contains the data of the dark reference.

fluxEngine_C_v1_CalibrationInfo const *calibration_info

Optional: calibration info.

If not NULL this may be used to specify calibration inforamtion that should be stored in conjunction with the measurement.

This field was added in fluxEngine 4.10.

struct fluxEngine_C_v1_MeasurementHSICubeBufferInput

Input data for creating a HSI cube measurement from buffer containers.

This structure describes the information required to create a HSI cube measurement a list of fluxEngine_C_v1_BufferContainer objects that the user has used to record data via a recording processing context.

To use the API properly, the user should initialize the structure via

fluxEngine_C_v1_MeasurementHSICubeBufferInput input; memset(&input, 0, sizeof(input)); input.structure_size = sizeof(input);

and then set the corresponding field values. This ensures future compatibility of the code in both API and ABI.

Public Members

size_t structure_size

The size of the structure.

This should always be initialized by the user to have sizeof(fluxEngine_C_v1_MeasurementHSICubeBufferInput) as its value. It exists to enable future extensions of the C API that are binary compatible.

char const *name

The name of the measurement.

If NULL this indicates the measurement has no specific name.

fluxEngine_C_v1_ValueType value_type

The value type of the measurement.

This indicates if the measurement was made in intensities or reflectances.

size_t buffer_container_count

The number of buffer containers to concatenate.

In order for the user not having to pre-allocate a buffer container that is large enough to hold the maximum possible recording size, this structure allows the user to specify multiple buffer containers that will be taken in sequence. The user could hence allocate buffer containers in blocks of a certain size and once one of them is full allocate the next container, and provide a list of them to this structure.

fluxEngine_C_v1_BufferContainer const **buffer_containers

Pointers to the buffer containers to concatenate.

The structure of the buffer containers is verified to be compatible with a HSI cube structure. It is assumed that the data in the containers is in BIP storage order, as that is the storage order returned by all recording processing contexts.

All buffer containers must match in structure, but may contain a varying number of lines. They will be concatenated.

double const *wavelengths: The vector of wavelengths of the measurement.

int wavelength_count

The number of wavelengths.

This will be cross-checked against the structure of the buffer containers supplied.

fluxEngine_C_v1_ProcessingContext_ReferenceMeasurement const *white_reference

Optional: the white reference.

The user may provide the same structure that is also returned by the context creation functions to indicate that the white reference should be saved together with the measurement.

fluxEngine_C_v1_ProcessingContext_ReferenceMeasurement const *dark_reference

Optional: the dark reference.

The user may provide the same structure that is also returned by the context creation functions to indicate that the dark reference should be saved together with the measurement.

fluxEngine_C_v1_CalibrationInfo const *calibration_info

Optional: calibration info.

If not NULL this may be used to specify calibration inforamtion that should be stored in conjunction with the measurement.

This field was added in fluxEngine 4.10.

int fluxEngine_C_v1_MeasurementList_load(fluxEngine_C_v1_Handle *handle, char const *format, char const *file_name, fluxEngine_C_v1_MeasurementList **measurement_list, fluxEngine_C_v1_Error **error)

Load a measurement from disk.

This function may be used to load a measurement from disk. At the moment the following formats are supported:

Hyperspectral cubes in ENVI format. (Specify "ENVI" as the format; note that this is case-sensitive.)

Please refer to the main fluxEngine documentation for details on the supported file formats.

If the data could be loaded from disk successfully, a fluxEngine_C_v1_MeasurementList object will be returned. Many file formats (for example ENVI) only support storing a single measurement in a file, which means that the list of measurements will always contain exactly one entry for that type of format. Other formats may support storing multiple measurements in a file, in which case number of measurements in the resulting list may vary.

The user must ensure they have enough RAM to load the corresponding measurement. Especially HSI cubes may be quite large and take up quite a bit of RAM.

HSI cubes: when loading HSI cubes their storage order is normalized at load time. All cubes, regardless of their storage order on disk, will be available in BIP storage order. This means that the first dimension of the loaded data will correspond to the y dimension, the second to the x dimension and the third to the wavelength dimension.

Licensing: if the license is tied to an instrument device serial number, the device must be connected in order to be able to call this function. Similarly, if the license is tied to a dongle and that dongle has been pulled, this function will fail. (Note that saving data will still work even if the device has since been disconnected.)

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 fluxEngine_C_v1_MeasurementList_load_w() function 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 method will very likely fail.

Note to non-Windows users: the encoding of the file name is highly dependent on the environment, and may or may not be UTF-8. It is up to the user to specify the file correctly; fluxEngine will pass it directly to the corresponding operating system functions.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_HandleNoLongerValid
fluxEngine_C_v1_ErrorCode_FileAccessError
fluxEngine_C_v1_ErrorCode_FileNotFoundError
fluxEngine_C_v1_ErrorCode_FileAccessDeniedError
fluxEngine_C_v1_ErrorCode_FileTypeError
fluxEngine_C_v1_ErrorCode_FileInUseError
fluxEngine_C_v1_ErrorCode_IOError

Parameters

handle – The fluxEngine handle
format – The format of the file to load. Note that the string is case-sensitive.
file_name – The file name to load.
measurement_list – [out] The resulting list of measurements
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_MeasurementList_load_w(fluxEngine_C_v1_Handle *handle, char const *format, wchar_t const *file_name, fluxEngine_C_v1_MeasurementList **measurement_list, fluxEngine_C_v1_Error **error)

Load a measurement from disk.

This function is identical to fluxEngine_C_v1_MeasurementList_load(), other than it takes a wide (“Unicode”) filename on Windows systems, to support opening files that can’t be encoded in the local codepage.

Please refer to the documentation of fluxEngine_C_v1_MeasurementList_load() for details on the behavior of this function beyond the encoding of the filename.

Note

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

Parameters

handle – The fluxEngine handle
format – The format of the file to load. Note that the string is case-sensitive.
file_name – The file name to load.
measurement_list – [out] The resulting list of measurements
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_Measurement_create_hsi_cube(fluxEngine_C_v1_Handle *handle, fluxEngine_C_v1_MeasurementHSICubeInput const *input, fluxEngine_C_v1_MeasurementList **measurement_list, fluxEngine_C_v1_Error **error)

Create a new HSI cube measurement from raw data.

Creates a measurement list that contains a single HSI cube measurement from raw data that the user must supply. Please see the fluxEngine_C_v1_MeasurementHSICubeInput structure for further details on the data that must be provided for this to succeed.

The resulting measurement list may then be saved via the fluxEngine_C_v1_MeasurementList_save() or fluxEngine_C_v1_MeasurementList_save_w() functions.

A copy of the data provided by the user will be created in this function. The user should ensure that there is enough RAM available to store such a copy.

This function may use the default processing queue set of the handle for any data processing that is required by this method. If another processing queue set is to be used, please use fluxEngine_C_v1_Measurement_create_hsi_cube_pqs() instead.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_HandleNoLongerValid

Parameters

handle – The fluxEngine handle
input – The input parameters required to create the measurement
measurement_list – [out] The resulting list of measurements
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_MeasurementList_save(fluxEngine_C_v1_Handle *handle, fluxEngine_C_v1_MeasurementList const *measurement_list, char const *format, char const *file_name, bool save_references, fluxEngine_C_v1_Error **error)

Save a measurement (list) to disk.

This function may be used to save a measurement (list) to disk. At the moment the following formats are supported:

Hyperspectral cubes in ENVI format. (Specify "ENVI" as the format; note that this is case-sensitive.)

Please refer to the main fluxEngine documentation for details on the supported file formats.

The measurements in the supplied measurement list must be compatible with the save format, otherwise an error will occur. In particular, some formats, such as ENVI, only support saving a single measurement in a file.

HSI cubes: note that this routine always stores HSI cubes in the BIP storage order when the format allows for a choice in that.

Licensing: this function may be called even if the device a license has been tied to has since been disconnected, or the license dongle has since been removed, in order to allow the application gracefully save data before failing. However, if the license is tied to a device, the device must have been connected at least once with the current handle before this function can be called successfully.

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 fluxEngine_C_v1_MeasurementList_save_w() function 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 method will very likely fail.

Note to non-Windows users: the encoding of the file name is highly dependent on the environment, and may or may not be UTF-8. It is up to the user to specify the file correctly; fluxEngine will pass it directly to the corresponding operating system functions.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_HandleNoLongerValid
fluxEngine_C_v1_ErrorCode_FileAccessError
fluxEngine_C_v1_ErrorCode_FileNotFoundError
fluxEngine_C_v1_ErrorCode_FileAccessDeniedError
fluxEngine_C_v1_ErrorCode_FileTypeError
fluxEngine_C_v1_ErrorCode_FileInUseError
fluxEngine_C_v1_ErrorCode_IOError

Parameters

handle – The fluxEngine handle
measurement_list – The measurements to save
format – The format of the file to load. Note that the string is case-sensitive.
file_name – The file name to save into.
save_references – Whether to also save reference measurements (if present), or only save the actual measurement itself.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_MeasurementList_save_w(fluxEngine_C_v1_Handle *handle, fluxEngine_C_v1_MeasurementList const *measurement_list, char const *format, wchar_t const *file_name, bool save_references, fluxEngine_C_v1_Error **error)

Save a measurement (list) to disk.

This function is identical to fluxEngine_C_v1_MeasurementList_save(), other than it takes a wide (“Unicode”) filename on Windows systems, to support opening files that can’t be encoded in the local codepage.

Please refer to the documentation of fluxEngine_C_v1_MeasurementList_save() for details on the behavior of this function beyond the encoding of the filename.

Note

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

Parameters

handle – The fluxEngine handle
measurement_list – The measurements to save
format – The format of the file to load. Note that the string is case-sensitive.
file_name – The file name to save into.
save_references – Whether to also save reference measurements (if present), or only save the actual measurement itself.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_MeasurementList_count(fluxEngine_C_v1_MeasurementList *measurement_list, fluxEngine_C_v1_Error **error)

Get the number of measurements in a measurement list.

Note that the result will be returned as the (non-negative) return value of this function and not as an output parameter. Please check for success of this function via the rc < 0 condition and not the rc != 0 check that may be used for other functions.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument

Parameters

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

Returns

The number of measurements on success, -1 on failure

int fluxEngine_C_v1_MeasurementList_get_value_type(fluxEngine_C_v1_MeasurementList *measurement_list, int index, int *value_type, fluxEngine_C_v1_Error **error)

Get the value type of a measurement.

Get the value type of the data in a given measurement. This indicates a measurement was made in intensities or reflectances.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_IndexOutOfRange

Parameters

measurement_list – The measurement list
index – The index of the measurement, starting at 0 for the first measurement in the list
value_type – [out] The value type of the measurement will be stored here. If the value type is one of the types listed in the fluxEngine_C_v1_ValueType enumeration, that value will be stored here. If the value type could not be determined, or the value type is something not supported by fluxEngine’s public API, -1 will be stored here, instead.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_MeasurementList_get_name(fluxEngine_C_v1_MeasurementList *measurement_list, int index, char **name, fluxEngine_C_v1_Error **error)

Get the name of a measurement.

Many file formats allow the user to specify a name for a given measurement. If such a name is present it will be returned.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_IndexOutOfRange

Parameters

measurement_list – The measurement list
index – The index of the measurement, starting at 0 for the first measurement in the list
name – [out] The name of the measurement will be stored here. The resulting string must be freed with fluxEngine_C_v1_string_free(). If no name is present in the measurement this may be set to NULL after the function returns.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_MeasurementList_get_description(fluxEngine_C_v1_MeasurementList *measurement_list, int index, char **description, fluxEngine_C_v1_Error **error)

Get the description of a measurement.

Many file formats allow the user to specify a description for a given measurement. If such a name is present it will be returned.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_IndexOutOfRange

Parameters

measurement_list – The measurement list
index – The index of the measurement, starting at 0 for the first measurement in the list
description – [out] The description of the measurement will be stored here. The resulting string must be freed with fluxEngine_C_v1_string_free(). If no description is present in the measurement this may be set to NULL after the function returns.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_MeasurementList_get_structure(fluxEngine_C_v1_MeasurementList *measurement_list, int index, fluxEngine_C_v1_DataType *data_type, int *order, int64_t dimensions[5], int64_t strides[5], fluxEngine_C_v1_Error **error)

Get the tensor structure of a measurement.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_IndexOutOfRange

Parameters

measurement_list – The measurement list
index – The index of the measurement, starting at 0 for the first measurement in the list
data_type – [out] The data type of the measurement data
order – [out] The order of the tensor. For example, for HSI cubes this will be 3.
dimensions – [out] The dimensions of the measurement.
strides – [out] The strides of the measurement data. These are only relevant when calling fluxEngine_C_v1_MeasurementList_get_data().
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_MeasurementList_get_data(fluxEngine_C_v1_MeasurementList *measurement_list, int index, void const **data, size_t *data_size, fluxEngine_C_v1_Error **error)

Get the data of the measurement.

Retrieves a pointer to the first element of the tensor that contains the data of a given measurement.

This will not copy any data, but only return a pointer to the internal data. That pointer will only be valid as long as this measurement list is not freed.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_IndexOutOfRange

Parameters

measurement_list – The measurement list
index – The index of the measurement, starting at 0 for the first measurement in the list
data – [out] A pointer to the internal data of the loaded measurement
data_size – [out] The number of bytes the internal data is using
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_MeasurementList_copy_data(fluxEngine_C_v1_MeasurementList *measurement_list, int index, void *buffer, int64_t strides[5], fluxEngine_C_v1_Error **error)

Copy the data of the measurement.

Create a copy of the data of the measurement. The data will be stored in a buffer provided by the user that has the stride structure specified by the strides parameter.

The user must ensure the buffer is large enough to hold the data. The structure may be obtained via the fluxEngine_C_v1_MeasurementList_get_structure() function.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_IndexOutOfRange

Parameters

measurement_list – The measurement list
index – The index of the measurement, starting at 0 for the first measurement in the list
buffer – [out] A pointer to the buffer that will hold the data
strides – The stride structure of the target buffer provided by the user
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_MeasurementList_has_reference(fluxEngine_C_v1_MeasurementList *measurement_list, int index, char const *reference_name, fluxEngine_C_v1_Error **error)

Does a given measurement have a specific reference?

Sometimes the file format loaders are able to automatically load reference data that was stored in conjunction with the actual measurement. This method returns whether such reference data for a given measurement exists.

Note that the result will be returned as the (non-negative) return value of this function and not as an output parameter. Please check for success of this function via the rc < 0 condition and not the rc != 0 check that may be used for other functions.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_IndexOutOfRange

Parameters

measurement_list – The measurement list
index – The index of the measurement, starting at 0 for the first measurement in the list
reference_name – The type of reference look at. Currently this may either be "WhiteReference" or "DarkReference". (This is case-sensitive.)
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

1 if the reference is present, 0 if not, -1 on failure

int fluxEngine_C_v1_MeasurementList_get_reference_structure(fluxEngine_C_v1_MeasurementList *measurement_list, int index, char const *reference_name, fluxEngine_C_v1_DataType *data_type, int *order, int64_t dimensions[5], int64_t strides[5], fluxEngine_C_v1_Error **error)

Get the tensor structure of a reference measurement.

Sometimes the file format loaders are able to automatically load reference data that was stored in conjunction with the actual measurement. This method returns the tensor structure of such a reference measurement, if present.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_IndexOutOfRange

Parameters

measurement_list – The measurement list
index – The index of the measurement, starting at 0 for the first measurement in the list
reference_name – The type of reference look at. Currently this may either be "WhiteReference" or "DarkReference". (This is case-sensitive.)
data_type – [out] The data type of the measurement data
order – [out] The order of the tensor. For example, for HSI cubes this will be 3.
dimensions – [out] The dimensions of the measurement.
strides – [out] The strides of the measurement data. These are only relevant when calling fluxEngine_C_v1_MeasurementList_get_data().
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_MeasurementList_get_reference_data(fluxEngine_C_v1_MeasurementList *measurement_list, int index, char const *reference_name, void const **data, size_t *data_size, fluxEngine_C_v1_Error **error)

Get the data of a reference measurement.

Sometimes the file format loaders are able to automatically load reference data that was stored in conjunction with the actual measurement. This method returns a pointer to the data of such a reference measurement, if present.

Retrieves a pointer to the first element of the tensor that contains the data of a given reference measurement.

This will not copy any data, but only return a pointer to the internal data. That pointer will only be valid as long as this measurement list is not freed.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_IndexOutOfRange

Parameters

measurement_list – The measurement list
index – The index of the measurement, starting at 0 for the first measurement in the list
reference_name – The type of reference look at. Currently this may either be "WhiteReference" or "DarkReference". (This is case-sensitive.)
data – [out] A pointer to the internal data of the loaded measurement
data_size – [out] The number of bytes the internal data is using
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_MeasurementList_copy_reference_data(fluxEngine_C_v1_MeasurementList *measurement_list, int index, char const *reference_name, void *buffer, int64_t strides[5], fluxEngine_C_v1_Error **error)

Copy the data of a reference measurement.

Sometimes the file format loaders are able to automatically load reference data that was stored in conjunction with the actual measurement. This method copies the data of such a reference measurement, if present.

Create a copy of the data of a reference measurement. The data will be stored in a buffer provided by the user that has the stride structure specified by the strides parameter.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_IndexOutOfRange

Parameters

measurement_list – The measurement list
index – The index of the measurement, starting at 0 for the first measurement in the list
reference_name – The type of reference look at. Currently this may either be "WhiteReference" or "DarkReference". (This is case-sensitive.)
buffer – [out] A pointer to the buffer that will hold the data
strides – The stride structure of the target buffer provided by the user
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_MeasurementList_is_hsi_cube(fluxEngine_C_v1_MeasurementList *measurement_list, int index, fluxEngine_C_v1_Error **error)

Is a given measurement a HSI cube?

While the only format supported as of now is ENVI, future versions of fluxEngine will support other types of measurements. For this reason this function exists to check whether a measurement that was loaded from disk is actually a HSI cube.

Note that the result will be returned as the (non-negative) return value of this function and not as an output parameter. Please check for success of this function via the rc < 0 condition and not the rc != 0 check that may be used for other functions.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_IndexOutOfRange

Parameters

measurement_list – The measurement list
index – The index of the measurement, starting at 0 for the first measurement in the list
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

1 if the measurement is a HSI cube, 0 if not, -1 on failure

int fluxEngine_C_v1_MeasurementList_get_wavelengths(fluxEngine_C_v1_MeasurementList *measurement_list, int index, double **wavelengths, size_t *wavelength_count, fluxEngine_C_v1_Error **error)

Obtain the wavelengths of a given measurement.

Formats that store spectral data, such as ENVI for hyperspectral data cubes, come with information about which wavelengths are assigned to the spectral dimension of the data.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_IndexOutOfRange

Parameters

measurement_list – The measurement list
index – The index of the measurement, starting at 0 for the first measurement in the list
wavelengths – [out] The wavelength array will be stored in this parameter. The pointer returned here must be freed via fluxEngine_C_v1_wavelengths_free().
wavelength_count – [out] The number of wavelengths. The number here will correspond to a dimension of the tensor structure
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_MeasurementList_get_calibration_info(fluxEngine_C_v1_MeasurementList *measurement_list, int index, fluxEngine_C_v1_CalibrationInfo **calibration_info, fluxEngine_C_v1_Error **error)

Get the calibration info of the measurement.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_IndexOutOfRange

Parameters

measurement_list – The measurement list
index – The index of the measurement, starting at 0 for the first measurement in the list
calibration_info – [out] A pointer to where the newly created calibration info object will be stored. The user must free this object via fluxEngine_C_v1_CalibrationInfo_free() after use.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

void fluxEngine_C_v1_MeasurementList_free(fluxEngine_C_v1_MeasurementList *measurement_list)

Free the memory associated with a measurement list.

Any pointer accessed via fluxEngine_C_v1_MeasurementList_get_data() and fluxEngine_C_v1_MeasurementList_get_reference_data() will no longer be valid after a call to this function.

Passing NULL to this function is safe. (The function will have no effect in that case.)

Parameters

measurement_list – The measurement list

Raw Reference Data

enum fluxEngine_C_v1_ReferenceImportFlag

Flags that influence importing of references.

This enumeration contains flags that may be passed to the fluxEngine_C_v1_import_reference() and fluxEngine_C_v1_import_reference_w() that will influence the behavior of these functions.

Values:

enumerator fluxEngine_C_v1_ReferenceImportFlag_IgnoreParameterMismatch

Ignore parameter mismatch.

If the parameters stored with the reference don’t match the current instrument parameters, this flag may be provided to indicate that these issues should be ignored.

A reference measured for a different exposure time or a different ROI offset will be able to be loaded with this flag set, though the math with that reference loaded will likely not work out correctly.

int fluxEngine_C_v1_export_reference(fluxEngine_C_v1_Device *device, fluxEngine_C_v1_BufferContainer const *buffer_container, char const *file_name, fluxEngine_C_v1_Error **error)

Export measured reference data to a file.

After a user has filled a buffer container with data from a reference measurement, that measurement may be exported to a file on disk, so it may be loaded again at a later point in time.

Measured references are typically stored in a file ending in .fluxref.

The buffer container’s structure is checked against the buffer structure of the device. If that doesn’t match, the export will fail.

The instrument device’s current settings that influence a reference measurement will be stored in the exported reference. These will be used to check if the reference is compatible when loading it again. (That check may be disabled, see fluxEngine_C_v1_ReferenceImportFlag_IgnoreParameterMismatch when importing it.)

Restrictions: it is currently not possible to export a ring buffer container. (This will be lifted in a future version.)

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 fluxEngine_C_v1_export_reference_w() function 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 method will very likely fail.

Note to non-Windows users: the encoding of the file name is highly dependent on the environment, and may or may not be UTF-8. It is up to the user to specify the file correctly; fluxEngine will pass it directly to the corresponding operating system functions.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_DeviceNoLongerValid
fluxEngine_C_v1_ErrorCode_InstrumentDeviceIncompatibleError
fluxEngine_C_v1_ErrorCode_DeviceTypeError
fluxEngine_C_v1_ErrorCode_BufferStructureMismatch
fluxEngine_C_v1_ErrorCode_NotImplemented

Parameters

device – The instrument device for which to export the reference data.
buffer_container – The buffer container containing the reference data to export.
file_name – The file name of the reference to export. This file will be overwritten.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_export_reference_w(fluxEngine_C_v1_Device *device, fluxEngine_C_v1_BufferContainer const *buffer_container, wchar_t const *file_name, fluxEngine_C_v1_Error **error)

Export measured reference data to a file.

This function is identical to fluxEngine_C_v1_export_reference(), other than it takes a wide (“Unicode”) filename on Windows systems, to support opening files that can’t be encoded in the local codepage.

Please refer to the documentation of fluxEngine_C_v1_export_reference() for details on the behavior of this function beyond the encoding of the filename.

Note

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

Parameters

device – The instrument device for which to export the reference data.
buffer_container – The buffer container containing the reference data to export.
file_name – The file name of the reference to export. This file will be overwritten.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_import_reference(fluxEngine_C_v1_Device *device, char const *file_name, uint64_t flags, fluxEngine_C_v1_BufferContainer **buffer_container, fluxEngine_C_v1_Error **error)

Import a reference measurement from disk.

Imports the raw data of a reference measurement from disk. This will load .fluxref files that may either be created via the fluxRecorder/fluxTrainer applications or have been exported via the fluxEngine_C_v1_export_reference() from within fluxEngine.

These will create a buffer container object that may then be passed to instrument processing contexts.

The tensor data type and dimensions for the reference that is loaded must be compatible, or an error will occur.

The instrument device’s current settings that influence a reference measurement will be compared against the settings stored in the exported reference. If these don’t match, by default this function will return an error, but that behavior may be overridden by specifying the fluxEngine_C_v1_ReferenceImportFlag_IgnoreParameterMismatch flag, in which case the reference is loaded regardless.

Parameters

device – The instrument device for which to import the reference data.
file_name – The file name of the reference to import.
flags – A bitwise or’d list of flags described in the fluxEngine_C_v1_ReferenceImportFlag enumeration that will influence how this function behaves. Specify 0 here for the default behavior.
buffer_container – [out] The newly loaded buffer container containing the reference data
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure

int fluxEngine_C_v1_import_reference_w(fluxEngine_C_v1_Device *device, wchar_t const *file_name, uint64_t flags, fluxEngine_C_v1_BufferContainer **buffer_container, fluxEngine_C_v1_Error **error)

Import a reference measurement from disk.

This function is identical to fluxEngine_C_v1_import_reference(), other than it takes a wide (“Unicode”) filename on Windows systems, to support opening files that can’t be encoded in the local codepage.

Please refer to the documentation of fluxEngine_C_v1_import_reference() for details on the behavior of this function beyond the encoding of the filename.

Note

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

Parameters

device – The instrument device for which to export the reference data.
file_name – The file name of the reference to import.
flags – A bitwise or’d list of flags described in the fluxEngine_C_v1_ReferenceImportFlag enumeration that will influence how this function behaves. Specify 0 here for the default behavior.
buffer_container – [out] The newly loaded buffer container containing the reference data
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns

0 on success, -1 on failure