# 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](https://chrome.google.com/webstore/detail/color-picker-for-chrome/clldacgmdnnanihiibdgemajcfkmfhia) can extract a hex color from a screenshot of the camera feed. If the color is not reliably detected, increase `hue_tolerance_pct`.

## Configure

1. Navigate to the **CONFIGURE** tab of your machine’s page.
2. Click the **+** icon next to your machine part and select **Blocks**.
3. In the search field, type `color detector` and select the `vision/color_detector` result.
4. Click **Add to machine**, enter a name, and click **Add to machine** again to confirm.
5. Choose a color and a hue tolerance, then set a segment size in pixels.
6. 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]`.<br>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]`.<br>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

1. 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.
2. 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](https://docs.viam.com/reference/components/camera/transform/):

```json
{
  "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.