---
title: カスタムカメラキャリブレーション
slug: api-guide/ja/_aHf1soJHYBji7pOzbP3i
docTags: 
createdAt: 2024-12-17T10:20:02.287Z
---

:::hint{type="info"}
### 注記

この機能は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ファイルから直接、簡単にインスタンス化できます。

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

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

## 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はデフォルトでは複数の戻り値をサポートしていませんが、[multi-value](https://github.com/WebAssembly/multi-value)プロポーザルを使用すると有効にできます。

点が視野内にない場合、関数はxおよびy座標の両方に対して[NaN](https://en.wikipedia.org/wiki/NaN)を返してください。

## 検証

:::hint{type="info"}
### 注記

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

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

1. モジュールがロードできること
2. 関数が存在し、正しいシグネチャを持つこと
3. モジュールを使用して点を投影できること
4. テストケースが提供されている場合、点が正しく投影されること

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

```python
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は以下のように使用できます。

```bash
kognicutil wasm validate calibration.wasm
```

## コンパイル

:::hint{type="warning"}
### 注意

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

:::hint{type="info"}
### 注記

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

上述のとおり、WebAssemblyモジュールは厳密なインターフェースに従う必要があり、コンパイルにはmulti-valueプロポーザルが必要です。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からは以下のようにモジュールをコンパイルできます。

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

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

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

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

キャリブレーションパラメータはWebAssemblyモジュールで使用できるようにバイナリに埋め込む必要があります。実行時の投影関数を高速化するため、できる限り事前計算を行ってください。

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

### 例：Rust

:::hint{type="info"}
### 注記

これには`wasm32-wasi`ターゲットでRustをインストールする必要があります。[こちら](https://www.rust-lang.org/tools/install)の手順に従ってRustをインストールし、`rustup target add wasm32-wasi`でターゲットを追加してください。
:::

[Rustファイル](https://github.com/annotell/kognic-io-examples-python/tree/master/examples/calibration/custom/pinhole.rs)は以下のようにコンパイルできます。

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

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

### Cargoを使用したRust

:::hint{type="info"}
### 注記

これには`wasm32-wasi`ターゲットでRustとCargoをインストールする必要があります。[こちら](https://doc.rust-lang.org/cargo/getting-started/installation.html)の手順に従ってRustとCargoをインストールし、`rustup target add wasm32-wasi`でターゲットを追加してください。
:::

[Cargoを使用したRustモジュール](https://github.com/annotell/kognic-io-examples-python/tree/master/examples/calibration/custom/pinhole-rust-cargo)は以下のようにコンパイルできます。

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

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

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

[profile.release]
strip = true
```

### 例：C++

:::hint{type="info"}
### 注記

これにはEmscriptenのインストールが必要です。[こちら](https://emscripten.org/docs/getting_started/downloads.html)の手順に従ってインストールしてください。
:::

[C++ファイル](https://github.com/annotell/kognic-io-examples-python/tree/master/examples/calibration/custom/pinhole.cc)は以下のようにコンパイルできます。

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

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

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

### 例：C

:::hint{type="info"}
### 注記

これにはEmscriptenのインストールが必要です。[こちら](https://emscripten.org/docs/getting_started/downloads.html)の手順に従ってインストールしてください。
:::

[Cファイル](https://github.com/annotell/kognic-io-examples-python/tree/master/examples/calibration/custom/pinhole.c)は以下のようにコンパイルできます。

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