LeRobot documentation

カメラ

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

カメラ

LeRobotでは、動画キャプチャに複数のオプションが提供されています:

クラスサポートされているカメラ
OpenCVCameraスマートフォン、内蔵ラップトップカメラ、USBウェブカメラ
ZMQCameraネットワーク接続カメラ
RealSenseCameraIntel RealSense(深度付き)
Reachy2CameraReachy 2 ロボットのカメラ

OpenCVCameraの互換性に関する詳細については、OpenCVによるビデオI/Oの概要を参照してください。

カメラを見つける

各カメラをインスタンス化するには一意の識別子が必要であり、これにより接続された複数のデバイスを区別できます。

OpenCVCamera と RealSenseCamera は自動検出に対応しています。以下のコマンドを実行すると、利用可能なデバイスとその識別子が一覧表示されます。OS によっては、コンピューター再起動やカメラの再接続後に識別子が変更される場合があります。

lerobot-find-cameras opencv # or realsense for Intel Realsense cameras

2つのカメラが接続されている場合、出力は次のようになります。

--- Detected Cameras ---
Camera #0:
  Name: OpenCV Camera @ 0
  Type: OpenCV
  Id: 0
  Backend api: AVFOUNDATION
  Default stream profile:
    Format: 16.0
    Width: 1920
    Height: 1080
    Fps: 15.0
--------------------
(more cameras ...)

macOS で Intel RealSense カメラを使用すると、エラー Error finding RealSense cameras: failed to set power state が発生する場合があります。この問題は、sudo 権限で同じコマンドを実行することで解決できます。なお、macOS での RealSense カメラの使用は不安定です。

ZMQCamera と Reachy2Camera は自動検出に対応していません。ネットワークアドレスとポート、またはロボット SDK の設定を手動で指定して構成する必要があります。

カメラの配置と照明

カメラの画像はポリシーが学習する対象となるため、高解像度よりも、適切なカメラの設置の方が重要です。

  • シーンを均一に照明する。 拡散した一貫性のある光を使用し、直射日光、強い反射、移動する影を避けてください。録画時とデプロイ時の照明が異なる場合、ポリシーが失敗する可能性があります。
  • カメラを固定します。 剛性に取り付け、録画セッションの間や、録画とデプロイの間で移動しないようにしてください。
  • タスクを定義する。対象物、グリップ、ターゲットは少なくとも1つのカメラで視認可能である必要があります。良いテスト方法: カメラの映像だけを見て、あなた自身でそのタスクを実行できますか?
  • 解像度は控えめに設定してください。 640×480、30 fps ならほとんどのタスクで十分であり、録画とトレーニングを高速に保つことができます。

カメラを使用する

フレームアクセスモード

すべてのカメラクラスは、フレームのキャプチャに3つのアクセスモードを実装しています:

メソッド動作ブロック?最適な用途
read()カメラハードウェアがフレームを返すまで待機します。カメラやSDKによって、長時間ブロックされる場合があります。はいシンプルなスクリプト、シーケンシャルキャプチャ
async_read(timeout_ms)バックグラウンドスレッドから最新かつ未消費のフレームを返します。バッファが空の場合のみ、timeout_ms までブロックします。フレームが届かない場合は TimeoutError を送出します。タイムアウト付きカメラのFPSに同期された制御ループ
read_latest(max_age_ms)バッファ内の最新のフレームを参照します(古い可能性があります)。フレームがmax_age_msより古い場合、TimeoutErrorを発生させます。いいえUIの可視化、ログ記録、モニタリング

使用例

以下の例では、カメラAPIを使用して異なるタイプのカメラからフレームを設定・キャプチャする方法を示しています。

  • OpenCVベースのカメラによるブロッキングおよびノンブロッキングのフレームキャプチャ
  • Intel RealSense カメラによるカラーと深度のキャプチャ

カメラを正常に切断できないと、リソースリークが発生する可能性があります。コンテキストマネージャープロトコルを使用して、自動的なクリーンアップを確保してください:

with OpenCVCamera(config) as camera:
    ...

connect()とdisconnect()を手動で呼び出すこともできますが、後者には常にfinallyブロックを使用してください。

Open CV カメラ
Intel Realsense カメラ
from lerobot.cameras.opencv import OpenCVCamera, OpenCVCameraConfig
from lerobot.cameras import ColorMode, Cv2Rotation

# Construct an `OpenCVCameraConfig` with your desired FPS, resolution, color mode, and rotation.
config = OpenCVCameraConfig(
    index_or_path=0,
    fps=15,
    width=1920,
    height=1080,
    color_mode=ColorMode.RGB,
    rotation=Cv2Rotation.NO_ROTATION
)

# Instantiate and connect an `OpenCVCamera`, performing a warm-up read (default).
with OpenCVCamera(config) as camera:

    # Read a frame synchronously — blocks until hardware delivers a new frame
    frame = camera.read()
    print(f"read() call returned frame with shape:", frame.shape)

    # Read a frame asynchronously with a timeout — returns the latest unconsumed frame or waits up to timeout_ms for a new one
    try:
        for i in range(10):
            frame = camera.async_read(timeout_ms=200)
            print(f"async_read call returned frame {i} with shape:", frame.shape)
    except TimeoutError as e:
        print(f"No frame received within timeout: {e}")

    # Instantly return a frame - returns the most recent frame captured by the camera
    try:
        initial_frame = camera.read_latest(max_age_ms=1000)
        for i in range(10):
            frame = camera.read_latest(max_age_ms=1000)
            print(f"read_latest call returned frame {i} with shape:", frame.shape)
            print(f"Was a new frame received by the camera? {not (initial_frame == frame).any()}")
    except TimeoutError as e:
        print(f"Frame too old: {e}")

深度の扱い

Intel RealSense と Reachy 2 のカメラは、カラーと深度を同期してキャプチャできます。read() を呼び出すと、カラーフレームが (H, W, 3) の uint8 として返されます。read_depth() を呼び出すと、深度マップが (H, W, 1) の uint16 として返され、各ピクセルの値はセンサーからの距離をミリメートル単位で表します。ピクセル値が 0 であることは、通常「測定値が利用できない」(範囲外、遮蔽、低信頼度)ことを意味します。

録画の間、制御ループはread_latest()(カラー)およびread_latest_depth()(深度)を介して、最新バッファリングされたフレームを非ブロッキングで参照し、深度マップを兄弟機能として追加します(例:frontの隣にfront_depth)。

データセットの録画時に深度ストリームがどのように保存・エンコードされるかについては、動画エンコーディングガイドのDepth streamsセクションを参照してください。

スマートフォンのカメラを使用する

iPhone & macOS
OBS仮想カメラ

macOSでiPhoneをカメラとして使用するには、Continuity Camera機能を有効にしてください:

  • MacがmacOS 13以降、iPhoneがiOS 16以降のOSで動作していることを確認してください。
  • 同じApple IDで両方のデバイスにサインインしてください。
  • デバイスをUSBケーブルで接続するか、ワイヤレス接続のためにWi-FiとBluetoothをオンにしてください。

詳細については、Apple サポートをご覧ください。

すべてが正しく設定されている場合、スマートフォンは標準的な OpenCV カメラとして認識され、OpenCVCamera で使用できます。

Update on GitHub