gemini-watermark

# 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)

```bash
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

```bash
# 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:

1. **Spa...