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.

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