ZED SDK で複数のZED カメラを使う

## 想定する読者
stereolabsのzed2, zed mini, zed x などのステレオカメラの利用者
いまどきのステレオカメラは何ができるのかを知りたい人

## 前提
ZED SDK 4.0
Ubuntu 20.04
ZED2i

以下の説明は、USB接続のZED2i を用いた範囲の記述です。
ZED-X のようなGMSL接続のカメラについては、この文書ではサポートしていません。

## 複数台のZEDカメラはどう見えるのか
USB接続のZED2iでは、/dev/video* にカメラが認識されている。1台のZED2iカメラは2つの/dev/video* に対応します。

```
ls /dev/video*
```

### cv2.VideoCapture()の場合
- 左カメラ・右カメラが左右に連結された１枚の画像をcap.read()します。
- ZEDカメラを２台にした場合には、cv2.VideoCapture(0), cv2.VideoCapture(2)をそれぞれ用意することになります。
- /dev/video0, /dev/video2といったデバイスの番号がどのように、実際のカメラに割り振られるのかについて、簡単に分かる方法がありません。
- ですから、cv2.VideoCapture()を使う方法はおすすめしません。
### Linux の cheese アプリケーション
- cheese アプリケーションでもその連結された１枚の画像を読み込みます。
- cheese アプリケーションでも入力のカメラを変更することができます。 
##### 複数台のカメラを接続したときに意識しなくちゃならなくなること
- どのUSBポートの接続されたのが、どういう順番でOSには認識されているのかということ。
- その設定は、再起動のたびに保たれるのかどうかということ。


## 接続されているZEDカメラを知る方法

```.py:
import inspect
import pyzed.sl as sl
camera_list = sl.Camera.get_camera_list()
for camera in camera_list:
    print(camera)
    for k, v in inspect.getmembers(camera):
        print(k, v)
```

## serial_number を指定して ZEDカメラを開く
以下のようにするとカメラのシリアル番号固定でZEDカメラを開くことができる。

```.py:
zed = sl.Camera()
init_params = sl.InitParameters()
init_params.set_from_serial_number(serial_number)
err = zed.open(init_params)
```

## stereolabs のサイトのmulti-cameraのドキュメント
https://www.stereolabs.com/docs/video/multi-camera

USB3.0 のインタフェースでの通信量の上限とZED カメラの通信量とが語られている。
解像度とフレーレートの組合せでは、PCIeの拡張ボードが必要になることを述べています。
また、解像度とDEPTH_MODEの組合せでは、GPUのメモリを増やす必要があることを述べています・

またUSB3.0 の帯域の中での接続可能な組合せは、以下のように記載がありました。
[Using a single USB 3.0 controller, here are configurations that we tested:
2 ZEDs in HD1080 @ 15fps and HD720 @ 30fps
3 ZEDs in HD720 @ 15fps
4 ZEDs in VGA @ 30fps](https://github.com/stereolabs/zed-sdk/tree/master/depth%20sensing/multi%20camera/cpp#:~:text=Using%20a%20single,in%20VGA%20%40%2030fps)


https://www.stereolabs.com/docs/video/multi-camera#setting-up-multiple-cameras-on-a-local-network

複数台のカメラにするとそれらの同期が必要になってきます。
Precision Time Protocol (PTP or IEEE1588)　を使って同期をとる方法が書いてあります。



## multi camera の例のありか
以下は `git clone git@github.com:stereolabs/zed-sdk.git` したリポジトリの中にあるmulti camera のコードです。
それを元に、zed SDK では標準のサンプルとしては、どういう状況なのかを探っていきます。


```
find . -name "multi*" -print | sort
./body tracking/multi-camera
./depth sensing/multi camera
./depth sensing/multi camera/python/multi_camera.py
./recording/playback/multi camera
./recording/recording/multi camera
./spatial mapping/multi camera
```


## body tracking

```
$ du body\ tracking/ | grep multi
24      body tracking/multi-camera/python/ogl_viewer
36      body tracking/multi-camera/python
52      body tracking/multi-camera/cpp/src
20      body tracking/multi-camera/cpp/include
80      body tracking/multi-camera/cpp
120     body tracking/multi-camera
```

### github 上のコード
github [body tracking/multi-camera](https://github.com/stereolabs/zed-sdk/tree/master/body%20tracking/multi-camera)

### 実行例
```
zed-sdk/body tracking/multi-camera/python$ python fused_cameras.py
This sample display the fused body tracking of multiple cameras.
It needs a Localization file in input. Generate it with ZED 360.
The cameras can either be plugged to your devices, or already running on the local network.
```

４台のZED カメラを接続する必要がありそうだ。


## depth sensing
```
/zed-sdk$ du depth\ sensing/ | grep multi
12      depth sensing/multi camera/python
12      depth sensing/multi camera/cpp/src
24      depth sensing/multi camera/cpp
44      depth sensing/multi camera
```

以下のREADME.mdを参照しよう。 

- [depth sensing/multi camera/README.md](https://github.com/stereolabs/zed-sdk/blob/master/depth%20sensing/multi%20camera/README.md)

- [depth sensing/multi camera/cpp/README.md](https://github.com/stereolabs/zed-sdk/blob/master/depth%20sensing/multi%20camera/cpp/README.md)

### github 上のコード
github [depth sensing/multi-camera](https://github.com/stereolabs/zed-sdk/tree/master/depth%20sensing/multi%20camera)

## recoding and playback
C++ 版のサンプルだけ、
python 版のサンプルはない。

```
zed-sdk$ du recording/ | grep multi
12      recording/recording/multi camera/cpp/src
8       recording/recording/multi camera/cpp/include
28      recording/recording/multi camera/cpp
32      recording/recording/multi camera
12      recording/playback/multi camera/cpp/src
8       recording/playback/multi camera/cpp/include
32      recording/playback/multi camera/cpp
36      recording/playback/multi camera
```

[ZED SDK - SVO Playback Multi-Camera](https://github.com/stereolabs/zed-sdk/blob/master/recording/playback/multi%20camera/cpp/README.md)

github [recording/multi camera](https://github.com/stereolabs/zed-sdk/tree/master/recording/recording/multi%20camera)

github [playback/multi camara](https://github.com/stereolabs/zed-sdk/tree/master/recording/playback/multi%20camera/cpp)

## spatial mapping
C++ 版のサンプルだけ、
python 版のサンプルはない。

```
 du spatial\ mapping/multi\ camera/
40      spatial mapping/multi camera/cpp/src
20      spatial mapping/multi camera/cpp/include
68      spatial mapping/multi camera/cpp
72      spatial mapping/multi camera/
```

github [spatial mapping/multi camara/cpp](https://github.com/stereolabs/zed-sdk/tree/master/spatial%20mapping/multi%20camera/cpp)

## [fusion](https://www.stereolabs.com/docs/fusion/overview)

> The Fusion API of the ZED SDK offers developers the ability to create applications using data from multiple cameras with ease. This module handles time synchronization and geometric calibration issues, along with 360° data fusion with noisy data coming from multiple cameras and sensor sources.

和訳：
ZED SDK の Fusion API を使用すると、開発者は複数のカメラからのデータを使用してアプリケーションを簡単に作成できます。 このモジュールは、複数のカメラやセンサー ソースからのノイズを含むデータとの 360° データ フュージョンに加えて、時間同期と幾何学的なキャリブレーションの問題を処理します。

![](https://docs.stereolabs.com/fusion/images/Centralized%20workflow.png)

## [ZED360](https://www.stereolabs.com/docs/fusion/zed360)

> ZED360 is an easy-to-use tool that simplifies multi-camera data fusion for users using the ZED SDK’s Fusion API. ZED360 allows you to seamlessly calibrate your camera array and fuse data from multiple sources. Although it is currently primarily focused on body-tracking fusion, ZED360 will continue to integrate more functionalities as the Fusion API evolves.

和訳：
ZED360 は、ZED SDK の Fusion API を使用してユーザーがマルチカメラ データ フュージョンを簡素化する使いやすいツールです。 ZED360 を使用すると、カメラ アレイをシームレスに調整し、複数のソースからのデータを融合できます。 ZED360 は現在、主にボディトラッキング フュージョンに焦点を当てていますが、Fusion API の進化に合わせてさらに多くの機能を統合し続ける予定です。

[Vision-based platform for robots](https://www.stereolabs.com/solutions/autonomous-robotics)
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/83761/bd611d78-2086-6fcc-ceb3-9b71c166e9a6.png)

https://stream.mux.com/ZauztMyUBOXE7EWgeit028L700RpsXcvOqwY6cK01TQLsQ/high.mp4