Data Processing of Loaded Measurements

enum fluxEngine_C_v1_MeasurementProcessingContextFlag

Flags that influence measurement processing context creation.

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

Values:

enumerator fluxEngine_C_v1_MeasurementProcessingContextFlag_VariableSpatialSize

Variable spatial size.

When creating a processing context from a measurement that contains something with spatial dimensions (a HSI cube, an image, etc.), this will indicate that the context should accept inputs of sizes that may differ from the measurement that was used to create the context. This is useful if the measurement is only there to provide the same structure (type of measurement, scalar data type, references), but that differently-sized measurements should be accepted for data processing with this context.

Note that the size of the measurement will be used as the maximum size that may be specified, so it is up to the user to create the context from the largest possible measurement.

This is in contrast to the default which assumes that the inputs of the processing context will always have the exact same (fixed) size as the measurement.

enumerator fluxEngine_C_v1_MeasurementProcessingContextFlag_IgnoreReferences

Ignore references.

Ignore any white and/or dark references when creating the processing context. This is only relevant if the value type of the measurement is not fluxEngine_C_v1_ValueType_Intensity, as references will be ignored for all other value types anyway.

int fluxEngine_C_v1_ProcessingContext_create_measurement(fluxEngine_C_v1_MeasurementList const *measurement_list, int index, fluxEngine_C_v1_Model *model, uint64_t flags, fluxEngine_C_v1_ProcessingContext **context, fluxEngine_C_v1_Error **error)

Create a processing context from a measurement.

This will create a processing context from a measurement so that the measurement (and other measurements of the same structure) can be processed with a given model.

This is useful if the user wants to load a measurement from disk, and then immediately process the data. The following example shows how this may be used to process data:

int rc = -1;
fluxEngine_C_v1_Error* error = NULL;
fluxEngine_C_v1_MeasurementList* measurement_list = NULL;
fluxEngine_C_v1_ProcessingContext* context = NULL;
rc = fluxEngine_C_v1_MeasurementList_load(handle, format, file_name,
         &measurement_list, &error);
if (rc != 0) {
    handle_error(error);
    return;
}
rc = fluxEngine_C_v1_ProcessingContext_create_measurement(measurement_list, 0,
         model, 0, &context, &error);
if (rc != 0) {
    fluxEngine_C_v1_MeasurementList_free(measurement_list);
    handle_error(error);
    return;
}
rc = fluxEngine_C_v1_ProcessingContext_set_source_data_measurement(context,
         measurement_list, 0, &error);
if (rc != 0) {
    fluxEngine_C_v1_ProcessingContext_destroy(context);
    fluxEngine_C_v1_MeasurementList_free(measurement_list);
    handle_error(error);
    return;
}
rc = fluxEngine_C_v1_ProcessingContext_process_next(context, &error);
if (rc != 0) {
    fluxEngine_C_v1_ProcessingContext_destroy(context);
    fluxEngine_C_v1_MeasurementList_free(measurement_list);
    handle_error(error);
    return;
}

After this code the user may extract the data from the output sinks in the model via the fluxEngine_C_v1_ProcessingContext_get_output_sink_data() method.

Note that if the measurement is a HSI cube, the context created by this function will be equivalent to a context created by the fluxEngine_C_v1_ProcessingContext_create_hsi_cube() function, if the structure of the measurement had been specified manually. For this reason the user my also use the fluxEngine_ProcessingContext_set_source_data_hsi_cube() and fluxEngine_ProcessingContext_set_source_data_hsi_cube_ex() functions to set the source data for a processing context created by this method, not just the fluxEngine_C_v1_ProcessingContext_set_source_data_measurement() 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
fluxEngine_C_v1_ErrorCode_LicenseDongleRemoved
fluxEngine_C_v1_ErrorCode_LicenseDeviceNotConnected
fluxEngine_C_v1_ErrorCode_ProcessingSetupError
fluxEngine_C_v1_ErrorCode_MeasurementProcessingTypeError
fluxEngine_C_v1_ErrorCode_MeasurementProcessingMutuallyIncompatible
fluxEngine_C_v1_ErrorCode_MeasurementProcessingIncompatibleWithFixedSize

Parameters

measurement_list – The measurement list
index – Indicates which measurement in the list should be used to initialize the processing context. If -1 is specified it will be assumed that the context should be capable of processing all measurements in the list, and an error will occur if the list contains mutually incompatible measurements. The first measurement in the list is at index 0.
model – The model to process the data with
processing_queue_set – The processing queue set to use
flags – Flags that influence the context creation. This may be 0, or an arbitrary bitwise or of flags in the fluxEngine_C_v1_MeasurementProcessingContextFlag enumeration.
context – [out] The preview processing context
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

int fluxEngine_C_v1_ProcessingContext_set_source_data_measurement(fluxEngine_C_v1_ProcessingContext *context, fluxEngine_C_v1_MeasurementList const *measurement_list, int index, fluxEngine_C_v1_Error **error)

Set processing context source data from a specific measurement.

Sets the source data of a processing context from a given measurement.

This method will typically be called on processing contexts that were created with the fluxEngine_C_v1_ProcessingContext_create_measurement() function, but it is possible to use it with contexts created via the fluxEngine_C_v1_ProcessingContext_create_hsi_cube() if the measurement is a HSI cube and has the correct structure (same scalar type, same wavelengths, same value type). Note that since all HSI cube measurements are stored in BIP storage order in fluxEngine (even if they were stored in another storage order on disk before they were loaded), contexts created for other storage orders will not be compatible with this method. In that case the user must provide the cube data manually via the fluxEngine_ProcessingContext_set_source_data_hsi_cube() or fluxEngine_ProcessingContext_set_source_data_hsi_cube_ex() functions (and transpose it outside of fluxEngine beforehand).

Object lifetime note: it is safe to free the measurement list after calling this method, even if processing has not started yet. The data of the measurement will remain in memory (though no copy will be created) until any function that sets the source data of the processing context is called again successfully, fluxEngine_C_v1_ProcessingContext_reset_state() is called, or the processing context is destroyed.

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
fluxEngine_C_v1_ErrorCode_LicenseDongleRemoved
fluxEngine_C_v1_ErrorCode_LicenseDeviceNotConnected
fluxEngine_C_v1_ErrorCode_ProcessingContextTypeMismatch
fluxEngine_C_v1_ErrorCode_ProcessingContextNoLongerValid
fluxEngine_C_v1_ErrorCode_InputScalarTypeError
fluxEngine_C_v1_ErrorCode_InputDimensionError