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.7.0).
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