The shapes a page carries over its drawing

Lay squares, circles, lines and outlines over a page, each with its own colour, border and note.

Summary

Some marks belong over a page rather than in it: the circle around a clause, the line that ties a comment to a figure, the outline drawn around an area of a plan. A reader shows them over the page, lists them beside it, and can be told to keep them off the paper. Each carries a note that a reader shows when a mouse rests on it.

Technically

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

page_annotations writes the /Annots of a page: one entry per page, and inside it the shapes in the order they are written. Five kinds are taken, each naming itself under type: square and circle, inscribed in the rectangle they state; line, between two points; polygon, a closed run of segments; and polyline, an open one. Every shape takes the same six common keys, and the shapes of the last entry given for a page are the ones that page carries.

Request schema

  • page_annotations — array, optional, empty by default.
  • page_annotations[].page — integer ≥ 1, required. The page the shapes are for.
  • page_annotations[].shapes — array, required. The shapes that page carries, in the order they are written.
  • shapes[].type — string, required. One of square, circle, line, polygon, polyline.
  • square and circle — llx, lly, urx, ury: numbers, all required, the rectangle the shape is inscribed in. interior — colour, optional, what fills it. effect — plain or cloudy, optional, how the border is drawn.
  • line — x1, y1, x2, y2: numbers, all required. endings — object, optional, what each end carries, under from and to. interior — colour, optional, what fills those endings.
  • polygon and polyline — vertices: array of two-number pairs, required. interior — colour, optional. polygon also takes effect, polyline also takes endings.
  • Common to every shape: contents — string, optional, the note a reader shows. name — string, optional, what the shape is known by. color — colour, optional, the border's own. border — object, optional, width in points and an optional dash. layer — string, optional, the declared layer the shape is drawn on.
  • shapes[].flags — object, optional. printed — boolean, whether the shape goes on paper. hidden, no_view, no_zoom, no_rotate, invisible, read_only — booleans, false by default.

A shape is laid over the page, not into what the page draws: it is kept out of the text a reader copies, and out of the structure a document states about itself.

A whole request that draws it

{
  "page_annotations": [
    {
      "page": 1,
      "shapes": [
        {
          "type": "square",
          "llx": 60, "lly": 640, "urx": 300, "ury": 700,
          "color": { "rgb": [0.8, 0.1, 0.1] },
          "border": { "width": 2 },
          "contents": "The clause under discussion",
          "flags": { "printed": false }
        }
      ]
    }
  ],
  "standard_fonts": [{ "name": "sans", "face": "helvetica" }],
  "items": [
    {
      "type": "text",
      "rect": { "llx": 60, "lly": 740, "urx": 535, "ury": 765 },
      "content": ["A square laid over the clause, and kept off the paper"],
      "font": "sans",
      "font_size": 14
    }
  ]
}

The line that sends it, in three languages

The sheet, and what is laid under it

The size of the pages A size of its own for certain pages The unit a page is measured in The areas a page states Which way up a page is shown How a page arrives, and how long it stands How far a supplied PDF is allowed to unpack The headed paper under the pages

Where to go next

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

See the prices See the examples