mirror of
https://github.com/wiltodelta/remove-ai-watermarks.git
synced 2026-10-21 16:21:42 +02:00
Victor Kuznetsov
07b07634cf
* Add rigorous SynthID research and evaluation harness * Record SynthID cross-epoch validation results * Reset SynthID detector hypotheses to paired training * Add paired wavelet and spectral SynthID probes * Record closed-corpus SynthID detector ablations * Add registered SynthID phase probing * Add periodic SynthID tile probing * Add calibrated SynthID pixel detector * Harden scale-registered SynthID detection * Record SynthID phase and channel rescue findings * Add production SynthID routing and OpenAI verification * Reframe periodic pixel route as pipeline lattice; confirm and harden detection The frozen periodic experts read an origin-anchored generation-pipeline lattice destroyed by a crop off the tile grid, not the crop-robust SynthID mark. Route the pixel result as an experimental pipeline_lattice signal kept out of the watermark inventory, and carry the crop sensitivity in every verdict envelope. Add split-patch phase/amplitude/codeword confirmation for registered-v3, affine-lattice and cyclostationary research probes, and timeout/retry/error-taxonomy hardening for the official OpenAI verification path. * Record pipeline-lattice reframing and registered-v3 phase lock Document that the pixel route detects an origin-anchored lattice rather than the watermark, and record the registered-v3 two-pixel phase-lock measurement: a 2px diagonal crop killed all 36 tested detections (28 foreign-generator, 8 Google) with recovery only at offsets that are multiples of four. Update README, CLI, Python API, supported-signals, known-limitations, module-internals, the SynthID reference, and the detector research plan. * Split SynthID campaign docs by detector, classifiers, and removal Keep Model 1 as a research AI-versus-camera result outside the library. Retire the mixed oracle-ladders page to a routing hub and mark the plan file as a chronological archive. * Keep 2026-08-22 SynthID campaign results in research docs only Drop Bayer, Model 1, and lattice re-check numbers from user guides and module internals. The library surface is unchanged. * Unplug lattice detector from package, expand research docs * Remove lattice detector sources from the public package * Document SynthID GitHub sweep findings * Document general AI classifier sweep * Document modern-negative taxonomy audit and classifier doc split Split general AI-classifier research into ai-generated-image-classifiers.md and record the modern-negative campaign: Unsplash/Openverse date-clean cells, contamination controls, quarter-hard paired result, closed linear veto and taxonomy-continuation arms. pre-commit: 1) maintain.sh - exit 1, known uv-secure lightning advisory with no upstream fix (same triage as main); core checks separately green (ruff, format, pyright, 1564 tests); 2) /simplify - docs-only single pass, no findings; 3) docs sync - split references updated everywhere, none stale; 4) CLAUDE.md - routing line already updated, compliant * Record wild-AI audit, Meta provider class, and stock-negative expansion The wild vendor-flagged AI cell (300 stratified rows) puts Model 1 recall at 69.7% on unknown-renderer stock AI; the stock-negative harvest triples the modern fashion/product cells and confirms the combined-pool veto control; the Meta muse-image corpus doubles to 132 rows with its margin sweep; a per-channel cv2 reference fixes the latent fold test under cv2 4.10.0. pre-commit: 1) maintain.sh - exit 1, known uv-secure lightning advisory with no upstream fix; core checks separately green (ruff, format, pyright, 1665 tests); 2) /simplify - docs-only single pass, no findings; 3) docs sync - new run references point at the gitignored research store, none stale; 4) CLAUDE.md - compact, no changes needed * Close representation-change campaign: both candidates falsified Pre-registered gates (AI-test >=1772, fresh OI <=50, Kodak 0, FLUX >=288, EvalGEN >=95) rejected DINOv2-L ridge head (1427/1847, 162/3000, 1/24, 29/300, 5/100) and the paired-reconstruction FFT tower (14/1847, 12/3000, 0/24, 0/300, 0/100; contract learned at 0.949 pairwise separation but no transfer to production generators). Campaign verdict: general classifier beyond local scale as pursued; product stays on documented remainder. pre-commit: 1) maintain.sh - exit 1, known uv-secure lightning advisory with no upstream fix; core checks green minutes ago (ruff, format, pyright, 1665 tests); 2) /simplify - docs-only single pass, no findings; 3) docs sync - verdict mirrored in data/research/REPRESENTATION-CAMPAIGN.md, no stale refs; 4) CLAUDE.md - no changes * Record full failure map, H2 router falsification, and H3 process detector closure 20 measured negative domains with batch-2 (memes, whiteboards, tickets, book pages). H2 domain router falsified: 97.9% of AI-test looks structured, every family 94-100%. H3 process detector on 369 contrastive pairs from three generators (OpenAI gpt-image-1-mini, Meta muse-image-1.0, Gemini flash-image) achieves 0.909 pairwise AUC on training pairs but transfers at AUC 0.55-0.60 to production AI; human receipts score higher than any AI family. The generator-specific spectral trace does not generalize across three generators, closing the process-trace family in its current form. pre-commit: 1) maintain.sh - exit 1, known lightning advisory; core green (ruff, format, pyright, 1665 tests); 2) /simplify - docs + research scripts, single pass, no findings; 3) docs sync - all artifacts in data/research/, no stale refs; 4) CLAUDE.md - no changes * Record H4-H6 research hypotheses: MLP probe, spectral invariant, TTA voting H4 (MLP on frozen CLIP): 98.6% AI-test recall but 15.8% photo FPR — same trade-off curve as quarter-hard. H5 (spectral invariant from CVPR 2025): 2.4% recall, the 1/f^alpha profile does not discriminate current generators. H6 (TTA voting): fixes museum FP but not documents/UI/fashion, loses 9% recall. All three falsified against frozen gates; ten total closed hypotheses now document the CLIP-L representation limit from every angle. Also records the provider cascade across all 20 domains (69.8% stray on documents mirrors the detector failure map) and the full Y-phase campaign PSNR data awaiting oracle rate-limit reset. pre-commit: 1) maintain.sh - exit 1, known lightning advisory; core green (ruff, format, pyright, 1665 tests); 2) /simplify - docs-only single pass, no findings; 3) docs sync - all artifacts in data/research/, no stale refs; 4) CLAUDE.md - no changes * Fix Y-phase frequency convention, record H4-H6 and campaign results The initial Y-phase campaign targeted FFT bins 16-32 instead of spatial periods 16-32 px (1/32 to 1/16 cycles/px). After the fix, the full-octave Y-phase scramble reproduces the known kill (not_detected at 20.5 dB on s1 at native 1122x1402). Partial sub-bands are visually invisible (42.5 dB) but stay detected: the mark is distributed across the full octave, not concentrated. Point intervention is not viable within this frequency band. H4 MLP probe: 98.6% recall, 15.8% FPR (same trade-off wall). H5 spectral invariant: 2.4% recall (1/f^alpha does not discriminate). H6 TTA voting: fixes museum FP but not documents/UI/fashion. pre-commit: 1) maintain.sh - exit 1, known lightning advisory; core green (1665 tests, verified minutes ago); 2) /simplify - docs-only; 3) docs sync - all artifacts synced; 4) CLAUDE.md - no changes * Add TC260 fifth class and per-class margin calibration to provider cascade Five-head cascade (openai/google/tc260/meta/no_ai): openai 68.8%, google 76.6%, tc260 63.8%, meta 71.8% mean recall at uniform margin 0.50. Per-class margins calibrated against 1.67% photo budget: openai 0.31, google 0.29, tc260 0.39, meta 0.55. TC260 test recall 71.4% at calibrated margins on 196 held-out images. Chinese-AIGC is a viable pixel class. pre-commit: 1) maintain.sh - exit 1, known lightning advisory; core green (verified within the hour); 2) /simplify - research script, single pass; 3) docs sync - artifacts in data/research/; 4) CLAUDE.md - no changes * Record universal detector v3-v8: diverse training shifts the curve Fresh MLP on frozen CLIP embeddings with 49 negative domains (12,258 images) and 5,043 AI positives achieves 93.0% AI-test recall with 39/49 domains at zero false positives. Digital art FP dropped from 99.3% (Model 1) to 24.8%, fashion from 62-71% to 12%, UI from 99.3% to 12%. Photo FPR 0.7%. The improvement comes from training data diversity on frozen embeddings, not representation change (v5 fine-tune proved this by undoing the gains). Also adds .local-eval to ruff exclude so the gate covers only tracked files. pre-commit: 1) maintain.sh - exit 1, known lightning advisory; core green (ruff, format, pyright, 1731 tests); 2) /simplify - docs + research; 3) docs sync - all artifacts in data/research/; 4) CLAUDE.md - no changes * Add three-tier ensemble detector: DEFINITELY/POSSIBLY/LIKELY_HUMAN Combines Model 1 and v8 into calibrated confidence tiers. DEFINITELY_AI (both models agree) achieves 79.6% recall at 0.50% photo FPR with 46/49 domains at zero FP. The union reaches 93.3% recall at 1.80% photo FPR with Kodak 0/24. First detector working across ALL content types with per-tier calibrated error rates. pre-commit: 1) maintain.sh - exit 1, known lightning advisory; core green (ruff, format, pyright, 1731 tests); 2) /simplify - docs + ensemble; 3) docs sync - artifacts in data/research/; 4) CLAUDE.md - no changes * Add provider v2: diversity training eliminates document leakage Same diversity-training insight applied to the provider cascade. Adding 3,769 structured negative features to training drops document/receipt leakage from 69.8% to 5.1%, UI from 10% to 4.3%, fashion from 5-15% to 0-3%. AI recall improves: OpenAI 84% (was 75%), Google 88.8% (was 79%). Photo leakage 1.4%. Worst regression: memes 47.9% (was 27%). pre-commit: 1) maintain.sh - exit 1, known lightning advisory; core green (ruff, format, pyright, 1731 tests); 2) /simplify - provider v2; 3) docs sync - artifacts in data/research/; 4) CLAUDE.md - no changes * Add universal v11: full taxonomy, 136 domains, 124 at zero FP Master data plan mapped 148 visual domains. Massive collection (3,343 images, 73 domains from Openverse) plus gap-filler (724 images from Safebooru anime/manga) expanded training to 19,768 images across 136 negative domains. Universal v11 (MLP-512 + Model 1 ensemble): DEFINITELY 90.3% recall at 0.50% photo FPR, ANY 95.6% recall, 124/134 domains at exactly 0% FP, worst FP 13.8% (digital art). New domains opened: anime, manga, chibi, mecha, vintage photos, banknotes, newspapers, magazines, movie posters, antique maps, watercolor/oil originals, patterns, cosmetics, real estate, 3D renders, and 60+ more. pre-commit: 1) maintain.sh - exit 1, known lightning advisory; core green (ruff, format, pyright, 1731 tests); 2) /simplify - docs + research; 3) docs sync - artifacts in data/research/; 4) CLAUDE.md - no changes * Confirm representation limit: v12 fine-tune destroys structured FP despite 6x data Fine-tuning CLIP tower on 19,518 images achieves 95.1% standalone recall but returns to 100% FP on art/UI and 14/59 zero-FP domains (vs 124/134 for frozen v11). This is a representation property, not a data issue. Frozen CLIP + MLP (v11) is the only working architecture. Also records provider v3 trained on all negative domains. pre-commit: 1) maintain.sh - exit 1, known lightning advisory; core green (ruff, format, pyright, 1731 tests); 2) /simplify - docs + research; 3) docs sync - artifacts in data/research/; 4) CLAUDE.md - no changes * Document v13 plateau: 128/136 zero FP, frozen-CLIP ceiling confirmed v13 with top-plan expansion (1,169 new images) improves domain coverage to 128/136 at zero FP and reduces fashion FP to 5.3%, but DEFINITELY recall plateaus at 89.6% and art FP at 15.9%. The frozen CLIP + MLP architecture has reached its ceiling. pre-commit: 1) maintain.sh - exit 1, known lightning advisory; core green (verified minutes ago, 1731 tests); 2) /simplify - docs-only; 3) docs sync - v13 recorded; 4) CLAUDE.md - no changes * Document the 2026-08-31 photo-classifier freeze. Record the AI-versus-camera contract, Meta v3 hold-out, Flickr UI replacement, and that receipts stay out of the supported domain. * Scrub Spaces catalog details from classifier research docs * Record receipt layout-gate probe for the universal detector
263 lines
8.9 KiB
Markdown
263 lines
8.9 KiB
Markdown
# Installation
|
|
|
|
Python 3.11 through 3.14 are supported.
|
|
|
|
## Default metadata mode
|
|
|
|
The default package provides:
|
|
|
|
- provenance inspection;
|
|
- AI metadata inspection and removal.
|
|
|
|
It installs Pillow, piexif, and c2pa-python for reading metadata directly from
|
|
files. It does not install NumPy, OpenCV, pillow-heif, Torch, diffusion models,
|
|
or invisible-watermark decoders.
|
|
|
|
Install it as an isolated command with uv:
|
|
|
|
```bash
|
|
uv tool install remove-ai-watermarks
|
|
```
|
|
|
|
Or with pipx:
|
|
|
|
```bash
|
|
pipx install remove-ai-watermarks
|
|
```
|
|
|
|
You can also install the Homebrew package on macOS or Linux:
|
|
|
|
```bash
|
|
brew install wiltodelta/tap/remove-ai-watermarks
|
|
```
|
|
|
|
## Visible watermark removal
|
|
|
|
Visible mark detection, OpenCV inpainting, and manual region erasing need the
|
|
`visible` extra:
|
|
|
|
```bash
|
|
uv tool install --force "remove-ai-watermarks[visible]"
|
|
```
|
|
|
|
Add `heif` only when the pixel path must decode HEIC, HEIF, or AVIF:
|
|
|
|
```bash
|
|
uv tool install --force "remove-ai-watermarks[visible,heif]"
|
|
```
|
|
|
|
## Video processing
|
|
|
|
Video metadata inspection works with the default package, and MP4 and MOV
|
|
stripping uses the in-tree ISOBMFF box walker. Stripping the non-ISOBMFF
|
|
containers (MKV, WebM, AVI, FLV, and the audio formats) and writing any cleaned
|
|
video need ffmpeg on PATH, for example `brew install ffmpeg`. Stable
|
|
visible-mark identification and removal, full video cleaning, and visible/all
|
|
batch modes need the `video` extra:
|
|
|
|
```bash
|
|
uv tool install --force "remove-ai-watermarks[video]"
|
|
```
|
|
|
|
The extra includes the visible pixel runtime and PyAV for preserving variable
|
|
frame timestamps. Video SynthID regeneration also needs the diffusion stack:
|
|
|
|
```bash
|
|
uv tool install --force "remove-ai-watermarks[video,diffusion]"
|
|
```
|
|
|
|
## Invisible watermark removal
|
|
|
|
Install the `qwen-zimage` extra:
|
|
|
|
```bash
|
|
uv tool install --force "remove-ai-watermarks[qwen-zimage]"
|
|
```
|
|
|
|
Both remaining profiles run a Z-Image face stage on the DiffSynth runtime, so
|
|
both need this extra. The third profile, `chroma-zimage`, uses diffusers'
|
|
ChromaImg2ImgPipeline instead of DiffSynth for its global stage but inherits
|
|
the same face stage, so it needs this extra too. It includes the `diffusion`
|
|
dependencies; `diffusion` on its own covers the torch and diffusers imports
|
|
but not the face stage, so it is not enough to run a removal.
|
|
|
|
**An NVIDIA GPU is required.** `qwen-zimage`, `sdxl-zimage` and `chroma-zimage`
|
|
are CUDA-only, and
|
|
construction refuses any other device rather than falling back to a slow or broken
|
|
one. There is no CPU, MPS or XPU path for invisible-watermark removal. Visible-mark
|
|
removal, metadata stripping and every `identify` command still run anywhere.
|
|
|
|
Video SynthID regeneration is a separate VAE path and does still run on CPU or MPS;
|
|
it needs the `diffusion` extra, not this one.
|
|
|
|
The experimental verified-text post-pass additionally needs LaMa:
|
|
|
|
```bash
|
|
uv tool install --force "remove-ai-watermarks[text-restoration]"
|
|
```
|
|
|
|
That extra includes `qwen-zimage` and `lama`; it does not add OCR. Text strings and
|
|
line boxes must be reviewed before the run.
|
|
|
|
## Feature extras
|
|
|
|
Extras are composable. Install only the capabilities and file formats the
|
|
application actually uses:
|
|
|
|
| Extra | Capability | Automatically includes | Torch or model download |
|
|
| --- | --- | --- | --- |
|
|
| `pixels` | Shared BGR runtime and calibrated-size SynthID carrier detection | NumPy, headless OpenCV | No |
|
|
| `heif` | HEIC, HEIF, and AVIF pixel decoding | pillow-heif | No |
|
|
| `visible` | Visible mark detection, OpenCV inpainting, and manual erasing | `pixels` | No |
|
|
| `video` | Visible video identification/removal and timestamp preservation | `visible`, PyAV | No |
|
|
| `detect` | Open DWT-DCT detection for Stable Diffusion, SDXL, and FLUX | `pixels`, PyWavelets | No |
|
|
| `trustmark` | Adobe TrustMark detection on Python 3.11-3.12 | trustmark | Yes |
|
|
| `classify` | Metadata-free photo AI-versus-camera classifier plus gated provider | `pixels`, Torch, Transformers | Yes |
|
|
| `verify` | Official remote OpenAI SynthID verification | OpenAI SDK | No |
|
|
| `diffusion` | Torch and Diffusers runtime; video SynthID regeneration | `pixels`, Torch, Diffusers | Yes |
|
|
| `migan` | MI-GAN ONNX fill backend | `visible`, ONNX Runtime | Model download, no Torch |
|
|
| `lama` | big-LaMa ONNX fill backend | `visible`, ONNX Runtime | Model download, no Torch |
|
|
| `qwen-zimage` | Invisible image-watermark removal, all CUDA-only profiles | `diffusion`, DiffSynth | Yes |
|
|
| `text-restoration` | Opt-in verified profile-VAE glyph restoration | `qwen-zimage`, `lama` | Yes |
|
|
| `text-draft` | Draft OCR proposals for operator verification | PaddleOCR, PaddlePaddle | Model download, no Torch |
|
|
| `all` | Every production feature available on the active Python | All compatible rows above | Yes |
|
|
| `dev` | Tests, linting, typing, and upstream parity checks | `video`, `detect`, upstream invisible-watermark | Yes, for parity tests |
|
|
|
|
Dependency composition:
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
visible --> pixels
|
|
video --> visible
|
|
detect --> pixels
|
|
diffusion --> pixels
|
|
migan --> visible
|
|
lama --> visible
|
|
qwen["qwen-zimage"] --> diffusion
|
|
text["text-restoration"] --> qwen
|
|
text --> lama
|
|
draft["text-draft"]
|
|
heif
|
|
trustmark
|
|
classify --> pixels
|
|
verify
|
|
```
|
|
|
|
`heif`, `trustmark`, `verify`, and `text-draft` are independent branches. Combine them
|
|
explicitly with another feature when required. `text-draft` is excluded from
|
|
`all` because it proposes unverified OCR annotations and is not a production
|
|
removal path. TrustMark requires NumPy 1.x, which has no
|
|
CPython 3.13 or 3.14 wheels, so that branch is available only on Python
|
|
3.11-3.12. The `all` bundle contains every production branch compatible with
|
|
the active Python and never includes `dev`.
|
|
|
|
Examples:
|
|
|
|
```bash
|
|
# Metadata plus torch-free DWT-DCT detection
|
|
uv tool install --force "remove-ai-watermarks[detect]"
|
|
|
|
# Visible removal with HEIC/AVIF support and MI-GAN
|
|
uv tool install --force "remove-ai-watermarks[migan,heif]"
|
|
|
|
# Visible video removal with preserved timestamps
|
|
uv tool install --force "remove-ai-watermarks[video]"
|
|
|
|
# DWT-DCT and TrustMark detection without diffusion removal
|
|
uv tool install --force "remove-ai-watermarks[detect,trustmark]"
|
|
|
|
# Official OpenAI SynthID verification
|
|
uv tool install --force "remove-ai-watermarks[verify]"
|
|
|
|
# Every production capability compatible with this Python
|
|
uv tool install --force "remove-ai-watermarks[all]"
|
|
|
|
# An arbitrary minimal combination
|
|
uv tool install --force "remove-ai-watermarks[migan,detect]"
|
|
```
|
|
|
|
`heif` stays independent so applications that only process PNG, JPEG, or WebP
|
|
do not install libheif. `detect` uses the in-tree torch-free decoder and does
|
|
not install the upstream `invisible-watermark` package. Optional models download
|
|
their weights on first use.
|
|
|
|
The `verify` extra makes an explicit remote request. The
|
|
`verify-openai-synthid` command first removes AI provenance metadata from a
|
|
temporary copy, checks that its decoded pixels are unchanged, and then uploads
|
|
that copy to OpenAI. It needs `OPENAI_API_KEY`; the command never runs from
|
|
`identify` and refuses to upload without `--acknowledge-upload`. The Python API
|
|
requires the equivalent explicit `acknowledge_upload=True` argument.
|
|
|
|
The old `gpu` and `remove` aliases are intentionally not provided. Use
|
|
`diffusion` and `visible` respectively.
|
|
|
|
## Install from the repository
|
|
|
|
```bash
|
|
git clone https://github.com/wiltodelta/remove-ai-watermarks.git
|
|
cd remove-ai-watermarks
|
|
uv sync --frozen
|
|
```
|
|
|
|
Add the feature groups required for your work:
|
|
|
|
```bash
|
|
uv sync --frozen --extra dev
|
|
uv sync --frozen --extra dev --extra diffusion
|
|
```
|
|
|
|
Run commands from the repository root:
|
|
|
|
```bash
|
|
uv run remove-ai-watermarks --help
|
|
```
|
|
|
|
## Development setup
|
|
|
|
Install development dependencies:
|
|
|
|
```bash
|
|
uv sync --frozen --extra dev
|
|
```
|
|
|
|
Run the complete project gate:
|
|
|
|
```bash
|
|
bash maintain.sh
|
|
```
|
|
|
|
The script syncs every optional backend on top of the `dev` environment above,
|
|
then runs dependency checks, linting, formatting, type checking, and the test
|
|
suite. It applies Ruff fixes and formatting in place rather than only reporting
|
|
them.
|
|
|
|
## Hugging Face authentication
|
|
|
|
Pass a Hugging Face token directly when the selected model or account requires
|
|
one:
|
|
|
|
```bash
|
|
remove-ai-watermarks invisible image.png --hf-token "$HF_TOKEN"
|
|
```
|
|
|
|
The CLI also loads `HF_TOKEN` from the environment and from a local `.env`
|
|
file. The same name is documented in `.env.example`.
|
|
|
|
## Troubleshooting
|
|
|
|
### The first model run is slow
|
|
|
|
Diffusion and learned fill backends may download model weights on first use.
|
|
Later runs reuse their caches.
|
|
|
|
### The command skips invisible removal
|
|
|
|
The normal behavior is to skip diffusion when no supported local signal is
|
|
found. A missing signal does not prove that the image is clean. If you know the
|
|
image came from a relevant generator, use `--force`.
|
|
|
|
If the CLI reports that the removal dependencies are unavailable, install the
|
|
`qwen-zimage` extra. `diffusion` alone covers Torch and Diffusers but not the
|
|
DiffSynth face stage that all profiles run. Video SynthID removal is a separate
|
|
path and needs `video` and `diffusion`.
|