> ## Documentation Index
> Fetch the complete documentation index at: https://learn.workflow.dog/llms.txt
> Use this file to discover all available pages before exploring further.

# Overlay Images

> Scale and place a foreground image over a background image.

**Overlay Images** composites one image over another. The foreground is scaled
relative to the background, aligned to one of nine positions, and optionally
made translucent.

## Inputs

| Input          | Type   | Required | Description                                                          |
| -------------- | ------ | -------- | -------------------------------------------------------------------- |
| **Background** | File   | Yes      | The base image and the output canvas.                                |
| **Foreground** | File   | Yes      | The image placed over the background.                                |
| **Scale**      | Number | No       | Foreground scale from `0.01` to `1`. Defaults to `0.5`.              |
| **Position**   | Enum   | No       | One of nine top, center, or bottom alignments. Defaults to `center`. |
| **Opacity**    | Number | No       | Foreground opacity from `0` to `1`. Defaults to `1`.                 |

The node preserves the foreground's aspect ratio. At scale `1`, the foreground
is sized to fit the background along the limiting dimension; at `0.5`, that
fitted size is halved.

Available positions are:

```text theme={null}
top-left       top-center       top-right
center-left    center           center-right
bottom-left    bottom-center    bottom-right
```

## Output

| Output              | Type | Description                                                         |
| ------------------- | ---- | ------------------------------------------------------------------- |
| **Composite Image** | File | The combined image, using the background file's name and MIME type. |

## Example: place a watermark

Use the source image as **Background**, a transparent logo as **Foreground**,
set **Scale** to a small value such as `0.15`, choose `bottom-right`, and lower
**Opacity** to `0.6`.

<Note>
  Positions align directly to an edge or corner; the action has no margin input.
  Add transparent padding to the foreground first when the overlay needs inset
  spacing.
</Note>

## Troubleshooting

<AccordionGroup>
  <Accordion title="The overlay is larger than expected">
    Scale is relative to the background's limiting dimension, not the
    foreground's original size. Reduce **Scale**.
  </Accordion>

  <Accordion title="The output format is wrong">
    The output follows the background file's name and MIME type. Convert the
    background before overlaying, or convert the composite afterward.
  </Accordion>
</AccordionGroup>