Detection zones limit where on a camera's image detections count. Use them to ignore trees, roads or the sky, or to record only when something is at a doorway or in a driveway.
LightNVR applies zones itself after every detection, whatever produced it: an external API (light-object-detect, DOODS2), embedded SOD, the in-process LiteRT engine, or ONVIF camera events that carry boxes. The detector never sees the zones.
- No enabled zones on a stream: every detection counts.
- One or more enabled zones: a detection counts only if the centre of its bounding box is inside an enabled zone whose class filter and minimum confidence it also passes. Zones are checked in order and the first match wins; its ID is stored with the detection, and Investigation can filter by it.
- Class filter (
filter_classes): comma-separated labels such asperson,car. Empty accepts every class. - Minimum confidence (
min_confidence, 0.0-1.0):0accepts any confidence.
Each stream can have up to 16 zones of 3 to 32 points.
- Open Streams, and Edit the stream.
- Turn on Enable AI Detection-Based Recording.
- Under Detection Zones, click Configure Zones (or Edit Zones).
- Click Draw Zone, then click points on the snapshot. Click Complete Zone when the polygon is closed. If no snapshot is available you can still draw on a grid.
- Use Select to pick a zone and change its name, colour or Enabled switch, and Delete to remove one.
- Click Save Zones.
The editor sets a zone's shape, name, colour and enabled state. Set class filters and minimum confidence through the API (below).
CREATE TABLE detection_zones (
id TEXT PRIMARY KEY,
stream_name TEXT NOT NULL,
name TEXT NOT NULL,
enabled INTEGER DEFAULT 1,
color TEXT DEFAULT '#3b82f6',
polygon TEXT NOT NULL, -- JSON array of points
filter_classes TEXT DEFAULT '',
min_confidence REAL DEFAULT 0.0,
created_at INTEGER NOT NULL,
updated_at INTEGER NOT NULL,
FOREIGN KEY (stream_name) REFERENCES streams(name) ON DELETE CASCADE
);Polygons are stored as JSON arrays of normalized coordinates (0.0 - 1.0):
[
{"x": 0.0, "y": 0.0},
{"x": 0.5, "y": 0.0},
{"x": 0.5, "y": 1.0},
{"x": 0.0, "y": 1.0}
]GET /api/streams/{stream_name}/zonesResponse:
{
"zones": [
{
"id": "zone_1234567890",
"stream_name": "front_door",
"name": "Entrance",
"enabled": true,
"color": "#3b82f6",
"polygon": [
{"x": 0.0, "y": 0.0},
{"x": 0.5, "y": 0.0},
{"x": 0.5, "y": 1.0},
{"x": 0.0, "y": 1.0}
],
"filter_classes": "person",
"min_confidence": 0.7
}
]
}POST /api/streams/{stream_name}/zones
Content-Type: application/json
{
"zones": [
{
"id": "zone_1234567890",
"name": "Entrance",
"enabled": true,
"color": "#3b82f6",
"polygon": [
{"x": 0.0, "y": 0.0},
{"x": 0.5, "y": 0.0},
{"x": 0.5, "y": 1.0},
{"x": 0.0, "y": 1.0}
],
"filter_classes": "person",
"min_confidence": 0.7
}
]
}Response:
{
"success": true,
"message": "Zones saved successfully",
"count": 1
}DELETE /api/streams/{stream_name}/zonesMonitor only the entrance area for persons:
{
"id": "entrance_zone",
"name": "Front Entrance",
"enabled": true,
"color": "#3b82f6",
"polygon": [
{"x": 0.2, "y": 0.3},
{"x": 0.8, "y": 0.3},
{"x": 0.8, "y": 0.9},
{"x": 0.2, "y": 0.9}
],
"filter_classes": "person",
"min_confidence": 0.75
}Monitor parking lot for vehicles:
{
"id": "parking_zone",
"name": "Parking Lot",
"enabled": true,
"color": "#10b981",
"polygon": [
{"x": 0.0, "y": 0.5},
{"x": 1.0, "y": 0.5},
{"x": 1.0, "y": 1.0},
{"x": 0.0, "y": 1.0}
],
"filter_classes": "car,truck,motorcycle",
"min_confidence": 0.6
}Combine multiple zones for comprehensive monitoring:
{
"zones": [
{
"id": "entrance",
"name": "Entrance",
"enabled": true,
"color": "#3b82f6",
"polygon": [...],
"filter_classes": "person",
"min_confidence": 0.75
},
{
"id": "driveway",
"name": "Driveway",
"enabled": true,
"color": "#10b981",
"polygon": [...],
"filter_classes": "car,truck,person",
"min_confidence": 0.65
},
{
"id": "backyard",
"name": "Backyard",
"enabled": false,
"color": "#f59e0b",
"polygon": [...],
"filter_classes": "",
"min_confidence": 0.5
}
]
}- Start with simple zones: Begin with one or two zones and refine as needed
- Use appropriate confidence thresholds: Higher for critical areas, lower for general monitoring
- Order overlapping zones deliberately: a detection is attributed to the first matching zone
- Test your zones: Use the live preview to verify zone coverage
- Name zones descriptively: Makes it easier to identify in logs and alerts
- Disable unused zones: Rather than deleting, disable zones you might need later
- Ensure the stream has a valid snapshot available
- Check browser console for errors
- Verify the stream is running
- Verify zones are enabled
- Check zone polygon coordinates are valid (0.0 - 1.0)
- Remember that only the bounding-box centre is tested
- Check class names match the detector's labels exactly (
person, notPerson) - Run with
log_level = 3; each rejection is logged with its reason
- Reduce the number of zones (the limit is 16 per stream)
- Simplify polygon shapes (fewer points)
- Use larger zones rather than many small ones