Static class granting access to SDK wide configuration and utility functions. More...

#include <Sdk.h>

Collaboration diagram for optris::Sdk:

Public Types
using	LogCallback = void(OTC_SDK_C_CALL )(int verbosityLevel, const char message)
	Callback function type for receiving SDK log messages.

Public Member Functions
	Sdk ()=delete
	No constructor.

Static Public Member Functions
static OTC_SDK_API void	init (Verbosity logScreen, Verbosity logFile, std::string logFilenamePrefix="", std::string customDataDirectory="")
	Initializes the SDK.

static OTC_SDK_API void	configureLogger (Verbosity logScreen, Verbosity logFile, std::string logFilenamePrefix="")
	Configures the SDK internal logger.

static OTC_SDK_API void	setLogCallback (LogCallback callback, bool exclusive=false)
	Sets a callback that receives SDK log messages.

static OTC_SDK_API void	setCustomDataDirectory (const std::string &customDataDirectory)
	Sets a custom data directory for the SDK to use.

static OTC_SDK_API void	clearCustomDataDirectory ()
	Clears a previously set custom data directory for the SDK.

static OTC_SDK_API bool	setCalibrationFileSources (CalibrationFileSource first, CalibrationFileSource second, CalibrationFileSource third)
	Sets the priority of the calibration file sources.

static OTC_SDK_API bool	setCalibrationFileSources (const std::vector< CalibrationFileSource > &sources)
	Sets the priority of the calibration file sources from an ordered list.

static OTC_SDK_API void	setCalibrationFileSourceDirectory (const std::string &sourceDirectory)
	Sets the source directory from which calibration files can be copied.

static OTC_SDK_API void	clearCalibrationFileSourceDirectory ()
	Clears a previously set source directory for calibration files.

static OTC_SDK_API void	addCalibrationFallbackServer (const std::string &url)
	Appends a fallback server for internet calibration file downloads.

static OTC_SDK_API void	clearCalibrationFallbackServers ()
	Removes all fallback servers registered via Sdk::addCalibrationFallbackServer().

static OTC_SDK_API VersionInfo	getVersionInfo ()
	Returns an object holding version and build information about the SDK.

static OTC_SDK_API void	loadPalettes ()
	Loads palettes from the SDK and user palette directories.

static OTC_SDK_API void	loadPalettes (const std::string &directory)
	Loads palettes from a custom directory.

static OTC_SDK_API std::vector< std::string >	getPaletteNames ()
	Returns the names of all currently loaded palettes in sorted order.

static OTC_SDK_API std::vector< std::array< uint8_t, 3 > >	getPaletteColors (const std::string &name)
	Returns the 240 RGB color entries of the named palette.

static OTC_SDK_API void	registerPalette (const std::string &name, const std::vector< std::array< uint8_t, 3 > > &colors)
	Registers a palette at runtime without persisting it to disk.

static OTC_SDK_API void	savePalette (const std::string &name)
	Saves a registered palette as a CSV file in the user palette directory.

Detailed Description

Static class granting access to SDK wide configuration and utility functions.

Member Typedef Documentation

◆ LogCallback

using optris::Sdk::LogCallback = void(OTC_SDK_C_CALL*)(int verbosityLevel, const char* message)

Callback function type for receiving SDK log messages.

Parameters

verbosityLevel	0=Error, 1=Warning, 2=Info, 3=Debug, 4=Trace.
message	the log message text.

Member Function Documentation

◆ addCalibrationFallbackServer()

static OTC_SDK_API void optris::Sdk::addCalibrationFallbackServer ( const std::string & url )

static

Appends a fallback server for internet calibration file downloads.

The SDK always tries its built-in servers first (https://calibration.optris.com/api, then the mirror https://calibration.optris-ir.cn/api). Servers registered here are appended after the built-ins in registration order. At the start of each internet acquisition all configured servers are health-checked in parallel and the highest-priority reachable one is used; individual downloads fail over to the next server on errors, timeouts, or when a server does not have the requested file.

The URL must include the scheme and the full API base path, e.g. https://mirror.example.com/api — the SDK appends /healthz and /v1/calibration/... to it. Trailing slashes are stripped. The server must mirror the REST layout of the built-in servers, including the Digest: sha-256=... response header used for integrity verification. Only https:// URLs are accepted: the integrity digest travels in-band, so plaintext HTTP would offer no protection for the calibration data. Duplicates of the built-in servers or of already registered entries are ignored with a warning.

Note: The internet-access consent requested via ConnectionState::CaliAccessInternet covers all configured servers, including the built-in mirror and any servers registered here.

This method is thread-safe and takes effect at the next calibration acquisition. It may also be called from within the ConnectionState::CaliAccessInternet callback.

Parameters

[in] url base URL of the fallback server.

Exceptions

SDKException if the URL is empty, does not start with https://, contains whitespace or a query/fragment, or the fallback server limit (8) is reached.

◆ clearCalibrationFallbackServers()

static OTC_SDK_API void optris::Sdk::clearCalibrationFallbackServers ( )

static

Removes all fallback servers registered via Sdk::addCalibrationFallbackServer().

The built-in Optris servers are unaffected and always remain active. This method is thread-safe.

◆ clearCalibrationFileSourceDirectory()

static OTC_SDK_API void optris::Sdk::clearCalibrationFileSourceDirectory ( )

static

Clears a previously set source directory for calibration files.

When cleared, the SDK will skip the CalibrationFileSource::Filesystem option when acquiring calibration files.

◆ clearCustomDataDirectory()

static OTC_SDK_API void optris::Sdk::clearCustomDataDirectory ( )

static

Clears a previously set custom data directory for the SDK.

Once cleared the SDK reverts to the default user data directory:

Linux ~/.config/optris/
Windows <User AppData>/Roaming/Imager/

Exceptions

SDKException if there is an active device connection or if the default user data directory path could not be determined.

◆ configureLogger()

static OTC_SDK_API void optris::Sdk::configureLogger	(	Verbosity	logScreen,
		Verbosity	logFile,
		std::string	logFilenamePrefix = `""`
	)

static

Configures the SDK internal logger.

If you change the logFilenamePrefix from the one used in Sdk::init() or in a previous call to Sdk::configure(), the current log file will be closed and new one will be created.

Parameters

[in]	logScreen	defines the minimum verbosity level of log messages displayed on the standard output and error.
[in]	logFile	defines the minimum verbosity level of log messages out to the logfile.
[in]	logFilenamePrefix	for the log file `<logFilenamePrefix>_<YYYY_MM_DDThh-mm-ss>.log`. If empty, it defaults to "OtcSDK".

◆ getPaletteColors()

static OTC_SDK_API std::vector< std::array< uint8_t, 3 > > optris::Sdk::getPaletteColors ( const std::string & name )

static

Returns the 240 RGB color entries of the named palette.

Each entry is an array of three bytes: { R, G, B }.

Parameters

[in] name palette name (case-sensitive).

Returns: vector of 240 RGB triples.

Exceptions

SDKException if the palette is not found.

◆ getPaletteNames()

static OTC_SDK_API std::vector< std::string > optris::Sdk::getPaletteNames ( )

static

Returns the names of all currently loaded palettes in sorted order.

Returns: sorted list of palette name strings.

◆ getVersionInfo()

static OTC_SDK_API VersionInfo optris::Sdk::getVersionInfo ( )

static

Returns an object holding version and build information about the SDK.

Returns: object holding version and build information about the SDK.

◆ init()

static OTC_SDK_API void optris::Sdk::init	(	Verbosity	logScreen,
		Verbosity	logFile,
		std::string	logFilenamePrefix = `""`,
		std::string	customDataDirectory = `""`
	)

static

Initializes the SDK.

It sets the verbosity levels of the internal logger of the SDK, starts the EnumerationManager in a dedicated thread to monitor the availability of devices, and loads color palettes from the SDK, working, and user palette directories.

Parameters

[in]	logScreen	defines the minimum verbosity level of log messages displayed on the standard output and error.
[in]	logFile	defines the minimum verbosity level of log messages out to the logfile.
[in]	logFilenamePrefix	for the log file `<logFilenamePrefix>_<YYYY_MM_DDThh-mm-ss>.log`. If empty, it defaults to "OtcSDK".
[in]	customDataDirectory	for the SDK to use. An empty string will have no effect. The SDK requires read and write access to this directory. For detail on how specify it see Sdk::setCustomDataDirectory().

◆ loadPalettes() [1/2]

static OTC_SDK_API void optris::Sdk::loadPalettes ( )

static

Loads palettes from the SDK and user palette directories.

Scans the SDK data directory first, then the user data directory so that user-supplied palettes with the same name override the built-in ones. Missing directories are silently skipped.

This method is idempotent — calling it more than once reloads all palettes from disk, replacing any previously registered entries.

◆ loadPalettes() [2/2]

static OTC_SDK_API void optris::Sdk::loadPalettes ( const std::string & directory )

static

Loads palettes from a custom directory.

Adds or overwrites palette entries in the registry without clearing previously loaded palettes.

When specifying the directory path the following symbols/variables are supported:

~, %USERPROFILE% refer to ~/ on Linux and <User Home>/ on Windows.
%APPDATA% refers to ~/.config/ on Linux and <User AppData>/Roaming/ on Windows.

Relative paths are not supported. You can either use / as system independet directory separator or utilize system dependent ones like / for Linux and \ on Windows.

Parameters

[in] directory path to scan for .csv palette files.

Exceptions

SDKException if directory does not exist or is not a directory.

◆ registerPalette()

static OTC_SDK_API void optris::Sdk::registerPalette	(	const std::string &	name,
		const std::vector< std::array< uint8_t, 3 > > &	colors
	)

static

Registers a palette at runtime without persisting it to disk.

An existing palette with the same name is overwritten.

Parameters

[in]	name	unique palette name.
[in]	colors	exactly 240 RGB triples `{ R, G, B }`.

Exceptions

SDKException if colors does not contain exactly 240 entries.

◆ savePalette()

static OTC_SDK_API void optris::Sdk::savePalette ( const std::string & name )

static

Saves a registered palette as a CSV file in the user palette directory.

The output filename is <name>.csv. The user palette directory is created automatically if it does not exist.

Parameters

[in] name palette name to save (case-sensitive).

Exceptions

SDKException if the palette is not found or the file cannot be written.

◆ setCalibrationFileSourceDirectory()

static OTC_SDK_API void optris::Sdk::setCalibrationFileSourceDirectory ( const std::string & sourceDirectory )

static

Sets the source directory from which calibration files can be copied.

When specifying the directory path the following symbols/variables are supported:

~, %USERPROFILE% refer to ~/ on Linux and <User Home>/ on Windows.
%APPDATA% refers to ~/.config/ on Linux and <User AppData>/Roaming/ on Windows.

Relative paths are not supported. You can either use / as system independet directory separator or utilize system dependent ones like / for Linux and \ on Windows.

Parameters

[in] sourceDirectory from which calibration files can be copied. An empty string will have no effect.

Exceptions

SDKException if the given path does not exist or is not a directory.

◆ setCalibrationFileSources() [1/2]

static OTC_SDK_API bool optris::Sdk::setCalibrationFileSources	(	CalibrationFileSource	first,
		CalibrationFileSource	second,
		CalibrationFileSource	third
	)

static

Sets the priority of the calibration file sources.

The priority of the sources needs to be set prior to connecting to a device. If you want to use less than three potential calibration file source, set the one you do not require to Empty. The different sources have individual requirements for them to work:

Device. Not all types of Optris cameras have their calibration files stored on-device.
Filesystem. The source directory should be accessible and the SDK should have the rights to copy the calibration files from it to their target destination. The source directory needs to be specified via the Sdk::setCalibrationFileSourceDirectory() method.
Internet. Access to the internet is required.
User. The SDK asks the client for a source directory through the ConnectionState::CaliCopySourceDirectory callback (e.g. to show a file picker). Use this to make the manual prompt an explicit, independently ordered fallback.

Parameters

[in]	first	source with the highest priority.
[in]	second	source with a medium priority.
[in]	third	source with the lowest priority.

Returns: true, if priority was successfully set. False, otherwise.

◆ setCalibrationFileSources() [2/2]

static OTC_SDK_API bool optris::Sdk::setCalibrationFileSources ( const std::vector< CalibrationFileSource > & sources )

static

Sets the priority of the calibration file sources from an ordered list.

This is the flexible counterpart to the fixed-arity overload: it accepts any number of sources, in any order, allowing the CalibrationFileSource::User prompt to be placed independently of the other sources. CalibrationFileSource::Empty entries are ignored. The sources are tried from the front of the list to the back. See the three-parameter overload for the individual source requirements.

Parameters

[in] sources ordered list of calibration file sources to try, highest priority first.

Returns: true, if at least one non-Empty source was set. False otherwise (the previous configuration is then kept).

◆ setCustomDataDirectory()

static OTC_SDK_API void optris::Sdk::setCustomDataDirectory ( const std::string & customDataDirectory )

static

Sets a custom data directory for the SDK to use.

Attention: A custom data directory can only be set when there are no active device connections.

If the given directory does not exist, the SDK will try to create it (recursively).

When specifying the directory path the following symbols/variables are supported:

~, %USERPROFILE% refer to ~/ on Linux and <User Home>/ on Windows.
%APPDATA% refers to ~/.config/ on Linux and <User AppData>/Roaming/ on Windows.

Relative paths are not supported. You can either use / as system independet directory separator or utilize system dependent ones like / for Linux and \ on Windows.

Parameters

[in] customDataDirectory for the SDK to use. An empty string will have no effect. The SDK requires read and write permission to this directory.

Exceptions

SDKException

if

there is an active device connection.
the given path is not a directory.
the SDK can not access the directory
the SDK failed to create the directory.

◆ setLogCallback()

static OTC_SDK_API void optris::Sdk::setLogCallback	(	LogCallback	callback,
		bool	exclusive = `false`
	)

static

Sets a callback that receives SDK log messages.

Parameters

[in]	callback	function pointer to invoke on each log message, or nullptr to remove.
[in]	exclusive	when true, disables file and screen output while the callback is active.

The documentation for this class was generated from the following file:

Sdk.h

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Typedef Documentation

◆ LogCallback

Member Function Documentation

◆ addCalibrationFallbackServer()

◆ clearCalibrationFallbackServers()

◆ clearCalibrationFileSourceDirectory()

◆ clearCustomDataDirectory()

◆ configureLogger()

◆ getPaletteColors()

◆ getPaletteNames()

◆ getVersionInfo()

◆ init()

◆ loadPalettes() [1/2]

◆ loadPalettes() [2/2]

◆ registerPalette()

◆ savePalette()

◆ setCalibrationFileSourceDirectory()

◆ setCalibrationFileSources() [1/2]

◆ setCalibrationFileSources() [2/2]

◆ setCustomDataDirectory()

◆ setLogCallback()