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.Acquisitions：Zivid.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

The general approach to configure Zivid.NET.Settings2D is equivalent to configuring Zivid.NET.Settings. See Settings 3D Manual Configuration

Zivid.NET.Settings2D.Acquisition（采集设置 - 以前的帧设置）

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

请注意，我们不支持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.Settings2D 或 Zivid.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;