File I/O for Raw References

ReferenceImportFlag

enum fluxEngine::ReferenceImportFlag

Flags that influence importing of references.

This enumeration contains flags that may be passed to the importReference() function that will influence the behavior of that function.

Note that since this enumeration is to be used as a binary flag, this is not a scoped enumeration.

Values:

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

exportReference

inline void fluxEngine::exportReference(InstrumentDevice *device, BufferContainer const &bufferContainer, std::string const &fileName)

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 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 std::wstring overload of this 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.

Parameters:

device – The instrument device for which to export the reference data.
bufferContainer – The buffer container containing the reference data to export.
fileName – The file name of the reference to export. This file will be overwritten.

inline void fluxEngine::exportReference(InstrumentDevice *device, BufferContainer const &bufferContainer, std::wstring const &fileName)

Load a measurement from disk.

This function is identical to the std::string overload, 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 the std::string overload of exportReference() 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.
bufferContainer – The buffer container containing the reference data to export.
fileName – The file name of the reference to export. This file will be overwritten.

importReference

inline BufferContainer fluxEngine::importReference(InstrumentDevice *device, std::string const &fileName, uint64_t flags)

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 exportReference() 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 ReferenceImportFlag_IgnoreParameterMismatch flag, in which case the reference is loaded regardless.

Parameters:

device – The instrument device for which to import the reference data.
fileName – The file name of the reference to import.
flags – A bitwise or’d list of flags described in the ReferenceImportFlag enumeration that will influence how this function behaves. Specify 0 here for the default behavior.

Returns:

The newly loaded buffer container containing the reference

inline BufferContainer fluxEngine::importReference(InstrumentDevice *device, std::wstring const &fileName, uint64_t flags)

Import a reference measurement from disk.

This function is identical to the std::string overload, 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 the std::string overload of importReference() 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 import the reference data.
fileName – The file name of the reference to import.
flags – A bitwise or’d list of flags described in the ReferenceImportFlag enumeration that will influence how this function behaves. Specify 0 here for the default behavior.

Returns:

The newly loaded buffer container containing the reference