The shapes a page lays over what it draws

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. Reading software shows them over the page, lists them beside it, and can be told to keep them off the paper. Each carries a note that reading software shows when a mouse rests on it.

Request schema

• page_review_marks — array, optional, empty by default.
• page_review_marks[].page — integer ≥ 1, required. The page the shapes are for.
• page_review_marks[].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, redaction.
• 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, each one of none (nothing drawn, which is what an end left out carries), square, circle, diamond, open_arrow, closed_arrow, butt, reverse_open_arrow, reverse_closed_arrow or slash. 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.
• redaction — llx, lly, urx, ury: numbers, all required, the part marked. over — array, optional, the patches inside it, each four corners counterclockwise; absent marks the rectangle itself. fill — colour, optional, what the emptied patch is filled with. overlay_text — string, optional, the words printed where the content was. repeating — boolean, optional, false by default, whether those words are set again and again until the patch is full. aligned — one of left (the default), center and right, where those words sit; read only beside words.
• A redaction states what must go. It does not take it out. What fill, overlay_text and aligned describe is the page as it will be once reading software has applied the mark and written the document out again: until that happens the words are still in the file under the mark, and a search finds them.
• Common to every shape: contents — string, optional, the note reading software 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.