What a Picture Says about Itself, and How It Is Read

Attach to a supplied picture its author and its rights, and say which of its pixels show, how opaque they are and which way up it is drawn.

See It in a Real PDF

Every Picture a Scanner Put in One File

A file of three sheets and a file holding one photograph, each picture on a page cut to its own size; the photograph goes in exactly as the camera wrote it, since reading software reads a photograph itself.

Open the PDF The Whole Example

Also shown in: A Register Whose Pages Say Where They Came From

Summary

A photograph belongs to somebody. The camera, the scanner or the picture library has usually written that down already, in the file itself, and those lines can be passed on exactly as they stand — or replaced by yours, where the picture came without any. Either way they travel with the image, inside the document, and stay with it when it is pulled back out. The same entry says how the picture is read: which of its pixels let the page show through, whether a second grey picture says how opaque it is pixel by pixel, and which way up it is drawn when its own file says the wrong thing.

Technically

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

images states what each supplied image says about itself, in an XMP packet written on the image XObject itself. Two ways: facts, from which the server writes the packet; or the name of a supplied part carrying a packet written elsewhere, passed on as it stands, with nothing added and nothing checked. An image never claims a standard on its own account: the standard is said once, by the document. Saying nothing about an image is the ordinary case, and an image no item draws never reaches the document. The same entry states what the XObject itself is written with: the stencil, the two kinds of mask, the see-through sample values, the range each component is read over, the orientation and the profile its colours are read through.

Request Schema

  • images — array, optional, empty by default.
  • images[].name — string, required. The name of the supplied part this entry describes, the very one an image item uses.
  • images[].metadata — optional. Two shapes:
    • {"facts": {...}} — the same fields as metadata: title, author, subject, producer, created, trapped, schemas. The server writes the packet from them.
    • {"packet": "part name"} — the name of a supplied part carrying a packet written elsewhere. What reading software finds there is what was given.
  • images[].files — array of strings, optional, empty by default. The names of the declared attachments the picture claims: the record of the scan it came from, the measurements taken of it, whatever a machine reads beside the pixels. An attachment claimed here belongs to the picture rather than to the document.
  • images[].stencil — boolean, optional, false by default. Whether the picture is read as a stencil rather than as a picture: it has no colour of its own and says where to put the colour the page is already filling with. A picture that is not one bit a pixel, of one component, is refused.
  • images[].stencil_mask — string, optional. The name of the supplied part whose zero bits say which of this picture's pixels show. That part is read as a stencil and is drawn nowhere itself.
  • images[].soft_mask — string, optional. The name of the supplied grey part whose samples say how opaque this picture is, pixel by pixel: black is see-through, white is solid. It is stretched over the picture, so the two need not be the same size, and it is drawn nowhere itself.
  • images[].color_key — array of pairs of integers, optional, one pair per component. The lowest and the highest sample value that is see-through. A pixel shows the page only where every one of its components falls in its pair. The values are the numbers the samples are stored as, not the colour they stand for.
  • images[].opaque — boolean, optional, false by default. Whether whatever the file says shows through the picture is dropped, so that nothing shows through it at all. This is the answer to a file with an alpha channel a standard will not have.
  • images[].decode — array of pairs of numbers, optional, one pair per component. The range each component is read over: the value its lowest sample stands for, then the value its highest stands for. A pair running end for end draws the picture as its own negative. Absent reads every component over the range its colour space is read over by default.
  • images[].orientation — string, optional. Which way up the picture is drawn, whatever its own file says. A camera stores a picture the way its sensor read it and records how the body was held; this is what a request states instead, for a file whose camera recorded the wrong thing. Eight values: upright, drawn the way its pixels are stored; mirrored_left_to_right, its left and right sides swapped; upside_down, turned by half a turn; mirrored_top_to_bottom, its top and bottom swapped; turned_left and turned_right, a quarter turn anticlockwise and clockwise; mirrored_and_turned_left and mirrored_and_turned_right, mirrored and then turned that quarter turn.
  • images[].icc_profile — string, optional. The name of the supplied part carrying the ICC profile the picture's colours are read through. A file may carry one of its own, and naming one here stands over it. The profile describes the components the picture's own colours are made of, or it is refused, and naming it on a picture read as a stencil is refused.
  • images[].opacity_channel — string, optional. In a TIFF an editor saved several opacity components in, the name of the one that says how opaque the picture is; absent takes the first the file says is opacity. The colours the file multiplied by one of those components are divided back by it, every other one is dropped, and a component the file says nothing of the meaning of is read as opacity standing apart from the colours. A name on a part that is not a TIFF, or one no component was saved under, is refused.
  • images[].clipping_path — object, optional. The path the picture is held inside where an image item states clip_to_path, standing over the one its own file carries. It takes contours, an array of closed contours. A contour takes knots, an array of the points it runs through in cubic Bézier curves, the last curve arriving back at the first knot. A knot takes anchor, the point the contour passes through, and arriving and leaving, the control points of the curves arriving at it and leaving it. Each is an [x, y] pair in fractions of the picture as it is stored, x from its left edge and y from its bottom edge, so a picture turned or mirrored on its way into its box carries its path with it. A knot whose control points are its anchor makes the curves either side of it straight. Where contours overlap, a point inside an even number of them is outside the path. A path with no contour holds nothing, and the picture is drawn whole.
  • A part carrying a packet written elsewhere writes its properties without their description: the standard is stated once, by the document.
  • images[].interpolate — boolean, optional, false by default. Whether reading software smooths the picture where it is drawn larger than its pixels. The picture then no longer shows exactly what it holds, which is why a document claiming an archive standard refuses it.
  • images[].rendering_intent — string, optional. How reading software brings the picture's colours into what the device can show, written on the picture itself and standing over the intent of the graphics state it is drawn under: absolute_colorimetric, relative_colorimetric, saturation or perceptual.
  • images[].inks — object, optional. The inks of the press the samples are the tints of, stated in full as a declared separation or device_n space is under color_spaces: a grey scan printed in one spot colour, a varnish, a white laid under a label. The samples are not touched, only what they are read as, so the picture has as many components as the space has inks. Any other kind of space is refused, and so are a picture naming measured as well, a stencil, a picture indexing a table of colours, one read through a profile, and a JPEG 2000 or JBIG2 stream.
  • images[].measured — object, optional. The measured colour the samples are read as, stated in full as a declared cal_gray, cal_rgb or lab space is under color_spaces: a scan from a calibrated scanner, a colorimeter's readings. The samples are not touched, only what they are read as, so the picture has as many components as the space takes: one for cal_gray, three for the other two. Any other kind of space is refused, and so are a picture naming inks as well, a stencil, a picture indexing a table of colours, one read through a profile, and a JPEG 2000 or JBIG2 stream.
  • images[].jbig2 — object, optional. {} says the part is a JBIG2 stream, which is never recognised from its bytes; {"globals": "part name"} also names the supplied part holding the segments the stream is read against. The bytes are carried as they stand. A part whose segments never state the size of the page is refused, and so are a picture number and an opacity channel beside it, both of which belong to a TIFF.
  • images[].fax — boolean, optional, false by default. Whether a picture of one bit a sample is carried coded the way a fax machine codes a page, CCITT group 4.

A Whole Request That Creates a PDF

{
  "images": [
    {
      "name": "photo",
      "orientation": "upright",
      "metadata": {
        "facts": {
          "author": "Camille Roy",
          "subject": "The workshop, June 2026"
        }
      }
    }
  ],
  "items": [
    {
      "type": "image",
      "image": "photo",
      "rect": { "llx": 60, "lly": 560, "urx": 300, "ury": 740 }
    }
  ]
}

The line that sends it, in three languages

The document as a whole

The Numbers Reading Software Shows A Hundred Letters in a Single File What the Document Says about Itself What the Document Says about Itself, Said Once Text Nobody Can Copy The Notes a Program Leaves in the File for Itself The Notes a Program Leaves on One Page The Data a Program Hangs on a Run of Ink A File Still Readable Decades from Now The Print Standard the Document Claims The Variable Print Standard the Document Claims The Password That Opens It, and What May Be Done with It An Invoice a Person and a Machine Both Read The Address Relative Links Are Read Against The PDF Version the File Declares The Extensions to PDF the File Says It Uses The Attachments the Document Carries Beside Its Pages Files the Document Names without Carrying The Attachments Shown as a Portfolio Which Attachments a Page Claims Which Attachments a Font Claims The Identity Card a Single Font Carries Which Attachments the Document's Card Claims A Document Card Written Elsewhere The Areas of a Page a Reader Measures In The Identity Card a Single Page Carries The Accessibility Standard the Document Claims The Standards the Finished Document Is Measured Against

Where to Go Next

Every JSON key of a request, in one page The other forty-one settings of a request

See the Prices See the Examples