The **Composite Processor** (`AbProcComposite`) 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
```yaml
- 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
# Overlay dimensions or scaling. (Ignored if two anchor pairs are used and valid.)
width: "{width:background} * 0.2"
height: ""
# Additional settings
mode: "normal" # "normal" or "clear"
opacity: 0.5 # Blend strength [0..1]
lock_ar: True # If true, maintain aspect ratio when using two anchors
outputs:
target: "output/composited.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 typically loaded or converted internally to **RGBA** format.
---
## Params
### 1. Anchors
You can use one or two **anchor pairs**:
- **Single Anchor Pair** (`background_anchor` + `overlay_anchor`):
Aligns the overlay so that its `overlay_anchor` matches the `background_anchor`. Any normal resizing rules (via `width`, `height`, or `scale`) apply afterward.
- **Two Anchor Pairs** (`background_anchor`, `overlay_anchor` **and** `background_anchor2`, `overlay_anchor2`):
Defines a “region” on the background (spanning from `background_anchor` to `background_anchor2`) and a corresponding “region” on the overlay (from `overlay_anchor` to `overlay_anchor2`). The overlay is then transformed—translated, scaled, or flipped—so that both regions line up exactly:
- If **`lock_ar = true`**, the overlay is scaled uniformly (maintaining aspect ratio). Small offsets may remain if the background region’s aspect ratio differs from the overlay’s.
- If **`lock_ar = false`**, the overlay is allowed to stretch or squash so the two anchor pairs match precisely.
#### Anchor Syntax
Coordinates can be absolute (e.g. `"(100, 50)"`) or relative (`rel(0.5, 0.5)`). The overlay and background each have their own coordinate space.
### 2. Overlay Dimensions
- **`width`** / **`height`**
Numeric expressions specifying how large to make the overlay. If one is specified and the other left blank, the overlay’s original aspect ratio is preserved.
**Note:** If both anchor pairs are provided and valid, these explicit dimensions or scaling factors are ignored in favor of the two-point transformation.
### 3. **mode**
- **`normal`**
Uses standard alpha compositing.
- **`clear`**
Interprets the overlay as a mask. White regions in the overlay clear (make transparent) those areas of the background.
### 4. **opacity**
A float in **[0, 1]** that uniformly scales the overlay’s opacity.
### 5. **max_size** (int)
If either dimension of the final composited image exceeds `max_size` (default 1500), it is proportionally scaled down.
### 6. **Aspect Ratio Lock** (`lock_ar`)
- **`true` (default)**: When using two anchor pairs, maintain the overlay’s aspect ratio.
- **`false`**: Allow non-uniform scaling so the overlay’s reference region matches the background’s reference region exactly.
### 7. **Additional Scaling Parameters** (Optional)
- **`scale`** (float)
A general scaling factor for the overlay if no explicit `width` or `height` is set.
- **`height_scale`** / **`width_scale`** (float)
Specific scaling factors for overlay height or width. These override a general `scale` but are themselves overridden by explicit `width` or `height`.
---
## Outputs
| **Key** | **Required** | **Description** |
| -------- | -----------: | -------------------------------------------------------------------------------------------- |
| `target` | | The file path for the final composited image. If omitted, the background may be overwritten. |
---
## Advanced Options
1. **Color Values**
- Interpreted via `PIL.ImageColor.getcolor(...)`. Examples: `#RRGGBB`, `rgba(...)`, or named colors.
2. **Numeric Values**
- Inline math (e.g. `"20/2"`, `"10*10"`) is supported.
- References like `"{width:background}"` retrieve metadata from other steps or images.
3. **Point Values**
- `(100, 50)` for absolute, `rel(0.5, 0.5)` for relative.
- You can mix numeric expressions (e.g. `"( {width:input}/2, 100 )"`).
---
## Compositing Flow
1. **Load** both the background and overlay images in RGBA.
2. **Parse** and apply resizing/scale if only a single anchor pair is used (or if reference anchors are not given).
3. **Check** if two anchor pairs are valid:
- **Yes**: Transform overlay so the region from `(overlay_anchor → overlay_anchor2)` aligns with `(background_anchor → background_anchor2)`. Use `lock_ar` to decide uniform or non-uniform scaling.
- **No**: Simply position the overlay anchor at the background anchor.
4. **Apply** optional `opacity`.
5. **Composite**:
- **`mode=normal`** → standard alpha blending.
- **`mode=clear`** → treat overlay as a mask that erases parts of the background.
6. **Scale down** to respect `max_size` if needed.
7. **Save** the result to `target`.
8. **Assign** overlay metrics (`left`, `top`, `right`, `bottom`, `width`, `height`).
---
## Error Handling
- **Anchor Syntax**: Malformed anchors or references throw a `ValueError`.
- **Numeric Expressions**: Invalid expressions raise parsing errors or revert to defaults.
- **Opacity**: Values outside `[0,1]` are clamped or raise errors.
- **Image Data**: Missing or corrupted images raise standard file or image errors.
---
## Assigns
The processor populates:
- **`left`**: Overlay’s left coordinate relative to the background
- **`top`**: Overlay’s top coordinate
- **`right`**: `left + overlay_width`
- **`bottom`**: `top + overlay_height`
- **`width`**: Final overlay width after transformations
- **`height`**: Final overlay height after transformations