File I/O for Measurements (HSI Cubes, etc.)

MeasurementList

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.

MeasurementHSICubeInput

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_MeasurementHSICubeInput const *illumination_reference

Optional: the illumination reference measurement.

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

This field was added in fluxEngine 4.17.

bool is_illumination_corrected

Optional: whether the measurement was already illumination corrected.

If the measurement is in intensities (or radiances), this flag indicates whether the illumination correction has already been performed.

This field was added in fluxEngine 4.17.

MeasurementHSICubeBufferInput

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.

fluxEngine_C_v1_ProcessingContext_ReferenceMeasurement const *illumination_reference

Optional: the illumination reference.

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

This field was added in fluxEngine 4.17.

bool is_illumination_corrected

Optional: whether the measurement was already illumination corrected.

If the measurement is in intensities (or radiances), this flag indicates whether the illumination correction has already been performed.

This field was added in fluxEngine 4.17.

MeasurementList_load

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

MeasurementList_load_w

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

Measurement_create_hsi_cube

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

Measurement_create_hsi_cube_pqs

int fluxEngine_C_v1_Measurement_create_hsi_cube_pqs(fluxEngine_C_v1_Handle *handle, fluxEngine_C_v1_ProcessingQueueSet *processing_queue_set, 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.

This function is identical to fluxEngine_C_v1_Measurement_create_hsi_cube(), but also takes a processing queue set that is used for the processing that is required to create the measurement.

The handle of the processing queue set must match the handle that is supplied.

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

Measurement_create_hsi_cube_from_buffers

int fluxEngine_C_v1_Measurement_create_hsi_cube_from_buffers(fluxEngine_C_v1_Handle *handle, fluxEngine_C_v1_MeasurementHSICubeBufferInput const *input, fluxEngine_C_v1_MeasurementList **measurement_list, fluxEngine_C_v1_Error **error)

Create a new HSI cube measurement from PushBroom buffers.

This will create a new HSI cube measurement from a set of PushBroom buffer containers the user must provide. This is useful if the user created one or more buffer containers via the fluxEngine_C_v1_BufferContainer_create_from_recording_context(), and added data to them via fluxEngine_C_v1_BufferContainer_add_last_result() to record data from a device. In that case the recording can be combined to a HSI cube that the user may then save to disk.

The list of buffers should be provided via the input parameter in form of a fluxEngine_C_v1_MeasurementHSICubeBufferInput structure. See the documentation of that structure for details on what is required to be specified.

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.

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

MeasurementList_save

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

MeasurementList_save_w

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

MeasurementList_count

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

MeasurementList_get_value_type

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

MeasurementList_get_name

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

MeasurementList_get_description

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

MeasurementList_get_structure

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

MeasurementList_get_data

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

MeasurementList_copy_data

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

MeasurementList_has_reference

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", "DarkReference", or "IlluminationReference". (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

MeasurementList_get_reference_structure

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", "DarkReference", or "IlluminationReference". (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

MeasurementList_get_reference_data

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", "DarkReference", or "IlluminationReference". (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

MeasurementList_copy_reference_data

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", "DarkReference", or "IlluminationReference". (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

MeasurementList_is_hsi_cube

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

MeasurementList_get_is_illumination_corrected

int fluxEngine_C_v1_MeasurementList_get_is_illumination_corrected(fluxEngine_C_v1_MeasurementList *measurement_list, int index, bool *value, fluxEngine_C_v1_Error **error)

Get whether the measurement was already illumination corrected.

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 – [out] Whether the measurementw as already illumination corrected
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

MeasurementList_get_wavelengths

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

MeasurementList_get_calibration_info

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

MeasurementList_free

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