Calibration Information

There are some key features of the details of the measurement setup used that may influence how specific calculations are to be performed. For example, when measuring in reflectance mode, the material used for the white reference may not be a perfect reflector of all light. It is possible to provide the reflectivity curve of that material to fluxEngine, so that the white reference calculation is more accurate.

Similarly the measurement geometry may have an influence on operations that require information about the precise angle the light takes relative to the surface of the material that is being measured.

These specific details of the measurement setup are grouped together in a data structure called calibration information. This is represented by the fluxEngine_C_v1_CalibrationInfo (C), CalibrationInfo (C++) and CalibrationInfo (Python) classes.

This structure may be obtained from measurements that have been loaded from disk; and it may be manually set when creating a measurement to store that information. Additionally it may be provided while creating a processing context for user-supplied data. Finally the user may apply such a structure to an instrument device that is connected to influence any future processing contexts that are created for that device.

This information is not required - if it is not provided all processing operations will use default values.

The list of properties described here are the currently available properties. This is

White reference reflectivity

The white reference reflectivity is used to indicate the actual reflectivity of the material used as the white reference in a given setup. It is always a single spectrum with a value type of reflectances. This material property influences how the white reference calculation is performed. The formula mentioned in the Referencing section of the Introduction will be modified in the following manner:

R = (I - D) / ((W - D) / R0)

where R0 is the white reference material reflectivity for each wavelength.

Since an entire spectrum needs to be provided, special accessor methods exist to provide this information to a calibration information structure:

• fluxEngine_C_v1_CalibrationInfo_set_white_reference_reflectivity() (C)

• fluxEngine_C_v1_CalibrationInfo_clear_white_reference_reflectivity() (C)

• fluxEngine_C_v1_CalibrationInfo_is_white_reference_reflectivity_present() (C)

• fluxEngine_C_v1_CalibrationInfo_get_white_reference_reflectivity() (C)

• CalibrationInfo::setWhiteReferenceReflectivity() (C++)

• CalibrationInfo::clearWhiteReferenceReflectivity() (C++)

• CalibrationInfo::isWhiteReferenceReflectivityPresent() (C++)

• CalibrationInfo::getWhiteReferenceReflectivity() (C++)

• CalibrationInfo.setWhiteReferenceReflectivity() (Python)

• CalibrationInfo.clearWhiteReferenceReflectivity() (Python)

• CalibrationInfo.isWhiteReferenceReflectivityPresent() (Python)

• CalibrationInfo.getWhiteReferenceReflectivity() (Python)

Numerical Properties

Several other properties just consist of a number and a single physical unit, such as mm (millimeters) for a length unit. Units are represented as strings in fluxEngine. The following units are currently supported:

Type	Description	Accepted String
N/A	Unitless (e.g. a single reflectance value between 0 and 1)	"" (empty string, R)
Length	Kilometers	"Kilometers"
		"km" (R)
	Meters	"Meters"
		"m" (R)
	Centimeters	"Centimeters"
		"cm" (R)
	Millimeters	"Millimeters"
		"mm" (R)
	Micrometers	"Micrometers"
		"µm" (using U+00B5, R)
		"µm" (using U+03BC)
	Nanometers	"Nanometers"
		"nm" (R)
	Angstroms	"Angstroms"
		"Angstrom"
		"Å" (using U+212B, R)
		"Å" (using U+00C5)
	Picometers	"Picometers"
		"pm" (R)
	Miles (imperial, 5280 feet)	"Miles"
		"mi" (R)
	Yards (imperial, 3 feet)	"Yards"
		"yd" (R)
	Feet (imperial, 12 inches)	"Feet"
		"ft" (R)
	Inches (imperial, 2.54 cm)	"Inches"
		"in" (R)
	Thou (imperial, 1/1000 inch)	"Thou"
		"th" (R)
Angle	Degrees (360° is a full circle)	"deg" (R)
	Radians (2π is a full circle)	"rad" (R)

All units with a note (R) are the canonical names returned when querying a given quantity, if that quantity has that unit.

Note

Unit names are case-sensitive.

The following generic accessor methods exist to manipulate quantities that consist of a number and a unit:

• fluxEngine_C_v1_CalibrationInfo_set_setting() (C)

• fluxEngine_C_v1_CalibrationInfo_clear_setting() (C)

• fluxEngine_C_v1_CalibrationInfo_is_setting_present() (C)

• fluxEngine_C_v1_CalibrationInfo_get_setting_unit() (C)

• fluxEngine_C_v1_CalibrationInfo_get_setting_value() (C)

• CalibrationInfo::setSetting() (C++)

• CalibrationInfo::clearSetting() (C++)

• CalibrationInfo::isSettingPresent() (C++)

• CalibrationInfo::getSettingUnit() (C++)

• CalibrationInfo::getSettingValue() (C++)

• CalibrationInfo.setSetting() (Python)

• CalibrationInfo.clearSetting() (Python)

• CalibrationInfo.isSettingPresent() (Python)

• CalibrationInfo.getSettingUnit() (Python)

• CalibrationInfo.getSettingValue() (Python)

Pixel Size (X)

The setting type for this setting is fluxEngine_C_v1_CalibrationSettingType_PixelSizeX (C), CalibrationSettingType::PixelSizeX (C++), CalibrationSettingType.PixelSizeX (Python). The unit must be a length unit.

This property indicates how wide a pixel is in x direction. For imager cameras this will also indicate the pixel height in y direction, as imagers are assumed to have square pixels.

The pixel width is not the actual width of the sensor, but rather the width of a pixel on surface that is being measured by the instrument.

This allows fluxEngine to determine how far away from the center position each pixel of a given frame is.

(This quantity does not apply to instruments that don’t measure an image, such as spectrometers.)

Instrument Base Distance

The setting type for this setting is fluxEngine_C_v1_CalibrationSettingType_InstrumentBaseDistance (C), CalibrationSettingType::InstrumentBaseDistance (C++), CalibrationSettingType.InstrumentBaseDistance (Python). The unit must be a length unit.

This property indicates how far away the instrument is relative to the surface that is being measured.

In conjunction with te pixel size (see the previous section) this allows fluxEngine to calculate the angle a pixel is at relative to the instrument.

Instrument Angle in Y-Z Plane

The setting type for this setting is fluxEngine_C_v1_CalibrationSettingType_InstrumentAngleX (C), CalibrationSettingType::InstrumentAngleX (C++), CalibrationSettingType.InstrumentAngleX (Python). The unit must be an angle unit.

The instrument may be placed at an angle in the Y-Z plane (The Z axis being perpendicular to the measurement surface), basically the instrument being rotated around the X axis. This is often used to avoid issues with specular reflection.

This quantity indivates the angle the instrument has. An angle of 0 indicates the instrument is perpendicular to the measured surface, directly facing it.

As this is mostly used with line cameras (such as hyperspectral push broom cameras) it does not make a difference if the angle is negative or positive at the moment. For this reason it is recommended to always specify a positive angle.