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 numpy

Requires: 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 --force

How It Works

Gemini adds a semi-transparent white star/sparkle logo to generated images using alpha blending:

watermarked = alpha * 255 + (1 - alpha) * original

This 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.png

Deriving 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) / 255

Save the result as a grayscale PNG and pass it via --alpha-map.

Output

Single file — saves to -o path, 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-small or --force-large to 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 numpy

Limitations

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-map with a captured reference for exact results

gemini-watermark