# **Frame Processor**
## Overview
The **Frame Processor** (`frame`) draws a border (“frame”) around an image, or creates a standalone framed canvas when no source is provided.
- If `composite=true`, the frame is overlaid onto an existing `source` image.
- If `composite=false`, you may supply a `source` for its dimensions or specify `width`/`height` explicitly.
---
## Example Usage
```yaml
- processor:
processor: "frame"
inputs:
source: "mem/subject.png"
params:
composite: true
size: 10
color: "#FFFFFF"
padding: 5
inner_radius: 0
outer_radius: 0
mode: "fit" # or "expand" or "overlay"
outputs:
target: "mem/framed_subject.png"
assigns:
content_top: "frame_top"
content_left: "frame_left"
content_bottom: "frame_bottom"
content_right: "frame_right"
content_width: "frame_content_width"
content_height: "frame_content_height"
```
---
## Inputs
| Key | Required | Description |
| ------ | --------------------------------------------: | ------------------------------------------------------- |
| source | Yes if `composite=true`,
or to supply dims | Path of image to frame (optional if standalone canvas). |
---
## Params
| Key | Type | Required | Default | Description |
| ------------ | -------------------------------- | -----------------: | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| composite | `boolean` | | `true` | If `true`, overlay frame on `source`; if `false`, generate standalone canvas (can use `source` size). |
| width | `int` | Yes if no `source` | — | Canvas width (standalone mode only). |
| height | `int` | Yes if no `source` | — | Canvas height (standalone mode only). |
| background | `str` | | `"transparent"` | Fill color for new canvas; also fills outer rounded-corner areas when `outer_radius > 0`. Ignored when compositing. |
| size | `int` | Yes | — | Frame thickness in pixels. |
| color | `str` | Yes | — | Frame color (`#RRGGBB`, `rgba()`, or named color). |
| padding | `int` | | `0` | Gap between image/canvas edge and inner edge of frame. |
| inner_radius | `int` | | `0` | Corner radius (px) on inner edge; clamped to `[0 .. canvas_short_side/2]` and forced ≤ `outer_radius`. |
| outer_radius | `int` | | `0` | Corner radius (px) on outer edge; clamped to `[0 .. canvas_short_side/2]`; outer corners are filled with `background`. |
| mode | `enum["fit","expand","overlay"]` | | `"overlay"` | `"fit"`: scale source to fit inner frame bounds;
`"expand"`: enlarge canvas for source+frame;
`"overlay"`: draw frame without resizing. |
---
## Outputs
| Key | Required | Description |
| ------ | -------: | --------------------------------------- |
| target | Yes | Path where the framed image is written. |
---
## Assigns
If an `assigns:` block is present, the processor will populate:
| Variable | Description |
| ---------------- | ----------------------------------------------------------------------- |
| `content_top` | Y-coordinate of the inner rectangle’s top edge (px from canvas origin). |
| `content_right` | X-coordinate of the inner rectangle’s right edge. |
| `content_bottom` | Y-coordinate of the inner rectangle’s bottom edge. |
| `content_left` | X-coordinate of the inner rectangle’s left edge. |
| `content_width` | Width of the interior area (`content_right - content_left`). |
| `content_height` | Height of the interior area (`content_bottom - content_top`). |