- name
- gemini-watermark
- description
- Remove visible Gemini AI watermarks from images via reverse alpha blending. Use for cleaning Gemini-generated images, removing the star/sparkle logo watermark, batch watermark removal.
- metadata
- author
- agiseek
- version
- 2.1.0
Gemini Watermark Remover
Remove the visible Gemini AI watermark (star/sparkle logo) from generated images using mathematically accurate reverse alpha blending.
Fully offline — pure Python, no external binary downloads, no network access.
When to Use
- Remove the Gemini watermark from AI-generated images
- Batch process a directory of Gemini-generated images
- Clean images before publishing or sharing
- Automate watermark removal in pipelines
Quick Start
Install Dependencies (one-time)
pip install Pillow numpy
# Recommended: use uv for faster, isolated installs
uv pip install Pillow numpyRequires: Python ≥ 3.9. No Rust toolchain, no compiled binaries, no downloads.
Basic Usage
# Single image (auto-detect watermark, save as photo_cleaned.jpg)
python3 scripts/remove_watermark.py photo.jpg
# Specify output path
python3 scripts/remove_watermark.py photo.jpg -o clean_photo.jpg
# Batch process directory
python3 scripts/remove_watermark.py ./input_dir -o ./output_dir
# Force removal without detection
python3 scripts/remove_watermark.py photo.jpg -o clean.jpg --forceHow It Works
Gemini adds a semi-transparent white star/sparkle logo to generated images using alpha blending:
watermarked = alpha * 255 + (1 - alpha) * originalThis tool reverses the equation to recover the original pixels:
original = (watermarked - alpha * 255) / (1 - alpha)The alpha map (watermark transparency pattern) is generated mathematically as a 4-pointed star (central Gaussian core + 4 elongated cardinal rays) at two sizes:
- 48×48 with 32 px margin — images where either dimension ≤ 1024 px
- 96×96 with 64 px margin — images where both dimensions > 1024 px
For improved accuracy you can supply your own alpha map derived from a background capture of the Gemini watermark on a white background (--alpha-map).
Detection
Before removal, a three-stage algorithm checks whether a watermark is present:
- Spatial NCC (50% weight) — normalised cross-correlation with the alpha map
- Gradient NCC (30% weight) — edge signature matching via Sobel operators
- Variance Analysis (20% weight) — texture dampening detection
Images without detected watermarks are automatically skipped.
CLI Parameters
| Parameter | Short | Default | Description |
|---|---|---|---|
input | (required) | Input image file or directory | |
--output | -o | {name}_cleaned.{ext} | Output file or directory |
--force | -f | false | Skip detection, process unconditionally |
--threshold | -t | 0.35 | Detection confidence threshold (0.0–1.0) |
--force-small | false | Force 48×48 watermark size | |
--force-large | false | Force 96×96 watermark size | |
--alpha-map | (built-in) | Custom grayscale alpha map image | |
--verbose | -v | false | Enable detailed output |
--quiet | -q | false | Suppress all non-error output |
Supported Formats
| Format | Read | Write |
|---|---|---|
| JPEG (.jpg, .jpeg) | Yes | Yes (quality 100) |
| PNG (.png) | Yes | Yes |
| WebP (.webp) | Yes | Yes |
| BMP (.bmp) | Yes | Yes |
Usage Examples
# Verbose output (shows detection confidence, watermark coordinates)
python3 scripts/remove_watermark.py photo.png -o clean.png -v
# Lower detection threshold (more sensitive)
python3 scripts/remove_watermark.py photo.jpg -t 0.15
# Force large watermark size regardless of image dimensions
python3 scripts/remove_watermark.py photo.jpg --force-large -o clean.jpg
# Batch process, quiet mode
python3 scripts/remove_watermark.py ./gemini_images/ -o ./cleaned/ -q
# Supply a custom alpha map for higher accuracy
python3 scripts/remove_watermark.py photo.jpg --alpha-map my_alpha.pngDeriving a Custom Alpha Map
For pixel-perfect removal, capture the Gemini watermark on a pure white background and compute:
alpha(x, y) = max(R, G, B) / 255Save the result as a grayscale PNG and pass it via --alpha-map.
Output
- Single file — saves to
-opath, or{name}_cleaned.{ext}by default - Directory — saves all processed images to the output directory
- Skipped images — images without detected watermarks are not modified (unless
--force) - Exit code — 0 on success, 1 if any image fails
Troubleshooting
"No watermark detected" on a watermarked image
- Try lowering the threshold:
-t 0.1 - Or bypass detection entirely:
--force - Consider supplying a custom alpha map for your watermark variant
Image looks distorted after removal
- The image may not have a Gemini watermark. Use detection (avoid
--force) - Try
--force-smallor--force-largeto match the correct size - Supply a custom alpha map for better precision
"Image too small" warning
The image dimensions are smaller than the watermark region. This typically means the image does not have a Gemini watermark.
ModuleNotFoundError: Pillow or numpy
pip install Pillow numpy
# or
uv pip install Pillow numpyLimitations
- Visible watermark only — this tool removes the visible star/sparkle logo watermark
- Cannot remove SynthID — Google's invisible watermark (SynthID) is embedded at the pixel level during generation and cannot be reversed
- Fixed position only — handles watermarks in the standard bottom-right position only
- Built-in alpha map is approximate — use
--alpha-mapwith a captured reference for exact results