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

配置 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.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;