File I/O for Raw References

ReferenceImportFlag

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.

export_reference

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

export_reference_w

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

import_reference

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

import_reference_w

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