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 

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

Zivid::Application zivid;

Connect 

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

auto camera = zivid.connectCamera();

Connect - Specific Camera & List Cameras

The serial number is now organized under CameraInfo. This is a member of Camera which is accessed via Zivid:Camera::info().

1.8.1

2.0

auto camera = zivid.connectCamera(Zivid::SerialNumber{ "2020C0DE" });

auto camera = zivid.connectCamera(Zivid::CameraInfo::SerialNumber("2020C0DE"));

auto cameras = zivid.cameras();

for(auto cam : cameras)
{
      std::cout << "Detected camera: "
          <<cam.serialNumber() << std::endl;
}

auto cameras = zivid.cameras();

for(auto cam : cameras)
{
    std::cout << "Detected camera: "
        << cam.info().serialNumber() << std.endl;
}

Connect - File Camera

1.8.1	2.0
auto zdfFile = "MiscObjects.zdf"; auto camera = zivid.createFileCamera(zdfFile);	const auto cameraFile = "FileCameraZividOne.zfc"; auto camera = zivid.createFileCamera(cameraFile);

여기서 변경 사항은 파일 카메라가 자체 파일 형식을 지원하는 것입니다. Zivid 파일 카메라(ZFC)에는 일반 Zivid 데이터 파일(ZDF)보다 더 많은 정보가 포함되어 있습니다.

Configure 

Settings 3D - Capture Assistant

1.8.1

2.0

const auto suggestSettingsParameters = Zivid::CaptureAssistant::SuggestSettingsParameters{
    std::chrono::milliseconds{ 900 },
    Zivid::CaptureAssistant::AmbientLightFrequency::none
};
const auto settingsVector{ Zivid::CaptureAssistant::suggestSettings(camera, suggestSettingsParameters) };

const auto suggestSettingsParameters = Zivid::CaptureAssistant::SuggestSettingsParameters{
    Zivid::CaptureAssistant::SuggestSettingsParameters::AmbientLightFrequency::none,
    Zivid::CaptureAssistant::SuggestSettingsParameters::MaxCaptureTime{ std::chrono::milliseconds{ 900 } }
};
const auto settings = Zivid::CaptureAssistant::suggestSettings(camera, suggestSettingsParameters);

우리는 생성자에서 명시적 유형을 사용하며 Zivid::SuggestSettingsParameters 의 모든 하위 항목이 허용됩니다.

Settings 3D - Manual Configuration

Zivid::Settings

Zivid SDK 2.0 introduces major changes to the capture settings. The most significant change is that a single 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 an HDR capture was either represented by:

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

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

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

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::Camera::capture(Zivid::Settings). The user may specify as few or as many parts of 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 Settings2D to the same capture function, Zivid::Camera::capture(Settings2D). The new Settings2D is structured similarly to the new Settings.

Zivid::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::Settings::Acquisition. These may be created at the time of constructing the Settings, or added later with e.g. settings.acquisitions().emplaceBack(acquisition). To see an example, see CaptureHDRCompleteSettings.cpp sample.

다음은 이전 설정의 구성원과 새로운 Zivid::Settings::Acquisition 의 구성원 간의 관계를 요약한 것입니다.

`Settings::ExposureTime`	→	`Zivid::Settings::Acquisition::ExposureTime`
`Settings::Gain`	→	`Zivid::Settings::Acquisition::Gain`
`Settings::Brightness`	→	`Zivid::Settings::Acquisition::Brightness`
`Settings::Iris`	→	`Zivid::Settings::Acquisition::Aperture` [1]
`Settings::Bidirectional`	→	이 설정은 제거되었습니다

Zivid::Settings::Processing

Filters

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

참고

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

필터는 Acquisitions 후에 적용되며 Zivid::Settings::Processing::Filters 아래와 같이 구성됩니다. 다음은 필터의 변경과 경우에 따라 변경된 방식을 보여줍니다.

`Zivid::Settings::Filters::Saturated`	→	이 필터가 제거되었습니다. 항상 활성화되어 있습니다.
`Zivid::Settings::Filter::Gaussian`	→	`Zivid::Settings::Processing::Filters::Smoothing::Gaussian`
`Zivid::Settings::Filter::Outlier`	→	`Zivid::Settings::Processing::Filters::Outlier::Removal`
`Zivid::Settings::Filter::Reflection`	→	`Zivid::Settings::Processing::Filters::Reflection::Removal`
`Settings::Contrast`	→	이 필터는 새로운 필터인 `Zivid::Settings::Processing::Filters::Noise::Removal` 로 대체되었습니다. [2]

Color Balance

SDK 2.0에서는 색상 균형이 개선되었습니다. 색상 균형 설정은 이제 포인트 클라우드의 색상에만 영향을 미치고 계산된 XYZ 포인트 좌표에는 영향을 미치지 않습니다.

`Settings::BlueBalance`	→	`Zivid::Settings::Processing::Color::Balance::Blue`
`Settings::RedBalance`	→	`Zivid::Settings::Processing::Color::Balance::Red`
N/A	→	`Zivid::Settings::Processing::Color::Balance::Green` (New)

Example: Single Frame → Single Acquisition in Settings

1.8.1

2.0

camera << Zivid::Settings::Iris{ 20 }
       << Zivid::Settings::ExposureTime{ std::chrono::microseconds{ 10000 } }
       << Zivid::Settings::Brightness{ 1 }
       << Zivid::Settings::Gain{ 1 }
       << Zivid::Settings::Filters::Contrast::Enabled::yes
       << Zivid::Settings::Filters::Contrast::Threshold{ 5 };
const auto frame = camera.capture();

const auto settings = Zivid::Settings{
    Zivid::Settings::Acquisitions{
        Zivid::Settings::Acquisition{ Zivid::Settings::Acquisition::Aperture{ 5.66 },
                                Zivid::Settings::Acquisition::ExposureTime{ std::chrono::microseconds{ 10000 } },
                                Zivid::Settings::Acquisition::Brightness{ 1.0 },
                                Zivid::Settings::Acquisition::Gain{ 1.0 } } },
    Zivid::Settings::Processing::Filters::Noise::Removal::Enabled::yes,
    Zivid::Settings::Processing::Filters::Noise::Removal::Threshold{ 7.0 }
};
const auto frame = camera.capture(settings);

이제 Settings 이 미리 카메라에 제공되지 않고 캡처 기능에 대한 인수로 제공된다는 점에 유의하십시오.

Example: HDR Frame → Multiple Acquisitions in Settings

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

1.8.1

2.0

std::vector<Zivid::Settings> settingsVector;
for(const size_t iris : { 14U, 21U, 35U })
{
    std::cout << "Add settings for frame with iris = " << iris << std::endl;
    auto settings = Zivid::Settings::Settings();
    settings.set(Zivid::Settings::Iris{ iris });
    settingsVector.emplace_back(settings);
}

const auto settings = Zivid::Settings();
for(const auto aperture : { 10.90, 5.80, 2.83 })
{
     const auto acquisitionSettings = Zivid::Settings::Acquisition{
        Zivid::Settings::Acquisitions::Aperture{ aperture },
     }
     settings.acquisitions().emplaceBack(acquisitionSettings);
}

Example: From YML File

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

1.8.1	2.0
camera.setSettings(Zivid::Settings("Frame01.yml"));	const auto settings = Zivid::Settings("Settings.yml");

또는 카메라에 연결하는 동안 다음을 수행합니다.

1.8.1	2.0
auto camera = zivid.connectCamera(Zivid::Settings("Frame01.yml"));	N/A

여기서 주요 변경 사항은 입력 파일에 모든 수집에 대한 설정이 포함되어 있다는 것입니다. 이전에는 프레임당 하나의 파일이 있었습니다. 이제 모든 것이 포함된 하나의 파일이 있습니다. 이 변경 사항에서 이름이 Frame에서 Acquisition으로 변경되었음을 참고하십시오.

Zivid::Settings의 이전 .yaml과 새 .yaml의 전체 비교

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 Settings2D is equivalent to configuring Settings. See Settings 3D - Manual Configuration

Zivid::Settings2D::Acquisition (Acquisition settings - former Frame settings)

Zivid::Settings2D::Acquisition 에서 변경한 내용은 Zivid::Settings::Acquisition 에서 변경한 내용과 동일합니다. 자세한 내용은 Acquisition Settings (3D) 를 참조하세요. 2D 설정은 한 번의 수집만 허용합니다(다중 수집 2D HDR은 불가능).

Zivid::Settings2D::Processing

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

Color Balance

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

Capture 

3D - Single Acquisition

The new Camera::capture() API always takes settings as input.

1.8.1	2.0
auto frame = camera.capture();	auto frame = camera.capture(settings);

3D - Multi Acquisition HDR

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

2D Acquisition

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

1.8.1	2.0
auto frame2D = camera.capture2D(settings2D); auto image = frame2D.image<Zivid::RGBA8>();	auto frame2D = camera.capture(settings2D); auto image = frame2D.imageRGBA();

캡처된 이미지는 frame2D.image<Zivid::RGBA8>() 가 아닌 frame2D.imageRGBA() 를 통해 읽을 수 있습니다. 이미지는 항상 8비트 빨강, 녹색, 파랑 및 알파 채널이 있는 RGBA 픽셀의 2차원 배열입니다.

Point Cloud

Before SDK 2.0 the point cloud was accessed via 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 Frame::pointCloud(). This call does not perform any copying from GPU memory. Then you can selectively copy data based on what is required. You can even copy directly into your own pre-allocated memory.

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

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

Return type	Functions for copying from GPU	Data per pixel	Total data copied
`Zivid::Array2D<Zivid::PointXYZ>`	`PointCloud::copyPointsXYZ()` (또는 `PointCloud::copyData<Zivid::PointXYZ>()`)	12 bytes	28 MB
`Zivid::Array2D<Zivid::PointXYZW>`	`PointCloud::copyPointsXYZW()` (또는 `PointCloud::copyData<Zivid::PointXYZW>()`)	16 bytes	37 MB
`Zivid::Array2D<Zivid::PointZ>`	`PointCloud::copyPointsZ()` (또는 `PointCloud::copyData<Zivid::PointZ>()`)	4 bytes	9 MB
`Zivid::Array2D<Zivid::ColorRGBA>`	`PointCloud::copyColorsRGBA()` (또는 `PointCloud::copyData<Zivid::ColorRGBA>()`)	4 bytes	9 MB
`Zivid::Array2D<Zivid::SNR>`	`PointCloud::copySNRs()` (또는 `PointCloud::copyData<Zivid::SNR>()`)	4 bytes	9 MB
`Zivid::Array2D<Zivid::PointXYZColorRGBA>`	`PointCloud::copyData<PointXYZColorRGBA>()`	16 bytes	37 MB
`Zivid::Array2D<Zivid::PointXYZColorBGRA>`	`PointCloud::copyPointsXYZColorsBGRA()` (또는 `PointCloud::copyData<PointXYZColorBGRA>()`)	16 bytes	37 MB
`Zivid::Image<Zivid::ColorRGBA>`	`PointCloud::copyImageRGBA()`	4 bytes	9 MB

Copy selected data from GPU to system memory (Zivid-allocated)

If a user was only interested in the XYZ coordinates of the point cloud they would previously need to call Frame::getPointCloud(). This function would then copy all data to the system memory. In SDK 2.0 this may be achieved faster by only calling PointCloud::copyPointsXYZ(). Similarly, consider a use case where we only need the RGB colors from the point cloud:

1.8.1

2.0

const auto pointCloud = frame.getPointCloud();
cv::Mat rgb(pointCloud.height(), pointCloud.width(),
            CV_8UC3, cv::Scalar(0, 0, 0));

const auto height = pointCloud.height();
const auto width = pointCloud.width();

for(size_t i = 0; i < height; i++)
{
    for(size_t j = 0; j < width; j++)
    {
        auto &color = bgr.at<cv::Vec3b>(i, j);
        color[0] = pointCloud(i, j).red();
        color[1] = pointCloud(i, j).green();
        color[2] = pointCloud(i, j).blue();
    }
}

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

auto rgba = frame.pointCloud().copyColorsRGBA();
auto *dataPtr = const_cast<void *>(static_cast<const void *>(image.data()));
cv::Mat rgba(rgba.height(), rgba.width(), CV_8UC4, dataPtr);

Line 1: 색상이 GPU에서 Zivid::Array2D<Zivid::ColorRGBA> 을 사용하여 복사됩니다.

이는 데이터를 복사했음을 의미합니다.

Line 2: OpenCV 매트릭스를 사용하기에 데이터 포인터를 void* 로 캐스트합니다.

색상 정보는 행렬 형태로 저장됩니다.

Line 3: 이 데이터 블록을 OpenCV 매트릭스로 래핑합니다.

이것은 Zivid::ColorRGBA 의 레이아웃이 CV_8UC4의 레이아웃과 정확히 일치하기 때문에 가능합니다.

이 단계에서는 복사가 발생하지 않습니다.

Copy selected data from GPU to system memory (user-allocated)

위의 예에서 데이터의 소유권은 반환된 Zivid::Array2D<> 객체에 의해 유지되었습니다. 또는 사용자가 사전 할당된 메모리 버퍼를 Zivid::PointCloud::copyData(dataPtr) 에 제공할 수 있습니다. dataPtr 유형은 복사할 대상을 정의합니다(PointXYZ*, ColorRGBA* 등).

이제 위와 똑같은 사용 사례를 살펴보겠습니다. 그러나 이번에는 OpenCV가 필요한 스토리지를 할당하도록 한 다음 Zivid API에 GPU에서 이 메모리 위치로 데이터를 직접 복사하도록 요청합니다.

1.8.1

2.0

const auto pointCloud = frame.getPointCloud();
cv::Mat rgb(pointCloud.height(), pointCloud.width(),
             CV_8UC3, cv::Scalar(0, 0, 0));

const auto height = pointCloud.height();
const auto width = pointCloud.width();

for(size_t i = 0; i < height; i++)
{
    for(size_t j = 0; j < width; j++)
    {
        auto &color = bgr.at<cv::Vec3b>(i, j);
        color[0] = pointCloud(i, j).red();
        color[1] = pointCloud(i, j).green();
        color[2] = pointCloud(i, j).blue();
    }
}

Line 1: XYZ + RGBA + Contrast 데이터를 GPU에서 시스템 메모리로 복사합니다.
Line 3: 적절한 크기의 OpenCV 행렬을 할당합니다.
Line 8-17: 시스템 메모리에서RGB 데이터를 선택적으로 복사합니다.

const auto pointCloud = frame.pointCloud();
auto rgba = cv::Mat(pointCloud.height(), pointCloud.width(), CV_8UC4);
auto *dataPtr = reinterpret_cast<Zivid::ColorRGBA *>(rgba.data);
pointCloud.copyData(dataPtr);

Line 1: GPU에서 전체 포인트 클라우드에 대한 핸들을 가져옵니다.

Line 2: 적절한 크기의 OpenCV 행렬을 할당합니다.

Line 3: Zivid API가 복사할 데이터를 이해할 수 있도록

OpenCV 데이터 포인터를 ColorRGBA* 에 캐스팅합니다.

Line 4: RGBA 데이터를 OpenCV 메모리 버퍼에 직접 복사합니다.

Visualize 

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

`Vis3D` library	→	`Visualization` library
`Zivid::CloudVisualizer`	→	`Visualization::Visualizer`
`Zivid::CloudVisualizer::EnableColors`	→	`Visualization::Visualizer::ColorsEnabled`
`Zivid::CloudVisualizer::EnableMeshing`	→	`Visualization::Visualizer::MeshingEnabled`

1.8.1

2.0

Zivid::CloudVisualizer vis;
zivid.setDefaultComputeDevice(vis.computeDevice());
...
vis.showMaximized();
vis.show(frame);
vis.resetToFit();
vis.run();

Zivid::Visualization::Visualizer visualizer;
...
visualizer.showMaximized();
visualizer.show(frame);
visualizer.resetToFit();
visualizer.run();

여러 컴퓨팅 장치는 동시에 지원되지 않습니다. 따라서 setDefaultComputeDevice 에 대한 설정이 없어 졌습니다.

Save 

3D

3D 데이터가 저장되는 방식에는 변경 사항이 없습니다.

frame.save("Frame");

2D

1.8.1	2.0
frame2D.image<Zivid::RGBA8>().save("Image.png");	frame2D.imageRGBA().save("Image.png");

Misc 

Intrinsics

intrinsics() 함수는 Camera 클래스에서 가져와 Experimental::Calibration 네임스페이스에 배치됩니다. 이제 Camera 를 인수로 사용합니다.

Camera::intrinsics()

→

Zivid::Experimental::Calibration::intrinsics(camera)

1.8.1	2.0
auto intrinsics = camera.intrinsics();	auto intrinsics = Zivid::Experimental::Calibration::intrinsics(camera);

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 CameraInfo. This is a member of Camera, accessed via Camera::info().

1.8.1	2.0
auto firmwareVersion = camera.firmwareVersion();	auto firmwareVersion = camera.info().firmwareVersion();
auto modelName = camera.modelName();	auto modelName = camera.info().modelName();
auto majorRevision = camera.revision().majorRevision(); auto minorRevision = camera.revision().minorRevision();	auto majorRevision = camera.info().revision().major(); auto minorRevision = camera.info().revision().minor();
auto serialNumber = camera.serialNumber();	auto serialNumber = camera.info().serialNumber();
auto maxDataSize = camera.userDataMaxSizeBytes();	auto maxDataSize = camera.info().userData().maxSizeBytes().value();