Porting Guide for C# SDK

Introduction 

이 가이드는 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.

Initialize 

어플리케이션이 초기화되는 방식에는 변경 사항이 없습니다.

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

Connect 

기본 연결에는 변경 사항이 없습니다.

var camera = zivid.ConnectCamera();

Connect - Specific Camera & List Cameras

일련 번호는 이제 Zivid.NET.CameraInfo 아래 구성됩니다. 이것은 Zivid.NET.Camera.Info 를 통해 액세스되는 Zivid.NET.Camera 의 멤버입니다.

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

Connect - 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)보다 더 많은 정보가 포함되어 있습니다.

Configure 

Settings 3D - Capture Assistant

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 로 이동했습니다.

Settings 3D - Manual Configuration

Zivid.NET.Settings

Zivid SDK 2.0에서 캡처 설정은 주요 변경 사항 중 하나입니다. 가장 중요한 변경 사항은 단일 Zivid.NET.Settings 개체에 다중 획득 캡처(HDR)를 포함한 모든 캡처 작업에 대한 완전한 설정이 포함되어 있다는 것입니다. 이는 HDR 캡처가 다음 중 하나로 표시되는 SDK 1.x와 대조됩니다.

Settings 개체의 목록 또는
나중에 병합할 수 있는 Frames의 목록

SDK 2.0에서 Settings 개체는 두 가지 주요 부분으로 나뉩니다.

Zivid.NET.Settings.Acquisitions: Zivid 카메라 자체에서 이미지 수집 매개변수를 지정하는 Zivid.NET.Settings.Acquisition 의 목록입니다. 각 Acquisition 에는 카메라 조리개(f-number) 및 프로젝터 밝기와 같은 설정이 포함됩니다.
Zivid.NET.Settings.Processing: 카메라에서 획득한 이미지를 기반으로 PC GPU에서 발생하는 포인트 클라우드 처리의 매개변수를 지정합니다. 여기에는 필터링 설정 및 색상 설정이 포함됩니다.

둘째, 별도의 작업으로 캡처하기 전에 Settings 이 더 이상 카메라에 제공되지 않습니다. SDK 2.0에서 설정은 Zivid.NET.Camera.capture(Zivid.NET.Settings) 에 인수로 전달됩니다. 사용자는 원하는 만큼 Zivid.NET.Settings 부분을 지정할 수 있습니다. 나머지 카메라 모델의 적절한 기본값은 Capture() 를 호출할 때 적용됩니다.

마지막으로 2D 캡처는 Zivid.NET.Settings2D 를 동일한 캡처 기능인 Zivid.NET.Camera.Capture(Settings2D) 에 전달하여 수행됩니다. 새로운 Settings2D 는 새로운 Settings 와 유사하게 구성됩니다.

Zivid.NET.Settings:Acquisition(s)

SDK 1.x에서 HDR 캡처는 Settings 목록을 구성하여 지정되었습니다. SDK 2.0에서는 모든 것이 단일 Settings 에 포함되며 HDR 캡처는 여러 Zivid.NET.Settings.Acquisition 을 포함하도록 지정됩니다. 이는 설정을 구성할 때 생성하거나 나중에 예를 들어 추가할 수 있습니다. 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

새로운 필터 Contrast Distortion 이 도입되었습니다. Zivid.NET.Settings.Processing.Experimental.ContrastDistortion.

참고

Contrast Distortion 필터는 이전 Contrast 값과 아무 관련이 없습니다.

필터는 Acquisitions 후에 적용되며 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]

Color Balance

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` (New)

Example: Single Frame → Single Acquisition in 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 이 미리 카메라에 제공되지 않고 캡처 기능에 대한 인수로 제공된다는 점에 유의하십시오.

Example: HDR Frame → Multiple Acquisitions in Settings

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

Example: From YML File

새 SDK의 Zivid.NET.Camera 는 설정을 보유하지 않기 때문에 파일에서 설정을 로드하는 것은 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으로 변경되었음을 참고하십시오.

Complete comparison of old and new .yml for Zivid.NET.Settings

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 를 구성하는 것과 동일합니다. Settings 3D Manual Configuration 을 참조하십시오.

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

Zivid.NET.Settings2D.Acquisition 의 변경 사항은 Zivid.NET.Settings.Acquisition 의 변경 사항과 동일합니다. Acquisition Settings (3D) 를 참조하십시오. 2D 설정은 하나의 획득만 허용합니다(다중 획득 2D HDR는 불가능).

Zivid.NET.Settings2D.Processing

2D 설정에 대한 필터는 지원하지 않습니다.

Color Balance

2D 설정에 색상 균형이 추가되었습니다. Zivid.NET.Settings2D.Processing.Color.Balance 를 구성하는 것은 Zivid.NET.Settings.Processing.Color.Balance 를 구성하는 것과 동일합니다. Color Balance (3D) 를 참조하십시오.

Capture 

3D - Single Acquisition

새로운 Zivid.NET.Camera.Capture() API는 항상 설정(Settings)을 입력으로 사용합니다.

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

3D - Multi Acquisition HDR

캡처가 단일 수집인지 다중 수집(HDR)인지 여부는 입력 매개변수 설정에 따라 결정됩니다. 단일 획득이든 HDR이든 상관없이 호출 서명은 항상 Zivid.NET.Camera.Capture(Zivid.NET.Settings) 입니다.

2D Acquisition

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 배열을 반환합니다.

Point Cloud

SDK 2.0 이전에는 포인트 클라우드가 Zivid.NET.Frame.getPointCloud() 를 통해 생성 되었습니다. 이 API는 GPU의 모든 데이터를 1200x1920x7 매트릭스의 시스템 메모리로 복사했습니다. Point Cloud 를 참조하십시오. SDK 2.0에서는 먼저 Zivid.NET.Frame.pointCloud() 를 통해 GPU의 포인트 클라우드 데이터를 얻습니다. 이 호출은 GPU 메모리에서 복사를 수행하지 않습니다. 그런 다음 필요한 항목에 따라 데이터를 선택적으로 복사할 수 있습니다. 사전 할당된 메모리에 직접 복사할 수도 있습니다.

새로운 포인트 클라우드 품질을 평가하는 Signal-to-Noise-Ratio (SNR) 이 도입되었습니다. 이것은 이전 Contrast 값을 대체하며 항상 음수가 아니고 NaN이 아닌 숫자입니다.

새로운 출력 데이터 형식의 전체 목록과 GPU에서 복사하는 방법은 다음과 같습니다:

Return type	Functions 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.CopySNR()`	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 (Zivid-allocated)

사용자가 포인트 클라우드의 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];
    }
}

Line 1: XYZ + RGBA + Contrast 데이터를 GPU에서 시스템 메모리로 복사합니다.
Line 6: RGB 데이터만 담을 수 있는 적절한 크기의 배열을 할당합니다.
Line 6-14: 시스템 메모리에서RGB 데이터를 선택적으로 복사합니다.

var colorsRGBA = frame.PointCloud.CopyColorsRGBA();

Line 1: 색상 정보가 GPU에서 3차원 배열로 복사되었습니다.

bytes (byte[height,width,4])는 4채널 RGBA 이미지를 나타냅니다.

Visualize 

Zivid 시각화 모듈의 이름이 변경되고 이동되었습니다.

`Vis3D` library	→	`Visualization` library
`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();

Save 

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

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

Environment

Zivid.NET.Environment.DataPath 가 제거되었습니다.

Firmware

Zivid.NET.Firmware 가 클래스에서 네임스페이스로 변경되었습니다. 이 네임스페이스는 펌웨어 업데이트 관련 기능을 제공하는 새로운 클래스 Zivid.NET.Firmware.Updater 를 보유하고 있습니다.

Zivid.Firmware

→

Zivid.NET.Firmware

Info

펌웨어 버전, 모델 이름 등을 가져오는 데 사용되는 Camera 의 멤버 기능이 제거되었습니다. 카메라에 대한 정보는 이제 Zivid.NET.CameraInfo 아래에 정리됩니다. 이것은 Zivid.NET.Camera.Info 를 통해 액세스되는 Zivid.NET.Camera 의 멤버입니다.

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;