sima-vision 0.0.2__py3-none-any.whl

sima_vision/__init__.py

@@ -0,0 +1,34 @@
+"""Live YOLO computer vision on a SiMa Modalix DevKit 3.0.
+
+Three applications share one pipeline: object detection, instance segmentation
+with an optional background blur, and fall detection with SMTP alerts. They
+differ only in what they do with a frame once the MLA has finished with it, so
+everything up to that point -- config loading, source geometry, the Neat graph,
+sample decoding, drawing and the sinks -- lives in this package and is written
+once.
+
+Run them from the command line::
+
+    sima-vision detect  --source clip.h264 --model yolo26m-det.tar.gz
+    sima-vision segment --source clip.h264 --model yolo26m-seg.tar.gz --blur
+    sima-vision fall    --source rtsp://camera/live --alert-to ops@example.com
+
+or from Python, with the same settings under the same names::
+
+    from sima_vision import run, preview, validate
+
+    preview("segment", out="blur.png", blur_strength=81)   # no board needed
+    run("detect", source="clip.h264", model="yolo26m-det.tar.gz", conf=0.5)
+
+Everything runs **on the DevKit**, not in the x86 SDK container: ``pyneat`` is
+compiled for aarch64. The imports that need it are deferred, so ``--validate``
+and ``--help`` work anywhere.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.0.2"
+
+from .api import load, preview, run, validate
+
+__all__ = ["__version__", "load", "preview", "run", "validate"]

sima_vision/api.py

@@ -0,0 +1,210 @@
+"""The Python API: the same three verbs the command line has.
+
+Every keyword these accept is derived from the CLI's own flags, so
+``--blur-strength 81`` and ``blur_strength=81`` cannot drift apart -- there is
+one table and it is built from the parser at import time.
+
+    from sima_vision import run, preview, validate
+
+    preview("segment", out="blur.png", blur_strength=81)
+    validate("detect", conf=0.5)
+    run("detect", source="clip.h264", model="yolo26m-det.tar.gz", conf=0.5)
+
+``preview`` and ``validate`` need no board. ``run`` needs the DevKit, because
+that is where the MLA is.
+"""
+
+from __future__ import annotations
+
+import argparse
+from functools import cache
+from pathlib import Path
+
+from .tasks import TASKS
+
+
+def _task(name: str):
+    if name not in TASKS:
+        raise ValueError(f"unknown task {name!r}. Choose one of: {', '.join(TASKS)}")
+    return TASKS[name]()
+
+
+def _alias_table(task) -> tuple[dict[str, str], set[str]]:
+    """Cached by task class -- the flags cannot change between calls."""
+    return _build_alias_table(type(task))
+
+
+@cache
+def _build_alias_table(task_cls) -> tuple[dict[str, str], set[str]]:
+    """Map Python keyword -> config path, straight off this task's CLI flags.
+
+    Returns the table and the set of keywords whose boolean has to be flipped:
+    ``--send`` turns ``alerts.dry_run`` *off*, so ``send=True`` must write
+    False. ``--no-save`` is registered as ``save`` for the same reason, in the
+    other direction -- nobody wants to write ``no_save=True``.
+    """
+    from .cli import add_shared_arguments
+
+    task = task_cls()
+    parser = argparse.ArgumentParser(add_help=False)
+    add_shared_arguments(parser)
+    task.add_arguments(parser.add_argument_group("task"))
+
+    aliases: dict[str, str] = {}
+    inverted: set[str] = set()
+    for action in parser._actions:
+        if "." not in action.dest:
+            continue
+        turns_off = getattr(action, "const", None) is False
+        for option in action.option_strings:
+            negative = option.startswith("--no-")
+            name = option.lstrip("-").replace("-", "_")
+            if negative:
+                name = name[3:]          # no_save -> save
+            # Two flags claiming one keyword would silently hide a setting --
+            # `--video PATH` and `--no-video` both wanted `video` once, and the
+            # path became unreachable from Python.
+            claimed = aliases.get(name)
+            if claimed is not None and claimed != action.dest:
+                raise RuntimeError(
+                    f"{task.name}: {option} wants the keyword {name!r}, which "
+                    f"already means {claimed!r}. Rename one of the flags."
+                )
+            aliases[name] = action.dest
+            # `--send` reads as "do send", but it clears a dry_run flag.
+            if turns_off and not negative:
+                inverted.add(name)
+    return aliases, inverted
+
+
+def settings_to_overrides(task, settings: dict) -> dict:
+    """Translate Python keywords into the dotted config paths the loader takes.
+
+    Dotted keys are passed through untouched, so anything the aliases do not
+    cover is still reachable::
+
+        run("detect", **{"runtime.output_buffers": 2})
+
+    Raises:
+        TypeError: On a keyword that is neither an alias nor a dotted path,
+            listing the near misses.
+    """
+    aliases, inverted = _alias_table(task)
+    overrides: dict = {}
+    for key, value in settings.items():
+        if "." in key:
+            overrides[key] = value
+            continue
+        path = aliases.get(key)
+        if path is None:
+            near = sorted(name for name in aliases if key in name or name in key)
+            hint = f" Did you mean: {', '.join(near[:5])}?" if near else ""
+            raise TypeError(f"{task.name}() got an unexpected setting {key!r}.{hint}")
+        overrides[path] = not value if key in inverted else value
+    return overrides
+
+
+def load(task: str, config: str | Path | None = None, use_config_file: bool = True,
+         **settings):
+    """Resolve a configuration the way the CLI does, and validate it.
+
+    Args:
+        task: ``detect``, ``segment`` or ``fall``.
+        config: Path to a config file, or None to look for ``./config.yaml``.
+        use_config_file: False ignores any file, like ``--no-config``.
+        **settings: Anything the CLI takes, as a keyword.
+
+    Returns:
+        A validated config for the task.
+    """
+    handle = _task(task)
+    return handle.load(
+        Path(config) if config else None,
+        settings_to_overrides(handle, settings),
+        use_file=use_config_file,
+    )
+
+
+def validate(task: str, config: str | Path | None = None, **settings):
+    """Check a configuration without a board. Raises ValueError if it is wrong.
+
+    Returns:
+        The resolved config, so it can be inspected.
+    """
+    return load(task, config, **settings)
+
+
+def run(task: str, config: str | Path | None = None, **settings) -> int:
+    """Run one task to completion. **Needs the DevKit.**
+
+    A clip or model archive that is missing is downloaded into ``assets/``
+    first; see :mod:`sima_vision.assets`. ``validate`` and ``preview`` resolve
+    the same paths and never fetch anything.
+
+    Args:
+        task: ``detect``, ``segment`` or ``fall``.
+        config: Path to a config file, or None to look for ``./config.yaml``.
+        **settings: Anything the CLI takes, as a keyword.
+
+    Returns:
+        The number of frames processed.
+    """
+    import os
+
+    from .runloop import Stopper
+    from .runtime import load_runtime_dependencies
+
+    handle = _task(task)
+    cfg = load(task, config, **settings)
+    load_runtime_dependencies()
+    # The same two side effects the command line has, so `run(...)` and
+    # `sima-vision <task>` really are the same run.
+    if cfg.profile:
+        os.environ.setdefault("SIMA_GST_ELEMENT_TIMINGS", "1")
+        os.environ.setdefault("SIMA_GST_FLOW_DEBUG", "1")
+    if cfg.save_enable:
+        Path(cfg.save_dir).mkdir(parents=True, exist_ok=True)
+    return handle.run(cfg, Stopper())
+
+
+def preview(task: str = "detect", config: str | Path | None = None,
+            out: str | Path = "preview.png", source: str | None = None,
+            size: tuple[int, int] = (1280, 720), use_config_file: bool = True,
+            **settings) -> Path:
+    """Draw the overlay a config produces, and write it to a PNG. **No board.**
+
+    Runs no model: the detections are synthetic and exist only to give the
+    drawing code something to draw.
+
+    Args:
+        task: ``detect``, ``segment`` or ``fall``.
+        config: Path to a config file, or None to look for ``./config.yaml``.
+        out: Where to write the PNG.
+        source: An image or video to draw on. None paints a synthetic scene.
+        size: Synthetic scene size, ignored when ``source`` is readable.
+        use_config_file: False ignores any file, like ``--no-config``.
+        **settings: Anything the CLI takes, as a keyword.
+
+    Returns:
+        The path written.
+    """
+    from . import runtime
+    from .cli import load_drawing_dependencies
+    from .scene import build_frame, render
+    from .sinks import load_labels
+
+    load_drawing_dependencies()
+    handle = _task(task)
+    config_path = Path(config) if config else None
+    cfg = handle.load(
+        config_path, settings_to_overrides(handle, settings), use_file=use_config_file
+    )
+
+    frame, subjects, _origin, _ = build_frame(source, size)
+    annotated = render(handle, cfg, frame, subjects, load_labels(cfg.labels_path))
+    out = Path(out)
+    if out.parent != Path("."):
+        out.parent.mkdir(parents=True, exist_ok=True)
+    if not runtime.cv2.imwrite(str(out), annotated):
+        raise RuntimeError(f"could not write {out}")
+    return out

sima_vision/assets.py

@@ -0,0 +1,340 @@
+"""Where the sample clips and model archives live, and how they get there.
+
+There is one ``assets/`` directory for the whole project rather than one inside
+each task folder. A clip is a clip: the same 13 MB of people walking through a
+mall feeds ``detect``, ``segment`` and ``fall``, and the detect archive is
+shared by ``detect`` and ``fall`` outright. Three copies of it said nothing that
+one copy does not.
+
+``--source`` and ``--model`` therefore take one of three things:
+
+1. a local path -- used as given
+2. an ``http(s)`` URL -- downloaded into ``assets/`` once, then reused
+3. nothing at all -- the task's default, downloaded on first run
+
+Case 3 is what makes ``sima-vision detect`` work on its own. The clips are on a
+public GitHub release so they are simply fetched. The model packs are behind a
+`community.sima.ai <https://community.sima.ai>`_ login -- the download URL
+answers a plain GET with a 302 to ``auth.sima.ai`` -- so those go through
+``sima-cli``, which already holds that login, and fall back to printing the
+command when it is not installed.
+
+Nothing here runs at config time. ``--validate`` and ``preview`` resolve the
+same paths and never touch the network; only :meth:`Task.run
+<sima_vision.tasks.base.Task.run>` calls :func:`ensure_assets`.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import shutil
+import subprocess
+import sys
+import urllib.error
+import urllib.request
+from dataclasses import dataclass, replace
+from pathlib import Path
+
+#: Overrides where downloads land. Default ``./assets`` in the working directory.
+ASSETS_ENV = "SIMA_VISION_ASSETS"
+
+#: Sample clips, already raw H.264 so they skip the Neat 0.3.0 demuxer bug.
+SAMPLE_RELEASE = "https://github.com/RizwanMunawar/sima-projects/releases/download/0.0.1"
+SAMPLE_VIDEOS = {
+    "people-walking-outside-mall.h264": "1920x1080 @ 24 fps, 13 MB. The usual default",
+    "people-walking-inside-mall.h264": "1920x1080 @ 30 fps, 1.2 MB. Quicker smoke test",
+}
+
+#: Where the SDK publishes compiled model packs.
+MODEL_BASE = "https://docs.sima.ai/pkg_downloads/SDK2.1.2/models/modalix"
+
+
+@dataclass(frozen=True)
+class TaskAssets:
+    """What one task runs on when it is given nothing.
+
+    Attributes:
+        model_dir: Model pack directory under :data:`MODEL_BASE`.
+        model_file: Archive name, which is also its name inside ``assets/models``.
+        clip: Sample clip name, a key of :data:`SAMPLE_VIDEOS`.
+    """
+
+    model_dir: str
+    model_file: str
+    clip: str
+
+
+#: Task name -> its default model and clip. ``detect`` and ``fall`` share a head.
+CATALOGUE: dict[str, TaskAssets] = {
+    "detect": TaskAssets(
+        "yolo26-detection",
+        "yolo26m-det-bf16-mla_tess-b1.tar.gz",
+        "people-walking-outside-mall.h264",
+    ),
+    "segment": TaskAssets(
+        "yolo26-segmentation",
+        "yolo26m-seg-bf16-mla_tess-b1.tar.gz",
+        "people-walking-outside-mall.h264",
+    ),
+    "fall": TaskAssets(
+        "yolo26-detection",
+        "yolo26m-det-bf16-mla_tess-b1.tar.gz",
+        "people-walking-inside-mall.h264",
+    ),
+}
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Locations
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def assets_root() -> Path:
+    """The ``assets/`` directory, honouring ``$SIMA_VISION_ASSETS``.
+
+    Read on every call rather than cached at import, so setting the variable
+    from a test -- or between two calls in one process -- takes effect.
+    """
+    return Path(os.environ.get(ASSETS_ENV) or "assets")
+
+
+def videos_dir() -> Path:
+    return assets_root() / "videos"
+
+
+def models_dir() -> Path:
+    return assets_root() / "models"
+
+
+def default_model_path(task: str) -> str:
+    """Where this task's model archive is expected, as a string for the config."""
+    return (models_dir() / CATALOGUE[task].model_file).as_posix()
+
+
+def default_source_uri(task: str) -> str:
+    """Where this task's sample clip is expected, as a string for the config."""
+    return (videos_dir() / CATALOGUE[task].clip).as_posix()
+
+
+def model_url(task: str) -> str:
+    entry = CATALOGUE[task]
+    return f"{MODEL_BASE}/{entry.model_dir}/{entry.model_file}"
+
+
+def model_command(task: str, into: Path | None = None) -> str:
+    """The one line that downloads the right model pack for a task.
+
+    ``sima-cli download`` needs a community.sima.ai login and writes into the
+    working directory, which is why this exists as a printable string as well as
+    something :func:`ensure_model` runs: getting the directory wrong is the
+    single most common way to end up with a pack the config cannot see.
+
+    Args:
+        task: Which pack to name.
+        into: The assets directory to write into, for ``fetch --into``. None
+            uses :func:`assets_root`, which is where a run looks.
+    """
+    models = ((into / "models") if into is not None else models_dir()).as_posix()
+    # A subshell rather than `cd there && ... && cd back`: the working directory
+    # you started in is where the rest of the commands expect to be, and one
+    # failed step in the middle of that chain would strand you in assets/models.
+    return f"mkdir -p {models} && (cd {models} && sima-cli download {model_url(task)})"
+
+
+def is_url(value: str) -> bool:
+    """True for something to download. ``rtsp://`` is a stream, not a file."""
+    return str(value).startswith(("http://", "https://"))
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Downloading
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def download(url: str, out: Path) -> bool:
+    """Fetch one file, reporting progress. Returns False on any HTTP failure."""
+    if out.exists():
+        print(f"  have  {out}  ({out.stat().st_size / 1e6:.1f} MB)")
+        return True
+    out.parent.mkdir(parents=True, exist_ok=True)
+    part = out.with_suffix(out.suffix + ".part")
+    # A carriage-return progress line is only readable on a terminal. Piped to a
+    # file or a CI log it just repeats the whole line hundreds of times.
+    live = sys.stdout.isatty()
+    try:
+        with urllib.request.urlopen(url, timeout=60) as response:  # noqa: S310
+            total = int(response.headers.get("Content-Length") or 0)
+            done = 0
+            with part.open("wb") as handle:
+                while chunk := response.read(1 << 16):
+                    handle.write(chunk)
+                    done += len(chunk)
+                    if live and total:
+                        print(
+                            f"\r  ...   {out.name}  {done / 1e6:5.1f} / {total / 1e6:.1f} MB",
+                            end="", flush=True,
+                        )
+        # A server that closes early, or a proxy that truncates, ends the read
+        # loop exactly like a finished transfer does. Without this the partial
+        # file is renamed into place and every later run reuses it, because the
+        # first thing this function does is trust a file that already exists.
+        if total and done != total:
+            part.unlink(missing_ok=True)
+            print(
+                f"\r  FAIL  {out.name}: got {done} of {total} bytes, "
+                f"the transfer was cut short",
+                file=sys.stderr,
+            )
+            return False
+        print(f"{chr(13) if live else ''}  got   {out}  ({done / 1e6:.1f} MB)          ")
+        part.replace(out)
+        return True
+    except (urllib.error.URLError, OSError, TimeoutError) as exc:
+        part.unlink(missing_ok=True)
+        print(f"\r  FAIL  {out.name}: {exc}", file=sys.stderr)
+        return False
+
+
+def cache_name(url: str) -> str:
+    """A local filename for a URL that cannot collide with another URL's.
+
+    ``--source https://a.example/clip.h264`` and the same name on another host
+    are different videos. Keying the cache on the last path segment alone meant
+    the second one silently ran the first one's footage, and the download was
+    skipped because the file was already there.
+
+    The digest goes before the extension rather than after, so the suffix still
+    says what the file is and `.tar.gz` survives intact::
+
+        clip.h264            ->  clip-1a2b3c4d.h264
+        yolo26m-det.tar.gz   ->  yolo26m-det-1a2b3c4d.tar.gz
+    """
+    digest = hashlib.sha256(url.encode("utf-8")).hexdigest()[:8]
+    name = Path(url.split("?")[0]).name or "download"
+    head, dot, tail = name.partition(".")
+    return f"{head}-{digest}{dot}{tail}"
+
+
+def fetch(url: str, out: Path, what: str) -> Path:
+    """Download to ``out``, or raise. The insisting version of :func:`download`."""
+    if not download(url, out):
+        raise RuntimeError(
+            f"could not download the {what} from {url}\n"
+            f"  wanted: {out}\n"
+            "Fetch it by hand and pass the local path instead."
+        )
+    return out
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Resolution
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def ensure_source(uri: str, source_type: str = "video") -> str:
+    """Make ``source.uri`` name a file that exists, downloading if it has to.
+
+    Args:
+        uri: The resolved ``source.uri``: a path, an ``http(s)`` URL, or one of
+            the sample clip paths the defaults fill in.
+        source_type: Only ``video`` reads a file. An RTSP URL or a camera is
+            handed back untouched.
+
+    Returns:
+        A local path, or ``uri`` unchanged when there is nothing to fetch. A
+        path that is simply missing is *also* handed back unchanged, so the
+        error comes from :func:`sima_vision.media.check_source_file`, which
+        knows how to describe it.
+    """
+    if source_type != "video" or not uri:
+        return uri
+    if is_url(uri):
+        return str(fetch(uri, videos_dir() / cache_name(uri), "source video"))
+    path = Path(uri)
+    if path.exists():
+        return uri
+    # A default, or a path the user wrote that happens to name a sample clip.
+    if path.name in SAMPLE_VIDEOS:
+        print(f"source: {uri} is missing, fetching the sample clip", flush=True)
+        fetch(f"{SAMPLE_RELEASE}/{path.name}", path, "sample clip")
+    return uri
+
+
+def ensure_model(path: str, task: str) -> str:
+    """Make ``model.path`` name an archive that exists, downloading if it has to.
+
+    A URL is fetched directly. Anything already on disk is used as it stands.
+    The remaining case is the default -- the task's own archive, not yet
+    downloaded -- and that one goes through ``sima-cli``, because a plain GET on
+    the pack URL answers with a login redirect rather than a tarball.
+
+    Raises:
+        RuntimeError: When the archive is missing and cannot be fetched, with
+            the command to run by hand.
+    """
+    if is_url(path):
+        return str(fetch(path, models_dir() / cache_name(path), "model archive"))
+    if not path or Path(path).exists():
+        return path
+
+    entry = CATALOGUE.get(task)
+    target = Path(path)
+    if entry is None or target.name != entry.model_file:
+        # Not something this task knows how to fetch: a name we have no URL for.
+        raise RuntimeError(
+            f"model archive not found: {path}\n"
+            f"  launched from: {Path.cwd()}\n"
+            "Pass --model with a path or an https URL, or leave it off to use "
+            f"the default for {task}."
+        )
+
+    url = model_url(task)
+    if shutil.which("sima-cli") is None:
+        raise RuntimeError(
+            f"model archive not found: {path}\n"
+            "The model packs need a community.sima.ai login, and `sima-cli` is "
+            "not on PATH here,\nso it cannot be fetched for you. Run:\n\n"
+            f"  sima-cli login\n  {model_command(task)}\n\n"
+            "Or pass --model with an https URL you can reach."
+        )
+
+    target.parent.mkdir(parents=True, exist_ok=True)
+    # flush: the child writes straight to the terminal, so an unflushed line
+    # here turns up *after* its output and reads as if it came from sima-cli.
+    print(f"model: {path} is missing, fetching it with sima-cli", flush=True)
+    print(f"  {url}", flush=True)
+    result = subprocess.run(  # noqa: S603
+        ["sima-cli", "download", url],
+        cwd=target.parent,
+        check=False,
+        # Left alone, sima-cli opens with "a newer version is available, update
+        # now? [Y/n]" and waits. Nothing is watching that prompt in the middle
+        # of a run, and answering no aborts the download with it. Its own
+        # message names this variable as the way off.
+        env={**os.environ, "SIMA_CLI_CHECK_FOR_UPDATE": "0"},
+    )
+    if result.returncode != 0 or not target.exists():
+        raise RuntimeError(
+            f"`sima-cli download` did not produce {target}\n"
+            "It needs a community.sima.ai login. Run `sima-cli login` and try "
+            "again, or download\nthe pack by hand and pass --model with its path."
+        )
+    return path
+
+
+def ensure_assets(cfg, task: str):
+    """Resolve ``model.path`` and ``source.uri`` to files that exist.
+
+    Called once, by :meth:`Task.run <sima_vision.tasks.base.Task.run>`, so that
+    everything which does not run inference -- ``--validate``, ``preview``, the
+    Python ``validate()`` -- stays offline.
+
+    Returns:
+        The config, or a copy of it with the two paths replaced.
+    """
+    source = ensure_source(cfg.source_uri, cfg.source_type)
+    model = ensure_model(cfg.model_path, task)
+    if (source, model) == (cfg.source_uri, cfg.model_path):
+        return cfg
+    return replace(cfg, source_uri=source, model_path=model)