HowItWorks
At a glance, the format of handling and generating the different Polyanno objects may appear unecessarily elaborate but it has been done for compatibility and interoperability purposes. This section is here for those interested in understanding that better.
The W3C Web Annotation Model is a standard designed to ensure that everyone's annotations, such as transcriptions, translations, or comments, are all defined consistently across the internet so that the relationships are more easily understood by computers, and so that people can swap and share the information without breaking each others' codes.
The standard asks that for the annotation relationships that exist, you generate a JSON file, ideally with a unique URL for an id, that points to the thing being annotated (the body property) and the thing that is doing the annotating (the target property).
A diagram of an annotation file
In order to comply with this, Polyanno breaks down the different annotation components involved with the transcription and translation of an image:
A diagram of typical components involved with a Polyanno annotation model
Polyanno generates annotation JSONs defining firstly, that the shapes drawn around text on the image (known as vectors) are annotations of the image:
Diagram of the annotation model structure of the shapes to the image
Then defining the textual components (assumed to be transcriptions and translations) to be annotations of the shapes, and the specific regions of the image (defined through the IIIF format):
Diagram of the annotation model structure of the text to the image regions and shapes
Finally also defining components that are inside (smaller than and fully enclosed by) other components as annotations of, sometimes informally referred to as "children" of, the outside, "parent", components. For example shapes inside other shapes, or sentences inside paragraphs.
Diagram of the annotation model structure of the hierarchy or granularity of the components
For a given image handled by Polyanno, there may be various different components that are bodies and/or targets, and various annotation files defining their relationships:
Diagram showing the annotation model components involved with one image
In this documentation, a single annotation model refers to all the components involved in a single annotation file including the annotation file itself.
Therefore multiple, adjacent, independent annotation models may be present for a single image:
Diagram showing multiple independent adjacent annotation models for one image
Within the Polyanno UI, there exist individual boxes on screen for each different process of generating or updating models, for example a box to type a new transcription.
Polyanno editors are objects not involved in the model but used within the application to contain both the information about these HTML boxes within the UI, and the other information involved with that annotation model, such as the vector that the new transcription is annotating and the annotation JSON defining this.
The Polyanno UI with a box open to allow the creation of a new transcription component - the information about this and the model it is handling will be defined in a Polyanno.editor object
Similarly to prevent unnecessary repetitive retrieval of models and their components throughout processes, especially when the user may not commit to this information, when a process is live the models handled are temporarily stored in Polyanno.selected object properties.
For more information about the Web Annotation Model basics and the model structures used in Polyanno check out this presentation.
To interact with and contribute to the annotation models, there are various processes that can happen within Polyanno.
The Polyanno objects can be used to import and export information compliant with the relevant standards outlined in this documentation by using AJAX to move from the client side. There is in-built support for using the dedicated Polyanno Storage Node back-end package for storage.
The Polyanno UI showing the menu for a new shape drawn.
Through the Leaflet Draw plugin tools, users can draw new shapes on the image to select regions of text. The shape tools enabled by default are rectangles and polygons.
The Polyanno UI showing the editor open for adding a new transcription for a new shape
However new shapes MUST be independent to other existing shape's annotation models on the page i.e. the shapes MUST NOT:
- overlap with other existing shapes
- contain other existing smaller shapes inside
- be inside other existing larger shapes
An example of independent adjacent shapes
To add new shapes to other existing annotation models, the buildingParents or connectingEquals processes must be used instead.
A "child" text is highlighted inside a larger "parent" one so that more information can be added to that specific selection
Users can select or "highlight" text within editor boxes so as to generate a new dedicated "child" model around that specific text selection and add further data to it.
The Polyanno UI showing the transcription in the editor box on the right for the shape selected during the building parents process
The buildingParents process is enabled by selected the "building parents" button: 
Once active, the user can then select independent adjacent shapes (those that do not overlap in any way) in the order that the text is read in the image.
Polyanno then generates a suggested new "parent" shape that encloses all of the user selected "children" shapes but also importantly generates a "parent" transcription, and translation with the text in the chosen order.
The Polyanno UI showing the suggested new "parent" shape in yellow for the two selected two blue shapes
The "child" text without a dedicated shape has the option in its editor to draw one for it inside the "parent" shape
The connectingEquals process allows users to draw shapes for transcriptions and translations that are annotating an image but do not yet have anything specifying the image region specific to the text.
In Polyanno these will typically either be texts imported through a REST API or textual "children" such as those generated from the textHighlighting process. This allows sufficient information about their annotation models to allow for verification, such as checking that the new "child" shapes are inside the corresponding "parent" shapes.
For more information about the development of the Polyanno processes check out this presentation.
Polyanno allows several alternative "child" annotation model layers to be added for any given "parent". For example, several alternative transcription texts to be generated for a given phrase within a paragraph of transcription text.
When multiple alternatives exist, users can vote between them by clicking on the "upvote button" when present in an editor box.
After a user has voted the highest ranking "child" is then pushed to the "parent". For example, if the most upvoted transcription is now "cat" instead of "chat" then the paragraph containing the phrase has that instance of "chat" replaced by "cat".
This means that whenever a "parent" model or its components are taken in isolation they contain the best combination of the "children".
Additionally, within the JSONs of annotation model components the voting information is stored in the voting properties of the object - see Polyanno Objects for more information on this.