postfx

Theme-based image post-processing & film-emulation pipeline — pure Python, CPU, no GPU.

postfx gives any image a consistent, reusable look — film stocks, cinematic grades, LUTs — defined entirely in YAML. Pick a theme, apply it to one image or a whole folder, and every output shares the same visual identity. It's a compact color/grain/lens pipeline (white balance, tone, split-toning, halation, grain, vignette, LUTs…) built on numpy + opencv that runs on the CPU — no GPU, no ML, no cloud.

The 15 built-in signature themes, applied to one source image (python -m postfx sheet).

Highlights

• Theme = YAML. Code and looks are fully decoupled. 30 themes built in (15 film-stock/industry signature looks, 15 experimental), plus .cube LUT support.
• Pure & deterministic. Every operation is a pure (array, params) -> array function. Same image + theme = byte-identical output (grain seed derives from the filename).
• Resolution-safe. Aspect ratio and resolution are preserved — no crop/resize. Grain and blur radii scale with image size, so a look is identical at any resolution.
• Fast on CPU. ~0.5 s @ 2 MP on a single core; batch mode fans out across cores.
• Three ways in: a postfx CLI, a tiny Python API, and drop-in .cube LUTs.

Install

pip install postfx

or with uv:

uv add postfx          # into a project
uv tool install postfx # as a standalone CLI tool

Quickstart

CLI

# One image or a whole folder (batch = auto-parallel across cores)
postfx run --input photo.jpg --theme portra_400 --condition day_outdoor --out out/

# Preview every signature theme on one image as a labeled grid
postfx sheet --input photo.jpg --out sheet.jpg

# List all themes (grouped by category) and conditions
postfx list

Python

import postfx
from postfx import Theme, Condition

# One-liner: load, process, save. Names are StrEnums — autocomplete + typo-safe.
# (Plain strings like "portra_400" still work everywhere too.)
postfx.process_file("photo.jpg", "graded.jpg",
                    theme=Theme.Signature.CINEMATIC_TEAL_ORANGE,
                    condition=Condition.INDOOR_EVENING, strength=1.0)

# Or work with arrays directly (float32 [0,1] RGB in, same out)
from postfx import load_theme, get_condition, imgio, process

rgb, alpha = imgio.load_image("photo.jpg")
out = process(rgb, load_theme(Theme.Signature.PORTRA_400), get_condition(Condition.DAY_OUTDOOR),
              strength=1.0, seed=imgio.seed_from_path("photo.jpg"))
imgio.save_image("graded.png", out, alpha)

Showcase

One source image (cat.jpg), four different themes — same pipeline, YAML-only difference:

Themes

Themes live under postfx/themes/, grouped into categories. Names are unique across categories, so --theme <name> resolves globally.

Signature (grounded in real film stocks & industry grades)

experimental holds 15 earlier looks. Run postfx list for the full set with descriptions.

LUTs (a LUT is a theme)

A .cube 3D LUT is a selectable look like any other theme. Bundled LUTs live in postfx/themes/luts/ with a small YAML wrapper. To use your own, drop a .cube there with a YAML referencing it — or point any theme's lut.file at an external absolute path. The LUT is applied in display (sRGB) space, with grain/lens/texture on top. See postfx/themes/luts/README.md.

Conditions

A separate axis from the theme. A theme sets the look (color); a condition sets how strongly the capture/optical texture — grain, chroma noise, halation — reads for the situation a shot was taken in, as a multiplier on the theme's own values. So one theme stays consistent across shooting conditions. Select with --condition (default neutral — the theme's texture exactly as authored).

Conditions live under postfx/conditions/ as YAML — add your own exactly the way you'd add a theme. neon_night deliberately blooms harder than night_flash while staying less grainy: the three multipliers are independent, not one slider.

Global strength

--strength 0.0–1.5 linearly blends the whole theme effect with the original: 0 = untouched, 1 = full theme, 1.5 = over. Additive effects like grain scale with it too.

Processing order (fixed)

1 sRGB→linear · 2 white balance (Bradford) · 3 exposure · 4 highlight rolloff · 5 lift/gamma/gain · 6 split toning · 7 tone curve · 8 vibrance+saturation · 9 halation (linear) · 10 linear→sRGB · 10b optional LUT (.cube) · 11 distortion · 12 chromatic aberration · 13 vignette · 14 black point lift · 15 clarity · 16 grain (luminance-weighted) · 17 sharpen · 18 JPEG re-encode (JPEG output only).

Halation must be in linear space, the LUT right after linear→sRGB, grain in sRGB — this order is deliberate and shouldn't be reordered.

Parameter reference

Each theme YAML carries the op blocks below. Omitted keys fall back to a neutral (no-op) default; an unknown key raises an error (so typos fail fast).

Determinism & constraints

• Resolution and aspect ratio are preserved — no crop/resize.
• All intermediate work is float32 in [0,1] RGB; conversion to 8-bit happens only on save. PNG keeps alpha and skips the JPEG step.
• The grain seed derives from the filename hash, so the same image + theme is byte-identical every run.
• No EXIF/metadata is written to outputs.

Adding a theme

Add postfx/themes/<category>/<name>.yaml. The first comment lines are the name / character / suited content; parameters follow (see the table above). Then verify with postfx sheet + pytest.

# my_look
# Warm, low-contrast, soft — a gentle everyday grade.
name: my_look
white_balance: { temp: 0.12, tint: 0.02 }
tone_curve: { strength: 0.15, pivot: 0.45 }
vibrance: { vibrance: 0.1, saturation: 1.03 }
grain: { luma: 0.015, size: 1.5 }

Development

git clone https://github.com/0xBeycan/postfx.git
cd postfx
uv sync --extra dev        # or: pip install -e ".[dev]"
uv run pytest -q           # or: pytest -q

License

MIT © 0xBeycan