diff --git a/_includes/links.md b/_includes/links.md index 0f7620a31..7c90ec891 100644 --- a/_includes/links.md +++ b/_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/ diff --git a/index.md b/index.md index c868e6fb7..e0dfba2a8 100644 --- a/index.md +++ b/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 diff --git a/recipe/0561-text-on-image/index.md b/recipe/0561-text-on-image/index.md new file mode 100644 index 000000000..34862df4e --- /dev/null +++ b/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 %} diff --git a/recipe/0561-text-on-image/manifest.json b/recipe/0561-text-on-image/manifest.json new file mode 100644 index 000000000..ba1b65fe7 --- /dev/null +++ b/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": "

Textual annotation

", + "language": "en" + }, + "target": "{{ id.path }}/canvas#xywh=27000,10200,25000,5000" + } + ] + } + ] + } + ] + }