A colour sliding into another

Declare a gradient, along a line or between circles, then fill a shape with it by naming it.

Written at the top level of a request, under "shadings"

In plain words

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

An evening sky goes from orange to blue with no telling where one stops. That is a gradient. Two kinds are built here: the one sliding along a line, from one point to another, and the one radiating from one circle to another, like a halo. You give it a name, then fill whatever shape you like with it: a title band, a card background, a disc.

For a developer

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

shadings declares the gradients the document defines for itself, each under the name a fill selects it by. A gradient is written as a pattern, so the colour shows through whatever the shape lets through rather than being painted over a clip. Each kind states its colours in two ways, and one at a time: two colours end to end, or a space and a function.

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.

  • shadings — array, optional, empty by default.
  • shadings[].name — string, required. The name a fill selects this gradient by.
  • shadings[].shading — object, required. Two kinds:
    • axial — from two numbers required, to two numbers required, in page coordinates.
    • radial — from and to in three numbers each, required: centre x, centre y, radius.
  • Both kinds share: start and end, optional colours, named together; space and function, optional, named together; extend, two optional booleans, [false, false] by default.
  • Exactly one of the two ways of stating the colour: start and end together, or space and function together. Both together are refused, neither is refused too.
  • start and end are stated in light; a CMYK colour is refused there.
  • function takes two shapes: exponential, with low and high required, domain two numbers optional (0 to 1), exponent optional (1) and range optional; stitching, with functions, bounds and encode required, domain and range optional.
  • Sampled functions and calculated functions are planned for a future version.
  • A fill names a gradient through the shape {"shading": "the name"}.

A whole request that draws it

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

{
  "shadings": [
    {
      "name": "sunrise",
      "shading": {
        "axial": {
          "from": [60, 700],
          "to": [300, 700],
          "start": [0.95, 0.75, 0.2],
          "end": [0.2, 0.35, 0.75]
        }
      }
    }
  ],
  "items": [
    {
      "type": "rect",
      "rect": { "llx": 60, "lly": 700, "urx": 300, "ury": 780 },
      "fill": { "shading": "sunrise" }
    }
  ]
}

The line that sends it, in three languages

Colour and how it is shown

The device the colours are stated for Declaring colour beyond red, green and blue Opacity and how colours mix The space a page mixes its colours in

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

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.
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.

Every word the site explains