Object detection and clips

Huntress can look at camera pictures and recognise people, vehicles and animals. When one appears it records an event that rules can act on, draws boxes on the picture so you see what was found and where, and can save a short video clip around it. The analysis runs on your own server or edge. No picture leaves it.

Switching it on#

1. Open the camera's settings, choose a snapshot interval in the Camera section and save. A live camera is analysed through its snapshots.
2. In Object detection, switch on Detect objects, choose how often to analyse and what to look for, and save. Detection is off for every camera until you do.
3. Other camera sensors (pictures pushed over HTTP, e-mail or MQTT) are analysed as the pictures arrive, at most one per interval.
4. Add a rule with the Object detected condition (for example: a person, outside business hours, in the Gate region) to open an incident or send a notification.

What it detects#

The model is RF-DETR Small, quantised to 8-bit integers, running on ONNX Runtime. It is trained on the COCO dataset and Huntress groups what it knows into three kinds; nothing else is detected.

People and vehicles are selected at first. A bird is an animal everywhere: in events, stored detections, overlays and rules. A vehicle first taken for a car and then for a truck is still the same vehicle.

Confidence and the quiet period#

The minimum confidence filters out uncertain detections: a lower value finds more objects and raises more false alarms. When a selected kind of object appears Huntress records one Object detected event (severity High when it is a person). When that kind of object has not been seen for the quiet period (“counts as gone after”) it records Object cleared, and only then can the same kind raise a new event. Rules see detected events; cleared events end the incident of a rule that opts in.

Regions#

Regions limit detection to parts of the picture such as a gate, a driveway or the ground in front of a fence. Draw them on the camera's newest snapshot (Draw region and click the corners, or Add rectangle and drag its corners) and name each one so rules can refer to it. An object counts when its feet, the bottom centre of its box, are inside a region: a person walking past behind the fence does not count when the region covers only the ground in front of it. Without regions the whole picture counts. A camera can have up to 8 regions of 3 to 32 corners.

Where it runs#

With Automatic, a camera connected through a Huntress Edge is analysed on the edge when the edge reports that it can, which spares the server's processor; otherwise the server analyses the snapshots it receives. Choose On this server or On the camera's edge to fix the place. The camera's settings page shows the actual interval, the model, where it runs and how long one analysis takes.

• Speed. On a modern laptop-class processor one analysis takes roughly 0.1 to 0.3 seconds. Memory use is about 75 MB more.
• CPU cap. Detection runs on one low-priority thread and may use at most Detection:MaxBusyPercent (50 by default) of a processor. On a busy server the actual interval is longer than the one you chose; Detection:MinIntervalSeconds (2 by default) is the shortest.
• CPU only. Release builds run on the CPU. A GPU needs an ONNX Runtime build for your GPU and driver, loaded through Detection:NativeLibraryPath; the shipped runtime refuses a GPU library of another minor version and falls back to the CPU with a reason in the log.
• Not yet verified on a Raspberry Pi edge or on a GPU. Test those on your own hardware before depending on them.

Seeing the results#

Boxes and labels such as “person 92%” are drawn over the live tile, over archived snapshots in playback, on the camera's page and over event pictures. Show detections hides or shows them and your browser remembers the choice. On the camera's page, snapshots with detections are marked on the strip and Only with detections narrows it to them. An Object detected event shows its evidence picture, the objects with their confidence and the regions they were in.

Rules#

The Object detected condition is true only for Object detected events. Pick the groups, a minimum confidence and optionally regions. Object cleared never makes it true; it can resolve the incident of a rule that watches that kind of object. The rule editor's Test tab replays stored detections through the unsaved rule.

Video clips#

Switch on Record a video clip on detection next to detection and set the pre-roll (0 to 30 seconds) and post-roll (5 to 300 seconds). When an object is detected, Huntress saves an MP4 around the moment: the stream is copied, never re-encoded, and audio is never stored. Further detections while a clip is recording extend it, up to Clips:MaxClipSeconds (120 seconds by default).

• The ring. A camera with clips on keeps a short ring of recent video in memory (up to Clips:MaxRingMegabytes, 64 MB by default, per camera the server captures itself). That is where the pre-roll comes from. A camera on an edge keeps its ring on the edge and uploads only the clip.
• Keyframes. A clip starts at a keyframe, so it can begin up to one keyframe interval early; use a keyframe interval of about 2 seconds or less. A restart of the server loses uploads that were in progress.
• Storage. Clips are stored under the data directory in clips/. The oldest are deleted above Clips:MaxTotalGigabytes (20 by default), after Retention:ClipDays (30 days), and no new clip is started below Clips:MinFreeDiskMegabytes of free disk (2,048 by default). At most 8 clips are written at once.
• Playback. An Object detected event shows the clip in a native video player with its evidence picture as the poster; the All Events list marks events that have a clip. H.265 clips play in some browsers only.
• Backups. --backup never includes the clips directory.

Privacy#