Application

The Zivid driver handle. Must be kept alive while operating the camera.

C++

class Application

Manager class for Zivid.

The Application class manages resources used by the Zivid SDK. It is required to have one instance of this class alive while using the SDK. Using any part of the SDK without a live Application is undefined behavior.

It is not possible to have more than one Application instance at a time. Creating a second Application instance before the first Application instance has been destroyed will trigger an exception. All objects (cameras, frames, etc.) from the previous Application instance must be destroyed before a new instance can be created.

Public Functions

inline Application()

Constructor.

When using the CUDA backend, this constructor first attempts to use the current CUDA context (the context bound to the calling thread via cuCtxSetCurrent). If a current context exists, it will be used for all GPU operations. If no current context exists, the SDK creates its own.

This enables seamless GPU interoperability with frameworks like PyTorch, CuPy, or TensorFlow that establish their own CUDA context. Simply initialize the framework before creating the Application:

// PyTorch establishes a CUDA context when first accessing the GPU
auto tensor = torch::zeros({1}, torch::kCUDA);

// Application will automatically use PyTorch's context
Zivid::Application app;

// GPU buffers can now be shared with PyTorch without context conflicts

When using a detected context, the SDK does not take ownership and will not destroy it. The user is responsible for ensuring the context outlives the Application.

For explicit context control, use the Application(CUDAContextPtr) constructor instead.

When using the OpenCL backend, this constructor always creates a new OpenCL context (OpenCL does not have a “current context” concept).

inline explicit Application(OpenCLContextPtr openclContext)

Constructor with user-provided OpenCL context.

Use this constructor to provide your own OpenCL context for GPU interoperability (e.g., OpenCL-OpenGL interop). Example for OpenCL with GL interop:

cl_context oclContext = ...; // Create with GL interop properties
Application app(OpenCLContextPtr{oclContext});

Parameters:: openclContext – OpenCL context (cl_context) for OpenCL backend

inline explicit Application(CUDAContextPtr cudaContext)

Constructor with user-provided CUDA context.

Use this constructor to provide your own CUDA context for GPU interoperability. Example:

CUcontext cuContext = ...; // Create CUDA context
Application app(CUDAContextPtr{cuContext});

Parameters:: cudaContext – CUDA context (CUcontext) for CUDA backend

Camera connectCamera()

Connect to the next available Zivid camera.

This method will throw an exception if no camera is currently in Available state.

Returns:: Zivid camera instance

Camera connectCamera(const CameraInfo::SerialNumber &serialNumber)

Connect to the Zivid camera with the specified serial number.

Parameters:: serialNumber – Connect to the camera with this serial number
Returns:: Zivid camera instance

Camera connectCamera(const CameraAddress &address)

Connect to the Zivid camera at the specified network address.

This method bypasses mDNS discovery and connects directly via TCP to the specified address. Use this when the camera is on a non-default subnet, mDNS is blocked, or when you otherwise want to connect without relying on discovery.

This method will throw an exception if no Zivid camera is reachable at the given address.

Parameters:: address – Hostname or IPv4 address of the camera
Returns:: Zivid camera instance

Camera createFileCamera(const Frame &frameWithDiagnostics)

Create a file camera from a captured frame.

A file camera is a virtual camera that replays a previously captured frame. It holds the raw sensor data from the original capture and reconstructs point clouds and color images from it, so it can be used to develop and test capture pipelines without physical camera hardware.

The frame must have been captured with Settings::Diagnostics::Enabled = yes, otherwise this method throws. The diagnostics data carries the raw sensor images required to replay the capture.

Because a file camera owns only the raw data from a single capture, the settings it can capture with are more restricted than those of a physical camera:

Processing settings (filters, color balance, resampling, etc.) may be changed freely.
Engine and Sampling (Pixel and Color) must match the values used for the original capture. If set to a value different from the original setting, the capture throws.
The number of acquisitions must not exceed the number stored in the file camera. Requesting fewer acquisitions is allowed and replays the corresponding subset; requesting more throws.
Acquisition values (Aperture, ExposureTime, Gain, Brightness) do not affect the captured data. The requested settings are recorded on the returned frame, but they do not change the underlying sensor data.
Settings left unset are set automatically before capture: Engine and Sampling are set from the file camera, while unset acquisition and processing fields are filled with the camera-model defaults.

The same restrictions apply to the 2D color acquisitions of a 2D or 2D+3D capture.

If you only need to adjust processing settings on an existing frame, Zivid::Experimental::reprocess() is a simpler alternative that reprocesses the frame directly.

Parameters:: frameWithDiagnostics – A frame captured with Settings::Diagnostics::Enabled = yes
Returns:: Zivid virtual camera instance

Camera createFileCamera(const std::string &cameraFile)

Create a virtual camera to simulate Zivid measurements by reading data from a file.

An example file camera may be found at zivid.com/downloads

This overload is deprecated. Use createFileCamera(const Frame &) instead. This overload will be removed in SDK 3.0.

Parameters:: cameraFile – Data file in ZFC format containing a Zivid File Camera
Returns:: Zivid virtual camera instance

std::vector<Camera> cameras()

Get a list of all cameras.

This method will return all discovered cameras that are connected to your PC or local network. This may include cameras that are not connectable from the SDK, because of misconfigured camera/PC network settings, etc. Check the CameraState Status enum to determine the state of a particular camera.

Returns:: A list of cameras including all physical cameras as well as virtual ones (e.g. cameras created by createFileCamera())

ComputeDevice computeDevice() const

The default compute device, used when connecting to new cameras.

Returns:: A compute device

std::string toString() const

Get string representation of the application.

Returns:: Application info as string

C#

class Application

Manager class for Zivid cameras.

The Application class manages resources used by the Zivid SDK. These resources will not be released until you manually invoke Dispose() (or use using). It is required to have one instance of this class alive while using the SDK. Using any part of the SDK without a live Application is undefined behavior.

It is not possible to have more than one Application instance at a time. Creating a second Application instance before the first Application instance has been manually disposed will trigger an exception. All objects (cameras, frames, etc.) from the previous Application instance must be disposed before a new instance can be created.

Public Functions

Camera ^ ConnectCamera ()

Connect to the next available Zivid camera.

This method will throw an exception if no camera is currently in Available state.

Returns:: Zivid camera instance

Camera ^ ConnectCamera (System::String ^ serialNumber)

Connect to the Zivid camera with the specified serial number.

Parameters:: serialNumber – Connect to the camera with this serial number
Returns:: Zivid camera instance

Camera ^ ConnectCamera (CameraAddress ^ address)

Connect to the Zivid camera at the specified network address.

Bypasses mDNS discovery and connects directly via TCP. Use when the camera is on a non-default subnet, mDNS is blocked, or when you otherwise want to connect without relying on discovery.

Parameters:: address – Hostname or IPv4 address of the camera
Returns:: Zivid camera instance

Camera ^ CreateFileCamera (Frame ^ frameWithDiagnostics)

Create a file camera from a captured frame.

A file camera is a virtual camera that replays a previously captured frame. It holds the raw sensor data from the original capture and reconstructs point clouds and color images from it, so it can be used to develop and test capture pipelines without physical camera hardware.

The frame must have been captured with Settings::Diagnostics::Enabled = yes, otherwise this method throws. The diagnostics data carries the raw sensor images required to replay the capture.

Because a file camera owns only the raw data from a single capture, the settings it can capture with are more restricted than those of a physical camera:

Processing settings (filters, color balance, resampling, etc.) may be changed freely.
Engine and Sampling (Pixel and Color) must match the values used for the original capture. If set to a value different from the original setting, the capture throws.
The number of acquisitions must not exceed the number stored in the file camera. Requesting fewer acquisitions is allowed and replays the corresponding subset; requesting more throws.
Acquisition values (Aperture, ExposureTime, Gain, Brightness) do not affect the captured data. The requested settings are recorded on the returned frame, but they do not change the underlying sensor data.
Settings left unset are set automatically before capture: Engine and Sampling are set from the file camera, while unset acquisition and processing fields are filled with the camera-model defaults.

The same restrictions apply to the 2D color acquisitions of a 2D or 2D+3D capture.

Parameters:: frameWithDiagnostics – A frame captured with Settings::Diagnostics::Enabled = yes
Returns:: Zivid virtual camera instance

Camera ^ CreateFileCamera (System::String ^ cameraFile)

Create a virtual camera to simulate Zivid measurements by reading data from a file.

An example file camera may be found at zivid.com/downloads

Deprecated:: Use CreateFileCamera(Frame ^) instead. This overload will be removed in SDK 3.0.

Parameters:: cameraFile – Data file in ZFC format containing a Zivid File Camera
Returns:: Zivid virtual camera instance

System::String ^ ToString () override

Get string representation of the application.

Returns:: Application info as string

Properties

System::Collections::Generic::IList< Camera^>^ Cameras

Return a collection of all available cameras.

This includes filecameras as well as physical ones

This method will return all discovered cameras that are connected to your PC or local network. This may include cameras that are not connectable from the SDK, because of misconfigured camera/PC network settings, etc. Check the Status enum to determine the state of a particular camera.

Return:: List with camera information for all connected Zivid camera

Zivid::NET::ComputeDevice^ ComputeDevice

The compute device used by the Application.

Return:: A compute device

Python

app = zivid.Application()