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

loadMeasurementList

fluxEngine.loadMeasurementList(handle, format, fileName)

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

Any path that may be passed to Python’s open() function will be accepted.

Parameters:

handle (Handle) – The fluxEngine handle
format (str) – The format of the file to load. Note that the string is case-sensitive.
fileName (str or bytes or os.PathLike) – The file name to load

Returns:

The measurement list

Return type:

MeasurementList

MeasurementList

class fluxEngine.MeasurementList(wrapped)

Measurement List

This contains a list of measurements.

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

calibrationInfo(index)

Get the calibration information of a measurement

Returns the calibration information of a measurement.

Parameters:: index (int) – The index of the measurements, starting at 0 for the first measurement in the list
Returns:: The calibration information of the measurement
Return type:: CalibrationInfo

count()

Get the number of measurements in a measurement list

Returns:: The number of measurements
Return type:: int

data(index)

Get the data of the measurement

Returns the data of the measurement as a numpy array. A copy will be made as the object lifetime semantics of fluxEngine differ from that of numpy.

Parameters:: index (int) – The index of the measurements, starting at 0 for the first measurement in the list
Returns:: The data of the measurement as a numpy array.
Return type:: numpy.ndarray

description(index)

Get the description of the measurement

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

Parameters:: index (int) – The index of the measurements, starting at 0 for the first measurement in the list
Returns:: The description of the measurement, if set, and None otherwise
Return type:: str or None

hasReference(index, referenceName)

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.

Parameters:

index (int) – The index of the measurements, starting at 0 for the first measurement in the list
referenceName (str) – The name of the reference. This must be "WhiteReference" or "DarkReference" at the moment. (This is case-sensitive.)

Returns:

Whether a specific reference measurement is present in the measurement

Return type:

bool

isHsiCube(index)

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.

Parameters:: index (int) – The index of the measurements, starting at 0 for the first measurement in the list
Returns:: Whether a specific measurement is a HSI cube
Return type:: bool

isIlluminationCorrected(index)

Get whether the measurement was already illumination corrected

Parameters:: index (int) – The index of the measurements, starting at 0 for the first measurement in the list
Returns:: Whether the measurementw as already illumination corrected
Return type:: bool

name(index)

Get the name of the 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.

Parameters:: index (int) – The index of the measurements, starting at 0 for the first measurement in the list
Returns:: The name of the measurement, if set, and None otherwise
Return type:: str or None

referenceData(index, referenceName)

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 copy of the data of such a reference measurement, if present.

Returns the data of a reference measurement as a numpy array. A copy will be made as the object lifetime semantics of fluxEngine differ from that of numpy.

Parameters:

index (int) – The index of the measurements, starting at 0 for the first measurement in the list
referenceName (str) – The name of the reference. This must be "WhiteReference" or "DarkReference" at the moment. (This is case-sensitive.)

Returns:

The data of the measurement as a numpy array.

Return type:

numpy.ndarray

valueType(index)

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.

Parameters:: index (int) – The index of the measurements, starting at 0 for the first measurement in the list
Returns:: The value type of the measurement, if it is one of the supported types in the ValueType enumeration, or None if the value type could not be determined or it is a non-supported type.
Return type:: ValueType or None

wavelengths(index)

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.

Parameters:: index (int) – The index of the measurements, starting at 0 for the first measurement in the list
Returns:: The list of wavelengths associated with the spectral dimension of the measurement
Return type:: list(float)

saveMeasurementList

fluxEngine.saveMeasurementList(handle, measurementList, format, fileName, saveReferences=True)

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

Any path that may be passed to Python’s open() function will be accepted.

Parameters:

handle (Handle) – The fluxEngine handle
measurementList (MeasurementList) – The measurement list to save
format (str) – The format of the file to load. Note that the string is case-sensitive.
fileName (str or bytes or os.PathLike) – The file name to load

MeasurementHSICubeInput

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

name

The name of the measurement

If an empty string this indicates the measurement has no specific name.

Type:: str or None

valueType

The value type of the measurement

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

Type:: ValueType

storageOrder

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.

Type:: HSICube_StorageOrder

wavelengths

A vector of the wavelengths of the cube

Type:: list(float)

whiteReference

Optional: the white reference measurement

If not None this should point to an array containing the white reference measurement data, using the same wavelengths and storage order as the primary measurement.

Type:: numpy.ndarray or None

darkReference

Optional: the dark reference measurement

If not None this should point to an array containing the dark reference measurement data, using the same wavelengths and storage order as the primary measurement.

Type:: numpy.ndarray or None

illuminationReference

Optional: the illumination reference measurement

If not None this should point to an array containing the illumination reference measurement data, using the same wavelengths and storage order as the primary measurement.

Type:: numpy.ndarray or None

data

The measurement data

This must have exactly 3 dimensions to be considered a valid array to be used to create a HSI cube measurement. The meaning of the shape depends on the storage order.

Type:: numpy.ndarray

calibrationInfo

Optional: calibration info

If not None this should be an instance of a CalibrationInfo object that should be used for the calibration information of the measurement that is to be stored.

Type:: CalibrationInfo or None

isIlluminationCorrected

Whether the raw intensities are already illumination corrected

Type:: bool

MeasurementHSICubeBufferInput

class fluxEngine.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 BufferContainer objects that the user has used to record data via a recording processing context.

name

The name of the measurement

If an empty string this indicates the measurement has no specific name.

Type:: str or None

valueType

The value type of the measurement

This indicates if the measurement was made in intensities or reflectances. This should be identical to the value specified when creating the recording context that was used to fill the provided buffer containers.

Type:: ValueType

wavelengths

A vector of the wavelengths of the cube

Type:: list(float)

whiteReference

Optional: the white reference measurement

If not None this should point to an array containing the white reference measurement data, using the same wavelengths as the primary measurement. The storage order is assumed to be BIP.

Type:: numpy.ndarray or None

darkReference

Optional: the dark reference measurement

If not None this should point to an array containing the dark reference measurement data, using the same wavelengths as the primary measurement. The storage order is assumed to be BIP.

Type:: numpy.ndarray or None

illuminationReference

Optional: the illumination reference measurement

If not None this should point to an array containing the illumination reference measurement data, using the same wavelengths and storage order as the primary measurement.

Type:: numpy.ndarray or None

bufferContainers

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.

Type:: list(BufferContainer)

calibrationInfo

Optional: calibration info

If not None this should be an instance of a CalibrationInfo object that should be used for the calibration information of the measurement that is to be stored.

Type:: CalibrationInfo or None

isIlluminationCorrected

Whether the raw intensities are already illumination corrected

Type:: bool

createMeasurementHSICube

fluxEngine.createMeasurementHSICube(handle, input, **kwargs)

Create a new HSI cube measurement

Creates a measurement list that contains a single HSI cube measurement from either raw data (when MeasurementHSICubeInput is supplied) or a sequence of buffer containers (when MeasurementHSICubeBufferInput is supplied). Please see the corresponding structures for details on the data that must be provided for this to succeed.

The variant for use with buffer containers ist useful when the user has created one or more containers via the createBufferContainerForRecordingContext() function, and added data to them via the BufferContainer.addLastResult() method in order 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 resulting measurement list may then be saved via the saveMeasurementList() function.

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.