Python Photo Workbench

PhotoWorkbench adds realistic borders, paper texture, soft edges, drop shadow, LUT color grading, and film grain to photos. It is a CLI-first tool with optional GUI application, presets and resource folders stored in your user config directory.

Features

• Clean border layouts or polaroid-style frames
• Soft feathered edges and configurable drop shadow
• Paper texture with adjustable noise and blend strength
• Optional LUT color grading via .cube files
• Optional film grain with tunable parameters
• Preset support via JSON configuration files

Install

pip install photoworkbench

GUI Application

The pip package installs two launch modes:

• CLI mode: photoworkbench (same options as pwb.py)
• GUI mode: photoworkbench-gui

Start the GUI with:

photoworkbench-gui

Example: Polaroid Frame

python src/photoworkbench/pwb.py input.jpg output.jpg \
  --border-size 100 \
  --border-color "245,242,235" \
  --polaroid \
  --polaroid-bottom-factor 1.8 \
  --soft-edges \
  --feather-radius 8 \
  --shadow \
  --shadow-offset 15 \
  --shadow-blur 12 \
  --texture \
  --texture-strength 0.15 \
  --noise-strength 20

Example: LUT + Film Grain

python src/photoworkbench/pwb.py input.jpg output.jpg \
  --enable-lut \
  --lut-path "look.cube" \
  --lut-strength 0.85 \
  --enable-filmgrain \
  --filmgrain-scale 1.0 \
  --filmgrain-src-gamma 1.0 \
  --filmgrain-grain-power 0.7 \
  --filmgrain-highs 0.2 \
  --filmgrain-shadows 0.2 \
  --filmgrain-type 1 \
  --filmgrain-grain-sat 0.5 \
  --filmgrain-sharpen 1 \
  --filmgrain-seed 42

Presets and Resource Paths

PhotoWorkbench looks for user presets and LUTs in the app config directory:

• Presets: ~/.config/photoworkbench/presets/
• LUTs: ~/.config/photoworkbench/luts/

You can pass an absolute path, a path relative to the current working directory, or just a filename that exists in the resource folder.

Preset Format

Preset files are JSON and can contain any CLI option names. Example my-border.json:

{
  "border_size": 120,
  "border_color": "245,242,235",
  "enable_shadow": true,
  "enable_soft_edges": true,
  "enable_texture": true,
  "feather_radius": 8,
  "shadow_offset": 12,
  "shadow_blur": 10,
  "texture_strength": 0.12,
  "noise_strength": 18
}

Use it with:

python src/photoworkbench/pwb.py input.jpg output.jpg --preset-path my-border.json

CLI Reference

usage: pwb.py [-h] [--preset-path PRESET_PATH] [--border-size BORDER_SIZE]
              [--border-size-percent BORDER_SIZE_PERCENT]
              [--border-color BORDER_COLOR] [--polaroid] [--enable-border]
              [--polaroid-bottom-factor POLAROID_BOTTOM_FACTOR] [--shadow]
              [--soft-edges] [--texture] [--enable-lut]
              [--lut-path LUT_PATH] [--lut-strength LUT_STRENGTH]
              [--enable-filmgrain] [--filmgrain-scale FILMGRAIN_SCALE]
              [--filmgrain-src-gamma FILMGRAIN_SRC_GAMMA]
              [--filmgrain-grain-power FILMGRAIN_GRAIN_POWER]
              [--filmgrain-highs FILMGRAIN_HIGHS]
              [--filmgrain-shadows FILMGRAIN_SHADOWS]
              [--filmgrain-type FILMGRAIN_TYPE]
              [--filmgrain-grain-sat FILMGRAIN_GRAIN_SAT]
              [--filmgrain-gray-scale] [--filmgrain-sharpen FILMGRAIN_SHARPEN]
              [--filmgrain-seed FILMGRAIN_SEED] [--feather-radius FEATHER_RADIUS]
              [--shadow-offset SHADOW_OFFSET] [--shadow-blur SHADOW_BLUR]
              [--texture-strength TEXTURE_STRENGTH]
              [--noise-strength NOISE_STRENGTH]
              input output

Layout

• --border-size sets the border size in pixels for all sides.
• --border-size-percent uses a percentage of the image short side (overrides pixel size).
• --border-color takes R,G,B values, for example "255,255,255".
• --polaroid enables a thicker bottom border.
• --polaroid-bottom-factor scales the bottom border height.
• --enable-border disables border generation.

Styling

• --soft-edges disables feathered edges.
• --feather-radius controls the feather size in pixels.
• --shadow disables the drop shadow.
• --shadow-offset sets the shadow offset in pixels.
• --shadow-blur sets the shadow blur radius.
• --texture disables paper texture.
• --texture-strength blends texture with the background (0 to 1).
• --noise-strength controls texture noise intensity.
• Defaults: shadow, soft edges, and texture are off in the CLI; enable them in presets by setting enable_shadow, enable_soft_edges, and enable_texture to true.

Color and Grain

• --enable-lut enables LUT color grading.
• --lut-path points to a .cube file.
• --lut-strength blends LUT results (0 to 1).
• --enable-filmgrain enables film grain processing.
• --filmgrain-scale, --filmgrain-src-gamma, --filmgrain-grain-power tune the base grain.
• --filmgrain-highs, --filmgrain-shadows tune highlights/shadows grain influence.
• --filmgrain-type selects a grain type preset.
• --filmgrain-grain-sat controls grain color saturation.
• --filmgrain-gray-scale forces monochrome grain.
• --filmgrain-sharpen applies sharpening passes.
• --filmgrain-seed sets a deterministic grain seed.

Notes

The filmgrain algorithm is the work of "larspontoppidan" (https://github.com/larspontoppidan/filmgrainer).

• EXIF orientation is normalized so portrait images stay upright.
• EXIF metadata is preserved when available.

Dependencies

• Pillow
• appdirs
• lut-tools
• filmgrainer

Install with your preferred Python packaging workflow, then run the CLI examples above.