Skip to main content

Zones

Zones allow you to define a specific area of the frame and apply additional filters for object types so you can determine whether or not an object is within a particular area. Presence in a zone is evaluated based on the bottom center of the bounding box for the object. It does not matter how much of the bounding box overlaps with the zone.

For example, the cat in this image is currently in Zone 1, but not Zone 2. bottom center

Zones cannot have the same name as a camera. If desired, a single zone can include multiple cameras if you have multiple cameras covering the same area by configuring zones with the same name for each camera.

Enabling/Disabling Zones​

Zones can be toggled on or off without removing them from the configuration. Disabled zones are completely ignored at runtime - objects will not be tracked for zone presence, and zones will not appear in the debug view. This is useful for temporarily disabling a zone during certain seasons or times of day without modifying the configuration.

During testing, enable the Zones option for the Debug view of your camera (Settings --> Debug) so you can adjust as needed. The zone line will increase in thickness when any object enters the zone.

Creating a Zone​

  1. Navigate to Settings→Camera configuration→Masks / Zones and select the desired camera.
  2. Under the Zones section, click the plus icon to add a new zone.
  3. Click on the camera's latest image to create the points for the zone boundary. Click the first point again to close the polygon.
  4. Configure zone options such as Friendly name, Objects, Loitering time, and Inertia in the zone editor.
  5. Press Save when finished.

Restricting alerts and detections to specific zones​

Often you will only want alerts to be created when an object enters areas of interest. This is done by combining zones with required zones for review items.

To create an alert only when an object enters the entire_yard zone:

Navigate to Settings→Camera configuration→Review.

FieldDescription
Alerts config > Required zonesZones that an object must enter to be considered an alert; leave empty to allow any zone.

You may also want to filter detections to only be created when an object enters a secondary area of interest. For example, to trigger alerts when an object enters the inner area of the yard but detections when an object enters the edge of the yard:

Navigate to Settings→Camera configuration→Review.

FieldDescription
Alerts config > Required zonesZones that an object must enter to be considered an alert; leave empty to allow any zone.
Detections config > Required zonesZones that an object must enter to be considered a detection; leave empty to allow any zone.

Restricting snapshots to specific zones​

To only save snapshots when an object enters a specific zone:

  1. Navigate to Settings→Camera configuration→Snapshots and select your camera.
    • Set Required zones to entire_yard

Restricting zones to specific objects​

Sometimes you want to limit a zone to specific object types to have more granular control of when alerts, detections, and snapshots are saved. The following example limits one zone to person objects and the other to cars.

  1. Navigate to Settings→Camera configuration→Masks / Zones and select the desired camera.
  2. Create a zone named entire_yard covering everywhere you want to track a person.
    • Under Objects, add person
  3. Create a second zone named front_yard_street covering just the street.
    • Under Objects, add car

Only car objects can trigger the front_yard_street zone and only person can trigger the entire_yard. Objects will be tracked for any person that enter anywhere in the yard, and for cars only if they enter the street.

Zone Loitering​

Sometimes objects are expected to be passing through a zone, but an object loitering in an area is unexpected. Zones can be configured to have a minimum loitering time after which the object will be considered in the zone.

note

When using loitering zones, a review item will behave in the following way:

  • When a person is in a loitering zone, the review item will remain active until the person leaves the loitering zone, regardless of if they are stationary.
  • When any other object is in a loitering zone, the review item will remain active until the loitering time is met. Then if the object is stationary the review item will end.
  1. Navigate to Settings→Camera configuration→Masks / Zones and select the desired camera.
  2. Edit or create the zone (e.g., sidewalk).
    • Set Loitering time to the desired number of seconds (e.g., 4)
    • Under Objects, add the relevant object types (e.g., person)

Zone Inertia​

Sometimes an objects bounding box may be slightly incorrect and the bottom center of the bounding box is inside the zone while the object is not actually in the zone. Zone inertia helps guard against this by requiring an object's bounding box to be within the zone for multiple consecutive frames.

  1. Navigate to Settings→Camera configuration→Masks / Zones and select the desired camera.
  2. Edit or create the zone (e.g., front_yard).
    • Set Inertia to the desired number of consecutive frames (e.g., 3)

There may also be cases where you expect an object to quickly enter and exit a zone, like when a car is pulling into the driveway, and you may want to have the object be considered present in the zone immediately:

  1. Navigate to Settings→Camera configuration→Masks / Zones and select the desired camera.
  2. Edit or create the zone (e.g., driveway_entrance).
    • Set Inertia to 1

Speed Estimation​

Frigate can be configured to estimate the speed of objects moving through a zone. This works by combining data from Frigate's object tracker and "real world" distance measurements of the edges of the zone. The recommended use case for this feature is to track the speed of vehicles on a road as they move through the zone.

Your zone must be defined with exactly 4 points and should be aligned to the ground where objects are moving.

Ground plane 4-point zone

Speed estimation requires a minimum number of frames for your object to be tracked before a valid estimate can be calculated, so create your zone away from places where objects enter and exit for the best results. The object's bounding box must be stable and remain a constant size as it enters and exits the zone. Your zone should not take up the full frame, and the zone does not need to be the same size or larger than the objects passing through it. An object's speed is tracked while it passes through the zone and then saved to Frigate's database.

Accurate real-world distance measurements are required to estimate speeds. These distances can be specified through the distances field. Each number represents the real-world distance between consecutive points in the coordinates list. The fastest and most accurate way to configure this is through the Zone Editor in the Frigate UI.

  1. Navigate to Settings→Camera configuration→Masks / Zones and select the desired camera.
  2. Create or edit a zone with exactly 4 points aligned to the ground plane.
  3. In the zone editor, enter the real-world Distances between each pair of consecutive points.
    • For example, if the distance between the first and second points is 10 meters, between the second and third is 12 meters, etc.
  4. Distances are measured in meters (metric) or feet (imperial), depending on the Unit system setting.

The distance values are measured in meters (metric) or feet (imperial), depending on how unit_system is configured in your ui config:

Navigate to Settings→System→UI.

FieldDescription
Unit systemSet to metric (kilometers per hour) or imperial (miles per hour)

The average speed of your object as it moved through your zone is saved in Frigate's database and can be seen in the UI in the Tracked Object Details pane in Explore. Current estimated speed can also be seen on the debug view as the third value in the object label (see the caveats below). Current estimated speed, average estimated speed, and velocity angle (the angle of the direction the object is moving relative to the frame) of tracked objects is also sent through the events MQTT topic. See the MQTT docs.

These speed values are output as a number in miles per hour (mph) or kilometers per hour (kph). For miles per hour, set unit_system to imperial. For kilometers per hour, set unit_system to metric.

Best practices and caveats​

  • Speed estimation works best with a straight road or path when your object travels in a straight line across that path. Avoid creating your zone near intersections or anywhere that objects would make a turn.
  • Create a zone where the bottom center of your object's bounding box travels directly through it and does not become obscured at any time.
  • A large zone can be used (as in the photo example above), but it may cause inaccurate estimation if the object's bounding box changes shape (such as when it turns or becomes partially hidden). Generally it's best to make your zone large enough to capture a few frames, but small enough so that the bounding box doesn't change size as it enters, travels through, and exits the zone.
  • Depending on the size and location of your zone, you may want to decrease the zone's inertia value from the default of 3.
  • The more accurate your real-world dimensions can be measured, the more accurate speed estimation will be. However, due to the way Frigate's tracking algorithm works, you may need to tweak the real-world distance values so that estimated speeds better match real-world speeds.
  • Once an object leaves the zone, speed accuracy will likely decrease due to perspective distortion and misalignment with the calibrated area. Therefore, speed values will show as a zero through MQTT and will not be visible on the debug view when an object is outside of a speed tracking zone.
  • The speeds are only an estimation and are highly dependent on camera position, zone points, and real-world measurements. This feature should not be used for law enforcement.

Speed Threshold​

Zones can be configured with a minimum speed requirement, meaning an object must be moving at or above this speed to be considered inside the zone. Zone distances must be defined as described above.

  1. Navigate to Settings→Camera configuration→Masks / Zones and select the desired camera.
  2. Edit or create the zone with distances configured.
    • Set Speed threshold to the desired minimum speed (e.g., 20)
    • The unit is kph or mph, depending on the Unit system setting