`add_images`

Stamp user-specified images onto PDF pages

Usage

pdftl <input> add_images <spec>... output <file>

Details

Add user-specified images to PDF pages as overlays or underlays.

An image rule specification has the format:

[page range]<delimiter><image path(s)><delimiter>[<options>]

<delimiter> must be a single, non-alphanumeric character (e.g., /, !, #). Multiple image paths within delimiters can be separated by spaces or commas.

Options

Options are passed as comma-separated key=value pairs inside parentheses, e.g., (position=top-right, scale_mode=fit, opacity=0.5).

Positioning and Layout Options

underlay=<true|false>: Draw the image behind the page contents instead of on top. Default: false.
scale_mode=<stretch|fit|fill|none>: Aspect ratio preservation logic. Default: none.
position=<keyword>: Preset position (top-left, center, bottom-right, etc.). Default: bottom-left.
width=<dim>, height=<dim>: Dimensions with a unit (e.g., 10cm, 2in, 150pt).
offset-x=<dim>, offset-y=<dim>: Extra offset displacement relative to the anchor position. Default: 0.
opacity=<float>: Transparency setting between 0.0 (transparent) and 1.0 (opaque). Default: 1.0.

Examples

Stamp a logo on the top right of all pages

pdftl in.pdf add_images '/logo.png/(position=top-right, width=5cm, offset-x=-0.5cm, offset-y=-0.5cm)' output out.pdf

Add a background underlay image to even pages, scaling to fill

pdftl in.pdf add_images 'even!background.jpg!(underlay=true, scale_mode=fill)' output out.pdf

Overlay a semi-transparent watermark centered on page 1

pdftl in.pdf add_images '1#watermark.png#(position=center, opacity=0.3, width=200pt)' output out.pdf

Tags: in_place, images, overlay, underlay

Source: pdftl.operations.add_images

Read online: https://pdftl.readthedocs.io/en/latest/operations/add_images.html

Type: Operation

add_images