Data Processing of Loaded Measurements

MeasurementProcessingContextFlag

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 fluxEngine_C_v1_ValueType_Intensity, fluxEngine_C_v1_ValueType_RelativeRadiance, or fluxEngine_C_v1_ValueType_Radiance, as references will be ignored for all other value types anyway.

ProcessingContext_create_measurement

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

  • 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

ProcessingContext_create_measurement_pqs

int fluxEngine_C_v1_ProcessingContext_create_measurement_pqs(fluxEngine_C_v1_MeasurementList const *measurement_list, int index, fluxEngine_C_v1_Model *model, fluxEngine_C_v1_ProcessingQueueSet *processing_queue_set, uint64_t flags, fluxEngine_C_v1_ProcessingContext **context, fluxEngine_C_v1_Error **error)

Create a processing context from a measurement.

This function is identical to fluxEngine_C_v1_ProcessingContext_create_measurement(), but allows the user to supply a processing queue set. If NULL is specified for processing_queue_set the default processing queue set of the handle will be used.

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

ProcessingContext_set_source_data_measurement

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

Parameters:
  • context – The processing context to set the source data for

  • measurement_list – The measurement list

  • index – Indicates which measurement in the list should be used. The first measurement is at index 0.

  • 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