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는 자동 감지를 지원합니다. 아래 명령을 실행하면 사용 가능한 장치와 해당 식별자를 나열합니다. 운영체제에 따라 컴퓨터 재부팅 또는 카메라 재연결 후 식별자가 변경될 수 있습니다.

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면 충분하며, 이를 통해 녹화와 학습 속도를 빠르게 유지할 수 있습니다.

카메라 사용

프레임 액세스 모드

모든 카메라 클래스는 프레임 캡처를 위한 세 가지 액세스 모드를 구현합니다:

메서드동작블록?가장 적합한 용도
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}")

깊이(depth) 작업

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 섹션을 참조하세요.

Use your phone’s camera

iPhone 및 macOS
OBS 가상 카메라

macOS에서 iPhone을 카메라로 사용하려면 Continuity Camera 기능을 활성화하세요:

  • Mac이 macOS 13 이상, iPhone이 iOS 16 이상을 실행 중인지 확인하세요.
  • 같은 Apple ID로 두 기기에 모두 로그인하세요.
  • USB 케이블로 장치를 연결하거나, 무선 연결을 위해 Wi-Fi와 Bluetooth를 켜세요.

자세한 내용은 Apple support를 방문하세요.

모든 설정이 올바르게 완료되면 휴대폰이 표준 OpenCV 카메라로 표시되며 OpenCVCamera와 함께 사용할 수 있습니다.

Update on GitHub