Gwt

GeminiWatermarkTool Skill for Codex-Like Agents

Overview

GeminiWatermarkTool (GWT) removes visible Gemini AI watermarks from images using mathematically accurate reverse alpha blending, with optional AI denoising (FDnCNN + NCNN Vulkan GPU) for residual cleanup.

Source: https://github.com/allenk/GeminiWatermarkTool

---

Binary Location

Search in this order:

1. Environment variable: GWT_BINARY_PATH
2. System PATH: GeminiWatermarkTool (or .exe on Windows)
3. Codex skill bin directory:

• Windows: %USERPROFILE%\.codex\skills\gwt\bin\GeminiWatermarkTool.exe
• Linux/macOS: ~/.codex/skills/gwt/bin/GeminiWatermarkTool

1. Repo-local bin directory (validation mode / fallback):

• Windows: .\bin\GeminiWatermarkTool.exe
• Linux/macOS: ./bin/GeminiWatermarkTool

If not found, run the installer:

python ~/.codex/skills/gwt/install.py

For local validation inside this repo only:

python ~/.codex/skills/gwt/install.py --dir ./bin

Always pass --no-banner when calling GWT — suppresses ASCII art that wastes tokens.

---

Watermark Profile Selection (v0.3.1+)

GWT ships with two watermark profiles. The default targets Gemini 3.5 and later, with automatic legacy fallback.

| Profile | Targets | When tried | |---------|---------|------------| | Current (V2) | Gemini 3.5 and later outputs | first, by default | | Legacy (V1) | Pre-Gemini-3.5 outputs | automatically retried if V2 skips |

This means remove_watermark(input, output) already handles mixed Gemini-3.5+ and pre-3.5 inputs without supervision — the CLI tries the current profile, and on skip retries with the legacy profile before reporting the final outcome. Two opt-out paths exist for the rare case where you need to pin a profile:

• no_legacy=True parameter — disable the automatic fallback (current only)
• remove_watermark_legacy / remove_watermark_batch_legacy — pin legacy only

Always start with remove_watermark / remove_watermark_batch. The auto-fallback handles the common case. The dedicated *_legacy tools are mostly there for callers that have side knowledge an image is pre-3.5 and want to skip the V2 attempt entirely.

What to do when detection fails ("skipped")

A skipped=True result from the default tool means both profiles tried their best and neither matched. The two indistinguishable causes are:

1. The image was generated by Gemini, but its watermark has been destroyed

by heavy editing/resizing/re-encoding.

1. The image was not generated by Gemini at all.

Do NOT silently re-invoke remove_watermark_legacy — the automatic fallback has already attempted that. Instead, surface the result to the user and ask whether to escalate:

> "I couldn't detect a Gemini watermark on this image (confidence X% on > the current profile, Y% on legacy). Either it isn't a Gemini output, or > the watermark has been damaged by post-processing. I can try forcing > removal at a custom region if you can point me at one — otherwise there's > nothing to do."

Escalation paths the agent can offer:

• --fallback-region br:64,64,500,500 --snap — multi-scale search in a

user-supplied area (good for resized / cropped images)

• Lower --threshold (e.g. 0.15) — relaxes the safety gate; risky on

non-Gemini files but legitimate when the user is certain

• Custom region in the GUI — most user-friendly for one-off cleanup

---

Decision Logic

Pipeline selection (automatic, based on flags)

| Flags | Internal behavior | |-------|-------------------| | No advanced flags | Standard 3-stage NCC detection → process or skip | | --fallback-region only | Standard detection first → if not found, apply to fallback region | | --fallback-region --snap | Skip standard detection entirely → snap search directly | | --force | Skip detection, process unconditionally | | --legacy | Pin V1 profile (pre-Gemini-3.5 outputs); skip the V2 attempt entirely | | --no-legacy | Disable the auto V2 → V1 fallback (current profile only) | | no --legacy and no --no-legacy | V2 first; auto-retry on V1 if V2 skips (v0.3.1+ default) |

Case A — Standard image (not resized after generation)

GeminiWatermarkTool --no-banner -i input.jpg -o clean.jpg

Detection on by default (threshold 25%). Non-watermarked images are skipped safely.

Case B — Image was resized or recompressed

--fallback-region --snap together skips standard detection and goes straight to multi-scale snap search:

GeminiWatermarkTool --no-banner \
  -i input.jpg -o clean.jpg \
  --fallback-region br:64,64,500,500 \
  --snap --snap-max-size 320 --snap-threshold 0.60 \
  --denoise ai --sigma 50 --strength 120

Case C — Unknown image (try standard first, fallback on failure)

Use --fallback-region without --snap. Standard detection runs first; fallback region only activates if standard detection fails:

GeminiWatermarkTool --no-banner \
  -i input.jpg -o clean.jpg \
  --fallback-region br:64,64,500,500 \
  --denoise ai --sigma 50 --strength 120

---

Full CLI Reference

Core options

| Flag | Default | Description | |------|---------|-------------| | -i, --input | — | Input file or directory | | -o, --output | — | Output file or directory | | -f, --force | false | Skip detection, process unconditionally | | -t, --threshold | 0.25 | Detection confidence threshold | | --force-small | — | Force small watermark size | | --force-large | — | Force large watermark size | | --legacy | — | Pin pre-Gemini-3.5 profile (V1); skips V2 attempt. | | --no-legacy | — | Disable the automatic V2 → V1 fallback. | | -v, --verbose | false | Detailed output | | -q, --quiet | false | Suppress output except errors | | --no-banner | — | Hide ASCII banner (always use in this skill) |

Region options

| Flag | Description | |------|-------------| | --region | Explicit watermark region | | --fallback-region | Search region when standard detection fails |

Region spec formats:

| Format | Meaning | |--------|---------| | x,y,w,h | Absolute pixel coordinates | | br:mx,my,w,h | Bottom-right: marginright, marginbottom, width, height | | bl:mx,my,w,h | Bottom-left relative | | tr:mx,my,w,h | Top-right relative | | tl:mx,my,w,h | Top-left / absolute | | br:auto | Gemini default position for this image size |

Snap engine

| Flag | Default | Description | |------|---------|-------------| | --snap | false | Multi-scale snap within region/fallback-region | | --snap-max-size | 160 | Maximum watermark size to search | | --snap-threshold | 0.60 | Minimum confidence to accept match |

Denoise / inpaint

| Flag | Default | Description | |------|---------|-------------| | --denoise | off | ai \| ns \| telea \| soft \| off | | --sigma | 50 | FDnCNN noise sigma (ai only) | | --strength | 120 (ai) / 85 (others) | Blend strength in percent | | --radius | 10 | Inpaint radius (ns / telea / soft only) |

---

Watermark Size Auto-Detection

| Profile | Small logo | Large logo | Threshold | |---------|-----------|-----------|-----------| | V2 (default — Gemini 3.5+) | 36×36 | 96×96 | long side > 1024 → large | | V1 (--legacy, pre-3.5) | 48×48 | 96×96 | long side > 1024 → large |

Override with --force-small or --force-large. Profile is selected by --legacy (off = V2, on = V1).

---

Parameter Tuning Guide

| Situation | Action | |-----------|--------| | Faint residual | --denoise ai --sigma 50 --strength 120 | | Visible edge artifacts | --sigma 75 --strength 180 | | Strong residual (heavily resized) | --sigma 100 --strength 250 | | Detection keeps skipping | Lower --threshold 0.15 or add --fallback-region | | Snap finds nothing | Widen region, increase --snap-max-size 320 | | Snap confidence too low | Lower --snap-threshold 0.40 | | Wrong size detected | --force-small or --force-large |

---

Exit Codes (v0.3.1+)

| Code | Meaning | |------|---------| | 0 | File processed (or batch directory completed without errors) | | 1 | Single-file invocation skipped — no watermark detected on any profile that the chosen flag combination tried | | 2 | Real failure — bad arguments, missing input, IO/write error |

Batch directory mode keeps lenient semantics (exit 0 unless something actually fails) since partial skips are expected when scanning a folder.

---

Important Notes

1. AI denoise GPU fallback: Vulkan GPU used when available, falls back to CPU

automatically. If AI init fails entirely, GWT falls back to NS inpainting.

1. SynthID cannot be removed: Statistically embedded during generation,

inseparable from image content.

1. Supported formats: jpg, jpeg, png, webp, bmp
2. Batch mode: -i dir/ -o dir/ processes all images; non-watermarked files

are skipped safely by default.

1. Profile auto-fallback (v0.3.1+): by default the CLI tries the current

profile, then automatically retries with the legacy profile on skip. Pin a single profile with --legacy (V1 only) or --no-legacy (V2 only) if the auto-fallback isn't what you want.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: allenk
• Source: allenk/gwt-integrations
• License: MIT
• Homepage: https://allenkuo.medium.com/removing-gemini-ai-watermarks-a-deep-dive-into-reverse-alpha-blending-bbbd83af2a3f#a563

Install and usage instructions live in the source repository linked above.