Skip to content

Spot Color Detector

The Spot Color Detector analyzes video frames to detect specific colors within defined circular or rectangular regions. When a color changes, it triggers AXIS events that can be used in rules or captured by Flow nodes.

Overview

Define circular "spots" or rectangular regions on the video feed and configure a color palette. The system continuously analyzes each region and detects which palette color is currently visible. When the color changes, an AXIS event is fired.

Use Cases:

  • Traffic light detection (red/yellow/green states)
  • Status indicator monitoring (LED colors on equipment)
  • Industrial process monitoring (color-coded stages)
  • Presence detection based on color changes

Profiles

Each Spot Color Detector instance can run up to 4 independent profiles in parallel. A profile owns its own video channel, resolution, framerate, analysis interval, preview configuration, trigger set (circles + rectangles), color palette and color rules. Profiles are useful when a device has multiple sensors/streams and each needs to be monitored separately.

The profile selector is the chip row at the top of the configuration column:

Action How
Switch profile Click any profile chip
Add profile Click the + icon next to the chips (max 4)
Remove profile Click the × on a profile chip (the last remaining profile cannot be removed)
Rename / change channel Adjust the Stream panel while the profile is active, then Save

When a profile is added or switched the live overlay is cleared immediately and the WebSocket reconnects to the new profile's emitter — you do not see the previous profile's circles/rects briefly during the switch.

Per-profile events are described in the Events section below.

Getting Started

  1. Navigate to Spot Color Detector from the feature menu
  2. The live video preview loads automatically for the active profile
  3. (Optional) Click + in the profile bar to add another profile bound to a different channel
  4. Click Add Circle or Add Rect to create a detection region
  5. Position and resize the region over the target area
  6. Configure the color palette with expected colors
  7. Start the feature to begin detection

Configuration

Video Settings (per profile)

Setting Description
Video Channel Select the video channel for this profile (default: 1)
Resolution Analysis resolution (lower = faster processing). The dropdown lists only resolutions reported by the selected channel
Framerate Analysis framerate
Analysis Interval Minimum time between two analyses (ms)
Hysteresis Threshold Color distance threshold to prevent flickering (0-100). Set to 0 to disable hysteresis and always match the nearest palette color

Circle Triggers

Each circle defines a circular detection region:

Property Description
Name Unique identifier for the circle (used in events)
Position X/Y center coordinates (drag to move)
Radius Detection area size (drag corner to resize)

Adding Circles:

  1. Click Add Circle button
  2. Enter a name for the circle (e.g., "traffic_light_1")
  3. Drag the circle to position it over the target
  4. Resize using the corner handle

Editing Circles:

  • Click the pencil icon to rename
  • Click the trash icon to delete
  • Drag to reposition
  • Drag the resize handle to change size

Rectangle Triggers

Rectangles provide flexible detection regions that can handle lens distortion better than circles.

Property Description
Name Unique identifier for the rectangle (used in events)
Position Top-left corner coordinates (drag to move)
Size Width and height (drag corner to resize)

Adding Rectangles:

  1. Click Add Rectangle button
  2. Enter a name for the rectangle
  3. Drag to position it over the target
  4. Resize by dragging the corners

When to Use Rectangles:

  • Detection areas near the edges of the image (where lens distortion is strongest)
  • Rectangular indicators or displays
  • When you need to match the shape of the target area precisely

Color Palette

The palette defines which colors the system recognizes. Each profile has its own palette so two profiles watching different scenes can use different vocabularies.

Default Colors: - Basic: Red, Green, Blue, Yellow, Orange, Purple, Cyan, Magenta, White, Black, Gray - Traffic: Traffic Red, Traffic Yellow, Traffic Green, Off/Dark

Managing Colors:

Action How To
Add Color Click "Add Color", pick a color and enter a name
Add Detected Click "Add to Palette" on a circle's detected color
Remove Color Click the X on a color chip
Reset Palette Click "Reset" to restore defaults

A palette color cannot be deleted while a Color Rule references it — remove or edit the rule first.

Color Rules

Color Rules turn "this region is currently showing one of these colors" into AXIS events that the device's rule engine can act on directly.

Each rule is:

  • Name — letters, spaces, hyphen and underscore only. Becomes the event nice name.
  • Trigger — one circle or one rect on this profile.
  • Colors — up to 4 palette colors that should activate the rule.

Up to 12 rules per profile. The same circle or rect can be referenced by multiple rules — for example "Stop" on red and "Go" on green for the same traffic light.

Why a rule and not just the per-region event? The Axis rule engine cannot match on a string field like color_name == "Red". A Color Rule packages "this region + these colors" into events with bool fields, which the rule engine can condition on.

Each rule produces two events (see Events below): a persistent state event and a one-shot trigger event.

A circle or rect cannot be deleted while a Color Rule references it — remove or repoint the rule first.

How It Works

Color Detection

  1. The system captures video frames at the configured resolution
  2. For each circle, pixels within the boundary are sampled
  3. The dominant color (average RGB) is calculated
  4. This color is matched to the nearest palette color
  5. If the color changed beyond the hysteresis threshold, an event fires

Hysteresis

The hysteresis threshold prevents rapid flickering between similar colors. The value measures how much better a new live measurement must match a different palette color before the state switches:

  • 0: Hysteresis disabled — always match the nearest palette color (no stickiness)
  • Low value (10-20): More sensitive, may flicker in variable lighting
  • High value (50-100): More stable, requires a clearly better match before switching
  • Default (30): Balanced for most scenarios

The threshold is compared in Euclidean RGB color space against the difference between the current match and candidate matches — not between palette colors themselves.

Processing Time

The UI displays processing time per frame:

  • Green: Under budget, system running smoothly
  • Red: Over budget, consider reducing resolution or circle count

Events

Individual Trigger Events

Each circle and rectangle generates an AXIS event when its color changes:

Event Name: {trigger_name}_state_{profile_name}

Event Data:

Field Description
profile_name Name of the profile that emitted the event
trigger_name Name of the circle or rectangle
color_name Matched palette color name
confidence Match confidence (0-1)

Color Rule Events

Each Color Rule registers two events. Both are prefixed with Spot Color - in the device event browser.

Event Name Stateless Description
rule_{event_key}_{profile_name} no Persistent state event. One bool per rule color (key = sanitized color name) plus a reserved unknown bool. Exactly one is true at a time.
rule_{event_key}_trigger_{profile_name} yes Fired the moment the matched bucket changes — entering one of the rule's colors, flipping between them, or going into unknown. Same bool fields as the state event.

event_key is the rule name lowercased with spaces stripped.

Use the state event when you want something to stay on while the color is showing (e.g. close an IO relay). Use the trigger event when you want a one-shot reaction the moment the color changes (e.g. send a notification).

Combined Events

Combined events fire whenever any trigger changes state, providing all trigger states in one event:

Event Name Description
all_circles_state_{profile_name} State of all circle triggers in the profile
all_rects_state_{profile_name} State of all rectangle triggers in the profile

Combined Event Data:

Each combined event includes individual color fields for every trigger plus the profile identifier:

Field Description
profile_name Name of the profile that emitted the event
{trigger_name}_color Current color for each trigger
{trigger_name}_confidence Match confidence for each trigger

This allows you to capture the state of all triggers in a single event subscription. The _{profile_name} suffix on the event name means each profile has its own combined event so subscribers can route events per stream.

Using Events in AXIS Rules

While the Spot Color Detector is running, events appear in the AXIS event system:

  1. Open the device's web interface
  2. Go to System > Events
  3. Find events under the Missing Features ACAP
  4. Create rules triggered by color state changes

Using Events in Flow

Use the Axis Metadata Event (Subscribe) node to receive color change events:

  1. Add the subscribe node to your flow
  2. Select the Spot Color Detector event
  3. Wire the outputs to your logic

Live Preview

The preview shows:

  • Real-time video feed via WebCodecs (no NAT/firewall issues)
  • Circle and rectangle overlays with current state
  • For each trigger:
  • Trigger name
  • Detected color (actual RGB from frame)
  • Matched color (nearest palette color)
  • Edit/Delete controls

Controls

Button Action
Add Circle Create new circular detection region
Add Rect Create new rectangular detection region
Show/Hide Toggle overlay visibility
Fullscreen Expand preview to full screen
Help Open the in-app guide (profiles, triggers, palette, events)
Save Persist changes for all profiles

Best Practices

Circle Placement

  • Position circles directly over the color area
  • Avoid edges where background colors might interfere
  • Use smaller circles for precise targets (LEDs, indicators)
  • Use larger circles for areas with color variation

Palette Configuration

  • Add only colors you expect to detect
  • Use specific shades (e.g., "Traffic Red" vs generic "Red")
  • Test detection and adjust palette colors if needed
  • Add the "Off/Dark" color for inactive states

Performance

  • Use lower resolution for faster processing
  • Limit the number of circles (each adds processing time)
  • Monitor the processing time indicator
  • Increase hysteresis if colors flicker

Troubleshooting

Issue Solution
Color not detected Ensure the palette includes a similar color
Flickering between colors Increase the hysteresis threshold
Wrong color matched Add a more specific color to the palette
High processing time Reduce resolution or circle count
Events not firing Check that the feature is started