oriented-det 0.1.0__py3-none-any.whl

oriented_det/utils/__init__.py

@@ -0,0 +1,31 @@
+"""Utility helpers for configuration management and visualization."""
+
+from .config import FrozenConfig, load_config, merge_dicts, apply_overrides
+from . import viz
+from .device import get_device, is_gpu_device
+from .logging import (
+    TraceLogger,
+    logger,
+    trace_function,
+    enable_tracing,
+    disable_tracing,
+    is_tracing_enabled,
+)
+from .progress import tqdm_progress_stream
+
+__all__ = [
+    "FrozenConfig",
+    "load_config",
+    "merge_dicts",
+    "apply_overrides",
+    "get_device",
+    "is_gpu_device",
+    "viz",
+    "TraceLogger",
+    "logger",
+    "trace_function",
+    "enable_tracing",
+    "disable_tracing",
+    "is_tracing_enabled",
+    "tqdm_progress_stream",
+]

oriented_det/utils/config.py

@@ -0,0 +1,376 @@
+"""Lightweight configuration helpers with strong validation."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, MutableMapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict, Iterable, Iterator, MutableSequence, Sequence
+import ast
+import json
+import os
+
+try:  # Optional dependency for YAML configs.
+    import yaml  # type: ignore
+except Exception:  # pragma: no cover - exercised when PyYAML is absent.
+    yaml = None  # type: ignore
+
+# Keys starting with this prefix are ignored when loading configs.
+# Use for keeping alternative values visible without affecting behavior, e.g.:
+#   "learning_rate": 0.01,
+#   "_muted_learning_rate": 0.005  # ignored
+MUTED_KEY_PREFIX = "_muted_"
+
+
+def _ensure_mapping(value: Any) -> Dict[str, Any]:
+    if isinstance(value, Mapping):
+        return dict(value)
+    raise TypeError("Configuration root must be a mapping.")
+
+
+def _deep_freeze(node: Any) -> Any:
+    if isinstance(node, Mapping):
+        return FrozenConfig({k: _deep_freeze(v) for k, v in node.items()})
+    if isinstance(node, list):
+        return tuple(_deep_freeze(v) for v in node)
+    return node
+
+
+def _deep_clone(node: Any) -> Any:
+    if isinstance(node, Mapping):
+        return {k: _deep_clone(v) for k, v in node.items()}
+    if isinstance(node, list):
+        return [_deep_clone(v) for v in node]
+    return node
+
+
+def _set_by_path(target: MutableMapping[str, Any], dotted_key: str, value: Any) -> None:
+    parts = dotted_key.split(".")
+    cursor: MutableMapping[str, Any] = target
+    for key in parts[:-1]:
+        if key not in cursor or not isinstance(cursor[key], MutableMapping):
+            cursor[key] = {}
+        cursor = cursor[key]  # type: ignore[assignment]
+    cursor[parts[-1]] = value
+
+
+def _parse_scalar(value: str) -> Any:
+    try:
+        return ast.literal_eval(value)
+    except Exception:
+        return value
+
+
+@dataclass(frozen=True)
+class FrozenConfig(Mapping[str, Any]):
+    """Immutable configuration wrapper with dotted-key access."""
+
+    _data: Mapping[str, Any]
+
+    def __getitem__(self, key: str) -> Any:
+        return self._data[key]
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self._data)
+
+    def __len__(self) -> int:
+        return len(self._data)
+
+    def get(self, dotted_key: str, default: Any = None) -> Any:
+        cursor: Any = self
+        for part in dotted_key.split("."):
+            if isinstance(cursor, Mapping) and part in cursor:
+                cursor = cursor[part]
+            else:
+                return default
+        return cursor
+
+    def to_dict(self) -> Dict[str, Any]:
+        def thaw(value: Any) -> Any:
+            if isinstance(value, FrozenConfig):
+                return {k: thaw(v) for k, v in value.items()}
+            if isinstance(value, tuple):
+                return [thaw(v) for v in value]
+            return value
+
+        return {k: thaw(v) for k, v in self.items()}
+
+
+def merge_dicts(base: Mapping[str, Any], override: Mapping[str, Any]) -> Dict[str, Any]:
+    result = _deep_clone(base)
+    for key, value in override.items():
+        if key in result and isinstance(result[key], Mapping) and isinstance(value, Mapping):
+            result[key] = merge_dicts(result[key], value)
+        else:
+            result[key] = _deep_clone(value)
+    return result
+
+
+def apply_overrides(cfg: Mapping[str, Any], overrides: Sequence[str] | Mapping[str, Any]) -> Dict[str, Any]:
+    result = _deep_clone(cfg)
+    if isinstance(overrides, Mapping):
+        for key, value in overrides.items():
+            _set_by_path(result, key, value)
+    else:
+        for override in overrides:
+            if "=" not in override:
+                raise ValueError(f"Override '{override}' must contain '='.")
+            key, value = override.split("=", 1)
+            _set_by_path(result, key, _parse_scalar(value))
+    return result
+
+
+def _load_from_path(path: Path) -> Dict[str, Any]:
+    with path.open("r", encoding="utf-8") as handle:
+        if path.suffix in {".yaml", ".yml"}:
+            if yaml is None:
+                raise RuntimeError("PyYAML is required to load YAML configs.")
+            data = yaml.safe_load(handle)
+        else:
+            data = json.load(handle)
+    return _ensure_mapping(data)
+
+
+# _base_ path prefix: paths are relative to oriented-det repository root (ORIENTED_DET_ROOT).
+ODET_BASE_PREFIX = "@odet:"
+
+
+def _oriented_det_root() -> Path:
+    """oriented-det repository root (``ORIENTED_DET_ROOT``)."""
+    raw = os.environ.get("ORIENTED_DET_ROOT")
+    if raw:
+        return Path(raw).expanduser().resolve()
+    try:
+        import oriented_det  # noqa: WPS433 — runtime package location
+    except ImportError as exc:
+        raise FileNotFoundError(
+            "Cannot resolve @odet: base — set ORIENTED_DET_ROOT or install oriented_det."
+        ) from exc
+    return Path(oriented_det.__file__).resolve().parent.parent
+
+
+def _framework_config_roots() -> list[Path]:
+    """Framework config directories to try for ``_base_`` fallbacks (in order).
+
+    Resolution order:
+    - ``ORIENTED_DET_CONFIG_ROOT`` (explicit override, sole entry when set)
+    - Editable checkout: ``<repo>/configs`` (full tree; preferred over vendored subset)
+    - Vendored wheel subset: ``oriented_det/configs``
+    """
+    roots: list[Path] = []
+    seen: set[Path] = set()
+
+    def _add(root: Path | None) -> None:
+        if root is None:
+            return
+        resolved = root.expanduser().resolve()
+        if resolved.is_dir() and resolved not in seen:
+            seen.add(resolved)
+            roots.append(resolved)
+
+    env = os.environ.get("ORIENTED_DET_CONFIG_ROOT")
+    if env:
+        _add(Path(env))
+        return roots
+
+    try:
+        import oriented_det
+
+        pkg = Path(oriented_det.__file__).resolve().parent
+        repo_configs = pkg.parent / "configs"
+        vendored = pkg / "configs"
+        # Repo tree is authoritative in editable installs; vendored may omit schedules like 6x.
+        if repo_configs.is_dir() and repo_configs != vendored:
+            _add(repo_configs)
+        _add(vendored)
+    except Exception:
+        pass
+    return roots
+
+
+def _framework_config_root() -> Path | None:
+    """Primary framework config tree (first entry from :func:`_framework_config_roots`)."""
+    roots = _framework_config_roots()
+    return roots[0] if roots else None
+
+
+def _normalize_base_ref_for_framework(base_path: str) -> str:
+    """Strip leading ``../`` so ``../_base_/models/x.json`` -> ``_base_/models/x.json``."""
+    ref = base_path.replace("\\", "/").lstrip("/")
+    while ref.startswith("../"):
+        ref = ref[3:]
+    if ref.startswith("./"):
+        ref = ref[2:]
+    return ref
+
+
+def _resolve_base_path(base_path: str, current_file: Path) -> Path:
+    """Resolve a _base_ reference: @odet:, absolute, file-relative, or framework fallback.
+
+    External projects can keep dataset bases locally and inherit
+    model/schedule bases from the framework ``configs/_base_/`` tree when absent.
+    """
+    if base_path.startswith(ODET_BASE_PREFIX):
+        rel = base_path[len(ODET_BASE_PREFIX) :].lstrip("/")
+        return (_oriented_det_root() / rel).resolve()
+
+    base_path_obj = Path(base_path)
+    if base_path_obj.is_absolute():
+        if not base_path_obj.exists():
+            raise FileNotFoundError(f"Config file not found: {base_path_obj}")
+        return base_path_obj
+
+    local = (current_file.parent / base_path_obj).resolve()
+    if local.exists():
+        return local
+
+    rel = _normalize_base_ref_for_framework(base_path)
+    checked: list[Path] = []
+    for fw_root in _framework_config_roots():
+        fallback = (fw_root / rel).resolve()
+        checked.append(fallback)
+        if fallback.exists():
+            return fallback
+
+    raise FileNotFoundError(
+        f"Config file not found: {local}"
+        + (f" (also checked framework: {', '.join(str(p) for p in checked)})" if checked else "")
+    )
+
+
+def _strip_muted_keys(cfg: Dict[str, Any], prefix: str = MUTED_KEY_PREFIX) -> None:
+    """Remove keys starting with prefix recursively. Modifies cfg in place."""
+    keys_to_remove = [k for k in cfg if isinstance(k, str) and k.startswith(prefix)]
+    for k in keys_to_remove:
+        del cfg[k]
+    for v in cfg.values():
+        if isinstance(v, dict):
+            _strip_muted_keys(v, prefix)
+
+
+def _delete_keys(cfg: Dict[str, Any], keys_to_delete: Dict[str, Any]) -> None:
+    """Delete keys specified in keys_to_delete from cfg.
+    
+    MMRotate-style deletion: {"key": {"_delete_": True}} removes "key" from parent.
+    """
+    for key, value in keys_to_delete.items():
+        if isinstance(value, dict) and value.get("_delete_") is True:
+            if key in cfg:
+                del cfg[key]
+        elif isinstance(value, dict) and isinstance(cfg.get(key), dict):
+            _delete_keys(cfg[key], value)
+
+
+def _load_config_with_base(
+    path: Path,
+    *,
+    visited: set[Path] | None = None,
+) -> Dict[str, Any]:
+    """Load config file and recursively resolve _base_ inheritance.
+    
+    Args:
+        path: Path to config file
+        visited: Set of already visited paths to detect circular dependencies
+        
+    Returns:
+        Merged configuration dictionary with _base_ resolved
+    """
+    if visited is None:
+        visited = set()
+    
+    path = path.resolve()
+    
+    # Detect circular dependencies
+    if path in visited:
+        raise ValueError(f"Circular dependency detected: {path} is already being loaded")
+    visited.add(path)
+    
+    if not path.exists():
+        raise FileNotFoundError(f"Config file not found: {path}")
+    
+    cfg_dict = _load_from_path(path)
+    
+    # Handle _base_ inheritance
+    if "_base_" in cfg_dict:
+        base_refs = cfg_dict.pop("_base_")
+        
+        # Normalize to list
+        if isinstance(base_refs, str):
+            base_refs = [base_refs]
+        elif not isinstance(base_refs, list):
+            raise TypeError(f"_base_ must be a string or list of strings, got {type(base_refs)}")
+        
+        # Load and merge base configs in order
+        merged = {}
+        for base_ref in base_refs:
+            if not isinstance(base_ref, str):
+                raise TypeError(f"Base reference must be a string, got {type(base_ref)}")
+            base_path = _resolve_base_path(base_ref, path)
+            base_cfg = _load_config_with_base(base_path, visited=visited)
+            merged = merge_dicts(merged, base_cfg)
+        
+        # Merge current config over base configs
+        merged = merge_dicts(merged, cfg_dict)
+        cfg_dict = merged
+    
+    visited.remove(path)
+    return cfg_dict
+
+
+def load_config(
+    source: str | os.PathLike[str] | Mapping[str, Any],
+    *,
+    overrides: Sequence[str] | Mapping[str, Any] | None = None,
+) -> FrozenConfig:
+    """Load a configuration file or dict and apply optional overrides.
+    
+    Supports MMRotate-style nested config inheritance via _base_ field.
+    
+    Args:
+        source: Path to config file or dict
+        overrides: Optional overrides to apply after loading
+        
+    Returns:
+        FrozenConfig instance with merged configuration
+        
+    Examples:
+        >>> # Simple config
+        >>> cfg = load_config("config.json")
+        
+        >>> # Config with base inheritance
+        >>> # config.json: {"_base_": "base.json", "lr": 0.01}
+        >>> cfg = load_config("config.json")
+        
+        >>> # With overrides
+        >>> cfg = load_config("config.json", overrides=["training.lr=0.001"])
+    """
+    if isinstance(source, Mapping):
+        cfg_dict = _deep_clone(_ensure_mapping(source))
+        _strip_muted_keys(cfg_dict)
+    else:
+        path = Path(source)
+        if not path.exists():
+            raise FileNotFoundError(path)
+        # Load with base inheritance support
+        cfg_dict = _load_config_with_base(path)
+    
+    # Strip _muted_* keys (keeps alternative values visible without affecting behavior)
+    _strip_muted_keys(cfg_dict)
+    
+    # Handle deletion syntax (must be done before overrides)
+    _delete_keys(cfg_dict, cfg_dict)
+    
+    if overrides:
+        cfg_dict = apply_overrides(cfg_dict, overrides)
+
+    return _deep_freeze(cfg_dict)
+
+
+__all__ = [
+    "ODET_BASE_PREFIX",
+    "FrozenConfig",
+    "MUTED_KEY_PREFIX",
+    "load_config",
+    "merge_dicts",
+    "apply_overrides",
+]

oriented_det/utils/device.py

@@ -0,0 +1,35 @@
+"""Device selection helpers for CPU, CUDA, and MPS (Apple Silicon)."""
+
+from __future__ import annotations
+
+try:
+    import torch
+except ImportError:
+    torch = None  # type: ignore
+
+
+def get_device(prefer_cuda: bool = True) -> "torch.device":
+    """Return the best available device: CUDA > MPS (Apple Silicon) > CPU.
+
+    Use this when you want training or inference to use GPU when possible,
+    including on macOS with M1/M2/M3 (MPS).
+    """
+    if torch is None:
+        raise RuntimeError("PyTorch is required for device selection.")
+    if prefer_cuda and torch.cuda.is_available():
+        return torch.device("cuda")
+    if getattr(torch.backends, "mps", None) and torch.backends.mps.is_available():
+        return torch.device("mps")
+    return torch.device("cpu")
+
+
+def is_gpu_device(device: "torch.device") -> bool:
+    """Return True if the device is a GPU (CUDA or MPS)."""
+    if device is None:
+        return False
+    device_type = device.type if hasattr(device, "type") else str(device).split(":")[0]
+    if device_type == "cuda":
+        return torch is not None and torch.cuda.is_available()
+    if device_type == "mps":
+        return torch is not None and getattr(torch.backends, "mps", None) is not None and torch.backends.mps.is_available()
+    return False

oriented_det/utils/logging.py

@@ -0,0 +1,163 @@
+"""Logging and tracing utilities for oriented-det framework.
+
+This module provides configurable logging for debugging and performance analysis.
+"""
+
+from __future__ import annotations
+
+import time
+from contextlib import contextmanager
+from typing import Optional, Callable, Any
+import functools
+
+
+class TraceLogger:
+    """Configurable logger for tracing function execution."""
+    
+    _enabled: bool = False
+    _indent_level: int = 0
+    _indent_str: str = "  "
+    
+    @classmethod
+    def enable(cls) -> None:
+        """Enable tracing/logging."""
+        cls._enabled = True
+    
+    @classmethod
+    def disable(cls) -> None:
+        """Disable tracing/logging."""
+        cls._enabled = False
+    
+    @classmethod
+    def is_enabled(cls) -> bool:
+        """Check if tracing is enabled."""
+        return cls._enabled
+    
+    @classmethod
+    def trace(cls, message: str, *args, **kwargs) -> None:
+        """Print a trace message if logging is enabled."""
+        if cls._enabled:
+            indent = cls._indent_str * cls._indent_level
+            formatted_msg = message.format(*args, **kwargs) if args or kwargs else message
+            print(f"{indent}{formatted_msg}")
+    
+    @classmethod
+    @contextmanager
+    def trace_block(cls, message: str, *args, **kwargs):
+        """Context manager for tracing a code block with timing."""
+        if cls._enabled:
+            formatted_msg = message.format(*args, **kwargs) if args or kwargs else message
+            cls.trace(f"→ {formatted_msg}")
+            cls._indent_level += 1
+            start_time = time.time()
+            try:
+                yield
+            finally:
+                elapsed = time.time() - start_time
+                cls._indent_level -= 1
+                cls.trace(f"✅ {formatted_msg} ({elapsed:.3f}s)")
+        else:
+            yield
+    
+    @classmethod
+    def trace_timing(cls, message: str, elapsed: float, *args, **kwargs) -> None:
+        """Trace a message with timing information."""
+        if cls._enabled:
+            formatted_msg = message.format(*args, **kwargs) if args or kwargs else message
+            cls.trace(f"{formatted_msg} ({elapsed:.3f}s)")
+    
+    @classmethod
+    def trace_value(cls, name: str, value: Any, unit: Optional[str] = None) -> None:
+        """Trace a value with optional unit."""
+        if cls._enabled:
+            if unit:
+                cls.trace(f"{name}: {value} {unit}")
+            else:
+                cls.trace(f"{name}: {value}")
+
+
+# Global instance
+logger = TraceLogger()
+
+
+def trace_function(func_name: Optional[str] = None):
+    """Decorator to trace function execution.
+    
+    Args:
+        func_name: Optional custom name for the function in logs.
+                   If None, uses the actual function name.
+    
+    Example:
+        @trace_function()
+        def my_function(x, y):
+            return x + y
+        
+        @trace_function("custom_name")
+        def another_function():
+            pass
+    """
+    def decorator(func: Callable) -> Callable:
+        name = func_name or func.__name__
+        
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            if logger.is_enabled():
+                # Format arguments for display
+                args_str = ", ".join([str(arg)[:50] for arg in args[:3]])
+                if len(args) > 3:
+                    args_str += f", ... (+{len(args)-3} more)"
+                kwargs_str = ", ".join([f"{k}={str(v)[:30]}" for k, v in list(kwargs.items())[:2]])
+                if len(kwargs) > 2:
+                    kwargs_str += f", ... (+{len(kwargs)-2} more)"
+                
+                call_str = f"{name}({args_str}"
+                if kwargs_str:
+                    call_str += f", {kwargs_str}"
+                call_str += ")"
+                
+                logger.trace(f"→ {call_str}")
+                logger._indent_level += 1
+                start_time = time.time()
+                try:
+                    result = func(*args, **kwargs)
+                    elapsed = time.time() - start_time
+                    logger._indent_level -= 1
+                    logger.trace(f"✅ {name} returned ({elapsed:.3f}s)")
+                    return result
+                except Exception as e:
+                    elapsed = time.time() - start_time
+                    logger._indent_level -= 1
+                    logger.trace(f"❌ {name} raised {type(e).__name__}: {e} ({elapsed:.3f}s)")
+                    raise
+            else:
+                return func(*args, **kwargs)
+        
+        return wrapper
+    return decorator
+
+
+# Convenience functions
+def enable_tracing() -> None:
+    """Enable tracing globally."""
+    logger.enable()
+
+
+def disable_tracing() -> None:
+    """Disable tracing globally."""
+    logger.disable()
+
+
+def is_tracing_enabled() -> bool:
+    """Check if tracing is enabled."""
+    return logger.is_enabled()
+
+
+__all__ = [
+    "TraceLogger",
+    "logger",
+    "trace_function",
+    "enable_tracing",
+    "disable_tracing",
+    "is_tracing_enabled",
+]
+

oriented_det/utils/progress.py

@@ -0,0 +1,62 @@
+"""Progress bar streams: show tqdm on the real console when stderr is piped (e.g. ``2>&1 | tee log``)."""
+
+from __future__ import annotations
+
+import atexit
+import os
+import sys
+from typing import Any, Optional, TextIO
+
+# Lazily opened /dev/tty (or Windows CON) for tqdm; closed at exit.
+_tqdm_tty: Optional[TextIO] = None
+_tqdm_tty_open_failed: bool = False
+_devnull: Optional[TextIO] = None
+
+
+def _close_tqdm_tty() -> None:
+    global _tqdm_tty
+    if _tqdm_tty is not None:
+        try:
+            _tqdm_tty.close()
+        except Exception:
+            pass
+        _tqdm_tty = None
+
+
+def _get_devnull() -> TextIO:
+    global _devnull
+    if _devnull is None:
+        _devnull = open(os.devnull, "w")
+    return _devnull
+
+
+def tqdm_progress_stream() -> Any:
+    """File object for ``tqdm(..., file=...)``, aligned with :func:`tools.train` / ``progress_stream`` on the training loop.
+
+    * If ``sys.stderr`` is a TTY, use it (normal interactive run).
+    * If not (shell redirect / ``| tee``), try ``/dev/tty`` (POSIX) or ``CON`` (Windows) so the bar
+      still updates on the user’s terminal while other output is captured in a file.
+    * If none of that works, use ``os.devnull`` so logs are not flooded with control characters.
+    """
+    global _tqdm_tty, _tqdm_tty_open_failed
+    if sys.stderr.isatty():
+        return sys.stderr
+    if _tqdm_tty is not None:
+        return _tqdm_tty
+    if not _tqdm_tty_open_failed:
+        if os.name == "posix":
+            try:
+                # Still works when e.g. ``python ... 2>&1 | tee x.log`` (stderr is a pipe, not a TTY).
+                _tqdm_tty = open("/dev/tty", "w", encoding="utf-8", buffering=1)
+                atexit.register(_close_tqdm_tty)
+                return _tqdm_tty
+            except OSError:
+                _tqdm_tty_open_failed = True
+        elif os.name == "nt":
+            try:
+                _tqdm_tty = open("CON", "w", encoding="utf-8", errors="replace", buffering=1)
+                atexit.register(_close_tqdm_tty)
+                return _tqdm_tty
+            except OSError:
+                _tqdm_tty_open_failed = True
+    return _get_devnull()