カスタムカメラキャリブレーション

14 分

この機能はkognic-ioのバージョン1.8.0で追加され、一部の機能はオプションの依存関係が必要です。インストールするにはpip install kognic-io[wasm]を実行してください。

キャリブレーションがサポートされている標準カメラキャリブレーションの一覧にない場合は、カスタムキャリブレーションを提供できます。以下の表にCustomCameraCalibrationオブジェクトの属性を示します。wasm_base64属性は、キャリブレーションを実装するWebAssemblyモジュールのbase64エンコード文字列です。test_cases属性は、作成時にキャリブレーションを検証するために使用されるTestCaseオブジェクトのリストです。キャリブレーションが正しいことを確認するために、いくつかのテストケースを提供することを推奨します。

キー	値	パラメータ
rotation_quaternion	RotationQuaternionオブジェクト	w, x, y, z
position	Positionオブジェクト	x, y, z
image_width	整数	なし
image_height	整数	なし
wasm_base64	文字列	なし
test_cases	TestCaseオブジェクトのリスト	point3d, point2d

CustomCameraCalibrationオブジェクトは、バイナリまたはwasmファイルから直接インスタンス化することができます。

calibration_file = CustomCameraCalibration.from_file("/path/to/calibration.wasm", ...)
calibration_binary = CustomCameraCalibration.from_bytes(b"...", ...)

WebAssemblyモジュールの操作を容易にするユーティリティセットを提供しています。具体的には、検証コードといくつかの異なる言語からWebAssemblyへのコンパイルコードを提供しています。このコードはPython関数およびkognicutilCLIの両方から利用できます。

WebAssemblyモジュール

WebAssemblyは、モジュールがproject_point_to_imageという関数をエクスポートする厳密なインターフェースに従う必要があります。この関数はfloat64型の3つの引数を受け取り、float64型の2つの値を返す必要があります。したがって、このインターフェースのWebAssemblyテキスト表現はfunc (param f64 f64 f64) (result f64 f64)となります。3つの引数は3D点のx、y、z座標です。2つの戻り値は画像平面に投影された点のxおよびy座標です。WebAssemblyはデフォルトでは複数の戻り値をサポートしていませんが、==!マルチバリュープロポーザルで有効化できます。

点が視野内にない場合、関数はxおよびy座標の両方に対してNaNを返す必要があります。

検証

これにはwasmtimeのインストールが必要です。wasmtimeはkognic-ioのオプションの依存関係です。インストールするにはpip install kognic-io[wasm]を実行してください。

検証コードはPython関数およびkognicutil CLIの両方で提供しています。検証する内容は以下を含みますが、これらに限りません。

モジュールがロードできること

関数が存在し、正しいシグネチャを持つこと

モジュールを使用して点を投影できること

テストケースが提供されている場合、点が正しく投影されること

Pythonでキャリブレーションを検証する方法は3つあります。

import kognic.io.tools.calibration.validation as wasm_validation
from kognic.io.model.calibration.camera.custom_camera_calibration import CustomCameraCalibration, Point2d, Point3d, TestCase

test_cases = [
    TestCase(
        point3d=Point3d(x=1.0, y=2.0, z=3.0),
        point2d=Point2d(x=2.0, y=5.6)
    ),
    TestCase(
        point3d=Point3d(x=1.0, y=1.0, z=-1.0),
        point2d=Point2d(x=float("nan"), y=float("nan")) # point is outside field of view
    )
]

wasm_file = "/path/to/calibration.wasm"
calibration = CustomCameraCalibration.from_bytes(wasm_file, test_cases=test_cases, ...)
wasm_bytes = calibration.to_bytes()

# Validate the calibration object
wasm_validation.validate_custom_camera_calibration(calibration, test_cases=test_cases)

# Validate the wasm file
wasm_validation.validate_wasm_file(wasm_file, test_cases=test_cases)

# Validate the wasm binary
wasm_validation.validate_wasm_bytes(wasm_bytes, test_cases=test_cases)

kognicutil CLIは以下のように使用できます。

kognicutil wasm validate calibration.wasm

コンパイル

Rust 1.82.0ではマルチバリューフィーチャーターゲット（関数からの複数値の返却）のサポートが削除されました。この機能はカスタムカメラキャリブレーションの動作に現在必要なため、RustおよびCargoのバージョンを1.82.0未満に固定する必要があります。

wasmファイルはできる限り小さく保つことを推奨します。不要な依存関係の使用は避けてください。例えば、標準ライブラリを使用する代わりに、一部の数学関数を自分で実装する方が望ましい場合があります。

上述のとおり、WebAssemblyモジュールは厳密なインターフェースに従う必要があり、コンパイルにはマルチバリュープロポーザルが必要です。WebAssemblyモジュールをいくつかの言語からコンパイルしやすくするユーティリティセットを提供しています。以下の表を参照してください。

言語	ターゲット	コンパイルツール	必要なバージョン
Rust	*.rs	rustc	< 1.82.0
Rust (Cargo)	Cargo.toml	cargo	< 1.82.0
C++	.cc, .cpp	emscripten	N/A
C	*.c	emscripten	N/A

ユーティリティはPython関数およびkognicutil CLIの両方で利用できます。Pythonからは以下のようにモジュールをコンパイルできます。

from kognic.io.tools.calibration.compilation import compile_to_wasm
wasm_binary = compile_to_wasm("path/to/source")

返されたバイナリはCustomCameraCalibrationオブジェクトの作成に使用できます。output_wasmパラメータが渡された場合、バイナリは指定されたパスに保存されます。kognicutil CLIは以下のように使用できます。

kognicutil wasm compile path/to/source path/to/output.wasm

コンパイル後にデフォルトで検証が実行されることに注意してください。これは--skip-validationフラグで無効化できます。

キャリブレーションパラメータはWebAssemblyモジュールで使用できるようにバイナリに埋め込む必要があります。ランタイム時の投

影関数の速度を上げるために、できる限り事前計算を行うようにしてください。

以下に、いくつかの異なる言語でのPinholeキャリブレーションの簡略版の例を示します。

例：Rust

これにはwasm32-wasiターゲットでRustをインストールする必要があります。こちらの手順に従ってRustをインストールし、rustup target add wasm32-wasiでターゲットを追加してください。

Rustファイルは以下のようにコンパイルできます。

kognicutil wasm compile path/to/source.rs path/to/output.wasm

panicsはサポートされていないため、コードに含まれている場合はコンパイルが失敗することに注意してください。

Cargoを使用したRust

これにはwasm32-wasiターゲットでRustとCargoをインストールする必要があります。こちらの手順に従ってRustとCargoをインストールし、rustup target add wasm32-wasiでターゲットを追加してください。

Cargoを使用したRustモジュールは以下のようにコンパイルできます。

kognicutil wasm compile path/to/source/Cargo.toml path/to/output.wasm

ライブラリがcdylibであることを指定することが重要であり、WebAssemblyモジュールのサイズを削減するためにstrip = trueを設定することも推奨されることに注意してください。これはCargo.tomlファイルに以下を追加することで行います。

[lib]
crate-type = ["cdylib"]

[profile.release]
strip = true

例：C++

これには Emscripten のインストールが必要です。こちらの手順に従ってインストールしてください。

C++ファイルは以下のようにコンパイルできます。

kognicutil wasm compile path/to/source.cc path/to/output.wasm

または以下のようにコンパイルできます。

kognicutil wasm compile path/to/source.cpp path/to/output.wasm

例：C

これにはEmscriptenのインストールが必要です。こちらの手順に従ってインストールしてください。

Cファイルは以下のようにコンパイルできます。

kognicutil wasm compile path/to/source.c path/to/output.wasm