khoroos 0.1.0__py3-none-any.whl

khoroos/__init__.py

@@ -0,0 +1,110 @@
+"""Khoroos — a toolkit for poultry behavior analysis.
+
+Typical use::
+
+    from khoroos import analyze_video
+
+    result = analyze_video("farm.mp4", preset="balanced")
+    print(result.metrics["time_budget"])
+
+Or from the command line::
+
+    khoroos ui                      # web interface
+    khoroos analyze farm.mp4 -o out # batch analysis
+"""
+
+from khoroos.config import (
+    ACTION_CLASSES,
+    BEHAVIOUR_GROUPS,
+    PRESETS,
+    UNCERTAIN_LABEL,
+    AnalysisParams,
+    Settings,
+    get_settings,
+    params_for_preset,
+)
+from khoroos.pipeline.types import (
+    ActionPrediction,
+    AnalysisResult,
+    ProgressEvent,
+    Track,
+    Tracklet,
+    VideoInfo,
+)
+
+
+def _installed_version() -> str:
+    """Read the version from package metadata, so pyproject.toml stays its one source."""
+    from importlib.metadata import PackageNotFoundError, version
+
+    try:
+        return version("khoroos")
+    except PackageNotFoundError:  # running from a source tree that was never installed
+        return "0.0.0+unknown"
+
+
+__version__ = _installed_version()
+
+__all__ = [
+    "ACTION_CLASSES",
+    "BEHAVIOUR_GROUPS",
+    "PRESETS",
+    "UNCERTAIN_LABEL",
+    "ActionPrediction",
+    "Detector",
+    "VideoClassifier",
+    "Tracker",
+    "VideoReader",
+    "PipelineComponents",
+    "SelectedClasses",
+    "AnalysisParams",
+    "AnalysisResult",
+    "AnalysisRunner",
+    "ProgressEvent",
+    "RunArtifacts",
+    "Settings",
+    "Track",
+    "Tracklet",
+    "VideoAnalyzer",
+    "VideoInfo",
+    "__version__",
+    "analyze_video",
+    "describe_environment",
+    "get_settings",
+    "params_for_preset",
+]
+
+#: Names served lazily, and the module each comes from. Everything here transitively
+#: imports torch.
+_LAZY = {
+    "Detector": "khoroos.interfaces",
+    "VideoClassifier": "khoroos.interfaces",
+    "Tracker": "khoroos.interfaces",
+    "VideoReader": "khoroos.interfaces",
+    "PipelineComponents": "khoroos.pipeline.components",
+    "SelectedClasses": "khoroos.models.selection",
+    "AnalysisRunner": "khoroos.pipeline.runner",
+    "RunArtifacts": "khoroos.pipeline.runner",
+    "VideoAnalyzer": "khoroos.pipeline.analyze",
+    "analyze_video": "khoroos.pipeline.analyze",
+    "describe_environment": "khoroos.environment",
+}
+
+
+def __getattr__(name: str):
+    """Defer the heavy pipeline import until something actually needs it.
+
+    Importing :mod:`khoroos` must stay cheap — the CLI touches it just to print a
+    version, and pulling in torch and transformers for that costs seconds.
+    """
+    module_name = _LAZY.get(name)
+    if module_name is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+    from importlib import import_module
+
+    return getattr(import_module(module_name), name)
+
+
+def __dir__() -> list[str]:
+    return sorted(__all__)

khoroos/annotations/__init__.py

@@ -0,0 +1,6 @@
+"""Interchangeable per-image bounding-box annotation codecs."""
+
+from khoroos.annotations.codecs import AnnotationCodec, CocoCodec, YoloCodec, annotation_codec
+from khoroos.annotations.detections import Detections
+
+__all__ = ["AnnotationCodec", "CocoCodec", "Detections", "YoloCodec", "annotation_codec"]

khoroos/annotations/codecs.py

@@ -0,0 +1,164 @@
+"""Per-image YOLO text and COCO JSON bounding-box interchange.
+
+These codecs handle detection annotations, not segmentation or keypoints. COCO category
+IDs are preserved explicitly; YOLO IDs are supplied by a caller-defined ordered mapping.
+"""
+
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+from typing import Any
+
+import numpy as np
+
+from khoroos.annotations.detections import Detections
+
+
+def _size(width: int, height: int):
+    if width <= 0 or height <= 0:
+        raise ValueError("Image width and height must be positive")
+
+
+def _bounds(detections: Detections, width: int, height: int):
+    _size(width, height)
+    boxes = detections.boxes
+    if (
+        np.any(boxes < -1e-4)
+        or np.any(boxes[:, [0, 2]] > width + 1e-4)
+        or np.any(boxes[:, [1, 3]] > height + 1e-4)
+    ):
+        raise ValueError("Annotation boxes must lie within image bounds")
+
+
+class AnnotationCodec(ABC):
+    """Implement encode/decode to add another per-image annotation protocol."""
+
+    @abstractmethod
+    def encode(self, detections: Detections, *, width: int, height: int) -> Any:
+        raise NotImplementedError
+
+    @abstractmethod
+    def decode(self, payload: Any, *, width: int, height: int) -> Detections:
+        raise NotImplementedError
+
+
+class YoloCodec(AnnotationCodec):
+    """Standard five-column YOLO labels: class cx cy w h, normalized to image size.
+
+    category_ids maps YOLO's contiguous zero-based IDs to canonical category IDs. Standard
+    YOLO labels have no scores: encoding drops scores and decoding assigns 1.0.
+    """
+
+    def __init__(self, category_ids: Sequence[int] | None = None):
+        self.category_ids = None if category_ids is None else list(category_ids)
+        if self.category_ids is not None and (
+            not self.category_ids
+            or len(set(self.category_ids)) != len(self.category_ids)
+            or any(not isinstance(i, int) or i < 0 for i in self.category_ids)
+        ):
+            raise ValueError("category_ids must be unique nonnegative integers")
+
+    def encode(self, detections, *, width, height) -> str:
+        _bounds(detections, width, height)
+        lines = []
+        for box, category in zip(detections.boxes, detections.class_ids, strict=True):
+            category = int(category)
+            if self.category_ids is not None:
+                category = self.category_ids.index(category)
+            x1, y1, x2, y2 = box
+            values = [
+                (x1 + x2) / (2 * width),
+                (y1 + y2) / (2 * height),
+                (x2 - x1) / width,
+                (y2 - y1) / height,
+            ]
+            lines.append(f"{category} " + " ".join(f"{v:.9g}" for v in values))
+        return "\n".join(lines) + ("\n" if lines else "")
+
+    def decode(self, payload: str, *, width, height) -> Detections:
+        _size(width, height)
+        boxes, ids = [], []
+        for line in payload.splitlines():
+            if not line.strip():
+                continue
+            fields = line.split()
+            if len(fields) != 5:
+                raise ValueError("YOLO rows must contain class cx cy width height")
+            category = int(fields[0])
+            if category < 0:
+                raise ValueError("YOLO class IDs must be nonnegative")
+            if self.category_ids is not None:
+                if category >= len(self.category_ids):
+                    raise ValueError(f"Unknown YOLO class ID {category}")
+                category = self.category_ids[category]
+            cx, cy, w, h = map(float, fields[1:])
+            if not all(np.isfinite(v) and 0 <= v <= 1 for v in (cx, cy, w, h)):
+                raise ValueError("YOLO coordinates must be finite and normalized to [0, 1]")
+            boxes.append(
+                [
+                    (cx - w / 2) * width,
+                    (cy - h / 2) * height,
+                    (cx + w / 2) * width,
+                    (cy + h / 2) * height,
+                ]
+            )
+            ids.append(category)
+        result = Detections(np.asarray(boxes).reshape(-1, 4), np.ones(len(boxes)), np.array(ids))
+        _bounds(result, width, height)
+        return result
+
+
+class CocoCodec(AnnotationCodec):
+    """COCO per-image annotation records with pixel [x, y, width, height] boxes.
+
+    Use image_id to select records from a dataset's annotations list. IDs generated during
+    encoding start at annotation_id; callers assembling datasets must allocate unique IDs.
+    Scores are preserved when present, defaulting to 1.0 for ground-truth records.
+    """
+
+    def __init__(self, image_id: int = 0, annotation_id: int = 1):
+        self.image_id = image_id
+        self.annotation_id = annotation_id
+
+    def encode(self, detections, *, width, height) -> list[dict]:
+        _bounds(detections, width, height)
+        records = []
+        for i, (box, score, category) in enumerate(
+            zip(detections.boxes, detections.scores, detections.class_ids, strict=True)
+        ):
+            x1, y1, x2, y2 = map(float, box)
+            records.append(
+                {
+                    "id": self.annotation_id + i,
+                    "image_id": self.image_id,
+                    "category_id": int(category),
+                    "bbox": [x1, y1, x2 - x1, y2 - y1],
+                    "area": (x2 - x1) * (y2 - y1),
+                    "iscrowd": 0,
+                    "score": float(score),
+                }
+            )
+        return records
+
+    def decode(self, payload: list[dict], *, width, height) -> Detections:
+        _size(width, height)
+        boxes, scores, ids = [], [], []
+        for row in payload:
+            if row["image_id"] != self.image_id:
+                continue
+            x, y, w, h = row["bbox"]
+            boxes.append([x, y, x + w, y + h])
+            scores.append(row.get("score", 1.0))
+            ids.append(row["category_id"])
+        result = Detections(np.asarray(boxes).reshape(-1, 4), np.array(scores), np.array(ids))
+        _bounds(result, width, height)
+        return result
+
+
+def annotation_codec(name: str, **options) -> AnnotationCodec:
+    """Select a built-in codec by name; custom codecs can be passed directly."""
+    codecs = {"yolo": YoloCodec, "coco": CocoCodec}
+    try:
+        codec = codecs[name.lower()]
+    except KeyError:
+        raise ValueError(f"Unknown annotation protocol {name!r}; choose yolo or coco") from None
+    return codec(**options)

khoroos/annotations/detections.py

@@ -0,0 +1,94 @@
+"""Canonical detections and explicit normalization of legacy detector outputs."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+import numpy as np
+
+InvalidBoxes = Literal["error", "drop"]
+
+
+def _arrays(boxes, scores, class_ids):
+    boxes = np.asarray(boxes, dtype=np.float32)
+    scores = np.asarray(scores, dtype=np.float32)
+    if boxes.ndim != 2 or boxes.shape[1] != 4 or scores.shape != (len(boxes),):
+        raise ValueError("Expected boxes (N, 4) and scores (N,)")
+    if not np.isfinite(scores).all() or np.any((scores < 0) | (scores > 1)):
+        raise ValueError("Scores must be finite and in [0, 1]")
+    ids = np.zeros(len(boxes), dtype=np.int64) if class_ids is None else np.asarray(class_ids)
+    if (
+        ids.shape != (len(boxes),)
+        or not np.isfinite(ids).all()
+        or np.any(ids < 0)
+        or np.any(ids != np.floor(ids))
+    ):
+        raise ValueError("class_ids must be nonnegative integers with shape (N,)")
+    return boxes, scores, ids.astype(np.int64)
+
+
+def _valid_boxes(boxes):
+    return np.isfinite(boxes).all(axis=1) & (boxes[:, 2:] > boxes[:, :2]).all(axis=1)
+
+
+def _readonly(array):
+    # A bytes-backed copy cannot be changed through input aliases or setflags(write=True).
+    return np.frombuffer(array.tobytes(), dtype=array.dtype).reshape(array.shape)
+
+
+@dataclass(frozen=True, eq=False)
+class Detections:
+    """Immutable pixel xyxy boxes, scores, and nonnegative integer category IDs.
+
+    Unpacking yields boxes and scores for the single-population tracking interface.
+    dropped_count records boxes explicitly discarded during normalization; it is never
+    inferred from confidence filtering or NMS. Array shapes, scores and category IDs are
+    always strict. Geometry can be discarded only via from_raw(invalid_boxes="drop").
+    """
+
+    boxes: np.ndarray
+    scores: np.ndarray
+    class_ids: np.ndarray | None = None
+    dropped_count: int = 0
+
+    def __post_init__(self):
+        boxes, scores, ids = _arrays(self.boxes, self.scores, self.class_ids)
+        if not _valid_boxes(boxes).all():
+            raise ValueError("Boxes must be finite with positive width and height")
+        if not isinstance(self.dropped_count, int) or self.dropped_count < 0:
+            raise ValueError("dropped_count must be a nonnegative integer")
+        for name, array in (("boxes", boxes), ("scores", scores), ("class_ids", ids)):
+            object.__setattr__(self, name, _readonly(array))
+
+    @classmethod
+    def from_raw(
+        cls, boxes, scores, class_ids=None, *, invalid_boxes: InvalidBoxes = "error"
+    ) -> Detections:
+        """Normalize raw arrays, optionally dropping invalid geometry with a recorded count."""
+        if invalid_boxes not in ("error", "drop"):
+            raise ValueError("invalid_boxes must be 'error' or 'drop'")
+        if invalid_boxes == "error":
+            return cls(boxes, scores, class_ids)
+        boxes, scores, ids = _arrays(boxes, scores, class_ids)
+        valid = _valid_boxes(boxes)
+        return cls(boxes[valid], scores[valid], ids[valid], dropped_count=int((~valid).sum()))
+
+    @classmethod
+    def coerce(cls, value, *, invalid_boxes: InvalidBoxes = "error") -> Detections:
+        """Accept canonical detections or a legacy (boxes, scores) pair at the boundary.
+
+        Canonical objects are returned unchanged, preserving category IDs and drop counts.
+        """
+        if isinstance(value, cls):
+            return value
+        if not isinstance(value, (tuple, list)) or len(value) != 2:
+            raise ValueError("Detector output must be Detections or a (boxes, scores) pair")
+        return cls.from_raw(*value, invalid_boxes=invalid_boxes)
+
+    def __iter__(self):
+        yield self.boxes
+        yield self.scores
+
+    def __len__(self):
+        return len(self.boxes)

khoroos/cli.py

@@ -0,0 +1,306 @@
+"""Command-line interface."""
+
+from __future__ import annotations
+
+import json
+import logging
+import sys
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from khoroos.config import (
+    PRESETS,
+    get_settings,
+    params_for_preset,
+    parse_overrides,
+)
+
+app = typer.Typer(
+    name="khoroos",
+    help="Poultry behavior analysis from farm video.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+models_app = typer.Typer(name="models", help="Manage model checkpoints.", no_args_is_help=True)
+app.add_typer(models_app)
+
+
+def _setup_logging(verbose: bool) -> None:
+    logging.basicConfig(
+        level=logging.DEBUG if verbose else logging.INFO,
+        format="%(levelname)s %(name)s: %(message)s",
+        stream=sys.stderr,
+    )
+
+
+def _runtime_settings(**overrides):
+    try:
+        return get_settings().with_overrides(**overrides)
+    except ValueError as exc:
+        raise typer.BadParameter(str(exc)) from exc
+
+
+@app.command()
+def analyze(
+    video: Annotated[Path, typer.Argument(help="Video file to analyse.")],
+    output: Annotated[Path, typer.Option("--output", "-o", help="Output directory.")] = Path(
+        "khoroos-output"
+    ),
+    preset: Annotated[
+        str, typer.Option("--preset", "-p", help=f"One of: {', '.join(PRESETS)}.")
+    ] = "balanced",
+    max_seconds: Annotated[
+        float | None, typer.Option("--max-seconds", help="Analyse only the first N seconds.")
+    ] = None,
+    min_confidence: Annotated[
+        float | None, typer.Option("--min-confidence", help="Below this, actions are 'uncertain'.")
+    ] = None,
+    detection_confidence: Annotated[
+        float | None,
+        typer.Option("--detection-confidence", help="Detector score threshold."),
+    ] = None,
+    detection_batch_size: Annotated[
+        int | None,
+        typer.Option(
+            "--detection-batch-size",
+            help="Frames per detector forward pass. Higher is faster but needs more memory.",
+        ),
+    ] = None,
+    action_batch_size: Annotated[
+        int | None,
+        typer.Option(
+            "--action-batch-size",
+            help="Clips per action-model forward pass. Each clip is 64 frames, so this "
+            "dominates memory use.",
+        ),
+    ] = None,
+    overlay: Annotated[
+        bool, typer.Option("--overlay/--no-overlay", help="Render an annotated video.")
+    ] = False,
+    set_param: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--set",
+            "-s",
+            metavar="NAME=VALUE",
+            help="Override any analysis parameter, e.g. -s window_seconds=3. Repeatable.",
+        ),
+    ] = None,
+    device: Annotated[str | None, typer.Option("--device", help="cuda, cpu, mps or auto.")] = None,
+    verbose: Annotated[bool, typer.Option("--verbose", "-v")] = False,
+) -> None:
+    """Analyse a video and write results to a directory."""
+    _setup_logging(verbose)
+
+    if not video.is_file():
+        typer.secho(f"No such video: {video}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(2)
+
+    settings = _runtime_settings(device=device)
+
+    try:
+        # The named flags are shorthands for the same fields `--set` reaches, so they go
+        # through one map. An explicit `--set` wins over its shorthand.
+        overrides: dict[str, object] = {
+            "max_duration_seconds": max_seconds,
+            "min_confidence": min_confidence,
+            "detection_confidence": detection_confidence,
+            "detection_batch_size": detection_batch_size,
+            "action_batch_size": action_batch_size,
+        }
+        overrides.update(parse_overrides(set_param or []))
+        params = params_for_preset(preset, **overrides)
+    except ValueError as exc:
+        typer.secho(str(exc), fg=typer.colors.RED, err=True)
+        raise typer.Exit(2) from None
+
+    from khoroos.pipeline.runner import AnalysisRunner
+
+    typer.echo(f"Analysing {video} [{preset}] on {settings.resolved_device()}")
+
+    with typer.progressbar(length=1000, label="starting") as bar:
+        position = 0
+
+        def on_progress(event) -> None:
+            # The bar never moves backwards: stage weights are approximate, and a bar that
+            # retreats reads as a bug during a run that already takes minutes.
+            nonlocal position
+            target = min(int(event.progress * 1000), 1000)
+            step = max(target - position, 0)
+            position += step
+            bar.label = event.stage
+            bar.update(step)
+
+        artifacts = AnalysisRunner(settings=settings).run(
+            video,
+            output_dir=output,
+            params=params,
+            render_overlay=overlay,
+            on_progress=on_progress,
+        )
+
+    _print_summary(artifacts.result)
+    typer.echo("\nWrote:")
+    for name, path in artifacts.paths.items():
+        typer.echo(f"  {name:12s} {path}")
+
+
+def _print_summary(result) -> None:
+    metrics = result.metrics
+    budget = metrics.get("time_budget", {})
+    population = metrics.get("population", {})
+
+    typer.echo("")
+    typer.secho("Summary", bold=True)
+    typer.echo(f"  video            {result.video.filename} ({result.video.duration_seconds:.1f}s)")
+    typer.echo(f"  runtime          {result.runtime_seconds:.1f}s")
+    typer.echo(f"  birds tracked    {len(result.tracks)}")
+    typer.echo(f"  mean in frame    {population.get('mean', 0)}")
+    typer.echo(f"  clips classified {len(result.predictions)}")
+    typer.echo(f"  observed         {budget.get('total_bird_seconds', 0):.0f} bird-seconds")
+
+    by_class = budget.get("by_class", {})
+    if by_class:
+        typer.echo("\n  Time budget:")
+        for label, values in list(by_class.items())[:8]:
+            bar = "█" * int(values["share"] * 30)
+            typer.echo(f"    {label:18s} {values['share']:6.1%} {bar}")
+
+    for warning in result.warnings:
+        typer.secho(f"  [note] {warning}", fg=typer.colors.MAGENTA)
+
+
+@app.command()
+def ui(
+    host: Annotated[str | None, typer.Option("--host", help="Bind address.")] = None,
+    port: Annotated[int | None, typer.Option("--port", help="Port to listen on.")] = None,
+    no_browser: Annotated[
+        bool, typer.Option("--no-browser", help="Do not open a browser.")
+    ] = False,
+    device: Annotated[str | None, typer.Option("--device", help="cuda, cpu, mps or auto.")] = None,
+    verbose: Annotated[bool, typer.Option("--verbose", "-v")] = False,
+) -> None:
+    """Launch the web interface."""
+    _setup_logging(verbose)
+
+    settings = _runtime_settings(device=device, host=host, port=port)
+
+    try:
+        import uvicorn
+    except ImportError:
+        typer.secho(
+            "The web interface needs extra dependencies. Install them with:\n"
+            "  pip install 'khoroos[web]'",
+            fg=typer.colors.RED,
+        )
+        raise typer.Exit(1) from None
+
+    from khoroos.web.app import create_app
+
+    if settings.host not in ("127.0.0.1", "localhost", "::1"):
+        typer.secho(
+            f"Serving on {settings.host} exposes Khoroos to your network. It has no "
+            f"authentication — only do this on a trusted network.",
+            fg=typer.colors.YELLOW,
+        )
+
+    url = f"http://{settings.host}:{settings.port}"
+    typer.secho(f"Khoroos UI: {url}", fg=typer.colors.GREEN, bold=True)
+
+    if not no_browser:
+        import threading
+        import webbrowser
+
+        threading.Timer(1.5, lambda: webbrowser.open(url)).start()
+
+    web_app = create_app(settings)
+    try:
+        uvicorn.run(web_app, host=settings.host, port=settings.port, log_level="info")
+    finally:
+        web_app.state.jobs.close()
+
+
+@models_app.command("status")
+def models_status() -> None:
+    """Show where model checkpoints will be loaded from."""
+    from khoroos.models.registry import checkpoint_status
+
+    _print_checkpoints(checkpoint_status(get_settings()))
+
+
+@models_app.command("download")
+def models_download() -> None:
+    """Download model checkpoints so later runs work offline."""
+    from khoroos.models.registry import CheckpointNotFoundError, resolve_checkpoint
+
+    failed = False
+    for kind in ("detector", "action"):
+        typer.echo(f"Resolving {kind}...")
+        try:
+            path = resolve_checkpoint(kind, allow_download=True)
+        except CheckpointNotFoundError as exc:
+            failed = True
+            typer.secho(f"  {kind}: {exc}", fg=typer.colors.RED, err=True)
+        else:
+            typer.secho(f"  {kind}: {path}", fg=typer.colors.GREEN)
+    if failed:
+        raise typer.Exit(1)
+
+
+@app.command()
+def info(
+    as_json: Annotated[bool, typer.Option("--json", help="Emit machine-readable JSON.")] = False,
+) -> None:
+    """Show presets, behaviours and checkpoint status.
+
+    The same description the web UI builds its controls from.
+    """
+    from khoroos.environment import describe_environment
+
+    env = describe_environment(get_settings())
+
+    if as_json:
+        typer.echo(json.dumps(env, indent=2))
+        return
+
+    typer.secho(f"Khoroos {env['version']}", bold=True)
+    typer.echo(f"  device      {env['device']}")
+    typer.echo(f"  cache       {env['cache_dir']}")
+
+    typer.echo("\n  Presets:")
+    for name, values in env["presets"].items():
+        default = " (default)" if name == env["default_preset"] else ""
+        summary = " ".join(f"{k}={v}" for k, v in values.items())
+        typer.echo(f"    {name:10s}{default:10s} {summary}")
+
+    typer.echo("\n  Behaviours:")
+    for group, members in env["behaviour_groups"].items():
+        typer.echo(f"    {group:12s} {', '.join(members)}")
+
+    typer.echo("\n  Models:")
+    _print_checkpoints(env["models"])
+
+
+def _print_checkpoints(models: dict) -> None:
+    for kind, details in models.items():
+        if details["available"]:
+            typer.secho(f"    {kind:9s} ✓ {details['path']}", fg=typer.colors.GREEN)
+        else:
+            typer.secho(
+                f"    {kind:9s} ✗ not found locally (would download {details['hub_repo']})",
+                fg=typer.colors.YELLOW,
+            )
+
+
+@app.command()
+def version() -> None:
+    """Print the installed version."""
+    from khoroos import __version__
+
+    typer.echo(__version__)
+
+
+if __name__ == "__main__":
+    app()