LeRobot documentation

相机

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.6.1).
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 支持自动发现。运行以下命令以列出可用设备及其标识符。请注意,根据操作系统的不同,这些标识符可能会在重启计算机或重新插拔摄像头后发生变化。

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

如果连接了两个摄像头,输出将类似于以下内容:

--- 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 设置来手动配置它们。

相机放置与照明

相机图像是策略学习的依据,因此良好的相机设置比高分辨率更为重要:

  • 均匀照亮场景。 使用漫射且一致的光线,避免直射阳光、强烈反光和移动阴影。录制与部署之间的光照差异可能导致策略失效。
  • 固定相机位置。 请将其牢固安装,并在录制会话之间,或录制与部署之间保持不动。
  • 明确任务。 物体、夹爪和目标应在至少一个摄像头中可见。一个好的测试方法:仅通过查看摄像头图像,您能否自己完成该任务?
  • 保持分辨率适中。 640×480 分辨率、30 fps 帧率对于大多数任务已经足够,同时也能确保录制和训练的速度。

使用摄像头

帧访问模式

所有相机类都实现了三种用于捕获帧的访问模式:

方法行为Blocks?最适用于
read()等待相机硬件返回一帧图像。根据相机和 SDK 的不同,可能会长时间阻塞。是的简单脚本,顺序捕获
async_read(timeout_ms)返回后台线程中最新的未消费帧。仅当缓冲区为空时阻塞,最长等待 timeout_ms。如果未收到帧,则引发 TimeoutError。带超时与相机帧率同步的控制循环
read_latest(max_age_ms)查看缓冲区中最新的帧(可能已过期)。如果帧的年龄超过 max_age_ms,则引发 TimeoutError。NoUI 可视化、日志记录、监控

使用示例

以下示例展示了如何使用相机 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)。

有关在录制数据集时深度流的存储和编码方式,请参阅视频编码指南中的深度流部分。

使用手机摄像头

iPhone 和 macOS
OBS 虚拟摄像头

要在 macOS 上将 iPhone 用作摄像头,请启用连续互通相机功能:

  • 请确保您的 Mac 运行的是 macOS 13 或更高版本,并且您的 iPhone 使用的是 iOS 16 或更高版本。
  • 使用相同的 Apple ID 登录两台设备。
  • 使用 USB 数据线连接您的设备,或开启 Wi-Fi 和蓝牙以建立无线连接。

有关更多详细信息,请访问 Apple 支持。

如果一切设置正确,您的手机将显示为标准 OpenCV 摄像头,并可与 OpenCVCamera 一起使用。

Update on GitHub