C#SDK移植指南

介绍

本指南重点介绍了API的更改。该流程遵循基于Zivid SDK的典型应用程序的流程。首先,将显示1.8.1版本中的代码示例,然后是2.0版本的示例。

例如:

1.8.1

2.0

You will find code snippets from SDK 1.8.1 on this side,
and code snippets from SDK 2.0 on this side.

初始化

应用程序的初始化方式没有变化。

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

连接

默认连接没有变化。

var camera = zivid.ConnectCamera();

连接 - 特定相机和列表相机

序列号现在组织在 Zivid.NET.CameraInfo 下。它是 Zivid.NET.Camera 的一个成员,通过 Zivid.NET.Camera.Info 访问。

1.8.1

2.0

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

连接 - File Camera(文件相机)

1.8.1

2.0

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

这里的变化是文件相机有了自己的文件类型。 Zivid文件相机(ZFC) 包含比普通Zivid数据文件 (ZDF) 更多的信息。

配置

3D设置 - 捕获助手

1.8.1

2.0

var suggestSettingsParameters =
    new Zivid.NET.CaptureAssistant.SuggestSettingsParameters(
        Duration.FromMilliseconds(900),
        Zivid.NET.CaptureAssistant.AmbientLightFrequency.none);

var settingsList = Zivid.NET.CaptureAssistant.SuggestSettings(
    camera, suggestSettingsParameters);
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);

请注意,SuggestSettings 移动到了 CaptureAssistant 命名空间中的新类 Assistant 中。

3D设置 - 手动配置

Zivid.NET.Settings

Zivid SDK 2.0对捕获设置进行了重大更改。最显着的变化是单个 Zivid.NET.Settings 对象现在包含了任何捕获任务的完整设置,包括多采集捕获(HDR)。这与SDK 1.x显著不同,在SDK 1.x中,HDR 捕获由以下方式表示:

  • Settings 对象列表,或

  • 可以在以后合并的帧列表

在SDK 2.0中, Settings 对象分为两个主要部分:

  • Zivid.NET.Settings.AcquisitionsZivid.NET.Settings.Acquisition 的列表指定了Zivid相机本身的图像采集参数。每个 Acquisition 都包含了诸如相机光圈(f-值)和投影仪亮度等设置。

  • Zivid.NET.Settings.Processing:指定了通过相机获取的图像在PC的GPU上发生的点云处理的参数。这包括过滤器设置和颜色设置。

其次, Settings 不再作为单独的操作在捕获之前提供给相机。在SDK 2.0中,设置作为参数传递给 Zivid.NET.Camera.capture(Zivid.NET.Settings) 。用户可以根据需要指定尽可能少或尽可能多的 Zivid.NET.Settings 的参数。剩余的相机模型适当的默认值将在调用 Capture() 时应用。

最后,通过将 Zivid.NET.Settings2D 传递给相同的捕获函数 Zivid.NET.Camera.Capture(Settings2D) 来执行2D捕获。新的 Settings2D 的结构类似于新的 Settings

Zivid.NET.Settings:Acquisition(s)

在SDK 1.0中,通过构造 Settings 列表来指定HDR捕获。在 SDK 2.0 中,所有内容都包含在单个 Settings 中,并且通过让其包含多个 Zivid.NET.Settings.Acquisition 来指定HDR捕获。这些可以在构建Settings时创建,或者稍后添加,例如 settings.Acquisitions.Add(acquisitionSettings)。如需查看示例,请参阅 CaptureHDRCompleteSettings 示例。

以下是旧设置成员与新 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 [1]

Zivid.NET.Settings.Bidirectional

此设置已被移除

Zivid.NET.Settings.Processing

Filters

加入了一个新的 对比度失真 过滤器, Zivid.NET.Settings.Processing.Experimental.ContrastDistortion

备注

对比度失真过滤器与旧的对比度值没有任何关系。

过滤器在采集后应用,并组织在 Zivid.NET.Settings.Processing.Filters 下。下面显示了过滤器是如何移动的,并且在某些情况下是如何改变的。

Zivid.NET.Settings.Filters.Saturated

此过滤器已删除。它将始终处于启用状态。

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

这个过滤器被一个新的过滤器取代 - Zivid.NET.Settings.Processing.Filters.Noise.Removal [2]

色彩均衡

SDK 2.0改进了色彩平衡。颜色平衡设置现在只影响点云的颜色,对计算的XYZ点坐标没有影响。

Zivid.NET.Settings.BlueBalance

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

Zivid.NET.Settings.RedBalance

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

N/A

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

示例:Settings中的单帧 → 单次采集

1.8.1

2.0

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

请注意 Settings 现在作为参数提供给捕获(capture )函数,而不是事先提供给相机。

示例:Settings中的HDR帧 → 多个采集

Zivid.NET.Settings 现在包含一个向量来保存多个采集的设置。

1.8.1

2.0

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

示例:导入YML文件

Zivid.NET.Camera 在新的SDK中不再保持settings的相关设置,从文件加载配置是在 Zivid.NET.Settings 中完成的。

1.8.1

2.0

camera.SetSettings(new Zivid.NET.Settings("Frame01.yml"));
var settings = new Zivid.NET.Settings("Settings.yml");

或者,在连接到相机时:

1.8.1

2.0

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

N/A

这里的主要变化是输入文件包含了所有采集的设置。以前我们每帧只有一个文件,现在我们有了一个包含所有内容的文件。还要注意在此上下文中名称从Frame更改为Acquisition。

Zivid.NET.Settings 的新旧 .yml 的完整比较

1.8.1

2.0

__version__: 3
Settings:
    Bidirectional: no
    BlueBalance: 1.081000
    Brightness: 1.000000
    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.000000
    Iris: 17
    RedBalance: 1.709000
__version__: 3
Settings:
    Bidirectional: no
    BlueBalance: 1.081000
    Brightness: 1.000000
    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.000000
    Iris: 27
    RedBalance: 1.709000
__version__: 3
Settings:
    Bidirectional: no
    BlueBalance: 1.081000
    Brightness: 1.000000
    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.000000
    Iris: 35
    RedBalance: 1.709000
__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

配置 Zivid.NET.Settings2D 的方法与 Zivid.NET.Settings 相同。请参阅 3D手动配置

Zivid.NET.Settings2D.Acquisition(采集设置 - 以前的帧设置)

Zivid.NET.Settings2D.Acquisition 的更改和 Zivid.NET.Settings.Acquisition 一样,请参阅 Acquisition Settings (3D)。请注意,2D 设置仅允许单次采集(无法进行多次采集2D HDR)。

Zivid.NET.Settings2D.Processing

请注意,我们不支持2D设置的过滤器。

色彩均衡

现在为2D设置添加了色彩平衡。配置 Zivid.NET.Settings2D.Processing.Color.Balance 与配置 Zivid.NET.Settings.Processing.Color.Balance 相同,参见 Color Balance (3D)

Capture

3D - 单次采集

新的 Zivid.NET.Camera.Capture() API总是将设置作为输入。

1.8.1

2.0

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

3D - 多次采集HDR

捕获是单次采集还是多次采集 (HDR) 由输入参数设置决定。调用签名始终是 Zivid.NET.Camera.Capture(Zivid.NET.Settings) ,无论是单次采集还是HDR。

2D采集

捕获2D图像的API 在 capture 中没有*2D*,即它是 Zivid.NET.Camera.Capture() 而不是 Zivid.NET.Camera.Capture2D()Zivid.NET.Camera.Capture() 生成2D还是3D由输入参数 Zivid.NET.Settings2DZivid.NET.Settings 给出。

1.8.1

2.0

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

方法ImageRGBA()将返回一个Zivid.NET.ImageRGBA实例,可以通过方法ToArray()和ToByteArray()从中访问颜色值。它们分别返回 ColorRGBA 的2D数组或 byte 的3D数组。

点云

在SDK 2.0之前,点云是通过Zivid.NET.Frame.getPointCloud()访问的。此API以1200x1920x7矩阵将所有数据从GPU复制到系统内存,请参阅 Point Cloud。在SDK 2.0中,您首先通过 Zivid.NET.Frame.pointCloud() 获取GPU上点云数据的句柄。此调用不会从GPU内存执行任何复制。然后,您可以根据需要有选择地复制数据。您甚至可以直接复制到您自己预先分配的内存中。

并且还引入了新的点云质量值: Signal-to-Noise-Ratio (SNR)。这个值替换了旧的对比度值,并且始终是非负非NaN的数值。

以下是新输出数据格式的完整列表以及如何从GPU复制它们:

返回类型

从GPU复制的函数

每像素数据

复制的总数据

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

将选定数据从GPU复制到系统内存(Zivid分配)

如果用户只对点云的XYZ坐标感兴趣,他们之前需要调用 Zivid.NET.Frame.GetPointCloud() 。然后,此函数会将所有数据复制到系统内存。在SDK 2.0中,这可以通过仅调用 PointCloud.CopyPointsXYZ() 更快地实现。同样的,考虑这样一个用例,我们只需要点云中的RGB颜色:

1.8.1

2.0

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++)
   {
    for(size_t 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行:将XYZ+RGBA+对比度数据从GPU复制到系统内存。
第6行:分配具有适当大小的Array仅用于保存RGB数据。
第6-14行:选择性地将RGB数据从系统内存的一部分复制到另一部分。
var colorsRGBA = frame.PointCloud.CopyColorsRGBA();
第1行:将颜色从GPU复制到一个三维数组
bytes (byte[height,width,4]), 表示4通道RGBA图像。

可视化

Zivid可视化模块已重命名和移动。

Vis3D

Visualization

Zivid.NET.CloudVisualizer

Zivid.NET.Visualization.Visualizer

Zivid.NET.CloudVisualizer.EnableColors

Zivid.NET.Visualization.Visualizer.ColorsEnabled

Zivid.NET.CloudVisualizer.EnableMeshing

Zivid.NET.Visualization.Visualizer.MeshingEnabled

1.8.1

2.0

var visualizer = new Zivid.NET.CloudVisualizer();
zivid.DefaultComputeDevice = visualizer.ComputeDevice;
...
visualizer.Show(frame);
visualizer.ShowMaximized();
visualizer.ResetToFit();
visualizer.EnableMeshing = true;
visualizer.EnableMeshing = true;
var visualizer = new Zivid.NET.Visualization.Visualizer();
...
visualizer.Show(frame);
visualizer.ShowMaximized();
visualizer.ResetToFit();
visualizer.MeshingEnabled = true;
visualizer.Run();

保存

3D

3D数据的保存方式没有变化。

frame.Save("Frame.zdf");

2D

1.8.1

2.0

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

Misc

内参

intrinsics() 函数从 Camera 类中移出并放置在 Experimental.NET.Calibration 命名空间内。它现在将 Camera 作为参数。

Zivid.NET.Camera.intrinsics()

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

1.8.1

2.0

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

环境

Zivid.NET.Environment.DataPath 被移除。

固件

Zivid.NET.Firmware 已从类更改为命名空间。这个命名空间包含一个新类,Zivid.NET.Firmware.Updater,它提供固件更新相关的功能。

Zivid.Firmware

Zivid.NET.Firmware

信息

Camera`里用于获取固件版本、型号名称等信息的成员函数已被删除。关于相机的信息现在被组织在 ``Zivid.NET.CameraInfo` 下。这是 Zivid.NET.Camera 的成员,可通过 Zivid.NET.Camera.Info 访问。

1.8.1

2.0

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