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.

初期化する 

アプリケーションの初期化方法に変更はありません。

Zivid::Application zivid;

接続する 

デフォルトの接続に変更はありません。

auto camera = zivid.connectCamera();

接続 - 特定のカメラとリストカメラ

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

接続 - ファイルカメラ

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 File Camera (ZFC) には、通常の Zivid Data File (ZDF) よりも多くの情報が含まれています。

構成 

設定 3D - キャプチャアシスタント

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 のすべての子孫が受け入れられます。

設定 3D - 手動構成

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 オブジェクトのリスト、または
後でマージできるフレームのリスト

SDK 2.0 では、 Settings オブジェクトは 2 つの主要な部分に分かれています。

Zivid::Settings::Acquisitions : Zivid カメラ自体の画像取得のパラメータを指定する Zivid::Settings::Acquisition のリスト。各 Acquisition は、カメラの絞り (F 値) やプロジェクターの明るさなどの設定が含まれます。
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::設定:取得

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

フィルター

新しいフィルター Contrast Distortion 、 Zivid::Settings::Processing::Experimental::ContrastDistortion が導入されました。

注釈

コントラスト歪みフィルタは、古いコントラスト値とは何の関係もありません。

フィルターは取得後に適用され、 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] に置き換えられます。

カラーバランス

SDK 2.0でカラーバランスが改善されました。カラーバランス設定は、点群の色にのみ影響するようになり、計算された XYZ 点座標には影響しません。

`Settings::BlueBalance`	→	`Zivid::Settings::Processing::Color::Balance::Blue`
`Settings::RedBalance`	→	`Zivid::Settings::Processing::Color::Balance::Red`
該当なし	→	`Zivid::Settings::Processing::Color::Balance::Green` (新規)

例：設定で単一フレーム→単一取得

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 事前にカメラに与えられるのではなく、キャプチャ関数への引数として提供されることに注意してください。

例: HDR フレーム → 設定の複数取得

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

例: YML ファイルから

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"));	該当なし

ここでの主な変更点は、入力ファイルにすべての取得の設定が含まれていることです。以前はフレームごとに 1 つのファイルがありました。これで、すべてが含まれた 1 つのファイルが完成しました。この文脈では、名前が Frame から Acquisition に変更されていることにも注意してください。

Zivid::Settings の新旧 .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

設定 2D

The general approach to configure Settings2D is equivalent to configuring Settings. See 設定 3D - 手動構成

Zivid::Settings2D::Acquisition (取得設定 - 以前のフレーム設定)

Zivid::Settings2D::Acquisition に加えられた変更は、Zivid::Settings::Acquisition に加えられた変更と同等です。 Acquisition Settings (3D) を参照してください。2D 設定では 1 つの取得しか許可されないことに注意してください(複数取得による 2D HDR は不可能です)。

Zivid::Settings2D::Processing

2D 設定のフィルターはサポートされていないことに注意してください。

カラーバランス

2D 設定にカラーバランスが追加されました。Zivid::Settings2D::Processing::Color::Balance の設定は Zivid::Settings::Processing::Color::Balance の設定と同じです。 Color Balance (3D) を参照してください。

キャプチャ 

3D - 単一取得

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 - マルチ取得 HDR

キャプチャがシングル取得であるかマルチ取得 (HDR) であるかは、入力パラメータ設定によって決まります。呼び出し署名は、単一取得か HDR かに関係なく、常に Zivid::Camera::capture(Zivid::Settings) です。

2D取得

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 次元配列です。

点群

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.

新しい点群品質値 : 信号対雑音比 (SNR) も導入されました。これは古いコントラスト値を置き換えるもので、常に負ではない非 NaN の数値になります。

新しい出力データ形式の完全なリストと、それらを GPU からコピーする方法:

戻り値の型	GPUからコピーする関数	ピクセルごとのデータ	コピーされたデータの合計
`Zivid::Array2D<Zivid::PointXYZ>`	`PointCloud::copyPointsXYZ()` (または `PointCloud::copyData<Zivid::PointXYZ>()` )	12バイト	28MB
`Zivid::Array2D<Zivid::PointXYZW>`	`PointCloud::copyPointsXYZW()` (または `PointCloud::copyData<Zivid::PointXYZW>()` )	16バイト	37MB
`Zivid::Array2D<Zivid::PointZ>`	`PointCloud::copyPointsZ()` (または `PointCloud::copyData<Zivid::PointZ>()` )	4バイト	9MB
`Zivid::Array2D<Zivid::ColorRGBA>`	`PointCloud::copyColorsRGBA()` (または `PointCloud::copyData<Zivid::ColorRGBA>()` )	4バイト	9MB
`Zivid::Array2D<Zivid::SNR>`	`PointCloud::copySNRs()` (または `PointCloud::copyData<Zivid::SNR>()` )	4バイト	9MB
`Zivid::Array2D<Zivid::PointXYZColorRGBA>`	`PointCloud::copyData<PointXYZColorRGBA>()`	16バイト	37MB
`Zivid::Array2D<Zivid::PointXYZColorBGRA>`	`PointCloud::copyPointsXYZColorsBGRA()` (または `PointCloud::copyData<PointXYZColorBGRA>()` )	16バイト	37MB
`Zivid::Image<Zivid::ColorRGBA>`	`PointCloud::copyImageRGBA()`	4バイト	9MB

選択したデータを GPU からシステムメモリ (Zivid に割り当て) にコピーします

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

行 1: XYZ + RGBA + コントラスト データを GPU からシステム メモリにコピーします。
3 行目: RGB データのみを保持する適切なサイズの OpenCV マトリックスを割り当てます。
行 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);

行 1: カラーは GPU から Zivid::Array2D<Zivid::ColorRGBA> にコピーされます。

データの所有権を取得します。

行 2: データポインタを void* としてキャストします。これは OpenCV が行うものであるためです。

行列コンストラクタには必要があります。

3 行目: このデータブロックを OpenCV 行列でラップします。

Zivid::ColorRGBA のレイアウトが正確に一致しているため、これが可能です。

CV_8UC4のレイアウト。このステップではコピーは行われません。

選択したデータを GPU からシステムメモリ (ユーザー割り当て) にコピーします

上の例では、データの所有権は返された 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();
    }
}

行 1: XYZ + RGBA + コントラスト データを GPU からシステム メモリにコピーします。
3行目: OpenCVマトリックスを適切なサイズで割り当てます。
行 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);

行 1: GPU 上の完全な点群へのハンドルを取得します。

2 行目: 適切なサイズの OpenCV マトリックスを割り当てます。

行 3: OpenCV データポインターを ColorRGBA* にキャストして、Zivid API が

どのデータをコピーするかを理解します。

行 4: RGBA データを OpenCV メモリバッファに直接コピーします。

視覚化する 

Zivid 視覚化モジュールの名前が変更され、移動されました。

`Vis3D` ライブラリ	→	`Visualization` ライブラリ
`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 への呼び出しは冗長です。

保存 

3D

3D データの保存方法に変更はありません。

frame.save("Frame");

2D

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

その他 

内部パラメータ

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

情報

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

C++ SDK 移植ガイド

接続 - 特定のカメラとリストカメラ

接続 - ファイルカメラ

設定 3D - キャプチャ アシスタント

設定 3D - 手動構成

Zivid::Settings

Zivid::設定:取得

Zivid::Settings::Processing

例：設定で単一フレーム→単一取得

例: HDR フレーム → 設定の複数取得

例: YML ファイルから

設定 2D

Zivid::Settings2D::Acquisition (取得設定 - 以前のフレーム設定)

Zivid::Settings2D::Processing

3D - 単一取得

3D - マルチ取得 HDR

2D取得

点群

選択したデータを GPU からシステム メモリ (Zivid に割り当て) にコピーします

選択したデータを GPU からシステム メモリ (ユーザー割り当て) にコピーします

3D

2D

内部パラメータ

情報

設定 3D - キャプチャアシスタント

選択したデータを GPU からシステムメモリ (Zivid に割り当て) にコピーします

選択したデータを GPU からシステムメモリ (ユーザー割り当て) にコピーします