Atlas Knowledge Base
Dashboard
Image Classifier Options

Image Classifier Options


The Image Classifier is configured in three layers. Service settings under imageclassifier control the service as a whole. Profiles name a model and its detection settings. Groups apply a profile to a set of cameras, add detection areas, and override profile settings where a camera set needs different behaviour. Set overrides in sbn-media.local.yaml, view the current values with ./sbn-media config view -a imageclassifier, and apply changes with ./sbn-media config reload.

How the layers combine

A camera is assigned a classifier group in its device configuration. When the camera is classified, the group's profile is loaded and every setting the group sets replaces the profile's value. Per-class settings (confidence thresholds, motion velocities, class priorities) merge key by key, so a group can change one class and keep the rest from the profile. A camera with no group uses the service settings.

Groups can also be edited from SBN Anywhere with Edit group in the device configuration window. Saved edits stay a draft until published; a published edit is layered on top of the group in the configuration file and takes effect without a reload.

Service settings

Turning classification on

SettingDefaultDescription
imageclassifier.enabledfalseClassify attached streams automatically. On-request classification works regardless.
imageclassifier.devices(none)Device types to attach to automatically, for example camera and webrtc. An empty list turns automatic attachment off.
imageclassifier.maxConcurrent4Streams one instance classifies at once before other instances take the rest. 0 means unlimited.
imageclassifier.activeGroups(all)Groups this instance handles for on-request classification. Empty handles every group.

Model and runtime

SettingDefaultDescription
imageclassifier.model.path./models/yolov8n.onnxDetection model used when no profile applies.
imageclassifier.model.numClasses80Number of classes the model detects.
imageclassifier.model.classNames(COCO names)Custom class names for a custom-trained model.
imageclassifier.backendonnxInference backend.
imageclassifier.execution.providercpuWhere inference runs: cpu, cuda (NVIDIA GPU), tensorrt, openvino, coreml or directml.
imageclassifier.install.dir./modelsWhere the AI runtime and downloaded models are kept.
imageclassifier.models(built-in list)Models available to ./sbn-media classifier setup.
imageclassifier.model.ftp.*(set by installer)Server, credentials and path for downloading prepared models.

Detection

SettingDefaultDescription
imageclassifier.confidence.threshold0.5Minimum confidence (0-1) for a detection to be reported.
imageclassifier.classes(all)Object classes to report. Empty reports every class the model knows.
imageclassifier.nmsThreshold0.45Overlap (0-1) above which two boxes for the same class are merged into one.
imageclassifier.frame.interval5Classify every Nth frame. 1 classifies every frame.
imageclassifier.frame.ttl5mHow long frame images from video classification are kept.
imageclassifier.trackingfalseTrack objects across frames, giving each a stable identity and direction of movement.
imageclassifier.defaultMotionVelocity(none)Speed (0-1 of the frame per frame) above which a tracked object counts as moving.
imageclassifier.publish.changes_onlyfalsePublish results only when the detections change.
imageclassifier.publish.change_iou_threshold0.5Box overlap (0-1) at which two detections count as the same object for change detection.

Always-on classification

Cameras with history enabled can be classified continuously, with or without a viewer.

SettingDefaultDescription
imageclassifier.alwaysOn.enabledfalseClassify history-enabled cameras with no viewer attached.
imageclassifier.alwaysOn.maxWorkers2Cameras classified this way per instance. They count within maxConcurrent.
imageclassifier.alwaysOn.frameInterval25Classify every Nth frame on these cameras.

Alarm classification

These settings classify the video for an alarm, for cameras whose alarm binding has analytics enabled.

SettingDefaultDescription
imageclassifier.mediaReady.enabledfalseClassify the clip stored for the alarm once it is available.
imageclassifier.mediaReady.tenants(none)Tenants whose stored alarm clips this instance handles.
imageclassifier.alarmStreams.max4Alarm video spans one instance classifies at once.
imageclassifier.alarmSignals.enabledfalseSend a signal to the SBN alarm log for each final classification of an alarm, on the camera's bound alarm account and zone.
imageclassifier.alarmSignals.codesperson: BAAlarm code for each detected class, as class and code pairs.
imageclassifier.alarmSignals.defaultCodeUAAlarm code for a detected class with no entry in codes.
imageclassifier.alarmSignals.failedCodeUXAlarm code sent when a classification fails or is inconclusive.
imageclassifier.alarmSignals.describedCodeUXAlarm code of the alarm-log entry that carries an AI description. The entry goes to the camera's bound alarm account and zone.
imageclassifier.alarmSignals.latchTTL24hHow long an alarm is remembered as signalled; a repeated delivery within this time sends nothing.

Detection events

SettingDefaultDescription
imageclassifier.detectionEvents.enabledfalsePublish one detection event per tracked object that passes its group's filters.
imageclassifier.detectionEvents.pictures.enabledfalsePublish a set of pictures for each reported object when it leaves view. Enable only after every recorder and API proxy runs a release that supports it.
imageclassifier.detectionEvents.pictures.max8Pictures per object, 1 to 8.

Re-identification

Re-identification attaches an embedding to each object's best picture, which powers the cross-camera "find similar" feature. Install an embedder first, for example ./sbn-media classifier setup dinov2-small.

SettingDefaultDescription
imageclassifier.reid.models(none)Named embedder models, each a name and a model file path.
imageclassifier.reid.default.model(none)Embedder used when a group does not choose one.
imageclassifier.reid.model.path(none)Single embedder model file, for sites that do not use reid.models.

Camera analytics

SettingDefaultDescription
imageclassifier.onvif.producer.enabledfalseReport detections made by the camera itself (ONVIF analytics) alongside the classifier's own.
imageclassifier.onvif.metadata.logoffDiagnostic logging of the camera's analytics: off, detections, all or raw. all writes thousands of lines an hour.

Profile settings

Profiles are defined under imageclassifier.profiles, each under its own name. A profile names a model and the detection settings that go with it.

Model

SettingDefaultDescription
modelPath(required)Model file.
modelType(required)Model family: yolov8, yolov11, yolox, rfdetr or dfine.
backendonnxInference backend.
executionProvider(service setting)Where inference runs for this profile.
inputWidth, inputHeight640Model input size in pixels.
numClasses80Number of classes the model detects.
classNames(COCO names)Custom class names.

Detection

SettingDefaultDescription
confidenceThreshold(required)Minimum confidence (0-1) for a detection to be reported.
classConfidenceThresholds(none)Per-class thresholds, for example person: 0.3.
classes(all)Object classes to report.
nmsThreshold0.45Overlap at which two boxes of the same class are merged.
preprocessing(none)Image stages applied before detection. clahe improves contrast in dark or washed-out scenes.
claheClipLimit2.0Strength of the clahe stage.
deepDetectionfalseSplit moving regions into overlapping tiles and classify each tile, which finds small and distant objects at extra CPU cost.
deepDetectionOverlap0.25Overlap between tiles (0-1).
deepDetectionPadding0.1Margin added around each moving region (0-1).

Frame rate and motion

SettingDefaultDescription
frameInterval(service setting)Classify every Nth frame.
adaptiveIntervalfalseClassify more often while objects are present and less often when the scene is idle.
intervalMin2Frame interval while objects are present.
intervalMax30Frame interval while the scene is idle.
motionGatefalseSkip classification of frames that show no change from the previous one.
motionThreshold0.01Amount of change (0-1) that counts as motion.
motionDownsample64Grid size used to compare frames. Smaller is faster and less sensitive.

Tracking and reporting

SettingDefaultDescription
tracking(service setting)Track objects across frames for stable identities and direction of movement.
minHitsToConfirm2Consecutive detections before a tracked object is reported.
defaultMotionVelocity(service setting)Speed above which a tracked object counts as moving.
classMotionVelocities(none)Per-class speeds, for example person: 0.005 and car: 0.02.
publishChangesOnly(service setting)Publish results only when the detections change.
changeIoUThreshold(service setting)Box overlap at which two detections count as the same object.
priority50Scheduling priority, 0-99. Higher priority cameras are classified first when the host is overloaded.
classPriorities(none)Display order of classes. A lower number is shown first.
staticPriorityPenalty0Added to the display priority of objects that are not moving.
describeClasses(all)Classes that trigger an automatic AI description of the detection. Empty describes every detection.

Group settings

Groups are defined under imageclassifier.groups, each under its own name.

SettingDescription
profileName of the profile the group uses. Required.
descriptionFree-text description of the group.
detectionAreasAreas of the frame to watch or ignore (see below). A camera's own saved areas take precedence.
includeStaticDetectionsReport objects that are not moving. Off by default: with tracking on, only moving objects are reported.
alwaysIncludeClassesClasses reported even when not moving, for example person.
stopOnClassStop classifying an alarm clip at the first frame in the alarm window that contains this class. Empty classifies every frame.
reidDefaultModelEmbedder for this group's cameras. Empty uses imageclassifier.reid.default.model.
reidModelByClassEmbedder per class. An empty name turns re-identification off for that class.
reidDefaultThresholdsMatch cut-offs for "find similar": badge (default 0.15) for the badge and panel (default 0.30) for the matches panel. Lower is stricter.
reidThresholdsByClassMatch cut-offs per class.
describeAI description of this group's alarm clips (see AI description settings).

A group can also set any of these profile settings to override them: confidenceThreshold, classConfidenceThresholds, frameInterval, adaptiveInterval, intervalMin, intervalMax, motionGate, motionThreshold, motionDownsample, publishChangesOnly, changeIoUThreshold, tracking, minHitsToConfirm, deepDetection, deepDetectionOverlap, deepDetectionPadding, preprocessing, claheClipLimit, priority, classPriorities, staticPriorityPenalty, defaultMotionVelocity, classMotionVelocities and describeClasses.

AI description settings

The describe block of a group sets how its alarm clips are described. Which detected classes trigger a description is set by describeClasses.

FieldDefaultDescription
enabledfalseDescribe this group's classified alarm clips.
imagecropcrop sends up to three crops of the detected objects from the best frame. scene sends the whole frame.
prompt(AI LLM default)Instructions given to the model with the image.
provider(AI LLM default)AI provider used for the description.
model(AI LLM default)Model used for the description.

Detection areas

Each area is a polygon of at least three points, in coordinates from 0 to 1 across the frame (0,0 is the top-left corner).

FieldDescription
nameName of the area.
pointsCorners of the polygon, each with x and y. The last point joins back to the first.
modeinclude (default) reports detections inside the area. exclude ignores detections inside it.
classesClasses the area applies to. Empty applies to every class.

Example

imageclassifier:
  enabled: true
  devices: ["camera"]
  tracking: true
  profiles:
    vehicles:
      modelPath: ./models/yolov8s.onnx
      modelType: yolov8
      confidenceThreshold: 0.6
      frameInterval: 3
      classes: ["car", "truck", "bus", "motorcycle"]
  groups:
    parking-lot:
      profile: vehicles
      description: Parking lot entry and exit
      motionGate: true
      describe:
        enabled: true
        image: scene
      classConfidenceThresholds:
        truck: 0.5
      detectionAreas:
        - name: entry-lane
          points:
            - { x: 0.0, y: 0.4 }
            - { x: 0.3, y: 0.4 }
            - { x: 0.3, y: 1.0 }
            - { x: 0.0, y: 1.0 }
        - name: road
          mode: exclude
          points:
            - { x: 0.0, y: 0.0 }
            - { x: 1.0, y: 0.0 }
            - { x: 1.0, y: 0.2 }
            - { x: 0.0, y: 0.2 }


Was this helpful?