simplevision 0.5.1__py3-none-any.whl

simplevision/__init__.py

@@ -0,0 +1,23 @@
+"""SimpleVision — student-friendly Python interface to SimpleVision pipelines.
+
+Typical use::
+
+    from simplevision import Pipeline
+
+    p = Pipeline.load("my_pipeline.simplevision")
+    p.run()
+
+    hit = p.outputs.MatchPercentage[0]
+    if hit > 0.85:
+        print("Match found")
+
+The pipeline definition (steps, params, output bindings) lives entirely
+in the ``.simplevision`` JSON. To change a step, open the editor — the
+``.py`` file never needs to be regenerated.
+"""
+
+from ._version import __version__
+from .outputs import Outputs, Point
+from .pipeline import Pipeline
+
+__all__ = ["Pipeline", "Outputs", "Point", "__version__"]

simplevision/_extractors.py

@@ -0,0 +1,321 @@
+"""Per-(fnId, outputId) extraction functions.
+
+Each entry takes the step's params, the runtime's ApplyResult, and the
+final image, and returns the value to set on the Outputs object. The TS
+node manifests declare which output ids exist; this table implements
+their Python-side computation.
+
+Adding a new output to a node = add one entry here + one entry on the
+TS manifest. Both sides must agree on the id.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+import cv2
+import numpy as np
+
+from .outputs import Point
+from .runtime.ops._registry import ApplyResult
+
+
+# Signature: (params, result, final_image) -> value
+Extractor = Callable[[dict[str, Any], ApplyResult, "np.ndarray"], Any]
+
+
+def _rows(result: ApplyResult) -> list[dict[str, Any]]:
+    return result.rows
+
+
+# --- thr -------------------------------------------------------------------
+
+
+def _thr_chosen_threshold(
+    params: dict[str, Any], result: ApplyResult, _img: "np.ndarray"
+) -> float:
+    # The runtime stashes the chosen value into a `Threshold` row.
+    for row in _rows(result):
+        if row.get("metric") == "Threshold":
+            v = row.get("value")
+            if isinstance(v, (int, float)):
+                return float(v)
+            # Adaptive mode reports "adaptive" — surface as NaN so students
+            # can `math.isnan(...)` check.
+            return float("nan")
+    # Fall back to the manual lower bound.
+    return float(params.get("lower", 0))
+
+
+# --- calibrate -------------------------------------------------------------
+
+
+def _calibrate_px_per_mm(
+    _params: dict[str, Any], result: ApplyResult, _img: "np.ndarray"
+) -> float:
+    for row in _rows(result):
+        if row.get("metric") == "px/mm":
+            return float(row["value"])
+    return float("nan")
+
+
+# --- hist ------------------------------------------------------------------
+
+
+def _hist_bins(
+    _params: dict[str, Any], _result: ApplyResult, img: "np.ndarray"
+) -> list[int]:
+    # The runtime's hist op only stores mean/stdev in rows. Compute the
+    # full 256-bin histogram here from the final (possibly equalised) image.
+    gray = img if img.ndim == 2 else cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
+    hist = cv2.calcHist([gray], [0], None, [256], [0, 256]).flatten()
+    return [int(x) for x in hist]
+
+
+# --- blob ------------------------------------------------------------------
+
+
+def _blob_count(_p: dict[str, Any], result: ApplyResult, _img: "np.ndarray") -> int:
+    return sum(1 for r in _rows(result) if r.get("ok", True))
+
+
+def _blob_centers(
+    _p: dict[str, Any], result: ApplyResult, _img: "np.ndarray"
+) -> list[Point]:
+    return [Point(x=float(r["cx"]), y=float(r["cy"])) for r in _rows(result)]
+
+
+def _blob_areas(
+    _p: dict[str, Any], result: ApplyResult, _img: "np.ndarray"
+) -> list[float]:
+    return [float(r["area"]) for r in _rows(result)]
+
+
+# --- particle --------------------------------------------------------------
+
+
+def _particle_count(_p: dict[str, Any], result: ApplyResult, _img: "np.ndarray") -> int:
+    return len(_rows(result))
+
+
+def _particle_areas(
+    _p: dict[str, Any], result: ApplyResult, _img: "np.ndarray"
+) -> list[float]:
+    return [float(r["area"]) for r in _rows(result)]
+
+
+def _particle_perimeters(
+    _p: dict[str, Any], result: ApplyResult, _img: "np.ndarray"
+) -> list[float]:
+    return [float(r["perim"]) for r in _rows(result)]
+
+
+def _particle_circularities(
+    _p: dict[str, Any], result: ApplyResult, _img: "np.ndarray"
+) -> list[float]:
+    return [float(r["circ"]) for r in _rows(result)]
+
+
+def _particle_centroids(
+    _p: dict[str, Any], result: ApplyResult, _img: "np.ndarray"
+) -> list[Point]:
+    return [Point(x=float(r["cx"]), y=float(r["cy"])) for r in _rows(result)]
+
+
+# --- shapematch ------------------------------------------------------------
+
+
+def _shapematch_count(
+    _p: dict[str, Any], result: ApplyResult, _img: "np.ndarray"
+) -> int:
+    return len(_rows(result))
+
+
+def _shapematch_scores(
+    _p: dict[str, Any], result: ApplyResult, _img: "np.ndarray"
+) -> list[float]:
+    # Sort best-first to match the editor's UI hint.
+    rows = sorted(_rows(result), key=lambda r: -float(r.get("score", 0)))
+    return [float(r.get("score", 0.0)) for r in rows]
+
+
+def _shapematch_positions(
+    _p: dict[str, Any], result: ApplyResult, _img: "np.ndarray"
+) -> list[Point]:
+    rows = sorted(_rows(result), key=lambda r: -float(r.get("score", 0)))
+    return [Point(x=float(r["cx"]), y=float(r["cy"])) for r in rows]
+
+
+# --- ocr -------------------------------------------------------------------
+
+
+def _ocr_text(_p: dict[str, Any], result: ApplyResult, _img: "np.ndarray") -> str:
+    # The OCR op stashes the concatenated string on a synthetic first row
+    # labelled "TEXT". Falls back to joining individual word rows if that
+    # row is missing (e.g. nothing recognised).
+    for row in _rows(result):
+        if row.get("label") == "TEXT":
+            return str(row.get("text", ""))
+    return " ".join(
+        str(r.get("text", "")) for r in _rows(result) if r.get("text")
+    )
+
+
+def _ocr_word_count(_p: dict[str, Any], result: ApplyResult, _img: "np.ndarray") -> int:
+    return sum(1 for r in _rows(result) if r.get("label", "").startswith("W"))
+
+
+def _ocr_positions(
+    _p: dict[str, Any], result: ApplyResult, _img: "np.ndarray"
+) -> list[Point]:
+    return [
+        Point(x=float(r["cx"]), y=float(r["cy"]))
+        for r in _rows(result)
+        if r.get("label", "").startswith("W")
+    ]
+
+
+def _ocr_scores(
+    _p: dict[str, Any], result: ApplyResult, _img: "np.ndarray"
+) -> list[float]:
+    return [
+        float(r.get("score", 0.0))
+        for r in _rows(result)
+        if r.get("label", "").startswith("W")
+    ]
+
+
+# --- geomatch --------------------------------------------------------------
+
+
+def _geomatch_count(_p: dict[str, Any], result: ApplyResult, _img: "np.ndarray") -> int:
+    return len(_rows(result))
+
+
+def _geomatch_positions(
+    _p: dict[str, Any], result: ApplyResult, _img: "np.ndarray"
+) -> list[Point]:
+    return [Point(x=float(r["cx"]), y=float(r["cy"])) for r in _rows(result)]
+
+
+def _geomatch_scores(
+    _p: dict[str, Any], result: ApplyResult, _img: "np.ndarray"
+) -> list[float]:
+    return [float(r.get("score", 0.0)) for r in _rows(result)]
+
+
+def _geomatch_angles(
+    _p: dict[str, Any], result: ApplyResult, _img: "np.ndarray"
+) -> list[float]:
+    return [float(r.get("angle", 0.0)) for r in _rows(result)]
+
+
+# --- barcode ---------------------------------------------------------------
+
+
+def _barcode_count(_p: dict[str, Any], result: ApplyResult, _img: "np.ndarray") -> int:
+    return sum(1 for r in _rows(result) if r.get("decoded"))
+
+
+def _barcode_text(_p: dict[str, Any], result: ApplyResult, _img: "np.ndarray") -> str:
+    return "\n".join(
+        str(r.get("text", "")) for r in _rows(result) if r.get("decoded")
+    )
+
+
+def _barcode_positions(
+    _p: dict[str, Any], result: ApplyResult, _img: "np.ndarray"
+) -> list[Point]:
+    return [
+        Point(x=float(r["cx"]), y=float(r["cy"]))
+        for r in _rows(result)
+        if r.get("decoded")
+    ]
+
+
+# --- pfilter ---------------------------------------------------------------
+
+
+def _pfilter_kept(_p: dict[str, Any], result: ApplyResult, _img: "np.ndarray") -> int:
+    return sum(1 for r in _rows(result) if r.get("kept"))
+
+
+def _pfilter_dropped(_p: dict[str, Any], result: ApplyResult, _img: "np.ndarray") -> int:
+    return sum(1 for r in _rows(result) if not r.get("kept", True))
+
+
+def _pfilter_areas(
+    _p: dict[str, Any], result: ApplyResult, _img: "np.ndarray"
+) -> list[float]:
+    return [float(r["area"]) for r in _rows(result) if r.get("kept")]
+
+
+def _pfilter_centroids(
+    _p: dict[str, Any], result: ApplyResult, _img: "np.ndarray"
+) -> list[Point]:
+    return [
+        Point(x=float(r["cx"]), y=float(r["cy"]))
+        for r in _rows(result)
+        if r.get("kept")
+    ]
+
+
+# --- qrcode ----------------------------------------------------------------
+
+
+def _qrcode_count(_p: dict[str, Any], result: ApplyResult, _img: "np.ndarray") -> int:
+    return sum(1 for r in _rows(result) if r.get("decoded"))
+
+
+def _qrcode_text(_p: dict[str, Any], result: ApplyResult, _img: "np.ndarray") -> str:
+    return "\n".join(
+        str(r.get("text", "")) for r in _rows(result) if r.get("decoded")
+    )
+
+
+def _qrcode_positions(
+    _p: dict[str, Any], result: ApplyResult, _img: "np.ndarray"
+) -> list[Point]:
+    return [
+        Point(x=float(r["cx"]), y=float(r["cy"]))
+        for r in _rows(result)
+        if r.get("decoded")
+    ]
+
+
+# --- dispatch table --------------------------------------------------------
+
+EXTRACTORS: dict[tuple[str, str], Extractor] = {
+    ("thr", "chosen_threshold"): _thr_chosen_threshold,
+    ("calibrate", "px_per_mm"): _calibrate_px_per_mm,
+    ("hist", "bins"): _hist_bins,
+    ("blob", "count"): _blob_count,
+    ("blob", "centers"): _blob_centers,
+    ("blob", "areas"): _blob_areas,
+    ("particle", "count"): _particle_count,
+    ("particle", "areas"): _particle_areas,
+    ("particle", "perimeters"): _particle_perimeters,
+    ("particle", "circularities"): _particle_circularities,
+    ("particle", "centroids"): _particle_centroids,
+    ("shapematch", "count"): _shapematch_count,
+    ("shapematch", "scores"): _shapematch_scores,
+    ("shapematch", "positions"): _shapematch_positions,
+    ("ocr", "text"): _ocr_text,
+    ("ocr", "wordCount"): _ocr_word_count,
+    ("ocr", "positions"): _ocr_positions,
+    ("ocr", "scores"): _ocr_scores,
+    ("qrcode", "count"): _qrcode_count,
+    ("qrcode", "text"): _qrcode_text,
+    ("qrcode", "positions"): _qrcode_positions,
+    ("pfilter", "kept"): _pfilter_kept,
+    ("pfilter", "dropped"): _pfilter_dropped,
+    ("pfilter", "areas"): _pfilter_areas,
+    ("pfilter", "centroids"): _pfilter_centroids,
+    ("barcode", "count"): _barcode_count,
+    ("barcode", "text"): _barcode_text,
+    ("barcode", "positions"): _barcode_positions,
+    ("geomatch", "count"): _geomatch_count,
+    ("geomatch", "positions"): _geomatch_positions,
+    ("geomatch", "scores"): _geomatch_scores,
+    ("geomatch", "angles"): _geomatch_angles,
+}

simplevision/_version.py

@@ -0,0 +1 @@
+__version__ = "0.5.1"

simplevision/outputs.py

@@ -0,0 +1,74 @@
+"""The ``Outputs`` container exposed as ``p.outputs`` after a pipeline run.
+
+Bindings declared in the editor's Output Control populate this object
+under student-chosen attribute names. The class itself stays simple:
+attribute access for reads, a friendly ``__repr__`` so ``print(outputs)``
+shows everything tidily.
+"""
+
+from __future__ import annotations
+
+from collections import namedtuple
+from typing import Any
+
+# Named-tuple so students can write `outputs.Centroids[0].x` instead of
+# unpacking. Confirmed during the design discussion: dot access is the
+# expected style.
+Point = namedtuple("Point", ["x", "y"])
+
+
+class Outputs:
+    """A simple attribute bag with a friendly repr.
+
+    Each entry corresponds to one ticked output in the editor's Output
+    Control panel. The variable name is whatever the student typed; the
+    value's shape depends on the output type (scalar, list of numbers,
+    list of ``Point``s — see the editor's type hint).
+    """
+
+    __slots__ = ("_values",)
+
+    def __init__(self) -> None:
+        # Bypass __setattr__ — direct dict assignment is the source of truth.
+        object.__setattr__(self, "_values", {})
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        if name.startswith("_"):
+            object.__setattr__(self, name, value)
+        else:
+            self._values[name] = value
+
+    def __getattr__(self, name: str) -> Any:
+        # __getattr__ only fires when normal lookup fails, so the dunder
+        # names are already handled by object.__getattribute__.
+        try:
+            return self._values[name]
+        except KeyError as exc:
+            raise AttributeError(
+                f"outputs.{name} is not set. Open Output Control in the editor "
+                f"and tick this measurement to expose it as a variable."
+            ) from exc
+
+    def __contains__(self, name: str) -> bool:
+        return name in self._values
+
+    def __iter__(self):
+        return iter(self._values.items())
+
+    def __repr__(self) -> str:
+        if not self._values:
+            return "Outputs(empty — no measurements exposed)"
+        lines = ["Outputs:"]
+        for k, v in self._values.items():
+            lines.append(f"  {k} = {_short_repr(v)}")
+        return "\n".join(lines)
+
+
+def _short_repr(value: Any) -> str:
+    """Compact repr for the Outputs.__repr__ — long lists get truncated."""
+    if isinstance(value, list):
+        if len(value) > 5:
+            head = ", ".join(repr(x) for x in value[:3])
+            return f"[{head}, ... +{len(value) - 3} more]"
+        return repr(value)
+    return repr(value)

simplevision/pipeline.py

@@ -0,0 +1,229 @@
+"""``Pipeline.load(...).run()`` — the student-facing API.
+
+Loads a ``.simplevision`` JSON, executes its steps using the same ops
+the editor uses (via ``simplevision.runtime``), and populates an
+Outputs object based on the bindings declared in the editor's Output
+Control.
+
+Source of the first frame:
+
+- The ``load`` step's params decide where the source comes from (file or
+  webcam). The ``path`` param is resolved relative to the ``.simplevision``
+  file's directory, so distributing a pipeline + a sample frame as a
+  single folder Just Works.
+- Pass ``p.run(frame_or_path)`` to override the load step with your own
+  image (handy for batch-processing many frames through the same
+  pipeline).
+"""
+
+from __future__ import annotations
+
+import tempfile
+from pathlib import Path
+from typing import Any
+
+import cv2
+import numpy as np
+
+from ._extractors import EXTRACTORS
+from .outputs import Outputs
+from .runtime import (
+    OutputBinding,
+    Pipeline as _PipelineSpec,
+    Step,
+    load_pipeline as _load_pipeline,
+)
+from .runtime.context import Context
+from .runtime.ops import REGISTRY
+
+
+class Pipeline:
+    """Runs a SimpleVision pipeline against an image and exposes named
+    measurements via :attr:`outputs`.
+
+    Typical use::
+
+        p = Pipeline.load("my_pipeline.simplevision")
+        p.run()
+        print(p.outputs)
+    """
+
+    def __init__(self, spec: _PipelineSpec, base_dir: Path):
+        self._spec = spec
+        self._base_dir = base_dir
+        self.outputs: Outputs = Outputs()
+        self.image: np.ndarray | None = None
+
+    @classmethod
+    def load(cls, path: str | Path) -> "Pipeline":
+        """Load a pipeline from a ``.simplevision`` JSON file."""
+        p = Path(path).resolve()
+        spec = _load_pipeline(p)
+        return cls(spec=spec, base_dir=p.parent)
+
+    def run(self, source: "str | Path | np.ndarray | None" = None) -> "Pipeline":
+        """Execute the pipeline and populate :attr:`outputs`.
+
+        Args:
+            source: Optional override for the first frame. If a path, the
+                image is read from disk. If a numpy array, it's used
+                directly (and the pipeline's load step is skipped). If
+                ``None`` (the default), the load step's params decide.
+
+        Returns ``self`` so calls can be chained:
+        ``Pipeline.load(...).run().outputs``.
+        """
+        self.outputs = Outputs()  # fresh on every run
+
+        ctx = self._build_context()
+        img = self._initial_image(source, ctx)
+
+        for step in self._spec.steps:
+            if not step.enabled:
+                continue
+            # The load step is handled above; skip when source was provided
+            # or when we've already resolved its image from params.
+            if step.fnId == "load":
+                self._bind_outputs(step, _LoadResult(image=img), img)
+                continue
+            img = self._execute_step(step, img, ctx)
+
+        self.image = img
+        return self
+
+    # --- internals ---------------------------------------------------------
+
+    def _build_context(self) -> Context:
+        # The runtime's Context expects a frame_path + out_dir. The lab
+        # doesn't write per-step PNGs (we only care about measurements),
+        # but a few ops (load, calibrate) read from frame_path or
+        # write into ctx.state, so we have to provide one. The frame_path
+        # is set later once we know the load source.
+        return Context(frame_path=Path("."), out_dir=Path(tempfile.gettempdir()))
+
+    def _initial_image(
+        self,
+        source: "str | Path | np.ndarray | None",
+        ctx: Context,
+    ) -> np.ndarray:
+        if isinstance(source, np.ndarray):
+            return source
+
+        if source is not None:
+            path = Path(source)
+            if not path.is_absolute():
+                path = (self._base_dir / path).resolve()
+            ctx.frame_path = path
+            return _read_image(path)
+
+        # Fall back to the load step's params.
+        load_step = next((s for s in self._spec.steps if s.fnId == "load"), None)
+        if load_step is None:
+            raise RuntimeError(
+                "Pipeline has no Load step and no source was passed to run()"
+            )
+        kind = load_step.params.get("kind", "file")
+        if kind == "file":
+            raw = load_step.params.get("path", "")
+            if not raw:
+                raise RuntimeError(
+                    "Load step has no file path. Pass one to run(\"frame.png\") "
+                    "or set it in the editor."
+                )
+            path = Path(raw)
+            if not path.is_absolute():
+                path = (self._base_dir / path).resolve()
+            ctx.frame_path = path
+            return _read_image(path)
+        if kind == "webcam":
+            return _capture_webcam(load_step.params)
+        raise RuntimeError(f"Unknown Load kind: {kind!r}")
+
+    def _execute_step(
+        self, step: Step, img: np.ndarray, ctx: Context
+    ) -> np.ndarray:
+        op = REGISTRY.get(step.fnId)
+        if op is None:
+            raise RuntimeError(f"Unknown step fnId: {step.fnId!r}")
+        result = op(img, step.params, ctx)
+        self._bind_outputs(step, result, result.image)
+        return result.image
+
+    def _bind_outputs(
+        self,
+        step: Step,
+        result: Any,
+        final_image: np.ndarray,
+    ) -> None:
+        if not step.outputs:
+            return
+        for binding in step.outputs:
+            extractor = EXTRACTORS.get((step.fnId, binding.outputId))
+            if extractor is None:
+                # Unknown binding — usually a stale .simplevision pointing
+                # at an output we no longer support. Skip rather than
+                # crash so the rest of the pipeline still runs.
+                continue
+            value = extractor(step.params, result, final_image)
+            setattr(self.outputs, binding.variableName, value)
+
+
+def _read_image(path: Path) -> np.ndarray:
+    img = cv2.imread(str(path), cv2.IMREAD_UNCHANGED)
+    if img is None:
+        raise FileNotFoundError(f"Cannot read image: {path}")
+    return img
+
+
+def _capture_webcam(params: dict[str, Any]) -> np.ndarray:
+    """Minimal webcam capture mirroring the editor's Load form. Honours
+    the same auto/manual settings the user picked. Lives here rather than
+    in the runtime so the runtime stays headless-only."""
+    import sys
+
+    device = int(params.get("device", 0))
+    settings = params.get("settings", {}) or {}
+    cap = cv2.VideoCapture(device)
+    if not cap.isOpened():
+        raise RuntimeError(f"Cannot open webcam device {device}")
+    try:
+        ae = settings.get("autoExposure")
+        if ae is not None:
+            if sys.platform == "win32":
+                cap.set(cv2.CAP_PROP_AUTO_EXPOSURE, 0.75 if ae else 0.25)
+            else:
+                cap.set(cv2.CAP_PROP_AUTO_EXPOSURE, 3 if ae else 1)
+        af = settings.get("autoFocus")
+        if af is not None:
+            cap.set(cv2.CAP_PROP_AUTOFOCUS, 1 if af else 0)
+        for prop_name, cv_prop in [
+            ("exposure", cv2.CAP_PROP_EXPOSURE),
+            ("focus", cv2.CAP_PROP_FOCUS),
+            ("brightness", cv2.CAP_PROP_BRIGHTNESS),
+            ("gain", cv2.CAP_PROP_GAIN),
+        ]:
+            v = settings.get(prop_name)
+            if v is not None:
+                cap.set(cv_prop, float(v))
+        # Warm-up so the sensor applies the settings before we grab.
+        for _ in range(4):
+            cap.read()
+        ok, frame = cap.read()
+    finally:
+        cap.release()
+    if not ok or frame is None:
+        raise RuntimeError(f"Failed to read frame from webcam {device}")
+    return frame
+
+
+class _LoadResult:
+    """Stand-in ApplyResult for the load step — we don't run the op (we
+    read the image ourselves), but the extractor table still expects
+    something with the `rows` shape. Load has no exposed outputs today,
+    so this stays empty; here only to keep the binding path uniform."""
+
+    __slots__ = ("image", "rows")
+
+    def __init__(self, image: np.ndarray):
+        self.image = image
+        self.rows = []