camera-ui-ml 1.0.0__tar.gz

camera_ui_ml-1.0.0/LICENSE.md

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2020-2024 seydx <hi@seydx.dev>
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

camera_ui_ml-1.0.0/PKG-INFO

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: camera-ui-ml
+Version: 1.0.0
+Summary: Shared ML inference framework for camera.ui detection plugins (onnx, openvino, coreml, ncnn)
+Author-email: seydx <hi@seydx.dev>
+Maintainer-email: seydx <hi@seydx.dev>
+Project-URL: Homepage, https://github.com/cameraui/ml
+Project-URL: Documentation, https://github.com/cameraui/ml
+Project-URL: Repository, https://github.com/cameraui/ml
+Project-URL: Bug Tracker, https://github.com/cameraui/ml/issues
+Project-URL: Changelog, https://github.com/cameraui/ml/blob/main/CHANGELOG.md
+Keywords: camera.ui,python,ml,inference,detection
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: typing_extensions>=4.15.0
+Requires-Dist: camera-ui-sdk>=1.0.95
+Requires-Dist: numpy>=2.0
+Requires-Dist: pillow>=12.0
+Requires-Dist: aiohttp>=3.12
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Provides-Extra: clip
+Requires-Dist: transformers>=4.40; extra == "clip"
+Dynamic: license-file
+
+# camera-ui-ml
+
+[![PyPI](https://img.shields.io/pypi/v/camera-ui-ml?label=pypi&logo=pypi&logoColor=white)](https://pypi.org/project/camera-ui-ml/)
+
+Shared ML inference framework for camera.ui's detection plugins.
+
+---
+
+_Part of the camera.ui ecosystem - A comprehensive camera management solution._

camera_ui_ml-1.0.0/README.md

@@ -0,0 +1,9 @@
+# camera-ui-ml
+
+[![PyPI](https://img.shields.io/pypi/v/camera-ui-ml?label=pypi&logo=pypi&logoColor=white)](https://pypi.org/project/camera-ui-ml/)
+
+Shared ML inference framework for camera.ui's detection plugins.
+
+---
+
+_Part of the camera.ui ecosystem - A comprehensive camera management solution._

camera_ui_ml-1.0.0/camera_ui_ml/__init__.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+from .backend import (
+    DType,
+    InferenceBackend,
+    InputSpec,
+    Layout,
+    NDArray,
+    Normalize,
+    Outputs,
+)
+from .detectors import (
+    BaseDetector,
+    BoxDetector,
+    Embedder,
+    NormalizedDetection,
+    OcrResult,
+    ParseKind,
+    PlateOcr,
+)
+from .geometry import (
+    Box,
+    NormalizedBox,
+    clamp_box,
+    cxcywh_to_xyxy,
+    normalize_box,
+    pad_box,
+    scale_box,
+)
+from .model_manager import BaseModelManager
+from .parsing import (
+    RawDetection,
+    channels_first,
+    decode_ocr,
+    l2_normalize,
+    nms,
+    parse_end2end,
+    parse_yolov9,
+)
+from .pipeline import prepare_executor, run_prepare
+from .preprocess import crop_rgb, decode_image, frame_to_rgb, resize_rgb, to_pil, to_tensor
+
+__all__ = [
+    # backend seam
+    "InferenceBackend",
+    "InputSpec",
+    "Outputs",
+    "NDArray",
+    "Layout",
+    "Normalize",
+    "DType",
+    # model manager
+    "BaseModelManager",
+    # detectors (ClipEncoder is opt-in via camera_ui_ml.detectors.clip)
+    "BaseDetector",
+    "BoxDetector",
+    "NormalizedDetection",
+    "ParseKind",
+    "Embedder",
+    "PlateOcr",
+    "OcrResult",
+    # geometry
+    "Box",
+    "NormalizedBox",
+    "cxcywh_to_xyxy",
+    "scale_box",
+    "clamp_box",
+    "normalize_box",
+    "pad_box",
+    # parsing
+    "RawDetection",
+    "channels_first",
+    "parse_yolov9",
+    "parse_end2end",
+    "decode_ocr",
+    "l2_normalize",
+    "nms",
+    # preprocess
+    "frame_to_rgb",
+    "resize_rgb",
+    "to_pil",
+    "to_tensor",
+    "crop_rgb",
+    "decode_image",
+    # pipeline
+    "run_prepare",
+    "prepare_executor",
+]

camera_ui_ml-1.0.0/camera_ui_ml/backend.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from typing import Any, Literal
+
+import numpy as np
+
+from .pipeline import run_prepare
+
+NDArray = np.ndarray[Any, Any]
+
+Layout = Literal["nchw", "nhwc"]
+Normalize = Literal["unit", "facenet", "none"]
+DType = Literal["float32", "uint8"]
+
+# Inference outputs in model output order; detectors index `outputs[0]` for the
+# primary output (OCR scans all outputs, CLIP uses the single embedding output).
+Outputs = Sequence[NDArray]
+
+
+@dataclass(frozen=True)
+class InputSpec:
+    width: int
+    height: int
+    layout: Layout = "nchw"
+    normalize: Normalize = "unit"  # "unit" = /255, "facenet" = (x-127.5)/128, "none" = raw
+    dtype: DType = "float32"
+
+
+class InferenceBackend(ABC):
+    @property
+    @abstractmethod
+    def input_size(self) -> tuple[int, int]: ...
+
+    @abstractmethod
+    def metadata(self) -> Mapping[str, str]: ...
+
+    @abstractmethod
+    async def infer(self, inputs: Sequence[Any]) -> Outputs: ...
+
+    @abstractmethod
+    def close(self) -> None: ...
+
+    def adapt(self, image: NDArray, spec: InputSpec) -> Sequence[Any]:
+        """Realize the canonical HWC uint8 RGB image into runtime model inputs.
+
+        Default: one normalized tensor per ``spec`` (onnx/openvino/ncnn). CoreML
+        image-input models override this to pass a PIL image instead. Runs on the
+        shared prepare-executor (CPU)."""
+        from .preprocess import to_tensor
+
+        return [to_tensor(image, spec)]
+
+    async def run(self, image: NDArray, spec: InputSpec) -> Outputs:
+        prepared = await run_prepare(lambda: list(self.adapt(image, spec)))
+        return await self.infer(prepared)

camera_ui_ml-1.0.0/camera_ui_ml/detectors/__init__.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from .base import BaseDetector
+from .box import BoxDetector, NormalizedDetection, ParseKind
+from .embedder import Embedder
+from .ocr import DEFAULT_ALPHABET, OcrResult, PlateOcr
+
+__all__ = [
+    "BaseDetector",
+    "BoxDetector",
+    "NormalizedDetection",
+    "ParseKind",
+    "Embedder",
+    "PlateOcr",
+    "OcrResult",
+    "DEFAULT_ALPHABET",
+]

camera_ui_ml-1.0.0/camera_ui_ml/detectors/base.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import asyncio
+
+from camera_ui_sdk import LoggerService
+
+from ..backend import InferenceBackend
+from ..model_manager import BaseModelManager
+
+
+class BaseDetector:
+    name: str = "detector"
+
+    def __init__(self, manager: BaseModelManager, logger: LoggerService) -> None:
+        self.manager = manager
+        self.logger = logger
+        self.backend: InferenceBackend | None = None
+        self.initialized = False
+        self.closed = False
+        self._init_task: asyncio.Task[None] | None = None
+
+    async def initialize(self, model_name: str) -> None:
+        if self.initialized:
+            return
+        if self._init_task is None:
+            self._init_task = asyncio.create_task(self._do_initialize(model_name))
+        await self._init_task
+
+    async def close(self) -> None:
+        self.closed = True
+        if self._init_task is not None:
+            self._init_task.cancel()
+            self._init_task = None
+        self.initialized = False
+        if self.backend is not None:
+            self.backend.close()
+            self.backend = None
+
+    async def _do_initialize(self, model_name: str) -> None:
+        try:
+            self.backend = await self.manager.ensure_backend(model_name)
+            if self.closed:
+                return
+            await self._configure(model_name)
+            self.initialized = True
+            self.logger.success(f"Loaded {self.name}: {model_name}")
+        except Exception as error:
+            self.logger.error(f"Failed to initialize {self.name}: {error}")
+        finally:
+            self._init_task = None
+
+    async def _configure(self, model_name: str) -> None:
+        """Read model-derived config (input size, labels) from ``self.backend``.
+        Overridden by subclasses that need it; the default is a no-op."""
+
+    def _ready(self) -> bool:
+        return self.initialized and self.backend is not None

camera_ui_ml-1.0.0/camera_ui_ml/detectors/box.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+import ast
+import re
+from collections.abc import Mapping
+from typing import Any, Literal
+
+import numpy as np
+from camera_ui_sdk import ImageMetadata, LoggerService, VideoFrameData
+
+from ..backend import InputSpec, NDArray, Normalize
+from ..geometry import NormalizedBox, normalize_box, scale_box
+from ..model_manager import BaseModelManager
+from ..parsing import RawDetection, channels_first, nms, parse_end2end, parse_yolov9
+from ..preprocess import decode_image, frame_to_rgb
+from .base import BaseDetector
+
+ParseKind = Literal["yolov9", "end2end"]
+NormalizedDetection = tuple[int, float, NormalizedBox]
+
+
+class BoxDetector(BaseDetector):
+    def __init__(
+        self,
+        manager: BaseModelManager,
+        logger: LoggerService,
+        *,
+        name: str = "detector",
+        parse: ParseKind = "yolov9",
+        size: tuple[int, int] = (320, 320),
+        normalize: Normalize = "unit",
+        multiclass: bool = False,
+        apply_nms: bool = False,
+        threshold: float = 0.5,
+    ) -> None:
+        super().__init__(manager, logger)
+        self.name = name
+        self.threshold = threshold
+        self.input_size = size
+        self.labels: dict[int, str] = {}
+
+        self._parse = parse
+        self._normalize = normalize
+        self._multiclass = multiclass
+        self._apply_nms = apply_nms
+
+    async def _configure(self, model_name: str) -> None:
+        assert self.backend is not None
+        self.input_size = self.backend.input_size
+        if self._multiclass:
+            self.labels = _parse_labels(self.backend.metadata())
+
+    @property
+    def _spec(self) -> InputSpec:
+        return InputSpec(
+            self.input_size[0],
+            self.input_size[1],
+            layout="nchw",
+            normalize=self._normalize,
+        )
+
+    async def detect(self, image: NDArray, threshold: float | None = None) -> list[RawDetection]:
+        """Detect on an HWC uint8 RGB array; boxes are in model-input pixel coords."""
+        if not self._ready():
+            return []
+        assert self.backend is not None
+
+        outputs = await self.backend.run(image, self._spec)
+        primary = np.asarray(outputs[0])
+        limit = self.threshold if threshold is None else threshold
+
+        if self._parse == "yolov9":
+            detections = parse_yolov9(channels_first(primary), limit)
+        else:
+            detections = parse_end2end(np.squeeze(primary), limit)
+
+        return nms(detections) if self._apply_nms else detections
+
+    async def detect_frame(self, frame: VideoFrameData, threshold: float | None = None) -> list[RawDetection]:
+        """Detect on a raw video frame; boxes are rescaled to frame pixel coords."""
+        if not self._ready():
+            return []
+
+        rgb = frame_to_rgb(frame["data"], frame["width"], frame["height"], frame["format"])
+        raw = await self.detect(rgb, threshold)
+
+        scale_x = frame["width"] / self.input_size[0]
+        scale_y = frame["height"] / self.input_size[1]
+        return [(cid, conf, scale_box(box, scale_x, scale_y)) for cid, conf, box in raw]
+
+    async def detect_single(
+        self, image_data: bytes, metadata: ImageMetadata, threshold: float | None = None
+    ) -> list[NormalizedDetection]:
+        """Detect on an encoded image; boxes are normalized to 0..1."""
+        if not self._ready():
+            return []
+
+        raw = await self.detect(decode_image(image_data), threshold)
+        return [
+            (cid, conf, normalize_box(box, self.input_size[0], self.input_size[1])) for cid, conf, box in raw
+        ]
+
+
+def _parse_labels(metadata: Mapping[str, str]) -> dict[int, str]:
+    names = metadata.get("names") or metadata.get("yolo.names")
+    if names:
+        parsed: dict[Any, Any] = ast.literal_eval(names)
+        return {int(key): str(value) for key, value in parsed.items()}
+
+    classes = metadata.get("classes")
+    if not classes:
+        return {}
+
+    labels: dict[int, str] = {}
+    for row, line in enumerate(classes.split(",")):
+        pair = re.split(r"[:\s]+", line.strip(), maxsplit=1)
+        if len(pair) == 2 and pair[0].strip().isdigit():
+            labels[int(pair[0])] = pair[1].strip()
+        else:
+            labels[row] = line.strip()
+    return labels

camera_ui_ml-1.0.0/camera_ui_ml/detectors/clip.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+import numpy as np
+from camera_ui_sdk import LoggerService, VideoFrameData
+from transformers import CLIPProcessor
+
+from ..backend import InferenceBackend, NDArray
+from ..model_manager import BaseModelManager
+from ..parsing import l2_normalize
+from ..pipeline import run_prepare
+from ..preprocess import frame_to_rgb, to_pil
+
+
+class ClipEncoder:
+    def __init__(
+        self,
+        manager: BaseModelManager,
+        logger: LoggerService,
+        *,
+        pretrained: str = "openai/clip-vit-base-patch32",
+        embedding_model: str = "clip-vit-base-patch32",
+    ) -> None:
+        self.manager = manager
+        self.logger = logger
+        self.embedding_model = embedding_model
+
+        self.vision: InferenceBackend | None = None
+        self.text: InferenceBackend | None = None
+        self.processor: Any = None
+
+        self.initialized = False
+        self.closed = False
+        self._pretrained = pretrained
+        self._init_task: asyncio.Task[None] | None = None
+
+    async def initialize(self, vision_model: str, text_model: str) -> None:
+        if self.initialized:
+            return
+        if self._init_task is None:
+            self._init_task = asyncio.create_task(self._do_initialize(vision_model, text_model))
+        await self._init_task
+
+    async def close(self) -> None:
+        self.closed = True
+        if self._init_task is not None:
+            self._init_task.cancel()
+            self._init_task = None
+        self.initialized = False
+        if self.vision is not None:
+            self.vision.close()
+            self.vision = None
+        if self.text is not None:
+            self.text.close()
+            self.text = None
+        self.processor = None
+
+    async def embed_image(self, image: NDArray) -> list[float]:
+        """Embed an HWC uint8 RGB image."""
+        if not self._ready():
+            return []
+        assert self.vision is not None
+
+        pil = to_pil(image)
+        pixel_values = await run_prepare(lambda: self._vision_input(pil))
+        outputs = await self.vision.infer([pixel_values])
+        return [float(value) for value in l2_normalize(outputs[0])]
+
+    async def embed_text(self, text: str) -> list[float]:
+        if not self._ready():
+            return []
+        assert self.text is not None
+
+        input_ids, attention_mask = await run_prepare(lambda: self._text_input(text))
+        outputs = await self.text.infer([input_ids, attention_mask])
+        return [float(value) for value in l2_normalize(outputs[0])]
+
+    async def embed_frame(self, width: int, height: int, data: bytes) -> list[float]:
+        return await self.embed_image(frame_to_rgb(data, width, height))
+
+    async def embed_frames(self, frames: list[VideoFrameData]) -> list[list[float]]:
+        if not self._ready():
+            return [[] for _ in frames]
+        return [await self.embed_frame(frame["width"], frame["height"], frame["data"]) for frame in frames]
+
+    def _ready(self) -> bool:
+        return (
+            self.initialized
+            and self.vision is not None
+            and self.text is not None
+            and self.processor is not None
+        )
+
+    async def _do_initialize(self, vision_model: str, text_model: str) -> None:
+        try:
+            self.vision = await self.manager.ensure_backend(vision_model)
+            self.text = await self.manager.ensure_backend(text_model)
+            self.processor = await asyncio.to_thread(CLIPProcessor.from_pretrained, self._pretrained)
+            if self.closed:
+                return
+            self.initialized = True
+            self.logger.success(f"Loaded CLIP: {vision_model} + {text_model}")
+        except Exception as error:
+            self.logger.error(f"Failed to initialize CLIP encoder: {error}")
+        finally:
+            self._init_task = None
+
+    def _vision_input(self, pil: Any) -> NDArray:
+        inputs = self.processor(images=pil, return_tensors="np", padding="max_length", truncation=True)
+        return np.asarray(inputs["pixel_values"], dtype=np.float32)
+
+    def _text_input(self, text: str) -> tuple[NDArray, NDArray]:
+        inputs = self.processor(text=text, return_tensors="np", padding="max_length", truncation=True)
+        return (
+            np.asarray(inputs["input_ids"], dtype=np.int64),
+            np.asarray(inputs["attention_mask"], dtype=np.int64),
+        )

camera_ui_ml-1.0.0/camera_ui_ml/detectors/embedder.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from camera_ui_sdk import LoggerService
+
+from ..backend import InputSpec, NDArray
+from ..geometry import Box
+from ..model_manager import BaseModelManager
+from ..parsing import l2_normalize
+from ..preprocess import frame_to_rgb
+from .base import BaseDetector
+
+
+class Embedder(BaseDetector):
+    def __init__(
+        self,
+        manager: BaseModelManager,
+        logger: LoggerService,
+        *,
+        size: int = 160,
+        name: str = "face embedder",
+    ) -> None:
+        super().__init__(manager, logger)
+        self.name = name
+        self.input_size = (size, size)
+
+    @property
+    def _spec(self) -> InputSpec:
+        return InputSpec(self.input_size[0], self.input_size[1], layout="nchw", normalize="facenet")
+
+    async def embed(self, image: NDArray) -> list[float]:
+        """Embed an HWC uint8 RGB face crop."""
+        if not self._ready():
+            return []
+        assert self.backend is not None
+        outputs = await self.backend.run(image, self._spec)
+        return [float(value) for value in l2_normalize(outputs[0])]
+
+    async def embed_from_crop(self, frame_data: bytes, width: int, height: int, box: Box) -> list[float]:
+        if not self._ready():
+            return []
+
+        x1 = max(0, int(box[0]))
+        y1 = max(0, int(box[1]))
+        x2 = min(width, int(box[2]))
+        y2 = min(height, int(box[3]))
+        if x2 <= x1 or y2 <= y1:
+            return []
+
+        rgb = frame_to_rgb(frame_data, width, height)
+        return await self.embed(rgb[y1:y2, x1:x2])

camera_ui_ml-1.0.0/camera_ui_ml/detectors/ocr.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+from camera_ui_sdk import LoggerService
+
+from ..backend import InputSpec, NDArray, Outputs
+from ..geometry import Box
+from ..model_manager import BaseModelManager
+from ..parsing import decode_ocr
+from ..preprocess import frame_to_rgb
+from .base import BaseDetector
+
+#: Default plate alphabet: digits + uppercase letters + pad. Plugins pass the
+#: exact constant their model was trained with.
+DEFAULT_ALPHABET = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ_"
+
+
+@dataclass(frozen=True)
+class OcrResult:
+    text: str
+    confidence: float
+
+
+class PlateOcr(BaseDetector):
+    def __init__(
+        self,
+        manager: BaseModelManager,
+        logger: LoggerService,
+        *,
+        width: int = 128,
+        height: int = 64,
+        slots: int = 10,
+        alphabet: str = DEFAULT_ALPHABET,
+        pad_char: str = "_",
+        name: str = "OCR",
+    ) -> None:
+        super().__init__(manager, logger)
+        self.name = name
+        self.input_size = (width, height)
+        self._slots = slots
+        self._alphabet = alphabet
+        self._pad = pad_char
+
+    @property
+    def _spec(self) -> InputSpec:
+        return InputSpec(
+            self.input_size[0],
+            self.input_size[1],
+            layout="nhwc",
+            normalize="none",
+            dtype="uint8",
+        )
+
+    async def recognize(self, image: NDArray) -> OcrResult | None:
+        """Recognize an HWC uint8 RGB plate crop."""
+        if not self._ready():
+            return None
+        assert self.backend is not None
+        return self._decode(await self.backend.run(image, self._spec))
+
+    async def recognize_from_crop(
+        self, frame_data: bytes, width: int, height: int, box: Box
+    ) -> OcrResult | None:
+        if not self._ready():
+            return None
+
+        x1 = max(0, int(box[0]))
+        y1 = max(0, int(box[1]))
+        x2 = min(width, int(box[2]))
+        y2 = min(height, int(box[3]))
+        if x2 <= x1 or y2 <= y1:
+            return None
+
+        rgb = frame_to_rgb(frame_data, width, height)
+        return await self.recognize(rgb[y1:y2, x1:x2])
+
+    def _decode(self, outputs: Outputs) -> OcrResult | None:
+        logits: NDArray | None = None
+        for value in outputs:
+            arr = np.asarray(value)
+            if arr.ndim == 3 and arr.shape[1] == self._slots:
+                logits = arr[0]
+
+        if logits is None:
+            return None
+
+        text, confidence = decode_ocr(logits, self._alphabet, self._pad)
+        return OcrResult(text, confidence) if text else None

camera_ui_ml-1.0.0/camera_ui_ml/geometry.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from typing import TypedDict
+
+Box = tuple[float, float, float, float]
+
+
+class NormalizedBox(TypedDict):
+    x: float
+    y: float
+    width: float
+    height: float
+
+
+def cxcywh_to_xyxy(cx: float, cy: float, w: float, h: float) -> Box:
+    half_w = w / 2.0
+    half_h = h / 2.0
+    return (cx - half_w, cy - half_h, cx + half_w, cy + half_h)
+
+
+def scale_box(box: Box, scale_x: float, scale_y: float) -> Box:
+    x1, y1, x2, y2 = box
+    return (x1 * scale_x, y1 * scale_y, x2 * scale_x, y2 * scale_y)
+
+
+def clamp_box(box: Box, width: float, height: float) -> Box:
+    x1, y1, x2, y2 = box
+    return (
+        min(max(x1, 0.0), width),
+        min(max(y1, 0.0), height),
+        min(max(x2, 0.0), width),
+        min(max(y2, 0.0), height),
+    )
+
+
+def normalize_box(box: Box, width: float, height: float) -> NormalizedBox:
+    x1, y1, x2, y2 = box
+    return {
+        "x": x1 / width,
+        "y": y1 / height,
+        "width": (x2 - x1) / width,
+        "height": (y2 - y1) / height,
+    }
+
+
+def pad_box(box: Box, width: float, height: float, padding: float, min_size: int = 0) -> Box:
+    """Expand a box by ``padding`` (fraction of its size) and an optional minimum
+    pixel size, clamped to the frame. Used to crop faces/plates with context."""
+    x1, y1, x2, y2 = box
+    w = x2 - x1
+    h = y2 - y1
+
+    extra_x = max(0.0, (min_size - w) / 2.0) if min_size > 0 else 0.0
+    extra_y = max(0.0, (min_size - h) / 2.0) if min_size > 0 else 0.0
+    pad_x = w * padding + extra_x
+    pad_y = h * padding + extra_y
+
+    return clamp_box((x1 - pad_x, y1 - pad_y, x2 + pad_x, y2 + pad_y), width, height)

camera_ui_ml-1.0.0/camera_ui_ml/model_manager.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+import asyncio
+import os
+from abc import ABC, abstractmethod
+from collections.abc import Mapping
+
+import aiohttp
+from camera_ui_sdk import LoggerService
+
+from .backend import InferenceBackend
+
+_CHUNK = 1024 * 1024
+
+
+class BaseModelManager(ABC):
+    def __init__(self, storage_path: str, logger: LoggerService, version: str) -> None:
+        self.logger = logger
+        self.model_path = os.path.join(storage_path, "models", version)
+        self._load_tasks: dict[str, asyncio.Task[InferenceBackend]] = {}
+
+    async def ensure_backend(self, model_name: str) -> InferenceBackend:
+        task = self._load_tasks.get(model_name)
+        if task is None:
+            task = asyncio.create_task(self._load(model_name))
+            self._load_tasks[model_name] = task
+        return await task
+
+    def reset(self) -> None:
+        self._load_tasks.clear()
+
+    @abstractmethod
+    def model_files(self, model_name: str) -> Mapping[str, tuple[str, str]]:
+        """Map of file key → (download_url, path relative to ``model_path``)."""
+
+    @abstractmethod
+    async def build_backend(self, model_name: str, paths: Mapping[str, str]) -> InferenceBackend:
+        """Build the runtime backend from the (already downloaded) local paths."""
+
+    async def _load(self, model_name: str) -> InferenceBackend:
+        files = self.model_files(model_name)
+        for url, rel in files.values():
+            await self._download(url, rel)
+
+        paths = {key: os.path.join(self.model_path, rel) for key, (_url, rel) in files.items()}
+        return await self.build_backend(model_name, paths)
+
+    async def _download(self, url: str, rel: str) -> None:
+        full_path = os.path.join(self.model_path, rel)
+        if os.path.isfile(full_path):
+            return
+
+        os.makedirs(os.path.dirname(full_path), exist_ok=True)
+        tmp_path = full_path + ".tmp"
+        name = os.path.basename(rel)
+        self.logger.log(f"Downloading {name}...")
+
+        async with aiohttp.ClientSession() as session, session.get(url) as response:
+            if response.status < 200 or response.status >= 300:
+                raise RuntimeError(f"Error downloading {url}: {response.status}")
+
+            total = int(response.headers.get("content-length", 0))
+            downloaded = 0
+            last_step = 0
+
+            with open(tmp_path, "wb") as handle:
+                async for chunk in response.content.iter_chunked(_CHUNK):
+                    if not chunk:
+                        continue
+                    downloaded += len(chunk)
+                    handle.write(chunk)
+                    if total > _CHUNK:
+                        percent = min(100, downloaded * 100 // total)
+                        if percent >= last_step + 25:
+                            last_step = (percent // 25) * 25
+                            self.logger.log(f"Downloading {name}... {last_step}%")
+
+        os.rename(tmp_path, full_path)
+        self.logger.log(f"Downloaded {name} ({downloaded / _CHUNK:.1f} MB)")

camera_ui_ml-1.0.0/camera_ui_ml/parsing.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+
+from .geometry import Box, cxcywh_to_xyxy
+
+NDArray = np.ndarray[Any, Any]
+RawDetection = tuple[int, float, Box]
+
+
+def channels_first(output: NDArray) -> NDArray:
+    squeezed = np.squeeze(output)
+    if squeezed.ndim != 2:
+        return squeezed
+    return squeezed if squeezed.shape[0] <= squeezed.shape[1] else squeezed.T
+
+
+def parse_yolov9(results: NDArray, threshold: float) -> list[RawDetection]:
+    scores = results[4:]
+    detections: list[RawDetection] = []
+    for class_id, index in np.argwhere(scores > threshold):
+        confidence = float(results[class_id + 4, index])
+        cx = float(results[0, index])
+        cy = float(results[1, index])
+        w = float(results[2, index])
+        h = float(results[3, index])
+        detections.append((int(class_id), confidence, cxcywh_to_xyxy(cx, cy, w, h)))
+    return detections
+
+
+def parse_end2end(rows: NDArray, threshold: float) -> list[RawDetection]:
+    detections: list[RawDetection] = []
+    for row in rows:
+        score = float(row[6])
+        if score <= threshold:
+            continue
+        detections.append(
+            (
+                int(row[5]),
+                score,
+                (float(row[1]), float(row[2]), float(row[3]), float(row[4])),
+            )
+        )
+    return detections
+
+
+def decode_ocr(logits: NDArray, alphabet: str, pad_char: str = "_") -> tuple[str, float]:
+    chars: list[str] = []
+    confidences: list[float] = []
+    for slot in logits:
+        index = int(np.argmax(slot))
+        char = alphabet[index] if index < len(alphabet) else pad_char
+        if char == pad_char:
+            break
+        shifted = np.exp(slot - np.max(slot))
+        confidences.append(float(shifted[index] / np.sum(shifted)))
+        chars.append(char)
+    return "".join(chars), (float(np.mean(confidences)) if confidences else 0.0)
+
+
+def l2_normalize(vector: NDArray) -> NDArray:
+    flat = np.asarray(vector, dtype=np.float32).flatten()
+    norm = float(np.linalg.norm(flat))
+    return flat / norm if norm > 0.0 else flat
+
+
+def nms(detections: list[RawDetection], iou_threshold: float = 0.45) -> list[RawDetection]:
+    if not detections:
+        return []
+
+    boxes = np.array([d[2] for d in detections], dtype=np.float32)
+    scores = np.array([d[1] for d in detections], dtype=np.float32)
+    order = scores.argsort()[::-1]
+
+    keep: list[int] = []
+    while order.size > 0:
+        best = int(order[0])
+        keep.append(best)
+        if order.size == 1:
+            break
+        rest = order[1:]
+        order = rest[_iou(boxes[best], boxes[rest]) <= iou_threshold]
+
+    return [detections[i] for i in keep]
+
+
+def _iou(box: NDArray, others: NDArray) -> NDArray:
+    x1 = np.maximum(box[0], others[:, 0])
+    y1 = np.maximum(box[1], others[:, 1])
+    x2 = np.minimum(box[2], others[:, 2])
+    y2 = np.minimum(box[3], others[:, 3])
+
+    inter = np.clip(x2 - x1, 0.0, None) * np.clip(y2 - y1, 0.0, None)
+    area = (box[2] - box[0]) * (box[3] - box[1])
+    areas = (others[:, 2] - others[:, 0]) * (others[:, 3] - others[:, 1])
+    union = area + areas - inter
+    return np.where(union > 0.0, inter / union, 0.0)

camera_ui_ml-1.0.0/camera_ui_ml/pipeline.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+import asyncio
+import os
+from collections.abc import Callable
+from concurrent.futures import ThreadPoolExecutor
+from typing import TypeVar
+
+T = TypeVar("T")
+
+_PREPARE_WORKERS = min(8, os.cpu_count() or 4)
+_prepare_executor = ThreadPoolExecutor(max_workers=_PREPARE_WORKERS, thread_name_prefix="ml-prepare")
+
+
+async def run_prepare(fn: Callable[[], T]) -> T:
+    return await asyncio.get_event_loop().run_in_executor(_prepare_executor, fn)
+
+
+def prepare_executor() -> ThreadPoolExecutor:
+    return _prepare_executor

camera_ui_ml-1.0.0/camera_ui_ml/preprocess.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+import io
+from typing import Any
+
+import numpy as np
+from PIL import Image
+
+from .backend import InputSpec
+from .geometry import Box
+
+NDArray = np.ndarray[Any, Any]
+
+
+def frame_to_rgb(data: bytes, width: int, height: int, fmt: str = "rgb") -> NDArray:
+    pixels = np.frombuffer(data, dtype=np.uint8)
+    if fmt == "rgb":
+        return pixels.reshape((height, width, 3))
+    if fmt == "rgba":
+        return pixels.reshape((height, width, 4))[:, :, :3]
+    if fmt == "gray":
+        return np.repeat(pixels.reshape((height, width, 1)), 3, axis=2)
+    raise ValueError(f"Unsupported frame format for detection: {fmt}")
+
+
+def decode_image(data: bytes) -> NDArray:
+    return np.asarray(Image.open(io.BytesIO(data)).convert("RGB"))
+
+
+def resize_rgb(rgb: NDArray, width: int, height: int) -> NDArray:
+    if rgb.shape[1] == width and rgb.shape[0] == height:
+        return rgb
+    return np.asarray(Image.fromarray(rgb, mode="RGB").resize((width, height)))
+
+
+def to_pil(rgb: NDArray, width: int | None = None, height: int | None = None) -> Image.Image:
+    image = Image.fromarray(rgb, mode="RGB")
+    if width is not None and height is not None and (image.width != width or image.height != height):
+        image = image.resize((width, height))
+    return image
+
+
+def to_tensor(rgb: NDArray, spec: InputSpec) -> NDArray:
+    resized = resize_rgb(rgb, spec.width, spec.height)
+
+    arr: NDArray
+    if spec.normalize == "unit":
+        arr = resized.astype(np.float32) / 255.0
+    elif spec.normalize == "facenet":
+        arr = (resized.astype(np.float32) - 127.5) / 128.0
+    else:  # "none"
+        arr = resized.astype(np.uint8 if spec.dtype == "uint8" else np.float32)
+
+    if spec.layout == "nchw":
+        arr = arr.transpose(2, 0, 1)
+
+    return np.ascontiguousarray(np.expand_dims(arr, axis=0))
+
+
+def crop_rgb(rgb: NDArray, box: Box) -> NDArray:
+    x1, y1, x2, y2 = (int(round(v)) for v in box)
+    return rgb[y1:y2, x1:x2]

camera_ui_ml-1.0.0/camera_ui_ml.egg-info/PKG-INFO

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: camera-ui-ml
+Version: 1.0.0
+Summary: Shared ML inference framework for camera.ui detection plugins (onnx, openvino, coreml, ncnn)
+Author-email: seydx <hi@seydx.dev>
+Maintainer-email: seydx <hi@seydx.dev>
+Project-URL: Homepage, https://github.com/cameraui/ml
+Project-URL: Documentation, https://github.com/cameraui/ml
+Project-URL: Repository, https://github.com/cameraui/ml
+Project-URL: Bug Tracker, https://github.com/cameraui/ml/issues
+Project-URL: Changelog, https://github.com/cameraui/ml/blob/main/CHANGELOG.md
+Keywords: camera.ui,python,ml,inference,detection
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: typing_extensions>=4.15.0
+Requires-Dist: camera-ui-sdk>=1.0.95
+Requires-Dist: numpy>=2.0
+Requires-Dist: pillow>=12.0
+Requires-Dist: aiohttp>=3.12
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Provides-Extra: clip
+Requires-Dist: transformers>=4.40; extra == "clip"
+Dynamic: license-file
+
+# camera-ui-ml
+
+[![PyPI](https://img.shields.io/pypi/v/camera-ui-ml?label=pypi&logo=pypi&logoColor=white)](https://pypi.org/project/camera-ui-ml/)
+
+Shared ML inference framework for camera.ui's detection plugins.
+
+---
+
+_Part of the camera.ui ecosystem - A comprehensive camera management solution._

camera_ui_ml-1.0.0/camera_ui_ml.egg-info/SOURCES.txt

@@ -0,0 +1,22 @@
+LICENSE.md
+README.md
+pyproject.toml
+camera_ui_ml/__init__.py
+camera_ui_ml/backend.py
+camera_ui_ml/geometry.py
+camera_ui_ml/model_manager.py
+camera_ui_ml/parsing.py
+camera_ui_ml/pipeline.py
+camera_ui_ml/preprocess.py
+camera_ui_ml/py.typed
+camera_ui_ml.egg-info/PKG-INFO
+camera_ui_ml.egg-info/SOURCES.txt
+camera_ui_ml.egg-info/dependency_links.txt
+camera_ui_ml.egg-info/requires.txt
+camera_ui_ml.egg-info/top_level.txt
+camera_ui_ml/detectors/__init__.py
+camera_ui_ml/detectors/base.py
+camera_ui_ml/detectors/box.py
+camera_ui_ml/detectors/clip.py
+camera_ui_ml/detectors/embedder.py
+camera_ui_ml/detectors/ocr.py

camera_ui_ml-1.0.0/camera_ui_ml.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

camera_ui_ml-1.0.0/camera_ui_ml.egg-info/requires.txt

@@ -0,0 +1,11 @@
+typing_extensions>=4.15.0
+camera-ui-sdk>=1.0.95
+numpy>=2.0
+pillow>=12.0
+aiohttp>=3.12
+
+[clip]
+transformers>=4.40
+
+[test]
+pytest>=8

camera_ui_ml-1.0.0/camera_ui_ml.egg-info/top_level.txt

@@ -0,0 +1 @@
+camera_ui_ml

camera_ui_ml-1.0.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=80.9.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "camera-ui-ml"
+version = "1.0.0"
+description = "Shared ML inference framework for camera.ui detection plugins (onnx, openvino, coreml, ncnn)"
+keywords = ["camera.ui", "python", "ml", "inference", "detection"]
+readme = "README.md"
+license-files = ["LICENSE.md"]
+authors = [{ name = "seydx", email = "hi@seydx.dev" }]
+maintainers = [{ name = "seydx", email = "hi@seydx.dev" }]
+requires-python = ">=3.11"
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = ["typing_extensions>=4.15.0", "camera-ui-sdk>=1.0.95", "numpy>=2.0", "pillow>=12.0", "aiohttp>=3.12"]
+
+[project.optional-dependencies]
+test = ["pytest>=8"]
+clip = ["transformers>=4.40"]
+
+[project.urls]
+Homepage = "https://github.com/cameraui/ml"
+Documentation = "https://github.com/cameraui/ml"
+Repository = "https://github.com/cameraui/ml"
+"Bug Tracker" = "https://github.com/cameraui/ml/issues"
+Changelog = "https://github.com/cameraui/ml/blob/main/CHANGELOG.md"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["camera_ui_ml*"]
+
+[tool.setuptools.package-data]
+camera_ui_ml = ["py.typed"]

camera_ui_ml-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+