A CLI tool for real-estate and architectural photographers who shoot 200+ images per session and publish 10–20 polished finals. ppsp is purpose-built around stack processing: every image is treated as part of an HDR exposure bracket or focus stack, and the tool is designed to handle dozens of stacks in a single automated run. It automates the tedious mechanical work — renaming, organizing, stacking/aligning, fusing, tone-mapping, grading, resizing — while keeping you as the creative director.

This README explains how ppsp can be used, but complementary documents are available:

• guide.md provides a deep-dive into the underlying theory and tools behind ppsp and its built-in presets.
• design.md provides a technical overview of the tool from a developer's perspective.

A typical architectural session produces hundreds of RAW images belonging to dozens of HDR and focus stacks that require a lot of processing steps before results can be shared. The optimum tone-mapping and color-grading parameters are impossible to know upfront, so you end up generating dozens of variants per image. ppsp speeds through that discovery phase at reduced resolution, presents the candidates in labeled collages, then generates only the keepers at full quality — with a single command.

Key design goals:

• Minimize human time. Make every choice among clearly prepared options, not from scratch.
• Minimize processing time. Variant discovery runs at reduced resolution (z25 or z6); full-quality output is generated only for selected results.
• Stateful and resumable. Every step automatically skips outputs that already exist. Pass --redo to force a step to regenerate even existing outputs.
• Verbose and transparent. Elapsed-time logging at every step so you can estimate remaining time. After the project, the logs can be archived along with the final outputs and possibly the original raw data.

Disclaimer: As of 2026-04-19, this tool has been written and used by only one Linux geek with a Sony a7R IV. Feel free to test this, critique it, and contribute to the project!

ppsp wraps standard Linux CLI tools. Install them once:

Ubuntu / Debian:

sudo apt install exiftool dcraw imagemagick hugin-tools luminance-hdr

Python ≥ 3.8.

pip install ppsp

This installs the ppsp command globally.

# Interactive full workflow
ppsp --dir /path/to/shoot/

# Fully automated (no prompts)
ppsp --dir /path/to/shoot/ --batch

Running ppsp without a command flag walks you through all steps interactively. Every step can also be invoked individually. All file-accepting commands default to all matching files under --dir (or the current directory) when no files are given explicitly.

All options — flags that tune command behaviour:

Warning: Three of the uppercase flags are destructive: -P deletes stack directories, -C removes z-tier and variants/ folders, -R forces regeneration of existing outputs.

Normalize all filenames to a canonical scheme and extract full EXIF metadata into ppsp_photos.csv (tab-separated). These two operations always run together: the CSV records both the original filename (SourceFile) and the renamed result (FileName).

ppsp --rename                                                          # all files in current dir
ppsp -r photo1.arw photo2.jpg                                          # specific files
ppsp --rename --default-model "ILCE-7RM4" --default-lens "SEL1635GM"  # EXIF fallbacks

If camera model or lens ID is absent from EXIF and no default is supplied, the placeholder zzz is used (e.g. -m4azzz-).

All files produced by ppsp follow this format throughout the entire pipeline:

YYYYMMDDHHMMSS-CCC[LLL]-NNNN-[chain].[ext]

The chain for original camera files is a single collision-avoidance letter (a, b, c, …), incremented when two files from the same camera, lens, and second would otherwise collide. For processed outputs, the chain is a --separated sequence of stage identifiers in fixed order:

[z-tier]-[enfuse-id]-[tmo-id]-[grading-id][-ct-id]

tmo-id is omitted for focus stacks and pure enfuse outputs. ct-id is optional and only present when a color-temperature preset was applied.

Stack folders use the first image's base name with a -stack suffix initially: 20260416095559-m4azzz-2126-stack/. After running --name (step 6), the -stack suffix is replaced by a 1–6 character shorthand derived from the title (e.g. 20260416095559-m4azzz-2126-bbfdtw/ for "Bedroom B from the door to the window"). Files inside a named stack get the shorthand inserted after NNNN: NNNN-bbfdtw-a.arw, NNNN-bbfdtw-z25-sel4-fatc-dvi1.jpg.

Written by --rename. The StackName column is added and populated by --organize.

Group renamed files into per-stack directories named after the first image in the group, and populate the StackName column in ppsp_photos.csv.

ppsp --organize                                                        # all renamed files
ppsp -o 20260416095559-m4azzz-2126-a.arw 20260416095559-m4azzz-2127-a.arw
ppsp --organize --gap 60                                               # longer gap threshold

Photos are sorted by timestamp. A new stack begins when any of the following signals fires:

Any single signal is sufficient to start a new stack. After grouping, each stack's type is determined by its exposure-compensation spread: more than one distinct rounded EV value → HDR stack (e.g. 0, −2, +2); all at the same EV → focus stack.

Produce one labeled JPG preview per stack in cull/, named <stack-name>_count<N>.jpg.

ppsp --cull

The representative image is chosen in this priority order: a JPG at EV 0 → any JPG → any file at EV 0 (ARW-derived) → middle image of the stack. The representatives are resized to 1920×1080 and annotated in the bottom-center: the image number (NNNN) in large bold, and the frame count (×N) in smaller text below it.

Browse the previews in cull/ and delete the ones for stacks you do not want to keep. When running interactively, ppsp opens the folder automatically with the configured viewer. You can also open it manually:

eog cull/ &

After deleting unwanted previews, run:

ppsp --prune

This deletes the stack directories that no longer have a corresponding preview in cull/ and thus completely eliminates them from further processing.

WARNING: If you have no backups, you will lose the culled images!

Assign a human title to each stack, embed it in EXIF/XMP/IPTC metadata via exiftool, rename the stack folder and all contained files to include a compact shorthand, and maintain ppsp_stacks.csv as the single source of truth for titles and per-stack generate specs.

ppsp --name                                                            # interactive: name all stacks in turn
ppsp -n ppsp_stacks.csv                                                # apply titles from an existing CSV
ppsp -s 2126 -n "Bedroom B from the door to the window"                # inline title for one stack
ppsp -s 2126 2150 -n                                                   # interactive only for two stacks

The shorthand is derived from the title by taking the first character of each non-filler word (articles, conjunctions), lowercased. Spatial prepositions ("from", "to", "by", etc.) are kept because they carry directional meaning in architectural scene titles. "Bedroom B from the door to the window" → bbfdtw.

After renaming, the stack folder changes from NNNN-stack/ to NNNN-{shorthand}/ and every file inside gains the shorthand after NNNN: NNNN-a.arw → NNNN-bbfdtw-a.arw. The --name command is idempotent — running it again on already-named stacks with the same title is a no-op; pass --redo to force re-application.

Created or updated on every --name invocation (tab-separated):

Pass ppsp_stacks.csv to --generate to use per-stack generate specs:

ppsp -g ppsp_stacks.csv

For each surviving stack, convert RAW files at reduced resolution, align the frames, generate the requested variants, annotate each with its full filename, and assemble a collage. Results land in a z-tier subfolder inside each stack directory and are hard-linked into variants/ for easy browsing.

ppsp --discover                                                        # z25, 'some' variants
ppsp -D --stacks 2126                                                  # one specific stack
ppsp --stacks 2126-2200 -D -z z6 -V many --quality 70                  # z6, stacks 2126-2200
ppsp -D -V natu,sel3,fatc,m06p                                         # custom ID selection
ppsp -D -V sel4-fatc-dvi1,sel4-fatc-neut,sel4-m06p-dvi1                # exact chains

Use -V to specify which variants to run and -z to override the resolution tier — see § --variants (-V).

The discovery phase is intentionally educational: instead of showing only fully-processed final images, -D generates chain stub variants at each processing level so you can see exactly what each step contributes.

For every enfuse × TMO combination the pipeline produces three stub levels (plus the CT layer on top):

The GUI's Discover tab steps through these levels one at a time, so each step shows a like-for-like comparison:

• Step 1 (Enfuse): compare sel3.jpg vs sel4.jpg vs sel6.jpg — which fusion setting captures the exposure range best?
• Step 2 (TMO): compare sel4-fatn.jpg vs sel4-m08n.jpg — which tone-mapping operator suits this scene?
• Step 3 (Grading): compare sel4-fatn-neut.jpg vs sel4-fatn-dvi1.jpg — which colour grade to publish?
• Step 4 (CT): optionally add a white-point shift to the chosen grading chain.

You can also mix processing levels freely — for example sel6.jpg (enfuse-only), sel3-fatd.jpg (enfuse+TMO), or sel5-kimd-dvi2-ctw4.jpg (full chain with CT) are all valid outputs that -D and -g can produce or export.

The z-tier label is encoded in every output filename. For -g, the tier is determined by each filename's embedded z-tier (directory/CSV/TXT inputs) or by -z (chain specs / presets; default: z100).

Each preset also includes a default set of grading presets. Variants = (enfuse × gradings) + (enfuse × TMO × gradings) × (no CT + CT IDs).

Flags are passed directly to enfuse:

For focus stacks, a single focu variant is used instead: --contrast-weight=1 --saturation-weight=0 --exposure-weight=0 --hard-mask --contrast-window-size=9.

Invoked via luminance-hdr-cli on the 16-bit TIFF produced by enfuse. The TIFF is passed as a positional argument (not -l, which is for existing .hdr/.exr HDR files). Tuned variants use individual --tmoXxx flags specific to each operator. Requires Luminance HDR v2.6.0.

For each operator, a d-suffix "defaults" variant is listed first (no extra flags — Luminance uses its built-in defaults), followed by tuned variants.

For single-frame stacks (no HDR brackets), enfuse is skipped and tone-mapping runs directly on the converted TIFF, producing a "pseudo-HDR" polish effect.

Note: The author compared the results with these tone-mapping presets with some sample indoor photos taken with the Sony a7R IV, and the following seemed to provide the best results by image content:

Applied via ImageMagick convert as the final stage after fusion/TMO. Warm or cool colour-temperature shifts are handled by the separate CT presets below (combine neut+ctw5 for the old warm look, dvi1+ctw5 for the old dv1w look).

CT presets are an optional chain element appended after grading (ct-id). They apply a white-point shift and per-channel gamma before the grading's sharpening stage. Combine any grading with any CT preset.

Each stack's discovery variants — and all combined intermediates — are written into a z-tier subfolder (z25/ or z6/) inside the stack directory. Only the per-frame source files (ARW, JPG companions, and their raw-converted TIFs) stay in the stack root. The collage is also written into the z-tier subfolder. Alongside this, ppsp creates a flat variants/ folder at the shoot root containing hard links (fallback: copies) to every variant and collage from all stacks — this is the folder you browse and cull from.

shoot/
├── 20260416095559-m4azzz-2126-bbfdtw/             ← named stack (shorthand set by --name in step 6)
│   ├── 20260416095559-m4azzz-2126-bbfdtw-a.arw   ← per-frame source files stay in root
│   ├── 20260416095559-m4azzz-2126-bbfdtw-a-z25.tif  ← per-frame raw-converted TIF stays in root
│   └── z25/                                       ← discovery outputs; removed by -C
│       ├── 20260416095559-m4azzz-2126-bbfdtw-z25-aligned0000.tif
│       ├── 20260416095559-m4azzz-2126-bbfdtw-z25-aligned0001.tif
│       ├── 20260416095559-m4azzz-2126-bbfdtw-z25-sel4.tif
│       ├── 20260416095559-m4azzz-2126-bbfdtw-z25-sel4-fatc.jpg
│       ├── 20260416095559-m4azzz-2126-bbfdtw-z25-sel3-fatc-dvi1.jpg
│       ├── 20260416095559-m4azzz-2126-bbfdtw-z25-sel4-m06p-neut.jpg
│       ├── ...
│       └── 20260416095559-m4azzz-2126-bbfdtw-collage.jpg
└── variants/                                      ← hard links to variants + collages; removed by -C
    ├── 20260416095559-m4azzz-2126-bbfdtw-z25-sel3-fatc-dvi1.jpg
    ├── 20260416095559-m4azzz-2126-bbfdtw-collage.jpg
    └── ...

After all variants for a stack are produced, a single <stack-name>-collage.jpg is written into the z-tier subfolder alongside the variants. All tiles (originals first, then variants) are arranged in a grid whose dimensions are chosen to approximate a 16:9 aspect ratio. Each tile is 640 px wide (preserving the source aspect ratio). Each tile is annotated at the bottom center with its full filename stem in large bold. Individual variant JPEGs are also annotated the same way, so you can identify them from any image viewer without relying on filename display.

After discovery, browse the variants/ folder with any image viewer (e.g. eog variants/ &). Two selection methods are available; ppsp asks you to choose when running interactively.

Simply delete the variants you do not want from variants/. Because these are hard links, the originals in the stack's z-tier subfolder are unaffected — you are only removing entries from the selection set.

# Delete unwanted variants, for example:
eog variants/ # browse through them and press delete on the unwanted
# or:
rm variants/*-natu-*.jpg
rm variants/*-collage.jpg
# Then generate what remains:
ppsp -g

ppsp also writes ppsp_generate.csv (tab-separated). Open it in any spreadsheet or editor and mark desired variants with x in the Generate column.

Filename	Generate
20260416095559-m4azzz-2126-z100-sel3-fatc-dvi2.jpg
20260416095559-m4azzz-2126-z100-sel4-m06p-dvi1.jpg	x

ppsp -g -V ppsp_generate.csv

Generates selected variants at full quality for publishing. Each output is written to out-{BBBB}/ where BBBB is the actual long-side pixel count of the generated image (e.g. out-7952/ for a z100 Sony a7R IV output). If --resolution PX is specified, a second resized copy is also exported to out-{PX}/ (e.g. out-2048/). Any variant already present in any out-*/ folder is skipped automatically; pass --redo to force regeneration. The -s flag limits generation to matching stacks.

Use -V to specify the source and -z to override the resolution tier — see § --variants (-V). The default is -V variants/ (the folder that -D populates).

ppsp --generate                                                        # default: from variants/
ppsp -g -V ppsp_generate.csv                                           # from CSV
ppsp -g -V my_selection.txt                                            # from TXT file
ppsp -g -V sel4-m06p-dvi1                                              # chain spec, all stacks
ppsp -g -V "(z25|z100)-sel4-m.*[pn]-dvi1"                              # regex, all stacks
ppsp --generate --redo                                                 # force regeneration
ppsp -g --stacks 2126-2200                                             # limit to stacks 2126-2200

When reading from a directory, CSV, or TXT file, the z-tier is taken from each filename and overridden by -z if specified. When using chain specs or presets, -z determines the tier (default: z100).

The -V option specifies what variants to run in -D (discovery) and -g (generate). It is evaluated in this order:

File path — directory: scans for *.jpg files; each filename's embedded z-tier is used as-is and overridden by -z if specified. Default for -g is variants/.

File path — single JPG: if the path resolves to a single .jpg file, only that variant is processed.

ppsp -g                            # reads variants/ (default)
ppsp -gV /path/to/my_folder
ppsp -gV variants/20260416095559-m4azzz-2126-z25-sel4-fatn-dvi1.jpg

File path — CSV (.csv): reads rows where Generate == x; z-tier from each filename, overridden by -z.

ppsp -g -V ppsp_generate.csv

File path — TXT (.txt): one target filename per line; z-tier as above.

ppsp -g -V my_selection.txt

Mode 1 — Preset level (some / many / lots / all): cross-product of the level's enfuse × TMO × grading IDs. Default for -D is some.

ppsp -D -V some    # 1 enfuse × 2 TMO × 2 gradings, no CT
ppsp -D -V many    # 2 enfuse × 3 TMO × 2 gradings × {∅, ctw5}
ppsp -D -V lots    # 5 enfuse × 8 TMO × 4 gradings × {∅, ctw5}  (≈640 variants)
ppsp -D -V all     # all enfuse × all TMO × all gradings × all CT IDs

Mode 2 — Comma-separated IDs (no - in any token): selects enfuse, TMO, and grading IDs and runs the cross-product. If no grading IDs are given, all six presets are used.

ppsp -D -V natu,sel3,fatc,m06p
# → enfuse: [natu, sel3]  TMO: [fatc, m06p]  gradings: all 6

ppsp -D -V sel3,fatc,m06p,dvi1
# → enfuse: [sel3]  TMO: [fatc, m06p]  gradings: [dvi1]

Mode 3 — Chain specs with Python regex (any token contains -): for -D each token is {enfuse-id}-{grading-id} or {enfuse-id}-{tmo-id}-{grading-id} (no z-tier); for -g a z-tier prefix is optional and overridden by -z. Standard Python re syntax is used for pattern matching against all valid chain combinations.

# Exact chains for -D:
ppsp -D -V sel4-fatc-dvi1,sel4-fatc-neut,sel4-m06p-dvi1

# Chain spec for -g:
ppsp -g -V z100-sel4-m06p-dvi1

# Alternation — same chain at two z-tiers:
ppsp -g -V "(z25|z100)-sel4-m06p-dvi1"

# Wildcard — all TMO variants for a fixed tier, enfuse ID, and grading:
ppsp -g -V "z6-sel4-.*-dvi1"
# → z6-sel4-m08d-dvi1, z6-sel4-m08n-dvi1, … (one per TMO variant)

# Combined — two z-tiers, only TMO IDs ending in p or n:
ppsp -g -V "(z25|z100)-sel4-m.*[pn]-dvi1"
# → z25-sel4-m06p-dvi1, z25-sel4-m08n-dvi1, z100-sel4-m06p-dvi1, z100-sel4-m08n-dvi1

Quote the pattern to prevent shell glob expansion. Patterns that match nothing emit a warning and produce no output.

--arws-enhance [FILES...] (-e) converts individual ARW files to high-quality enhanced JPGs without stacking or grading. Defaults to all ARWs under --dir.

--cleanup (-C) removes all z-tier subfolders (z6/, z25/, z100/) inside every stack directory, and the flat variants/ folder at the shoot root. Original ARW and JPG source files, and the out-{BBBB}/ export folders, are untouched. Run this after generation is complete and you no longer need to re-run discovery.

shoot/
├── ppsp_photos.csv                             # EXIF catalogue + StackName (tab-separated)
├── ppsp_stacks.csv                             # Stack titles, shorthands and per-stack generate specs (from --name)
├── ppsp_generate.csv                           # Variant selection file (tab-separated)
├── ppsp.log                                    # Full run log
├── cull/                                       # One labeled preview per stack
│   └── 20260416095559-m4azzz-2126-stack_count5.jpg
├── variants/                                   # Hard links to all discovery variants + collages; removed by -C
│   ├── 20260416095559-m4azzz-2126-bbfdtw-z25-sel3-fatc-dvi1.jpg
│   └── 20260416095559-m4azzz-2126-bbfdtw-collage.jpg
├── 20260416095559-m4azzz-2126-bbfdtw/          # Named stack folder (shorthand replaces -stack after --name)
│   ├── 20260416095559-m4azzz-2126-bbfdtw-a.arw  # Shorthand inserted after NNNN in all filenames
│   ├── 20260416095559-m4azzz-2126-bbfdtw-a-z25.tif
│   └── z25/                                    # Discovery outputs: intermediates + variants + collage; removed by -C
│       ├── *-z25-aligned0000.tif
│       ├── *-z25-sel4.tif
│       ├── *-bbfdtw-z25-sel4-fatc.jpg
│       ├── 20260416095559-m4azzz-2126-bbfdtw-z25-sel3-fatc-dvi1.jpg
│       └── 20260416095559-m4azzz-2126-bbfdtw-collage.jpg
├── out-7952/                                   # Full-res finals (from --generate; BBBB = actual long side)
│   └── 20260416095559-m4azzz-2126-bbfdtw-z100-sel3-fatc-dvi2.jpg
└── out-2048/                                   # Resized copies (from --generate --resolution 2048)
    └── 20260416095559-m4azzz-2126-bbfdtw-z100-sel3-fatc-dvi2.jpg

## Steps 1-6:
# Steps 1-3: Systematic renaming, stack organization, and generation of previews culling
ppsp -r -l L15
ppsp -o
ppsp -c
# Step 4: Manually review and deletion of unwanted previews
# Step 5: Prune unwanted stacks
ppsp -P
# Step 6: Add human readable names, tags and ratings to the surviving stacks interactively
ppsp -n
# Now we have clearly organized, titled stacks of the photo stacks we are really interested in.
## Generation with no actual discovery phase (you know what works)
# Manually add a good processing chain guess for each stack in ppsp_stacks.csv that you want to generate (f. ex. `sel4-fatn-neut`)
# Step 8: Generate the outputs
ppsp -z z25 -q 70 -i 2048 -V ppsp_stacks.csv -g
# Step 8: Generate warmer alternatives for each output
ppsp -z z25 -q 70 -i 2048 -s out-2048/* -gV 'sel5-fatc-neut-ctw5,sel5-kimv-dvi1-ctw5'
# For specific stacks (bathroom photos) generate normal temperature versions with specific TMO-grading combos
ppsp -z z25 -q 70 -i 2048 -s 2474 2489 2501 -gV 'sel5-(kimn|kimv|m06s)-dvi1,sel5-(fatn|fatc|fats)-deno'
ppsp -z z25 -q 70 -i 2048 -s 2474 2489 2501 -gV 'sel5-m06s-dvi1'
# Hardlink the photos to the upload directory
cp -l out-2048/*-{2474,2489,2501}-*-m06s-*.jpg ~/dwl/photos/2026/
# For other specific difficult stacks (living room with green carpet and strong inbound light), create all TMO alternatives (a sort of targeted discovery with generate)
ppsp -z z25 -q 70 -i 2048 -s 2116 2126 -gV 'sel4-.*-neut'
# Then realize two TMOs might be best with slight desaturation and warmup
ppsp -z z25 -q 70 -i 2048 -s 2116 2126 -gV 'sel4-(kimn|r02h)-dens-ctw4'
# Manually go through the outputs and delete the ones that you do not need
eog out-2048/
# Export (hard link) the ones you want to a specific directory
ppsp -z z25 -i 2048 -s 2474 2489 2501 -V 'sel5-fatn-dvi1-ctr1' -X /home/samsy/dwl/photos/2026/2026-04-27__mt17d39/
# Step 9: Cleanup the intermediary files
ppsp -C

git clone <repo>
cd ppsp
pip install -e ".[dev]"

# Run all tests
pytest

# Run a single test
pytest tests/test_rename.py::test_compute_refined_name

# Lint
ruff check src/

Test data: place a small set of Sony ARW + JPG pairs in test_data/. Tests requiring real image data are automatically skipped if test_data/ is absent or empty. The directory is gitignored and not distributed with the package. See design.md for the full testing strategy and code architecture.

Development journal: journal.md is a session-by-session narrative log of collaboration and decisions — the human complement to git log. Each entry summarises what a working session covered and which commits it produced. Design decisions with lasting architectural significance go in design.md instead.

Active work: wip.md holds specs, wireframes, and annotation notes while work is in flight. It is committed as a snapshot when each piece of work ships, then flushed and refilled for the next topic. See design.md § Development workflow for the full protocol.

For a deep-dive into the underlying tools and the reasoning behind ppsp's built-in presets, see guide.md. It covers:

• RAW conversion with dcraw — parameters, colour science, resolution tiers
• Image alignment with align_image_stack — feature detection, HDR vs focus-stack modes
• Exposure fusion with enfuse — Laplacian pyramid, weight functions, all built-in variant IDs
• Tone-mapping with luminance-hdr-cli — every supported operator, parameter guide, when to use each one
• Color grading with ImageMagick — S-curve contrast, proportional brightness scaling, the five built-in grading presets
• Photography-context guide — which operator combinations work best for each shot type

These are the foundational command-line utilities that ppsp is empowered by:

This table includes the wider ecosystem, including GUI wrappers and specialized scientific stacking tools:

For professional context, these are the "commercial" competitors that ppsp is designed to disrupt or emulate:

The following tabulates novel image processing or enhancement tools that leverage AI models: