From 8813b6a11246b238bb0fea85ae656a3afa6e499e Mon Sep 17 00:00:00 2001 From: Trip Kirkpatrick Date: Thu, 2 Jan 2025 15:47:43 -0500 Subject: [PATCH 1/8] =?UTF-8?q?First=20draft=20of=20new=20recipe=20for=20v?= =?UTF-8?q?isible=20text=20annotation=20=F0=9F=93=9D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- recipe/0561-text-on-image/index.md | 46 +++++++++++++++++++++ recipe/0561-text-on-image/manifest.json | 54 +++++++++++++++++++++++++ 2 files changed, 100 insertions(+) create mode 100644 recipe/0561-text-on-image/index.md create mode 100644 recipe/0561-text-on-image/manifest.json diff --git a/recipe/0561-text-on-image/index.md b/recipe/0561-text-on-image/index.md new file mode 100644 index 000000000..a6cf0d178 --- /dev/null +++ b/recipe/0561-text-on-image/index.md @@ -0,0 +1,46 @@ +--- +title: Name of Recipe +id: -1 +layout: recipe +tags: [tbc] +summary: "tbc" +viewers: +topic: + - basic +--- + +## Use Case + +Describe the use case that the pattern is intended to solve. +Why is this pattern important? + +## Implementation Notes + +What do you need to know to use this pattern? +How do you implement the pattern? + +## Restrictions + +When is this pattern is usable / not usable? Is it deprecated? If it uses multiple specifications, which versions are needed, etc.? + +Delete this section if it is not needed. +If you don't know what the restrictions might be initially, just leave the following line: +**Unknown - Help Needed** + +## Example + +Describe the solution in prose and provide an example. +The example json document must be an external document, and imported with the following: + +{% include manifest_links.html viewers="UV, Mirador, Annona, Clover, Ramp, Aviary, Glycerine, Theseus" manifest="manifest.json" %} + +{% include jsonviewer.html src="manifest.json" %} + +The direct link to the fixture is a useful convenience. + +## Related Recipes + +Provide a bulleted list of related recipes and why they are relevant. + +{% 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..443604c87 --- /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": [ "Multimedia Canvas" ] }, + "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/p0006-text", + "type": "Annotation", + "motivation": "painting", + "body": { + "type": "TextualBody", + "format": "text/html", + "value": "

Close your browser

", + "language": "en" + }, + "target": "{{ id.path }}/canvas#xywh=27000,10200,25000,5000" + } + ] + } + ] + } + ] + } From 216d8c482a39f20f46b1da4c60f3b3ec967f61a6 Mon Sep 17 00:00:00 2001 From: Trip Kirkpatrick Date: Thu, 2 Jan 2025 15:48:14 -0500 Subject: [PATCH 2/8] =?UTF-8?q?Added=20new=20recipe=20for=20visible=20text?= =?UTF-8?q?=20annotation=20=E2=9E=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- _includes/links.md | 2 ++ index.md | 1 + 2 files changed, 3 insertions(+) diff --git a/_includes/links.md b/_includes/links.md index 0f7620a31..f0d9383dd 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 Annotation" + [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..2c7c260eb 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 Annotation][0561] ## Internal structure From 6d6a73b786a51b2c51bbd20c24160a7d1d570b62 Mon Sep 17 00:00:00 2001 From: Trip Kirkpatrick Date: Fri, 17 Jan 2025 08:03:03 -0500 Subject: [PATCH 3/8] =?UTF-8?q?Took=20a=20first=20pass=20at=20creating=20t?= =?UTF-8?q?he=20files=20=E2=9A=A1=EF=B8=8F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- recipe/0561-text-on-image/index.md | 34 ++++++++++++------------- recipe/0561-text-on-image/manifest.json | 6 ++--- 2 files changed, 19 insertions(+), 21 deletions(-) diff --git a/recipe/0561-text-on-image/index.md b/recipe/0561-text-on-image/index.md index a6cf0d178..ff305c926 100644 --- a/recipe/0561-text-on-image/index.md +++ b/recipe/0561-text-on-image/index.md @@ -1,38 +1,35 @@ --- -title: Name of Recipe -id: -1 +title: Visible Text Annotation +id: 561 layout: recipe -tags: [tbc] -summary: "tbc" +tags: annotation +summary: "Overlaying (painting) visible text on top of an image resource" viewers: topic: - - basic + - realWorldObject --- ## Use Case -Describe the use case that the pattern is intended to solve. -Why is this pattern important? +You have an ## Implementation Notes -What do you need to know to use this pattern? -How do you implement the pattern? +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] recipe. -## Restrictions +Fundamentally, what it is showing is the importance of the `motivation` property on an annotation, in combination itself with making that annotation directly inside a Canvas resource instead of as part of an `annotations` section. Making these two changes tells a viewer to display the text directly instead of separating it as an annotation to be handled in the viewer's manner of showing those. + +Styling text or using HTML in text painted onto a Canvas is possible, but the options are limited. -When is this pattern is usable / not usable? Is it deprecated? If it uses multiple specifications, which versions are needed, etc.? +## Restrictions -Delete this section if it is not needed. -If you don't know what the restrictions might be initially, just leave the following line: -**Unknown - Help Needed** +For security reasons, clients are expected to allow only `a`, `b`, `br`, `i`, `img`, `p`, `small`, `span`, `sub`, and `sup` tags in the textual annotation, 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 -Describe the solution in prose and provide an example. -The example json document must be an external document, and imported with the following: +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 recognizable to people unfamiliar with the scene, there is a textual annotation adjacent to it that identifies it. -{% include manifest_links.html viewers="UV, Mirador, Annona, Clover, Ramp, Aviary, Glycerine, Theseus" manifest="manifest.json" %} +{% include manifest_links.html viewers="" manifest="manifest.json" %} {% include jsonviewer.html src="manifest.json" %} @@ -40,7 +37,8 @@ The direct link to the fixture is a useful convenience. ## Related Recipes -Provide a bulleted list of related recipes and why they are relevant. +* [Embedding HTML in descriptive properties][0007] +* [Image Rotation Two Ways][0040] to see an example of using a CSS class for style manipulation {% include acronyms.md %} {% include links.md %} diff --git a/recipe/0561-text-on-image/manifest.json b/recipe/0561-text-on-image/manifest.json index 443604c87..ba1b65fe7 100644 --- a/recipe/0561-text-on-image/manifest.json +++ b/recipe/0561-text-on-image/manifest.json @@ -2,7 +2,7 @@ "@context": "http://iiif.io/api/presentation/3/context.json", "id": "{{ id.url }}", "type": "Manifest", - "label": { "en": [ "Multimedia Canvas" ] }, + "label": { "en": [ "Visible Text Annotation" ] }, "items": [ { "id": "{{ id.path }}/canvas", @@ -35,13 +35,13 @@ "target": "{{ id.path }}/canvas" }, { - "id": "{{ id.path }}/annotation/p0006-text", + "id": "{{ id.path }}/annotation/p0001-text", "type": "Annotation", "motivation": "painting", "body": { "type": "TextualBody", "format": "text/html", - "value": "

Close your browser

", + "value": "

Textual annotation

", "language": "en" }, "target": "{{ id.path }}/canvas#xywh=27000,10200,25000,5000" From 6dfefac8e4e156a9327e326e9d77bebf72a633fe Mon Sep 17 00:00:00 2001 From: Trip Kirkpatrick Date: Fri, 17 Jan 2025 08:15:22 -0500 Subject: [PATCH 4/8] =?UTF-8?q?Moved=20the=20textual=20annotation=20to=20f?= =?UTF-8?q?irst=20in=20the=20order=20=F0=9F=9A=9A?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit It may matter to some viewers/clients that read the sequential order as the top-to-bottom layer order --- recipe/0561-text-on-image/manifest.json | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/recipe/0561-text-on-image/manifest.json b/recipe/0561-text-on-image/manifest.json index ba1b65fe7..037d4d53f 100644 --- a/recipe/0561-text-on-image/manifest.json +++ b/recipe/0561-text-on-image/manifest.json @@ -14,6 +14,18 @@ "id": "{{ id.path }}/page/p1/1", "type": "AnnotationPage", "items": [ + { + "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" + }, { "id": "{{ id.path }}/annotation/p0001-image", "type": "Annotation", @@ -33,18 +45,6 @@ ] }, "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" } ] } From ba3847f8d48aa65c19d82c77f6fdbc8838ec367e Mon Sep 17 00:00:00 2001 From: Trip Kirkpatrick Date: Fri, 31 Jan 2025 10:14:31 -0500 Subject: [PATCH 5/8] =?UTF-8?q?Edited=20recipe=20text=20significantly=20?= =?UTF-8?q?=F0=9F=93=9D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- recipe/0561-text-on-image/index.md | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/recipe/0561-text-on-image/index.md b/recipe/0561-text-on-image/index.md index ff305c926..8a31eb210 100644 --- a/recipe/0561-text-on-image/index.md +++ b/recipe/0561-text-on-image/index.md @@ -11,34 +11,40 @@ topic: ## Use Case -You have an +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] recipe. +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. -Fundamentally, what it is showing is the importance of the `motivation` property on an annotation, in combination itself with making that annotation directly inside a Canvas resource instead of as part of an `annotations` section. Making these two changes tells a viewer to display the text directly instead of separating it as an annotation to be handled in the viewer's manner of showing those. +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 `annotation` section are not permitted to have the `motivation` value `painting` ([Annotations](https://iiif.io/api/presentation/3.0/#annotations)) ++ Conversely, Annotations in pages 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. +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 -For security reasons, clients are expected to allow only `a`, `b`, `br`, `i`, `img`, `p`, `small`, `span`, `sub`, and `sup` tags in the textual annotation, 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). +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 recognizable to people unfamiliar with the scene, there is a textual annotation adjacent to it that identifies it. +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 viewers="" manifest="manifest.json" %} +{% include manifest_links.html manifest="manifest.json" %} {% include jsonviewer.html src="manifest.json" %} -The direct link to the fixture is a useful convenience. ## 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 %} From f10dc8912903e6efcb516eba0a0a8801581da454 Mon Sep 17 00:00:00 2001 From: Trip Kirkpatrick Date: Fri, 31 Jan 2025 10:15:29 -0500 Subject: [PATCH 6/8] =?UTF-8?q?Reordered=20the=20Annotations=20for=20the?= =?UTF-8?q?=20desired=20outcome=20per=20spec=20=F0=9F=9A=9A?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- recipe/0561-text-on-image/manifest.json | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/recipe/0561-text-on-image/manifest.json b/recipe/0561-text-on-image/manifest.json index 037d4d53f..ba1b65fe7 100644 --- a/recipe/0561-text-on-image/manifest.json +++ b/recipe/0561-text-on-image/manifest.json @@ -14,18 +14,6 @@ "id": "{{ id.path }}/page/p1/1", "type": "AnnotationPage", "items": [ - { - "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" - }, { "id": "{{ id.path }}/annotation/p0001-image", "type": "Annotation", @@ -45,6 +33,18 @@ ] }, "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" } ] } From a57859c6f7e408d4b8e6c8e1c42dde52b12f3a90 Mon Sep 17 00:00:00 2001 From: Trip Kirkpatrick Date: Sun, 9 Feb 2025 12:07:55 -0500 Subject: [PATCH 7/8] =?UTF-8?q?Fixed=20styling=20=F0=9F=8E=A8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- recipe/0561-text-on-image/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/recipe/0561-text-on-image/index.md b/recipe/0561-text-on-image/index.md index 8a31eb210..d7fdb06dc 100644 --- a/recipe/0561-text-on-image/index.md +++ b/recipe/0561-text-on-image/index.md @@ -18,8 +18,8 @@ You would like to add text visibly over some portion of a IIIF image resource wi 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 `annotation` section are not permitted to have the `motivation` value `painting` ([Annotations](https://iiif.io/api/presentation/3.0/#annotations)) -+ Conversely, Annotations in pages referenced in Items have to have the `motivation` value `painting`. ([Canvas](https://iiif.io/api/presentation/3.0/#53-canvas)) ++ 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. From 187dd652c68a0d1649fd633fa9aad3a1a767df2b Mon Sep 17 00:00:00 2001 From: Trip Kirkpatrick Date: Fri, 14 Feb 2025 10:21:32 -0500 Subject: [PATCH 8/8] =?UTF-8?q?Changed=20recipe=20name=20to=20highlight=20?= =?UTF-8?q?text=20as=20resource=20=F0=9F=93=9D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- _includes/links.md | 2 +- index.md | 2 +- recipe/0561-text-on-image/index.md | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/_includes/links.md b/_includes/links.md index f0d9383dd..7c90ec891 100644 --- a/_includes/links.md +++ b/_includes/links.md @@ -79,7 +79,7 @@ [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 Annotation" +[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 diff --git a/index.md b/index.md index 2c7c260eb..e0dfba2a8 100644 --- a/index.md +++ b/index.md @@ -94,7 +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 Annotation][0561] +* [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 index d7fdb06dc..34862df4e 100644 --- a/recipe/0561-text-on-image/index.md +++ b/recipe/0561-text-on-image/index.md @@ -1,9 +1,9 @@ --- -title: Visible Text Annotation +title: Visible Text Resource on a Canvas id: 561 layout: recipe tags: annotation -summary: "Overlaying (painting) visible text on top of an image resource" +summary: "Overlaying (painting) text on top of an image resource" viewers: topic: - realWorldObject