Cuvis Python API

class cuvis.AcquisitionContext.AcquisitionContext(base: Calibration | SessionFile, *, simulate: bool = False)

property auto_exp: bool

property auto_exp_comp: float

property average: int

property bandwidth: int

property binning: bool

capture(to_interal=False) → AsyncMesu | None

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 (int, in) – the acquisition context

• o_pAsyncResult (int, out) – the async capture handle will be written to this variable or NULL

Return type:

int

Returns:

status_ok if the async call could be executed.

capture_at(timeout_ms: int) → Measurement

Capture a measurement

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

Parameters:

• i_acqCont (int, in) – the acquisition context

• o_pMesu (int, out) – the handle of the recorded image will be written to this variable

• timeout_ms (int, in) – the timeout in ms. Give 0 to wait for ever.

Return type:

int

Returns:

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

property component_count: int

Get the number of components

The acquisition hardware is build from one or more components. Get the component count. :type i_acqCont: int, in :param i_acqCont: the acquisition context :type o_pCount: int, out :param o_pCount: the number of components is written here :rtype: int :return: cuvis_ok if the number of components could be set

components()

Returns an iterator over all components

property fps: float

get_next_measurement(timeout_ms: int) → Measurement

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 (int, in) – the acquisition context

• o_pMesu (int, out) – the handle of the recorded image will be written to this variable.

• timeout_ms (int, in) – the timeout in ms. Give 0 to wait for ever.

Return type:

int

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.

has_next_measurement() → bool

check if any measurements are available in the buffer

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

Parameters:

• i_acqCont (int, in) – the acquisition context

• o_pHasNext (int, in) – value of 0 is written, if no measurements are available. value > 0, if a measurement is available.

Return type:

int

Returns:

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

property integration_time: float

property operation_mode: OperationMode

property queue_size: int

property queue_used: int

property ready: bool

get initialization state of the acquisition context

Parameters:

• i_acqCont (int, in) – the acquisition context

• o_pIsReady (int, out) – whether the acquisition context has completed all initialization tasks

Return type:

int

Returns:

status_ok, if no internal error occurred.

register_ready_callback(callback: Callable[[None], Awaitable[None]]) → None

register_state_change_callback(callback: Callable[[HardwareState, list[tuple[str, bool]]], Awaitable[None]]) → None

reset_ready_callback() → None

reset_state_change_callback() → None

property session_info: SessionData

get the acquisition session_info

Get the acquisition session_info settings. Also use this function to get the current sequence number. :type i_acqCont: int, in :param i_acqCont: the acquisition context :type o_pSessionInfo: cuvis_session_info_t, out :param o_pSessionInfo: the state will be written here :rtype: int :return: status_ok, if no internal error occurred.

set_auto_exp_async(val: bool) → Async

set_auto_exp_comp_async(val: float) → Async

set_average_async(avg: int) → Async

set_binning_async(val: bool) → Async

set_continuous(val: bool) → None

set_continuous_async(val: bool) → Async

set_fps_async(val: float) → Async

set_integration_time_async(val: float) → Async

set_operation_mode_async(val: OperationMode) → Async

property state: HardwareState

get the online state of the hardware

Hardware can be used, when at least it’s required components are online. :type i_acqCont: int, in :param i_acqCont: the acquisition context :type o_pState: int, out :param o_pState: the state will be written here :rtype: int :return: status_ok, if no internal error occurred.

class cuvis.AcquisitionContext.Component(acq: AcquisitionContext, idx: int)

property available_pixel_formats: list[str]

property gain: float

property integration_time_factor: float

property online: bool

property pixel_format: str

property temperature: float

class cuvis.Async.Async(handle)

get(timeout_ms: int | timedelta) → AsyncResult

class cuvis.Async.AsyncMesu(handle)

get(timeout_ms: int | timedelta) → tuple[Measurement | None, AsyncResult]

class cuvis.Calibration.Calibration(base: Path | str | SessionFile)

get_capabilities(operation_mode: OperationMode) → Capabilities

property id: str

property info: CalibrationInfo

class cuvis.cuvis_aux.Bitset(value)

all()

“Returns a bitset containing all possible members of the current Bitset class

classmethod from_strings(*values: list[str])

“ Creates a Bitset from a list of strings

strings() → list[str]

“Returns a list containing the string values of the current members of the Bitset

classmethod supremum()

“Returns a bitset containing all possible members of the current Bitset class

class cuvis.cuvis_aux.CalibrationInfo(model_name: str, serial_no: str, calibration_date: datetime.datetime, annotation_name: str, unique_id: str, file_path: str)

annotation_name: str

calibration_date: datetime

file_path: str

model_name: str

serial_no: str

unique_id: str

class cuvis.cuvis_aux.Capabilities(value: int)

class cuvis.cuvis_aux.GPSData(longitude: float, latitude: float, altitude: float, time: datetime.datetime)

altitude: float

latitude: float

longitude: float

time: datetime

class cuvis.cuvis_aux.MeasurementFlags(value: int)

exception cuvis.cuvis_aux.SDKException(*args)

class cuvis.cuvis_aux.SensorInfo(averages: int, temperature: int, gain: float, readout_time: datetime.datetime, width: int, height: int, raw_frame_id: int, pixel_format: str, binning: bool)

averages: int

binning: bool

gain: float

height: int

pixel_format: str

raw_frame_id: int

readout_time: datetime

temperature: int

width: int

class cuvis.cuvis_aux.SessionData(name: str, session_number: int, sequence_number: int)

name: str

sequence_number: int

session_number: int

class cuvis.cuvis_aux.WorkerState(measurementsInQueue: int, sessionFilesInQueue: int, framesInQueue: int, measurementsBeingProcessed: int, resultsInQueue: int, hasAcquisitionContext: bool, isProcessing: bool)

framesInQueue: int

hasAcquisitionContext: bool

isProcessing: bool

measurementsBeingProcessed: int

measurementsInQueue: int

resultsInQueue: int

sessionFilesInQueue: int

class cuvis.cuvis_types.AsyncResult(value)

An enumeration.

deferred = 3

done = 0

overwritten = 2

timeout = 1

class cuvis.cuvis_types.ComponentType(value)

An enumeration.

ImageSensor = 1

MiscSensor = 2

class cuvis.cuvis_types.DataType(value)

An enumeration.

data_type_gps = 3

data_type_image = 2

data_type_sensor_info = 5

data_type_string = 4

data_type_unsupported = 1

class cuvis.cuvis_types.HardwareState(value)

An enumeration.

Offline = 3

Online = 1

PartiallyOnline = 2

class cuvis.cuvis_types.OperationMode(value)

An enumeration.

External = 1

Internal = 2

Software = 3

UNDEFINED = 4

class cuvis.cuvis_types.PanSharpeningAlgorithm(value)

An enumeration.

AlphaBlendOverlay = 4

CubertMacroPixel = 2

CubertPanRatio = 3

Noop = 1

class cuvis.cuvis_types.PanSharpeningInterpolationType(value)

An enumeration.

Cubic = 3

Lanczos = 4

Linear = 2

NearestNeighbour = 1

class cuvis.cuvis_types.ProcessingMode(value)

An enumeration.

DarkSubtract = 3

Preview = 1

Raw = 2

Reflectance = 4

SpectralRadiance = 5

class cuvis.cuvis_types.ReferenceType(value)

An enumeration.

Dark = 1

Distance = 5

SpRad = 4

White = 2

WhiteDark = 3

class cuvis.cuvis_types.SessionItemType(value)

An enumeration.

all_frames = 1

no_gaps = 2

references = 3

class cuvis.cuvis_types.TiffCompressionMode(value)

An enumeration.

LZW = 2

Nothing = 1

class cuvis.cuvis_types.TiffFormat(value)

An enumeration.

MultiChannel = 2

MultiPage = 3

Single = 1

class cuvis.Export.CubeExporter(fs: SaveArgs)

class cuvis.Export.EnviExporter(ge: EnviExportSettings)

class cuvis.Export.Exporter

apply(mesu: Measurement) → Measurement

flush()

property queue_used: int

class cuvis.Export.TiffExporter(fs: TiffExportSettings)

class cuvis.Export.ViewExporter(fs: ViewExportSettings)

class cuvis.FileWriteSettings.EnviExportSettings(export_dir: str = '.', channel_selection: str = 'all', spectra_multiplier: int = 1, pan_scale: float = 0.0, pan_sharpening_interpolation_type: cuvis.cuvis_types.PanSharpeningInterpolationType = <PanSharpeningInterpolationType.Linear: 2>, pan_sharpening_algorithm: cuvis.cuvis_types.PanSharpeningAlgorithm = <PanSharpeningAlgorithm.CubertMacroPixel: 2>, pre_pan_sharpen_cube: bool = False, add_pan: bool = False, add_fullscale_pan: bool = False, permissive: bool = False)

class cuvis.FileWriteSettings.GeneralExportSettings(export_dir: str = '.', channel_selection: str = 'all', spectra_multiplier: int = 1, pan_scale: float = 0.0, pan_sharpening_interpolation_type: cuvis.cuvis_types.PanSharpeningInterpolationType = <PanSharpeningInterpolationType.Linear: 2>, pan_sharpening_algorithm: cuvis.cuvis_types.PanSharpeningAlgorithm = <PanSharpeningAlgorithm.CubertMacroPixel: 2>, pre_pan_sharpen_cube: bool = False, add_pan: bool = False, add_fullscale_pan: bool = False, permissive: bool = False)

add_fullscale_pan: bool = False

add_pan: bool = False

channel_selection: str = 'all'

export_dir: str = '.'

pan_scale: float = 0.0

pan_sharpening_algorithm: PanSharpeningAlgorithm = 2

pan_sharpening_interpolation_type: PanSharpeningInterpolationType = 2

permissive: bool = False

pre_pan_sharpen_cube: bool = False

spectra_multiplier: int = 1

class cuvis.FileWriteSettings.ProcessingArgs(allow_recalib: bool = False, processing_mode: cuvis.cuvis_types.ProcessingMode = <ProcessingMode.Raw: 2>)

allow_recalib: bool = False

processing_mode: ProcessingMode = 2

class cuvis.FileWriteSettings.SaveArgs(export_dir: str = '.', channel_selection: str = 'all', spectra_multiplier: int = 1, pan_scale: float = 0.0, pan_sharpening_interpolation_type: cuvis.cuvis_types.PanSharpeningInterpolationType = <PanSharpeningInterpolationType.Linear: 2>, pan_sharpening_algorithm: cuvis.cuvis_types.PanSharpeningAlgorithm = <PanSharpeningAlgorithm.CubertMacroPixel: 2>, pre_pan_sharpen_cube: bool = False, add_pan: bool = False, add_fullscale_pan: bool = False, permissive: bool = False, allow_overwrite: bool = False, allow_fragmentation: bool = False, allow_drop: bool = False, allow_session_file: bool = True, allow_info_file: bool = True, operation_mode: cuvis.cuvis_types.OperationMode = <OperationMode.Software: 3>, fps: float = 0.0, soft_limit: int = 20, hard_limit: int = 100, max_buftime: int = 10000, full_export: bool = False)

allow_drop: bool = False

allow_fragmentation: bool = False

allow_info_file: bool = True

allow_overwrite: bool = False

allow_session_file: bool = True

fps: float = 0.0

full_export: bool = False

hard_limit: int = 100

max_buftime: int = 10000

operation_mode: OperationMode = 3

soft_limit: int = 20

class cuvis.FileWriteSettings.TiffExportSettings(export_dir: str = '.', channel_selection: str = 'all', spectra_multiplier: int = 1, pan_scale: float = 0.0, pan_sharpening_interpolation_type: cuvis.cuvis_types.PanSharpeningInterpolationType = <PanSharpeningInterpolationType.Linear: 2>, pan_sharpening_algorithm: cuvis.cuvis_types.PanSharpeningAlgorithm = <PanSharpeningAlgorithm.CubertMacroPixel: 2>, pre_pan_sharpen_cube: bool = False, add_pan: bool = False, add_fullscale_pan: bool = False, permissive: bool = False, compression_mode: str = <TiffCompressionMode.Nothing: 1>, format: str = <TiffFormat.MultiChannel: 2>)

compression_mode: str = 1

format: str = 2

class cuvis.FileWriteSettings.ViewExportSettings(export_dir: str = '.', channel_selection: str = 'all', spectra_multiplier: int = 1, pan_scale: float = 0.0, pan_sharpening_interpolation_type: cuvis.cuvis_types.PanSharpeningInterpolationType = <PanSharpeningInterpolationType.Linear: 2>, pan_sharpening_algorithm: cuvis.cuvis_types.PanSharpeningAlgorithm = <PanSharpeningAlgorithm.CubertMacroPixel: 2>, pre_pan_sharpen_cube: bool = False, add_pan: bool = False, add_fullscale_pan: bool = False, permissive: bool = False, userplugin: dataclasses.InitVar[str] = <property object at 0x7f5055e329d0>)

property userplugin: str

class cuvis.FileWriteSettings.ViewerSettings(userplugin: dataclasses.InitVar[str] = <property object at 0x7f504cedc180>, pan_scale: float = 0.0, pan_sharpening_interpolation_type: cuvis.cuvis_types.PanSharpeningInterpolationType = <PanSharpeningInterpolationType.Linear: 2>, pan_sharpening_algorithm: cuvis.cuvis_types.PanSharpeningAlgorithm = <PanSharpeningAlgorithm.CubertMacroPixel: 2>, pre_pan_sharpen_cube: bool = False, complete: bool = False, blend_opacity: float = 0.0)

blend_opacity: float = 0.0

complete: bool = False

pan_scale: float = 0.0

pan_sharpening_algorithm: PanSharpeningAlgorithm = 2

pan_sharpening_interpolation_type: PanSharpeningInterpolationType = 2

pre_pan_sharpen_cube: bool = False

property userplugin: str

class cuvis.FileWriteSettings.WorkerSettings(input_queue_size: int = 0, mandatory_queue_size: int = 4, supplementary_queue_size: int = 4, output_queue_size: int = 10, can_skip_measurements: bool = False, can_skip_supplementary_steps: bool = True, can_drop_results: bool = True)

can_drop_results: bool = True

can_skip_measurements: bool = False

can_skip_supplementary_steps: bool = True

input_queue_size: int = 0

mandatory_queue_size: int = 4

output_queue_size: int = 10

supplementary_queue_size: int = 4

class cuvis.General.ComponentInfo(type: cuvis.cuvis_types.ComponentType = None, display_name: str = None, sensor_info: str = None, user_field: str = None, pixel_format: str = None)

display_name: str = None

pixel_format: str = None

sensor_info: str = None

type: ComponentType = None

user_field: str = None

cuvis.General.init(settings_path: str = '.', log_path: str = '', global_loglevel: int = 10)

cuvis.General.sdk_version() → str

cuvis.General.set_log_level(lvl)

cuvis.General.shutdown()

cuvis.General.version() → str

cuvis.General.wrapper_version() → str

class cuvis.Measurement.Measurement(base: int | str | Path)

property assembly: str

property averages: int

property calibration_id: str

property capabilities: Capabilities

property capture_time: datetime

clear_cube() → None

clear_implicit_reference(ref_type: ReferenceType) → None

property comment: str

property cube: ImageData

Retrieves or processes the ‘cube’ data for this Measurement.

This property prioritizes convenience over strict design principles: - Attempts to retrieve the ‘cube’ from self.data. - Lazily initializes a ProcessingContext if a session is available but uninitialized. - May trigger expensive processing and modify internal state during property access.

While functional, this approach introduces side effects and tight coupling, making it less predictable and not the cleanest solution. Suitable for specific workflows where these trade-offs are acceptable.

Raises:

ValueError – If the ‘cube’ is not available and processing is not possible.

Returns:

The ‘cube’ data, either retrieved from self.data or generated through processing.

Return type:

ImageData

property data_count: int

deepcopy()

property distance: float

property factory_calibration: datetime

property frame_id: int

property integration_time: int

property measurement_flags: MeasurementFlags

property name: str

property path: str

property processing_mode: ProcessingMode

property product_name: str

refresh() → None

save(saveargs: SaveArgs) → None

property serial_number: str

property session_info: SessionData

property thumbnail

class cuvis.ProcessingContext.ProcessingContext(base: Calibration | SessionFile | Measurement)

apply(mesu: Measurement) → Measurement

calc_distance(distMM: float) → bool

property calibration_id: str

clear_reference(refType: ReferenceType) → None

get_processing_args() → ProcessingArgs

get_reference(refType: ReferenceType) → Measurement

has_reference(refType: ReferenceType) → bool

is_capable(mesu: Measurement, pa: ProcessingArgs) → bool

property processing_mode: ProcessingMode

set_processing_args(pa: ProcessingArgs) → None

set_reference(mesu: Measurement, refType: ReferenceType) → None

class cuvis.SessionFile.SessionFile(base: Path | str)

property fps: float

get_measurement(frameNo: int = 0, itemtype: SessionItemType = SessionItemType.no_gaps) → Measurement | None

get_reference(frameNo: int, reftype: ReferenceType) → Measurement | None

get_size(itemtype: SessionItemType = SessionItemType.no_gaps) → int

property hash: str

property operation_mode: OperationMode

property thumbnail: ImageData

class cuvis.Viewer.Viewer(settings: int | ViewerSettings)

apply(mesu: Measurement) → dict[str, ImageData]

class cuvis.Worker.Worker(args: WorkerSettings)

property can_drop_results: bool

Query current drop behavior :type i_worker: int, in :param i_worker: The worker handle :type o_pCanDrop: int, out :param o_pCanDrop: If 1, the worker is allowed to drop results when the output queue is full

property can_skip_measurements: bool

Query current skip behavior :type i_worker: int, in :param i_worker: The worker handle :type o_pCanSkip: int, out :param o_pCanSkip: If 1, the worker is allowed to entirely skip processing measurements, if the mandatory queue is full

property can_skip_supplementary: bool

Query current skip behavior :type i_worker: int, in :param i_worker: The worker handle :type o_pCanSkip: int, out :param o_pCanSkip: If 1, the worker is allowed to skip supplementary processing of measurements, if the supplementary queue is full

drop_all_queued() → None

Command the worker to discard all measurements it is currently processing and empty the result queue.

get_next_result(timeout) → WorkerResult

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 (int, in) – The worker handle

• o_pMesu (int, out) – The recorded measurement or NULL if recording failed

• o_pView (int, out) – The view, if calculated sucessfully, else NULL

• i_Timeout_ms (int, in) – The number of milliseconds to wait for a result. -1 to wait indefinitely

Return type:

int

Returns:

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

async get_next_result_async(timeout: int) → WorkerResult

has_next_result() → bool

Check, if a new worker result is available

Parameters:

• i_worker (int, in) – The worker handle

• o_pHasNext (int, out) – 1 if a result is available now, else 0

ingest_mesu(mesu: Measurement) → None

Push a mesurement into the worker to process. Worker must have neither a session file nor an acquisition context.

ingest_session_file(session: SessionFile, frame_selection: str = 'all') → None

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.

property input_queue_limit: int

Query the maximum queue size of the input queue :type i_worker: int, in :param i_worker: The worker handle :type o_pInputQueueLimit: int, out :param o_pInputQueueLimit: The maximum size of the input queue

property is_processing: bool

Query wether the worker is currently allowed to process measurements - wether it is running. :type i_worker: int, in :param i_worker: The worker handle :type o_pIsProcessing: int, out :param o_pIsProcessing: 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

property is_processing_mandatory: bool

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) :type i_worker: int, in :param i_worker: The worker handle :type o_pProcessingMandatory: int, out :param o_pProcessingMandatory: If 1, the appying the processing context to the measurement is part of the mandatory processing steps

property mandatory_queue_limit: int

Query the maximum queue size of the mandatory queue :type i_worker: int, in :param i_worker: The worker handle :type o_pMandatoryLimit: int, out :param o_pMandatoryLimit: The maximum size of the mandatory queue. This is also the maximum number of measurements processed simultaneously

property output_queue_limit: int

Query the maximum queue size of the output queue :type i_worker: int, in :param i_worker: The worker handle :type o_pOutputQueueLimit: int, out :param o_pOutputQueueLimit: The maximum size of the output queue

property query_session_progress: float

Get the current percentage of frames done of the current session. -1.0 if no session file is currently being processed.

property queue_used: int

Query the number of items currently in the result queue. :type i_worker: int, in :param i_worker: The worker handle :type o_pQueueUsed: int, out :param o_pQueueUsed: The number of results currently in the output queue

register_worker_callback(callback: Callable[[WorkerResult], Awaitable[None]]) → None

reset_worker_callback() → None

set_acquisition_context(base: AcquisitionContext | None = None) → None

set the acquistion context for the worker. Give CUVIS_HANDLE_NULL to clear

set_exporter(base: Exporter | None = None) → None

set the exporter for the worker. Give CUVIS_HANDLE_NULL to clear

set_processing_context(base: ProcessingContext | None = None) → None

set the processing context for the worker. Give CUVIS_HANDLE_NULL to clear

set_viewer(base: Viewer | None = None) → None

set the viewer for the worker. Give CUVIS_HANDLE_NULL to clear

start_processing() → None

Start the worker

property state: WorkerState

Query multiple attributes of the worker at once, see cuvis_worker_state_t :type i_worker: int, in :param i_worker: The worker handle :type o_pWorkerState: cuvis_worker_state_t, out :param o_pWorkerState: Collection of worker stats

stop_processing() → None

Pause the worker

property supplementary_queue_limit: int

Query the maximum queue size of the supplementary queue :type i_worker: int, in :param i_worker: The worker handle :type o_pSupplementaryLimit: int, out :param o_pSupplementaryLimit: The maximum size of the supplementary queue. This is also the maximum number of measurements processed simultaneously

property threads_busy: int

Query how many measurements the worker is processing right now :type i_worker: int, in :param i_worker: The worker handle :type o_pThreadsBusy: int, out :param o_pThreadsBusy: The number of measurements currently being processed

class cuvis.Worker.WorkerResult(mesu: cuvis.Measurement.Measurement, view: cuvis.cube_utils.ImageData)

mesu: Measurement

view: ImageData