nathanatgit/shalielie/photographic-style-port

Photographic Style Port

CLI that rewrites a HEIC's metadata so Apple Photos offers the Photographic Styles palette, plus iOS 27's Texture/Grain controls. Pixels are never altered — the decoded output is identical to the input.

patch picks its route from the photo itself:

• No style data (iPhones before the iPhone 16, or a re-saved copy): full port, plus Texture/Grain.
• Native style data (iPhone 16/17): nothing is ported; only the Texture/Grain items are

added and every existing payload stays byte-identical. add-texture IN OUT does the same explicitly.

• Already has Texture/Grain (iPhone 18 / iOS 27): refused — nothing to do.

Before the first run

Locate photographic_style_port.py in the project, then check which mode is available:

command -v ffmpeg heif-convert     # both present -> default mode

On Windows the repo's tools/ directory supplies heif-convert; add it to PATH first: $env:PATH = "$PWD\tools;$env:PATH".

Run uv sync once if .venv is missing. Invoke as uv run photographic_style_port.py ..., or python photographic_style_port.py ... if the project has no uv setup — the script itself is standard-library only.

Choosing a mode

Do not install ffmpeg or libheif without asking — the no-encoder mode is a complete fallback, not a degraded one.

Running

uv run photographic_style_port.py patch IN.HEIC OUT.HEIC

Exit code 0 means success, and a summary goes to stdout. The output HEIC is the only file written unless you ask for more — add --report for a machine-readable OUT.HEIC.report.json, which is worth doing when you need to verify the result rather than just report it. Useful fields:

• output_sha256 — identifies the result
• linear_thumb_mode — generate or reuse-thumbnail
• mattes_transplanted / mattes_added — Portrait data carried over
• texture_styles — whether the iOS 27 Texture/Grain set was added (--texture off skips it)
• thumbnail — target, or synthesized when the photo had none and one was encoded
• warnings — non-fatal issues worth relaying to the user

For batches, loop one file at a time and report per-file outcomes; there is no batch mode and a failure on one photo says nothing about the next.

Do not leave report or ZIP files in the user's directories unless they asked for them, and clean up any --report output you generated purely for your own verification.

Errors

Other commands

uv run photographic_style_port.py profiles              # built-in donor profiles, as JSON
uv run photographic_style_port.py inspect PHOTO.HEIC    # style-related metadata, as JSON
uv run photographic_style_port.py add-texture IN.HEIC OUT.HEIC   # native style photo -> + Texture/Grain

Use inspect before patching when diagnosing why a photo behaves unexpectedly.

Rules

• Never write the output over the input, and never patch a file in place. These are

irreplaceable photos and the tool is experimental.

• Do not delete or move the user's originals, including after a successful patch.
• Tell the user that transferring the result to an iPhone must be done as a file. Going

through the Photo Library converts HEIC to JPEG and discards everything this tool adds.

• Results are not validated by Apple and vary by photo. Report what the tool did; do not

promise that the palette will appear.