Declaring colour beyond red, green and blue

In plain words

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

A brand's blue is not a blue approximated on a screen: it is a precise pot of ink, ordered from the maker, with a number on it. A printing works lays it down as a separate ink, on top of the usual four. For that, the document has to name it rather than mix it. A colour can also be described by its real measurement, the one an instrument takes, rather than by a screen recipe. You declare those colours here, under a name, and use them everywhere afterwards.

For a developer

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

color_spaces declares the colour spaces the document defines for itself, each under the name a colour selects it by. A device colour needs no declaration: three numbers are red, green and blue wherever they appear. A spot ink, a measured space or a profiled one is written into the document before a colour names it. Six kinds exist, each stated by its own numbers — save the ICC space, whose profile arrives as a supplied part.

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.

• color_spaces — array, optional, empty by default.
• color_spaces[].name — string, required. The name the request's colours select this space by.
• color_spaces[].space — object, required. Six kinds:
  • separation — colorant string required; ink array of four numbers optional; tint object optional. Exactly one of the two: both together are refused, neither is refused too.
  • indexed — base required, same recursive shape; entries array of bytes from 0 to 255 required, 256 entries at most.
  • lab — white_point three numbers required; black_point three numbers optional; range four numbers optional, −100 to 100 by default.
  • cal_gray — white_point three numbers required; black_point optional; gamma number optional, 1 by default.
  • cal_rgb — white_point three numbers required; black_point optional; gamma three numbers optional, 1 by default; primaries three by three numbers optional.
  • icc — profile string required, the name of a supplied part; space optional, otherwise read from the profile.
• tint — alternate required; low and high arrays of numbers required; exponent optional, 1 by default; domain two numbers optional, 0 to 1 by default; range array of pairs optional.
• A colour names a declared space through the shape {"space": "the name", "components": n, …}. The short forms stay available: [g] for a grey, [r, g, b], [c, m, y, k], and {"gray": n}.

A whole request that draws it

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

{
  "color_spaces": [
    {
      "name": "brand_blue",
      "space": {
        "separation": {
          "colorant": "Corporate Blue",
          "ink": [0.92, 0.58, 0.0, 0.06]
        }
      }
    }
  ],
  "items": [
    {
      "type": "rect",
      "rect": { "llx": 60, "lly": 700, "urx": 300, "ury": 780 },
      "fill": { "space": "brand_blue", "components": [1.0] }
    }
  ]
}

The line that sends it, in three languages

Glossary

byte

The unit a file's weight is counted in, the way a parcel is counted in grams. A thousand of them make a kilobyte, and a million make a megabyte — the size of one photograph taken with a telephone. A one-page PDF here weighs between six thousand and a hundred and twenty thousand, so a hundred of them fit in the space of five photographs.

colour profile

A file that says what a colour actually looks like. Without one, the same red is one red on your screen and another on a press. A document meant for print carries the profile its colours were chosen against.

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.

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.

colour space

The rule that says what a set of numbers means as a colour. The same three numbers are one red on a screen and another on a press, so a document says which rule it is speaking under. Say nothing and three numbers are read as the lights of a screen.

Every word the site explains