Composite Processor

Overview

The Composite Processor merges two images—background and overlay—into a single output. It supports flexible alignment options, optional resizing, and an additional pair of reference anchors for advanced transformations.

---

Example Usage

- processor:
    processor: "composite"
    inputs:
      background: "input/bg.png"
      overlay: "account/logo.png"
    params:
      # Single anchor pair (standard usage).
      background_anchor: "rel(0.1, 0.1)" # Place overlay near upper-left
      overlay_anchor: "(0, 0)" # Overlay's own upper-left corner

      # Optional second anchor pair. If provided, the overlay is transformed so
      # that its two anchor points match the background’s two anchor points.
      background_anchor2: "rel(0.9, 0.9)" # Bottom-right of the background
      overlay_anchor2: "rel(1, 1)" # Bottom-right of the overlay

      # Explicit overlay sizing (single-anchor only).
      width: "[[ {width:background} * 0.2 ]]"
      height: # auto by aspect ratio

      # Additional settings
      mode: "normal" # "normal" or "clear"
      opacity: 0.5 # Blend strength [0..1]
      stretch: false # false = uniform AR; true = non-uniform scaling
      padding: 10 # px inset within the background region

    outputs:
      target: "output/composited.png"
      annotated: "output/composited_annotated.png"

    assigns:
      left: "overlay_left"
      top: "overlay_top"
      right: "overlay_right"
      bottom: "overlay_bottom"
      width: "overlay_width"
      height: "overlay_height"

---

Inputs

Key	Required	Description
background	Yes	Virtual filepath for the background image (e.g., "input/bg.png").
overlay	Yes	Virtual filepath for the overlay image (e.g., "account/logo.png").

Both images are loaded internally in RGBA format.

---

Params

Anchors

• Single-anchor (background_anchor + overlay_anchor): Places the overlay so that its overlay_anchor matches the background_anchor. Optional width or height can resize the overlay (maintaining aspect ratio).

• Two-anchor (background_anchor, overlay_anchor and background_anchor2, overlay_anchor2): Defines a region on each image and transforms the overlay so both regions align.

  • stretch = false: uniform scaling (may leave gaps).
  • stretch = true: non-uniform scaling (exact fit).
  • width/height are ignored in this mode.

Anchor Syntax

Coordinates may be absolute ("(100, 50)") or relative (rel(0.5, 0.5)).

---

width, height

• Single-anchor only
• Specify one dimension; the other auto-computes to preserve aspect ratio.
• Ignored when two-anchor mode is used.

mode

• normal: standard alpha compositing.
• clear: overlay acts as an eraser (white → transparent).

opacity

Float in [0, 1], scaling the overlay’s alpha channel.

padding

Integer 0–300 px to inset the effective background region (shrinks two-anchor region or offsets single-anchor placement).

stretch

• false (default): uniform scaling in two-anchor mode.
• true: allow independent X/Y scaling.

max_size (int)

If the final image exceeds this in either dimension, it is proportionally scaled down.

---

Outputs

Key	Required	Description
target	Yes	File path for the final composite. If omitted, background may be overwritten.
annotated	No	Optional annotated image with registration marks.

---

Compositing Flow

1. Load background & overlay in RGBA.

2. Parse single-anchor resize (width/height) if no second anchors.

3. Check for two-anchor mode:

   • Yes → transform overlay by region, ignoring width/height.
   • No → position (and resize) by single-anchor rules.

4. Apply opacity.

5. Composite (mode=normal or clear).

6. Clamp to max_size if set.

7. Save to target.

8. Save annotated if annotated provided.

9. Assign metrics (left, top, right, bottom, width, height).

---

Error Handling

• Malformed anchors or parsing errors throw ValueError.
• Out-of-range numeric params are clamped or defaulted.
• Missing/corrupt images raise image-related exceptions.

---

Assigns

Key	Description
left	Overlay’s left coordinate on the background
top	Overlay’s top coordinate on the background
right	left + width
bottom	top + height
width	Overlay width after transform
height	Overlay height after transform