What a picture says about itself, and how it is read

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.

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.
• A part carrying a packet written elsewhere writes its properties without their description: the standard is stated once, by the document.