ros-streamer 0.3.0__py3-none-any.whl

ros_stream_viewer/__init__.py

@@ -0,0 +1,13 @@
+"""ros_stream_viewer: ZMQ 카메라 스트림 뷰어."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    # 설치된 배포 메타데이터에서 버전을 읽어 pyproject와 어긋나지 않게 한다.
+    __version__ = version("ros-streamer")
+except PackageNotFoundError:  # 소스 트리에서 직접 실행하는 경우
+    __version__ = "0.1.0"
+
+__all__ = ["__version__"]

ros_stream_viewer/config.py

@@ -0,0 +1,365 @@
+"""wpyconf(import name: ``wconfig``) 기반 설정 계층.
+
+우선순위(높은 것이 낮은 것을 덮어씀):
+
+    CLI 플래그 > 환경변수 > .env > 설정 파일 > 코드 기본값
+
+환경변수 prefix는 ``ROS_STREAMER``이며, 중첩 키는 ``__``로 구분한다.
+
+    ROS_STREAMER_STREAM__HOST=10.0.0.2
+    ROS_STREAMER_STREAM__PORT=15555
+    ROS_STREAMER_STREAM__TYPE=compressed
+    ROS_STREAMER_LOGGING__LEVEL=DEBUG
+
+설정 파일은 ``--config PATH``로 지정하며 JSON/TOML/YAML을 지원한다.
+
+값 해석 규약
+    * 환경변수/``.env``/설정 파일 값은 문자열로 들어오므로 타입별로 명시적으로
+      변환한다. 특히 불리언은 ``true/false/1/0/yes/no/on/off``만 인정한다
+      (``bool("false") is True`` 같은 함정을 피한다).
+    * 해석 자체가 불가능한 값은 기본값으로 폴백한다.
+    * 해석됐지만 규약을 벗어난 값(포트 범위 밖, 0 이하 해상도 등)은
+      :class:`StreamConfigError`를 올려 사용법/설정 오류(종료 코드 2)로 처리한다.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any
+
+ENV_PREFIX = "ROS_STREAMER"
+
+#: 문자열을 불리언으로 해석할 때 허용하는 표기(wpycli ``_parse_bool``과 동일).
+_TRUE_STRINGS = frozenset({"1", "true", "t", "yes", "y", "on"})
+_FALSE_STRINGS = frozenset({"0", "false", "f", "no", "n", "off"})
+
+MIN_PORT = 1
+MAX_PORT = 65535
+MIN_DIMENSION = 1
+MAX_DIMENSION = 32768
+MAX_TIMEOUT_SECONDS = 3600.0
+MAX_DURATION_SECONDS = 86400.0
+MAX_FRAMES_LIMIT = 1_000_000_000
+
+#: ``stream.type`` 허용값. ``auto``는 매직 바이트로 자동 판별한다.
+STREAM_TYPES = ("auto", "raw", "compressed")
+
+
+class StreamConfigError(ValueError):
+    """해석은 됐지만 규약을 벗어난 설정값(사용법/설정 오류, 종료 코드 2)."""
+
+
+DEFAULTS: dict[str, Any] = {
+    "stream": {
+        "host": "localhost",
+        # 서버 포트 규약: base(5555)=raw, base+1(5556)=compressed.
+        "port": 5556,
+        "width": 640,
+        "height": 480,
+        "type": "auto",
+        "connect_timeout": 5.0,
+        "stall_timeout": 3.0,
+        "max_frames": 0,
+        "duration": 0.0,
+        "snapshot_dir": ".",
+        "frame_log": False,
+        "network_info": True,
+        "headless": False,
+    },
+    "output": {
+        # 기계 판독 출력. 결과는 stdout, 로그는 stderr로 나간다.
+        "json": False,
+    },
+    "logging": {
+        "level": "INFO",
+        "file": None,
+        # wpycli ``LoggingSettings``가 ``logging.max_bytes``/``backup_count``
+        # 키로 읽어 로그 로테이션에 사용한다.
+        "max_bytes": 10 * 1024 * 1024,
+        "backup_count": 5,
+    },
+}
+
+
+@dataclass(frozen=True)
+class StreamOptions:
+    """뷰어 서비스에 전달되는 해석된 옵션."""
+
+    host: str
+    port: int
+    width: int
+    height: int
+    stream_type: str
+    connect_timeout: float
+    stall_timeout: float
+    max_frames: int
+    duration: float
+    snapshot_dir: str
+    frame_log: bool
+    network_info: bool
+    headless: bool
+
+    def service_kwargs(self) -> dict[str, Any]:
+        """``StreamService`` 생성자 인자로 변환한다."""
+        return {
+            "host": self.host,
+            "port": self.port,
+            "width": self.width,
+            "height": self.height,
+            "stream_type": self.stream_type,
+            "connect_timeout": self.connect_timeout,
+            "stall_timeout": self.stall_timeout,
+            "max_frames": self.max_frames,
+            "duration": self.duration,
+            "snapshot_dir": self.snapshot_dir,
+            "is_frame": self.frame_log,
+            "show_network_info": self.network_info,
+            "headless": self.headless,
+        }
+
+
+@dataclass(frozen=True)
+class OutputOptions:
+    """출력 관련 해석된 옵션."""
+
+    json: bool
+
+
+# -- 값 해석 헬퍼 ---------------------------------------------------------
+
+
+def _resolve(
+    config: Any,
+    flags: Mapping[str, Any],
+    *,
+    flag: str,
+    key: str,
+    default: Any,
+) -> Any:
+    """플래그가 명시되면 플래그를, 아니면 설정을, 아니면 기본값을 반환한다.
+
+    설정에 명시적 ``null``이 있으면 기본값으로 본다.
+    """
+    value = flags.get(flag)
+    if value is not None:
+        return value
+    if config is not None:
+        found = config.get(key, default)
+        if found is not None:
+            return found
+    return default
+
+
+def _as_int(value: Any, default: int) -> int:
+    """설정/플래그 값을 정수로 변환한다. 변환 실패 시 기본값을 쓴다."""
+    if isinstance(value, bool):
+        return default
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return default
+
+
+def _as_float(value: Any, default: float) -> float:
+    """설정/플래그 값을 실수로 변환한다. 변환 실패 시 기본값을 쓴다."""
+    if isinstance(value, bool):
+        return default
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return default
+
+
+def _as_bool(value: Any, default: bool) -> bool:
+    """설정/플래그 값을 불리언으로 변환한다.
+
+    ``bool("false") == True``이므로 문자열/정수를 명시적으로 해석한다.
+    해석할 수 없으면 기본값을 쓴다.
+    """
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, int):
+        return bool(value) if value in (0, 1) else default
+    if isinstance(value, str):
+        normalized = value.strip().lower()
+        if normalized in _TRUE_STRINGS:
+            return True
+        if normalized in _FALSE_STRINGS:
+            return False
+    return default
+
+
+def _int_in_range(
+    value: Any,
+    *,
+    default: int,
+    minimum: int,
+    maximum: int,
+    field: str,
+) -> int:
+    number = _as_int(value, default)
+    if not minimum <= number <= maximum:
+        raise StreamConfigError(
+            f"{field} 값이 허용 범위를 벗어났습니다: {number} (허용 범위 {minimum}~{maximum})"
+        )
+    return number
+
+
+def _float_in_range(
+    value: Any,
+    *,
+    default: float,
+    minimum: float,
+    maximum: float,
+    field: str,
+) -> float:
+    number = _as_float(value, default)
+    if not minimum <= number <= maximum:
+        raise StreamConfigError(
+            f"{field} 값이 허용 범위를 벗어났습니다: {number} (허용 범위 {minimum}~{maximum})"
+        )
+    return number
+
+
+def _choice(value: Any, allowed: tuple[str, ...], field: str) -> str:
+    text = str(value).strip().lower()
+    if text not in allowed:
+        raise StreamConfigError(
+            f"{field} 값이 올바르지 않습니다: {value!r} (허용: {', '.join(allowed)})"
+        )
+    return text
+
+
+def _non_empty(value: Any, field: str) -> str:
+    text = str(value).strip()
+    if not text:
+        raise StreamConfigError(f"{field} 값이 비어 있습니다.")
+    return text
+
+
+def resolve_stream_options(
+    config: Any,
+    flags: Mapping[str, Any],
+) -> StreamOptions:
+    """플래그·설정·기본값을 병합해 ``StreamOptions``를 만든다.
+
+    Raises:
+        StreamConfigError: 해석된 값이 허용 범위/허용 목록을 벗어난 경우.
+    """
+    section = "stream"
+    defaults = DEFAULTS[section]
+
+    def value(flag: str | None, key: str) -> Any:
+        return _resolve(
+            config,
+            flags,
+            flag=flag or key.replace("_", "-"),
+            key=f"{section}.{key}",
+            default=defaults[key],
+        )
+
+    return StreamOptions(
+        host=_non_empty(value("host", "host"), f"{section}.host"),
+        port=_int_in_range(
+            value("port", "port"),
+            default=defaults["port"],
+            minimum=MIN_PORT,
+            maximum=MAX_PORT,
+            field=f"{section}.port",
+        ),
+        width=_int_in_range(
+            value("width", "width"),
+            default=defaults["width"],
+            minimum=MIN_DIMENSION,
+            maximum=MAX_DIMENSION,
+            field=f"{section}.width",
+        ),
+        height=_int_in_range(
+            value("height", "height"),
+            default=defaults["height"],
+            minimum=MIN_DIMENSION,
+            maximum=MAX_DIMENSION,
+            field=f"{section}.height",
+        ),
+        stream_type=_choice(
+            value("stream-type", "type"),
+            STREAM_TYPES,
+            f"{section}.type",
+        ),
+        connect_timeout=_float_in_range(
+            value("connect-timeout", "connect_timeout"),
+            default=defaults["connect_timeout"],
+            minimum=0.0,
+            maximum=MAX_TIMEOUT_SECONDS,
+            field=f"{section}.connect_timeout",
+        ),
+        stall_timeout=_float_in_range(
+            value("stall-timeout", "stall_timeout"),
+            default=defaults["stall_timeout"],
+            minimum=0.0,
+            maximum=MAX_TIMEOUT_SECONDS,
+            field=f"{section}.stall_timeout",
+        ),
+        max_frames=_int_in_range(
+            value("max-frames", "max_frames"),
+            default=defaults["max_frames"],
+            minimum=0,
+            maximum=MAX_FRAMES_LIMIT,
+            field=f"{section}.max_frames",
+        ),
+        duration=_float_in_range(
+            value("duration", "duration"),
+            default=defaults["duration"],
+            minimum=0.0,
+            maximum=MAX_DURATION_SECONDS,
+            field=f"{section}.duration",
+        ),
+        snapshot_dir=_non_empty(
+            value("snapshot-dir", "snapshot_dir"),
+            f"{section}.snapshot_dir",
+        ),
+        frame_log=_as_bool(value("frame-log", "frame_log"), defaults["frame_log"]),
+        network_info=_as_bool(
+            value("network-info", "network_info"),
+            defaults["network_info"],
+        ),
+        headless=_as_bool(value("headless", "headless"), defaults["headless"]),
+    )
+
+
+def resolve_output_options(
+    config: Any,
+    flags: Mapping[str, Any],
+) -> OutputOptions:
+    """출력 관련 플래그·설정·기본값을 병합한다."""
+    defaults = DEFAULTS["output"]
+    return OutputOptions(
+        json=_as_bool(
+            _resolve(
+                config,
+                flags,
+                flag="json",
+                key="output.json",
+                default=defaults["json"],
+            ),
+            defaults["json"],
+        )
+    )
+
+
+def load_viewer_config(
+    *,
+    files: tuple[str, ...] = (),
+    dotenv: str | None = ".env",
+) -> Any:
+    """wpyconf ``Config``를 직접 로드한다(라이브러리 사용 시)."""
+    from wconfig import load_config
+
+    return load_config(
+        defaults=DEFAULTS,
+        files=files,
+        dotenv=dotenv,
+        env_prefix=ENV_PREFIX,
+        env_nested_delimiter="__",
+    )

ros_stream_viewer/services/__init__.py

@@ -0,0 +1,3 @@
+from .stream_service import StreamService
+
+__all__ = ["StreamService"]

ros_stream_viewer/services/stream_service.py

@@ -0,0 +1,31 @@
+"""단순 스트림 표시 서비스."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from numpy.typing import NDArray
+
+from ros_stream_viewer.services.viewer_service import BaseStreamViewerService
+
+
+class StreamService(BaseStreamViewerService):
+    """수신한 프레임을 가공 없이 화면에 표시한다.
+
+    옵션은 ``StreamOptions.service_kwargs()``가 만든 키를 그대로 받아
+    :class:`BaseStreamViewerService`로 전달한다(시그니처 중복/불일치 방지).
+    """
+
+    def __init__(
+        self,
+        logger: logging.Logger | None = None,
+        **options: Any,
+    ) -> None:
+        super().__init__(logger=logger, **options)
+
+    def _process_frame(self, frame: NDArray) -> NDArray:
+        return frame
+
+    def _get_window_name(self) -> str:
+        return "frame"