Cuvis C API

Handles

group Handles

The SDK is handle-based, i.e to access an internal data object you will require a handle.

The main concepts of the SDK which use handles are the Measurement, the Calibration, the Session File, the Acquisition Context, the Processing Context, the Viewer, the Export API and the Worker. On how to obtain a handle of the individual components of the SDK, see the respective Pages for the individual components.

For example, a handle wich represents a Measurement can be obtained by either loading (cuvis_measurement_load) or by recording (cuvis_acq_cont_capture or cuvis_acq_cont_get_next_measurement

) a measurement.

A measurement is equivalent to a data-cube and would be called a frame in a traditional Camera-Setup. The handle then refers to measurement in the SDK context.

Each handle should be freed after it is no longer needed. This can be done via the respective free function. Calling the free-function does not necessarily free up the used memory immediately, because there could be multiple handles referring to the same object.

Reserved Keys

group Reserved Keys

Defines

CUVIS_MESU_CUBE_KEY: name of the data field for the hyperspectral cube (in all modes except Preview)

CUVIS_MESU_PAN_KEY: name of the pan image (pixels registered to CUVIS_MESU_CUBE_KEY)

CUVIS_MESU_GPS_KEY: name of the GPS data field, if available

CUVIS_MESU_PREVIEW_KEY

name of the generate preview image, if available.

The preview will be generated by the cuvis_proc_cont_apply function

CUVIS_MESU_DARKREF_KEY

If this field is present, a dark was set while recording the measurement.

This is the dark that is implicitly loaded when a processing context is created with the current measurement and used, if a dark is needed (unless overwritten by cuvis_proc_cont_set_reference ) The reference file should be located in ../Calibration/<reference-name>.cu3 or the precise path defined by the string value of the data tag

CUVIS_MESU_WHITEREF_KEY

If this field is present, a white was set while recording the measurement.

This is the white that is implicitly loaded when a processing context is created with the current measurement and used, if a dark is needed (unless overwritten by cuvis_proc_cont_set_reference ) The reference file should be located in ../Calibration/<reference-name>.cu3 or the precise path defined by the string value of the data tag

CUVIS_MESU_WHITEDARKREF_KEY

If this field is present, a white’s dark was set while recording the measurement.

This is the white’ dark that is implicitly loaded when a processing context is created with the current measurement and used, if a dark is needed (unless overwritten by cuvis_proc_cont_set_reference ) The reference file should be located in ../Calibration/<reference-name>.cu3 or the precise path defined by the string value of the data tag

CUVIS_MESU_FLAG_OVERILLUMINATED_KEY: see CUVIS_MESU_FLAG_OVERILLUMINATED

CUVIS_MESU_FLAG_PAN_OVERILLUMINATED_KEY: see CUVIS_MESU_FLAG_OVERILLUMINATED

CUVIS_MESU_FLAG_POOR_REFERENCE_KEY: see CUVIS_MESU_FLAG_POOR_REFERENCE

CUVIS_MESU_FLAG_POOR_WHITE_BALANCING_KEY: see CUVIS_MESU_FLAG_POOR_WHITE_BALANCING

CUVIS_MESU_FLAG_DARK_INTTIME_KEY: see CUVIS_MESU_FLAG_DARK_INTTIME

CUVIS_MESU_FLAG_DARK_TEMP_KEY: see CUVIS_MESU_FLAG_DARK_TEMP

CUVIS_MESU_FLAG_WHITE_INTTIME_KEY: see CUVIS_MESU_FLAG_WHITE_INTTIME

CUVIS_MESU_FLAG_WHITE_TEMP_KEY: see CUVIS_MESU_FLAG_WHITE_TEMP

CUVIS_MESU_FLAG_WHITEDARK_INTTIME_KEY: see CUVIS_MESU_FLAG_WHITEDARK_INTTIME

CUVIS_MESU_FLAG_WHITEDARK_TEMP_KEY: see CUVIS_MESU_FLAG_WHITEDARK_TEMP

Calibration

group Calibration

Functions to interact with a calibration object of the SDK.

There are two ways to create a calibration object. One way is by loading it specifically from a factory directory (see cuvis_calib_create_from_path). The other one is by loading it from a session file. The Calibration object is needed to load other parts of the SDK like the Acquisition Context and the Processing Context.

Functions

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_calib_create_from_path (const CUVIS_CHAR *i_factoryDir, CUVIS_CALIB *o_pCalibration)

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:

i_factoryDir – [in] The path to the factory directory
o_pCalibration – [in] the handle of the calibration

Returns:

status_ok if the calibration could be loaded

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_calib_create_from_session_file (const CUVIS_SESSION_FILE i_sess, CUVIS_CALIB *o_pCalibration)

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:

i_sess – [in] The session file
o_pCalibration – [in] the handle of the calibration

Returns:

status_ok if the calibration could be loaded

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_calib_free (CUVIS_CALIB *io_pCalibration)

Clear a loaded calibration by it’s handle.

The internal memory is freed.

Parameters:: io_pCalibration – [inout] The handle of the calibration. The handle number will be invalidated.
Returns:: status_ok if the calibration could be released

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_calib_get_id (CUVIS_CALIB i_calib, CUVIS_CHAR *o_pCalibId)

Get the unique id of a calibration.

Parameters:

i_calib – [in] the calibration
o_pCalibId – [out] the unique id output string

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_calib_get_info (CUVIS_CALIB i_calib, CUVIS_CALIBRATION_INFO *o_pCalibInfo)

Get info of a calibration.

Parameters:

i_calib – [in] the calibration
o_pCalibInfo – [out] the info data struct

Measurement

group Measurement

How to interact with the Measurements taken by the SDK.

Functions

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_measurement_load (const CUVIS_CHAR *i_path, CUVIS_MESU *o_pMesu)

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.

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_measurement_deep_copy (CUVIS_MESU i_mesu, CUVIS_MESU *o_pMesu)

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.

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_measurement_clear_cube (CUVIS_PROC_CONT i_mesu)

Clears the cube from a 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.

Parameters:: i_mesu – [in] The measurement

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_measurement_clear_implicit_reference (CUVIS_PROC_CONT i_mesu, CUVIS_REFERENCE_TYPE i_type)

Clears an 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:

i_mesu – [in] The measurement
i_type – [in] The type of the reference to be cleard

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_measurement_save (CUVIS_MESU const i_mesu, const CUVIS_CHAR *i_path, CUVIS_SAVE_ARGS args)

Save a measurement to disk.

Saves a single measurement to the disk in cu3 format. The file name is given by the measurement’s name (see cuvis_measurement_set_name)

Parameters:

i_path – [in] The file directory
i_mesu – [in] The handle of the measurement to be saved
args – [in] The saving options

Returns:

status_ok, if the measurement was save successfully.

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_measurement_set_name (CUVIS_MESU const i_mesu, const CUVIS_CHAR *i_name)

Set the name of the measurement in memory.

By default, a newly aquired measurement has the name <SESSIONNAME>_<session_no>_<sequence_no> (see CUVIS_SESSION_INFO). This will also be the name of the file while saving it. This can be changed by this function.

Parameters:

i_mesu – [in] The measurements to be changed
i_name – [in] The new measurement’s name

Returns:

status_ok, if the measurement’s name was set successfully.

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_measurement_set_comment (CUVIS_MESU const i_mesu, const CUVIS_CHAR *i_comment)

Set the comment of the measurement in memory.

Parameters:

i_mesu – [in] The measurements to be changed
i_comment – [in] The new measurement’s comment

Returns:

status_ok, if the measurement’s name was set successfully.

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_measurement_free (CUVIS_MESU *io_pMesu)

Release a measurement handle.

Release a measurement by it’s handle. The handle will be overwritten to CUVIS_HANDLE_NULL This will not affect any measurements on disk.

Parameters:: io_pMesu – [inout] The handle to the measurement to be deleted
Returns:: status_ok if the measurement was released.

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_measurement_get_metadata (CUVIS_MESU i_mesu, CUVIS_MESU_METADATA *o_pMetaData)

Obtain metadata from 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.

Parameters:

i_mesu – [in] The measurement’s handle
o_pMetaData – [out] The meta structure to be filled

Returns:

status_ok, if the meta-data could be loaded without errors

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_measurement_get_data_image (CUVIS_MESU i_mesu, const CUVIS_CHAR *i_key, CUVIS_IMBUFFER *o_pBuf)

Get image data from measurement.

Return image data from a measurement. The image data is valid as long as the measurement handle is not released and the measurement is not re-processed.

This function can only be called, if he data type is data_type_image. This can be checked by the function cuvis_measurement_get_data_info.

see also: Reserved Keys

Parameters:

i_mesu – [in] The measurement handle
i_key – [in] The data frame identification key (see cuvis_measurement_get_data_info or Reserved Keys)
o_pBuf – [out] The image buffer to be filled

Returns:

status_ok if the buffer could be filled with the image element. status_not_available if the requested data was empty, or the key could not be found

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_measurement_get_data_string (CUVIS_MESU i_mesu, const CUVIS_CHAR *i_key, CUVIS_SIZE i_outBufferlength, CUVIS_CHAR *o_pValue)

Get string data from measurement.

Return string data from a measurement.

This function can only be called, if he data type is data_type_string. This can be checked by the function cuvis_measurement_get_data_info.

see also: Reserved Keys

Parameters:

i_mesu – [in] The measurement handle
i_key – [in] the data frame identification key (see cuvis_measurement_get_data_info or Reserved Keys)
i_outBufferlength – [in] the maximal possible length of the string that is going to be copied (see cuvis_measurement_get_data_info or Reserved Keys)
o_pValue – [out] The string buffer to be filled. The provided array must have the length of i_length

Returns:

status_ok if the buffer could be filled with the string.

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_measurement_get_data_string_length (CUVIS_MESU i_mesu, const CUVIS_CHAR *i_key, CUVIS_SIZE *o_pLength)

Get the length of string data from measurement.

Return the length of a string data from a measurement.

This function can only be called, if he data type is data_type_string. This can be checked by the function cuvis_measurement_get_data_info.

see also: Reserved Keys

Parameters:

i_mesu – [in] The measurement handle
i_key – [in] the data frame identification key (see cuvis_measurement_get_data_info or Reserved Keys)
o_pLength – [out] The length of the string data

Returns:

status_ok if the length could be returned

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_measurement_get_data_sensor_info (CUVIS_MESU i_mesu, const CUVIS_CHAR *i_key, CUVIS_SENSOR_INFO *o_pValue)

Get image info data from measurement.

Return image data from a measurement. Tis

This function can only be called, if he data type is data_type_string. This can be checked by the function cuvis_measurement_get_data_info.

see also: Reserved Keys

Parameters:

i_mesu – [in] The measurement handle
i_key – [in] the data frame identification key (see cuvis_measurement_get_data_info or Reserved Keys)
o_pValue – [out] The string buffer to be filled. The provided array must have the length of CUVIS_MAXBUF

Returns:

status_ok if the buffer could be filled with the string.

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_measurement_get_data_gps (CUVIS_MESU i_mesu, const CUVIS_CHAR *i_key, CUVIS_GPS *o_pGps)

Get GPS data from measurement.

Return gps data from a measurement.

This function can only be called, if he data type is data_type_gps. This can be checked by the function cuvis_measurement_get_data_info.

see also: Reserved Keys

Parameters:

i_mesu – [in] The measurement handle
i_key – [in] the data frame identification key (see cuvis_measurement_get_data_info or Reserved Keys)
o_pGps – [out] The gps buffer to be filled.

Returns:

status_ok if the buffer could be filled with the gps data set.

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_measurement_get_data_info (CUVIS_MESU i_mesu, CUVIS_CHAR *o_pKey, CUVIS_DATA_TYPE *o_pType, CUVIS_INT i_id)

get meta-information of a data element

Retrieve the meta-informations of a data element identified by it’s positional number. A measurement has N data elements (obtain N with the functions cuvis_measurement_get_data_count) Thus, the meta-data of element 0 to N-1 can be obtained. The o_pType defined the data type: If it is data_type_image, retrieve it with cuvis_measurement_get_data_image.

If it is data type is data_type_gps, retrieve it with cuvis_measurement_get_data_gps. If it is data_type_string, retrieve with cuvis_measurement_get_data_string If it is data_type_unsupported, the data cannot be retrieved.

To retrieve the data, you will require the o_pKey wich you can obtain by using this function. The key is the name of the data channel.

Some keys are reserved, see Reserved Keys

Parameters:

i_mesu – [in] The measurement handle
o_pKey – [out] Output the data key
o_pType – [out] The data type
i_id – [in] The number of the data element

Returns:

status_ok if the data information could be obtained

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_measurement_get_data_count (CUVIS_MESU i_mesu, CUVIS_INT *o_pCount)

Retrieve the number of data elements.

Parameters:

i_mesu – [in] The measurement handle
o_pCount – [out] The number of data elements

Returns:

status_ok if the data element count could be retrieved

Session File

group Session File

The main file format of the SDK.

Functions

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_session_file_load (const CUVIS_CHAR *i_path, CUVIS_SESSION_FILE *o_pSess)

Load a session_info file from disk.

The session_info file is a cu3s file and consists of binary cu3 measurement data. Call cuvis_session_file_get_mesu to obtain a single measurement frame. SessionFile files can be create with the Cube Exporter (see cuvis_exporter_create_cube)

Note

Do not read a file currently opened for writing.

Parameters:

i_path – [in] the file path of the session_info file
o_pSess – [out] the handle of the session_info file.

Returns:

status_ok, if the measurement could be loaded.

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_session_file_free (CUVIS_SESSION_FILE *o_pSess)

Release a session_info file handle.

Release a measurement by it’s handle. The handle will be overwritten to CUVIS_HANDLE_NULL This will not affect any measurements on disk. Measurements loaded from the session_info file remain valid.

Parameters:: o_pSess – [inout] The handle to the measurement to be deleted
Returns:: status_ok if the session_info file was released.

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_session_file_get_mesu (CUVIS_SESSION_FILE i_sess, CUVIS_INT i_frameNo, CUVIS_SESSION_ITEM_TYPE i_type, CUVIS_MESU *o_pMesu)

Load a measurement from the session_info file.

Parameters:

i_sess – [in] the session_info file handle
i_frameNo – [in] the frame no. Counting from 0, must be below value of cuvis_session_file_get_size of it’s respective i_type
i_type – [in] the type of listing (size depends on type)
o_pMesu – [out] the handle of the measurement.

Returns:

status_ok, if the measurement could be loaded. status_no_measurement if the measurement was dropped. status_error if the frame exeeds the number of frames.

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_session_file_get_reference_mesu (CUVIS_SESSION_FILE i_sess, CUVIS_INT i_frameNo, CUVIS_REFERENCE_TYPE i_type, CUVIS_MESU *o_pMesu)

Load a reference measurement from the session_info file.

Parameters:

i_sess – [in] the session_info file handle
i_frameNo – [in] the reference number. Counting from 0. If i_type is not set, refers to the index of all references and must be below the value of cuvis_session_file_get_size using type session_item_type_references. If i_type is set, must be 0.
i_type – [in] the type of reference measurement requested
o_pMesu – [out] the handle of the measurement.

Returns:

status_ok, if the reference could be loaded. status_no_measurement if the reference does not exist. status_error if the i_frameNo exeeds the number of references.

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_session_file_get_size (CUVIS_SESSION_FILE i_sess, CUVIS_SESSION_ITEM_TYPE i_type, CUVIS_INT *o_pSize)

Get number of total frames of session_info file.

Parameters:

i_sess – [in] the session_info file handle
i_type – [in] the type of listing (size depends on type)
o_pSize – [out] the size is written here.

Returns:

status_ok if no error occurred.

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_session_file_get_thumbnail (CUVIS_SESSION_FILE i_sess, CUVIS_IMBUFFER *o_pThumbnail)

Get the thumbnail image of a session file.

Return the thumbnail of a session file. The image data is valid as long as the session file handle is not released.

see also: Reserved Keys

Parameters:

i_sess – [in] The session file handle
o_pThumbnail – [out] The image buffer to be filled

Returns:

status_ok if the buffer could be filled with the image element. status_not_available if the requested data was empty, or the key could not be found

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_session_file_get_fps (CUVIS_SESSION_FILE i_sess, double *o_pFps)

get a session_info file’s FPS

The session_info file meta-Information will be available only if the mode cuvis_session_file_get_operation_mode returns “Internal”

Parameters:

i_sess – [in] the session_info file handle
o_pFps – [out] the frames per second the session_info was recorded with.

Returns:

status_ok if fps could be retrieved, status_not_available if the session_info file has not FPS property set.

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_session_file_get_hash (CUVIS_SESSION_FILE i_sess, CUVIS_CHAR *o_pHash)

get a session_info file’s hash

Parameters:

i_sess – [in] the session_info file handle
o_pHash – [out] the hash of the sessionfile.

Returns:

status_ok if hash could be retrieved, status_not_available if the sessionfile has no hash property set.

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_session_file_get_operation_mode (CUVIS_SESSION_FILE i_sess, CUVIS_OPERATION_MODE *o_pMode)

returns the operation mode the session_info file was recorded in

The operation mode gives indication how the session_info file was recorded.

Parameters:

i_sess – [in] the session_info file handle
o_pMode – [out] the operation mode of the session_info file.

Returns:

status_ok if no error occurred.

The Info Layer

group The info layer

The info layer can be retrieved with the function cuvis_measurement_get_data_image Though is appears to be an image and will also be exported and fragmented as an image it is actually a set of flags.

Each position of the a info-layer pixel represents a data flag for a respective cube (or pan image).

E.g. if a cube (CUVIS_MESU_CUBE_KEY) has the size of 410x410x164 (W x H x Chn), the respective info layer (CUVIS_MESU_CUBE_INFO_KEY) will have a size of 410x410. The info_layer value at position x,y contains the flags for the whole spectrum at position x,y in the cube.

The same is true for the pan-chromatic image ((CUVIS_MESU_CUBE_INFO_KEY) and CUVIS_MESU_CUBE_INFO_KEY, respectively)

The info layer pixel value is retrieved by binary operation.

Example:

// mesu is a measurement already loaded
// load the info channel to cube_info_layer_buffer
CUVIS_IMBUFFER cube_info_layer_buffer;
cuvis_measurement_get_data_image(mesu, CUVIS_MESU_CUBE_INFO_KEY, &cube_info_layer_buffer);
//now load pixel x=15, y=17' s flag information
int x = 15, y = 17;
uint16_t info_ptr = (const uint16_t*)(cube_info_layer_buffer.raw);
cube_info_layer_buffer pixel_info = IMBUFFER_GET(info_ptr, x, y, 0, imbuf);
//check if the pixel is ok
if (pixel_info == CUVIS_MESU_INFO_OK)
    printf("pixel 15|17 ok \n");
else
{
    // multiple flags can be set
    if ((pixel_info  & CUVIS_MESU_INFO_BAD_PIXEL) != 0)
        printf("pixel 15|17 is over-illuminated \n");

    if ((pixel_info  & CUVIS_MESU_INFO_OVERILLUMINATED) != 0)
        printf("pixel 15|17 is a bad pixel \n");
    // ...
}

Note

The info layer may not be available on all devices.

Defines

CUVIS_MESU_CUBE_INFO_KEY: name of the info channel of its respective cube.

CUVIS_MESU_PAN_INFO_KEY: name of the info channel of its respective pan image.

CUVIS_MESU_INFO_OK: no flag set, only valid, if pixel value is equal 0

CUVIS_MESU_INFO_OVERILLUMINATED: one or more channels of the spectrum are over-exposed / the pan image is over-exposed at this position

CUVIS_MESU_INFO_BAD_PIXEL

the pixel is marked bad, eg.

a pixel of the respective spectrum is dead

CUVIS_MESU_INFO_OVERILLUMINATED_REFERENCE: one or more channels of the spectrum of the white reference that was used to calculate this position was over-exposed

CUVIS_MESU_INFO_UNDERFLOW_MEASUREMENT_MIN_DARK: the meausurement was darker then the dark reference at this position (underflow)

CUVIS_MESU_INFO_UNDERFLOW_WHITE_MIN_DARK: the white reference was darker then the dark reference at this position (underflow)

CUVIS_MESU_INFO_REFERENCE_CALC_OVERFLOW

the reflectance value exceeded the maximum value possible by the data format (i.e.

the value reflectance reached or exceeded 655.35% (uint16 value of 65535)

CUVIS_MESU_INFO_INCOMPLETE: the spectrum at this position is incomplete, e.g by a bad / too close distance calibration

Return Values of SDK Functions

group Return Values of SDK Functions

More Information on the Return Values of the SDK Functions.

Most of the SDK functions return a cuvis_status_t. This value indicates if the function call was executed sucessfully or if a error occurred. If the value is status_error for example, this indicates that an error occurred. The specific error message can then be retrieved via cuvis_get_last_error_msg to get more details.

Enums

enum cuvis_status_t

return state of any SDK function

Values:

enumerator status_ok: the function encountered no problems

enumerator status_error

the function failed for some reason.

Call cuvis_get_last_error_msg for details

enumerator status_deferred: a async function has not been started yet

enumerator status_overwritten: the async call was overwritten by another async call to the same internal values

enumerator status_timeout

obtaining a async function result has timed out.

Call again later

enumerator status_no_measurement: polling a measurement returned no result / frame was dropped

enumerator status_not_available: retrieving a value is (currently) not possible

enumerator status_not_processed: processing the measurement with the worker failed, raw data is available

enumerator status_not_stored: storing the measurement with the worker/exporter failed

enumerator status_no_view: obtaining the measurement’s view with the worker failed, raw data is available

Functions

SDK_CAPI const CUVIS_CHAR *SDK_CCALL cuvis_get_last_error_msg (void): Call this function for obtaining the last error message.

SDK_CAPI const CUVIS_STATUS SDK_CCALL cuvis_set_last_error_locale (CUVIS_CHAR const *i_locale_id)

Set the locale for localized error messages.

Parameters:: i_locale_id – [in] set the locale id, e.g. “de” for german. See the “locale” directory for available translations.

SDK_CAPI const CUVIS_WCHAR *SDK_CCALL cuvis_get_last_error_msg_localized (void)

Call this function for obtaining the last localized error message.

remember to set locale with cuvis_set_last_error_locale first.

Logging

group Logging

There are several ways to configure the logging behaviour in the Cuvis SDK.

Logfile Configuration Behaviour

The SDK provides the possibility to write the log to a logfile. For this a “log.cfg” file has to be created at a certain position.

When a local “.cuvis” directory exists with an empty “log.cfg” file, the cuvis sdk will create a debug log in that directory. The log file name is the process name followed by log, e.g. “example.exe.log”, if the process is named “example.log”

If a local “.cuvis” directory is not found, the system-wide configuration of the logging is used (activated by default from the installation of cuvis): The configuration can be found under PROGRAMDATA%/cuvis/log.cfg (usually “C:/Program Data/cuvis/log.cfg”) for Windows or /etc/cuvis/log.cfg for linux. The log output can be found under PROGRAMDATA%/cuvis for Windows and /var/log/cuvis for linux.

Loglevel at Runtime

Secondly there is the option to adapt the logging behaviour the the standard output stream via cuvis_set_log_level.

Registration of Log Callbacks

As a third option there is the possibility to register a function as a callback that will be called every time a new log message is recevied with the requested log level. See cuvis_register_log_callback and cuvis_register_log_callback_localized for more information.

Typedefs

void(SDK_CCALL * log_callback )(const char *msg, CUVIS_INT level)

void(SDK_CCALL * log_callback_localized )(const CUVIS_WCHAR *msg, CUVIS_INT level)

Enums

enum cuvis_loglevel_t

The available log levels.

Values:

enumerator loglevel_fatal: only report error not recoverable

enumerator loglevel_error: report errors and loglevel_fatal messages

enumerator loglevel_warning: report warnings and loglevel_error messages.

enumerator loglevel_info: report status information and loglevel_warning messages.

enumerator loglevel_debug: report all messages, including debug messages

Functions

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_set_log_level (CUVIS_INT level)

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

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_register_log_callback (log_callback i_callback, CUVIS_INT i_min_level)

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,

Acquisition Context

group Acquisition Context

Capturing Images with the SDK.

An handle for an acquisition context can be obtained by either loading it with a calibration handle (Calibration) or by loading it with a Session File handle.

The acquisition context handles the communication with the camera, including setting state variables and capturing images.

Enums

enum cuvis_operation_mode_t

Operation mode of a camera.

Values:

enumerator OperationMode_Software: software trigger, aka “single shot mode” or “software mode”.

enumerator OperationMode_Internal: triggered by internal clock, aka “video mode”.

enumerator OperationMode_External: triggered by external trigger, aka “trigger mode”.

enumerator OperationMode_Undefined

undefiend (e.g.

changing)

Functions

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_acq_cont_capture (CUVIS_ACQ_CONT i_acqCont, CUVIS_MESU *o_pMesu, CUVIS_INT timeout_ms)

Capture a measurement.

This function is only available in operation mode “Software”. The function executes a software trigger synchronously.

Parameters:

i_acqCont – [in] the acquisition context
o_pMesu – [out] the handle of the recorded image will be written to this variable
timeout_ms – [in] the timeout in ms. Give 0 to wait for ever.

Returns:

status_ok if the measurement was recorded. status_timeout or status_deferred is returned, if the capture was not completed (yet)

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_acq_cont_capture_async (CUVIS_ACQ_CONT i_acqCont, CUVIS_ASYNC_CAPTURE_RESULT *o_pAsyncResult)

Capture a measurement async.

This function is only available in operation mode “Software”. The function executes a software trigger asynchronously. The recorded measurement can be obtained by the function cuvis_async_capture_get.

If o_pAsyncResult is set to NULL, the measurement is added to the Acqusition Context’s internal queue. Retrieve it with cuvis_acq_cont_get_next_measurement or via the worker (if used) cuvis_worker_get_next_result

Parameters:

i_acqCont – [in] the acquisition context
o_pAsyncResult – [out] the async capture handle will be written to this variable or NULL

Returns:

status_ok if the async call could be executed.

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_acq_cont_get_next_measurement (CUVIS_ACQ_CONT i_acqCont, CUVIS_MESU *o_pMesu, CUVIS_INT timeout_ms)

Get measurement from internal cache.

This function is only available in operation mode “Internal” or “External”. The function obtains the image from the internal memory, if available.

Parameters:

i_acqCont – [in] the acquisition context
o_pMesu – [out] the handle of the recorded image will be written to this variable.
timeout_ms – [in] the timeout in ms. Give 0 to wait for ever.

Returns:

status_ok if the measurement was recorded. Returns status_no_measurement if no measurement was made available during the timeout time. If any error occurred status_error is returned.

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_acq_cont_has_next_measurement (CUVIS_ACQ_CONT i_acqCont, CUVIS_INT *o_pHasNext)

check if any measurements are available in the buffer

This function is only available in operation mode “Internal” or “External”.

Parameters:

i_acqCont – [in] the acquisition context
o_pHasNext – [in] value of 0 is written, if no measurements are available. value > 0, if a measurement is available.

Returns:

status_ok if no error occurred. If any error occurred status_error is returned.

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_acq_cont_create_from_calib (CUVIS_CALIB i_calib, CUVIS_ACQ_CONT *o_pAcqCont)

Load a acquisition context from a given calibration.

Load the acquisition context from the calibration. This will load the hardware and initialize it. Do not load multiple instances of the came calibration / camera.

Parameters:

i_calib – [in] The calibration instance the processing context will be loaded from
o_pAcqCont – [out] The handle of the acquisition context.

Returns:

status_ok if the acquisition context could be loaded

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_acq_cont_create_from_session_file (CUVIS_SESSION_FILE i_sess, CUVIS_INT i_simulate, CUVIS_ACQ_CONT *o_pAcqCont)

Load a acquisition context from a given session_file.

The acquisition context from the embedded acquisition context of the session_info file.

Parameters:

i_sess – [in] The session_file the processing context will be loaded from
i_simulate – [in] If True, uses the provided session file for simulated data capturing
o_pAcqCont – [out] The handle of the acquisition context.

Returns:

status_ok if the acquisition context could be loaded

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_acq_cont_get_state (CUVIS_ACQ_CONT i_acqCont, CUVIS_HARDWARE_STATE *o_pState)

get the online state of the hardware

Hardware can be used, when at least it’s required components are online.

Parameters:

i_acqCont – [in] the acquisition context
o_pState – [out] the state will be written here

Returns:

status_ok, if no internal error occurred.

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_acq_cont_ready_get (CUVIS_ACQ_CONT i_acqCont, CUVIS_INT *o_pIsReady)

get initialization state of the acquisition context

Parameters:

i_acqCont – [in] the acquisition context
o_pIsReady – [out] whether the acquisition context has completed all initialization tasks

Returns:

status_ok, if no internal error occurred.

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_acq_cont_get_session_info (CUVIS_ACQ_CONT i_acqCont, CUVIS_SESSION_INFO *o_pSessionInfo)

get the acquisition session_info

Get the acquisition session_info settings. Also use this function to get the current sequence number.

Parameters:

i_acqCont – [in] the acquisition context
o_pSessionInfo – [out] the state will be written here

Returns:

status_ok, if no internal error occurred.

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_acq_cont_set_session_info (CUVIS_ACQ_CONT i_acqCont, CUVIS_SESSION_INFO const *i_pSessionInfo)

set the acquisition session_info

Set the acquisition session_info settings.

Parameters:

i_acqCont – [in] the acquisition context
i_pSessionInfo – [out] the session_info details to be set

Returns:

status_ok, if no internal error occurred.

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_acq_cont_queue_size_set (CUVIS_ACQ_CONT i_acqCont, CUVIS_INT i_size)

set the receive queue buffer size

Set the amounts of measurements that will be stored internally, ready for retrieval. Default=100.

Parameters:

i_acqCont – [in] the acquisition context
i_size – [in] the new queue size

Returns:

status_ok if the new queue size could be set.

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_acq_cont_free (CUVIS_ACQ_CONT *io_pAcqCont)

Clear a loaded acquisition context by it’s handle.

The internal memory is freed.

Parameters:: io_pAcqCont – [inout] The handle of the processing context. The handle number will be invalidated.
Returns:: status_ok if the acquisition context could be released

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_acq_cont_get_component_info (CUVIS_ACQ_CONT i_acqCont, CUVIS_INT i_id, CUVIS_COMPONENT_INFO *o_pCompInfo)

Get components general info.

Return general component information about a component build into the acquisition hardware. This helps identifying the correct component for settings specific component settings (e.g. gain)

Parameters:

i_acqCont – [in] the acquisition context
i_id – [in] the device id (value between 0 and below cuvis_acq_cont_get_component_count)
o_pCompInfo – [out] the component info to be filled

Returns:

cuvis_ok if the info fields could be filled.

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_acq_cont_get_component_count (CUVIS_ACQ_CONT i_acqCont, CUVIS_INT *o_pCount)

Get the number of components.

The acquisition hardware is build from one or more components. Get the component count.

Parameters:

i_acqCont – [in] the acquisition context
o_pCount – [out] the number of components is written here

Returns:

cuvis_ok if the number of components could be set

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_comp_pixel_format_set (CUVIS_ACQ_CONT i_acqCont, CUVIS_INT i_id, CUVIS_CHAR const *i_pPixelFormat)

Set components pixelformat.

Set components pixelformat

Parameters:

i_acqCont – [in] the acquisition context
i_id – [in] the device id (value between 0 and below cuvis_acq_cont_get_component_count)
i_pPixelFormat – [in] the components pixelformat

Returns:

cuvis_ok if the pixelformat was set.

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_comp_pixel_format_set_async (CUVIS_ACQ_CONT i_acqCont, CUVIS_ASYNC_CALL_RESULT *o_pAsyncResult, CUVIS_INT i_id, CUVIS_CHAR const *i_pPixelFormat)

Set components pixelformat.

Set components pixelformat (asynchronous)

Parameters:

i_acqCont – [in] the acquisition context
o_pAsyncResult – [out] The Async object that will contain the result of the operation
i_id – [in] the device id (value between 0 and below cuvis_acq_cont_get_component_count)
i_pPixelFormat – [in] the components pixelformat

Returns:

cuvis_ok if the pixelformat was set.

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_comp_pixel_format_get (CUVIS_ACQ_CONT i_acqCont, CUVIS_INT i_id, CUVIS_CHAR *o_pPixelFormat)

Get components actual pixelformat.

Return actual components pixelformat

Parameters:

i_acqCont – [in] the acquisition context
i_id – [in] the device id (value between 0 and below cuvis_acq_cont_get_component_count)
o_pPixelFormat – [out] the components pixelformat

Returns:

cuvis_ok if the pixelformat was returned.

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_comp_available_pixel_format_count_get (CUVIS_ACQ_CONT i_acqCont, CUVIS_INT i_id, CUVIS_INT *o_pCount)

Get components actual pixelformat.

Return the amount of components available pixelformats

Parameters:

i_acqCont – [in] the acquisition context
i_id – [in] the device id (value between 0 and below cuvis_acq_cont_get_component_count)
o_pCount – [out] amount of available pixel formats

Returns:

cuvis_ok if the amount was returned.

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_comp_available_pixel_format_get (CUVIS_ACQ_CONT i_acqCont, CUVIS_INT i_id, CUVIS_INT i_index, CUVIS_CHAR *o_pPixelFormat)

Get components actual pixelformat.

Return indexed components available pixelformat

Parameters:

i_acqCont – [in] the acquisition context
i_id – [in] the device id (value between 0 and below cuvis_acq_cont_get_component_count)
i_index – [in] index of the requested available pixelformat
o_pPixelFormat – [out] the components available pixelformat

Returns:

cuvis_ok if the pixelformat was returned.

enum cuvis_status_t cuvis_acq_cont_fps_get(int32_t i_acqCont, double *o_pvalue)

Get cuvis_acq_cont_fps function.

Details: “Frames per second”

Result is written to o_pvalue

enum cuvis_status_t cuvis_acq_cont_fps_set(int32_t i_acqCont, double value)

set cuvis_acq_cont_fps .

Unit: “Frames per second”

Block until done or failed

enum cuvis_status_t cuvis_acq_cont_fps_set_async(int32_t i_acqCont, int32_t *o_pAsyncResult, double value)

set cuvis_acq_cont_fps asynchronously.

Unit: “Frames per second”

Use

cuvis_async_call_get to sync again

enum cuvis_status_t cuvis_acq_cont_average_get(int32_t i_acqCont, int32_t *o_pvalue)

Get cuvis_acq_cont_average function.

Details: “Number of averages”

Result is written to o_pvalue

enum cuvis_status_t cuvis_acq_cont_average_set(int32_t i_acqCont, int32_t value)

set cuvis_acq_cont_average .

Unit: “Number of averages”

Block until done or failed

enum cuvis_status_t cuvis_acq_cont_average_set_async(int32_t i_acqCont, int32_t *o_pAsyncResult, int32_t value)

set cuvis_acq_cont_average asynchronously.

Unit: “Number of averages”

Use

cuvis_async_call_get to sync again

enum cuvis_status_t cuvis_acq_cont_integration_time_get(int32_t i_acqCont, double *o_pvalue)

Get cuvis_acq_cont_integration_time function.

Details: “Integration time in milliseconds”

Result is written to o_pvalue

enum cuvis_status_t cuvis_acq_cont_integration_time_set(int32_t i_acqCont, double value)

set cuvis_acq_cont_integration_time .

Unit: “Integration time in milliseconds”

Block until done or failed

enum cuvis_status_t cuvis_acq_cont_integration_time_set_async(int32_t i_acqCont, int32_t *o_pAsyncResult, double value)

set cuvis_acq_cont_integration_time asynchronously.

Unit: “Integration time in milliseconds”

Use

cuvis_async_call_get to sync again

enum cuvis_status_t cuvis_acq_cont_auto_exp_get(int32_t i_acqCont, int32_t *o_pvalue)

Get cuvis_acq_cont_auto_exp function.

Details: “get_auto_exp”

Result is written to o_pvalue

enum cuvis_status_t cuvis_acq_cont_auto_exp_set(int32_t i_acqCont, int32_t value)

set cuvis_acq_cont_auto_exp .

Unit: “set_auto_exp”

Block until done or failed

enum cuvis_status_t cuvis_acq_cont_auto_exp_set_async(int32_t i_acqCont, int32_t *o_pAsyncResult, int32_t value)

set cuvis_acq_cont_auto_exp asynchronously.

Unit: “set_auto_exp”

Use

cuvis_async_call_get to sync again

enum cuvis_status_t cuvis_acq_cont_auto_exp_comp_get(int32_t i_acqCont, double *o_pvalue)

Get cuvis_acq_cont_auto_exp_comp function.

Details: “get auto exposure compensation”

Result is written to o_pvalue

enum cuvis_status_t cuvis_acq_cont_auto_exp_comp_set(int32_t i_acqCont, double value)

set cuvis_acq_cont_auto_exp_comp .

Unit: “set auto exposure compensation”

Block until done or failed

enum cuvis_status_t cuvis_acq_cont_auto_exp_comp_set_async(int32_t i_acqCont, int32_t *o_pAsyncResult, double value)

set cuvis_acq_cont_auto_exp_comp asynchronously.

Unit: “set auto exposure compensation”

Use

cuvis_async_call_get to sync again

enum cuvis_status_t cuvis_acq_cont_binning_get(int32_t i_acqCont, int32_t *o_pvalue)

Get cuvis_acq_cont_binning function.

Details: “0 = disable, 1 = enable”

Result is written to o_pvalue

enum cuvis_status_t cuvis_acq_cont_binning_set(int32_t i_acqCont, int32_t value)

set cuvis_acq_cont_binning .

Unit: “0 = disable, 1 = enable”

Block until done or failed

enum cuvis_status_t cuvis_acq_cont_binning_set_async(int32_t i_acqCont, int32_t *o_pAsyncResult, int32_t value)

set cuvis_acq_cont_binning asynchronously.

Unit: “0 = disable, 1 = enable”

Use

cuvis_async_call_get to sync again

enum cuvis_status_t cuvis_acq_cont_operation_mode_get(int32_t i_acqCont, enum cuvis_operation_mode_t *o_pvalue)

Get cuvis_acq_cont_operation_mode function.

Details: “enumeration value”

Result is written to o_pvalue

enum cuvis_status_t cuvis_acq_cont_operation_mode_set(int32_t i_acqCont, enum cuvis_operation_mode_t value)

set cuvis_acq_cont_operation_mode .

Unit: “enumeration value”

Block until done or failed

enum cuvis_status_t cuvis_acq_cont_operation_mode_set_async(int32_t i_acqCont, int32_t *o_pAsyncResult, enum cuvis_operation_mode_t value)

set cuvis_acq_cont_operation_mode asynchronously.

Unit: “enumeration value”

Use

cuvis_async_call_get to sync again

enum cuvis_status_t cuvis_acq_cont_continuous_set(int32_t i_acqCont, int32_t value)

set cuvis_acq_cont_continuous .

Unit: “0 = stop, 1 = run”

Block until done or failed

enum cuvis_status_t cuvis_acq_cont_continuous_set_async(int32_t i_acqCont, int32_t *o_pAsyncResult, int32_t value)

set cuvis_acq_cont_continuous asynchronously.

Unit: “0 = stop, 1 = run”

Use

cuvis_async_call_get to sync again

enum cuvis_status_t cuvis_acq_cont_bandwidth_get(int32_t i_acqCont, int32_t *o_pvalue)

Get cuvis_acq_cont_bandwidth function.

Details: “bandwidth in MBit/s”

Result is written to o_pvalue

enum cuvis_status_t cuvis_acq_cont_queue_size_get(int32_t i_acqCont, int32_t *o_pvalue)

Get cuvis_acq_cont_queue_size function.

Details: “size of measurement queue”

Result is written to o_pvalue

enum cuvis_status_t cuvis_acq_cont_queue_used_get(int32_t i_acqCont, int32_t *o_pvalue)

Get cuvis_acq_cont_queue_used function.

Details: “used part of measurement queue”

Result is written to o_pvalue

Components

group Components

Functions

enum cuvis_status_t cuvis_comp_online_get(int32_t i_acqCont, int32_t i_id, int32_t *o_pvalue)

Get cuvis_comp_online function.

Details: “0 = false, 1 = true”

Result is written to o_pvalue

enum cuvis_status_t cuvis_comp_temperature_get(int32_t i_acqCont, int32_t i_id, double *o_pvalue)

Get cuvis_comp_temperature function.

Details: “temperature in degrees celsius”

Result is written to o_pvalue

enum cuvis_status_t cuvis_comp_bandwidth_get(int32_t i_acqCont, int32_t i_id, int32_t *o_pvalue)

Get cuvis_comp_bandwidth function.

Details: “bandwidth in MBit/s”

Result is written to o_pvalue

enum cuvis_status_t cuvis_comp_driver_queue_size_get(int32_t i_acqCont, int32_t i_id, int32_t *o_pvalue)

Get cuvis_comp_driver_queue_size function.

Details: “driver’s internal receiving queue size”

Result is written to o_pvalue

enum cuvis_status_t cuvis_comp_driver_queue_used_get(int32_t i_acqCont, int32_t i_id, int32_t *o_pvalue)

Get cuvis_comp_driver_queue_used function.

Details: “driver’s internal receiving queue used”

Result is written to o_pvalue

enum cuvis_status_t cuvis_comp_hardware_queue_size_get(int32_t i_acqCont, int32_t i_id, int32_t *o_pvalue)

Get cuvis_comp_hardware_queue_size function.

Details: “internal hardware buffer size (if supported)”

Result is written to o_pvalue

enum cuvis_status_t cuvis_comp_hardware_queue_used_get(int32_t i_acqCont, int32_t i_id, int32_t *o_pvalue)

Get cuvis_comp_hardware_queue_used function.

Details: “internal hardware buffer used (if supported)”

Result is written to o_pvalue

enum cuvis_status_t cuvis_comp_gain_get(int32_t i_acqCont, int32_t i_id, double *o_pvalue)

Get cuvis_comp_gain function.

Details: “a.u.”

Result is written to o_pvalue

enum cuvis_status_t cuvis_comp_gain_set(int32_t i_acqCont, int32_t i_id, double value)

set cuvis_comp_gain .

Unit: “a.u.”

Block until done or failed

enum cuvis_status_t cuvis_comp_gain_set_async(int32_t i_acqCont, int32_t i_id, int32_t *o_pAsyncResult, double value)

set cuvis_comp_gain asynchronously.

Unit: “a.u.”

Use

cuvis_async_call_get to sync again

enum cuvis_status_t cuvis_comp_integration_time_factor_get(int32_t i_acqCont, int32_t i_id, double *o_pvalue)

Get cuvis_comp_integration_time_factor function.

Details: “factor to main integration time”

Result is written to o_pvalue

enum cuvis_status_t cuvis_comp_integration_time_factor_set(int32_t i_acqCont, int32_t i_id, double value)

set cuvis_comp_integration_time_factor .

Unit: “factor to main integration time”

Block until done or failed

enum cuvis_status_t cuvis_comp_integration_time_factor_set_async(int32_t i_acqCont, int32_t i_id, int32_t *o_pAsyncResult, double value)

set cuvis_comp_integration_time_factor asynchronously.

Unit: “factor to main integration time”

Use

cuvis_async_call_get to sync again

Export API

group Export API

How to export Measurement captured with the SDK.

A handle for each of the exporter can be obtainend by calling either cuvis_exporter_create_cube, cuvis_exporter_create_envi, cuvis_exporter_create_tiff or cuvis_exporter_create_view. Each of the so created exporter can then export a Measurement to the respective format by calling cuvis_exporter_apply. Each exporter takes options in form of cuvis_export_general_settings_t and one of the following format specific structs cuvis_save_args_t, cuvis_export_view_settings_t, cuvis_export_tiff_settings_t

See the respective struct documentations for more information on the individual options

Functions

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_exporter_create_cube (CUVIS_EXPORTER *o_pExporter, CUVIS_EXPORT_GENERAL_SETTINGS generalSettings, CUVIS_EXPORT_CUBE_SETTINGS formatSettings)

Create a cube exporter.

Parameters:

o_pExporter – [out] The handle of the exporter
generalSettings – [in] General export settings
formatSettings – [in] Additional Cube export settings

Returns:

status_ok if the exporter was created successfully

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_exporter_create_tiff (CUVIS_EXPORTER *o_pExporter, CUVIS_EXPORT_GENERAL_SETTINGS generalSettings, CUVIS_EXPORT_TIFF_SETTINGS formatSettings)

Create a tiff exporter.

Parameters:

o_pExporter – [out] The handle of the exporter
generalSettings – [in] General export settings
formatSettings – [in] Additional TIF export settings

Returns:

status_ok if the exporter was created successfully

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_exporter_create_envi (CUVIS_EXPORTER *o_pExporter, CUVIS_EXPORT_GENERAL_SETTINGS generalSettings)

Create a ENVI exporter.

Parameters:

o_pExporter – [out] The handle of the exporter
generalSettings – [in] General export settings

Returns:

status_ok if the exporter was created successfully

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_exporter_create_view (CUVIS_EXPORTER *o_pExporter, CUVIS_EXPORT_GENERAL_SETTINGS generalSettings, CUVIS_EXPORT_VIEW_SETTINGS formatSettings)

Create a VIEW exporter.

Not to be confused with the VIEWER. The view exporter saves views to disk.

Parameters:

o_pExporter – [out] The handle of the exporter
generalSettings – [in] General export settings
formatSettings – [in] Additional view export settings

Returns:

status_ok if the exporter was created successfully

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_exporter_apply (CUVIS_EXPORTER i_exporter, CUVIS_MESU i_mesu)

Export a measurement with an exporter.

Parameters:

i_exporter – [in] The exporter
i_mesu – [in] the measurement

Returns:

status_ok if the measurement was exported successfully. status_not_stored if the measurement could not be stored.

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_exporter_flush (CUVIS_EXPORTER i_exporter)

Flush an exporter.

Parameters:: i_exporter – [in] The exporter to flush
Returns:: status_ok if the exporter was flushed successfully.

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_exporter_get_queue_used (CUVIS_EXPORTER i_exporter, CUVIS_INT *o_pQueueUsed)

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_exporter_free (CUVIS_EXPORTER *io_pExporter)

Release an exporter.

Parameters:: io_pExporter – [inout] Exporter to be released. If successfully, handle will be invalidated
Returns:: status_ok if the exporter was cleared.

struct cuvis_save_args_t

#include <cuvis.h>

options for saving as cu3/cu3s files

The cube exporter works asynchronically. For

offline saving to session file

When processing sesion files (allow_session_file=true) offline, the option allow_drop should be set to false. In this case measurements are added to the internal buffer until the size given by hard_limit

is reached.

In this mode, the options

soft_limit and max_buftime are ignroed.

online saving to session file

When recording sesion files (allow_session_file=true) live, the options allow_drop should be set to true.

When a new measurement is added to the cube exporter, the following strategy is applied:

The internal buffer has a total limit of size hard_limit. If the buffer is full, it will be dropped (end).
If the buffer is not full, the soft_limit is checked. If it is reachd, the ordering of the frame numbers is ignored and the measurement with the lowest sequence nubmer is stored to the disk directly. (This can mess up the order of the frames set soft_limit = hard_limit to disable this behaviour)
All meausurements in the internal buffer are checked: If they are held in the buffer for longer then the time given by max_buftime, they are saved to disk directly. (This can mess up the order of the frames set max_buftime to a higher value allow for longer hold time intervals.)

Public Members

CUVIS_INT allow_fragmentation

allow to split file to multiple files.

When exporting to a cu3s file (allow_session_file=true) the allow_fragmentation flag controlles if all measurements (of the same session name) are written to one file like a single file (set to false) or if each measurement is saved to a separate cu3s file (set to true). The latter option generates substantial overhead.

When exporting to a (legacy) cu3 file (allow_session_file=false), the fragmentation flag will lead to multiple files exported: a <name>.cu3 file, followed by <name>_<postfix>.tiff files. These come as a tuple and must be kept together, else the file will be corrupted. This export option is intended for legacy programs that were deisnged to read raw data with the previous software verison 2.x.

CUVIS_INT allow_overwrite

allow to overwrite an existing file.

This option anables to allow to ovewrite files on the disk, if they exist.

Note

When exporting to legacy format of version 2.x (allow_session_file=false and allow_fragmentation=true), only the existance of the *.cu3 file is checked, existing *.tiff files are neither cleaned up nor checked if they exist prior overwriting.

CUVIS_INT allow_drop

allow to drop files, if output buffers are full

This options controlls the export behaviour. If internal write buffers are full, new measurements are either dropped or kept.

The policy to drop measurements on full buffer (allow_drop=true) is recommended for online opration. The idea is to rather drop measurements and thus allow the acquisition to continue without slowing down. When this policy is set, the soft_limit and the max_buftime options are also used (see there).

If new measurements are forced to be kept (allow_drop=true), the exporter will wait until the measurement can be written. This polocy is recommended for batch-processing measurements (offline). The options soft_limit and max_buftime are ignored.

Note

This option only applies, if allow_session_file=true.

CUVIS_INT allow_session_file

save files of same session number to a single cu3s file.

If allow_fragmentation is set, cu3s fill be split by measurement. Default in Wrappers: True

CUVIS_INT allow_info_file

save additional info file.

The info file is written to the same path as the export files. It is a plain text file and consits of the a header showing the recoridng FPS and mode and a body, where each frame number from 0 till the last frame written is shown by their name. Missing frames are noted as “dropped”.

This option is ignored, when allow_session_file is set to false.

Note

The output of this file is not flushed until the exporter writes to a different file or is closed. Thus, it is not suited to be used as a way to monitor frame drops during live acquisiton.

CUVIS_OPERATION_MODE operation_mode

give the current operation mode.

Save the operation mode used while recording. Only used if allow_session_file is set.

double fps

the fps used in operation_mode video

only used if allow_session_file=true and operation_mode=Internal.

CUVIS_INT soft_limit

Out-of-order frames are sorted within the cache, as long as the cache useage is below this limit.

The soft limit is only used if allow_drop=true and allow_session_file=true.

The internal chache may hold up to soft_limit number of frames that are out of sequence.

For example: Let the the seqence number of the measurement written last be #14, and let the internal cache hold the frames #16,#17,…#24 (9 images in chache) and let the soft limit be 10 If we assume the next frame to be #25, the 10 images in cache reached the soft limit, forcing the first frame with the lowest nubmer (#16) to be written (#15 is makred as ‘dropped’). If the next image actually is #15, this image is then written out of sequence, resulting in the order #14, #16, #15.

Theese are the states of the example avove.

write to disk: #14

cache: #16,#17,…#24 [soft limit: 10]

insert: #25

write to disk: #16

cache: #17,…#24, #25 [soft limit: 10]

insert: #15

write to disk: #15

cache: #17,…#24, #25 [soft limit: 10]

This behaviour is a compromise between keeping the seuqence in order and at the same time not storing too many images if a frame was acutally dropped. Increase the soft_limit to a value same or grater the hard_limit to disable this behaviour.

CUVIS_INT hard_limit

Maximum number of elements in output cache.

The hard limit is only used if allow_session_file=true.

The output cache has a maximum size of hard_limit. If more measurements are added, adding another measurment is not possible. Adding a measurement will lock the calling function if allow_drop is set to false. If allow_drop is set to true, the added frame is directrly dropped and not stored.

Note

This behaviour also applies when using the exproter within a worker.

CUVIS_INT max_buftime

Any frame is forced to be written after this time (in ms), latest.

The maximum buffer time option is only used if allow_drop=true and allow_session_file=true.

The time a buffer is held in the exporter’s cache is tracked. If the time given by the max_buftime is exceeded, a measuremnt is written to disk.

This option also helps to guarantee a measurements to be serialized to a permanent storage and avoid data loss upon power or abnormal program termination.

This option will overwrite the soft_limit for this frame, if needed.

CUVIS_INT full_export

Whether processing results are also saved in the export.

If enabled, all cube data and accompanying meta-data are stored in the exported file as well. This vastly increases file size and the time and processing resources needed for the export.

If disabled, only the raw image from the camera and raw data from any additional devices are stored. This in turn requires the data to be reprocessed when loading it again.

struct cuvis_export_general_settings_t

#include <cuvis.h>

general export settings

Public Members

CUVIS_CHAR export_dir[CUVIS_MAXBUF]: The export directory.

CUVIS_CHAR channel_selection[CUVIS_MAXBUF]

The export channel selection

Use “all” or “full” for all available channels

Use ranges for wavelength range start-end or start:end or start:step:end ; All values in Nanometers. Examples: 450:10:550 or 450-550

uint8_t spectra_multiplier

multiply spectrum by fixed factor before exporting

This is most usefull for bitshifting the data - especially when the pan image is also added to the export.

double pan_scale

amount of pan-sharpening

The value is relative to the pan image size, give a value between 0 and 1

CUVIS_PAN_SHAPRENING_INTERPOLATION_TYPE pan_interpolation_type

for pansharpening use this interpolation type to scale up the cube before adjusting the weights

As a first step to pan-sharpening the spectral data needs to be re-sampled to the target resolution This parameter determines the method for this resampling.

CUVIS_PAN_SHAPRENING_ALGORITHM_TYPE pan_algorithm: method for calculating the weights

CUVIS_INT pre_pan_sharpen_cube

pansharpen cube before calculating user plugin

Normally pan sharpening is applied after calculating the user plugin. Prepansharpening can be used to get a pansharpened cube when no real userplugin shall be applied. Prepansharpening is calculated on the whole spectral cube which is heavy on performance.

double blend_opacity: opacity for pan_sharpening_algorithm_AlphablendPanOverlay, give a value between 0 and 1 a value of 1.0 represents usage of 100% pan image, 0 will be 100% view image

CUVIS_INT add_pan

add pan to exported image.

If applicable, the pan image is scaled to target pan-sharpening resolution.

CUVIS_INT add_fullscale_pan

add full-resolution pan to exported image.

If applicable, the image is added directly to the output. else, the image is stored separately.

CUVIS_INT permissive

Set exporter to “permisive mode”.

If set, errors will be skipped and alternative values assumed, wherever possible.

E.g., if add_pan is selected but there is no panchromatic image avaialbe, the export is not possible. In permissive mode, however, the add_pan option is de-activated and an exprot without pan image is conducted instead.

Note

This mode may lead to unexpected behaviour and should be used with caution.

struct cuvis_export_view_settings_t

#include <cuvis.h>

Additional settings for exporting to a userplugin view.

Public Members

CUVIS_CHAR const *userplugin

The userplugin xml string.

See userplugin manual.

struct cuvis_export_tiff_settings_t

#include <cuvis.h>

Additional settings for exporting tiff.

Public Members

CUVIS_TIFF_COMPRESSION_MODE compression_mode: the compression mode for tiff export

CUVIS_TIFF_FORMAT format: the tiff export mode / format

Async Programming

group Async Programming

The Async Capabilites of the SDK.

The functions of the sdk with depend on either setting a state of the camera, or awaiting image data from the camera have async variations of themself. This includes most of the setter of the acqusition context as well as cuvis_acq_cont_capture.

The non async version of these functions execute the respective task and block as long as it takes. The async counterpart function call completes immediately and returns the handle to an aync result or async Measurement.

Theses async handles can then be used to check the state of the respective function call.

Functions

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_async_call_get (CUVIS_ASYNC_CALL_RESULT *io_pAsyncResult, CUVIS_INT timeout_ms)

get the result of a async call.

Get the return code (and error message, if applicable) of an async function, that has been called. If result is not status_ok use the cuvis_get_last_error_msg function to get details.

If the timeout is used (value above 0ms), status_timeout or status_deferred will be returned, if the function is not yet finished. In that case, the asyncResult handle is still valid and can be used again. If the result is status_ok the function has finished. For both status_ok and status_error, the handle is now invalid.

If the result is status_overwritten the function’s call was overwritten by another (similar) call. The actual value set by this async function was not used, but the one of the other call. On this result, the handle is now invalid.

Parameters:

io_pAsyncResult – [inout] the async handle obtained by calling a async function. If the call finished, the handle will be invalidated
timeout_ms – [in] the timeout in ms. Give 0 to wait for ever.

Returns:

status_ok if the async function finished successfully. status_timeout or status_deferred will be returned, if the function is not yet finished. If the call failed, because it was overwritten it this function will return status_overwritten. If it failed for other reasons, the this function returns status_error.

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_async_capture_free (CUVIS_ASYNC_CAPTURE_RESULT *io_pAsyncResult): Free an async measurement result without calling it.

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_async_call_free (CUVIS_ASYNC_CALL_RESULT *io_pAsyncResult): Free an async call result without calling it.

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_async_call_status (CUVIS_ASYNC_CALL_RESULT i_pAsyncResult, CUVIS_STATUS *io_pStatusResult): checks the status of the async call object and returns it

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_async_capture_status (CUVIS_ASYNC_CAPTURE_RESULT i_pAsyncResult, CUVIS_STATUS *io_pStatusResult): checks the status of the async capture object and returns it

Processing Context

group Processing Context

Processing Images with the SDK.

Functions

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_proc_cont_create_from_calib (CUVIS_CALIB i_calib, CUVIS_PROC_CONT *o_pProcCont)

Load a processing context from a given calibration.

Load the processing context from the calibration.

Parameters:

i_calib – [in] The calibration instance the processing context will be loaded from
o_pProcCont – [out] The handle of the processing context.

Returns:

status_ok if the processing context could be loaded

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_proc_cont_create_from_mesu (CUVIS_MESU i_mesu, CUVIS_PROC_CONT *o_pProcCont)

Load a processing context from a given measurement.

The processing context is loaded from the CALIBRATION directory, relative to the measurement given ( ../Calibration/* ) . This directory is present in the normal camera operation / recording, but the reference might get lost, if you manually move the measurements. In that case, this function will fail.

Parameters:

i_mesu – [in] The measurement with a valid reference to the processing context
o_pProcCont – [out] The handle of the processing context.

Returns:

status_ok if the processing context could be loaded

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_proc_cont_create_from_session_file (CUVIS_SESSION_FILE i_sess, CUVIS_PROC_CONT *o_pProcCont)

Load a processing context from a given session_file.

The processing context from the embedded processing context of the session_info file.

Parameters:

i_sess – [in] The session_file with a valid reference to the processing context
o_pProcCont – [out] The handle of the processing context.

Returns:

status_ok if the processing context could be loaded

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_proc_cont_get_reference (CUVIS_PROC_CONT i_procCont, CUVIS_MESU *o_pMesu, CUVIS_REFERENCE_TYPE i_type)

get a specific reference from the processing context

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

Note

Implicit references given by a measurement are not returned. If they are available can only be checked indirectly by the cuvis_proc_cont_is_capable or by checking for the measurement’s data keys CUVIS_MESU_DARKREF_KEY, CUVIS_MESU_WHITEREF_KEY and CUVIS_MESU_WHITEDARKREF_KEY

Parameters:

i_procCont – [in] The handle of the processing context
o_pMesu – [out] The reference measurement’s handle
i_type – [in] The type of the measurement to be retrieved.

Returns:

status_ok if the reference measurement is available and could be loaded

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_proc_cont_set_reference (CUVIS_PROC_CONT i_procCont, CUVIS_MESU i_mesu, CUVIS_REFERENCE_TYPE i_type)

Set a reference measurement.

The available processing modes (cuvis_processing_mode_t) require certain references to be set. When a measurement is recorded with references in place, these references are available per measurement implicitly. However, if you want to process measurements with different references, or if the measurement lacks a reference, they can be set with this function.

CUVIS_MESU mesu;
cuvis_measurement_load("mesu.cu3",&mesu);
//contains implicit Reference_Dark

CUVIS_PROC_CONT pc;
cuvis_proc_cont_create_from_mesu(mesu,&pc); //will implicitly load Reference_Dark

CUVIS_MESU white;
cuvis_measurement_load("white.cu3",&white);

cuvis_proc_cont_set_reference(pc, white, Reference_White);

//Cube_Reflectance requires Reference_Dark and Reference_White
cuvis_proc_cont_apply(pc,mesu,{Cube_Reflectance});

Note

The reference explicitly set by this function has priority over the implicit measurement.

Parameters:

i_procCont – [in] The handle of the processing context
i_mesu – [in] The measurement to be used as explicit reference
i_type – [in] The type of the reference

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_proc_cont_clear_reference (CUVIS_PROC_CONT i_procCont, CUVIS_REFERENCE_TYPE i_type)

Clears a reference measurement.

Clears a reference explicitly set by cuvis_proc_cont_set_reference

Parameters:

i_procCont – [in] The handle of the processing context
i_type – [in] The type of the reference

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_proc_cont_calc_distance (CUVIS_PROC_CONT i_procCont, double i_distanceMM)

Set the operating distance by value.

Some cameras require a distance reference (calibration). This is usually obtained from a measurement at that distance. However, if the distance is known, it can be set manually.

Note

Some OEM-Cameras or older models do not support this.

Note

Internally, a measurement is created. It can be obtained by cuvis_proc_cont_get_reference.

Parameters:

i_procCont – [in] The handle of the processing context
i_distanceMM – [in] The distance in millimeters.

Returns:

status_ok if the distance could be set

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_proc_cont_has_reference (CUVIS_PROC_CONT i_procCont, CUVIS_REFERENCE_TYPE i_type, CUVIS_INT *o_pHasReference)

Check if an explicit reference was set.

Parameters:

i_procCont – [in] The handle of the processing context
i_type – [in] The reference type
o_pHasReference – [out] true, if reference is explicitly set. false, otherwise

Returns:

status_ok if no error occurred.

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_proc_cont_is_capable (CUVIS_PROC_CONT i_procCont, CUVIS_MESU i_mesu, CUVIS_PROC_ARGS i_args, CUVIS_INT *o_pIsCapable)

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.

Parameters:

i_procCont – [in] The handle of the processing context
i_mesu – [in] The measurement to be checked
i_args – [in] The processing options to be checked
o_pIsCapable – [out] true, if mode is possible. false, otherwise

Returns:

status_ok if no error occurred.

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_proc_cont_apply (CUVIS_PROC_CONT i_procCont, CUVIS_MESU i_mesu)

(Re-)Process a measurement

Process a measurement according to the current settings of the processing context. Those get set via cuvis_proc_cont_set_args The availability of the modes depends, use cuvis_proc_cont_is_capable to check if the processing is possible.

In short: Cube_Raw does not require references (Reference_Distance is optional)

Cube_DarkSubtract requires Reference_Dark (and Reference_Distance is optional)

Cube_Reflectance requires Reference_Dark and Reference_White reference (and Reference_Distance is optional), the Reference_WhiteDark is strongly recommended if using different integration times.

Cube_SpectralRadiance depends on the camera model: All cameras require Reference_SpRad. The Fireflye requires: Reference_Dark, Reference_White, the Ultris series requires only Reference_Dark.

Parameters:

i_procCont – [in] The handle of the processing context
i_mesu – [in] The measurement to be processed

Returns:

status_ok if measurement was processed.

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_proc_cont_set_args (CUVIS_PROC_CONT i_procCont, CUVIS_PROC_ARGS i_args)

Sets the processing arguments for a processing contex.

For processing a measurement see cuvis_proc_cont_apply

Parameters:

i_procCont – [in] The handle of the processing context
i_args – [in] The processing arguments that will be set

Returns:

status_ok if measurement was processed.

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_proc_cont_free (CUVIS_PROC_CONT *io_pProcCont)

Clear a loaded processing context by it’s handle.

The internal memory is freed.

Parameters:: io_pProcCont – [inout] The handle of the processing context. The handle number will be invalidated.
Returns:: status_ok if processing context could be freed.

Viewer

group Viewer

Something about the viewer.

Functions

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_viewer_create (CUVIS_VIEWER *o_pViewer, CUVIS_VIEWER_SETTINGS viewerSettings)

Create a viewer.

Not to be confused with the view exporter. The viewer returns the view in the memory

Parameters:

o_pViewer – [out] The handle of the viewer
viewerSettings – [in] view settings

Returns:

status_ok if the exporter was created successfully

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_viewer_apply (CUVIS_VIEWER i_viewer, CUVIS_MESU i_mesu, CUVIS_VIEW *o_pView)

Generate a view from a measurement.

The view is processed from a measurement by the viewer. The resulting view handle can be accessed by the cuvis_view_get_data_count to get number of elements, cuvis_view_get_data to get a single date element and cuvis_view_free to release the view (this must always be called)

Parameters:

i_viewer – [in] The viewer
i_mesu – [in] the measurement
o_pView – [out] the resulting view handle.

Returns:

status_ok if the measurement was processed successfully.

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_viewer_free (CUVIS_VIEWER *io_pViewer)

Release a viewer.

Parameters:: io_pViewer – [inout] Viewer to be released. If successfully, handle will be invalidated
Returns:: status_ok if the exporter was cleared.

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_view_get_data_count (CUVIS_MESU i_view, CUVIS_INT *o_pCount)

retrieves the number of view data elements

Parameters:

i_view – [in] the view handle
o_pCount – [out] The number of elements

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_view_get_data (CUVIS_MESU i_view, CUVIS_INT i_index, CUVIS_VIEW_DATA *o_pData)

Obtain data from view.

The data contains the actual view

Parameters:

i_view – [in] The view handle
i_index – [in] The element number
o_pData – [out] The actual view data

Returns:

status_ok, if the meta-data could be loaded without errors

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_view_free (CUVIS_VIEWER *io_pView)

Release a view.

Parameters:: io_pView – [inout] View to be released. If successfully, handle will be invalidated
Returns:: status_ok if the exporter was cleared.

Worker

group Worker

Functions

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_worker_create (CUVIS_WORKER *o_pWorker, CUVIS_WORKER_SETTINGS worker_settings)

Create a Worker.

The encapsulates the functions of the Acquisiton Context, Processing Context, Exporter, and Viewer into a single container and manages the communications between these. It also enables multi-threaded operation

Note

The set functions need to be called in order for the worker to be enabled.

Parameters:

o_pWorker – [out] The worker handle to be created
worker_settings – [in] The worker configuration

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_worker_free (CUVIS_WORKER *io_pWorker): release a worker

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_worker_set_acq_cont (CUVIS_WORKER i_worker, CUVIS_ACQ_CONT i_acq_cont)

set the acquistion context for the worker.

Give CUVIS_HANDLE_NULL to clear

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_worker_set_proc_cont (CUVIS_WORKER i_worker, CUVIS_PROC_CONT i_proc_cont)

set the processing context for the worker.

Give CUVIS_HANDLE_NULL to clear

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_worker_set_exporter (CUVIS_WORKER i_worker, CUVIS_EXPORTER i_exporter)

set the exporter for the worker.

Give CUVIS_HANDLE_NULL to clear

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_worker_set_viewer (CUVIS_WORKER i_worker, CUVIS_VIEWER i_viewer)

set the viewer for the worker.

Give CUVIS_HANDLE_NULL to clear

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_worker_query_session_progress (CUVIS_WORKER i_worker, double *o_frames_read)

Get the current percentage of frames done of the current session.

-1.0 if no session file is currently being processed.

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_worker_ingest_session_file (CUVIS_WORKER i_worker, CUVIS_SESSION_FILE i_session_file, const char *i_frame_selection)

set a session file for the worker to process (read access only).

Give CUVIS_HANDLE_NULL to clear. Set parameter SkipDroppedFrames to 1 to skip any dropped frames contained in the session - 0 will insert empty frames.

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_worker_ingest_mesu (CUVIS_WORKER i_worker, CUVIS_MESU i_mesu)

Push a mesurement into the worker to process.

Worker must have neither a session file nor an acquisition context.

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_worker_get_next_result (CUVIS_WORKER i_worker, CUVIS_MESU *o_pMesu, CUVIS_VIEW *o_pView, CUVIS_SIZE i_Timeout_ms)

Get the next result in order.

The measurement will be readyly recorded, processed (if set), stored (if set) and have a view (if set).

Parameters:

i_worker – [in] The worker handle
o_pMesu – [out] The recorded measurement or NULL if recording failed
o_pView – [out] The view, if calculated sucessfully, else NULL
i_Timeout_ms – [in] The number of milliseconds to wait for a result. -1 to wait indefinitely

Returns:

status_ok or on error: status_error, status_not_processed, status_not_stored, or status_no_view, or status_not_available

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_worker_has_next_result (CUVIS_WORKER i_worker, CUVIS_INT *o_pHasNext)

Check, if a new worker result is available.

Parameters:

i_worker – [in] The worker handle
o_pHasNext – [out] 1 if a result is available now, else 0

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_worker_get_input_queue_limit (CUVIS_WORKER i_worker, CUVIS_SIZE *o_pInputQueueLimit)

Query the maximum queue size of the input queue.

Parameters:

i_worker – [in] The worker handle
o_pInputQueueLimit – [out] The maximum size of the input queue

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_worker_get_mandatory_queue_limit (CUVIS_WORKER i_worker, CUVIS_SIZE *o_pMandatoryLimit)

Query the maximum queue size of the mandatory queue.

Parameters:

i_worker – [in] The worker handle
o_pMandatoryLimit – [out] The maximum size of the mandatory queue. This is also the maximum number of measurements processed simultaneously

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_worker_get_supplementary_queue_limit (CUVIS_WORKER i_worker, CUVIS_SIZE *o_pSupplementaryLimit)

Query the maximum queue size of the supplementary queue.

Parameters:

i_worker – [in] The worker handle
o_pSupplementaryLimit – [out] The maximum size of the supplementary queue. This is also the maximum number of measurements processed simultaneously

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_worker_get_output_queue_limit (CUVIS_WORKER i_worker, CUVIS_SIZE *o_pOutputQueueLimit)

Query the maximum queue size of the output queue.

Parameters:

i_worker – [in] The worker handle
o_pOutputQueueLimit – [out] The maximum size of the output queue

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_worker_get_queue_used (CUVIS_WORKER i_worker, CUVIS_INT *o_pQueueUsed)

Query the number of items currently in the result queue.

Parameters:

i_worker – [in] The worker handle
o_pQueueUsed – [out] The number of results currently in the output queue

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_worker_get_can_drop_results (CUVIS_WORKER i_worker, CUVIS_INT *o_pCanDrop)

Query current drop behavior.

Parameters:

i_worker – [in] The worker handle
o_pCanDrop – [out] If 1, the worker is allowed to drop results when the output queue is full

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_worker_get_can_skip_measurements (CUVIS_WORKER i_worker, CUVIS_INT *o_pCanSkip)

Query current skip behavior.

Parameters:

i_worker – [in] The worker handle
o_pCanSkip – [out] If 1, the worker is allowed to entirely skip processing measurements, if the mandatory queue is full

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_worker_get_can_skip_supplementary (CUVIS_WORKER i_worker, CUVIS_INT *o_pCanSkip)

Query current skip behavior.

Parameters:

i_worker – [in] The worker handle
o_pCanSkip – [out] If 1, the worker is allowed to skip supplementary processing of measurements, if the supplementary queue is full

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_worker_is_processing_mandatory (CUVIS_WORKER i_worker, CUVIS_INT *o_pProcessingMandatory)

Query wether the processing step is currently mandatory The result is only valid, if a processing context is assigned to the worker.

If no processing context is assigned, will always return 0 (false)

Parameters:

i_worker – [in] The worker handle
o_pProcessingMandatory – [out] If 1, the appying the processing context to the measurement is part of the mandatory processing steps

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_worker_start (CUVIS_WORKER i_worker): Start the worker.

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_worker_stop (CUVIS_WORKER i_worker): Pause the worker.

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_worker_drop_all_queued (CUVIS_WORKER i_worker): Command the worker to discard all measurements it is currently processing and empty the result queue.

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_worker_is_processing (CUVIS_WORKER i_worker, CUVIS_INT *o_pIsProcessing)

Query wether the worker is currently allowed to process measurements - wether it is running.

Parameters:

i_worker – [in] The worker handle
o_pIsProcessing – [out] If 1, the worker is allowed process measurements. This does not mean, that it is currently working on a measurement - see cuvis_worker_get_threads_busy

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_worker_get_threads_busy (CUVIS_WORKER i_worker, CUVIS_INT *o_pThreadsBusy)

Query how many measurements the worker is processing right now.

Parameters:

i_worker – [in] The worker handle
o_pThreadsBusy – [out] The number of measurements currently being processed

SDK_CAPI CUVIS_STATUS SDK_CCALL cuvis_worker_get_state (CUVIS_WORKER i_worker, CUVIS_WORKER_STATE *o_pWorkerState)

Query multiple attributes of the worker at once, see cuvis_worker_state_t.

Parameters:

i_worker – [in] The worker handle
o_pWorkerState – [out] Collection of worker stats

Examples

group Examples

There are several examples delivered with the SDK.

Overview

Under Windows you can find the examples in your installation directory (Default: “C:\Program Files\Cuvis\sdk\cuvis_c\examples” or “C:\Program Files\Cuvis\sdk\cuvis_cpp\examples”), under Linux they can be found in “/lib/cuvis/cuvis_c/examples” or “/lib/cuvis/cuvis_cpp/examples” . Each Example comes with the precompiled binary, a short .sh-script to run the application and the source code file. The .sh-script requires the bash console. Under windows we recommend to use Git Bash.

Examples 01-04 and 07 require the “sample_data” folder to be present in the installation directory ( Windows: “C:\Program Files\Cuvis\sdk\sample_data” , Linux: “/lib/cuvis/sample_data”). Examples 05-06 require a camera to be installed and connected.

Compiling examples

Instead of using the precompiled examples, you can use the provided source code to compile it yourself. Under Linux this is quite simple.

sudo apt install gcc
sudo gcc -o 0X_example main.c  -L/lib/cuvis -lcuvis

or

sudo apt install g++
sudo g++ -o 0X_example main.cpp  -L/lib/cuvis -lcuvis -std=c++17