froxxxy/imagepipeline
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
100302bf01f4055e0e0ae160abc2a0c4529f14a6
imagepipeline/RECIPES.md
T
Frank Schwenk 1c36fc1968 docs: add RECIPES.md declarative pipeline recipes 
Catalog of single-step and composite/pipeline recipes for agents to
expand into pipelines, with human notes, recipe inclusion, and xcf_stack.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-12 11:32:01 +02:00

18 KiB
Raw Blame History

RECIPES.md — Declarative Pipeline Recipes

Open this file when you forget how recipes work — rules first, catalog below.

Not executable code. Named building blocks for creating or editing pipelines in pipelines/<name>.py. Load via @RECIPES.md in Cursor when working on pipelines.

1. Rules cheat sheet

  1. What a recipe is — a named list of declarative lines. Agents turn it into Python using modules from imagepipeline/modules/.

  2. Layer order — in every combine / composite recipe, lines are listed bottom layer → top layer (first line = background, last line = foreground on top).

  3. Indentation — recipe id on its own line; indented lines below are the layers/steps of that recipe.

  4. combine = composite — a multi-line recipe produces one output image by stacking those layers.

  5. Two-layer vs three-layer — the composite module accepts exactly 2 inputs. Three or more layers need chained composites (bottom pair first, then add the next layer on top):

    # 3 layers: A (bottom), B (middle), C (top)
combine
  A
  B
  C
# → composite(A, B) then composite(result, C)

  6. Shared expensive steps — rembg runs once per pipeline and is reused. Recipe lines say rembg, but the agent must not re-run it for every composite.

  7. xcf_stack (GIMP export) — stacks all prior step outputs (plus input/ by default) into one .xcf per image with layers named after step ids. Usually the last step after all composites. Requires gimp on PATH. Not a layer inside a combine block — a separate finishing recipe.

  8. Placeholders — COLOR1, COLOR2, COLOR, STYLE, MAX_EDGE, PROMPT, MODEL, TEMPLATE_IMAGE, etc. are filled in at pipeline creation time (from your prompt or constants at the top of the script).

  9. Colors — hex for backgrounds (#RRGGBB or #RRGGBBAA). G'MIC filters need R,G,B tuples (see GMIC color derivation below).

  10. Single-step vs composite vs pipeline — one declarative line = one module step. Multiple indented lines in a composite recipe = layers (bottom → top). Multiple indented lines in a pipeline recipe = sequential steps (first step first, output feeds the next).

  11. Recipe inclusion — an indented line that matches a recipe id from this file expands that recipe instead of inlining its steps:

    • In a pipeline recipe (e.g. colorsplash-watermark): resolve the referenced recipe, then chain the next line on its output.
    • In a composite recipe: layers stay declarative (layer descriptions, not recipe ids). Do not nest composite recipes as layers.
    • Expand recursively; share expensive steps (rembg, etc.) once across all expanded recipes in the same pipeline.

  12. Notes (human only) — freeform reminders for you. Agents must ignore them entirely when building pipelines:

    • Full-line note: line starts with # (optional leading spaces) — not a layer, not a recipe id.
    • Inline note: # … after a recipe id on the same line (everything from # onward is ignored).
    • Notes may be German or English. They never become code, constants, or prompts.

  13. Quick read examples:

    original-stereo-rembg  # wie horseland 3d effekt
  original
  rembg with gmic: gcd_stereo_img …
  rembg

    colorsplash
  # team gallery default look
  original as greyscale
  rembg

    colorsplash-watermark
  colorsplash
  darktable style STYLE

2. How agents use this file

  • Recipes are names + declarative steps, not Python.
  • When creating or editing a pipeline: read @RECIPES.md, resolve named recipes, substitute placeholders, emit real Pipeline code.
  • Recipe inclusion: if an indented line is a known recipe id (e.g. colorsplash inside colorsplash-watermark), look up that recipe, expand it, and use its output as the input for the next step. Expand recursively. Do not duplicate shared steps — one rembg (etc.) per pipeline when multiple included recipes need it.
  • Pipeline vs composite: multiple indented lines that are sequential steps or recipe refs = pipeline recipe (chain). Multiple indented layer lines (original, rembg, backgrounds, gmic-on-rembg, …) = composite recipe (combine). When unsure: if any line is another recipe id, treat the parent as a pipeline recipe.
  • Ignore notes: skip any line that is only a # comment (after indent trim). Strip inline # … suffixes on recipe-id lines. Do not copy note text into Python comments unless Fränky asks.
  • xcf_stack: when a pipeline includes recipe xcf-stack (or the user asks for GIMP layers), append as the final step: p.step("xcf_stack", inputs="input"). The module auto-collects prior_steps from the runner — do not list every composite as explicit inputs. See imagepipeline/modules/xcf_stack.py.
  • Shared steps: define rembg (and other expensive steps) once per pipeline and reference the step in composites — mirror pipelines/pipeline_baxxter.py.
  • Follow the Rules cheat sheet above — especially layer order and chained composites.
  • 3+ layers: chain composite steps (see baxxter, crusaders, orange).

3. Vocabulary

Recipe term Maps to
original inputs="input"
original as greyscale gmic_grayscale on input
grayscale imagemagick_grayscale on input
rembg rembg on input (outputs .png)
white background / black background imagemagick_fill solid #ffffff / #000000
gradient background COLOR1 COLOR2 45 degree imagemagick_fill linear, angle=45
gradient background COLOR1 COLOR2 radial imagemagick_fill radial
COLOR background imagemagick_fill solid color1=COLOR
rembg with gmic: FILTER gmic on rembg output; command = -FILTER
layer opacity N% composite foreground_opacity=N/100 on that layer
make layer 5% bigger then crop to original size imagemagick_scale_crop scale=1.05
COLOR to alpha color_to_alpha color=COLOR
resize max edge MAX_EDGE imagemagick_resize max_edge=MAX_EDGE
crop square crop_square
darktable style STYLE darktable_style style=STYLE
xcf stack all steps xcf_stack — GIMP layer export of all prior steps
xcf stack without input xcf_stack include_input=false
xcf stack skip missing xcf_stack skip_missing=true
openrouter edit PROMPT MODEL openrouter_edit
openrouter gallery match TEMPLATE_IMAGE openrouter_edit with template_image

Placeholders: COLOR1, COLOR2, COLOR, STYLE, MAX_EDGE, PROMPT, MODEL, TEMPLATE_IMAGE, YELLOW — substituted from the user prompt or pipeline constants.

4. Single-step recipes

One entry per built-in module. Format: recipe id, declarative line(s), Python mapping.

rembg

rembg
  rembg
  • Module: rembg — p.step("rembg", inputs="input")
  • Note: outputs .png; downstream steps match by stem.

rembg-alpha-matting-off

rembg-alpha-matting-off
  rembg
  • Module: rembg — alpha_matting=False

grayscale-gmic

grayscale-gmic
  original as greyscale
  • Module: gmic_grayscale — default command -to_gray

grayscale-imagemagick

grayscale-imagemagick
  grayscale
  • Module: imagemagick_grayscale

resize-max-edge

resize-max-edge
  resize max edge MAX_EDGE
  • Module: imagemagick_resize — e.g. max_edge=2000
  • Source: pipelines/pipeline_2000px.py

scale-crop-5pct

scale-crop-5pct
  make layer 5% bigger then crop to original size
  • Module: imagemagick_scale_crop — scale=1.05

solid-fill

solid-fill
  COLOR background
  • Module: imagemagick_fill — color1=COLOR

gradient-linear-45

gradient-linear-45
  gradient background COLOR1 COLOR2 45 degree
  • Module: imagemagick_fill — gradient=True, angle=45

gradient-radial

gradient-radial
  gradient background COLOR1 COLOR2 radial
  • Module: imagemagick_fill — gradient=True, radial=True

gmic

gmic
  gmic: COMMAND
  • Module: gmic — command="-COMMAND" (leading - as in existing pipelines)

color-to-alpha

color-to-alpha
  COLOR to alpha
  • Module: color_to_alpha — outputs .png

darktable-style

darktable-style
  darktable style STYLE
  • Module: darktable_style — style must exist in ~/.config/darktable/styles/

crop-square

crop-square
  crop square
  • Module: crop_square — center-crop to largest square

xcf-stack

xcf-stack  # GIMP layer export — one .xcf per input image
  xcf stack all steps
  • Module: xcf_stack — p.step("xcf_stack", inputs="input") as last step
  • Layer order in XCF: input/ (bottom, default) then prior steps in pipeline definition order
  • Matching: layers matched by filename stem (extension may differ, e.g. rembg .png on .jpg input)
  • Output: {stem}.xcf per input image
  • Requires: gimp on PATH
  • No existing pipeline uses this yet — append to any multi-output pipeline (e.g. baxxter variants + xcf-stack)

xcf-stack-no-input

xcf-stack-no-input
  xcf stack without input
  • Module: xcf_stack — include_input=False

xcf-stack-skip-missing

xcf-stack-skip-missing
  xcf stack skip missing
  • Module: xcf_stack — skip_missing=True

openrouter-edit

openrouter-edit
  openrouter edit PROMPT MODEL
  • Module: openrouter_edit — needs OPENROUTER_API_KEY in .env
  • Source: pipelines/example_ai.py

openrouter-gallery-match

openrouter-gallery-match
  openrouter gallery match TEMPLATE_IMAGE
  • Module: openrouter_edit with template_image=TEMPLATE_IMAGE and gallery-match prompt
  • Source: pipelines/pipeline_team_gallery_match.py

ai-exposure

ai-exposure
  ai exposure strength STRENGTH
  • Module: ai_exposure — optional [ai] extra; max_edge, strength

ai-tone-map

ai-tone-map
  ai tone map strength STRENGTH
  • Module: ai_tone_map — optional [ai] extra

comfy-flux-edit

comfy-flux-edit
  comfy flux edit PROMPT
  • Module: comfy_flux_edit — local ComfyUI; very slow on CPU

5. Composite and pipeline recipes

Composite recipes produce one output image. Layers listed bottom → top.
Pipeline recipes chain steps or other recipes in order (output of step n → input of step n+1).
Parameterized recipes use COLOR1 / COLOR2 (hex) — derive G'MIC RGB via section 6.

colorsplash

colorsplash
  original as greyscale
  rembg
  • Layers: grayscale background, rembg cutout on top
  • Source: baxxter, orange, crusaders, pipeline_colorsplash_watermark_f12.py

colorsplash-watermark

colorsplash-watermark
  colorsplash
  darktable style STYLE
  • Type: pipeline recipe (includes colorsplash, then chains darktable_style)
  • Python: expand colorsplash → composite step ref → p.step("darktable_style", inputs=combined, style=STYLE)
  • Source: pipelines/pipeline_colorsplash_watermark_f12.py (STYLE = "Watermark F12.rocks")

rembg-white-bg

rembg-white-bg
  white background
  rembg
  • Source: baxxter, crusaders

rembg-black-bg

rembg-black-bg
  black background
  rembg
  • Source: baxxter, crusaders

rembg-gradient-45

rembg-gradient-45
  gradient background COLOR1 COLOR2 45 degree
  rembg
  • Source: baxxter, crusaders

rembg-radial-2colors

rembg-radial-2colors
  gradient background COLOR1 COLOR2 radial
  rembg
  • Source: baxxter, crusaders

original-stereo-rembg

original-stereo-rembg  # wie horseland 3d effekt
  original
  rembg with gmic: gcd_stereo_img 0,0,2.028,1,1.714,3.06,4,1,0
  rembg
  • 3 layers: composite(original, rembg_stereo) → composite(result, rembg)
  • Source: baxxter, crusaders

original-stereo-black-alpha-rembg

original-stereo-black-alpha-rembg
  original
  rembg with gmic: gcd_stereo_img 0,0,2.028,1,1.714,3.06,4,1,0
  #000000 to alpha
  rembg
  • Middle layer: stereo gmic, then #000000 to alpha on that output
  • Source: crusaders, baxxter_2

original-drop-shadow-rembg

original-drop-shadow-rembg
  original
  rembg with gmic: fx_drop_shadow3d 0,0,0,10,1,1,2,0.5,R2,G2,B2,200,0
  rembg

original-bwrecolor-rembg

original-bwrecolor-rembg
  original
  rembg with gmic: fx_bwrecolorize 0,0,0,0,0,1,0,2,R2,G2,B2,255,R1,G1,B1,255,158,137,189,255,224,191,228,255,R1,G1,B1,0,255,255,255,255,255,255,255,255,255,R1,G1,B1,0,255
  rembg
  • Middle layer opacity: 50% (foreground_opacity=0.5 on first composite)
  • Palette: R1,G1,B1 from COLOR1, R2,G2,B2 from COLOR2
  • Source: baxxter, orange, crusaders

rembg-custom-gradient-a

rembg-custom-gradient-a
  rembg with gmic: fx_custom_gradient 0,0,0,1,2,1,0,128,100,100,2,0,1,0,"",1,0,R1,G1,B1,0,255,R2,G2,B2,255,255,255,0,255,255,255,255,255,0,255,255,255,0,255,0,255,0,0,255,255,128,128,128,255,255,0,255,255,0,0,0,0
  rembg
  • Gradient direction: COLOR1 → COLOR2 on the rembg cutout
  • Source: baxxter, orange, crusaders

rembg-custom-gradient-b

rembg-custom-gradient-b
  rembg with gmic: fx_custom_gradient 0,0,0,1,2,1,0,128,100,100,2,0,1,0,"",1,0,R2,G2,B2,255,R1,G1,B1,0,255,255,255,0,255,255,255,255,255,0,255,255,255,0,255,0,255,0,0,255,255,128,128,128,255,255,0,255,255,0,0,0,0
  rembg
  • Gradient direction: COLOR2 → COLOR1 on the rembg cutout
  • Source: baxxter, orange, crusaders

original-jpr-smooth-rembg

original-jpr-smooth-rembg
  original
  rembg with gmic: jpr_gradient_smooth 0,1.5
  make layer 5% bigger then crop to original size
  rembg
  • Middle layer: jpr smooth on rembg, then scale 5% + center crop
  • Source: baxxter, crusaders

original-jpr-smooth-grey-alpha-rembg

original-jpr-smooth-grey-alpha-rembg
  original
  rembg with gmic: jpr_gradient_smooth 0,1.5
  #7f7f7f to alpha
  make layer 5% bigger then crop to original size
  rembg
  • Middle layer: jpr smooth → #7f7f7f to alpha → scale 5% + crop
  • Source: crusaders, baxxter_2

color-bg-drop-shadow-rembg

color-bg-drop-shadow-rembg
  COLOR1 background
  rembg with gmic: fx_drop_shadow3d 0,0,0,10,1,1,2,0.5,R2,G2,B2,200,0
  rembg
  • 3 layers: solid COLOR1 bg, drop-shadow rembg in middle, rembg on top
  • Source: orange (COLOR1 = #AA4E00), crusaders

yellow-bg-drop-shadow-rembg

yellow-bg-drop-shadow-rembg
  YELLOW background
  rembg with gmic: fx_drop_shadow3d 0,0,0,10,1,1,2,0.5,R2,G2,B2,200,0
  rembg
  • Source: pipelines/pipeline_baxxter_2.py (YELLOW = #d7fd00, shadow RGB from baxxter COLOR2)

resize-2000px

resize-2000px
  resize max edge 2000
  • Single-step preset — not a composite
  • Source: pipelines/pipeline_2000px.py

openrouter-enhance

openrouter-enhance
  openrouter edit PROMPT MODEL
  • Single-step — subtle enhancement prompt from pipelines/example_ai.py
  • Typical: max_edge=2048

team-gallery-match

team-gallery-match
  openrouter gallery match TEMPLATE_IMAGE
  • Single-step — style-match new photos to existing gallery reference
  • Source: pipelines/pipeline_team_gallery_match.py

6. GMIC color derivation

G'MIC commands in parameterized recipes use comma-separated RGB integers, not hex.

Hex → RGB

  1. Take #RRGGBB or strip alpha from #RRGGBBAA (last two hex digits = alpha, ignored for GMIC tuples).
  2. Split into three byte pairs → decimal 0–255.
Hex R,G,B
#AA4E00 170, 78, 0
#EDDD93 237, 221, 147
#d7fd00 215, 253, 0
#fc0ade 252, 10, 222
#0064b0 0, 100, 176
#00badf 0, 186, 223

Where colors go

Recipe Color usage
original-drop-shadow-rembg shadow tint: R2,G2,B2 from COLOR2 in fx_drop_shadow3d …,R2,G2,B2,200,0
original-bwrecolor-rembg highlight R2,G2,B2, accent R1,G1,B1 in fx_bwrecolorize
rembg-custom-gradient-a starts with R1,G1,B1, transitions via R2,G2,B2
rembg-custom-gradient-b starts with R2,G2,B2, transitions via R1,G1,B1
imagemagick_fill backgrounds use full hex including alpha if needed (#d7fd00ff)

Agent workflow

  1. Define COLOR1 and COLOR2 as constants at the top of the pipeline script.
  2. Add a short comment with derived RGB tuples (as in pipeline_orange.py).
  3. Build GMIC command strings using those integers.

7. Usage examples

Compose by recipe name

Create pipeline "foo" with recipes colorsplash and rembg-radial-2colors, COLOR1=#123456, COLOR2=#654321

Agent: shared rembg step, gmic_grayscale, two imagemagick_fill gradients, two composite outputs (separate variants, not chained).

Pipeline recipe with inclusion

Create pipeline "watermark" with recipe colorsplash-watermark, STYLE="Watermark F12.rocks"

Agent: expand colorsplash inside colorsplash-watermark, then chain darktable_style on the composite output.

colorsplash-watermark
  colorsplash
  darktable style STYLE

With GIMP layer export

Create pipeline "foo" with recipes colorsplash, rembg-radial-2colors, and xcf-stack

Agent: all composite outputs first, then p.step("xcf_stack", inputs="input") as the final step.

Full combine list (baxxter style)

Paste a raw list of combine blocks (bottom → top). Agent maps each block to a recipe id from section 5 or expands inline steps. Reuse one rembg step for the whole pipeline.

Extend existing pipeline

Add recipe color-bg-drop-shadow-rembg to pipeline_orange.py with current COLOR1

Agent: read existing constants, append new composite steps using the same rembg_out and rembg_shadow pattern.

Human notes in prompts

You may add # notizen in recipe blocks in this file anytime — agents ignore them per section 1 rule 11.

Reference in New Issue View Git Blame Copy Permalink