Estimated object speed for zones (#16452)

* utility functions * backend config * backend object speed tracking * draw speed on debug view * basic frontend zone editor * remove line sorting * fix types * highlight line on canvas when entering value in zone edit pane * rename vars and add validation * ensure speed estimation is disabled when user adds more than 4 points * pixel velocity in debug * unit_system in config * ability to define unit system in config * save max speed to db * frontend * docs * clarify docs * utility functions * backend config * backend object speed tracking * draw speed on debug view * basic frontend zone editor * remove line sorting * fix types * highlight line on canvas when entering value in zone edit pane * rename vars and add validation * ensure speed estimation is disabled when user adds more than 4 points * pixel velocity in debug * unit_system in config * ability to define unit system in config * save max speed to db * frontend * docs * clarify docs * fix duplicates from merge * include max_estimated_speed in api responses * add units to zone edit pane * catch undefined * add average speed * clarify docs * only track average speed when object is active * rename vars * ensure points and distances are ordered clockwise * only store the last 10 speeds like score history * remove max estimated speed * update docs * update docs * fix point ordering * improve readability * docs inertia recommendation * fix point ordering * check object frame time * add velocity angle to frontend * docs clarity * add frontend speed filter * fix mqtt docs * fix mqtt docs * don't try to remove distances if they weren't already defined * don't display estimates on debug view/snapshots if object is not in a speed tracking zone * docs * implement speed_threshold for zone presence * docs for threshold * better ground plane image * improve image zone size * add inertia to speed threshold example
2026-10-09 00:02:48 +03:00 · 2025-02-10 13:23:42 -07:00
parent dd7820e4ee
commit 72209986b6
25 changed files with 1030 additions and 79 deletions
@@ -1,13 +1,16 @@
 # this uses the base model because the color is an extra attribute
+import logging
 from typing import Optional, Union

 import numpy as np
-from pydantic import BaseModel, Field, PrivateAttr, field_validator
+from pydantic import BaseModel, Field, PrivateAttr, field_validator, model_validator

 from .objects import FilterConfig

 __all__ = ["ZoneConfig"]

+logger = logging.getLogger(__name__)
+

 class ZoneConfig(BaseModel):
    filters: dict[str, FilterConfig] = Field(
@@ -16,6 +19,10 @@ class ZoneConfig(BaseModel):
    coordinates: Union[str, list[str]] = Field(
        title="Coordinates polygon for the defined zone."
    )
+    distances: Optional[Union[str, list[str]]] = Field(
+        default_factory=list,
+        title="Real-world distances for the sides of quadrilateral for the defined zone.",
+    )
    inertia: int = Field(
        default=3,
        title="Number of consecutive frames required for object to be considered present in the zone.",
@@ -26,6 +33,11 @@ class ZoneConfig(BaseModel):
        ge=0,
        title="Number of seconds that an object must loiter to be considered in the zone.",
    )
+    speed_threshold: Optional[float] = Field(
+        default=None,
+        ge=0.1,
+        title="Minimum speed value for an object to be considered in the zone.",
+    )
    objects: Union[str, list[str]] = Field(
        default_factory=list,
        title="List of objects that can trigger the zone.",
@@ -49,6 +61,34 @@ class ZoneConfig(BaseModel):

        return v

+    @field_validator("distances", mode="before")
+    @classmethod
+    def validate_distances(cls, v):
+        if v is None:
+            return None
+
+        if isinstance(v, str):
+            distances = list(map(str, map(float, v.split(","))))
+        elif isinstance(v, list):
+            distances = [str(float(val)) for val in v]
+        else:
+            raise ValueError("Invalid type for distances")
+
+        if len(distances) != 4:
+            raise ValueError("distances must have exactly 4 values")
+
+        return distances
+
+    @model_validator(mode="after")
+    def check_loitering_time_constraints(self):
+        if self.loitering_time > 0 and (
+            self.speed_threshold is not None or len(self.distances) > 0
+        ):
+            logger.warning(
+                "loitering_time should not be set on a zone if speed_threshold or distances is set."
+            )
+        return self
+
    def __init__(self, **config):
        super().__init__(**config)

@@ -5,7 +5,7 @@ from pydantic import Field

 from .base import FrigateBaseModel

-__all__ = ["TimeFormatEnum", "DateTimeStyleEnum", "UIConfig"]
+__all__ = ["TimeFormatEnum", "DateTimeStyleEnum", "UnitSystemEnum", "UIConfig"]


 class TimeFormatEnum(str, Enum):
@@ -21,6 +21,11 @@ class DateTimeStyleEnum(str, Enum):
    short = "short"


+class UnitSystemEnum(str, Enum):
+    imperial = "imperial"
+    metric = "metric"
+
+
 class UIConfig(FrigateBaseModel):
    timezone: Optional[str] = Field(default=None, title="Override UI timezone.")
    time_format: TimeFormatEnum = Field(
@@ -35,3 +40,6 @@ class UIConfig(FrigateBaseModel):
    strftime_fmt: Optional[str] = Field(
        default=None, title="Override date and time format using strftime syntax."
    )
+    unit_system: UnitSystemEnum = Field(
+        default=UnitSystemEnum.metric, title="The unit system to use for measurements."
+    )