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.
In plain words
Written for anybody. It says what this puts on a sheet of paper, and asks nothing of you beyond that.
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 then you say « put that one here, at this size ». The file holds the drawing a single time and refers to it everywhere else, which is why a hundred pages of the same badge weigh barely more than one. You can also turn it, or stretch it, without redrawing anything.
For a developer
Written for somebody who writes the calling program: the model, the units, and the settings that carry the weight.
Asked for with
"type": "drawing"
A drawing item places a drawing declared in drawings on the page. 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. 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.
Every key, with its default
The reference: which keys are required, which are optional, what each one defaults to and which combinations the server declines.
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 a marked run the structure tree claims; artifact, what the drawing is furniture of. 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 x, y, width and height bounding the part of its own space that is kept), items, the shapes it is made of, and an optional matrix of six numbers.
A whole request that draws it
Post this as it stands and a PDF comes back. Nothing has been left out of it.
{
"drawings": [
{
"name": "badge",
"box": {"x": 0, "y": 0, "width": 60, "height": 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]}
}
]
}
],
"items": [
{"type": "drawing", "drawing": "badge", "x": 72, "y": 700},
{"type": "drawing", "drawing": "badge", "x": 160, "y": 700, "scale": 0.5}
]
}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 key of a request, in one page The other twenty things you can draw
Glossary
- CMYK
- The four inks a printing press lays down: cyan, magenta, yellow and black. A screen mixes light instead, so a document going to a press states its colours in inks, not in screen colours.
- structure tree
- The list, held inside a tagged PDF, that says what each part of the page is and what it belongs to: this block is a section, this line its heading, this run of cells one row of that table. It is the shape of the document, kept apart from the ink.
- signature
- A seal inside the document that proves two things at once: who approved it, and that not one byte has changed since. A reader shows it as a banner at the top of the page.
- request
- One call to the service: you send what the document should say, and get the document back. Your bill counts these calls, one for each document. The number of pages inside a document is never counted.
- layer
- A named group of things drawn on a page that a reader can switch on and off, like tracing paper laid over a plan. A drawing can hold its measurements on one and its notes on another, and a layer can be set to show on screen and stay off the printer.