Configure a color_detector | Vision

Configure a color_detector

The color_detector vision service is a heuristic detector that draws boxes around connected regions of a specified hue. It runs entirely on the machine with no ML model. Use it for any task where the target stands out by color: red objects on a conveyor, green plants against soil, a blue marker against a wall.

The detector cannot detect black, white, or perfect grays (pixels whose red, green, and blue values are equal). It only detects hues on the color wheel.

Tip

Object colors vary dramatically with lighting. Verify your target color value under actual lighting conditions. Tools like Color Picker for Chrome can extract a hex color from a screenshot of the camera feed. If the color is not reliably detected, increase hue_tolerance_pct.

Configure

Navigate to the CONFIGURE tab of your machine’s page.
Click the + icon next to your machine part and select Blocks.
In the search field, type color detector and select the vision/color_detector result.
Click Add to machine, enter a name, and click Add to machine again to confirm.
Choose a color and a hue tolerance, then set a segment size in pixels.
Select a default camera.

Attributes

Attribute	Type	Required?	Description
`detect_color`	string	Required	The target color in hex format (`#RRGGBB`). Must not be black, white, or any grayscale value.
`hue_tolerance_pct`	float	Required	How much hue variation to accept, between `0.0` (exact match) and `1.0` (any color). Start at `0.05` and increase if detection is unreliable. Values outside `(0.0, 1.0]` fail at startup.
`segment_size_px`	int	Required	Minimum pixel area of a connected color region for it to count as a detection. Filters out small noise blobs.
`saturation_cutoff_pct`	float	Optional	Pixels with HSV saturation below this are treated as gray and ignored. Must be in `[0.0, 1.0]`. Default: `0.2`
`value_cutoff_pct`	float	Optional	Pixels with HSV value (brightness) below this are treated as black and ignored. Must be in `[0.0, 1.0]`. Default: `0.3`
`label`	string	Optional	Label applied to detected bounding boxes. If unset, detections have no label.
`camera_name`	string	Optional	Default camera for calls such as `GetDetectionsFromCamera`. Must name a configured camera.

Info

hue_tolerance_pct, saturation_cutoff_pct, and value_cutoff_pct describe cutoff thresholds using the HSV color model. They do not specify the absolute saturation or brightness of the target color. hue_tolerance_pct controls how strictly the detector matches your detect_color; the saturation and value cutoffs filter out pixels that are too gray or too dark before matching.

Test your detector

Live camera footage

Open your machine in the Viam app and either click the vision service’s Test area or navigate to the CONTROL tab and select the vision service.
In the Camera dropdown, select the camera whose feed you want the detector to run on. Detections appear as bounding boxes on the live camera feed and refresh automatically.

For a continuous overlay, configure a transform camera:

{
  "pipeline": [
    {
      "type": "detections",
      "attributes": {
        "confidence_threshold": 0.5,
        "detector_name": "<vision-service-name>",
        "valid_labels": ["<label>"]
      }
    }
  ],
  "source": "<camera-name>"
}

Troubleshooting

Service fails to start with "saturation of 0" error

Your detect_color is black, white, or a perfect gray. The detector can only match hues on the color wheel. Pick a saturated color and try again.

Service fails to start with "too unsaturated" error

Your detect_color has saturation below the saturation cutoff. Either pick a more saturated color, or lower saturation_cutoff_pct.

Service fails to start with hue_tolerance_pct error

hue_tolerance_pct must be strictly greater than 0.0 and at most 1.0. A value of 0 is not allowed because it would require a pixel-perfect hue match that camera noise makes effectively impossible.

Detector runs but returns no detections

Check the color under actual lighting conditions. Use a color picker on a live camera screenshot to find the real hex value. The color on the object often looks different through the camera.
Increase hue_tolerance_pct (try 0.10 to 0.15) if the color is close but not exact.
Lower segment_size_px if the color region in the image is small.
If the lighting is dim, lower value_cutoff_pct (for example, 0.10).

Detector returns too many false positives

Decrease hue_tolerance_pct to require a closer match.
Raise saturation_cutoff_pct to ignore washed-out regions.
Increase segment_size_px to ignore small noise blobs.