Cuvis C++ API

class General

Public Static Functions

static void set_log_level(int_t lvl)

Set the internal log level.

Log output will be redirected to cout

If this function is not called, a failback logger is used, with loglevel “warning” The failback logger is de-activated, when this function is called or when a callback is registered for the log messages. However, when this function is called, messages are logged to console, even when a callaback is registered. debug = 4, info = 3, warning = 2, error = 1, fatal = 0

Parameters:

level – [in] the log level to be set

static void set_exception_locale(std::string const &locale = "")

static void register_log_callback(std::function<void(char const*, loglevel_t)> callback, int_t min_lvl)

Register an additional logger.

Only one classic callback will be set, multiple calls will overwrite the previous callback. The callback’s message argument pointer is only valid during the runtime of the callback. The “classic” logger will output original messages, instead of it’s respective translations. For localized (translated) messages,

See also

cuvis_reset_log_callback_localized.

Note

The classical logger and localized logger can be used simultaneously.

Parameters:

• i_callback – [in] the function callback

• i_min_level – [in] the minimum level of the callback

static void reset_log_callback()

Unregister the additional logger.

This will not clear the localized logger

static void register_log_callback_localized(std::function<void(wchar_t const*, loglevel_t)> callback, int_t min_lvl, std::string const &loc_id)

Register an additional logger with localized language.

Only one callback will be set, multiple calls will overwrite the previous callback. The callback’s message argument pointer is only valid during the runtime of the callback.

Note

The classical logger and localized logger can be used simultaneously.

Parameters:

• i_callback_localized – [in] the function callback

• i_min_level – [in] the minimum level of the callback

• i_locale_id – [in] set the locale id, e.g. “de-DE.UTF8” for german. See the “locale” directory for available translations.

static void reset_log_callback_localized()

Unregister the additional localized logger.

This will not clear the classic logger

static std::string version()

Get the SDK version.

Parameters:

o_pVersion – [out] The output version string. The provided array must have the length of CUVIS_MAXBUF

static void init(std::string const &settings_path, int global_loglevel = 4)

The init function set the settings path.

Parameters:

• i_settings_path – [in] The path to the settings directory.

• i_global_loglevel – [in] The log level that will be used for the backend logging system

static void shutdown()

Function for shutting down Cuvis safely.

Gently stops all threads.

static int_t register_event_callback(cpp_event_callback_t callback, int_t i_type)

static void unregister_event_callback(int_t i_handler_id)

Unregisters an event handler.

Supply a valid handler id to specific the correct callback which is going to be unregistered

class Calibration

central calibration Class

Public Functions

Calibration(std::filesystem::path const &path)

Create a calibration from factory path.

The calibration is created from a factory path, containing the license and calibration file “init.daq” as well as further calibration files (e.g. SpRad.cu3).

The calibration is lazy-loading, i.e. the AcquisitionContext and the ProcessingContext will only be initialized, when explicitly called.

Note

do not load multiple calibration instances of the same camera

Parameters:

path – [in] The path to the factory directory

Calibration(SessionFile const &session)

Create a calibration from session file.

Create a calibration from an existion session file.

The calibration is lazy-loading, i.e. the AcquisitionContext and the ProcessingContext will only be initialized, when explicitly called.

When you create a processing context from the calibration cerated with this function, you won’t have the references from the session file set. Use cuvis_proc_cont_create_from_session_file to load a processing context where the referenecs are taken from the session file.

Note

do not load multiple calibration instances of the same camera

Parameters:

session – [in] The session file

std::vector<capabilities_t> get_capabilities(CUVIS_OPERATION_MODE mode) const

get calibration capabilities

Parameters:

mode – Operation mode of the camera see also cuvis_operation_mode_t

CalibrationInfo get_info() const

get calibration infos

std::string get_id() const

get the calibration id

class Measurement

central measurement class

Public Types

using image_variant_t = std::variant<image_t<std::uint8_t>, image_t<std::uint16_t>, image_t<std::uint32_t>, image_t<float>>

using gps_data_t = std::map<std::string, cuvis_gps_t>

using string_data_t = std::map<std::string, std::string>

using image_data_t = std::map<std::string, image_variant_t>

using sensor_info_data_t = std::map<std::string, SensorInfoData>

Public Functions

Measurement &operator=(Measurement const &measurement) = default

Measurement(Measurement &&measurement) = default

Measurement(Measurement const &source)

create a deep copy of a measurement

All operations on a measurement are performed on the same object. If different processing needs to be perfomed on a measurement It should be deep-copied. The copied meausrement’s name will be changed to end with “_copy”

Parameters:

• i_mesu – [in] The measurement copy source.

• o_pMesu – [out] The copy will be linked to the handle given.

Measurement(std::filesystem::path const &path)

Load a measurement from disk.

The measurement is a cu3 file - and if fragmented some additional tiff files with a postfix, e.g. _cube.tiff To load the file, all fragmented parts must be in the same directory. Fragmented files must not be renamed.

Parameters:

• i_path – [in] the file path of the measurement

• o_pMesu – [out] the handle of the measurement.

Returns:

status_ok, if the measurement could be loaded.

std::vector<capabilities_t> get_capabilities() const

Get the capabilites of the measurement which were present in the calibration during capture.

This doesn’t indicate which capabilities are currently available for the measurement.

MeasurementMetaData const *get_meta() const

Get the metadata of the measurement.

The meta-data from the measurement contains information about the measurement when it was recorded: when and how. Meta-Data do not contain the actual recorded data.

sensor_info_data_t const *get_sensor_info() const

Get image info data from measurement.

Return image data from a measurement.

inline gps_data_t const *get_gps() const

Get GPS data from measurement.

inline image_data_t const *get_imdata() const

Get image data from measurement.

Return image data from measurement.

inline string_data_t const *get_strdata() const

Get string data from measurement.

image_t<std::uint8_t> const *get_thumbnail() const

Get thumbnail / preview image of measurement.

std::string get_calib_id() const

get calibration id of this measurement

void save(SaveArgs const &args)

Save measurement.

Save the measurement with given arguments

Parameters:

args – The Save Arguments to use for saving the measurement. See also SaveArgs

void set_name(std::string const &name)

Set name of measurement.

Parameters:

name – String to use as name of the measuremen

void set_comment(std::string const &comment)

set comment of measurement

Parameters:

comment – String to use as comment for the measurement

void clear_cube()

clears the cube from the measurement

Clears the proceessing result, i. e. the cube, from the measurement. This returns the measurement the state before applying the processing. This can be usefull for reduced data usage.

void clear_implicit_reference(reference_type_t type)

Clear the implicit reference measurement.

Implict measurements are created, when a measurement is processed with a processing context, where explicit references are set. Then, these references are remebemred by the measurement. When changing the processing context, the references are implicitly available, still. Clearing them may be interesing if the references set are wrong/invalid or if disk space is a concearn.

Parameters:

type – Type of reference to clear

void refresh()

Resynchronize the Measurement with the SDK data.

usally this does not have to be called manually, but is rather called internally by any operation that may result in invalidated (meta-)data

Friends

friend class ProcessingContext

friend class Exporter

friend class AsyncMesu

friend class Viewer

friend class SessionFile

friend class AcquisitionContext

friend class Worker

class SessionFile

Public Functions

SessionFile(std::filesystem::path const &path)

std::optional<Measurement> get_mesu(int_t frameNo, cuvis_session_item_type_t type = cuvis_session_item_type_t::session_item_type_frames) const

std::optional<Measurement> get_ref(int_t refNo, cuvis_reference_type_t type) const

common_image_t<std::uint8_t> get_thumbnail() const

int_t get_size(cuvis_session_item_type_t type = cuvis_session_item_type_t::session_item_type_frames) const

get size of the SessionFile

double get_fps() const

get the frame rate of this session

std::string get_hash() const

CUVIS_OPERATION_MODE get_operation_mode() const

get operation mode of the session

class ProcessingContext

Public Functions

ProcessingContext(Calibration const &calib)

ProcessingContext(Measurement const &mesu)

ProcessingContext(SessionFile const &session)

Measurement &apply(Measurement &mesu) const

bool calc_distance(double distMM)

void set_reference(Measurement const &mesu, reference_type_t type)

Set the reference for processing context.

Parameters:

• mesu – measurement The measurement to be used as explicit reference

• type – Type of reference to set

void clear_reference(reference_type_t type)

Clear a reference measurement.

Parameters:

type – Type of reference to clear

void set_processingArgs(ProcessingArgs const &procArgs)

set the processing arguments for the processing context

Parameters:

procArgs – arguments to set

std::optional<Measurement> get_reference(reference_type_t type) const

get a specific reference from the processing context

The processing context can hold explicit references (e.g. a dark), see ProcessingArgs.set_reference . These reference can be obtained by this functions

ProcessingArgs const &get_processingArgs() const

get the arguments of the processing context

bool is_capable(Measurement const &mesu, ProcessingArgs const &procArgs) const

Check if a processing mode is possible for a measurement.

Depending on the measurement, it’s intrinsic references, the processing context’s explicit references and the internal camera calibration itself the availability of a mode varies.

Use this function, to check whether a specific mode is explicitly possible for a measurement.

bool has_reference(reference_type_t type) const

Check if an explicit reference was set.

Parameters:

type – reference type to check for

std::string get_calib_id() const

get the calibration id of the procession context

class AcquisitionContext

Public Types

using mesu_callback_t = std::function<void(Measurement)>

using component_state_t = std::pair<std::string, bool>

using state_callback_t = std::function<void(hardware_state_t, std::map<int_t, component_state_info_t>)>

Public Functions

AcquisitionContext(Calibration const &calib)

AcquisitionContext(SessionFile const &sess, bool simulate = false)

~AcquisitionContext()

AsyncMesu capture()

void capture_queue()

hardware_state_t get_state() const

std::string get_component_pixel_format(int id) const

Async set_component_pixel_format(int id, std::string format)

std::vector<std::string> get_component_available_pixel_formats(int_t id) const

std::optional<Measurement> get_next_measurement(std::chrono::milliseconds timeout_ms = std::chrono::milliseconds(0)) const

SessionInfo get_session_info() const

int_t get_component_count() const

CUVIS_COMPONENT_INFO get_component_info(int_t id) const

void set_session_info(SessionInfo session)

void set_queue_size(int_t size)

bool has_next_measurement() const

bool is_ready() const

void register_state_change_callback(state_callback_t callback, bool output_initial_state = true)

void reset_state_change_callback()

inline double get_fps() const

inline double get_integration_time() const

inline bool get_auto_exp() const

inline double get_auto_exp_comp() const

inline bool get_binning() const

inline operation_mode_t get_operation_mode() const

inline int get_average() const

inline int get_bandwidth() const

inline int get_queue_size() const

inline int get_queue_used() const

inline Async set_fps(double value) const

inline Async set_integration_time(double value) const

inline Async set_auto_exp(bool value) const

inline Async set_auto_exp_comp(double value) const

inline Async set_binning(bool value) const

inline Async set_operation_mode(operation_mode_t value) const

inline Async set_average(int value) const

inline Async set_continuous(int value) const

inline int get_component_online(size_t id) const

inline double get_component_gain(size_t id) const

inline double get_component_integration_time_factor(size_t id) const

inline int get_bandwidth(size_t id) const

inline size_t get_driver_queue_size(size_t id) const

inline size_t get_driver_queue_used(size_t id) const

inline size_t get_hardware_queue_size(size_t id) const

inline size_t get_hardware_queue_used(size_t id) const

inline double get_temperature(size_t id) const

inline Async set_component_gain(size_t id, double value) const

inline Async set_component_integration_time_factor(size_t id, double value) const

CUVIS_ACQ_CONT get_handle() const

struct component_state_info_t

Public Members

std::string display_name

bool is_online

class Exporter

Subclassed by cuvis::CubeExporter, cuvis::EnviExporter, cuvis::TiffExporter, cuvis::ViewExporter

Public Types

using general_export_settings_t = cuvis_export_general_settings_t

Public Functions

Measurement const &apply(Measurement const &mesu) const

size_t get_queue_used() const

void flush()

class Async

Public Functions

async_result_t get(std::chrono::milliseconds waittime = std::chrono::milliseconds(0))

class AsyncMesu

Public Functions

std::pair<async_result_t, std::optional<Measurement>> get(std::chrono::milliseconds waittime = std::chrono::milliseconds(0))

class Worker

Public Types

using worker_callback_t = std::function<void(worker_return_t)>

Public Functions

Worker(WorkerArgs const &args)

void set_acq_cont(AcquisitionContext const *acqCont)

void set_proc_cont(ProcessingContext const *procCont)

void set_exporter(Exporter const *exporter)

void set_viewer(Viewer const *viewer)

void ingest_measurement(Measurement const *measurement)

void ingest_session_file(SessionFile const *session, std::string frame_selection)

double query_session_progress()

bool get_can_drop_results()

bool get_can_skip_measurements()

bool get_can_skip_supplementary()

bool has_next_result() const

worker_return_t get_next_result(std::chrono::milliseconds timeout) const

size_t get_queue_used() const

size_t get_input_queue_limit() const

size_t get_mandatory_queue_limit() const

size_t get_supplementary_queue_limit() const

size_t get_output_queue_limit() const

void start_processing()

void stop_processing()

void drop_all_queued()

bool is_processing_mandatory() const

bool is_processing() const

int32_t get_threads_busy() const

worker_state_t get_state() const

void register_worker_callback(worker_callback_t callback, unsigned concurrency = 1)

void reset_worker_callback()

struct worker_return_t

Public Members

std::optional<Measurement> mesu

std::optional<Viewer::view_data_t> view

std::exception_ptr exception

struct worker_state_t

Public Members

size_t measurementsInQueue

size_t sessionFilesInQueue

size_t framesInQueue

size_t measurementsBeingProcessed

size_t resultsInQueue

bool hasAcquisitionContext

bool isProcessing