Calibration Information

CalibrationInfo

class CalibrationInfo

Calibration Information.

This class contains calibration information that influences how data is processed. Some fluxEngine filters that process data may use information such as the angle of the instrument to perform more accurate calculations.

There are two types of information stored here: simple quantities that consist of a value and a unit, as well as more complex quantities. All simple quantities may be set by a common set of getter and setter methods, while the more complex pieces of information have specific methods of their own.

For the available simple quantities take a look at the CalibrationSettingType enumeration.

All fluxEngine filters will have a default behavior if a certain piece of information is not set. For example, the angle of the instrument is assumed to be perpendicular to the sample if nothing else has been set.

Units are treated as strings in this API to allow for future extensibility. The following units are currently supported:

  • Unitless: "" (empty string)

  • Kilometers: "Kilometers", "km"

  • Meters: "Meters", "m"

  • Centimeters: "Centimeters", "cm"

  • Millimeters: "Millimeters", "mm"

  • Micrometers: "Micrometers", "µm" (U+00B5), "μm" (U+03BC)

  • Nanometers: "Nanometers", "nm"

  • Angstroms: "Angstroms", "Angstrom", "Å" (U+212B), "Å" (U+00C5)

  • Picometers: "Picometers", "pm"

  • Miles (imperial, 5280 feet): "Miles", "mi"

  • Yards (imperial, 3 feet): "Yards", "yd"

  • Feet (imperial, 12 iches): "Feet", "ft"

  • Inches (imperial, 2.54 cm): "Inches", "in"

  • Thou (imperial, 1/1000 inch): "Thou", "th"

  • Degrees (Angle): "deg"

  • Radians (Angle): "rad"

Please note that units are case sensitive, because SI prefixes are case sensitive!

Reminder: all strings in fluxEngine are encoded as UTF-8.

This structure has value semantics.

Public Functions

inline CalibrationInfo()

Default constructor.

If an error occurs, an exception will be thrown. The following exceptions may occur:

  • std::bad_alloc

  • std::invalid_argument

  • Error

inline CalibrationInfo(CalibrationInfo const &other)

Copy constructor.

If an error occurs, an exception will be thrown. The following exceptions may occur:

  • std::bad_alloc

  • std::invalid_argument

  • Error

Parameters:

other – The object to copy

inline CalibrationInfo(CalibrationInfo &&other) noexcept

Move constructor.

Parameters:

other – The object to move

inline CalibrationInfo &operator=(CalibrationInfo const &other)

Copy assignment operator.

If an error occurs, an exception will be thrown. The following exceptions may occur:

  • std::bad_alloc

  • std::invalid_argument

  • Error

Parameters:

other – The object to copy

Returns:

A reference to *this

inline CalibrationInfo &operator=(CalibrationInfo &&other) noexcept

Move assignment operator.

Parameters:

other – The object to move

Returns:

A reference to *this

inline ~CalibrationInfo() noexcept

Destructor.

inline void setSetting(CalibrationSettingType type, double value, std::string const &unit)

Set a simple calibration setting.

If an error occurs, an exception will be thrown. The following exceptions may occur:

  • std::bad_alloc

  • std::invalid_argument

  • Error

Parameters:
  • type – The setting type

  • value – The value of the setting

  • unit – The unit of the setting. For a list of units, please see the class documentation of CalibrationInfo. This unit must be of the right type (length unit, angle unit, etc.) for the given setting.

inline void clearSetting(CalibrationSettingType type)

Clear a simple calibration setting.

This will remove the setting from the calibration information structure, if present. If the setting was not present, this method will have no effect.

If an error occurs, an exception will be thrown. The following exceptions may occur:

  • std::bad_alloc

  • std::invalid_argument

  • Error

Parameters:

type – The setting type

inline bool isSettingPresent(CalibrationSettingType type) const

Check whether a simple calibration setting is present.

This will check whether a simple calibration setting is present in the given calibration information structure.

If an error occurs, an exception will be thrown. The following exceptions may occur:

  • std::bad_alloc

  • std::invalid_argument

  • Error

Parameters:

type – The setting type

Returns:

Whether that setting is present in the calibration information structure

inline std::string getSettingUnit(CalibrationSettingType type) const

Get the unit of the stored calibration setting.

If an error occurs, an exception will be thrown. The following exceptions may occur:

  • std::bad_alloc

  • std::invalid_argument

  • Error

Parameters:

type – The setting type

Returns:

The unit of the calibration setting. The unit string will be one of the strings documented in the class documentation of CalibrationInfo. For units that have multiple representations the first abbreviated representation will be returned. For example, micrometers will return a string containing 2 characters, the first being the unicode symbol for micro, U+00B5, the second being ‘m’. Since all strings in fluxEngine are considered to be UTF-8 that example will be 3 bytes long, as U+00B5 will be encoded as 0xC2 0xB5 in UTF-8.

inline double getSettingValue(CalibrationSettingType type, std::string const &unit) const

Get the value of the stored calibration setting.

The value will be converted to the specified unit automatically.

If an error occurs, an exception will be thrown. The following exceptions may occur:

  • std::bad_alloc

  • std::invalid_argument

  • Error

Parameters:
  • type – The setting type

  • unit – The unit to convert the value into. This must be a compatible unit (e.g. a length unit for lengths). See the class documentation of CalibrationInfo for details on how to specify units.

Returns:

The value of the setting, converted to the specified unit.

inline void setWhiteReferenceReflectivity(std::vector<double> const &wavelengths, std::vector<double> const &reflectivities, std::string const &wavelengthUnit)

Set the white reference reflectivity.

This special setting may be used to supply a reflectance curve for the white reference that is used in the measurement setup. The white reference measurement will automatically be corrected by fluxEngine by this reflectance curve to more closely be able to calculate the true reflectance of the sample.

If a previous white reference reflectivity curve was present in the calibration information structure, it will be replaced.

The number of elements in the wavelengths and reflectivities vectors must be the same, otherwise an exception will be thrown.

If an error occurs, an exception will be thrown. The following exceptions may occur:

  • std::bad_alloc

  • std::invalid_argument

  • Error

Parameters:
  • wavelengths – A vector of wavelengths (x labels) of the curve

  • reflectivities – The reflectance values of the white reference, corresponding to the supplied wavelengths. The values must fall between 0.0 (no reflectivity) and 1.0 (full reflectivity). A good white reference typically has a relatively flat reflectivity that is larger than 0.9 for all relevant wavelengths.

  • wavelengthUnit – The unit of the wavelengths, see the class documentation of CalibrationInfo for a list of possible units. Typically this will be "nm" to indicate that the curve has been specified in nanometers.

inline void clearWhiteReferenceReflectivity()

Clear the white reference reflectivity curve.

Removes any existing white reference reflectivity curve in the calibration information structure. If no such curve was present this method has no effect.

If an error occurs, an exception will be thrown. The following exceptions may occur:

  • std::bad_alloc

  • std::invalid_argument

  • Error

inline bool isWhiteReferenceReflectivityPresent()

Determine whether a white reference reflectivity curve was stored in the calibration information.

If an error occurs, an exception will be thrown. The following exceptions may occur:

  • std::bad_alloc

  • std::invalid_argument

  • Error

Returns:

Whether a white reference reflectivity curve was stored

inline WhiteReferenceReflectivity getWhiteReferenceReflectivity()

Get the white reference reflectivity stored in the calibration inforamtion.

This will retrieve the white reference reflectivity curve stored in the calibration information. If no such curve has been stored, an error will be thrown.

If an error occurs, an exception will be thrown. The following exceptions may occur:

  • std::bad_alloc

  • std::invalid_argument

  • Error

Returns:

The stored white reference reflectivity curbe

inline explicit CalibrationInfo(fluxEngine_C_v1_CalibrationInfo *wrapped)

Wrapping constructor.

This constructor wraps the underlying C handle and takes ownership of it. This means that once this object is destroyed the C handle will be freed.

Users will typically not need to call this constructor, as the C++ wrappers for other objects will return this structure directly.

Parameters:

wrapped – The C handle to wrap

struct WhiteReferenceReflectivity

Stored white reference reflectivity.

This structure is returned by CalibrationInfo::getWhiteReferenceReflectivity() and contains the information about the white reference reflectivity curve.

Public Members

std::vector<double> wavelengths

The wavelengths.

std::vector<double> reflectivities

The associated reflectivity values.

This will have the same number of elements as the wavelengths.

std::string wavelengthUnit

The wavelength unit.

See the class documentation of CalibrationInfo for a list of units.

CalibrationSettingType

enum class fluxEngine::CalibrationSettingType

Simple calibration setting type.

This enumeration lists the simple settings (that consist of a value and a unit) that describe a given measurement setup.

See also

CalibrationInfo

Values:

enumerator PixelSizeX

The pixel size in x direction.

How large is a pixel in x direction when looking at the measurement target. (This is not the size of the pixel in the sensor chip!) The quantity associated with this must have a length unit (e.g. 3 mm). This applies equally to line cameras and imager cameras; in the case of imager cameras this will also be used for the size in y direction.

Note that this may be quite large; when processing satellite images this may be of the order of kilometers.

This quantity only makes sense if the target that is looked at is relatively flat.

enumerator InstrumentBaseDistance

The distance of the instrument to the sample.

The quantity associated with this must have a length unit (e.g. 10 cm).

This quantity only makes sense if the target that is looked at is relatively flat.

enumerator InstrumentAngleX

The angle of the instrument in the y-z plane.

An angle of 0 indicates perpendicularity to the measurement sample, any deviation indicates that the instrument has been rotated relative to the sample along an axis aligned with the x direction.

ComparisonResult

enum class fluxEngine::ComparisonResult

Comparison result of two numeric structures.

This result is returned by functions that compare structures (such as CalibrationInfo) that contain floating point values. Since a direct comparison of two floating point values will likely not yield exactly the same values, this enumeration exists to indicate the state when values are so similar that they are considered equivalent.

Values:

enumerator Identical

The structures are identical.

enumerator Equivalent

The structures are equivalent.

enumerator Different

The structures are different.

compare

inline ComparisonResult fluxEngine::compare(CalibrationInfo const &info1, CalibrationInfo const &info2, double relativePrecision = 1e-7)

Compare two CalibrationInfo structures.

This may be used to determine if both structures describe the same data. Since calibration information is provided in the form of floating point data, this comparison routine will also provide feedback in case both structures are not exactly (bitwise) identical, but are close enough in relative precision that they should be considerd equivalent. (The threshold for this may be specified by the user.)

Parameters:
  • info1 – The first structure

  • info2 – The second structure

  • relativePrecision – The relative precision to which to compare various values to. Specify 0 here to always force absolute comparisons. A good default is 1e-7.

Returns:

The comparison result of both structures