Recipe #0561: Visible Text Annotation

_includes/links.md

@@ -82,6 +82,8 @@
 [0489]: {{ site.cookbook_url | absolute_url }}/recipe/0489-multimedia-canvas/ "Rendering Multiple Media Types on a Time-Based Canvas"
 [0540]: {{ site.cookbook_url | absolute_url }}/recipe/0540-link-for-opening-multiple-canvases/ "Sharing a link for opening two or more Canvases"
 
+[0561]: {{ site.cookbook_url | absolute_url }}/recipe/0561-text-on-image/ "Visible Text Resource on a Canvas"
+
 [cookbook-process]: {{site.cookbook_url | absolute_url }}/recipe
 
 [trc]: {{ site.root_url | absolute_url }}/community/trc/

index.md

@@ -95,6 +95,7 @@ _(leading on to segmentation examples later)_
 * [Using Annotation collections][0309]
 * [Image in annotations][0377]
 * [Annotating in Multiple Languages][0346]
+* [Visible Text Resource on a Canvas][0561]
 
 ## Internal structure
 

recipe/0561-text-on-image/index.md

@@ -0,0 +1,50 @@
+---
+title: Visible Text Resource on a Canvas
+id: 561
+layout: recipe
+tags: annotation
+summary: "Overlaying (painting) text on top of an image resource"
+viewers:
+topic:
+ - realWorldObject
+---
+
+## Use Case
+
+You would like to add text visibly over some portion of a IIIF image resource without making a derivative of the original image and retaining its deep zoom possibilities.
+
+## Implementation Notes
+
+This recipe aims to show the simplest form of a combination that is more likely to be used in combination with other IIIF recipes. For example, it forms a part of the [Multimedia Canvas][0489] recipe.
+
+Though the implementation is not complex, the implications get well into the nuances of IIIF. Making a textual annotation visible is the consequence of using a `motivation` value of `painting` on an Annotation in combination with placing that Annotation as an item inside an Annotation Page instead of as part of an `annotations` section. Making these two changes tells a client to display the text directly instead of separating it as an annotation to be handled in the client's manner of showing those. The Presentation API 3.0 states clearly that
++ Annotations in an `annotations` section are not permitted to have the `motivation` value `painting` ([Annotations](https://iiif.io/api/presentation/3.0/#annotations))
++ Conversely, Annotations referenced in `items` must have the `motivation` value `painting`. ([Canvas](https://iiif.io/api/presentation/3.0/#53-canvas))
++ Finally, content to be rendered must be in an Annotation with the `motivation` value `painting`. ([Motivation values](https://iiif.io/api/presentation/3.0/#values-for-motivation) and [Canvas](https://iiif.io/api/presentation/3.0/#53-canvas))
+
+Styling text or using HTML in text painted onto a Canvas is possible, but the options are limited. In addition, styling added to a manifest may be unreliable across viewers. For one example, since IIIF Canvas dimensions are unit-less, using pixels for text size is valid but may not be interpreted identically by different viewers. For a more detailed look at styles in Web Annotations, see [the W3C Web Annotation Data Model’s Styles section](https://www.w3.org/TR/annotation-model/#styles).
+
+The presentation of resources is upwards in a z-index from the first "painting" Annotation encountered to all subsequent "painting" Annotations. Therefore, for the textual annotation to be visible, it must come later in the manifest order of Annotations than the image resource it marks.
+
+## Restrictions
+
+Markup in the textual annotation is limited for security reasons. Clents are expected to allow only `a`, `b`, `br`, `i`, `img`, `p`, `small`, `span`, `sub`, and `sup` tags, and may remove any or all of those. For more details of permitted and prohibited markup, see the [HTML Markup in Property Values](https://iiif.io/api/presentation/3.0/#45-html-markup-in-property-values) section of the IIIF Presentation specification.
+
+## Example
+
+In this example, we have a base image showing people in the countryside, one of whom is carrying a wrapped koto. Hypothesizing for our use case that the wrapped koto is less identifiable to people unfamiliar with the scene, there is a textual annotation adjacent to it that indicates it. A viewer might render it as shown in this image:
+
+![One possible rendering of this recipe's manifest](image_visible_text.png)
+
+{% include manifest_links.html manifest="manifest.json" %}
+
+{% include jsonviewer.html src="manifest.json" config='data-line="41-52"' %}
+
+
+## Related Recipes
+
+* [HTML in Annotations][0019] for further discussion on markup in an Annotation
+* [Multiple Choice of Images in a Single View (Canvas)][0033] contains additional text about z-index ordering
+
+{% include acronyms.md %}
+{% include links.md %}

recipe/0561-text-on-image/manifest.json

@@ -0,0 +1,54 @@
+{
+    "@context": "http://iiif.io/api/presentation/3/context.json",
+    "id": "{{ id.url }}",
+    "type": "Manifest",
+    "label": { "en": [ "Visible Text Annotation" ] },
+    "items": [
+      {
+        "id": "{{ id.path }}/canvas",
+        "type": "Canvas",
+        "height": 31722,
+        "width": 70399,
+        "items": [
+          {
+            "id": "{{ id.path }}/page/p1/1",
+            "type": "AnnotationPage",
+            "items": [
+              {
+                "id": "{{ id.path }}/annotation/p0001-image",
+              "type": "Annotation",
+              "motivation": "painting",
+              "body": {
+                "id": "https://iiif.io/api/image/3.0/example/reference/36ca0a3370db128ec984b33d71a1543d-100320001004/full/max/0/default.jpg",
+                "type": "Image",
+                "format": "image/jpeg",
+                "height": 31722,
+                "width": 70399,
+                "service": [
+                  {
+                    "id": "https://iiif.io/api/image/3.0/example/reference/36ca0a3370db128ec984b33d71a1543d-100320001004",
+                    "profile": "level1",
+                    "type": "ImageService3"
+                  }
+                ]
+              },
+                "target": "{{ id.path }}/canvas"
+              },
+              {
+                "id": "{{ id.path }}/annotation/p0001-text",
+                "type": "Annotation",
+                "motivation": "painting",
+                "body": {
+				  "type": "TextualBody",
+				  "format": "text/html",
+				  "value": "<p style='font-size:1000px; background-color: rgba(16, 16, 16, 0.5); padding:300px'>The koto is to the right, carried in a cloth wrapping.</p>",
+				  "language": "en"
+                },
+                "target": "{{ id.path }}/canvas#xywh=5500,12200,8000,5000"
+              }
+            ]
+          }
+        ]
+      }    
+    ]
+  }