ros-tviewer 0.1.0__tar.gz

ros_tviewer-0.1.0/.env.example

@@ -0,0 +1,9 @@
+ROS_TVIEWER_APP__DEFAULT_TARGET=world
+ROS_TVIEWER_LOGGING__LEVEL=WARNING
+ROS_TVIEWER_CAMERA__TOPIC=/camera/image_raw
+ROS_TVIEWER_CAMERA__FPS=30
+ROS_TVIEWER_CAMERA__ROTATE=0
+ROS_TVIEWER_CAMERA__STRETCH=false
+ROS_TVIEWER_CAMERA__COMPRESSED=false
+ROS_TVIEWER_CAMERA__TIMEOUT=5.0
+ROS_TVIEWER_CAMERA__FRAMES=0

ros_tviewer-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: ci
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@8d55fbecc275b1c35dbe060458839f8d30439ccf # v3
+
+      - name: Install system dependencies
+        # tcamviewer sdist 빌드에 cmake + FFmpeg dev 라이브러리 필요
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends cmake libavcodec-dev libavformat-dev libavutil-dev libswscale-dev libswresample-dev
+
+      - name: Install dependencies
+        run: |
+          if [ -f uv.lock ]; then
+            uv sync --locked --group dev
+          else
+            uv sync --group dev
+          fi
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Format
+        run: uv run ruff format --check .
+
+      - name: Test
+        run: uv run pytest

ros_tviewer-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,38 @@
+name: publish
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch: # 수동 재배포 (릴리스 재실행은 원본 워크플로우 SHA를 재사용함)
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      # PyPI Trusted Publishing (OIDC) — 비밀 토큰 불필요
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@8d55fbecc275b1c35dbe060458839f8d30439ccf # v3
+
+      - name: Install system dependencies
+        # tcamviewer sdist 빌드에 cmake + FFmpeg dev 라이브러리 필요
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y cmake libavcodec-dev libavformat-dev libavutil-dev libswscale-dev libswresample-dev
+
+      - name: Build
+        run: uv build
+        env:
+          UV_NO_CACHE: "1" # 캐시 독립 빌드 (cache poisoning 공격 표면 제거)
+
+      - name: Publish to PyPI
+        # v1.14.2 — 이전 버전(v1.12.x)의 twine은 hatchling이 생성하는
+        # Metadata-Version 2.5를 거부하므로 신규 버전 유지 필수
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2

ros_tviewer-0.1.0/.gitignore

@@ -0,0 +1,116 @@
+# --- OS Specific ---
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+Icon
+._*
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+
+# Windows
+Thumbs.db
+Thumbs.db:encryptable
+ehthumbs.db
+ehthumbs_vista.db
+*.stackdump
+[Dd]esktop.ini
+$RECYCLE.BIN/
+*.cab
+*.msi
+*.msix
+*.msm
+*.msp
+*.lnk
+
+# Linux
+*~
+.fuse_hidden*
+.directory
+.Trash-*
+.nfs*
+
+# --- Python General ---
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# --- Environments & Secrets ---
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+# Keep .env.example for documentation
+
+# --- Tooling & Linting ---
+# Ruff
+.ruff_cache/
+
+# Mypy / Pyright
+.mypy_cache/
+.dmypy.json
+dmypy.json
+# pyrightconfig.json is usually kept if shared, but can be ignored if local-only
+# pyrightconfig.json 
+
+# Pytest / Coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+cover/
+
+# --- Package Managers (uv / Poetry / PDM) ---
+# uv: uv.lock should be committed for reproducibility
+.pdm.toml
+__pypackages__/
+poetry.toml
+
+# --- IDEs ---
+# Visual Studio Code
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+!.vscode/*.code-snippets
+.history/
+
+# PyCharm / JetBrains
+.idea/
+
+# --- Project Specific ---
+*.log

ros_tviewer-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

ros_tviewer-0.1.0/AGENTS.md

@@ -0,0 +1,153 @@
+# AGENTS.md — ros-tviewer 개발 가이드
+
+ROS 2 카메라 토픽을 터미널에서 재생하는 CLI 뷰어. 이 문서는 에이전트(및 개발자)가
+**일관성 있게** 개발하기 위한 아키텍처 명세와 TDD 규칙이다. 코드 변경 전 반드시 읽는다.
+
+---
+
+## 1. 프로젝트 개요
+
+| 항목 | 내용 |
+| --- | --- |
+| 목적 | ROS 2 `sensor_msgs/msg/Image`, `CompressedImage` 토픽을 터미널(ANSI TrueColor Half-Block)로 실시간 재생 |
+| 렌더링 | [tcamviewer](https://pypi.org/project/tcamviewer/) `>=0.2.3` (C-ABI 코어 + ctypes 바인딩, PyPI 배포됨) |
+| CLI | `wpycli` (cobra 스타일 Command), 설정 `wpyconf`, 로깅 `wpylog` |
+| 실행 | `uv run ros-tviewer play /camera/image_raw` 또는 ROS env source 후 `uvx ros-tviewer ...` |
+| Python | 3.12 (ROS 2 Jazzy ABI 매칭 — `requires-python = ">=3.12"`) |
+| 테스트 | `pytest` (단위), E2E는 ROS 환경에서 `bash tests/e2e.sh` |
+
+## 2. 아키텍처
+
+```text
+                      ┌──────────────────────────────┐
+                      │  main.py (wpycli Command)    │  play / topics / config
+                      └──────┬───────────────────────┘
+                             │ 1) ros_env.ensure_rclpy()   ← 반드시 가장 먼저
+                             ▼
+                      ┌──────────────────────────────┐
+                      │  ros_env.py                  │  rclpy 부트스트랩
+                      │  (시스템 ROS 탐지 + re-exec) │  (pip 설치 불가 → 시스템 전용)
+                      └──────┬───────────────────────┘
+                             ▼
+                      ┌──────────────────────────────┐
+                      │  node.py (CameraViewer)      │  rclpy 구독 + 스로틀 + 렌더 루프
+                      │  - 최신 프레임만 유지(Drop)  │  QoS: sensor_data (depth 1)
+                      └──────┬───────────────────────┘
+                             ▼
+        ┌────────────────────┴────────────────────┐
+        ▼                                          ▼
+┌──────────────────┐                    ┌──────────────────────┐
+│  convert.py      │                    │  tcamviewer (PyPI)   │
+│  Image/Compressed│  ── RGB24 numpy ──▶│  TerminalRenderer    │
+│  → RGB24 (H,W,3) │                    │  render_rgb()        │
+└──────────────────┘                    └──────────────────────┘
+   numpy + opencv만 사용. cv_bridge 사용 금지.
+```
+
+### 모듈 계약 (변경 금지 원칙)
+
+| 모듈 | 책임 | 금지 사항 |
+| --- | --- | --- |
+| `main.py` | wpycli 커맨드 정의, ctx → 파라미터 변환 | ROS/rclpy 직접 임포트 금지, 렌더 로직 금지 |
+| `ros_env.py` | rclpy 가용성 확인, sys.path 주입, 환경변수 구성 후 `os.execve` 재실행 | rclpy를 모듈 레벨에서 import 금지(항상 함수 내 지연 임포트) |
+| `node.py` | rclpy 노드/구독/스핀 루프, 프레임 슬롯·레이트리미터 | 픽셀 변환 로직 금지(convert에 위임), 렌더러 생성만 |
+| `convert.py` | 메시지 → RGB24 numpy. 순수 함수. rclpy 무의존 (테스트 가능) | rclpy/노드 상태 금지. cv2 임포트는 함수 내부 지연. 채널 재배치는 cv2.cvtColor 사용 |
+| `tests/` | 단위 테스트는 rclpy 없이 실행 가능해야 함 | ROS 미설치 환경에서 fail 금지 → `skipif` 사용 |
+
+### 데이터 규약
+
+- **내부 프레임 표준**: `numpy.ndarray`, `dtype=uint8`, `shape=(H, W, 3)`, **RGB24**, C-contiguous.
+  - 렌더러가 BGR을 원하면 `render_bgr`을 쓰지 말고 convert에서 RGB로 통일한다.
+- `convert.image_to_rgb(data, encoding, width, height, step)`는 순수 함수 — 부작용 없음.
+- 지원 encoding: `rgb8`, `bgr8`, `rgba8`, `bgra8`, `mono8`, `8UC1/3/4`. 추가 시
+  `_SUPPORTED_ENCODINGS` 테이블 + 테스트를 **함께** 추가한다 (TDD).
+- 지원하지 않는 encoding은 `UnsupportedEncodingError`, 데이터 손상은 `FrameDecodeError`.
+
+### rclpy 다루기 (중요)
+
+- **rclpy는 pip 설치 불가** — 시스템 ROS 2(`/opt/ros/<distro>`)에만 존재.
+- 규칙:
+  1. rclpy import는 **함수 내부 지연 임포트**만 허용 (`ros_env.ensure_rclpy()` 이후).
+  2. CLI 런 핸들러 첫 줄에서 `ensure_rclpy()` 호출. 미설치 환경에서는
+     명확한 `_HELP_MESSAGE`와 함께 `RuntimeError`.
+  3. `ensure_rclpy()`는 find_spec 기반 확인 → sys.path 주입 → 실패 시 환경변수 구성 후
+     **re-exec**(`os.execve`, 마커 `ROS_TVIEWER_REEXEC`로 무한루프 방지) 순서를 유지.
+  4. ruff/pyright: `import rclpy` 라인에는 `# type: ignore[import-not-found]` 허용.
+
+## 3. TDD 규칙 (Red → Green → Refactor)
+
+1. **새 기능 = 실패하는 테스트부터**. 구현 전 테스트가 반드시 `pytest`에서 fail/red를
+   확인한 뒤 구현한다.
+2. 테스트 분류:
+   - `tests/test_convert.py` — 변환 순수함수. rclpy 불필요, 항상 실행.
+   - `tests/test_main.py` — CLI 커맨드/플래그 구조. rclpy 불필요, 항상 실행.
+   - `tests/test_ros_env.py` — 부트스트랩. `os.execve`는 **반드시 monkeypatch**로 가로챔
+     (테스트 프로세스 교체 방지).
+   - `tests/test_ros2_e2e.py` — 실제 rclpy 구독/렌더. `pytest.mark.skipif`:
+     rclpy 미탑재 환경에서는 skip. 서브프로세스로 `source /opt/ros/*/setup.bash` 후 실행.
+3. Fake 메시지: `sensor_msgs`를 임포트하지 말고 `types.SimpleNamespace`로
+   `data/encoding/width/height/step` 필드를 만든다 (`tests/fakes.py` 헬퍼 재사용).
+4. 커버리지 목표: convert 100%, ros_env 분기 커버, main 플래그 파싱 스냅샷.
+5. 커밋 단위: Red(테스트 추가) → Green(최소 구현) → Refactor → `uv run ruff check .` → 반복.
+
+## 4. 명령어
+
+```bash
+uv sync                       # 의존성 설치 (tcamviewer는 sdist → 시스템에 cmake+FFmpeg dev 필요)
+uv run pytest                 # 단위 테스트
+uv run pytest tests/test_ros2_e2e.py -v   # ROS E2E (source 없이도 skip만 됨)
+uv run ruff check . && uv run ruff format --check .   # 린트/포맷
+bash tests/e2e.sh             # ROS 환경 E2E (더미 퍼블리셔 → play 60프레임)
+uv run ros-tviewer play /camera/image_raw   # 실행
+```
+
+## 5. 설정 참조 (wpyconf)
+
+`config.toml` / `.env` / CLI 플래그 우선순위: **CLI > env > file > defaults**.
+
+| 키 (config) | env | CLI 플래그 | 기본값 |
+| --- | --- | --- | --- |
+| `camera.topic` | `ROS_TVIEWER_CAMERA__TOPIC` | (위치인자 `[topic]`) | `/camera/image_raw` |
+| `camera.fps` | `ROS_TVIEWER_CAMERA__FPS` | `--fps/-f` | 30 |
+| `camera.rotate` | `ROS_TVIEWER_CAMERA__ROTATE` | `--rotate/-r` | 0 |
+| `camera.stretch` | `ROS_TVIEWER_CAMERA__STRETCH` | `--stretch/-s` | false |
+| `camera.compressed` | `ROS_TVIEWER_CAMERA__COMPRESSED` | `--compressed/-z` | false(→None, 자동감지) |
+| `camera.timeout` | `ROS_TVIEWER_CAMERA__TIMEOUT` | `--timeout/-t` | 5.0 |
+| `camera.frames` | `ROS_TVIEWER_CAMERA__FRAMES` | `--frames/-n` | 0(무제한) |
+| `logging.level` | `ROS_TVIEWER_LOGGING__LEVEL` | `--log-level` | WARNING |
+
+- `compressed`는 트라이스테이트다: 플래그/설정 true → 강제, 미지정 → **None(자동 감지)**.
+  bool로 강제하면 CompressedImage 토픽에 Image로 구독하는 미스매치로 무한 대기한다 (E2E 회귀 1회).
+- 로그는 터미널 렌더를 오염시키므로 **기본 WARNING 이상** 유지. 렌더 루프 안에서 로그 금지.
+- 새 플래그 추가 시: main.py 플래그 + defaults + config.toml + .env.example + AGENTS.md 표 — 5곳 동시 갱신.
+
+## 6. 실행 모델 & 성능
+
+- 구독 QoS: `qos_profile_sensor_data` (best effort, depth 1) — 프레임 밀림 방지.
+- 콜백은 **변환 없이 원본 메시지만** `FrameSlot`에 저장(drop)한다. 픽셀 변환은 렌더 직전에만
+  수행 — 수신률이 렌더율보다 높으면 수신 프레임 상당수가 렌더 없이 버려지므로, 변환 비용을
+  렌더량에 비례시킨다.
+- 손상 프레임(`FrameDecodeError`/`UnsupportedEncodingError`)은 렌더 루프에서 스킵하고
+  종료 시 `bad_frames` 카운트만 로그에 남긴다.
+- FPS 스로틀은 `RateLimiter`(모노토닉 클럭)로 구현 — `time.sleep` 사용 금지.
+- 변환 성능(1080p, ms/frame): rgb8 0.2 / bgr8 0.3 / rgba·bgra 0.8 / mono 0.25 /
+  CompressedImage(jpeg) ~20(디코딩 자체가 지배). 채널 재배치에 numpy 음수 스트라이드 복사
+  (예: `[..., ::-1]`)을 쓰지 않는다 — `cv2.cvtColor`(SIMD)가 수십 배 빠르다.
+- 터미널 리사이즈: 매 프레임 `get_terminal_size()` 비교, 변경 시 `renderer.resize()`.
+- 렌더러는 `use_diff=True, alt_screen=True, hide_cursor=True` 고정.
+  종료 시(Signal 포함) `renderer.close()` 보장 — 터미널 복구 필수.
+
+## 7. 자주 하는 실수 (Do NOT)
+
+- ❌ 모듈 레벨 `import rclpy` → ROS 미설치 머신의 단위 테스트 전부 붕괴.
+- ❌ `cv_bridge` 사용 → ROS 전용 의존성, uvx 실행이 깨짐. convert.py (numpy/cv2)만 사용.
+- ❌ BGR 프레임을 `render_rgb`로 전달 → 색 반전. RGB24로 정규화 후 전달.
+- ❌ 렌더 콜백 안에서 `print`/`logging.info` → 화면 깨짐.
+- ❌ `except Exception: pass` 같은 무시 처리 → 에러는 명시적 예외 타입 + 안내 메시지.
+- ❌ `time.sleep` 기반 프레임 페이싱 → 지연 누적. 모노토닉 기반 RateLimiter 사용.
+
+## 8. 배포
+
+- `uv build` → `uv publish` (PyPI, 패키지명 `ros_tviewer` / 실행명 `ros-tviewer`).
+- 배포 전 체크리스트: `uv run pytest`, `uv run ruff check .`, `bash tests/e2e.sh`, README 실행 예시 최신화.
+- tcamviewer 하위호환: 구버전(≤0.2.2) 휠의 `.so` 이중 중첩 버그가 있으므로 하한 `>=0.2.3` 고정.

ros_tviewer-0.1.0/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+이 프로젝트의 모든 주목할 만한 변경 사항이 이 파일에 기록됩니다.
+
+형식은 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/)을 따르며,
+버전 관리는 [Semantic Versioning](https://semver.org/lang/ko/)을 따릅니다.
+
+## [Unreleased]
+
+### Added
+
+- `play` 커맨드: ROS 2 카메라 토픽(Image/CompressedImage)을 tcamviewer
+  Half-Block TrueColor 렌더러로 터미널에 실시간 재생 — `--fps`, `--rotate`,
+  `--stretch`, `--compressed`, `--timeout`, `--frames` 플래그
+- `topics` 커맨드: 광고 중인 sensor_msgs 카메라 토픽 나열
+- `config` / `version` 커맨드
+- 최신 프레임 우선(drop) 구독 + 모노토닉 FPS 스로틀, 렌더 직전 변환
+- 시스템 ROS 2 자동 부트스트랩 (sys.path 주입 → re-exec)
+- 단위 테스트(ROS 불필요), ROS E2E 테스트, CI (ruff lint/format + pytest)
+
+## [0.1.0] - 2025-09-09
+
+### Added
+
+- 최초 릴리스 (위 Unreleased 항목 포함)
+
+[Unreleased]: https://github.com/wkqco33/ros_tviewer/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/wkqco33/ros_tviewer/releases/tag/v0.1.0

ros_tviewer-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,33 @@
+# 기여 가이드 (Contributing)
+
+ros-tviewer에 관심을 가져주셔서 감사합니다. 아래 규칙을 따라주시면 리뷰가 빨라집니다.
+
+## 개발 환경
+
+- Python 3.12, [uv](https://docs.astral.sh/uv/), ROS 2 (Jazzy/Humble, 테스트 실행 시)
+- 빌드 도구: `cmake`, FFmpeg dev 라이브러리 (`libavcodec-dev` 등) — tcamviewer sdist 빌드용
+
+```bash
+uv sync                        # 의존성 설치
+uv run pytest                  # 단위 테스트 (ROS 미설치 환경에서도 실행 가능)
+uv run ruff check .            # 린트
+uv run ruff format --check .   # 포맷 검사
+uvx pyright --project .        # 타입 체크
+bash tests/e2e.sh              # ROS 환경 E2E (더미 퍼블리셔 → play 60프레임)
+```
+
+## 규칙
+
+- **[AGENTS.md](AGENTS.md)를 먼저 읽어주세요** — 아키텍처·모듈 계약·TDD 규칙이 정리되어 있습니다.
+- 새 기능은 **실패하는 테스트부터** 추가합니다 (Red → Green → Refactor).
+- 단위 테스트는 rclpy/sensor_msgs 없이 실행 가능해야 합니다 (`tests/fakes.py` 헬퍼 사용).
+  rclpy가 필요한 경로는 `pytest.mark.skipif` 또는 서브프로세스 E2E로 검증합니다.
+- 모듈 레벨 `import rclpy` 금지 (함수 내부 지연 임포트만 허용).
+- 렌더 루프 안에서 `print`/로깅 금지 (터미널 오염).
+- 커밋 전에 린트·포맷·테스트를 모두 통과해야 합니다.
+
+## PR 프로세스
+
+1. 이슈를 먼저 생성해 방향을 맞추는 것을 권장합니다.
+2. 작은 단위의 PR을 선호합니다 (한 PR = 한 목적).
+3. PR 설명에 변경 요약과 검증 방법(`pytest`, E2E 등)을 적어주세요.

ros_tviewer-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 seo.youngchae
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ros_tviewer-0.1.0/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.5
+Name: ros_tviewer
+Version: 0.1.0
+Summary: ROS 2 카메라 토픽을 터미널에서 재생하는 뷰어
+Project-URL: Homepage, https://github.com/wkqco33/ros_tviewer
+Project-URL: Repository, https://github.com/wkqco33/ros_tviewer
+Project-URL: Issues, https://github.com/wkqco33/ros_tviewer/issues
+Project-URL: Changelog, https://github.com/wkqco33/ros_tviewer/blob/main/CHANGELOG.md
+Author: seo.youngchae
+License-Expression: MIT
+License-File: LICENSE
+Keywords: camera,rclpy,ros2,terminal,tui,viewer
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Video :: Capture
+Classifier: Topic :: Terminals
+Requires-Python: >=3.12
+Requires-Dist: numpy
+Requires-Dist: opencv-python-headless
+Requires-Dist: tcamviewer>=0.2.3
+Requires-Dist: wpycli
+Requires-Dist: wpyconf
+Requires-Dist: wpylog
+Description-Content-Type: text/markdown
+
+# ros-tviewer
+
+[![CI](https://github.com/wkqco33/ros_tviewer/actions/workflows/ci.yml/badge.svg)](https://github.com/wkqco33/ros_tviewer/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/ros-tviewer)](https://pypi.org/project/ros-tviewer/)
+[![Python](https://img.shields.io/badge/python-3.12%2B-blue)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+ROS 2 카메라 토픽을 터미널에서 재생하는 CLI 뷰어.
+
+[sensor_msgs/msg/Image](https://docs.ros.org/) 및 `sensor_msgs/msg/CompressedImage` 토픽을
+[tcamviewer](https://pypi.org/project/tcamviewer/)의 Half-Block TrueColor(24-bit ANSI) 렌더러로
+터미널에 실시간(30~60+ FPS) 재생한다.
+
+```text
+uv run ros-tviewer play /camera/image_raw
+▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
+```
+
+## 요구 사항
+
+| 항목 | 설명 |
+| --- | --- |
+| OS | Linux |
+| Python | 3.12 (ROS 2 Jazzy ABI 매칭) |
+| ROS 2 | Jazzy/Humble (`rclpy`는 시스템 ROS에서 로드 — pip 설치 불가) |
+| 빌드 도구 | `cmake`, FFmpeg dev 라이브러리 (`libavcodec-dev` 등) — tcamviewer sdist 빌드용 |
+| 터미널 | TrueColor 지원 (`echo $COLORTERM` → `truecolor`/`24bit`) |
+
+## 시작하기
+
+### 설치
+
+```bash
+# uv tool (권장)
+uv tool install ros-tviewer
+
+# 또는 pipx / pip
+pipx install ros-tviewer
+pip install ros-tviewer
+```
+
+PyPI 배포 전 개발 트리에서는 저장소 클론 후 실행한다:
+
+### 개발 트리에서 실행
+
+```bash
+uv sync
+
+# 1) 광고 중인 카메라 토픽 확인
+uv run ros-tviewer topics
+
+# 2) 재생 (ROS 환경 미 source 시 자동 감지·재실행)
+source /opt/ros/jazzy/setup.bash   # 권장 — 미실행 시 자동 부트스트랩이 시도됨
+uv run ros-tviewer play /camera/image_raw
+
+# 옵션 예시
+uv run ros-tviewer play /camera/image_raw/compressed --fps 30 --rotate 90 --stretch
+uv run ros-tviewer play /camera/image_raw --frames 100   # 100 프레임 렌더 후 종료 (테스트/데모)
+uv run ros-tviewer config                                # 현재 설정 출력
+uv run ros-tviewer version                               # 앱·의존성·런타임 리포트
+```
+
+- `q`/`Ctrl+C`로 종료 (터미널 상태 자동 복구).
+- `--compressed` 미지정 시 토픽 타입을 자동 감지한다.
+- 설정 우선순위: **CLI 플래그 > `.env` > `config.toml` > 기본값**.
+
+## E2E 테스트
+
+```bash
+uv run pytest                 # 단위 테스트 (ROS 미설치 환경에서도 실행 가능, ROS 테스트는 skip)
+bash tests/e2e.sh             # 더미 퍼블리셔 → play 60프레임 데모
+uv run pytest tests/test_ros2_e2e.py -v   # 실제 rclpy 구독 + 렌더 E2E
+```
+
+## 구성
+
+| 모듈 | 책임 |
+| --- | --- |
+| `main.py` | wpycli 커맨드 (`play`/`topics`/`config`), 플래그·설정 파싱 |
+| `ros_env.py` | rclpy 부트스트랩 (시스템 ROS 탐지 → sys.path 주입 → re-exec) |
+| `node.py` | 구독(QoS sensor_data), 최신 메시지 유지(drop), FPS 스로틀, 렌더 직전 변환 루프 |
+| `convert.py` | Image/CompressedImage → RGB24 numpy (numpy/opencv만 사용, cv_bridge 없이) |
+
+## 개발
+
+- 아키텍처·TDD 규칙·컨벤션: **[AGENTS.md](AGENTS.md)** — 코드 변경 전 필독.
+- 린트: `uv run ruff check .`
+- 타입 체크: `uvx pyright --project .`
+- 테스트: `uv run pytest`
+
+## 기여 및 보안
+
+- 기여 방법: [CONTRIBUTING.md](CONTRIBUTING.md)
+- 취약점 보고: [SECURITY.md](SECURITY.md) — 공개 이슈로 보고하지 마세요.
+- 변경 이력: [CHANGELOG.md](CHANGELOG.md)
+- 라이선스: [MIT](LICENSE)

ros_tviewer-0.1.0/README.md

@@ -0,0 +1,96 @@
+# ros-tviewer
+
+[![CI](https://github.com/wkqco33/ros_tviewer/actions/workflows/ci.yml/badge.svg)](https://github.com/wkqco33/ros_tviewer/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/ros-tviewer)](https://pypi.org/project/ros-tviewer/)
+[![Python](https://img.shields.io/badge/python-3.12%2B-blue)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+ROS 2 카메라 토픽을 터미널에서 재생하는 CLI 뷰어.
+
+[sensor_msgs/msg/Image](https://docs.ros.org/) 및 `sensor_msgs/msg/CompressedImage` 토픽을
+[tcamviewer](https://pypi.org/project/tcamviewer/)의 Half-Block TrueColor(24-bit ANSI) 렌더러로
+터미널에 실시간(30~60+ FPS) 재생한다.
+
+```text
+uv run ros-tviewer play /camera/image_raw
+▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
+```
+
+## 요구 사항
+
+| 항목 | 설명 |
+| --- | --- |
+| OS | Linux |
+| Python | 3.12 (ROS 2 Jazzy ABI 매칭) |
+| ROS 2 | Jazzy/Humble (`rclpy`는 시스템 ROS에서 로드 — pip 설치 불가) |
+| 빌드 도구 | `cmake`, FFmpeg dev 라이브러리 (`libavcodec-dev` 등) — tcamviewer sdist 빌드용 |
+| 터미널 | TrueColor 지원 (`echo $COLORTERM` → `truecolor`/`24bit`) |
+
+## 시작하기
+
+### 설치
+
+```bash
+# uv tool (권장)
+uv tool install ros-tviewer
+
+# 또는 pipx / pip
+pipx install ros-tviewer
+pip install ros-tviewer
+```
+
+PyPI 배포 전 개발 트리에서는 저장소 클론 후 실행한다:
+
+### 개발 트리에서 실행
+
+```bash
+uv sync
+
+# 1) 광고 중인 카메라 토픽 확인
+uv run ros-tviewer topics
+
+# 2) 재생 (ROS 환경 미 source 시 자동 감지·재실행)
+source /opt/ros/jazzy/setup.bash   # 권장 — 미실행 시 자동 부트스트랩이 시도됨
+uv run ros-tviewer play /camera/image_raw
+
+# 옵션 예시
+uv run ros-tviewer play /camera/image_raw/compressed --fps 30 --rotate 90 --stretch
+uv run ros-tviewer play /camera/image_raw --frames 100   # 100 프레임 렌더 후 종료 (테스트/데모)
+uv run ros-tviewer config                                # 현재 설정 출력
+uv run ros-tviewer version                               # 앱·의존성·런타임 리포트
+```
+
+- `q`/`Ctrl+C`로 종료 (터미널 상태 자동 복구).
+- `--compressed` 미지정 시 토픽 타입을 자동 감지한다.
+- 설정 우선순위: **CLI 플래그 > `.env` > `config.toml` > 기본값**.
+
+## E2E 테스트
+
+```bash
+uv run pytest                 # 단위 테스트 (ROS 미설치 환경에서도 실행 가능, ROS 테스트는 skip)
+bash tests/e2e.sh             # 더미 퍼블리셔 → play 60프레임 데모
+uv run pytest tests/test_ros2_e2e.py -v   # 실제 rclpy 구독 + 렌더 E2E
+```
+
+## 구성
+
+| 모듈 | 책임 |
+| --- | --- |
+| `main.py` | wpycli 커맨드 (`play`/`topics`/`config`), 플래그·설정 파싱 |
+| `ros_env.py` | rclpy 부트스트랩 (시스템 ROS 탐지 → sys.path 주입 → re-exec) |
+| `node.py` | 구독(QoS sensor_data), 최신 메시지 유지(drop), FPS 스로틀, 렌더 직전 변환 루프 |
+| `convert.py` | Image/CompressedImage → RGB24 numpy (numpy/opencv만 사용, cv_bridge 없이) |
+
+## 개발
+
+- 아키텍처·TDD 규칙·컨벤션: **[AGENTS.md](AGENTS.md)** — 코드 변경 전 필독.
+- 린트: `uv run ruff check .`
+- 타입 체크: `uvx pyright --project .`
+- 테스트: `uv run pytest`
+
+## 기여 및 보안
+
+- 기여 방법: [CONTRIBUTING.md](CONTRIBUTING.md)
+- 취약점 보고: [SECURITY.md](SECURITY.md) — 공개 이슈로 보고하지 마세요.
+- 변경 이력: [CHANGELOG.md](CHANGELOG.md)
+- 라이선스: [MIT](LICENSE)