chris/frigate
1
0
Fork 0
forked from Github/frigate
Code Pull Requests Packages Activity

Docs updates (#9476)

Browse Source 
* revamp plus docs

* consolidate label guidance

* add some common complete config examples

* clarify zone presence

* bottom center example of mask

* update recommended hardware

* update nav

* update getting started

* add openvino example

* explain why we track stationary objects

* move false positive guide to config folder

* fix link

* update record and parked car guide

* tweaks
This commit is contained in:
Blake Blackshear
2024-01-30 06:14:16 -06:00
committed by GitHub
parent 64a91f552f
commit d15ab0922b
28 changed files with 1142 additions and 769 deletions
Download Patch File Download Diff File Expand all files Collapse all files

55
docs/docs/guides/false_positives.md
View File

@@ -1,55 +0,0 @@
---
id: false_positives
title: Reducing false positives
---
## Object Scores
For object filters in your configuration, any single detection below `min_score` will be ignored as a false positive. `threshold` is based on the median of the history of scores (padded to 3 values) for a tracked object. Consider the following frames when `min_score` is set to 0.6 and threshold is set to 0.85:
| Frame | Current Score | Score History | Computed Score | Detected Object |
| ----- | ------------- | --------------------------------- | -------------- | --------------- |
| 1 | 0.7 | 0.0, 0, 0.7 | 0.0 | No |
| 2 | 0.55 | 0.0, 0.7, 0.0 | 0.0 | No |
| 3 | 0.85 | 0.7, 0.0, 0.85 | 0.7 | No |
| 4 | 0.90 | 0.7, 0.85, 0.95, 0.90 | 0.875 | Yes |
| 5 | 0.88 | 0.7, 0.85, 0.95, 0.90, 0.88 | 0.88 | Yes |
| 6 | 0.95 | 0.7, 0.85, 0.95, 0.90, 0.88, 0.95 | 0.89 | Yes |
In frame 2, the score is below the `min_score` value, so Frigate ignores it and it becomes a 0.0. The computed score is the median of the score history (padding to at least 3 values), and only when that computed score crosses the `threshold` is the object marked as a true positive. That happens in frame 4 in the example.
### Minimum Score
Any detection below `min_score` will be immediately thrown out and never tracked because it is considered a false positive. If `min_score` is too low then false positives may be detected and tracked which can confuse the object tracker and may lead to wasted resources. If `min_score` is too high then lower scoring true positives like objects that are further away or partially occluded may be thrown out which can also confuse the tracker and cause valid events to be lost or disjointed.
### Threshold
`threshold` is used to determine that the object is a true positive. Once an object is detected with a score >= `threshold` object is considered a true positive. If `threshold` is too low then some higher scoring false positives may create an event. If `threshold` is too high then true positive events may be missed due to the object never scoring high enough.
## Object Shape
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. The recordings timeline can be used to determine the area of the bounding box in that frame by selecting a timeline item then mousing over or tapping the red box.
### Object Proportions
`min_ratio` and `max_ratio` values are compared against a given detected object's width/height ratio (in pixels). If the ratio is outside this range, the object will be ignored as a false positive. This allows objects that are proportionally too short-and-wide (higher ratio) or too tall-and-narrow (smaller ratio) to be ignored.
:::info
Conceptually, a ratio of 1 is a square, 0.5 is a "tall skinny" box, and 2 is a "wide flat" box. If `min_ratio` is 1.0, any object that is taller than it is wide will be ignored. Similarly, if `max_ratio` is 1.0, then any object that is wider than it is tall will be ignored.
:::
## Other Tools
### Zones
[Required zones](/configuration/zones.md) can be a great tool to reduce false positives that may be detected in the sky or other areas that are not of interest. The required zones will only create events for objects that enter the zone.
### Object Masks
[Object Filter Masks](/configuration/masks) are a last resort but can be useful when false positives are in the relatively same place but can not be filtered due to their size or shape.

10
docs/docs/guides/getting_started.md
View File

@@ -327,9 +327,15 @@ cameras:
By default, Frigate will retain snapshots of all events for 10 days. The full set of options for snapshots can be found [here](../configuration/index.md#full-configuration-reference).
### Step 7: Follow up guides
### Step 7: Complete config
Now that you have a working install, you can use the following guides for additional features:
At this point you have a complete config with basic functionality. You can see the [full config reference](../configuration/reference.md) for a complete list of configuration options.
### Follow up
Now that you have a working install, you can use the following documentation for additional features:
1. [Configuring go2rtc](configuring_go2rtc.md) - Additional live view options and RTSP relay
2. [Home Assistant Integration](../integrations/home-assistant.md) - Integrate with Home Assistant
3. [Masks](../configuration/masks.md)
4. [Zones](../configuration/zones.md)

5
docs/docs/guides/ha_network_storage.md
View File

@@ -1,9 +1,9 @@
---
id: ha_network_storage
title: HA Network Storage
title: Home Assistant network storage
---
As of HomeAsisstant Core 2023.6, Network Mounted Storage is supported for addons.
As of Home Asisstant Core 2023.6, Network Mounted Storage is supported for addons.
## Setting Up Remote Storage For Frigate
@@ -16,6 +16,7 @@ As of HomeAsisstant Core 2023.6, Network Mounted Storage is supported for addons
1. Stop the Frigate addon
2. Update your [config](configuration/index.md) so the DB is stored in the /config directory by adding:
```yaml
database:
path: /config/frigate.db

71
docs/docs/guides/parked_cars.md Normal file
View File

@@ -0,0 +1,71 @@
---
id: parked_cars
title: Handling parked cars
---
:::tip
This is an area targeted for improvement in future releases.
:::
Many people use Frigate to detect cars entering their driveway, and they often run into an issue with repeated events of parked cars and/or long running events after the car parks. This can cause Frigate to store more video than desired.
:::caution
It is not recommended to use motion masks to try and eliminate parked cars in your driveway. Motion masks are designed to prevent motion from triggering object detection and will not prevent objects from being detected in the area if motion is detected outside of the motion mask.
:::
## Repeated events of parked cars
To only be notified of cars that enter your driveway from the street, you can create multiple zones that cover your driveway. For cars, you would only notify if `entered_zones` from the events MQTT topic has contains the entrance zone.
See [this example](../configuration/zones.md#restricting-zones-to-specific-objects) from the Zones documentation to see how to restrict zones to certain object types.
![Driveway Zones](/img/driveway_zones-min.png)
To limit snapshots and events, you can list the zone for the entrance of your driveway under `required_zones` in your configuration file.
```yaml
camera:
record:
events:
required_zones:
- zone_2
zones:
zone_1:
coordinates: ... (parking area)
zone_2:
coordinates: ... (entrance to driveway)
```
This will only save events if the car entered the entrance zone at any point.
## Long running events
There are a few recommended approaches to avoid excessive storage use due to parked cars. These can be used in combination.
### 1. Use `motion` or `active_objects` mode for event recordings
Leverages [recording settings](../configuration/record.md#what-do-the-different-retain-modes-mean) to avoid excess storage use.
#### Advantages of this approach
For users using `motion` mode for continuous recording, this successfully avoids extra video from being stored for cars parked in view because all motion video is already being saved.
#### Limitations of this approach
For users that only want to record motion during events, long running events will result in all motion being stored as long as the car is in view. You can mitigate this further by using the `active_objects` mode for event recordings, but that may result less video being retained than is desired.
### 2. Use an object mask to prevent detections in the parking zone
Leverages [object filter masks](../configuration/masks.md#object-filter-masks) to prevent detections of cars parked in the driveway.
#### Advantages of this approach
Using this approach, you will get two separate events for when a car enters the driveway, parks in the parking zone, and then later leaves the zone. Using an object mask will ensure that cars parked in the parking zone are not detected and confused with cars driving by on the street as well.
#### Limitations of this approach
This approach will only work for cars that park in the parking zone. Cars that park in other areas will still be tracked as long as they are in view. This will also prevent zone sensors from telling you if a car is parked in the parking zone from working.

43
docs/docs/guides/stationary_objects.md
View File

@@ -1,43 +0,0 @@
---
id: stationary_objects
title: Avoiding stationary objects
---
Many people use Frigate to detect cars entering their driveway, and they often run into an issue with repeated notifications or events of a parked car being repeatedly detected over the course of multiple days (for example if the car is lost at night and detected again the following morning).
You can use zones to restrict events and notifications to objects that have entered specific areas.
:::caution
It is not recommended to use masks to try and eliminate parked cars in your driveway. Masks are designed to prevent motion from triggering object detection and/or to indicate areas that are guaranteed false positives.
Frigate is designed to track objects as they move and over-masking can prevent it from knowing that an object in the current frame is the same as the previous frame. You want Frigate to detect objects everywhere and configure your events and alerts to be based on the location of the object with zones.
:::
:::info
Once a vehicle crosses the entrance into the parking area, that event will stay `In Progress` until it is no longer seen in the frame. Frigate is designed to have an event last as long as an object is visible in the frame, an event being `In Progress` does not mean the event is being constantly recorded. You can define the recording behavior by adjusting the [recording retention settings](../configuration/record.md).
:::
To only be notified of cars that enter your driveway from the street, you could create multiple zones that cover your driveway. For cars, you would only notify if `entered_zones` from the events MQTT topic has more than 1 zone.
See [this example](../configuration/zones.md#restricting-zones-to-specific-objects) from the Zones documentation to see how to restrict zones to certain object types.
![Driveway Zones](/img/driveway_zones-min.png)
To limit snapshots and events, you can list the zone for the entrance of your driveway under `required_zones` in your configuration file. Example below.
```yaml
camera:
record:
events:
required_zones:
- zone_2
zones:
zone_1:
coordinates: ... (parking area)
zone_2:
coordinates: ... (entrance to driveway)
```