Porting Guide for C# SDK

Introduction

This guide focus on changes to the API. The flow follows that of a typical application based on the Zivid SDK.

 

1.8.1

1 You will find code snippets from SDK 1.8.1 on this side,

2.0

1 and code snippets from SDK 2.0 on this side.

Initialize

No change to how the application is initialized.

1 var zivid = new Zivid.NET.Application();

Connect

No change to default connection.

1 var camera = zivid.ConnectCamera();

Connect - Specific Camera & List Cameras

The Serial Number is now organized under Zivid.NET.CameraInfo. This is a member of Zivid.NET.Camerawhich is accessed via Zivid.NET.Camera.Info.

1 var camera = zivid.ConnectCamera(new Zivid.NET.SerialNumber("2020C0DE"));
1 var camera = zivid.ConnectCamera(new Zivid.NET.CameraInfo.SerialNumber("2020C0DE"));
1 2 3 4 5 var cameras = zivid.Cameras; foreach (var camera in cameras) { Console.WriteLine("Detected camera: {0}", camera.SerialNumber); }
1 2 3 4 5 var cameras = zivid.Cameras; foreach (var camera in cameras) { Console.WriteLine("Detected camera: {0}", camera.Info.SerialNumber); }

Connect - File Camera

1 2 var zdfFile = "MiscObjects.zdf"; var camera = zivid.CreateFileCamera(zdfFile);
1 2 var fileCamera = "FileCameraZividOne.zfc"; var camera = zivid.CreateFileCamera(fileCamera);

The change here is that the File Camera has received its own file type. A Zivid File Camera (ZFC) contains more information than a normal Zivid Data File (ZDF).

Configure

Settings 3D - Capture Assistant

1 2 3 4 5 6 7 var suggestSettingsParameters = new Zivid.NET.CaptureAssistant.SuggestSettingsParameters( Duration.FromMilliseconds(900), Zivid.NET.CaptureAssistant.AmbientLightFrequency.none); var settingsList = Zivid.NET.CaptureAssistant.SuggestSettings( camera, suggestSettingsParameters);
1 2 3 4 5 6 7 var suggestSettingsParameters = new Zivid.NET.CaptureAssistant.SuggestSettingsParameters { AmbientLightFrequency = Zivid.NET.CaptureAssistant.SuggestSettingsParameters.AmbientLightFrequencyOption.none, MaxCaptureTime = Duration.FromMilliseconds(900) }; var settings = Zivid.NET.CaptureAssistant.Assistant.SuggestSettings(camera, suggestSettingsParameters);

Note that SuggestSettings moved into a new class Assistant in the CaptureAssistant namespace

Settings 3D - Manual configuration

Zivid.NET.Settings

Zivid SDK 2.0 introduces major changes to the capture settings. The most significant change is that a single Zivid.NET.Settings object now contains complete settings for any capture task, including multi-acquisition capture (HDR). This is in contrast to SDK 1.x, in which a HDR capture was represented by a list of Settings objects (or a list of Frames that could be merged at a later time).

In SDK 2.0, a Settings object is divided into two main parts:

  • Zivid.NET.Settings.Acquisitions: A list of Zivid.NET.Settings.Acquisition, which specify the parameters of image-acquisition on the Zivid camera itself. Each Acquisition includes settings such as camera aperture (f-number) and projector brightness.

  • Zivid.NET.Settings.Processing: Specifies the parameters of the point-cloud processing occurring on the PC GPU, based on the images acquired on the camera. This includes filtering settings and color settings.

Secondly, the Settings is no longer given to the camera before capture as a separate operation. In SDK 2.0, settings are passed as an argument to Zivid.NET.Camera.Capture(Zivid.NET.Settings). The user may specify as few or as many parts of Zivid.NET.Settings as desired. The remaining camera-model appropriate defaults will be applied at the time of calling Capture().

Lastly, 2D-capture is performed by passing a Zivid.NET.Settings2D to the same capture function,Zivid.NET.Camera.Capture(Settings2D). The new Settings2D is structured similarly to the new Settings.

Zivid.NET.Settings.Acquisition(s)

In SDK 1, a HDR capture was specified by constructing a list of Settings. In SDK 2.0, everything is contained in a single Settings, and a HDR capture is specified by letting it contain multiple Zivid.NET.Settings.Acquisition. These may be created at the time of constructing the Settings, or added later with e.g. settings.Acquisitions.Add(acquisitionSettings). To see an example, see CaptureHDRCompleteSettings sample.

The following is a summary of the relation between members of old settings and the members of the new Zivid.NET.Settings.Acquisition:

Zivid.NET.Settings.ExposureTime

Zivid.NET.Settings.Acquisition.ExposureTime

Zivid.NET.Settings.Gain

Zivid.NET.Settings.Acquisition.Gain

Zivid.NET.Settings.Brightness

Zivid.NET.Settings.Acquisition.Brightness

Zivid.NET.Settings.Iris

Zivid.NET.Settings.Acquisition.Aperture*

Zivid.NET.Settings.Bidirectional

This setting is removed.

*The setting to control the Iris/Aperture is changed. The f-number unit is introduced. To change your iris values with equivalent aperture f-numbers, check out the IrisToAperture conversion list below.
Note: If the file doesn’t load in your browser, click the download icon.

Zivid.NET.Settings.Processing

Filters

A new filter Contrast Distortion is introduced, Zivid.NET.Settings.Processing.Experimental.ContrastDistortion. Note: This filter does not have anything to do with the old Contrast value.

Filters are applied after acquisitions and are organized under Zivid.NET.Settings.Processing.Filters. The following shows how filters have moved, and in some cases changed.

Zivid.NET.Settings.Filters.Saturated

This filter is removed. It is always enabled and not possible to disable.

Zivid.NET.Settings.Filter.Gaussian

Zivid.NET.Settings.Processing.Filters.Smoothing.Gaussian

Zivid.NET.Settings.Filter.Outlier

Zivid.NET.Settings.Processing.Filters.Outlier.Removal

Zivid.NET.Settings.Filter.Reflection

Zivid.NET.Settings.Processing.Filters.Reflection.Removal

Zivid.NET.Settings.Contrast

This filter is replaced with a new filter - Zivid.NET.Settings.Processing.Filters.Noise.Removal *

*The contrast filter removed points based on the contrast value threshold. The noise filter removes points based on the SNR value threshold. SNR and contrast values are computed differently, and the two filters are therefore different; Consider the noise filter as a contrast filter improvement. To achieve similar results, different threshold values must be applied. Similar value to a Contrast threshold of 3 is the Noise threshold value of 7.

Color Balance

Color balance is improved with SDK 2.0. Color balance settings now only affects the colors of the point cloud, and has no effect on the computed XYZ point coordinates.

Zivid.NET.Settings.BlueBalance

Zivid.NET.Settings.Processing.Color.Balance.Blue

Zivid.NET.Settings.RedBalance

Zivid.NET.Settings.Processing.Color.Balance.Red





Zivid.NET.Settings.Processing.Color.Balance.Green (New)

Example: Single Frame → Single Acquisition in Settings

1 2 3 4 5 6 7 8 9 10 camera.UpdateSettings(settings => { settings.Iris = 20; settings.ExposureTime = Duration.FromMicroseconds(10000); settings.Brightness = 1; settings.Gain = 1; settings.Filters.Contrast.Enabled = true; settings.Filters.Contrast.Threshold = 5; }); var frame = camera.Capture();
1 2 3 4 5 6 7 8 9 10 var settings = new Zivid.NET.Settings { Acquisitions = { new Zivid.NET.Settings.Acquisition{ Aperture = 5.66, ExposureTime = Duration.FromMicroseconds(8333), Brightness = 1, Gain = 1} }, Processing = { Filters = { Noise = { Removal = { Enabled = true, Threshold = 5.0 } } } } }; var frame = camera.Capture(settings);

Note how Settings is now provided as an argument to the capture function, not given to the camera beforehand.

Example: HDR Frame → Multiple Acquisitions in Settings

Zivid.NET.Settings now contains a vector to hold settings for multiple acquisitions.

1 2 3 4 5 6 7 8 9 10 var frames = new List<Zivid.NET.Frame>(); foreach (var iris in new ulong[] { 14, 21, 35 }) { camera.UpdateSettings(settings => { settings .Iris = iris; }); frames.Add(camera.Capture()); } var hdrFrame = Zivid.NET.HDR.CombineFrames(frames);
1 2 3 4 5 6 7 var settings = new Zivid.NET.Settings(); foreach (var aperture in new double[] { 11.31, 5.66, 2.83 }) { var acquisitionSettings = new Zivid.NET.Settings.Acquisition { Aperture = aperture }; settings.Acquisitions.Add(acquisitionSettings); } var frame = camera.Capture(settings);

Example: From YML File

Since Zivid.NET.Camera does not hold settings in the new SDK, loading settings from file is done onZivid.NET.Settings.

1 camera.SetSettings(new Zivid.NET.Settings("Frame01.yml"));

Alternatively, while connecting to the camera:

1 var camera = zivid.ConnectCamera(new Zivid.NET.Settings("Frame01.yml"));
1 var settings = new Zivid.NET.Settings("Settings.yml");

The main change here is that the input file contains settings for all acquisitions. Previously we had one file per Frame. Now we have one file with everything. Note also the name change from Frame to Acquisition in this context.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 __version__: 3 Settings: Bidirectional: no BlueBalance: 1.081000 Brightness: 1.8 ExposureTime: 10000 Filters: Contrast: Enabled: yes Threshold: 3.000000 Gaussian: Enabled: yes Sigma: 1.500000 Outlier: Enabled: yes Threshold: 20.000000 Reflection: Enabled: yes Saturated: Enabled: yes Gain: 1.0 Iris: 17 RedBalance: 1.709000 __version__: 3
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 Settings: Bidirectional: no BlueBalance: 1.081000 Brightness: 1.8 ExposureTime: 10000 Filters: Contrast: Enabled: yes Threshold: 3.000000 Gaussian: Enabled: yes Sigma: 1.500000 Outlier: Enabled: yes Threshold: 20.000000 Reflection: Enabled: yes Saturated: Enabled: yes Gain: 1.0 Iris: 27 RedBalance: 1.709000 __version__: 3
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 Settings: Bidirectional: no BlueBalance: 1.081000 Brightness: 1.8 ExposureTime: 10000 Filters: Contrast: Enabled: yes Threshold: 3.000000 Gaussian: Enabled: yes Sigma: 1.500000 Outlier: Enabled: yes Threshold: 20.000000 Reflection: Enabled: yes Saturated: Enabled: yes Gain: 4.0 Iris: 35 RedBalance: 1.709000
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 __version__: serializer: 1 data: 4 Settings: Acquisitions: - Acquisition: Aperture: 7.98 Brightness: 1.8 ExposureTime: 10000 Gain: 1 - Acquisition: Aperture: 4.02 Brightness: 1.8 ExposureTime: 10000 Gain: 1 - Acquisition: Aperture: 2.81 Brightness: 1.8 ExposureTime: 10000 Gain: 4 Processing: Color: Balance: Blue: 1.081 Green: 1 Red: 1.709 Filters: Experimental: ContrastDistortion: Correction: Enabled: no Strength: 0.4 Removal: Enabled: no Threshold: 0.5 Noise: Removal: Enabled: yes Threshold: 7 Outlier: Removal: Enabled: yes Threshold: 5 Reflection: Removal: Enabled: yes Smoothing: Gaussian: Enabled: yes Sigma: 1.5

Settings 2D

The general approach to configure Zivid.NET.Settings2D is equivalent to configuring Zivid.NET.Settings, see Settings 3D - Manual configuration.

Zivid.NET.Settings2D.Acquisition (Acquisition settings - former Frame settings)

The changes made on Zivid.NET.Settings2D.Acquisition are equivalent to the changes made on Zivid.NET.Settings.Acquisition, see Acquisition Settings (3D). Note that 2D settings allow only one acquisition (multi acquisition 2D HDR is not possible).

Zivid.NET.Settings2D.Processing

Note that we don’t support filters for 2D settings.

Color Balance

Color balance is now added for 2D settings. Configuring Zivid.NET.Settings2D.Processing.Color.Balance is the same as configuring Zivid.NET.Settings.Processing.Color.Balance, see Color Balance (3D).

Capture

3D - Single Acquisition

The new Zivid.NET.Camera.Capture() API always takes settings as input.

1 var frame = camera.Capture();
1 var frame = camera.Capture(settings);

3D - Multi Acquisition HDR

Whether the capture is a single acquisition or multi-acquisition (HDR) is given by the input parameter settings. The call signature is always Zivid.NET.Camera.Capture(Zivid.NET.Settings), regardless of whether it is single acquisition or HDR.

2D

The API to capture 2D image doesn’t have 2D in capture, i.e. it is Zivid.NET.Camera.Capture() instead of Zivid.Camera.Capture2D(). Whether Zivid.NET.Camera.Capture() produces 2D or 3D is given by the input parameter, Zivid.NET.Settings2D or Zivid.NET.Settings.

1 2 var frame2D = camera.Capture2D(settings); var image = frame2D.Image<Zivid.NET.RGBA8>();
1 2 var frame2D = camera.Capture(settings2D); var image = frame2D.ImageRGBA();

The method ImageRGBA() returns a Zivid.Net.ImageRGBA instance, from which color values may be accessed through methods ToArray() and ToByteArray(). These return a 2D array of ColorRGBA or a 3D array of byte, respectively.

Point Cloud

Before SDK 2.0 the point cloud was accessed via Zivid.NET.Frame.GetPointCloud(). This API copied all data from GPU to system memory in a 1200x1920x7 matrix, see Point Cloud. In SDK 2.0 you first get a handle to the point cloud data on the GPU through Zivid.NET.Frame.PointCloud(). This call does not perform any copying from GPU memory. Then you can selectively copy data based on what is required.

A new point-cloud quality value has also been introduced: Signal-to-Noise-Ratio (SNR). This replaces the old Contrast value, and is always a non-negative non-NaN number.

Complete list of new output data-formats and how to copy them from the GPU:

Return type

Methods for copying from GPU

Data per pixel

Total data copied

Return type

Methods for copying from GPU

Data per pixel

Total data copied

float[height,width,3]

PointCloud.CopyPointsXYZ()

12 bytes

28 MB

float[height,width,4]

PointCloud.CopyPointsXYZW()

16 bytes

37 MB

float[height,width,1]

PointCloud.CopyPointsZ()

4 bytes

9 MB

byte[height,width,4]

PointCloud.CopyColorsRGBA()

4 bytes

9 MB

float[height,width]

PointCloud.CopySNRs()

4 bytes

9 MB

Zivid.NET.PointXYZColorRGBA[height, width]

PointCloud.CopyPointsXYZColorsRGBA()

16 bytes

37 MB

Zivid.NET.PointXYZColorBGRA[height, width]

PointCloud.CopyPointsXYZColorsBGRA()

16 bytes

37 MB

Zivid.NET.ImageRGBA

PointCloud.CopyImageRGBA()

4 bytes

9 MB

 

Copy selected data from GPU to system memory

Even if a user is only concerned about the XYZ coordinates of the point cloud they would previously need to call Zivid.NET.Frame.GetPointCloud(), which would copy all data to the system memory. In SDK 2.0 this may be achieved faster by only calling Zivid.NET.PointCloud.CopyPointsXYZ(). Similarly, consider a use case where we only need the RGB colors from the point cloud:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 var pointCloud = frame.GetPointCloud(); var height = pointCloud.Height; var width = pointCloud.Width; var pointCloudArray = pointCloud.ToArray(); float[,,] colorsRGB = new float[width, height, 3]; for (ulong i = 0; i < height; i++) { for (ulong j = 0; j < width; j++) { colorsRGB[i, j, 0] = pointCloudArray[i, j, 3]; colorsRGB[i, j, 1] = pointCloudArray[i, j, 4]; colorsRGB[i, j, 2] = pointCloudArray[i, j, 5]; } }
1 var colorsRGBA = frame.PointCloud.CopyColorsRGBA();

 

 

 

 

Line 1: Copy XYZ + RGBA + Contrast data from GPU to system memory.

Line 6: Allocate Array with an appropriate size to hold just the RGB data.

Line 6-14: Selectively copy RGB data from one part of system memory to another.

Line 1: Colors are copied from the GPU and into a three-dimensional array of bytes (byte[height,width,4]), representing a 4-channel RGBA image.

Visualize

The Zivid visualization module is renamed and moved.

Vis3D library

Visualization library

Zivid::CloudVisualizer

Zivid::Visualization::Visualizer

Zivid::CloudVisualizer::EnableColors

Zivid::Visualization::Visualizer::ColorsEnabled

Zivid::CloudVisualizer::EnableMeshing

Zivid::Visualization::Visualizer::MeshingEnabled

1 2 3 4 5 6 7 8 var visualizer = new Zivid.NET.CloudVisualizer(); zivid.DefaultComputeDevice = visualizer.ComputeDevice; ... visualizer.Show(frame); visualizer.ShowMaximized(); visualizer.ResetToFit(); visualizer.EnableMeshing = true; visualizer.Run();
1 2 3 4 5 6 7 var visualizer = new Zivid.NET.Visualization.Visualizer(); ... visualizer.Show(frame); visualizer.ShowMaximized(); visualizer.ResetToFit(); visualizer.MeshingEnabled = true; visualizer.Run();

Save

3D

No change to how 3D data is saved.

1 frame.Save("Frame.zdf");

2D

1 frame2D.Image<Zivid.NET.RGBA8>().Save("Image.png");
1 frame2D.ImageRGBA().Save("Image.png");

Misc

Intrinsics

Function intrinsics() is taken out of the Camera class and placed in the Experimental.NET.Calibration namespace. It now takes Camera as an argument.

Zivid.NET.Camera.Intrinsics

Zivid.NET.Experimental.Calibration.Calibrator.Intrinsics(Zivid.NET.Camera)

1 var intrinsics = camera.Intrinsics;
1 var intrinsics = Zivid.NET.Experimental.Calibration.Calibrator.Intrinsics(camera);

Environment

Zivid.NET.Environment.DataPath is removed.

Firmware

Zivid.NET.Firmware has been changed from a class to a namespace. This namespace holds a new class, Zivid.NET.Firmwar.Updater, which provides firmware-update related functionality.

Zivid.Firmware

Zivid.NET.Firmware

Info

The member functions on Camera that used to get firmware version, model name, etc. have been removed. Information about the camera is now organized under Zivid.NET.CameraInfo. This is a member of Zivid.NET.Camera, accessed via Zivid.NET.Camera.Info.

1 var firmwareVersion = camera.FirmwareVersion;
1 var firmwareVersion = camera.Info.FirmwareVersion;
1 var modelName = camera.ModelName;
1 var modelName = camera.Info.ModelName;
1 2 var majorRevision = camera.Revision.Major; var minorRevision = camera.Revision.Minor;
1 2 var majorRevision = camera.Info.Revision.Major; var mainorRevision = camera.Info.Revision.Minor;
1 var serialNumber = camera.SerialNumber;
1 var serialNumber = camera.Info.SerialNumber;
1 var maxDataSize = camera.UserDataMaxSizeBytes;
1 var maxDataSize = camera.Info.UserData.MaxSizeBytes;