ros-stream-viewer

ROS Streamer 서버가 ZMQ로 발행하는 카메라 이미지를 구독해 화면에 표시하는 CLI입니다. ROS 설치 없이 단독 실행되며, Python 3.12+ 에서 동작합니다.

# 설치 없이 실행 (권장)
uvx ros-streamer stream --host <HOST> --port 5556

# 설치
uv tool install ros-streamer    # 또는: pip install ros-streamer
ros-stream-viewer stream

ros-streamer, ros-stream-viewer, rviewer는 동일한 실행 파일입니다.

빠른 시작

# compressed(JPEG) 스트림 표시 (서버 base+1, 기본 5556)
ros-stream-viewer stream

# raw 스트림 표시 (서버 base, 기본 5555)
ros-stream-viewer stream --port 5555 --stream-type raw

# 창 없이 100프레임만 수신하고 JSON 요약을 stdout으로 출력 (CI/스크립트)
ros-stream-viewer stream --headless --max-frames 100 --json

표시 중 단축키: i 정보 오버레이 토글 · p/Space 일시정지 · s PNG 스냅샷 · v mp4 녹화 · f 전체화면 · q/ESC 종료.

주요 플래그

설정

우선순위는 플래그 > 환경변수 > .env > 설정 파일 > 기본값이며, 환경변수 prefix는 ROS_STREAMER, 중첩 키 구분자는 __입니다.

ROS_STREAMER_STREAM__HOST=10.0.0.2 ROS_STREAMER_STREAM__PORT=15555 \
  ros-stream-viewer stream

설정 파일(JSON/TOML/YAML)은 --config로 지정합니다. 지정하지 않으면 .env와 OS 설정 디렉터리($XDG_CONFIG_HOME/ros-streamer/config.toml, macOS는 ~/Library/Application Support, Windows는 %APPDATA%)의 config.{toml,yaml,yml,json}을 자동으로 찾습니다.

# viewer.yaml
stream:
  host: 10.0.0.2
  port: 5555
  type: raw
  connect_timeout: 5.0
  network_info: false
logging:
  level: INFO

불리언은 true/false/1/0/yes/no/on/off(대소문자 무관)만 인정합니다. 해석할 수 없는 값은 기본값으로, 해석됐지만 규약을 벗어난 값(포트 범위 등)은 종료 코드 2로 거부합니다.

출력과 종료 코드

결과(도움말, --json 요약)는 stdout, 로그·진행·오류는 stderr로 나갑니다.

$ ros-stream-viewer stream --headless --max-frames 100 --json 2>/dev/null
{"backlog_skipped": 0, "decode_errors": 0, "dropped_frames": 0, "exit_code": 0,
 "fps": 30.0, "frames": 100, "frames_processed": 100, "host": "localhost",
 "latency_ms": 0.4, "port": 5556, "resolution": "640x480", "status": "ok", ...}

요구 사항과 지원 범위

• Python 3.12 / 3.13 (CI에서 두 버전 모두 테스트)
• Linux/macOS/Windows. GUI 표시에는 OpenCV 창이 필요하며, 헤드리스 환경에서는 --headless를 사용하세요.
• 일부 Linux 배포판은 OpenCV 런타임 의존성(libGL)이 필요합니다: apt-get install -y libgl1 libglib2.0-0
• ROS 서버 없이도 동작하며, ROS 패키지는 필요하지 않습니다.

0.x 버전은 API가 아직 안정적이지 않습니다. 하위 호환이 깨지는 변경은 CHANGELOG에 기록합니다.

문서

• 저장소·서버 노드·프로토콜: https://gitlab.com/wkqco33/ros-streamer#readme
• 이슈/요청: https://gitlab.com/wkqco33/ros-streamer/-/issues

라이선스

Apache-2.0 (LICENSE).