Merge pull request #1033 from john-/yolo_component_squashed

yolo component

Author: roflcoopter

.mypy.ini

@@ -77,4 +77,7 @@ ignore_missing_imports = True
 ignore_missing_imports = True
 
 [mypy-telegram-ext.*]
+ignore_missing_imports = True
+
+[mypy-ultralytics.*]
 ignore_missing_imports = True

docs/src/pages/components-explorer/components/yolo/_meta.tsx

@@ -0,0 +1,12 @@
+import { Component } from "@site/src/types";
+
+const ComponentMetadata: Component = {
+  title: "Ultralytics YOLO",
+  name: "yolo",
+  description: "Ultralytics YOLO supports a wide range of YOLO models, from early versions like YOLOv3 to the latest YOLO11",
+  image: "https://cdn.prod.website-files.com/680a070c3b99253410dd3dcf/680a070c3b99253410dd3e88_UltralyticsYOLO_full_blue.svg",
+  tags: ['object_detector'],
+};
+
+export default ComponentMetadata;
+

docs/src/pages/components-explorer/components/yolo/config.json

@@ -0,0 +1,113 @@
+import ComponentConfiguration from "@site/src/pages/components-explorer/_components/ComponentConfiguration";
+import ComponentHeader from "@site/src/pages/components-explorer/_components/ComponentHeader";
+import ComponentTroubleshooting from "@site/src/pages/components-explorer/_components/ComponentTroubleshooting/index.mdx";
+
+import ComponentMetadata from "./_meta";
+import config from "./config.json";
+
+<ComponentHeader meta={ComponentMetadata} />
+
+Ultralytics YOLO supports a wide range of models, from early versions like YOLOv3 to the latest YOLO11.
+
+:::warning
+
+This component has undergone limited testing.  In addition to partial functional testing, only the following models have been confirmed to work: yolov5mu.pt, yolov8n, and yolo11s.pt
+
+:::
+
+:::note
+
+`yolo` component uses the official [`ultralytics`](https://docs.ultralytics.com/usage/python) python package.  A GPU is used when available.
+
+:::
+
+:::info
+
+Models are not installed by default.  See below for steps to define the model as well as make them available to Viseron.
+
+:::
+
+## Configuration
+
+<details>
+  <summary>Configuration example</summary>
+
+```yaml title="/config/config.yaml"
+yolo:
+  object_detector:
+    model_path: /detectors/models/yolo/my_model.pt
+    cameras:
+      viseron_camera1:
+        fps: 1
+        scan_on_motion_only: true
+        log_all_objects: false
+        labels:
+          - label: dog
+            confidence: 0.7
+            trigger_event_recording: false
+          - label: cat
+            confidence: 0.8
+```
+
+</details>
+
+<ComponentConfiguration meta={ComponentMetadata} config={config} />
+
+### Pre-trained models
+
+These steps should assist in locating models, configuring your container to access them, and configuring Viseron to use them.
+
+#### Finding models
+
+Pre-trained YOLO models can be found online or you can train them yourself.
+
+Examples of where to find pre-trained models:
+
+- [Ultralytics](https://docs.ultralytics.com/models/)
+- [Roboflow](https://universe.roboflow.com/)
+- [Hugging Face](https://huggingface.co/models?pipeline_tag=object-detection&sort=trending)
+
+There are models for many different tasks, including object detection.  If you are not sure if there is a problem with Viseron please confirm your
+Viseron environment with a stock YOLO model from Ultralytics.  For example: [yolov8n.pt](https://github.com/ultralytics/assets/releases/download/v8.3.0/yolov8n.pt)
+
+This component does not provide any training capabilities.  See the [Ultralytics training](https://docs.ultralytics.com/modes/train/) documentation for more information.
+
+#### Where to place models
+
+Place your YOLO models in a directory of your choice.
+
+There will be a later step to map the directory to the container.  Therefore, choose a location supported by docker compose.  If in doubt, do not use a SMB or NFS share.
+
+#### Configuring Docker to make models available to Viseron
+
+The following `docker-compose.yaml` snippet will show how to map the directory above to the container:
+```yaml title="/docker-compose.yaml"
+    volumes:
+      - {models path}:/detectors/models/yolo
+```
+
+This is the only change to `docker-compose.yaml` required for this component.
+
+#### Configuring Viseron to use a model
+
+Modify the `model_path` setting in your Viseron `config.yaml` to point to one of the model(s) you installed.  See the example above.
+
+Only one model can be used at a time.
+
+### Image resizing
+
+Images inferenced by the component are resized by the underlying `ultralytics` package to match the model's input size.
+
+There is no functionality to resize the image in the `yolo` component configuration before inferencing.
+
+### Labels
+
+When Viseron loads the model, it will print that model's labels to the log.
+```
+cd {location of Viseron docker-compose.yaml}
+docker compose logs | grep "Labels"
+viseron  | 2025-05-29 08:19:04.943 [INFO    ] [viseron.components.yolo.object_detector] - Labels: {0: 'bicycle', 1: 'bird', 2: 'bus', 3: 'car', 4: 'cat', 5: 'dog', 6: 'motorcycle', 7: 'person', 8: 'truck', 9: 'squirrel', 10: 'car-light', 11: 'rabbit', 12: 'fox', 13: 'opossum', 14: 'skunk', 15: 'racoon'}
+```
+
+<ComponentTroubleshooting meta={ComponentMetadata} />
+

docs/src/pages/components-explorer/components/yolo/index.mdx

@@ -34,3 +34,4 @@ sqlalchemy==2.0.30
 watchdog==4.0.0
 python-telegram-bot==21.4
 onvif-zeep==0.2.12
+ultralytics==8.3.146

requirements.txt

@@ -161,7 +161,7 @@ async def forward_event(event: Event) -> None:
 
     @debounce(
         wait=message["debounce"],
-        options=DebounceOptions(  # pylint: disable=unexpected-keyword-arg
+        options=DebounceOptions(
             time_window=message["debounce"],
         ),
     )

viseron/components/webserver/websocket_api/commands.py

@@ -0,0 +1,104 @@
+"""YOLO component."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import voluptuous as vol
+
+from viseron import Viseron
+from viseron.domains import RequireDomain, setup_domain
+from viseron.domains.object_detector import (
+    BASE_CONFIG_SCHEMA as OBJECT_DETECTOR_BASE_CONFIG_SCHEMA,
+)
+from viseron.domains.object_detector.const import CONFIG_CAMERAS
+from viseron.helpers.schemas import FLOAT_MIN_ZERO_MAX_ONE
+from viseron.helpers.validators import Maybe
+
+from .const import (
+    COMPONENT,
+    CONFIG_DEVICE,
+    CONFIG_HALF_PRECISION,
+    CONFIG_IOU,
+    CONFIG_MIN_CONFIDENCE,
+    CONFIG_MODEL_PATH,
+    CONFIG_OBJECT_DETECTOR,
+    DEFAULT_DEVICE,
+    DEFAULT_HALF_PRECISION,
+    DEFAULT_IOU,
+    DEFAULT_MIN_CONFIDENCE,
+    DEFAULT_MODEL_PATH,
+    DESC_COMPONENT,
+    DESC_DEVICE,
+    DESC_HALF_PRECISION,
+    DESC_IOU,
+    DESC_MIN_CONFIDENCE,
+    DESC_MODEL_PATH,
+    DESC_OBJECT_DETECTOR,
+)
+
+OBJECT_DETECTOR_SCHEMA = OBJECT_DETECTOR_BASE_CONFIG_SCHEMA.extend(
+    {
+        vol.Optional(
+            CONFIG_MODEL_PATH,
+            default=DEFAULT_MODEL_PATH,
+            description=DESC_MODEL_PATH,
+        ): str,
+        vol.Optional(
+            CONFIG_MIN_CONFIDENCE,
+            default=DEFAULT_MIN_CONFIDENCE,
+            description=DESC_MIN_CONFIDENCE,
+        ): FLOAT_MIN_ZERO_MAX_ONE,
+        vol.Optional(
+            CONFIG_IOU,
+            default=DEFAULT_IOU,
+            description=DESC_IOU,
+        ): FLOAT_MIN_ZERO_MAX_ONE,
+        vol.Optional(
+            CONFIG_HALF_PRECISION,
+            default=DEFAULT_HALF_PRECISION,
+            description=DESC_HALF_PRECISION,
+        ): bool,
+        vol.Optional(
+            CONFIG_DEVICE,
+            default=DEFAULT_DEVICE,
+            description=DESC_DEVICE,
+        ): Maybe(str),
+    }
+)
+
+CONFIG_SCHEMA = vol.Schema(
+    {
+        vol.Required(COMPONENT, description=DESC_COMPONENT): vol.Schema(
+            {
+                vol.Required(
+                    CONFIG_OBJECT_DETECTOR, description=DESC_OBJECT_DETECTOR
+                ): OBJECT_DETECTOR_SCHEMA,
+            }
+        )
+    },
+    extra=vol.ALLOW_EXTRA,
+)
+
+
+def setup(vis: Viseron, config: dict[str, Any]) -> bool:
+    """Set up YOLO component."""
+    config = config[COMPONENT]
+
+    if config.get(CONFIG_OBJECT_DETECTOR, None):
+        for camera_identifier in config[CONFIG_OBJECT_DETECTOR][CONFIG_CAMERAS].keys():
+            setup_domain(
+                vis,
+                COMPONENT,
+                CONFIG_OBJECT_DETECTOR,
+                config,
+                identifier=camera_identifier,
+                require_domains=[
+                    RequireDomain(
+                        domain="camera",
+                        identifier=camera_identifier,
+                    )
+                ],
+            )
+
+    return True

viseron/components/yolo/__init__.py

@@ -0,0 +1,40 @@
+"""Constants for the YOLO component."""
+from typing import Final
+
+COMPONENT = "yolo"
+
+# CONFIG_SCHEMA constants
+CONFIG_OBJECT_DETECTOR = "object_detector"
+
+# OBJECT_DETECTOR_SCHEMA constants
+CONFIG_MODEL_PATH = "model_path"
+CONFIG_MIN_CONFIDENCE = "min_confidence"
+CONFIG_IOU = "iou"
+CONFIG_HALF_PRECISION = "half_precision"
+CONFIG_DEVICE = "device"
+
+DEFAULT_MODEL_PATH = "/detectors/models/yolo/default.pt"
+DEFAULT_MIN_CONFIDENCE = 0.25
+DEFAULT_IOU = 0.7
+DEFAULT_HALF_PRECISION = False
+DEFAULT_DEVICE: Final = None
+
+DESC_COMPONENT = "YOLO configuration."
+DESC_OBJECT_DETECTOR = "Object detector domain config."
+
+DESC_MODEL_PATH = (
+    "Path to a YOLO model."
+    "More information "
+    "<a href=https://docs.ultralytics.com/models>here</a>."
+)
+DESC_MIN_CONFIDENCE = (
+    "Minimum confidence to consider a detection.<br>"
+    "This minimum is enforced during inference before being filtered by values "
+    "in <code>labels</code>"
+)
+DESC_IOU = "Intersection Over Union (IoU) threshold for Non-Maximum Suppression (NMS)."
+DESC_HALF_PRECISION = (
+    "Enable/disable half precision accuracy.<br>"
+    "If your GPU supports FP16, enabling this might give you a performance increase."
+)
+DESC_DEVICE = "Specifies the device for inference (e.g., cpu, cuda:0 or 0)."

viseron/components/yolo/const.py

@@ -0,0 +1,98 @@
+"""YOLO object detector."""
+
+import logging
+from pathlib import Path
+
+import numpy as np
+from ultralytics import YOLO
+
+from viseron import Viseron
+from viseron.domains.object_detector import AbstractObjectDetector
+from viseron.domains.object_detector.detected_object import DetectedObject
+from viseron.exceptions import DomainNotReady
+
+from .const import (
+    COMPONENT,
+    CONFIG_DEVICE,
+    CONFIG_HALF_PRECISION,
+    CONFIG_IOU,
+    CONFIG_MIN_CONFIDENCE,
+    CONFIG_MODEL_PATH,
+    CONFIG_OBJECT_DETECTOR,
+)
+
+LOGGER = logging.getLogger(__name__)
+
+
+def setup(vis: Viseron, config, identifier) -> bool:
+    """Set up the YOLO object_detector domain."""
+    ObjectDetector(vis, config, identifier)
+
+    return True
+
+
+class ObjectDetector(AbstractObjectDetector):
+    """YOLO object detection."""
+
+    def __init__(self, vis: Viseron, config, camera_identifier) -> None:
+        super().__init__(
+            vis, COMPONENT, config[CONFIG_OBJECT_DETECTOR], camera_identifier
+        )
+
+        try:
+            model = Path(self._config[CONFIG_MODEL_PATH])
+            self._detector = YOLO(model)
+        except Exception as error:
+            LOGGER.error("YOLO model file not loaded: %s", error)
+            raise DomainNotReady from error
+
+        LOGGER.info(f"Loaded YOLO model: {model}")
+        LOGGER.info(f"Labels: {self._detector.names}")
+
+    def preprocess(self, frame):
+        """Preprocess frame before detection."""
+
+        return np.array(frame)
+
+    def postprocess(self, results):
+        """Return yolo detections as DetectedObject."""
+
+        objects = []
+
+        for result in results:
+            classes_names = result.names
+
+            for box in result.boxes:
+                cls = int(box.cls[0])
+                [x1, y1, x2, y2] = box.xyxy[0]
+                x1, y1, x2, y2 = int(x1), int(y1), int(x2), int(y2)
+                objects.append(
+                    DetectedObject.from_absolute(
+                        label=classes_names[cls],
+                        confidence=float(box.conf),
+                        x1=x1,
+                        y1=y1,
+                        x2=x2,
+                        y2=y2,
+                        frame_res=self._camera.resolution,
+                        model_res=result.orig_shape[::-1],
+                    )
+                )
+        return objects
+
+    def return_objects(self, frame):
+        """Perform object detection."""
+        try:
+            results = self._detector.predict(
+                frame,
+                conf=self._config[CONFIG_MIN_CONFIDENCE],
+                iou=self._config[CONFIG_IOU],
+                half=self._config[CONFIG_HALF_PRECISION],
+                device=self._config[CONFIG_DEVICE],
+                verbose=False,
+            )
+        except ValueError as error:
+            LOGGER.error(f"Error calling yolo prediction check yolo config: {error}")
+            return []
+
+        return self.postprocess(results)