What an image says about itself

In plain words

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

A photograph belongs to someone. When it goes into a document, it is often useful to say in passing who took it, where it came from, and what may be done with it. You can write those details by hand, or pass on as they stand the ones the camera, the scanner or the picture library already put in the file. Those details then travel with the image, inside the document.

For a developer

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

images states what each supplied image says about itself. Two ways: facts, from which the server writes the metadata packet; or the name of a supplied part holding 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.

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.

• 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 — required. 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 holding a packet written elsewhere. What a reader finds there is what was given.
• A part carrying a packet written elsewhere writes its properties without their description: the standard is stated once, by the document.

A whole request that draws it

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

{
  "images": [
    {
      "name": "photo",
      "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

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.

the identity card of a file

The block inside a file that says what the file is: its title, who made it, when, and which rules it follows. Search engines and archives read it; a reader never sees it. Its technical name is XMP.

server

A machine that waits for calls and answers them, running day and night with nobody sitting at it. The one that draws documents here holds the engine and hands back the finished pages; the one your website runs on is a different machine doing the same kind of job.

Every word the site explains