magicdispel 0.1.0__tar.gz

magicdispel-0.1.0/CHANGELOG.md

@@ -0,0 +1,111 @@
+# Changelog
+
+## 0.1.0 (2026-09-24)
+
+- Command-line package for macOS, Windows and Linux.
+- Local metadata cleaning for JPEG, PNG/APNG, HEIC/HEIF, AVIF, WebP, GIF and TIFF.
+- Lossless BMP-to-PNG conversion and frame/page verification for GIF/APNG/TIFF.
+- Correct handling of lossless and extended WebP format names.
+- MPF/HDR JPEG support with per-image metadata cleaning, HDR preservation and rebuilt indexes.
+- Recognize HEIF and AVIF sequence file types; verify animated AVIF frames and clear container dates.
+- Handle JPEG-compressed TIFF strip aliases and verify all encoded TIFF strips/tiles directly.
+- Image-data hash checks, original preservation and collision-safe output names.
+- Preserve necessary HDR fields while removing recognized HEIF depth/calibration,
+  portrait/semantic masks, thumbnails and editing-only style maps with their actual bytes.
+- Protect shared image dependencies and reject unsupported auxiliary layouts.
+- Remove HEIF XMP toolkit strings and unused item properties.
+- Add `--anonymous` random output filenames with collision protection.
+- Synthetic auxiliary-graph and filename tests, run by CI on macOS, Windows and Linux.
+  The tests need only Pillow; with ExifTool installed they also check each result with it,
+  and CI runs them both ways.
+- Explicit dependency checks and installation documentation.
+- Clean macOS screenshots, whose display profiles carry Apple parametric curves
+  (`aarg`/`aagg`/`aabg`, kept) and display identity/setup tags (`dscm`, `mmod`,
+  `ndin`, `vcgt`, `vcgp`, removed). Previously these files were refused.
+- One-command installers for macOS/Linux (`install.sh`) and Windows (`install.ps1`). They
+  install uv when needed, then MagicDispel, and end by showing the logo. CI runs them on
+  all three systems and cleans a screenshot with the installed command; tagging a version
+  publishes to PyPI through trusted publishing.
+- Rewritten help screen, in English. Running `magicdispel` on its own shows the
+  MagicDispel logo in color with the credits, the tagline and how to use it; outside a
+  terminal, or with `NO_COLOR` set, it is plain text.
+- Regression harness (`scripts/regression.py`) for local sample corpora, with macOS
+  ImageIO/ColorSync render checks and synthetic leak probes (`scripts/make_probes.py`).
+- PNG, APNG and BMP are rebuilt by MagicDispel itself from an allowlist of the chunks
+  needed for display, instead of asking ExifTool to delete known metadata. Private and
+  unknown chunks, C2PA manifests, text, time stamps and data after the image end are
+  now removed; DPI (`pHYs`) and color chunks (`sRGB`, `gAMA`, `cHRM`, `cICP`) are kept,
+  so Retina screenshots keep their size. Compressed image data must hold exactly the
+  image, with no extra bytes. BMP-to-PNG conversion keeps the DPI. These formats no
+  longer need ExifTool, which still double-checks results when installed.
+- JPEG is rebuilt the same way. Decoding segments and HDR data (ISO 21496-1 gain-map
+  metadata, Apple gain curves) are copied unchanged; JFIF, EXIF, XMP, the ICC profile
+  and the MPF index are written afresh with only display fields: orientation, DPI,
+  color space, Apple HDR headroom/gain and recognized gain-map XMP. Comments,
+  IPTC/Photoshop, C2PA, private segments, JFIF and EXIF thumbnails, MPF image IDs and
+  trailing data are removed. JPEG DPI is now kept. iPhone HDR JPEGs render identically
+  in macOS (SDR, HDR and gain maps).
+- WebP and GIF are rebuilt the same way. WebP keeps its image, alpha and animation
+  chunks, a sanitized ICC profile and the orientation; XMP, unknown chunks (including
+  inside animation frames) and trailing data are removed, and files that no longer
+  need the extended header are written in the simple format. GIF keeps images, color
+  tables, frame timing, transparency, the loop count and a sanitized ICC profile;
+  comments, plain-text overlays, XMP and other application extensions are removed.
+  Reserved bits in WebP and GIF headers are cleared.
+- HEIC/HEIF and AVIF are cleaned without ExifTool. EXIF, URI, JUMBF and non-XMP MIME
+  items are removed with their bytes (orientation lives in HEIF's irot/imir); XMP items
+  keep only recognized HDR fields; unknown item types are refused. Top-level boxes
+  other than ftyp, meta, moov and mdat (such as uuid XMP) are emptied in place or
+  dropped from the end; bytes in mdat and idat that no item or sample uses are zeroed.
+  In image sequences, creation/modification times, handler and compressor names, user
+  data and metadata boxes are cleared, and external media references are refused.
+- TIFF is written afresh: each page keeps its image data and the tags needed to decode
+  and show it, with a sanitized ICC profile; EXIF and GPS directories, XMP, IPTC,
+  Photoshop blocks, descriptions, private tags, sub-images and free space are removed.
+  Every byte of the result is accounted for. BigTIFF and old-style JPEG are refused.
+- **ExifTool is no longer required.** Every format is rebuilt by MagicDispel itself;
+  when ExifTool 12.73+ is installed it double-checks each result, and `--check` reports
+  whether that second check is on. The ExifTool-based cleaning pipeline is removed.
+- HEIF items are read by one parser and removed in one pass. Damaged HEIF files are now
+  reported as damaged; boxes in the item container other than the item tables (such as
+  XML boxes) are emptied; image sequences without an item container are accepted; and
+  the check before saving also confirms that no editing image, thumbnail or item name
+  remains.
+- Photos up to 268 megapixels are checked, including 200-megapixel phone photos; larger
+  ones are refused with a message. Previously anything over 179 megapixels stopped the
+  whole batch with a Python error. The pixel comparison now uses the decoded samples at
+  full precision (16-bit included) and hashes them in strips, never copying a whole frame:
+  a 200-megapixel photo is checked in under a second with about 0.9 GB of memory.
+- Multi-picture JPEGs (such as iPhone HDR photos) that ExifTool has added metadata to are
+  accepted. ExifTool leaves the first image's size in the index as it was; that size is no
+  longer relied on, while MagicDispel's own index is still checked exactly.
+- HEIC files that ExifTool's `-all=` has already processed are accepted. ExifTool leaves
+  their EXIF and XMP items in place with no data; such empty metadata items are removed
+  like any other. Previously these files were refused as damaged.
+- Output names leave out the dates, times and timestamps that screenshots, phone cameras
+  and chat apps put in file names, which told when a picture was taken: `Screenshot
+  2026-09-23 at 15.14.15.png` becomes `Screenshot_clean.png`, `IMG_20240501_123456.jpg`
+  becomes `IMG_clean.jpg`, `mmexport1714567890123.jpg` becomes `mmexport_clean.jpg`. The
+  rest of the name stays. `--keep-name` keeps the name as it is.
+- Hardening after an audit with crafted files and 4,000 mutated samples:
+  - HEIF item properties are now allowlisted. Only those needed to decode and show an image
+    stay, and fixed-size ones must have exactly their size. Descriptions (`udes`), creation
+    and modification times (`crtt`, `mdft`), camera parameters and unknown properties were
+    kept before and are now removed. An unknown property marked essential is refused.
+  - RAW photos built on TIFF (DNG, CR2, NEF and others) are refused with a clear message.
+    Before, a DNG was "cleaned" into a copy of its small preview.
+  - TIFF pages must hold exactly the strips or tiles their image needs, uncompressed ones at
+    exactly their size, and kept tags exactly the number of values the specification gives
+    them. Extra strips and values could carry hidden bytes.
+  - PNG palettes and transparency chunks must hold exactly what the color type allows
+    (an oversized tRNS chunk could carry hidden bytes). Images over the pixel limit are
+    refused before any data is inflated, and APNG frames must lie within the image.
+  - Any failure of Pillow's decoders now reads "cannot be decoded to check the result"
+    instead of an unexpected error (damaged AVIF files raised RuntimeError), and Pillow's
+    warnings about damaged files no longer appear in the terminal.
+- ExifTool's second check reads each result from a pipe instead of a temporary file next to
+  the photo. On Windows, a photo in a folder with Chinese or other non-ASCII characters
+  failed the check, because Windows passes paths to ExifTool in its legacy code page.
+- A photo that fails unexpectedly is reported as an unexpected error and no longer stops
+  the rest of a batch. A result its own format cannot read back counts as failing
+  verification.

magicdispel-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MagicDispel contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

magicdispel-0.1.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include LICENSE README.md CHANGELOG.md install.sh install.ps1
+recursive-include docs *.md
+recursive-include tests *.py
+recursive-include scripts *.py
+recursive-exclude * __pycache__ *.pyc .DS_Store

magicdispel-0.1.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: magicdispel
+Version: 0.1.0
+Summary: Clean common photo metadata locally while preserving image quality
+Author: VincentC
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/v1nc3nt-continualab/magicdispel
+Project-URL: Issues, https://github.com/v1nc3nt-continualab/magicdispel/issues
+Project-URL: Source, https://github.com/v1nc3nt-continualab/magicdispel
+Keywords: exif,metadata,photos,privacy,cli
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Pillow>=11.3
+Provides-Extra: test
+Requires-Dist: Pillow>=11.3; extra == "test"
+Dynamic: license-file
+
+# MagicDispel
+
+Remove private metadata from photos on your own computer, without touching image quality.
+
+```console
+magicdispel photo.jpg
+magicdispel "photo one.heic" screenshot.png
+magicdispel --anonymous photo.jpg
+```
+
+Type `magicdispel` and a space, drag one or more photos into the terminal, and press Enter.
+A cleaned copy named `photo_clean.jpg` appears next to each original, without the dates and
+times that screenshots and phone cameras put in names: `Screenshot 2026-09-23 at 15.14.15.png`
+becomes `Screenshot_clean.png`. Originals are never modified and existing files are never
+overwritten: further copies get `_clean_1`, `_clean_2`... `--keep-name` keeps the name as it is;
+`--anonymous` names the copy `photo_<random>.jpg` instead. It changes the name only, not what
+the picture shows.
+
+## How it works
+
+MagicDispel does not hunt for known metadata to delete. It writes a new file from only the
+parts a viewer needs to show the image, such as the compressed pixels, color profile,
+orientation, DPI, transparency, animation timing and HDR gain maps, and leaves everything
+else behind: location, capture time, camera and lens details, author, comments, editing
+software, thumbnails, depth maps and portrait mattes, C2PA manifests, and private or unknown
+data blocks, wherever a format stores them.
+
+- Image data is copied byte for byte. Only BMP is re-encoded, losslessly, as PNG.
+- ICC color profiles keep their color data; their dates become a fixed placeholder
+  (`2000-01-01`), their descriptions `Clean`, and device and creator fields are cleared.
+- Every result is checked before it is saved. The format's rebuilder parses it again on its
+  own; Pillow must decode identical pixels and frames (for HEIC, which Pillow cannot decode,
+  every image item is compared byte for byte instead); and ExifTool, if installed, gives an
+  independent second reading. If any check fails, nothing is saved.
+- Everything happens on your computer: no uploads, telemetry or network access.
+
+**This is not an anonymity tool.** What the picture shows, a match with a copy published
+earlier, or the account it is shared from can still identify people and places. Removing
+depth and style data also limits later portrait, depth-of-field and style edits.
+See [privacy and format details](https://github.com/v1nc3nt-continualab/magicdispel/blob/main/docs/PRIVACY.md).
+
+## Install
+
+One command installs MagicDispel and everything it needs. It uses
+[uv](https://docs.astral.sh/uv/), which brings its own Python when the system has none that fits,
+and ends by showing the MagicDispel logo.
+
+macOS and Linux:
+
+```sh
+curl -LsSf https://raw.githubusercontent.com/v1nc3nt-continualab/magicdispel/main/install.sh | sh
+```
+
+Windows (PowerShell):
+
+```powershell
+powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/v1nc3nt-continualab/magicdispel/main/install.ps1 | iex"
+```
+
+If `magicdispel` is not found afterwards, open a new terminal window.
+
+Already using uv or pipx (Python 3.10 or newer):
+
+```sh
+uv tool install magicdispel
+pipx install magicdispel
+```
+
+To update, run the install command again, or `uv tool upgrade magicdispel`. To remove
+MagicDispel, run `uv tool uninstall magicdispel`.
+
+[ExifTool](https://exiftool.org/) is optional: when version 12.73 or newer is installed,
+MagicDispel uses it to double-check every result. Install it with `brew install exiftool`,
+`sudo apt install libimage-exiftool-perl` or `winget install --exact --id OliverBetz.ExifTool`.
+
+## Usage
+
+```sh
+magicdispel --check
+magicdispel --version
+magicdispel photo.jpg screenshot.png portrait.heic
+magicdispel --anonymous photo.jpg
+magicdispel --keep-name "Screenshot 2026-09-23 at 15.14.15.png"
+magicdispel -- "-filename-starts-with-a-dash.jpg"
+```
+
+Quote paths containing spaces, or drag the files into the terminal. On Windows, drag-and-drop
+depends on the terminal; a quoted path always works. Folders are not processed recursively.
+Run `magicdispel` on its own to see the logo and how to use it. If ExifTool is installed
+somewhere unusual, set `MAGICDISPEL_EXIFTOOL` to its full path.
+
+Exit codes: `0` success or help, `1` one or more files not cleaned, `2` invalid arguments,
+`130` interrupted. A failed file does not stop the rest of a batch.
+
+## Formats
+
+| Format | Kept | Removed |
+| --- | --- | --- |
+| JPEG | image data, JFIF density, orientation, DPI, color space, ICC profile; HDR gain-map images (MPF), Apple HDR headroom and gain-map XMP | other EXIF and XMP, IPTC/Photoshop, comments, C2PA, thumbnails, maker notes, trailing data |
+| PNG, APNG | image data, palette, transparency, color chunks (sRGB, gAMA, cHRM, cICP, HDR), DPI, animation, ICC profile, orientation | text, time stamps, C2PA, private chunks, anything after the end |
+| HEIC, HEIF | image items and tiles, HDR gain maps (Apple and ISO), alpha, orientation, ICC profile, HDR XMP fields | EXIF, other XMP, Apple property lists, depth and calibration, portrait and semantic mattes, style maps, thumbnails, unused data |
+| AVIF | as HEIF, including animations; sequence times, names and user data are cleared | as HEIF |
+| WebP | image data, alpha, animation, ICC profile, orientation | other EXIF, XMP, unknown chunks |
+| GIF | images, palettes, frame timing, transparency, loop count, ICC profile | comments, text overlays, XMP, other extensions |
+| TIFF | image data, decoding tags, DPI, orientation, page numbers, ICC profile | EXIF and GPS directories, XMP, IPTC, Photoshop, descriptions, private tags, sub-images |
+| BMP | converted to lossless PNG with the same pixels, DPI and profile | everything else |
+| RAW, video, PDF | not supported; RAW files built on TIFF (DNG, CR2, NEF...) are recognized and refused | |
+
+Variants that cannot be rebuilt safely, such as BigTIFF, fragmented image sequences or
+unknown HEIF item types, are refused rather than passed through. Images up to 268 megapixels
+are checked (enough for 200-megapixel phone photos); larger ones are refused.
+
+## Development
+
+```sh
+python -m venv .venv
+# Activate the environment for your shell.
+python -m pip install -e ".[test]" build
+python -m unittest discover -s tests -v
+python -m build
+```
+
+The tests need only Pillow. When ExifTool is installed, they also add metadata the way other
+programs write it and let ExifTool double-check each result; CI runs them both ways. No
+personal photos are included.
+
+Before and after any change to the cleaning code, run the regression harness over a folder
+of real sample photos kept outside the repository:
+
+```sh
+python scripts/make_probes.py ~/magicdispel-corpus    # adds synthetic leak probes
+python scripts/regression.py ~/magicdispel-corpus     # saves a run under runs/
+python scripts/regression.py ~/magicdispel-corpus --baseline ~/magicdispel-corpus/runs/<run>.json
+```
+
+It checks that every output looks identical to its input (Pillow, and macOS ImageIO/ColorSync
+when available), that no probe marker survives, and, against a baseline, that no sample
+changes outcome or gains metadata. Pure refactors should also pass `--identical`, and
+`--without-exiftool` checks the path users without ExifTool take.
+
+`.github/workflows/test.yml` runs the tests on macOS, Windows and Linux with Python 3.10 and
+3.13, with and without ExifTool, and the install scripts on all three. `release.yml` publishes a
+tagged version to PyPI once those pass.
+
+## License and attribution
+
+MagicDispel is MIT licensed. [ExifTool](https://exiftool.org/), an optional companion, is
+developed by Phil Harvey and distributed separately under its own license. MagicDispel is not
+affiliated with ExifTool.

magicdispel-0.1.0/README.md

@@ -0,0 +1,149 @@
+# MagicDispel
+
+Remove private metadata from photos on your own computer, without touching image quality.
+
+```console
+magicdispel photo.jpg
+magicdispel "photo one.heic" screenshot.png
+magicdispel --anonymous photo.jpg
+```
+
+Type `magicdispel` and a space, drag one or more photos into the terminal, and press Enter.
+A cleaned copy named `photo_clean.jpg` appears next to each original, without the dates and
+times that screenshots and phone cameras put in names: `Screenshot 2026-09-23 at 15.14.15.png`
+becomes `Screenshot_clean.png`. Originals are never modified and existing files are never
+overwritten: further copies get `_clean_1`, `_clean_2`... `--keep-name` keeps the name as it is;
+`--anonymous` names the copy `photo_<random>.jpg` instead. It changes the name only, not what
+the picture shows.
+
+## How it works
+
+MagicDispel does not hunt for known metadata to delete. It writes a new file from only the
+parts a viewer needs to show the image, such as the compressed pixels, color profile,
+orientation, DPI, transparency, animation timing and HDR gain maps, and leaves everything
+else behind: location, capture time, camera and lens details, author, comments, editing
+software, thumbnails, depth maps and portrait mattes, C2PA manifests, and private or unknown
+data blocks, wherever a format stores them.
+
+- Image data is copied byte for byte. Only BMP is re-encoded, losslessly, as PNG.
+- ICC color profiles keep their color data; their dates become a fixed placeholder
+  (`2000-01-01`), their descriptions `Clean`, and device and creator fields are cleared.
+- Every result is checked before it is saved. The format's rebuilder parses it again on its
+  own; Pillow must decode identical pixels and frames (for HEIC, which Pillow cannot decode,
+  every image item is compared byte for byte instead); and ExifTool, if installed, gives an
+  independent second reading. If any check fails, nothing is saved.
+- Everything happens on your computer: no uploads, telemetry or network access.
+
+**This is not an anonymity tool.** What the picture shows, a match with a copy published
+earlier, or the account it is shared from can still identify people and places. Removing
+depth and style data also limits later portrait, depth-of-field and style edits.
+See [privacy and format details](https://github.com/v1nc3nt-continualab/magicdispel/blob/main/docs/PRIVACY.md).
+
+## Install
+
+One command installs MagicDispel and everything it needs. It uses
+[uv](https://docs.astral.sh/uv/), which brings its own Python when the system has none that fits,
+and ends by showing the MagicDispel logo.
+
+macOS and Linux:
+
+```sh
+curl -LsSf https://raw.githubusercontent.com/v1nc3nt-continualab/magicdispel/main/install.sh | sh
+```
+
+Windows (PowerShell):
+
+```powershell
+powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/v1nc3nt-continualab/magicdispel/main/install.ps1 | iex"
+```
+
+If `magicdispel` is not found afterwards, open a new terminal window.
+
+Already using uv or pipx (Python 3.10 or newer):
+
+```sh
+uv tool install magicdispel
+pipx install magicdispel
+```
+
+To update, run the install command again, or `uv tool upgrade magicdispel`. To remove
+MagicDispel, run `uv tool uninstall magicdispel`.
+
+[ExifTool](https://exiftool.org/) is optional: when version 12.73 or newer is installed,
+MagicDispel uses it to double-check every result. Install it with `brew install exiftool`,
+`sudo apt install libimage-exiftool-perl` or `winget install --exact --id OliverBetz.ExifTool`.
+
+## Usage
+
+```sh
+magicdispel --check
+magicdispel --version
+magicdispel photo.jpg screenshot.png portrait.heic
+magicdispel --anonymous photo.jpg
+magicdispel --keep-name "Screenshot 2026-09-23 at 15.14.15.png"
+magicdispel -- "-filename-starts-with-a-dash.jpg"
+```
+
+Quote paths containing spaces, or drag the files into the terminal. On Windows, drag-and-drop
+depends on the terminal; a quoted path always works. Folders are not processed recursively.
+Run `magicdispel` on its own to see the logo and how to use it. If ExifTool is installed
+somewhere unusual, set `MAGICDISPEL_EXIFTOOL` to its full path.
+
+Exit codes: `0` success or help, `1` one or more files not cleaned, `2` invalid arguments,
+`130` interrupted. A failed file does not stop the rest of a batch.
+
+## Formats
+
+| Format | Kept | Removed |
+| --- | --- | --- |
+| JPEG | image data, JFIF density, orientation, DPI, color space, ICC profile; HDR gain-map images (MPF), Apple HDR headroom and gain-map XMP | other EXIF and XMP, IPTC/Photoshop, comments, C2PA, thumbnails, maker notes, trailing data |
+| PNG, APNG | image data, palette, transparency, color chunks (sRGB, gAMA, cHRM, cICP, HDR), DPI, animation, ICC profile, orientation | text, time stamps, C2PA, private chunks, anything after the end |
+| HEIC, HEIF | image items and tiles, HDR gain maps (Apple and ISO), alpha, orientation, ICC profile, HDR XMP fields | EXIF, other XMP, Apple property lists, depth and calibration, portrait and semantic mattes, style maps, thumbnails, unused data |
+| AVIF | as HEIF, including animations; sequence times, names and user data are cleared | as HEIF |
+| WebP | image data, alpha, animation, ICC profile, orientation | other EXIF, XMP, unknown chunks |
+| GIF | images, palettes, frame timing, transparency, loop count, ICC profile | comments, text overlays, XMP, other extensions |
+| TIFF | image data, decoding tags, DPI, orientation, page numbers, ICC profile | EXIF and GPS directories, XMP, IPTC, Photoshop, descriptions, private tags, sub-images |
+| BMP | converted to lossless PNG with the same pixels, DPI and profile | everything else |
+| RAW, video, PDF | not supported; RAW files built on TIFF (DNG, CR2, NEF...) are recognized and refused | |
+
+Variants that cannot be rebuilt safely, such as BigTIFF, fragmented image sequences or
+unknown HEIF item types, are refused rather than passed through. Images up to 268 megapixels
+are checked (enough for 200-megapixel phone photos); larger ones are refused.
+
+## Development
+
+```sh
+python -m venv .venv
+# Activate the environment for your shell.
+python -m pip install -e ".[test]" build
+python -m unittest discover -s tests -v
+python -m build
+```
+
+The tests need only Pillow. When ExifTool is installed, they also add metadata the way other
+programs write it and let ExifTool double-check each result; CI runs them both ways. No
+personal photos are included.
+
+Before and after any change to the cleaning code, run the regression harness over a folder
+of real sample photos kept outside the repository:
+
+```sh
+python scripts/make_probes.py ~/magicdispel-corpus    # adds synthetic leak probes
+python scripts/regression.py ~/magicdispel-corpus     # saves a run under runs/
+python scripts/regression.py ~/magicdispel-corpus --baseline ~/magicdispel-corpus/runs/<run>.json
+```
+
+It checks that every output looks identical to its input (Pillow, and macOS ImageIO/ColorSync
+when available), that no probe marker survives, and, against a baseline, that no sample
+changes outcome or gains metadata. Pure refactors should also pass `--identical`, and
+`--without-exiftool` checks the path users without ExifTool take.
+
+`.github/workflows/test.yml` runs the tests on macOS, Windows and Linux with Python 3.10 and
+3.13, with and without ExifTool, and the install scripts on all three. `release.yml` publishes a
+tagged version to PyPI once those pass.
+
+## License and attribution
+
+MagicDispel is MIT licensed. [ExifTool](https://exiftool.org/), an optional companion, is
+developed by Phil Harvey and distributed separately under its own license. MagicDispel is not
+affiliated with ExifTool.

magicdispel-0.1.0/docs/PRIVACY.md

@@ -0,0 +1,110 @@
+# Privacy and format details
+
+MagicDispel rebuilds each file from an allowlist: it copies only the parts a viewer needs to
+show the image and leaves everything else behind. It does not search for known metadata to
+delete, so metadata it has never heard of is removed too. It does not promise forensic
+anonymization.
+
+## What is kept, and why
+
+- **Image data.** Compressed pixels are copied byte for byte. BMP is the only format that is
+  re-encoded, losslessly, as PNG.
+- **Color.** ICC profiles keep their color conversion data: matrices, curves, lookup tables,
+  Apple's parametric curves in screenshot profiles, and HDR adaptive curves (with their
+  image-specific identifier cleared). Every profile is rebuilt with the fixed date
+  `2000-01-01 00:00:00` and description `Clean`; creator, maker, model, CMM, platform and profile
+  ID are cleared, and display calibration data is removed. Color declarations of the formats
+  themselves are kept: PNG sRGB, gAMA, cHRM, cICP and HDR chunks, HEIF color boxes.
+- **Display fields.** Orientation, DPI, color space and the DCF interoperability index, written
+  into a fresh EXIF block holding nothing else. For iPhone HDR photos, Apple's HDR headroom and
+  gain, in a fresh maker note holding nothing else.
+- **HDR.** Gain-map images (JPEG multi-picture files, HEIF auxiliary images and ISO `tmap`
+  items), ISO 21496-1 gain-map metadata, Apple gain curves, and recognized numeric gain-map XMP
+  fields.
+- **Structure.** Transparency, animation frames, timing and loop count, TIFF pages and page
+  numbers, and the format's own headers.
+- **The file name**, with `_clean` added and without the dates, times and timestamps that
+  screenshots, cameras and chat apps put in names: `Screenshot 2026-09-23 at 15.14.15.png`
+  becomes `Screenshot_clean.png`, `IMG_20240501_123456.jpg` becomes `IMG_clean.jpg`.
+  `--keep-name` keeps the name as it is; `--anonymous` replaces it with a random 128-bit token
+  that contains no name, time, MAC address or user ID.
+
+## What is removed
+
+Everything not listed above, including: EXIF capture time, camera, lens, serial numbers,
+location and maker notes; XMP (except gain-map fields); IPTC and Photoshop blocks; comments and
+text chunks; C2PA manifests; embedded thumbnails and previews, which may show an uncropped
+original; HEIF depth maps, lens calibration, portrait and semantic mattes, style maps, Apple
+property lists, item names, and item properties such as descriptions, creation times and camera
+parameters; JPEG MPF image IDs; image-sequence creation times, handler and encoder names
+and user data; TIFF EXIF and GPS directories, descriptions, private tags and sub-images; and
+unknown or private data blocks and data after the end of an image.
+
+Removing auxiliary HEIF images limits later portrait, depth-of-field and photographic-style
+edits. Tested HEIC and HDR JPEG files render identically on macOS in SDR and HDR.
+
+## How nothing slips through
+
+- **Rebuild, not delete.** Each format has its own rebuilder (`src/magicdispel/formats/`). Parts
+  with a fixed size must have exactly that size, so they cannot carry extra bytes. PNG image data
+  must inflate to exactly the scanlines the header describes, with nothing after the compressed
+  stream, and its palette and transparency hold exactly what the color type allows. A TIFF page
+  holds exactly the strips or tiles its image needs, uncompressed ones at exactly their size, and
+  every kept tag has exactly the number of values the specification gives it. HEIF item
+  properties are kept only if they say how to decode and show an image. JPEG multi-picture
+  indexes are written fresh.
+- **HEIF in place.** HEIF files are cleaned without moving any image data, so every offset
+  stays valid: the item tables are rewritten in the space they had, removed items and boxes are
+  zero-filled, bytes that no remaining item or sample uses are zeroed, and boxes at the end of
+  the file are dropped. This is why HEIC files do not shrink much.
+- **Fail closed.** Anything that cannot be handled safely is refused, not passed through: an
+  unknown critical PNG chunk, an unknown HEIF item type or auxiliary image, a HEIF property of
+  unknown meaning that readers may not ignore, an image that depends on a removed layer, image
+  groups other than alternatives (such as the stereo pairs of spatial photos), fragmented image
+  sequences, media stored outside the file, BigTIFF, old-style JPEG in TIFF, metadata inside
+  JPEG-compressed TIFF strips, unrecognized ICC tags. RAW photos built on TIFF (DNG, CR2, NEF and
+  others) are refused too: their TIFF pages hold only a preview.
+- **Checked before saving.** The rebuilder parses its own result independently and compares it
+  with what the original should yield: for HEIF, for instance, that every retained image item is
+  byte-identical, XMP holds only gain-map fields, no editing image, thumbnail or item name
+  remains, profiles are sanitized, and unused bytes are zero; for TIFF, that no byte of the file is unaccounted for. Pillow must then decode identical
+  pixels, frames, timing and transparency (all formats but HEIC). If ExifTool 12.73+ is
+  installed, it reads the result as a second opinion, and any warning, private field or data it
+  cannot identify stops the save. The original's hash is compared before and after, so a file
+  changed by another program during cleaning is not published.
+
+## Out of scope
+
+Data hidden inside the compressed image data itself, for example in JPEG scans, VP8 or HEVC
+frames, GIF LZW data or unused palette entries, is copied along with the image. Detecting such
+steganography is beyond this tool.
+
+## File-system information
+
+Outputs are new files containing only the verified bytes. Extended attributes, macOS resource
+forks and Windows alternate data streams of the original are not copied; macOS output
+attributes are cleared, as are Linux `user.` attributes where supported. Normal permissions and
+creation/modification times of the new file are set by the system.
+
+## What this cannot prevent
+
+- Location or identity inferred from what the picture shows: faces, signs, documents,
+  scenery, reflections.
+- Matching the image with a previously published or known original.
+- Identification through the account or service used to share the result.
+- Information a sharing application adds afterwards.
+- Deliberately hidden information, steganography or sensor fingerprinting.
+
+When anonymity matters, share a separate copy and look at what it shows.
+
+## Validation status
+
+On macOS, the unit tests and a local corpus of 60 real and synthetic samples pass: every output
+renders identically in macOS ImageIO/ColorSync (pixels, sRGB and Display P3 renders, SDR, HDR,
+gain maps, orientation and DPI), and 11 synthetic leak probes come out clean. On macOS,
+Windows and Linux, CI runs the unit tests with Python 3.10 and 3.13, with and without ExifTool,
+and installs MagicDispel with the install scripts. Windows and Linux are validated by those
+synthetic tests, not by a corpus of real photos.
+
+References: [ExifTool FAQ](https://exiftool.org/faq.html#Q32),
+[Apple location metadata guidance](https://support.apple.com/guide/personal-safety/ips0d7a5df82/web).

magicdispel-0.1.0/docs/RELEASE_NOTES.md

@@ -0,0 +1,32 @@
+MagicDispel 0.1.0 removes private metadata from photos on your computer, without touching
+image quality.
+
+Install it with one command. On macOS and Linux:
+
+```sh
+curl -LsSf https://raw.githubusercontent.com/v1nc3nt-continualab/magicdispel/main/install.sh | sh
+```
+
+On Windows, in PowerShell:
+
+```powershell
+powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/v1nc3nt-continualab/magicdispel/main/install.ps1 | iex"
+```
+
+Or, with uv or pipx: `uv tool install magicdispel` or `pipx install magicdispel`.
+
+Then type `magicdispel` and a space, drag photos into the terminal, and press Enter. A cleaned
+copy appears next to each original; originals are never modified and nothing is overwritten.
+
+Supported formats: JPEG, PNG/APNG, HEIC/HEIF, AVIF, WebP, GIF, TIFF and BMP. Each file is
+rebuilt from only what is needed to show it, so location, capture time, camera details,
+author, comments, thumbnails, depth maps and portrait mattes, C2PA manifests and unknown data
+blocks are left behind. Image data is copied unchanged (BMP becomes lossless PNG), and color,
+orientation, DPI, transparency, animation and HDR gain maps are kept. The dates and times that
+screenshots and cameras put in file names are left out of the new name. Every result is
+checked before it is saved. ExifTool is optional; when installed, it double-checks each result.
+
+This is not an anonymity tool: what a picture shows can still identify people and places. Read
+the privacy details before sharing sensitive photos.
+
+Tested on macOS, Windows and Linux with Python 3.10 and 3.13.

magicdispel-0.1.0/install.ps1

@@ -0,0 +1,32 @@
+# Install MagicDispel on Windows, from PowerShell:
+#   powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/v1nc3nt-continualab/magicdispel/main/install.ps1 | iex"
+#
+# It installs uv (https://docs.astral.sh/uv/) if needed, which then installs
+# MagicDispel with a Python of its own when the system has none that fits.
+# MAGICDISPEL_NO_MODIFY_PATH=1 leaves the user's PATH alone.
+# MAGICDISPEL_PACKAGE installs something else, such as a local wheel to test.
+$ErrorActionPreference = "Stop"
+
+$package = if ($env:MAGICDISPEL_PACKAGE) { $env:MAGICDISPEL_PACKAGE } else { "magicdispel" }
+$keepPath = $env:MAGICDISPEL_NO_MODIFY_PATH -eq "1"
+
+$uv = (Get-Command uv -ErrorAction SilentlyContinue).Source
+if (-not $uv) {
+    $uv = Join-Path $HOME ".local\bin\uv.exe"
+}
+if (-not (Test-Path $uv)) {
+    Write-Host "Installing uv, which installs MagicDispel and the Python it needs..."
+    if ($keepPath) { $env:UV_NO_MODIFY_PATH = "1" }
+    Invoke-RestMethod https://astral.sh/uv/install.ps1 | Invoke-Expression
+}
+
+Write-Host "Installing MagicDispel..."
+& $uv tool install --upgrade $package
+if ($LASTEXITCODE) { exit $LASTEXITCODE }
+if (-not $keepPath) { & $uv tool update-shell *> $null }
+
+$bin = & $uv tool dir --bin
+& (Join-Path $bin "magicdispel.exe")
+if (($env:PATH -split ";") -notcontains $bin) {
+    Write-Host "  Open a new PowerShell window, then type magicdispel."
+}