# Replace image color

- Human page: https://happytails.ai/en/image-tools/image-color-replacement/
- Markdown: https://happytails.ai/en/image-tools/image-color-replacement.md
- Structured JSON: https://happytails.ai/agents/en/image-tools/image-color-replacement/index.json
- Visibility: public

## Tool capabilities

| Property | Value |
| --- | --- |
| Tool ID | `image-color-replacement` |
| Category | image-tools |
| Implementation | Registered implementation. Registration alone is not a production-quality guarantee. |
| Browser execution | Use the visible action or interactive controls. |
| Browser processing | Browser; see tool notes for network behavior. |
| HTTP API | Not callable through HTTP. |
| Browser-agent interface | run_current_tool |

### Implementation notes

Runs locally without uploads. One still PNG, JPEG or WebP up to 20 MiB and 16 million decoded pixels, with at most 16,384 pixels per side. Replaces pixels within a hard RGB distance of the selected source color. Zero tolerance matches the exact color; 100 matches all colors. Decoded alpha bytes stay unchanged. The browser may discard hidden RGB values in transparent pixels and convert the source color profile. Download the complete PNG, black-and-white selection mask and settings report. Original metadata is not retained. Outputs are limited to 100 MiB in total; processing stops after 30 seconds.

### Inputs and settings

No free-text input is required. Use the file inputs and/or settings below.

Accepted browser files: `.png,.jpg,.jpeg,.webp`. Choose one file.

Browser file-input limit: 20971520 bytes in total. HTTP limits can differ.

| Setting | Meaning | Control type | Default | Constraints |
| --- | --- | --- | --- | --- |
| `source` | Source color | color | "#000000" |  |
| `replacement` | Replacement color | color | "#00ff00" |  |
| `tolerance` | Color tolerance (%) | number | "0" | min=0 max=100 step=0.1 |
| `includeTransparent` | Include fully transparent pixels | checkbox | false |  |

### Browser-agent workflow

1. Open the human page in a browser that supports WebMCP.
2. Discover the interface exposed by that page; use its actual schema.
3. Select files on the page first when the tool requires files.
4. Call `run_current_tool` with valid input and settings.
5. Inspect the returned result or error and the displayed output. Retrieve files from the displayed download links.

Calls do not automatically copy or download results. Browser permissions still apply. Interface availability alone is not proof of successful execution.

### Planning specification

Runs locally without uploads. One still PNG, JPEG or WebP up to 20 MiB and 16 million decoded pixels, with at most 16,384 pixels per side. Replaces pixels within a hard RGB distance of the selected source color. Zero tolerance matches the exact color; 100 matches all colors. Decoded alpha bytes stay unchanged. The browser may discard hidden RGB values in transparent pixels and convert the source color profile. Download the complete PNG, black-and-white selection mask and settings report. Original metadata is not retained. Outputs are limited to 100 MiB in total; processing stops after 30 seconds.

This describes intended requirements. Use the implementation notes, interface schema and observed output to determine current support.

### Complete machine-readable capability record

```json
{
  "id": "image-color-replacement",
  "category": "image-tools",
  "built": true,
  "requirements": "Runs locally without uploads. One still PNG, JPEG or WebP up to 20 MiB and 16 million decoded pixels, with at most 16,384 pixels per side. Replaces pixels within a hard RGB distance of the selected source color. Zero tolerance matches the exact color; 100 matches all colors. Decoded alpha bytes stay unchanged. The browser may discard hidden RGB values in transparent pixels and convert the source color profile. Download the complete PNG, black-and-white selection mask and settings report. Original metadata is not retained. Outputs are limited to 100 MiB in total; processing stops after 30 seconds.",
  "implementation": {
    "fields": [
      {
        "key": "source",
        "label": "Source color",
        "value": "#000000",
        "type": "color"
      },
      {
        "key": "replacement",
        "label": "Replacement color",
        "value": "#00ff00",
        "type": "color"
      },
      {
        "key": "tolerance",
        "label": "Color tolerance (%)",
        "value": "0",
        "type": "number",
        "min": 0,
        "max": 100,
        "step": 0.1
      },
      {
        "key": "includeTransparent",
        "label": "Include fully transparent pixels",
        "value": false,
        "type": "checkbox"
      }
    ],
    "registrationFamily": "pixel-editing",
    "files": true,
    "input": false,
    "multiple": false,
    "accept": ".png,.jpg,.jpeg,.webp",
    "maxFileBytes": 20971520,
    "deferImagePreview": true,
    "note": "Runs locally without uploads. One still PNG, JPEG or WebP up to 20 MiB and 16 million decoded pixels, with at most 16,384 pixels per side. Replaces pixels within a hard RGB distance of the selected source color. Zero tolerance matches the exact color; 100 matches all colors. Decoded alpha bytes stay unchanged. The browser may discard hidden RGB values in transparent pixels and convert the source color profile. Download the complete PNG, black-and-white selection mask and settings report. Original metadata is not retained. Outputs are limited to 100 MiB in total; processing stops after 30 seconds.",
    "experience": {
      "automatic": false,
      "single": false,
      "inputMaxLength": 1000000,
      "inputMode": "text",
      "label": "Your text",
      "placeholder": "Type or paste your input…",
      "help": "Up to 1,000,000 characters. Review the settings before running.",
      "action": null
    },
    "mode": "explicit",
    "interactive": false
  },
  "execution": "Browser interface",
  "api": null,
  "browser_agent": {
    "supported": true,
    "name": "run_current_tool",
    "discovery": "WebMCP on the human page in a supporting browser",
    "verification": "See audit/API-AUDIT.md; availability is not verification"
  }
}
```

## Page guide

Replace one color in an image while keeping transparency. Adjust tolerance and download the edited PNG and selection mask.

How can we improve this tool?

Report a problem or share an idea.

Please leave out private information. Your message and the tool name go to our team via PostHog.

### How to use Replace image color

1. Choose a still PNG, JPEG or WebP image.
2. Select the source color, replacement color and tolerance.
3. Run the tool, compare the original and result, and download the PNG, selection mask or report.

## Useful next steps

- [Image to ASCII art](https://happytails.ai/en/image-tools/image-to-ascii-art/) ([Markdown](https://happytails.ai/en/image-tools/image-to-ascii-art.md))

- [Compress image](https://happytails.ai/en/image-tools/compress-image/) ([Markdown](https://happytails.ai/en/image-tools/compress-image.md))

## See exactly what changed

The selection mask is white where a pixel matched and black everywhere else. Tolerance uses RGB distance. It is a hard threshold, not a feathered selection.

### Keep transparency

The replacement preserves the decoded alpha channel. Fully transparent pixels are skipped unless you include them. Browser decoding can change hidden RGB values and color profiles; original metadata is not copied.