A free path: lines, curves and filled shapes

In plain words

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

This is the free pencil: you say where to set the tip down, then the points to pass through, and the line follows. Straight segments make triangles, arrows and polygons; curves make round corners, waves and perfect circles. The resulting shape is filled with a colour or a gradient, edged with a stroke, or both. This is what a rule under a heading, a band behind a title and the ornament on a certificate are made of.

For a developer

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

A path is a sequence of segments applied in order: move_to opens a subpath at a point, line_to extends it with a straight edge, curve_to appends a cubic Bézier through two control points, and close shuts the subpath back onto its origin. Each coordinate is a number or an expression, so a path sits against the page width without the caller computing anything. Painting is said in two independent keys, the fill and the stroke; the fill takes a colour or the name of a declared gradient. An optional clip limits what the item shows, and it holds for that item alone: the items after it stay whole.

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 key: segments, an array of steps, each {"move_to": {"x", "y"}}, {"line_to": {"x", "y"}}, {"curve_to": {"x1","y1","x2","y2","x","y"}} or the string "close"; each coordinate is a number or an expression. Optional: fill, a colour or {"shading": "name"}; stroke, an object with a required width plus color (default black), dash (an object with a required lengths and a phase, default 0), cap (butt by default, round, projecting) and join (miter by default, round, bevel); clip, an object with a required segments and a rule (nonzero by default, even_odd); graphics_state, the name of a declared graphics state; pages, an array of one-based integers, default empty; transform, six numbers; rotate, degrees counter-clockwise about the centre of the box; layer, the name of a declared layer. Cross refusals: transform together with rotate; a clip whose segments are empty. A shape takes fill, stroke, or both.

A whole request that draws it

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

{
  "items": [
    {
      "type": "path",
      "segments": [
        {"move_to": {"x": 72, "y": 700}},
        {"line_to": {"x": 272, "y": 700}},
        {"line_to": {"x": 172, "y": 780}},
        "close"
      ],
      "fill": [0.85, 0.89, 0.95],
      "stroke": {"width": 1.0}
    }
  ]
}

The line that sends it, in three languages

Glossary

gradient

A colour that changes across the space it fills, with no step anywhere between one end and the other: a header that fades out, a bar with some depth to it. It is described once, in a handful of numbers, and painted wherever it is wanted, so it stays sharp at any size and weighs almost nothing.

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.

Bézier curve

A curve drawn from its two ends plus two points that pull it out of line, the way the handles in a drawing program bend a stroke. Every rounded shape in a PDF, and every letter of every typeface, is made of them.

Every word the site explains