Zivid::Application Class Reference

Manager class for Zivid. More...

#include <Zivid/Application.h>

Public Member Functions
	Application ()
	Constructor.
	Application (OpenCLContextPtr openclContext)
	Constructor with user-provided OpenCL context.
	Application (CUDAContextPtr cudaContext)
	Constructor with user-provided CUDA context.
ZIVID_CORE_EXPORT Camera	connectCamera ()
	Connect to the next available Zivid camera.
ZIVID_CORE_EXPORT Camera	connectCamera (const CameraInfo::SerialNumber &serialNumber)
	Connect to the Zivid camera with the specified serial number.
ZIVID_CORE_EXPORT Camera	connectCamera (const CameraAddress &address)
	Connect to the Zivid camera at the specified network address.
ZIVID_CORE_EXPORT Camera	createFileCamera (const Frame &frameWithDiagnostics)
	Create a file camera from a captured frame.
ZIVID_CORE_EXPORT Camera	createFileCamera (const std::string &cameraFile)
	Create a virtual camera to simulate Zivid measurements by reading data from a file.
ZIVID_CORE_EXPORT std::vector< Camera >	cameras ()
	Get a list of all cameras.
ZIVID_CORE_EXPORT ComputeDevice	computeDevice () const
	The default compute device, used when connecting to new cameras.
ZIVID_CORE_EXPORT std::string	toString () const
	Get string representation of the application.

Friends
Application	Detail::createApplicationForWrapper (Zivid::Detail::EnvironmentInfo::Wrapper wrapper)
Application	Detail::createApplicationForWrapper (Detail::EnvironmentInfo::Wrapper wrapper, OpenCLContextPtr openclContext, CUDAContextPtr cudaContext)

Detailed Description

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.

Constructor & Destructor Documentation

Application() [1/3]

Zivid::Application::Application ( )

inline

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).

Application() [2/3]

Zivid::Application::Application ( OpenCLContextPtr openclContext )

inlineexplicit

Constructor with user-provided OpenCL context.

Parameters

openclContext

OpenCL context (cl_context) for OpenCL backend

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});

Application() [3/3]

Zivid::Application::Application ( CUDAContextPtr cudaContext )

inlineexplicit

Constructor with user-provided CUDA context.

Parameters

cudaContext

CUDA context (CUcontext) for CUDA backend

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

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

Member Function Documentation

cameras()

ZIVID_CORE_EXPORT std::vector< Camera > Zivid::Application::cameras

(

)

Get a list of all cameras.

Returns

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

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.

computeDevice()

ZIVID_CORE_EXPORT ComputeDevice Zivid::Application::computeDevice

(

)

const

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

Returns

A compute device

connectCamera() [1/3]

ZIVID_CORE_EXPORT Camera Zivid::Application::connectCamera

(

)

Connect to the next available Zivid camera.

Returns

Zivid camera instance

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

connectCamera() [2/3]

ZIVID_CORE_EXPORT Camera Zivid::Application::connectCamera

(

const CameraAddress &

address

)

Connect to the Zivid camera at the specified network address.

Parameters

address

Hostname or IPv4 address of the camera

Returns

Zivid camera instance

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.

connectCamera() [3/3]

ZIVID_CORE_EXPORT Camera Zivid::Application::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

createFileCamera() [1/2]

ZIVID_CORE_EXPORT Camera Zivid::Application::createFileCamera

(

const Frame &

frameWithDiagnostics

)

Create a file camera from a captured frame.

Parameters

frameWithDiagnostics

A frame captured with Settings::Diagnostics::Enabled = yes

Returns

Zivid virtual camera instance

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.

createFileCamera() [2/2]

ZIVID_CORE_EXPORT Camera Zivid::Application::createFileCamera

(

const std::string &

cameraFile

)

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

Parameters

cameraFile

Data file in ZFC format containing a Zivid File Camera

Returns

Zivid virtual camera instance

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.

toString()

ZIVID_CORE_EXPORT std::string Zivid::Application::toString

(

)

const

Get string representation of the application.

Returns

Application info as string

Friends And Related Symbol Documentation

Detail::createApplicationForWrapper [1/2]

Application Detail::createApplicationForWrapper ( Detail::EnvironmentInfo::Wrapper wrapper, OpenCLContextPtr openclContext, CUDAContextPtr cudaContext )

friend

Detail::createApplicationForWrapper [2/2]

Application Detail::createApplicationForWrapper ( Zivid::Detail::EnvironmentInfo::Wrapper wrapper )

friend

---

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

• Zivid/Application.h