Sheets a reader shows or hides

In plain words

Written for anybody. It says what this puts on a sheet of paper, and asks nothing of you beyond that.

An architect works with transparent sheets stacked up: the walls on one, the furniture on another, the dimensions on a third. Lifting one takes it out of view. Here it is exactly the same gesture. What you draw is sorted into named layers, and whoever reads the document ticks or unticks the layer they care about. You can also decide a layer shows on screen but stays off the print — a draft watermark, for instance. A layer can also show itself on its own, with nobody ticking anything: the fine dimensions of a plan appear once a reader has come close enough to read them, and a legend written twice, in two languages, shows each reader the one they set their program to.

For a developer

Written for somebody who writes the calling program: the model, the units, and the settings that carry the weight.

layers declares the layers the document defines for itself, each under the name an item says it is drawn on. A reader lists them in its panel, in the order the request declares them, and shows or hides everything on one of them at once. Screen display and printing are set apart: naming them opposite answers builds a layer that is only ever looked at, or only ever printed. A layer can also show itself without the panel: a zoom shows it between two magnifications, and a language shows it to a reader set to that language and hides it from the layers of every other. A layer the panel refuses to switch is locked, and still starts where visible puts it.

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.

layers — array, optional, empty by default.
layers[].name — string, required. The name items name this layer by, and the name a reader's panel shows.
layers[].visible — boolean, optional. Whether the layer starts shown. Absent, it starts shown.
layers[].printed — boolean, optional. Whether printing shows the layer, whatever the panel says. Absent, printing follows the panel.
layers[].on_screen — boolean, optional. Whether looking at the document shows the layer, whatever the panel says. Absent, the screen follows the panel.
layers[].locked — boolean, optional, false by default. Whether the reader's panel refuses to switch the layer. A locked layer keeps its entry, showing the state it starts under, and still starts where visible puts it.
layers[].zoom — object, optional. The magnifications the layer shows itself between, whatever the panel says. Absent shows it at every magnification, and an object naming neither bound is refused.
layers[].zoom.from — number, optional. The magnification the layer is shown from, that one counted in. Absent leaves it no floor, which is 0.
layers[].zoom.to — number, optional. The magnification the layer is shown below, that one left out. Absent leaves it no ceiling. A pair nothing can satisfy — a from at or above the to, or a from below zero — is refused.
layers[].language — string, optional, no language by default. A language tag, fr-FR or en-GB. A reader set to that language shows this layer and hides the layers of every other language, which is how one sheet carries its wording twice and shows one of them.
layers[].preferred — boolean, optional, false by default. Whether this is the layer a reader falls back on when no layer states the language it is set to exactly. Stating it without a language is refused.
An item sits on a layer through its layer key, carrying the name declared here. An item with no layer is always there, under every layer.
Layers want PDF 1.5 at least.
A document stating an archive standard refuses a layer that states printed, on_screen, zoom or language: an archival file leaves that decision to the reader. The layer itself is fine, and so is locked, which makes nothing on the page depend on what the page is being looked at for.

A whole request that draws it

Post this as it stands and a PDF comes back. Nothing has been left out of it.

{
  "layers": [
    { "name": "Dimensions" },
    { "name": "Draft", "on_screen": true, "printed": false },
    { "name": "Crop marks", "locked": true },
    { "name": "Fine print", "zoom": { "from": 2 } },
    { "name": "French wording", "language": "fr-FR" },
    { "name": "English wording", "language": "en-GB", "preferred": true }
  ],
  "standard_fonts": [{ "name": "sans", "face": "helvetica" }],
  "items": [
    {
      "type": "rect",
      "rect": { "llx": 80, "lly": 560, "urx": 380, "ury": 760 },
      "stroke": { "width": 2 }
    },
    {
      "type": "text",
      "rect": { "llx": 80, "lly": 540, "urx": 380, "ury": 556 },
      "content": ["300 by 200"],
      "font": "sans",
      "font_size": 10,
      "layer": "Dimensions"
    },
    {
      "type": "text",
      "rect": { "llx": 80, "lly": 700, "urx": 380, "ury": 740 },
      "content": ["DRAFT"],
      "font": "sans",
      "font_size": 36,
      "color": [0.85, 0.85, 0.85],
      "layer": "Draft"
    },
    {
      "type": "text",
      "rect": { "llx": 80, "lly": 520, "urx": 380, "ury": 534 },
      "content": ["Shown from twice the page size upwards"],
      "font": "sans",
      "font_size": 7,
      "layer": "Fine print"
    },
    {
      "type": "text",
      "rect": { "llx": 80, "lly": 480, "urx": 380, "ury": 496 },
      "content": ["Plan du premier etage"],
      "font": "sans",
      "font_size": 11,
      "layer": "French wording"
    },
    {
      "type": "text",
      "rect": { "llx": 80, "lly": 480, "urx": 380, "ury": 496 },
      "content": ["First floor plan"],
      "font": "sans",
      "font_size": 11,
      "layer": "English wording"
    }
  ]
}

The line that sends it, in three languages

What is drawn, and how it comes out

Everything that can be drawn on a page The file's weight and the time it takes A drawing made once, shown by a button

Where to go next

Every key of a request, in one page The other thirty-two settings of a request

See the prices See the examples

Glossary

standard: A rule argued out in committee, published under a number anybody may buy and read, and identical for every firm claiming it. A claim to follow one can therefore be checked against the text. A way of working that merely spread because it worked is a habit of the trade: useful, widespread, and answerable to no text at all.
transparency: Paint that lets what is underneath it come back through, by a stated amount. It is what makes a mark laid across a page leave the text under it readable, and a highlight a highlight rather than a blot. The file says how much comes through; whatever draws the page works out the colour that results.
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.
watermark: Wording printed across the page itself, saying the document was made with a free account. It cannot be removed from the file; a paid tier simply never puts it there.

Every word the site explains