A picture placed in a rectangle
Place a photo or a logo supplied with the request in a chosen frame, stretched to the edges or kept at its own proportions.
Summary
Your photo or your logo travels with the request, and settles into the frame you point at. Filling the frame edge to edge suits a background; keeping the original shape and centring in what is left suits a portrait or a product, which filling edge to edge would squash. The same picture can serve in several places, small in a corner and large on another page, without being sent twice.
Technically
Asked for with
"type": "image"
The image bytes travel with the request, in a supplied part of the multipart/form-data body; the image key repeats that name. It is the same pool of supplied parts the templates come from, so several items draw the same picture at different sizes and places, for one upload and one copy inside the finished file. That part is written as an image XObject — DCTDecode for a JPEG, FlateDecode for a PNG or a BMP, with an SMask where the picture is transparent — and painted with Do inside the frame. The frame is a rectangle in points; the fit says whether the picture fills that rectangle or keeps its proportions. The item takes the same placement settings as the others: chosen pages, matrix, rotation and layer.
Request schema
Required keys: image, a string naming the supplied part; rect. Optional: fit, either a mode alone or an object. The mode is stretch (the default, the picture fills the rectangle), contain (it keeps its proportions and centres in what is left), cover (it keeps its proportions and covers the rectangle whole, clip holding off what hangs over), natural (its own size, whatever the rectangle) or shrink_to_fit (as contain, except that a picture already smaller than the rectangle is left at its own size). The object takes mode (default stretch); anchor, where the sized picture sits, one of bottom_left, bottom, bottom_right, left, center (the default), right, top_left, top, top_right, or two fractions [x, y] from 0 to 1 counted from the left edge and the bottom; margin, points taken off every side before anything is fitted, 0 by default; turn, how far the picture is turned on its way in, upright by default; mirror, one of neither (the default), left_to_right, top_to_bottom or both; clip, a boolean at false, whether what hangs over the box is held off the page. clip_to_path, a boolean at false, whether the picture is held inside the path its own file carries — the outline an editor saves when it cuts a picture out of its background; a picture whose file names none is drawn whole. pages, an array of one-based integers, default empty for every page; transform, six numbers; rotate, degrees counter-clockwise about the centre of the rectangle; layer, the name of a declared layer. Cross refusal: transform together with rotate. An image name the request leaves unsupplied answers 400.
A whole request that creates a PDF
{
"items": [
{
"type": "image",
"image": "logo.png",
"rect": {"llx": 72, "lly": 660, "urx": 192, "ury": 780},
"fit": {
"mode": "contain",
"anchor": "top_left",
"turn": "upright",
"mirror": "neither"
}
}
]
}Pictures and imported pages
Where to go next
Every JSON key of a request, in one page The other twenty-two things you can draw