amurcloak 0.10.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- amurcloak-0.10.0/.gitignore +24 -0
- amurcloak-0.10.0/LICENSE +21 -0
- amurcloak-0.10.0/PKG-INFO +445 -0
- amurcloak-0.10.0/README.md +413 -0
- amurcloak-0.10.0/assets/logo.svg +40 -0
- amurcloak-0.10.0/assets/modes.png +0 -0
- amurcloak-0.10.0/assets/screenshot-app.png +0 -0
- amurcloak-0.10.0/assets/screenshot-dark.png +0 -0
- amurcloak-0.10.0/pyproject.toml +130 -0
- amurcloak-0.10.0/requirements.txt +12 -0
- amurcloak-0.10.0/src/amurcloak/__init__.py +11 -0
- amurcloak-0.10.0/src/amurcloak/__main__.py +6 -0
- amurcloak-0.10.0/src/amurcloak/app.py +740 -0
- amurcloak-0.10.0/src/amurcloak/cli.py +127 -0
- amurcloak-0.10.0/src/amurcloak/engine/__init__.py +8 -0
- amurcloak-0.10.0/src/amurcloak/engine/detector.py +383 -0
- amurcloak-0.10.0/src/amurcloak/engine/photo.py +515 -0
- amurcloak-0.10.0/src/amurcloak/engine/pipeline.py +172 -0
- amurcloak-0.10.0/src/amurcloak/engine/presets.py +344 -0
- amurcloak-0.10.0/src/amurcloak/engine/redact.py +317 -0
- amurcloak-0.10.0/src/amurcloak/engine/sessions.py +1122 -0
- amurcloak-0.10.0/src/amurcloak/engine/video/__init__.py +14 -0
- amurcloak-0.10.0/src/amurcloak/engine/video/probe.py +222 -0
- amurcloak-0.10.0/src/amurcloak/engine/video/render.py +346 -0
- amurcloak-0.10.0/src/amurcloak/engine/video/track.py +310 -0
- amurcloak-0.10.0/src/amurcloak/models/LICENSE +21 -0
- amurcloak-0.10.0/src/amurcloak/models/face_detection_yunet_2023mar.onnx +0 -0
- amurcloak-0.10.0/src/amurcloak/static/app.js +1428 -0
- amurcloak-0.10.0/src/amurcloak/static/style.css +1084 -0
- amurcloak-0.10.0/src/amurcloak/templates/index.html +226 -0
- amurcloak-0.10.0/tests/__init__.py +0 -0
- amurcloak-0.10.0/tests/build_clip.py +63 -0
- amurcloak-0.10.0/tests/fixtures/lena.jpg +0 -0
- amurcloak-0.10.0/tests/roundtrip_live.py +114 -0
- amurcloak-0.10.0/tests/test_api.py +892 -0
- amurcloak-0.10.0/tests/test_engine.py +766 -0
- amurcloak-0.10.0/tests/test_video.py +752 -0
- amurcloak-0.10.0/uv.lock +581 -0
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
# Python
|
|
2
|
+
.venv/
|
|
3
|
+
__pycache__/
|
|
4
|
+
*.pyc
|
|
5
|
+
|
|
6
|
+
# Build output. `uv build` writes its own self-ignoring dist/.gitignore; these
|
|
7
|
+
# cover the other tools and the sdist's egg-info.
|
|
8
|
+
dist/
|
|
9
|
+
build/
|
|
10
|
+
*.egg-info/
|
|
11
|
+
|
|
12
|
+
# Runtime scratch space for the --tmp flag. The default temp root now lives in
|
|
13
|
+
# the system temp directory, so this only appears if --tmp points back here.
|
|
14
|
+
.tmp/
|
|
15
|
+
|
|
16
|
+
# Rebuilt on demand by the fixture builders in tests/test_engine.py,
|
|
17
|
+
# so the generated fixtures are not worth tracking.
|
|
18
|
+
tests/fixtures/gen/
|
|
19
|
+
|
|
20
|
+
# Browser-verification scratch
|
|
21
|
+
.playwright-mcp/
|
|
22
|
+
|
|
23
|
+
# macOS
|
|
24
|
+
.DS_Store
|
amurcloak-0.10.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Ahmad170412
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,445 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: amurcloak
|
|
3
|
+
Version: 0.10.0
|
|
4
|
+
Summary: Local face redaction for photos and short clips. Nothing leaves this machine.
|
|
5
|
+
Project-URL: Homepage, https://github.com/Ahmad170412/AmurCloak
|
|
6
|
+
Project-URL: Repository, https://github.com/Ahmad170412/AmurCloak
|
|
7
|
+
Project-URL: Issues, https://github.com/Ahmad170412/AmurCloak/issues
|
|
8
|
+
Project-URL: Changelog, https://github.com/Ahmad170412/AmurCloak/releases
|
|
9
|
+
Author: Ahmad170412
|
|
10
|
+
License-Expression: MIT
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Keywords: face-detection,heic,offline,photos,privacy,redaction
|
|
13
|
+
Classifier: Environment :: Web Environment
|
|
14
|
+
Classifier: Intended Audience :: End Users/Desktop
|
|
15
|
+
Classifier: Operating System :: MacOS
|
|
16
|
+
Classifier: Operating System :: Microsoft :: Windows
|
|
17
|
+
Classifier: Operating System :: POSIX :: Linux
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
22
|
+
Classifier: Topic :: Multimedia :: Graphics
|
|
23
|
+
Classifier: Topic :: Security
|
|
24
|
+
Requires-Python: >=3.11
|
|
25
|
+
Requires-Dist: flask>=3.0
|
|
26
|
+
Requires-Dist: imageio-ffmpeg>=0.5
|
|
27
|
+
Requires-Dist: numpy>=1.26
|
|
28
|
+
Requires-Dist: opencv-python-headless>=4.10
|
|
29
|
+
Requires-Dist: pillow-heif>=0.16
|
|
30
|
+
Requires-Dist: pillow>=10.0
|
|
31
|
+
Description-Content-Type: text/markdown
|
|
32
|
+
|
|
33
|
+
<div align="center">
|
|
34
|
+
|
|
35
|
+
<img src="assets/logo.svg" alt="AmurCloak logo" width="320"/>
|
|
36
|
+
|
|
37
|
+
# AmurCloak
|
|
38
|
+
|
|
39
|
+
**Find every face in a photo or short clip and cover it — on your own machine, with the network unplugged.**
|
|
40
|
+
|
|
41
|
+
No uploads, no accounts, no telemetry. Drop photos in, check the map, download redacted copies.
|
|
42
|
+
|
|
43
|
+
[](https://www.python.org/)
|
|
44
|
+
[](#requirements)
|
|
45
|
+
[](#quick-start)
|
|
46
|
+
[](#testing)
|
|
47
|
+
[](LICENSE)
|
|
48
|
+
[](#requirements)
|
|
49
|
+
[](#why-amurcloak)
|
|
50
|
+
[](src/amurcloak/models/)
|
|
51
|
+
|
|
52
|
+
[Quick Start](#quick-start) · [Features](#features) · [Configuration](#configuration) · [Testing](#testing) · [Report a bug](https://github.com/Ahmad170412/AmurCloak/issues) · [Request a feature](https://github.com/Ahmad170412/AmurCloak/issues)
|
|
53
|
+
|
|
54
|
+
</div>
|
|
55
|
+
|
|
56
|
+
---
|
|
57
|
+
|
|
58
|
+
## Why AmurCloak?
|
|
59
|
+
|
|
60
|
+
- **Your photos never leave the machine.** There is no server to upload to, no cloud API behind a spinner, and no outbound request anywhere in the runtime — the only socket the program opens is a loopback check of its own port, to tell "already running" apart from "free port". You can pull the network cable out mid-batch and nothing changes.
|
|
61
|
+
- **One detection pass is not enough for group photos.** A single frame inference reliably misses the small faces at the back of a crowd. AmurCloak also scans overlapping tiles and merges the results — on the 10-face test fixture that is the difference between finding 1 face and finding 4.
|
|
62
|
+
- **The default mode is the one that cannot be undone.** Solid black destroys the pixels. Pixelate and blur are *partially reversible* and are labelled as such in the interface, because "AI un-pixelation" is a real and published technique.
|
|
63
|
+
- **It costs you nothing to leave running.** Every transient byte lives under one temp root: batches stream into a ZIP one file at a time, staged inputs are freed the moment you download, and a reaper clears idle sessions. Steady-state disk usage is zero.
|
|
64
|
+
|
|
65
|
+
---
|
|
66
|
+
|
|
67
|
+
## What it looks like
|
|
68
|
+
|
|
69
|
+
The default mode, next to the two softer ones — so the trade-off is visible rather than assumed:
|
|
70
|
+
|
|
71
|
+

|
|
72
|
+
|
|
73
|
+
The **audit map** shows you what was found before you commit to anything. If a face is visible here, you know it is covered; if someone is missed, you can see that too and switch to a more aggressive preset:
|
|
74
|
+
|
|
75
|
+

|
|
76
|
+
|
|
77
|
+
The same workspace after dark, switched to the result view. It follows your system until you choose a side, remembers the choice, and settles the theme before the first paint so the page never flashes the wrong one:
|
|
78
|
+
|
|
79
|
+

|
|
80
|
+
|
|
81
|
+
---
|
|
82
|
+
|
|
83
|
+
## Table of Contents
|
|
84
|
+
|
|
85
|
+
- [Why AmurCloak?](#why-amurcloak)
|
|
86
|
+
- [What it looks like](#what-it-looks-like)
|
|
87
|
+
- [Quick Start](#quick-start)
|
|
88
|
+
- [Architecture](#architecture)
|
|
89
|
+
- [Features](#features)
|
|
90
|
+
- [Installation](#installation)
|
|
91
|
+
- [Configuration](#configuration)
|
|
92
|
+
- [Usage](#usage)
|
|
93
|
+
- [Testing](#testing)
|
|
94
|
+
- [Repository Structure](#repository-structure)
|
|
95
|
+
- [Contributing](#contributing)
|
|
96
|
+
- [License](#license)
|
|
97
|
+
|
|
98
|
+
---
|
|
99
|
+
|
|
100
|
+
## Quick Start
|
|
101
|
+
|
|
102
|
+
**One paste.** This installs [uv](https://docs.astral.sh/uv/) — which brings its own Python — and then AmurCloak itself, straight from a release. The `export` is there so it works in the terminal you already have open, with no restart:
|
|
103
|
+
|
|
104
|
+
```bash
|
|
105
|
+
curl -LsSf https://astral.sh/uv/install.sh | sh && export PATH="$HOME/.local/bin:$PATH" && uv tool install https://github.com/Ahmad170412/AmurCloak/releases/latest/download/amurcloak-0.9.0-py3-none-any.whl
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
Windows, in PowerShell — same idea:
|
|
109
|
+
|
|
110
|
+
```powershell
|
|
111
|
+
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"; $env:Path = "$env:USERPROFILE\.local\bin;$env:Path"; uv tool install https://github.com/Ahmad170412/AmurCloak/releases/latest/download/amurcloak-0.9.0-py3-none-any.whl
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
**Then, forever after:**
|
|
115
|
+
|
|
116
|
+
```bash
|
|
117
|
+
amurcloak
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
That wheel is the entire install — one file, and the same one on macOS, Windows and Linux, with every dependency resolved for your machine. GitHub Releases is the only published channel for now; AmurCloak is not on PyPI yet.
|
|
121
|
+
|
|
122
|
+
It takes the first free port from 5000, opens your browser, and stops on Control-C. Run it a second time and it notices the copy already running instead of starting another server.
|
|
123
|
+
|
|
124
|
+
The URL names the version on purpose, so moving to a later release means re-running the install command with that release's filename — see [Install](#install). `uv tool upgrade amurcloak` does not cross versions for a URL install.
|
|
125
|
+
|
|
126
|
+
No API keys, no configuration files, no model download — the detector ships inside the package.
|
|
127
|
+
|
|
128
|
+
---
|
|
129
|
+
|
|
130
|
+
## Architecture
|
|
131
|
+
|
|
132
|
+
A single process, one request at a time, no queue and no worker pool:
|
|
133
|
+
|
|
134
|
+
```text
|
|
135
|
+
photo
|
|
136
|
+
│
|
|
137
|
+
▼
|
|
138
|
+
┌─────────────┐ EXIF orientation applied, ICC profile kept,
|
|
139
|
+
│ decode │ everything else discarded
|
|
140
|
+
└──────┬──────┘
|
|
141
|
+
▼
|
|
142
|
+
┌─────────────┐ YuNet (227 KB ONNX, via OpenCV's DNN module)
|
|
143
|
+
│ detect ├──▶ full-frame pass
|
|
144
|
+
└──────┬──────┘ └─▶ + overlapping tiles when the long edge is large
|
|
145
|
+
▼ └─▶ NMS, with edge-touching hits ranked down
|
|
146
|
+
┌─────────────┐
|
|
147
|
+
│ mask │ ellipse fitted and roll-aligned to the face from
|
|
148
|
+
└──────┬──────┘ the five detected landmarks — not a circle
|
|
149
|
+
▼
|
|
150
|
+
┌─────────────┐ black · opaque, irreversible
|
|
151
|
+
│ redact │ pixelate · mosaic blocks, partly reversible
|
|
152
|
+
└──────┬──────┘ blur · Gaussian, partly reversible
|
|
153
|
+
▼ faces you left visible are passed through untouched
|
|
154
|
+
┌─────────────┐ alpha → PNG .heic/.heif → JPEG
|
|
155
|
+
│ encode │ .png → PNG everything else → JPEG q95
|
|
156
|
+
└──────┬──────┘ .tif/.tiff → TIFF
|
|
157
|
+
▼ EXIF dropped, or a forged block written in its place
|
|
158
|
+
single file, or a ZIP streamed one entry at a time
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
**Colour order is BGR throughout the engine** (OpenCV's convention) and is converted only at the file boundary, so no module has to guess.
|
|
162
|
+
|
|
163
|
+
---
|
|
164
|
+
|
|
165
|
+
## Features
|
|
166
|
+
|
|
167
|
+
| Feature | Description |
|
|
168
|
+
|---|---|
|
|
169
|
+
| **Short clips** | Redact faces in short video clips, with the cover following the face across frames; audio kept or dropped on request. |
|
|
170
|
+
| **Three redaction modes** | Solid black, pixelate, and blur — with an honest note on which are reversible. |
|
|
171
|
+
| **Tiled detection** | Overlapping crops recover small faces that a single full-frame pass misses. |
|
|
172
|
+
| **Audit map** | Annotated preview with numbered boxes, landmark-fitted ellipses, and per-face confidence, so you can verify coverage before rendering. |
|
|
173
|
+
| **Roll-aware mask** | The ellipse is aligned to the eye line, so it follows a tilted head instead of clipping the chin. |
|
|
174
|
+
| **Metadata stripping** | EXIF, XMP, IPTC and GPS are dropped by default. The ICC profile is kept, so iPhone Display P3 colours survive. |
|
|
175
|
+
| **Leave one person visible** | Click any covered face in the preview to give that person their pixels back — the person waving behind the birthday cake stays in the photo. Per photo, and never matched across a batch. |
|
|
176
|
+
| **Forged metadata (opt-in)** | Leave stripped, or write a deliberately false block instead: a chosen date on all three timestamp tags, a made-up camera, and a location fixed to the emptiest point in the Pacific — built from nothing, so no thumbnail and no maker notes from the original can tag along. |
|
|
177
|
+
| **Light and dark** | One workspace at two exposures, chosen with the toggle in the top bar. It follows your system until you pick a side, then remembers. The theme is settled before the first paint, so there is no flash, and every text-on-background pair in both themes clears WCAG AA. |
|
|
178
|
+
| **HEIC support** | iPhone photos work directly, via `pillow-heif`. |
|
|
179
|
+
| **Nine input extensions** | `.bmp`, `.heic`, `.heif`, `.jpeg`, `.jpg`, `.png`, `.tif`, `.tiff`, `.webp` — outputs keep the original format. |
|
|
180
|
+
| **Streaming batches** | Outputs are appended to a `ZIP_STORED` archive and unlinked as they go, so a batch never exists twice on disk. |
|
|
181
|
+
| **Automatic cleanup** | Idle sessions are reaped, inputs are freed on download, and orphans are purged at startup. |
|
|
182
|
+
| **No outbound network** | No CDN, no webfonts, no telemetry, no cloud API. The interface is plain HTML, CSS and JavaScript with no build step. |
|
|
183
|
+
|
|
184
|
+
---
|
|
185
|
+
|
|
186
|
+
## Installation
|
|
187
|
+
|
|
188
|
+
### Requirements
|
|
189
|
+
|
|
190
|
+
- **Python 3.11 or newer.** uv supplies one if you do not have it, which matters: a clean macOS ships a 3.9 stub with a 2021-era pip that cannot install these dependencies.
|
|
191
|
+
- **macOS, Windows or Linux.** The package is pure Python (`py3-none-any`), so one 251 KB wheel covers all three. The platform-specific weight comes from OpenCV's own published wheels, fetched per machine.
|
|
192
|
+
- **~250 MB on first run**, almost all of it OpenCV, into uv's shared cache. Reinstalling, or any other uv project, reuses it.
|
|
193
|
+
- **One download, ever.** After the first run the command works with the network off.
|
|
194
|
+
|
|
195
|
+
Six dependencies, all prebuilt wheels, none of them a framework:
|
|
196
|
+
|
|
197
|
+
| Package | Why |
|
|
198
|
+
|---|---|
|
|
199
|
+
| `opencv-python-headless` | DNN inference for YuNet, plus resize/blur/pixelate |
|
|
200
|
+
| `numpy` | the pixel maths |
|
|
201
|
+
| `flask` | the local web interface |
|
|
202
|
+
| `pillow` | decode, encode, EXIF |
|
|
203
|
+
| `pillow-heif` | iPhone HEIC/HEIF |
|
|
204
|
+
| `imageio-ffmpeg` | static ffmpeg binary for muxing clip audio and H.264 output |
|
|
205
|
+
|
|
206
|
+
Deliberately absent: **PyTorch** and **onnxruntime**. YuNet runs through the DNN module OpenCV already ships, which is why the model is 227 KB instead of hundreds of megabytes. The one native binary that is present, ffmpeg, arrives inside the `imageio-ffmpeg` wheel rather than from the system, so the runtime network posture is unchanged.
|
|
207
|
+
|
|
208
|
+
### Install
|
|
209
|
+
|
|
210
|
+
The Quick Start above is the whole thing. Two other routes, if you want them:
|
|
211
|
+
|
|
212
|
+
```bash
|
|
213
|
+
git clone https://github.com/Ahmad170412/AmurCloak.git
|
|
214
|
+
cd AmurCloak && uv tool install . # from a checkout
|
|
215
|
+
uv tool install dist/amurcloak-0.9.0-py3-none-any.whl # from a wheel you built
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
Re-running the Quick Start install command with the new version's wheel filename upgrades in place; `uv tool install` replaces the existing environment. Removing is one command:
|
|
219
|
+
|
|
220
|
+
```bash
|
|
221
|
+
uv tool uninstall amurcloak
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
`uv tool upgrade amurcloak` is deliberately not the upgrade instruction here. uv remembers the exact requirement an install was given, and a URL names `0.9.0` — so an upgrade would keep resolving `0.9.0` rather than looking for a newer release. If AmurCloak is published to PyPI later, both `uv tool install amurcloak` and `uv tool upgrade amurcloak` will work as usual.
|
|
225
|
+
|
|
226
|
+
`uv tool install` gives each tool its own isolated environment and drops a small shim on your `PATH`. It does not touch your system Python, and uninstalling leaves nothing behind.
|
|
227
|
+
|
|
228
|
+
### Working on the source
|
|
229
|
+
|
|
230
|
+
The package lives under `src/`, so it imports without being installed:
|
|
231
|
+
|
|
232
|
+
```bash
|
|
233
|
+
uv run python -m amurcloak
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
`requirements.txt` carries the same pins for anyone using plain `pip` instead of uv.
|
|
237
|
+
|
|
238
|
+
### Verify the model
|
|
239
|
+
|
|
240
|
+
The detector is vendored inside the package, and its checksum is verified on startup:
|
|
241
|
+
|
|
242
|
+
```bash
|
|
243
|
+
shasum -a 256 src/amurcloak/models/face_detection_yunet_2023mar.onnx
|
|
244
|
+
# 8f2383e4dd3cfbb4553ea8718107fc0423210dc964f9f4280604804ed2552fa4
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
---
|
|
248
|
+
|
|
249
|
+
## Configuration
|
|
250
|
+
|
|
251
|
+
Everything is a command-line flag. There are no environment variables and no config file.
|
|
252
|
+
|
|
253
|
+
```bash
|
|
254
|
+
amurcloak [flags]
|
|
255
|
+
```
|
|
256
|
+
|
|
257
|
+
Running `amurcloak` with no flags picks the port and opens the browser — that is the intended way to use it. The flags exist for the corners.
|
|
258
|
+
|
|
259
|
+
| Flag | Default | Notes |
|
|
260
|
+
|---|---|---|
|
|
261
|
+
| `--host` | `127.0.0.1` | Bind address. Localhost only — do not expose this. |
|
|
262
|
+
| `--port` | first free from `5000` | Pass one explicitly to pin it. |
|
|
263
|
+
| `--tmp` | the system temp directory | Where uploads and renders are staged. Never inside the package. |
|
|
264
|
+
| `--no-open` | off | Do not open the browser. For SSH, scripts and headless runs. |
|
|
265
|
+
| `--ttl` | `1800` | Seconds of inactivity before a session is reaped. |
|
|
266
|
+
| `--max-age` | `21600` | Hard limit on a session's age, in seconds. |
|
|
267
|
+
| `--shred` | off | Zero-fill temp files before unlinking. Slower; costs a full write pass. |
|
|
268
|
+
| `--keep-inputs` | off | Keep staged uploads after download instead of freeing them. |
|
|
269
|
+
| `--allow-download` | off | Permit a one-time model fetch if the vendored model is missing. |
|
|
270
|
+
| `--debug` | off | Flask debug mode. |
|
|
271
|
+
|
|
272
|
+
### Limits
|
|
273
|
+
|
|
274
|
+
| Limit | Value |
|
|
275
|
+
|---|---|
|
|
276
|
+
| Files per batch | 300 |
|
|
277
|
+
| Single file | 200 MB |
|
|
278
|
+
| Total per upload | 1.5 GB |
|
|
279
|
+
| Free-space guard | 3× the upload, plus 512 MB headroom |
|
|
280
|
+
|
|
281
|
+
An upload that will not fit is refused **before** anything is written, and the error states the reason.
|
|
282
|
+
|
|
283
|
+
---
|
|
284
|
+
|
|
285
|
+
## Usage
|
|
286
|
+
|
|
287
|
+
### The interface
|
|
288
|
+
|
|
289
|
+
The page is three columns and the rule never changes: your **photos and the export button** on the left, the **picture** in the middle, and **every setting** on the right, in the order you would reach for them — how hard to look, how to cover, how wide, and what the file claims. The left column's button is the only primary action, and it stays put: it becomes Redact, then the progress bar, then Download, in the same place every time.
|
|
290
|
+
|
|
291
|
+
1. **Drop photos** anywhere on the page, paste a screenshot, or click **Choose photos**.
|
|
292
|
+
2. **Check the audit map.** Every detection is numbered and scored. Switch to **Result** to see the actual redaction.
|
|
293
|
+
3. **Leave someone visible, if you want to.** Click a covered face to give that person their pixels back; click again to cover them.
|
|
294
|
+
4. **Pick a cover mode.** Solid black is selected by default. Adjust **Coverage** to push the mask further past the face, and **Strength** to change the blur or block size — the latter is disabled in black mode, because solid black ignores it.
|
|
295
|
+
5. **Choose how hard to look.** Cautious, Balanced or Thorough, which trades false positives against missed faces.
|
|
296
|
+
6. **Decide what the file says about itself.** **Removed** drops all metadata; **Forged** replaces it with a date you choose, a made-up camera and a location in the middle of the ocean.
|
|
297
|
+
7. **Redact photos**, then **Download**. One photo downloads as a single image; several are bundled into a ZIP.
|
|
298
|
+
|
|
299
|
+
Settings apply to the whole staged set, and changing any of them — or leaving a different set of faces visible — invalidates a rendered result rather than letting you download pixels that no longer match what is on screen.
|
|
300
|
+
|
|
301
|
+
A batch is held in the running server's memory, so quitting `amurcloak` — or leaving a batch untouched past `--ttl` — clears it. The page notices and asks for the photos again rather than leaving a stale preview up, which matters because a frame that no longer matches its settings is worse than no frame at all.
|
|
302
|
+
|
|
303
|
+
### Leaving someone visible
|
|
304
|
+
|
|
305
|
+
Every face starts covered, which is the only safe default. Click a face in the preview — the audit map and the result view carry the same click targets — and that person keeps their own pixels in the export. The ring turns green with a `visible` tag under it; click again to cover them, or **Cover everyone again** to reset the photo.
|
|
306
|
+
|
|
307
|
+
Three details are deliberate:
|
|
308
|
+
|
|
309
|
+
- **It is per photo.** Faces are never matched across a batch. Two photos of the same person are two independent decisions, because the alternative is exactly the face recognition this tool exists to avoid.
|
|
310
|
+
- **The decision is not painted into the image.** The green ring and the tag are browser overlays. Nothing in the exported file hints that a face was spared, and the audit map marks a spared face differently for the same reason.
|
|
311
|
+
- **It invalidates a rendered result**, just as changing a setting does, so a download can never disagree with the screen.
|
|
312
|
+
|
|
313
|
+
### Metadata
|
|
314
|
+
|
|
315
|
+
Two policies. The default is the one that says nothing at all:
|
|
316
|
+
|
|
317
|
+
| Policy | What the exported file carries |
|
|
318
|
+
|---|---|
|
|
319
|
+
| **Removed** (default) | No EXIF, no GPS, no XMP, no IPTC, no maker notes, no thumbnail. The ICC profile is kept so the colours are right. |
|
|
320
|
+
| **Forged** | The same stripping, then a false block: the date you choose on `DateTime`, `DateTimeOriginal` and `DateTimeDigitized` alike; `Make`/`Model` set to `Apple`/`iPhone 13`; a full iPhone 13 exposure set — Exif 2.32, the f/1.6 lens, 26 mm-equivalent focal length, exposure time, ISO, colour space and the image's own pixel dimensions; and a location pinned to 48°52′36″S 123°23′36″W — Point Nemo, the most remote point in the ocean, picked precisely so the coordinates can never name a house. |
|
|
321
|
+
|
|
322
|
+
The forged block is **built from nothing rather than copied and edited**, and that detail is the whole design. An EXIF block can carry a *thumbnail*, which is a small copy of the unredacted photo, so a spoofing pass that edited the original's tags would ship the face it had just covered inside the metadata. The tests assert the output holds exactly one JPEG stream and no thumbnail directory.
|
|
323
|
+
|
|
324
|
+
It is also **complete, not just false.** A file that says `Apple / iPhone 13` and then stops is its own kind of tell — no camera records a lens and an aperture and then omits the rest — so the forgery carries what a real iPhone 13 would: `ExifVersion` 0232, the lens model string, the 35 mm-equivalent focal length, exposure time and ISO, the pixel dimensions of the image actually written, and the 72 dpi resolution in IFD0. The rule that governs all of it is internal consistency. Shutter speed and aperture are stored in the logarithmic APEX form, so they are *derived* from the exposure time and f-number rather than guessed — a block whose stated aperture contradicts its own computed one is the loudest thing a forgery can carry — and the tests check that arithmetic, along with the recorded dimensions matching the delivered image.
|
|
325
|
+
|
|
326
|
+
What it is, and is not:
|
|
327
|
+
|
|
328
|
+
- **It is false metadata, not the absence of metadata.** A missing block and a consistent one read differently to a tool that looks — that is a difference in suspicion, not proof either way.
|
|
329
|
+
- **It is not anonymity.** The pixels are what identify a place and a person; all this removes is the file volunteering where and when it was taken.
|
|
330
|
+
- **Most platforms strip EXIF on upload anyway.** It matters for files sent directly — email, chat, a USB stick, a shared folder.
|
|
331
|
+
- **A `.tif` cannot carry any of the nested detail.** Pillow attaches a nested directory only through its own uncompressed writer, and libtiff rejects the offset it produces for a compressed file — which is true of the Exif sub-directory (`EXIFIFDOffset`) exactly as much as the GPS one. Rather than change the archival format's encoding to plant the detail, a spoofed TIFF keeps a flat IFD0: the camera, the resolution and all three timestamps, and nothing deeper.
|
|
332
|
+
- **The default stays `Removed`.** Stamping a false date on a photo is a claim about evidence, so it is something you opt into, not something done for you.
|
|
333
|
+
|
|
334
|
+
### Presets
|
|
335
|
+
|
|
336
|
+
| Preset | Confidence | Smallest face | Inference edge | Use it for |
|
|
337
|
+
|---|---|---|---|---|
|
|
338
|
+
| Cautious | 0.75 | 32 px | 1024 | Fewest false positives. Solo portraits. |
|
|
339
|
+
| **Balanced** | 0.65 | 24 px | 1024 | The default. Confident hits plus a tiled scan. |
|
|
340
|
+
| Thorough | 0.45 | 16 px | 1280 | Crowds and small faces, at the cost of more false positives. |
|
|
341
|
+
|
|
342
|
+
### Performance
|
|
343
|
+
|
|
344
|
+
Detection is tens of milliseconds on a phone-sized photo, and a few hundred milliseconds on a 24 MP frame with tiling. Rendering is dominated by JPEG encoding, not by the mask.
|
|
345
|
+
|
|
346
|
+
---
|
|
347
|
+
|
|
348
|
+
## Testing
|
|
349
|
+
|
|
350
|
+
Three suites, no test framework, no fixtures to download:
|
|
351
|
+
|
|
352
|
+
```bash
|
|
353
|
+
uv run python tests/test_engine.py # 18/18 — detection, masking, colour, metadata, formats
|
|
354
|
+
uv run python tests/test_api.py # 22/22 — upload, tune, preview, render, download, disk
|
|
355
|
+
uv run python tests/test_video.py # 17/17 — clip probe, tracking, render, audio, end-to-end
|
|
356
|
+
```
|
|
357
|
+
|
|
358
|
+
The API suite drives the real Flask app through its test client, so it covers the actual routes rather than mocks. Its last four checks fetch the page, the script and the stylesheet and compare them against each other.
|
|
359
|
+
|
|
360
|
+
Notable coverage:
|
|
361
|
+
|
|
362
|
+
- Tiling recovers strictly more faces than a single pass on the group fixture.
|
|
363
|
+
- Pixelate and blur **keep the photo's colours** and never composite against black.
|
|
364
|
+
- Solid black writes pure black across the whole masked region.
|
|
365
|
+
- Every facial landmark falls inside the mask.
|
|
366
|
+
- Outputs carry no EXIF, GPS or camera metadata by default, and the ICC profile survives.
|
|
367
|
+
- Restoring one face leaves that face original **and** the others covered, checked against the same ellipse geometry the browser is handed.
|
|
368
|
+
- Restoring everyone hands back the photo's own pixels, exactly — the lossless path in and out.
|
|
369
|
+
- A forged block carries the chosen date on all three timestamp tags, the forged camera, a Point Nemo location and no thumbnail: a source file that arrives carrying a thumbnail of the original comes out with exactly one JPEG stream.
|
|
370
|
+
- The forged block reads as a real capture rather than a stub: the exposure and lens tags are present, the recorded pixel dimensions match the image actually written, and the APEX shutter and aperture values agree with the exposure time and f-number they were derived from.
|
|
371
|
+
- Only a box the detector actually found can be restored; repeating a click does not double-count, junk keys and indices are refused, and a rendered result is discarded when the visible set changes.
|
|
372
|
+
- Changing settings invalidates a stale result.
|
|
373
|
+
- The temp spool survives startup and a real multi-megabyte upload, and the orphan purge spares reserved folders.
|
|
374
|
+
- A batch that loses all but one photo at render still hands that survivor back, as a plain image rather than a zip.
|
|
375
|
+
- A non-finite slider value degrades to the default instead of reaching the mask geometry.
|
|
376
|
+
- The page, the script and the stylesheet agree with each other: every id the controller queries exists in the markup, every column the workspace declares is filled by a pane the page actually uses, the theme is decided before the stylesheet so it cannot flash, and no custom property is used without being defined — and none is defined only for the dark theme.
|
|
377
|
+
|
|
378
|
+
Several of these exist because they were real bugs: an upload that silently failed with a 500, a purge that deleted the directory Werkzeug spools uploads into, a batch that reported "ready" with no file behind it, a `"nan"` margin that could have reached the ellipse maths, and a renamed pane whose stylesheet kept the old class name — which cost the rail its grid area and its divider without a single error being raised.
|
|
379
|
+
|
|
380
|
+
---
|
|
381
|
+
|
|
382
|
+
## Repository Structure
|
|
383
|
+
|
|
384
|
+
```text
|
|
385
|
+
AmurCloak/
|
|
386
|
+
├── README.md
|
|
387
|
+
├── pyproject.toml # metadata, the 5 dependencies, the entry point
|
|
388
|
+
├── requirements.txt # the same pins, for plain pip
|
|
389
|
+
├── src/
|
|
390
|
+
│ └── amurcloak/
|
|
391
|
+
│ ├── __init__.py # version
|
|
392
|
+
│ ├── __main__.py # python -m amurcloak
|
|
393
|
+
│ ├── cli.py # free-port search, already-running check, browser
|
|
394
|
+
│ ├── app.py # Flask routes, config, flags, lifecycle
|
|
395
|
+
│ ├── engine/
|
|
396
|
+
│ │ ├── detector.py # YuNet wrapper: tiling, NMS, ranking
|
|
397
|
+
│ │ ├── redact.py # ellipse geometry, three modes, audit map
|
|
398
|
+
│ │ ├── photo.py # decode/encode, EXIF, metadata policy
|
|
399
|
+
│ │ ├── pipeline.py # full-resolution preview composition
|
|
400
|
+
│ │ ├── presets.py # modes, presets, settings resolution
|
|
401
|
+
│ │ ├── sessions.py # staging, disk accounting, renderer, reaper
|
|
402
|
+
│ │ └── __init__.py
|
|
403
|
+
│ ├── models/
|
|
404
|
+
│ │ └── face_detection_yunet_2023mar.onnx # 227 KB, checksum verified
|
|
405
|
+
│ ├── templates/
|
|
406
|
+
│ │ └── index.html # the single page
|
|
407
|
+
│ └── static/
|
|
408
|
+
│ ├── style.css # the whole stylesheet, both themes as tokens
|
|
409
|
+
│ └── app.js # the whole front end, no build step
|
|
410
|
+
├── assets/ # logo and screenshots
|
|
411
|
+
└── tests/
|
|
412
|
+
├── test_engine.py # 18 tests
|
|
413
|
+
├── test_api.py # 22 tests
|
|
414
|
+
├── test_video.py # 17 tests
|
|
415
|
+
└── fixtures/ # lena.jpg, plus fixtures built on demand
|
|
416
|
+
```
|
|
417
|
+
|
|
418
|
+
---
|
|
419
|
+
|
|
420
|
+
## Contributing
|
|
421
|
+
|
|
422
|
+
This is a private tool, so there is no contribution process to speak of. If you do extend it, six rules keep it honest:
|
|
423
|
+
|
|
424
|
+
1. **Nothing may make an outbound network call at runtime.** That is the entire point of the project. The one request AmurCloak ever makes is a loopback probe of its own port, to tell "already running" apart from "free port" — it is pinned to `127.0.0.1` and deliberately ignores any proxy set in the environment, so it cannot become an outbound request by accident.
|
|
425
|
+
2. **A preview must never disagree with the delivered file.** Previews are composed at full resolution and only then downscaled — shrinking first would change the blur kernel and the block size. It is also why the preview and the export share one face list, restored faces included.
|
|
426
|
+
3. **Never describe a reversible redaction as safe.** If a mode can be partially undone, the interface has to say so.
|
|
427
|
+
4. **Build forged metadata from nothing; never edit the source's tags.** An EXIF block can carry a thumbnail, which is a small copy of the *original* photo — so the obvious "copy the tags and change a few" shortcut would ship the unredacted face inside the metadata of the file that covered it.
|
|
428
|
+
5. **Whatever the forged block claims, make it agree with itself.** A block that is merely sparse is a poor forgery, and a block that contradicts itself is a worse one: derive the APEX shutter and aperture values from the exposure time and f-number instead of guessing them, and record the dimensions of the image you actually wrote.
|
|
429
|
+
6. **Keep `index.html`, `style.css` and `app.js` in agreement, and let the tests hold you to it.** This front end has no build step, so nothing checks the seams: rename a pane, miss one of the three files, and the page still loads — it just quietly loses a control, or a rail loses the grid area that held it in place. The API suite compares the three files against each other for exactly that reason, and is the cheapest way to find out you renamed something twice.
|
|
430
|
+
|
|
431
|
+
Run both suites before committing; they are fast enough that there is no excuse not to.
|
|
432
|
+
|
|
433
|
+
---
|
|
434
|
+
|
|
435
|
+
## License
|
|
436
|
+
|
|
437
|
+
MIT — see [`LICENSE`](LICENSE). Use it, fork it, ship it.
|
|
438
|
+
|
|
439
|
+
One component is somebody else's work: the bundled face detector, `src/amurcloak/models/face_detection_yunet_2023mar.onnx`, is YuNet by Shiqi Yu, licensed separately under MIT. Its notice travels alongside the model at [`src/amurcloak/models/LICENSE`](src/amurcloak/models/LICENSE), which is what redistribution requires.
|
|
440
|
+
|
|
441
|
+
---
|
|
442
|
+
|
|
443
|
+
<div align="center">
|
|
444
|
+
<sub>Built to be used once and trusted: the photos go in, the faces come out covered, and nothing in between leaves the machine.</sub>
|
|
445
|
+
</div>
|