The device the colours are stated for

Name the press or the screen the document's colours were chosen for, so they come out as intended.

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

In plain words

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

A red is not a red. The same red does not look the same on a screen, on glossy paper and on newsprint. So that the colour comes out as intended, the document names the device it was chosen for: such a reference screen, such a press, such a paper. The printer reads that note and knows exactly where it stands. Short of it, the document simply says its colours are those of the ordinary screen.

For a developer

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

output_intent states the device the document's colours are stated for: that device's profile, and the name its condition is known by. A page that fills with four numbers is a page of ink on a press, and the file names the press it was separated for, or the four numbers stand for nothing. Short of a supplied profile, the library writes the sRGB profile it carries. An archiving standard expects this statement.

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.

  • output_intent — object, optional. Absent, the file says its colours are sRGB.
  • output_intent.profile — string, optional. The name of the supplied part holding the ICC profile. Absent, the library writes the sRGB profile it carries.
  • output_intent.space — string, optional. The space the profile describes. Three values: gray, rgb, cmyk. Absent, the space is read from the profile, which is what says which it is; writing it has the profile checked against it.
  • output_intent.identifier — string, required. The short name the condition is registered or known under: FOGRA39, CGATS TR 001, sRGB.
  • output_intent.info — string, optional, empty by default. The sentence a person reads to tell one condition from another.

A whole request that draws it

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

{
  "output_intent": { "identifier": "sRGB", "info": "sRGB IEC61966-2.1" },
  "standard_fonts": [{ "name": "sans", "face": "helvetica" }],
  "items": [
    {
      "type": "rect",
      "rect": { "llx": 60, "lly": 690, "urx": 240, "ury": 770 },
      "fill": [0.85, 0.15, 0.15]
    },
    {
      "type": "text",
      "rect": { "llx": 260, "lly": 720, "urx": 535, "ury": 740 },
      "content": ["Colours stated for sRGB"],
      "font": "sans",
      "font_size": 12
    }
  ]
}

The line that sends it, in three languages

Colour and how it is shown

Declaring colour beyond red, green and blue A colour sliding into another 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

PDF library
A piece of software your own programs use to write PDF documents. It has no window and no buttons: your program tells it what to draw, and it hands the finished file back. This site also calls it the engine, which is the same thing under another name. The server is a second program that holds the engine and answers whoever asks it for a document over the network, and the rendering service is that server running on our machines rather than on yours.
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.
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.
RGB
The three lights a screen mixes a colour from: red, green and blue. All three at full is white, all three off is black. It is how a colour is said for anything lit from behind, and the wrong way to say one for a press, which lays ink on white paper instead.

Every word the site explains