Recipe #0561: Visible Text Annotation

_includes/links.md

@@ -79,6 +79,8 @@
 [0434]: {{ site.cookbook_url | absolute_url }}/recipe/0434-choice-av/ "Multiple Choice of Audio Formats in a Single View (Canvas)"
 [0489]: {{ site.cookbook_url | absolute_url }}/recipe/0489-multimedia-canvas/ "Rendering Multiple Media Types on a Time-Based Canvas"
 
+[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

@@ -94,6 +94,7 @@ _(leading on to segmentation examples later)_
 * [Linking external Annotations targeting a Canvas to a Manifest][0306]
 * [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][prezi3] 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` have to 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.
+
+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 specification](https://iiif.io/api/presentation/3.0/#45-html-markup-in-property-values).
+
+## 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.
+
+{% include manifest_links.html manifest="manifest.json" %}
+
+{% include jsonviewer.html src="manifest.json" %}
+
+
+## Related Recipes
+
+* [Embedding HTML in descriptive properties][0007]
+* [Image Rotation Two Ways][0040] to see an example of using a CSS class for style manipulation
+* [Image and Canvas with Differing Dimensions][0004] has more discussion about the nature of IIIF dimensioning
+* [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:2000px'>Textual annotation</p>",
+				  "language": "en"
+                },
+                "target": "{{ id.path }}/canvas#xywh=27000,10200,25000,5000"
+              }
+            ]
+          }
+        ]
+      }    
+    ]
+  }