Vision Field Notes

Managing Per-Camera Configuration at Scale

With five cameras, settings live comfortably in one file, edited by hand. With five hundred, every camera has its own zones, lines, thresholds, schedules, stream address and quirks, and the settings become the largest and most fragile part of the system. A typo in one camera's zone silently disables an alert. A threshold changed "temporarily" for one camera is still there a year later and nobody remembers why.

This article describes a way of organising per-camera configuration that stays manageable as the number of cameras grows.

What configuration includes

For each camera, typically:

Most of these are the same for most cameras. That is the key to keeping them manageable.

Layer defaults and overrides

Define settings at a few levels, and let each level override only what it needs:

Four boxes joined by arrows: global defaults (model, frame rate, person and helmet thresholds, cooldown, time zone from site), site (name, time zone Asia/Singapore, a night schedule), camera (camera ID, substream, zones, a higher person threshold with a comment about glare at dusk), and the effective computed configuration combining them.
A diagram with example values. A camera file holds only what is different about that camera, ideally with the reason, and the effective settings are computed and logged.

A camera file then contains a handful of lines: its geometry and whatever genuinely differs. When you change a default, every camera that does not override it follows. When you look at a camera file, every line in it is there for a reason.

Write the reason next to each override. person_conf: 0.55 # glare from loading-bay door at dusk, see ticket 112 is maintainable. A bare 0.55 is not.

Compute and log the effective settings

The pipeline should merge the layers at start-up, produce the effective configuration for each camera, and log it (or save it next to the logs). When someone asks "what threshold was camera 7 using last Tuesday?", the answer is in the log, not in a reconstruction from four files and their histories.

Provide a command that prints the effective configuration for a camera. It is the first thing anyone debugging a camera should run.

Validate before it runs

Configuration errors should fail loudly at load time, not silently at 3 a.m. Define a schema and validate every file against it:

from pydantic import BaseModel, Field, field_validator

class Zone(BaseModel):
    name: str
    points: list[tuple[float, float]]           # normalised 0..1 coordinates

    @field_validator("points")
    @classmethod
    def valid_polygon(cls, pts):
        if len(pts) < 3:
            raise ValueError("a zone needs at least 3 points")
        if not all(0 <= x <= 1 and 0 <= y <= 1 for x, y in pts):
            raise ValueError("zone points must be normalised to 0..1")
        return pts

class Camera(BaseModel):
    id: str
    stream: str
    zones: list[Zone] = []
    person_conf: float = Field(0.45, ge=0.05, le=0.95)
    fps: float = Field(5, gt=0, le=30)

Validation catches typos in keys, thresholds outside a sensible range, zones with too few points, unknown rule names, and time zones that do not exist. Run it in CI on every change, and again on the device before applying a new configuration.

Also check cross-references: every rule refers to a zone that exists; every camera's site exists; no two cameras share an ID.

Store geometry in normalised coordinates

Store zone and line points as fractions of the frame width and height (0 to 1), not as pixels. Then switching a camera from the main stream to the substream, or the camera's resolution being changed, does not move every zone. Convert to pixels when frames arrive, using the actual frame size.

Keep the reference image each zone was drawn on, with the zones overlaid. When a camera is moved or replaced, compare the new view with that image to see whether the zones still fit. A view-shift check can flag it automatically.

Version control everything

Keep configuration in Git, separate from the code but versioned the same way:

Keep secrets out of it. Stream credentials and API keys belong in a secrets store or in device-local files with restricted permissions, referenced from the configuration by name.

Changes made in a UI

Operators often need to adjust zones or schedules through a web interface. That is fine, as long as the interface writes to the same versioned store, records who changed what, and validates before saving. A configuration that exists only in a database edited by hand from a UI loses its history and its review.

Watch for drift

Over time, overrides accumulate. Every few months, list all camera-level overrides and ask whether each one is still needed. A threshold raised to handle glare in winter may be wrong in summer. A mask added during construction work may now hide a real area. Overrides with a date or a ticket reference are much easier to review.

Also detect configuration that no longer matches reality: a stream that now delivers a different resolution or frame rate than the configuration expects, or a camera whose view has shifted from the reference. Both are cheap to check at start-up and on a schedule. See Metrics and Logging for a Vision Service.

Checklist

Next steps: Scaling Video Analytics to Hundreds of Camera Streams and Handover Documentation for a Computer Vision System.