How to Configure Zones and Motion Masks for Detection Areas in Frigate

Frigate limits object detection to specific camera regions by using polygonal zones and binary motion masks, both configurable via the web UI or YAML configuration files.

Frigate, the open-source NVR (Network Video Recorder) from blakeblackshear/frigate, provides granular control over where object detection occurs through zones and motion masks. These tools help reduce false positives and processing load by focusing computational resources only on relevant areas of your camera feeds.

Understanding Zones and Motion Masks

Frigate offers two complementary methods for defining detection areas. Zones are polygonal regions of interest where object presence triggers specific logic, while motion masks are binary images that suppress motion detection entirely in unwanted regions. According to the implementation in frigate/video/detect.py, masks are evaluated before zones during the detection pipeline, ensuring masked areas never reach zone tracking logic.

Configuring Zones for Object Detection

What Are Zones?

Zones are user-defined polygons that designate "areas of interest" within a camera view. As documented in docs/docs/configuration/zones.md, Frigate evaluates object presence by checking if the bottom-center point of an object's bounding box falls within a zone polygon. This approach ensures that objects are only considered "in" a zone when their base (representing their ground contact point) enters the defined area.

Creating Zones via the Web UI

The Frigate web interface provides a visual editor for drawing zones:

1. Navigate to Settings → Camera configuration → Masks / Zones.
2. Under the Zones section, click the + button.
3. Click points on the latest camera image to draw the polygon (click the first point again to close the shape).
4. Fill in the zone editor fields including Friendly name, Objects, Loitering time, and Inertia.
5. Click Save to persist the configuration.

Defining Zones in config.yml

Zones can also be defined directly in your config.yml file. The Pydantic models in frigate/config/schema.py validate the structure of these entries. Here is a standard YAML definition for a zone:

cameras:
  front_door:
    zones:
      entire_yard:
        friendly_name: Entire yard
        coordinates: 0.12,0.34,0.56,0.78,0.90,0.20

Coordinates are normalized values (0-1) representing percentages of the image width and height. Each pair corresponds to an x,y point in the polygon.

Enabling and Disabling Zones

Zones support runtime toggling without deletion. As noted in the source documentation, you can disable a zone by setting enabled: false in the YAML configuration or toggling it in the Debug view. Disabled zones are ignored at runtime but retain their definitions for quick re-enabling.

Filtering Alerts with Required Zones

To generate alerts only when objects enter specific zones, configure the required_zones parameter under the review configuration. This restricts notifications to meaningful movements rather than peripheral activity.

review:
  alerts:
    required_zones:
      - entire_yard
  detections:
    required_zones:
      - entire_yard

This configuration, referenced in docs/docs/configuration/zones.md, ensures that both alerts and detection recordings only trigger when objects occupy the defined yard area.

Configuring Motion Masks

What Are Motion Masks?

Motion masks are binary images where white pixels represent active detection areas and black pixels represent ignored regions. Unlike zones, which filter detection results, masks prevent motion detection from occurring in masked areas entirely, reducing CPU usage from irrelevant movement like trees or roads.

Creating Motion Masks via the Web UI

To create a motion mask through the interface:

1. Go to Settings → Camera configuration → Masks / Zones.
2. Under the Masks section, click +.
3. Paint the mask directly on the camera image (white areas allow detection, black areas suppress it).
4. Save the mask to apply it immediately.

Defining Motion Masks in YAML

Motion masks can reference external PNG files or base64-encoded images in your config.yml. Store mask images in a path relative to your configuration directory:

cameras:
  front_door:
    masks:
      motion_mask:
        file: masks/front_door.png

The frigate/config/schema.py file validates these mask definitions, ensuring proper file references and coordinate systems.

MQTT Integration for Motion Masks

Frigate exposes motion mask states through MQTT for home automation integration. The system publishes current states to frigate/<camera_name>/motion_mask/<mask_name>/state and accepts commands via frigate/<camera_name>/motion_mask/<mask_name>/set, allowing dynamic mask control from external systems like Home Assistant.

How Zones and Motion Masks Work Together

The detection pipeline in frigate/video/detect.py processes masks before evaluating zones. This sequential processing means that objects falling within a masked-out area are never considered for zone tracking. Use this behavior to first eliminate static background noise with motion masks, then apply zones to trigger specific actions in the remaining active areas.

Summary

• Zones are polygonal regions defined by normalized coordinates that trigger logic when an object's bottom-center point enters them.
• Motion masks are binary images that suppress motion detection entirely in blacked-out regions, evaluated before zones in the processing pipeline.
• Both can be configured visually via Settings → Camera configuration → Masks / Zones or manually in config.yml.
• Use required_zones under review configuration to filter alerts and recordings to specific areas.
• Motion masks support MQTT control via topics under frigate/<camera_name>/motion_mask/<mask_name>/.

Frequently Asked Questions

How do I prevent false alerts from cars on the street while detecting them in my driveway?

Create a motion mask covering the street area to suppress motion detection there entirely. Then define a zone covering only your driveway. Configure required_zones in your review alerts to only trigger notifications when vehicles enter the driveway zone. Because masks are evaluated before zones, street traffic never generates detection events.

What coordinate format does Frigate use for zone definitions?

Frigate uses normalized coordinates (values between 0 and 1) representing the percentage of image width and height. In config.yml, provide coordinates as comma-separated x,y pairs: 0.25,0.50,0.75,0.50 defines two points. The Pydantic validation in frigate/config/schema.py ensures these values fall within the valid 0-1 range.

Can I temporarily disable a zone without deleting its configuration?

Yes. Zones support an enabled boolean property that can be toggled in the Debug view or set to false in config.yml. Disabled zones are ignored at runtime but retain their polygon definitions and coordinates for easy re-enabling later, as implemented in the zone validation logic.

Why is my object not triggering the zone even though it appears inside the polygon?

Frigate evaluates zone presence using the bottom-center of the object's bounding box, not the entire box. If the object's base (bottom-center point) has not crossed into the polygon, the zone will not register the object. Adjust your zone polygon to ensure it includes the ground-level area where objects typically stand or move.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}