Object area debugging and improvements (#16432)

* add ability to specify min and max area as percentages

* debug draw area and ratio

* docs

* update for best percentage

docs/docs/configuration/object_filters.md

@@ -34,7 +34,7 @@ False positives can also be reduced by filtering a detection based on its shape.
 
 ### Object Area
 
-`min_area` and `max_area` filter on the area of an objects bounding box in pixels and can be used to reduce false positives that are outside the range of expected sizes. For example when a leaf is detected as a dog or when a large tree is detected as a person, these can be reduced by adding a `min_area` / `max_area` filter.
+`min_area` and `max_area` filter on the area of an objects bounding box and can be used to reduce false positives that are outside the range of expected sizes. For example when a leaf is detected as a dog or when a large tree is detected as a person, these can be reduced by adding a `min_area` / `max_area` filter. These values can either be in pixels or as a percentage of the frame (for example, 0.12 represents 12% of the frame).
 
 ### Object Proportions
 

docs/docs/configuration/reference.md

@@ -312,9 +312,11 @@ objects:
   # Optional: filters to reduce false positives for specific object types
   filters:
     person:
-      # Optional: minimum width*height of the bounding box for the detected object (default: 0)
+      # Optional: minimum size of the bounding box for the detected object (default: 0).
+      # Can be specified as an integer for width*height in pixels or as a decimal representing the percentage of the frame (0.000001 to 0.99).
       min_area: 5000
-      # Optional: maximum width*height of the bounding box for the detected object (default: 24000000)
+      # Optional: maximum size of the bounding box for the detected object (default: 24000000).
+      # Can be specified as an integer for width*height in pixels or as a decimal representing the percentage of the frame (0.000001 to 0.99).
       max_area: 100000
       # Optional: minimum width/height of the bounding box for the detected object (default: 0)
       min_ratio: 0.5
@@ -559,7 +561,7 @@ genai:
 # Optional: Restream configuration
 # Uses https://github.com/AlexxIT/go2rtc (v1.9.2)
 # NOTE: The default go2rtc API port (1984) must be used,
-#       changing this port for the integrated go2rtc instance is not supported. 
+#       changing this port for the integrated go2rtc instance is not supported.
 go2rtc:
 
 # Optional: Live stream configuration for WebUI.

frigate/config/camera/objects.py

@@ -11,11 +11,13 @@ DEFAULT_TRACKED_OBJECTS = ["person"]
 
 
 class FilterConfig(FrigateBaseModel):
-    min_area: int = Field(
-        default=0, title="Minimum area of bounding box for object to be counted."
+    min_area: Union[int, float] = Field(
+        default=0,
+        title="Minimum area of bounding box for object to be counted. Can be pixels (int) or percentage (float between 0.000001 and 0.99).",
     )
-    max_area: int = Field(
-        default=24000000, title="Maximum area of bounding box for object to be counted."
+    max_area: Union[int, float] = Field(
+        default=24000000,
+        title="Maximum area of bounding box for object to be counted. Can be pixels (int) or percentage (float between 0.000001 and 0.99).",
     )
     min_ratio: float = Field(
         default=0,

frigate/config/config.py

@@ -29,6 +29,7 @@ from frigate.util.builtin import (
 )
 from frigate.util.config import (
     StreamInfoRetriever,
+    convert_area_to_pixels,
     find_config_file,
     get_relative_coordinates,
     migrate_frigate_config,
@@ -148,6 +149,13 @@ class RuntimeFilterConfig(FilterConfig):
         if mask is not None:
             config["mask"] = create_mask(frame_shape, mask)
 
+        # Convert min_area and max_area to pixels if they're percentages
+        if "min_area" in config:
+            config["min_area"] = convert_area_to_pixels(config["min_area"], frame_shape)
+
+        if "max_area" in config:
+            config["max_area"] = convert_area_to_pixels(config["max_area"], frame_shape)
+
         super().__init__(**config)
 
     def dict(self, **kwargs):

frigate/util/config.py

@@ -347,6 +347,36 @@ def get_relative_coordinates(
     return mask
 
 
+def convert_area_to_pixels(
+    area_value: Union[int, float], frame_shape: tuple[int, int]
+) -> int:
+    """
+    Convert area specification to pixels.
+
+    Args:
+        area_value: Area value (pixels or percentage)
+        frame_shape: Tuple of (height, width) for the frame
+
+    Returns:
+        Area in pixels
+    """
+    # If already an integer, assume it's in pixels
+    if isinstance(area_value, int):
+        return area_value
+
+    # Check if it's a percentage
+    if isinstance(area_value, float):
+        if 0.000001 <= area_value <= 0.99:
+            frame_area = frame_shape[0] * frame_shape[1]
+            return max(1, int(frame_area * area_value))
+        else:
+            raise ValueError(
+                f"Percentage must be between 0.000001 and 0.99, got {area_value}"
+            )
+
+    raise TypeError(f"Unexpected type for area: {type(area_value)}")
+
+
 class StreamInfoRetriever:
     def __init__(self) -> None:
         self.stream_cache: dict[str, tuple[int, int]] = {}

web/src/components/overlay/DebugDrawingLayer.tsx

@@ -0,0 +1,177 @@
+import React, { useState, useRef, useCallback, useMemo } from "react";
+import { Stage, Layer, Rect } from "react-konva";
+import { KonvaEventObject } from "konva/lib/Node";
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+} from "@/components/ui/popover";
+import Konva from "konva";
+import { useResizeObserver } from "@/hooks/resize-observer";
+
+type DebugDrawingLayerProps = {
+  containerRef: React.RefObject<HTMLDivElement>;
+  cameraWidth: number;
+  cameraHeight: number;
+};
+
+function DebugDrawingLayer({
+  containerRef,
+  cameraWidth,
+  cameraHeight,
+}: DebugDrawingLayerProps) {
+  const [rectangle, setRectangle] = useState<{
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  } | null>(null);
+  const [isDrawing, setIsDrawing] = useState(false);
+  const [showPopover, setShowPopover] = useState(false);
+  const stageRef = useRef<Konva.Stage>(null);
+
+  const [{ width: containerWidth }] = useResizeObserver(containerRef);
+
+  const imageSize = useMemo(() => {
+    const aspectRatio = cameraWidth / cameraHeight;
+    const imageWidth = containerWidth;
+    const imageHeight = imageWidth / aspectRatio;
+    return { width: imageWidth, height: imageHeight };
+  }, [containerWidth, cameraWidth, cameraHeight]);
+
+  const handleMouseDown = (e: KonvaEventObject<MouseEvent>) => {
+    const pos = e.target.getStage()?.getPointerPosition();
+    if (pos) {
+      setIsDrawing(true);
+      setRectangle({ x: pos.x, y: pos.y, width: 0, height: 0 });
+    }
+  };
+
+  const handleMouseMove = (e: KonvaEventObject<MouseEvent>) => {
+    if (!isDrawing) return;
+
+    const pos = e.target.getStage()?.getPointerPosition();
+    if (pos && rectangle) {
+      setRectangle({
+        ...rectangle,
+        width: pos.x - rectangle.x,
+        height: pos.y - rectangle.y,
+      });
+    }
+  };
+
+  const handleMouseUp = () => {
+    setIsDrawing(false);
+    if (rectangle) {
+      setShowPopover(true);
+    }
+  };
+
+  const convertToRealCoordinates = useCallback(
+    (x: number, y: number, width: number, height: number) => {
+      const scaleX = cameraWidth / imageSize.width;
+      const scaleY = cameraHeight / imageSize.height;
+      return {
+        x: x * scaleX,
+        y: y * scaleY,
+        width: width * scaleX,
+        height: height * scaleY,
+      };
+    },
+    [cameraWidth, cameraHeight, imageSize.width, imageSize.height],
+  );
+
+  const calculateArea = useCallback(() => {
+    if (!rectangle) return 0;
+    const { width, height } = convertToRealCoordinates(
+      0,
+      0,
+      Math.abs(rectangle.width),
+      Math.abs(rectangle.height),
+    );
+    return width * height;
+  }, [rectangle, convertToRealCoordinates]);
+
+  const calculateAreaPercentage = useCallback(() => {
+    if (!rectangle) return 0;
+    const { width, height } = convertToRealCoordinates(
+      0,
+      0,
+      Math.abs(rectangle.width),
+      Math.abs(rectangle.height),
+    );
+    return (width * height) / (cameraWidth * cameraHeight);
+  }, [rectangle, convertToRealCoordinates, cameraWidth, cameraHeight]);
+
+  const calculateRatio = useCallback(() => {
+    if (!rectangle) return 0;
+    const { width, height } = convertToRealCoordinates(
+      0,
+      0,
+      Math.abs(rectangle.width),
+      Math.abs(rectangle.height),
+    );
+    return width / height;
+  }, [rectangle, convertToRealCoordinates]);
+
+  return (
+    <div className="absolute inset-0 cursor-crosshair">
+      <Stage
+        width={imageSize.width}
+        height={imageSize.height}
+        onMouseDown={handleMouseDown}
+        onMouseMove={handleMouseMove}
+        onMouseUp={handleMouseUp}
+        ref={stageRef}
+      >
+        <Layer>
+          {rectangle && (
+            <Rect
+              x={rectangle.x}
+              y={rectangle.y}
+              width={rectangle.width}
+              height={rectangle.height}
+              stroke="white"
+              strokeWidth={4}
+            />
+          )}
+        </Layer>
+      </Stage>
+      {showPopover && rectangle && (
+        <Popover open={showPopover} onOpenChange={setShowPopover}>
+          <PopoverTrigger asChild>
+            <div
+              style={{
+                position: "absolute",
+                left: `${rectangle.x + rectangle.width / 2}px`,
+                top: `${rectangle.y + rectangle.height / 2}px`,
+              }}
+            />
+          </PopoverTrigger>
+          <PopoverContent className="w-auto p-5 text-center">
+            <div className="flex flex-col gap-2">
+              <div className="flex flex-col text-primary">
+                Area:{" "}
+                <span className="text-sm text-primary-variant">
+                  px: {calculateArea().toFixed(0)}
+                </span>
+                <span className="text-sm text-primary-variant">
+                  %: {calculateAreaPercentage().toFixed(4)}
+                </span>
+              </div>
+              <div className="flex flex-col text-primary">
+                Ratio:{" "}
+                <span className="text-sm text-primary-variant">
+                  {" "}
+                  {calculateRatio().toFixed(2)}
+                </span>
+              </div>
+            </div>
+          </PopoverContent>
+        </Popover>
+      )}
+    </div>
+  );
+}
+
+export default DebugDrawingLayer;

web/src/components/overlay/detail/ObjectLifecycle.tsx

@@ -490,12 +490,27 @@ export default function ObjectLifecycle({
                             Area
                           </p>
                           {Array.isArray(item.data.box) &&
-                          item.data.box.length >= 4
-                            ? Math.round(
-                                detectArea *
-                                  (item.data.box[2] * item.data.box[3]),
-                              )
-                            : "N/A"}
+                          item.data.box.length >= 4 ? (
+                            <>
+                              <div className="flex flex-col text-xs">
+                                px:{" "}
+                                {Math.round(
+                                  detectArea *
+                                    (item.data.box[2] * item.data.box[3]),
+                                )}
+                              </div>
+                              <div className="flex flex-col text-xs">
+                                %:{" "}
+                                {(
+                                  (detectArea *
+                                    (item.data.box[2] * item.data.box[3])) /
+                                  detectArea
+                                ).toFixed(4)}
+                              </div>
+                            </>
+                          ) : (
+                            "N/A"
+                          )}
                         </div>
                       </div>
                     </div>

web/src/views/settings/ObjectSettingsView.tsx

@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useMemo } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import ActivityIndicator from "@/components/indicators/activity-indicator";
 import AutoUpdatingCameraImage from "@/components/camera/AutoUpdatingCameraImage";
 import { CameraConfig, FrigateConfig } from "@/types/frigateConfig";
@@ -23,6 +23,9 @@ import { getIconForLabel } from "@/utils/iconUtil";
 import { capitalizeFirstLetter } from "@/utils/stringUtil";
 import { LuExternalLink, LuInfo } from "react-icons/lu";
 import { Link } from "react-router-dom";
+import DebugDrawingLayer from "@/components/overlay/DebugDrawingLayer";
+import { Separator } from "@/components/ui/separator";
+import { isDesktop } from "react-device-detect";
 
 type ObjectSettingsViewProps = {
   selectedCamera?: string;
@@ -37,6 +40,8 @@ export default function ObjectSettingsView({
 }: ObjectSettingsViewProps) {
   const { data: config } = useSWR<FrigateConfig>("config");
 
+  const containerRef = useRef<HTMLDivElement>(null);
+
   const DEBUG_OPTIONS = [
     {
       param: "bbox",
@@ -130,6 +135,12 @@ export default function ObjectSettingsView({
     [options, setOptions],
   );
 
+  const [debugDraw, setDebugDraw] = useState(false);
+
+  useEffect(() => {
+    setDebugDraw(false);
+  }, [selectedCamera]);
+
   const cameraConfig = useMemo(() => {
     if (config && selectedCamera) {
       return config.cameras[selectedCamera];
@@ -234,7 +245,7 @@ export default function ObjectSettingsView({
                                   <span className="sr-only">Info</span>
                                 </div>
                               </PopoverTrigger>
-                              <PopoverContent className="w-80">
+                              <PopoverContent className="w-80 text-sm">
                                 {info}
                               </PopoverContent>
                             </Popover>
@@ -256,18 +267,74 @@ export default function ObjectSettingsView({
                     </div>
                   ))}
                 </div>
+                {isDesktop && (
+                  <>
+                    <Separator className="my-2" />
+                    <div className="flex w-full flex-row items-center justify-between">
+                      <div className="mb-2 flex flex-col">
+                        <div className="flex items-center gap-2">
+                          <Label
+                            className="mb-0 cursor-pointer capitalize text-primary"
+                            htmlFor="debugdraw"
+                          >
+                            Object Shape Filter Drawing
+                          </Label>
+
+                          <Popover>
+                            <PopoverTrigger asChild>
+                              <div className="cursor-pointer p-0">
+                                <LuInfo className="size-4" />
+                                <span className="sr-only">Info</span>
+                              </div>
+                            </PopoverTrigger>
+                            <PopoverContent className="w-80 text-sm">
+                              Enable this option to draw a rectangle on the
+                              camera image to show its area and ratio. These
+                              values can then be used to set object shape filter
+                              parameters in your config.
+                              <div className="mt-2 flex items-center text-primary">
+                                <Link
+                                  to="https://docs.frigate.video/configuration/object_filters#object-shape"
+                                  target="_blank"
+                                  rel="noopener noreferrer"
+                                  className="inline"
+                                >
+                                  Read the documentation{" "}
+                                  <LuExternalLink className="ml-2 inline-flex size-3" />
+                                </Link>
+                              </div>
+                            </PopoverContent>
+                          </Popover>
+                        </div>
+                        <div className="mt-1 text-xs text-muted-foreground">
+                          Draw a rectangle on the image to view area and ratio
+                          details
+                        </div>
+                      </div>
+                      <Switch
+                        key={`$draw-${selectedCamera}`}
+                        className="ml-1"
+                        id="debug_draw"
+                        checked={debugDraw}
+                        onCheckedChange={(isChecked) => {
+                          setDebugDraw(isChecked);
+                        }}
+                      />
+                    </div>
+                  </>
+                )}
               </div>
             </div>
           </TabsContent>
           <TabsContent value="objectlist">
-            {ObjectList(memoizedObjects)}
+            <ObjectList cameraConfig={cameraConfig} objects={memoizedObjects} />
           </TabsContent>
         </Tabs>
       </div>
 
       {cameraConfig ? (
         <div className="flex md:h-dvh md:max-h-full md:w-7/12 md:grow">
-          <div className="size-full min-h-10">
+          <div ref={containerRef} className="relative size-full min-h-10">
             <AutoUpdatingCameraImage
               camera={cameraConfig.name}
               searchParams={searchParams}
@@ -275,6 +342,13 @@ export default function ObjectSettingsView({
               className="size-full"
               cameraClasses="relative w-full h-full flex flex-col justify-start"
             />
+            {debugDraw && (
+              <DebugDrawingLayer
+                containerRef={containerRef}
+                cameraWidth={cameraConfig.detect.width}
+                cameraHeight={cameraConfig.detect.height}
+              />
+            )}
           </div>
         </div>
       ) : (
@@ -284,7 +358,12 @@ export default function ObjectSettingsView({
   );
 }
 
-function ObjectList(objects?: ObjectType[]) {
+type ObjectListProps = {
+  cameraConfig: CameraConfig;
+  objects?: ObjectType[];
+};
+
+function ObjectList({ cameraConfig, objects }: ObjectListProps) {
   const { data: config } = useSWR<FrigateConfig>("config");
 
   const colormap = useMemo(() => {
@@ -326,7 +405,7 @@ function ObjectList(objects?: ObjectType[]) {
                     {capitalizeFirstLetter(obj.label.replaceAll("_", " "))}
                   </div>
                 </div>
-                <div className="flex w-8/12 flex-row items-end justify-end">
+                <div className="flex w-8/12 flex-row items-center justify-end">
                   <div className="text-md mr-2 w-1/3">
                     <div className="flex flex-col items-end justify-end">
                       <p className="mb-1.5 text-sm text-primary-variant">
@@ -351,7 +430,25 @@ function ObjectList(objects?: ObjectType[]) {
                       <p className="mb-1.5 text-sm text-primary-variant">
                         Area
                       </p>
-                      {obj.area ? obj.area.toString() : "-"}
+                      {obj.area ? (
+                        <>
+                          <div className="text-xs">
+                            px: {obj.area.toString()}
+                          </div>
+                          <div className="text-xs">
+                            %:{" "}
+                            {(
+                              obj.area /
+                              (cameraConfig.detect.width *
+                                cameraConfig.detect.height)
+                            )
+                              .toFixed(4)
+                              .toString()}
+                          </div>
+                        </>
+                      ) : (
+                        "-"
+                      )}
                     </div>
                   </div>
                 </div>