File I/O
- 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
- 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
- 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
- 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)
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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.