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
일련 번호는 이제 Zivid::CameraInfo
아래 구성됩니다. 이것은 Zivid:Camera::info()
를 통해 액세스되는 Zivid::Camera
의 멤버입니다.
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에서 캡처 설정은 주요 변경 사항 중 하나입니다. 가장 중요한 변경 사항은 단일 Zivid::Settings
개체에 다중 획득 캡처(HDR)를 포함한 모든 캡처 작업에 대한 완전한 설정이 포함되어 있다는 것입니다. 이는 HDR 캡처가 다음 중 하나로 표시되는 SDK 1.x와 대조됩니다.
Settings
개체의 목록 또는나중에 병합할 수 있는 Frames의 목록
SDK 2.0에서 Settings
개체는 두 가지 주요 부분으로 나뉩니다.
Zivid::Settings::Acquisitions
: Zivid 카메라 자체에서 이미지 수집 매개변수를 지정하는Zivid::Settings::Acquisition
의 목록입니다. 각Acquisition
에는 카메라 조리개(f-number) 및 프로젝터 밝기와 같은 설정이 포함됩니다.Zivid::Settings::Processing
: 카메라에서 획득한 이미지를 기반으로 PC GPU에서 발생하는 포인트 클라우드 처리의 매개변수를 지정합니다. 여기에는 필터링 설정 및 색상 설정이 포함됩니다.
둘째, 별도의 작업으로 캡처하기 전에 Settings
이 더 이상 카메라에 제공되지 않습니다. SDK 2.0에서 설정은 Zivid::Camera::capture(Zivid::Settings)
에 인수로 전달됩니다. 사용자는 원하는 만큼 Zivid::Settings
부분을 지정할 수 있습니다. 나머지 카메라 모델의 적절한 기본값은 capture()
를 호출할 때 적용됩니다.
마지막으로 2D 캡처는 Zivid::Settings2D
를 동일한 캡처 기능인 Zivid::Camera::capture(Settings2D)
에 전달하여 수행됩니다. 새로운 Settings2D
는 새로운 Settings
와 유사하게 구성됩니다.
Zivid::Settings:Acquisition(s)
SDK 1.x에서 HDR 캡처는 Settings
목록을 구성하여 지정되었습니다. SDK 2.0에서는 모든 것이 단일 Settings
에 포함되며 HDR 캡처는 여러 Zivid::Settings::Acquisition
을 포함하도록 지정됩니다. 이는 설정을 구성할 때 생성하거나 나중에 예를 들어 추가할 수 있습니다. settings.acquisitions().emplaceBack(acquisition)
. 예를 보려면 CaptureHDRCompleteSettings 샘플을 참조하십시오.
다음은 이전 설정의 구성원과 새로운 Zivid::Settings::Acquisition
의 구성원 간의 관계를 요약한 것입니다.
|
→ |
|
|
→ |
|
|
→ |
|
|
→ |
|
|
→ |
이 설정은 제거되었습니다 |
Zivid::Settings::Processing
Filters
새로운 필터 Contrast Distortion 이 도입되었습니다. Zivid::Settings::Processing::Experimental::ContrastDistortion
.
참고
Contrast Distortion 필터는 이전 Contrast 값과 아무 관련이 없습니다.
필터는 Acquisitions 후에 적용되며 Zivid::Settings::Processing::Filters
아래와 같이 구성됩니다. 다음은 필터의 변경과 경우에 따라 변경된 방식을 보여줍니다.
|
→ |
이 필터가 제거되었습니다. 항상 활성화되어 있습니다. |
|
→ |
|
|
→ |
|
|
→ |
|
|
→ |
이 필터는 새로운 필터인 |
대비 필터는 대비 값 임계값에 따라 점을 제거했습니다. 노이즈 필터는 SNR value 를 기반으로 포인트를 제거합니다. SNR 및 대비 값은 다르게 계산되므로 두 필터가 다릅니다. 노이즈 필터는 대비 필터를 개선한 필터로 고려하십시오. 유사한 결과를 얻으려면 다른 임계값을 적용해야 합니다. 대비 임계값 3과 유사한 값은 노이즈 임계값 7입니다.
Color Balance
SDK 2.0에서는 색상 균형이 개선되었습니다. 색상 균형 설정은 이제 포인트 클라우드의 색상에만 영향을 미치고 계산된 XYZ 포인트 좌표에는 영향을 미치지 않습니다.
|
→ |
|
|
→ |
|
N/A |
→ |
|
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
Zivid::Settings
에는 이제 여러 수집에 대한 설정을 유지하는 벡터가 포함됩니다.
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
새 SDK의 Zivid::Camera
는 설정을 보유하지 않기 때문에 파일에서 설정을 로드하는 것은 Zivid::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으로 변경되었음을 참고하십시오.
Complete comparison of old and new .yaml for Zivid::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::Settings2D
를 구성하는 일반적인 접근 방식은 Zivid::Settings
를 구성하는 것과 동일합니다. 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
새로운 Zivid::Camera::capture()
API는 항상 설정(Settings)을 입력으로 사용합니다.
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
2D 이미지를 캡처하는 API는 capture 에 2D 를 포함하지 않습니다. 즉 Zivid::Camera::capture()
대신 Zivid::Camera::capture2D()
을 사용할 수 있습니다. Zivid::Camera::capture()
2D를 생성하는지 3D를 생성하는지 여부는 입력 매개변수 Zivid::Settings2D
또는 Zivid::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
SDK 2.0 이전에는 포인트 클라우드가 Zivid::Frame::getPointCloud()
를 통해 생성 되었습니다. 이 API는 GPU의 모든 데이터를 1200x1920x7 매트릭스의 시스템 메모리로 복사했습니다. Point Cloud 를 참조하십시오. SDK 2.0에서는 먼저 Zivid::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 |
---|---|---|---|
|
|
12 bytes |
28 MB |
|
|
16 bytes |
37 MB |
|
|
4 bytes |
9 MB |
|
|
4 bytes |
9 MB |
|
|
4 bytes |
9 MB |
|
|
16 bytes |
37 MB |
|
|
16 bytes |
37 MB |
|
|
4 bytes |
9 MB |
Copy selected data from GPU to system memory (Zivid-allocated)
사용자가 포인트 클라우드의 XYZ 좌표에만 관심이 있었다면 이전에는 Zivid::Frame::getPointCloud()
를 호출해야 했습니다. 이 기능은 모든 데이터를 시스템 메모리에 복사합니다. SDK 2.0에서는 PointCloud::copyPointsXYZ()
만 호출하면 더 빠르게 이를 달성할 수 있습니다. 마찬가지로 포인트 클라우드의 RGB 색상만 필요한 사용 사례를 고려하십시오.
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 시각화 모듈의 이름이 변경되고 이동되었습니다.
|
→ |
|
|
→ |
|
|
→ |
|
|
→ |
|
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
를 인수로 사용합니다.
|
→ |
|
1.8.1 |
2.0 |
---|---|
auto intrinsics = camera.intrinsics();
|
auto intrinsics = Zivid::Experimental::Calibration::intrinsics(camera);
|
Info
펌웨어 버전, 모델 이름 등을 가져오는 데 사용되는 Camera
의 멤버 기능이 제거되었습니다. 카메라에 대한 정보는 이제 Zivid::CameraInfo
아래에 정리됩니다. 이것은 Zivid::Camera::info()
를 통해 액세스되는 Zivid::Camera
의 멤버입니다.
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();
|