A Drawing Declared Once and Placed as Often as Wanted
Put a drawing the request declared on the page, where you want it and at the size you want, without the file carrying the same ink twice.
See It in a Real PDF
One Drawing, Placed Many Times
One badge built as a drawing and placed eight times, plus once at half size: the file carries the drawing once, however many times it is placed. A second page shows a badge that turns itself a quarter wherever it is placed, says what it is, and holds a file of its own: the guest list.
Open the PDF The Whole Example
Also shown in: The Notes a Program Leaves Itself · Text That Keeps to a Shape · One Drawing, and Each Reader Sees Their Own
Summary
A logo on a hundred pages, a signature block at the foot of every contract, a decorative border around each certificate: the shape is always the same, only its place changes. So you draw it once, you give it a name, and afterwards you simply say “that one, here”. A hundred pages of the same badge then weigh barely more than one. You can also turn it, or stretch it, without redrawing anything.
Technically
Asked for with
"type": "drawing"
A drawing item places a drawing declared in drawings on the page, painting its form XObject with Do. The drawing carries its own space and its own box; placing it says where that space's origin lands, at x and y in page coordinates, and what it is multiplied by, which is the matrix the item writes. The ink is written into the file once, whatever the number of placements, which is what keeps a repeated badge cheap. A placement takes the same reach as any other item: the pages it appears on, a matrix or a turn, a layer, and the tag the structure tree claims it by — or artifact, when the drawing is furniture rather than something the document says.
Request Schema
Required keys: drawing, the name of a drawing declared in drawings; x and y, each a number or a quoted expression, where the drawing's own origin lands from the left and bottom edges of the page. Optional keys: scale, a number the drawing's own space is multiplied by, 1 by default; pages, the one-based pages it is drawn on, empty for every page, or a rule that picks them out; transform, six numbers [a, b, c, d, e, f]; rotate, degrees counter-clockwise about the centre of its own box; layer, the name of a declared layer; tag and mark, stated together, which open marked content the structure tree claims; artifact, what the drawing is furniture of, one of header (a running head), footer (a running foot, a page number), watermark (laid over or under what the page says), pagination (what belongs to the pagination without being one of those three), layout (rules, boxes, shading: what separates what the page says rather than saying anything itself), page (what belongs to the making of the sheet: cut marks, registration targets, colour bars) or background (what is drawn behind what the page says). Cross refusals: transform together with rotate; artifact together with tag; a drawing naming nothing the request declared. A declared drawing takes name, box (an object of llx, lly, urx and ury bounding the part of its own space that is kept), items, the shapes it is made of, an optional matrix of six numbers, and an optional layer, the name of a declared layer the whole drawing belongs to — reading software that hides the layer hides the drawing wherever it is shown, including where no marked run reaches it, as a button's picture. A drawing a graphics state uses as a soft mask carries no layer. Among its shapes, a drawing alone holds a shaped_text block: text set inside a shape that need not be a rectangle — rect or ellipse, each an object of llx, lly, urx and ury, or polygon, an array of three corners or more, each [x, y] — its lines cut round each rectangle of around, an array of objects of llx, lly, urx, ury and gap, the room kept clear all round it. It takes content, font, font_size and every setting of a flowed text block, outline among them, the stroke round its letters, and narrowest, the narrowest stretch of a line in points; the words that do not fit are left out. artifact also names four more kinds: page_number, a page number standing on its own, apart from a running head or foot; bates, a number stamped on every page of a set of documents so that each page of the set can be cited; line_number, a number set in the margin beside the line it counts; redaction, the mark left where something was taken out. These four need PDF 2.0, which the request declares under version. In place of the word, artifact takes an object: kind, required, one of those eleven words; attached, an array of top, bottom, left and right, each named once, the edges of the page it hangs from, taken by pagination and by a background alone; bbox, the box it covers in the page's own points, an object of llx, lly, urx and ury. Every item that takes artifact takes either form.
A Whole Request That Creates a PDF
{
"standard_fonts": [{ "name": "sans", "face": "helvetica" }],
"drawings": [
{
"name": "badge",
"box": { "llx": 0, "lly": 0, "urx": 60, "ury": 60 },
"items": [
{
"type": "rect",
"rect": { "llx": 0, "lly": 0, "urx": 60, "ury": 60 },
"fill": [0.11, 0.31, 0.55]
},
{
"type": "line",
"from": { "x": 12, "y": 30 },
"to": { "x": 48, "y": 30 },
"stroke": { "width": 3, "color": [1, 1, 1] }
}
]
},
{
"name": "notice",
"box": { "llx": 0, "lly": 0, "urx": 160, "ury": 160 },
"items": [
{
"type": "shaped_text",
"shape": { "ellipse": { "llx": 0, "lly": 0, "urx": 160, "ury": 160 } },
"around": [{ "llx": 60, "lly": 60, "urx": 100, "ury": 100, "gap": 4 }],
"content": "Each line keeps inside the circle and round the square.",
"font": "sans",
"font_size": 9
}
]
}
],
"items": [
{ "type": "drawing", "drawing": "badge", "x": 72, "y": 700 },
{ "type": "drawing", "drawing": "notice", "x": 72, "y": 480 },
{
"type": "drawing",
"drawing": "badge",
"x": 160,
"y": 700,
"scale": 0.5,
"artifact": { "kind": "pagination", "attached": ["top"] }
}
]
}Shapes
A Free Path: Lines, Curves and Filled Shapes A Rectangle, Filled or Outlined A Straight Line between Two Points
Where to Go Next
Every JSON key of a request, in one page The other twenty-two things you can draw