From 3e5ee620659f7b57f924d66ee4df7d696c575e4e Mon Sep 17 00:00:00 2001 From: tomcrane Date: Wed, 29 Oct 2025 12:42:55 +0000 Subject: [PATCH 1/2] More activating anno earlier, leave storytelling for later --- source/presentation/4.0/index.md | 765 +++++++++++++++---------------- 1 file changed, 381 insertions(+), 384 deletions(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index cd86f3bd7..b04d8bf26 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -1814,334 +1814,38 @@ It is important to be able to position the textual body of an annotation within ## Linking Annotations +An Annotation with the motivation `linking` is used to create links between resources, both within the Manifest or to external content on the web, including other IIIF resources. Examples include linking to the continuation of an article in a digitized newspaper in a different Canvas, or to an external web page that describes the diagram in the Canvas. A client typically renders the links as clickable "Hotspots" - but can offer whatever accessible affordance as appropriate. The user experience of whether the linked resource is opened in a new tab, new window or by replacing the current view is up to the implementation. -Simple hotspot linking example - ----- - -## Activating Annotations - -Lightweight intro here - -Timeline example - reach point in timeline, do something -enables and disables? - -Can we use light switch example here - in 2D? - -Moving books? - tab moves something revealing something else -click to fold out and fold back - - - -# Integration - -seeAlso, service(s), extensions -mention search, image api, auth - -profile for seeAlso - -partOf - - - - - - -# Content State - -(this + model doc should relieve Content State spec of modelling concerns and leave it entirely about protocol) - -A Content State is simply any valid IIIF Presentation Resource, or part of a Presentation resource. The following are all Content States that describe a "fragment" of IIIF: - -A "bare" Manifest URI: - -``` -https://example.org/manifests/1 -``` - -A reference to a Manifest: - -```json -{ - "id": "https://example.org/manifests/1", - "type": "Manifest" -} -``` - -A region of a Canvas within a Manifest: - -```json -{ - "id": "https://example.org/canvases/aabb#xywh=4500,1266,600,600", - "type": "Canvas", - "partOf": { - "id": "https://example.org/manifests/1", - "type": "Manifest" - } -} -``` - -Two versions of a painting from different publishers: - -```json -[ - { - "id": "https://gallery-1.org/iiif/sunflowers/canvas1", - "type": "Canvas", - "partOf": [ - { - "id": "https://gallery-1.org/iiif/sunflowers", - "type": "Manifest" - } - ] - }, - { - "id": "https://gallery-2.org/collection/sunflowers/c1", - "type": "Canvas", - "partOf": [ - { - "id": "https://gallery-2.org/collection/sunflowers", - "type": "Manifest" - } - ] - } -] -``` - -A Scene with a Camera at a particular point: - - -```json -{ - "id": "https://example.org/iiif/scene1/page/p1/1", - "type": "Scene", - "items": [ - { - "id": "https://example.org/iiif/3d/anno8", - "type": "Annotation", - "motivation": ["painting"], - "body": { - "type": "SpecificResource", - "source": [ - { - "id": "https://example.org/iiif/3d/cameras/1", - "type": "PerspectiveCamera", - "label": { - "en": [ - "Perspective Camera Pointed At Front of Cranium and Mandible" - ] - }, - "fieldOfView": 50.0, - "near": 0.1, - "far": 2000.0 - } - ] - }, - "target": { - "type": "SpecificResource", - "source": [ - { - "id": "https://example.org/iiif/scene1", - "type": "Scene" - } - ], - "selector": [ - { - "type": "PointSelector", - "x": 0.0, "y": 0.15, "z": 0.75 - } - ] - } - } - ] -} -``` - -The term _Content State_ is used for any arbitrary fragments of IIIF such as the above when they are used in the particular ways defined by this specification. A Content State is **usually** carried by the `target` of an annotation with the motivation `contentState`, or `body` of an annotation with the motivation `activating`, but in some scenarios may be transferred between client applications without an enclosing annotation, as a "bare" URI (see Content State 2.0 specification). - -Annotations with the motivation `contentState` are referred to as _content state_ annotations. - -Content States are used for the following applications: - -## Load a particular view of a resource or group of resources - -In this usage, an annotation with the motivation `contentState` is passed to a client to initialize it with a particular view of a resource. Almost all IIIF Clients initialize from the very simplest form of Content State - a Manifest URI. A more complex Content State might target a particular region of a particular canvas within a Manifest, as in the second example above. A client initialized from such a Content State would load the Manifest, show the particular Canvas, and perhaps zoom in on the target region. - -The mechanisms for passing Content State into a client, and exporting a Content State from a client, are given in the Content State Protocol API 2.0 specification, which describes the scenarios in which a URI, or Content State not carried by an annotation, should be interpreted by a Client as a Content State. - - -## Load a particular view of some resource and modify it - -⚠ what are we doing with this? Do we still allow it? It's a good use case... - -In the previous usage, the fragment of IIIF carried by the annotation with the motivation `contentState` provides enough information for a Client to load a resource and show it. This fragment can also carry additional IIIF Presentation API resources not shown in the referred-to resource. For example, in the following example the Content State carries additional annotations not present in the original published Manifest. A client initializing from this Content State would show these additional annotations to the user: - -What to do about activating annos in the introduced content? - -```json -{ - "id": "https://example.org/import/3", - "type": "Annotation", - "motivation": "contentState", - "target": { - "id": "https://example.org/canvases/aabb#xywh=4500,1266,600,600", - "type": "Canvas", - "partOf": { - "id": "https://example.org/manifests/nook12", - "type": "Manifest" - }, - "annotations": [ - { - "id": "https://my-annotation-store.org/user4532/notes-on-book12/p1", - "type": "AnnotationPage" - } - ] - } -} -``` - - -# Interactivity and Storytelling - -Sometimes it is necessary to modify the contents of a Container in the contexts of different annotations on that Container. This technique allows IIIF to be used for _storytelling_ and other narrative applications beyond simply conveying a static Digital Object into a viewer and leaving subsequent interactions entirely in the control of the user. - -A narrative might comprise a set (an AnnotationPage) of `commenting` annotations that target different parts of the Container, for example a guided tour of a painting or a map. For a Canvas or Timeline it is usually sufficient to leave the interactivity to the client; the fact that comments target different extents implies the client must offer some affordance for those comments (typically the user can click each one), and in response the client will move the current play point of the Timeline to the commenting annotation target, or pan and zoom the viewport to show the relevant part of an image. For 3D this may not be enough; a particular comment may only make sense from a certain viewpoint (i.e., Camera), or different steps of the story require different Lights to be active. - - -## 3D Comments with Cameras - -Consider a Scene with two models, two `commenting` annotations, and a camera. We really only want the camera to be used when the user is looking at the Mandibular tooth, by default and at other times we don't need a specific camera, we can let them explore freely. +The resource the user should be taken to is the `body` of the annotation, and the region of the Container that the user clicks or otherwise activates to follow the link is the `target`: ```jsonc { - "id": "https://example.org/iiif/3d/whale_comment_scope_content_state.json", - "type": "Manifest", - "label": { "en": ["Whale Cranium and Mandible with Dynamic Commenting Annotations and Custom Per-Anno Views"] }, - "items": [ + "id": "https://example.com/annotation/p0002-link", + "type": "Annotation", + "motivation": "linking", + "body": [ { - "id": "https://example.org/iiif/scene1/page/p1/1", - "type": "Scene", - "label": { "en": ["A Scene Containing a Whale Cranium and Mandible"] }, - "items": [ - { - "id": "https://example.org/iiif/scene1/page/p1/1", - "type": "AnnotationPage", - "items": [ - { - "id": "https://example.org/iiif/3d/anno1", - "type": "Annotation", - "motivation": ["painting"], - "body": { - "id": "https://raw.githubusercontent.com/IIIF/3d/main/assets/whale/whale_mandible.glb", - "type": "Model" - }, - "target": { - // SpecificResource with PointSelector - } - }, - { - "id": "https://example.org/iiif/3d/anno-that-paints-desired-camera", - "type": "Annotation", - "motivation": ["painting"], - "behavior": ["hidden"], - "body": { - "type": "SpecificResource", - "source": [ - { - "id": "https://example.org/iiif/3d/cameras/1", - "type": "PerspectiveCamera", - "label": {"en": ["Perspective Camera Pointed At Front of Cranium and Mandible"]}, - "fieldOfView": 50.0, - "near": 0.10, - "far": 2000.0 - } - ] - }, - "target": { - "type": "SpecificResource", - "source": [ - { - "id": "https://example.org/iiif/scene1", - "type": "Scene" - } - ], - "selector": [ - { - "type": "PointSelector", - "x": 0.0, "y": 0.15, "z": 0.75 - } - ] - } - }, - { - "id": "https://example.org/iiif/3d/anno2", - "type": "Annotation", - "motivation": ["painting"], - "body": { - "id": "https://raw.githubusercontent.com/IIIF/3d/main/assets/whale/whale_cranium.glb", - "type": "Model" - }, - "target": { - // SpecificResource with PointSelector - } - } - ] - } - ] + "id": "https://example.com/website1", + "type": "Text" } ], - "annotations": [ - { - "id": "https://example.org/iiif/scene1/page/p1/annotations/1", - "type": "AnnotationPage", - "items": [ - { - "id": "https://example.org/iiif/3d/commenting-anno-for-mandibular-tooth", - "type": "Annotation", - "motivation": ["commenting"], - "bodyValue": "Mandibular tooth", - "target": { - // SpecificResource with PointSelector - } - }, - { - "id": "https://example.org/iiif/3d/commenting-anno-for-right-pterygoid-hamulus", - "type": "Annotation", - "motivation": ["commenting"], - "bodyValue": "Right pterygoid hamulus", - "target": { - // SpecificResource with PointSelector - } - } - ] - } - ] + "target": "https://example.com/canvas/p1#xywh=265,661,1260,1239" } ``` -In that form, the user is left to interpret the commenting annotations and explore the Scene. The client will render a UI that presents the two commenting annotation in some form and allow the user to navigate between them. The commenting annotations are ordered; while the user might explore them freely in the Scene they might also go "forward" from the first to the second commenting annotation and "back" to the first from the second. - -In many complex 3D Scenes, it may not be clear what or how to look at a particular point of interest even when the commenting annotation targets a particular point. The view may be occluded by parts of the model, or other models in the Scene. In this case we only want that camera to be used for looking at the Mandibular tooth. For now, it has been given the behavior `hidden`. ## Activating Annotations -Annotations with the motivation `activating` are referred to as _activating_ annotations, and are used to link a resource that triggers an action with the resource(s) to change, enable or disable. In the above case the `target` of the activating annotation could be one of the commenting annotations, for which a user might click a corresponding UI element. In other scenarios the `target` could be the painting annotation of a 3D model, or an annotation that targets part of a model, or a region of a Canvas, or a point or segment of a Timeline, or any other annotation that a user could interact with (in whatever manner) to trigger an event. The `body` of the annotation is the resource that is then activated - for example, a Camera which then becomes the active viewport. - -`target` variations +Sometimes it is necessary to modify the contents of a Container in the contexts of different annotations on that Container. This technique allows IIIF to be used for _storytelling_ (ref) and other narrative applications beyond simply conveying a static Digital Object into a viewer and leaving subsequent interactions entirely in the control of the user. -- user "walks into a room" -- AV scrub bar reaches time t1 -- user interacts with a model -- user touches a face in a painting +Annotations with the motivation `activating` are referred to as _activating_ annotations, and are used to link a resource that triggers an action with the resource(s) to change, enable or disable. The `target` of the activating annotation could be a commenting annotation, for which a user might click a corresponding UI element. In other scenarios the `target` could be the painting annotation of a 3D model, or an annotation that targets part of a model, or a region of a Canvas, or a point or segment of a Timeline, or any other annotation that a user could interact with (in whatever manner) to trigger an event. Even a region of space in a Scene or an extent of time in a Container with `duration` could be the `target`, so that when the user "enters" that region or extent, something happens. The `body` of the annotation is the resource that is then activated: -We can add an additional `activating` annotation to the existing annotations, to connect them to the resources activated. +- a Camera: if "hidden" the behavior is removed, and this Camera becomes the viewport. +- AnimationSelector: A named animation within a model is played (fwd ref) +- (anything else yet?) Activating annotations are provided in a Container's `annotations` property. They can be mixed in with the commenting (or other interactive annotations) they target, or they can be in a separate AnnotationPage. The client should evaluate all the activating annotations it can find. -> recommend they are inline in the manifest? - -> use cases for loading in new pages of annos later - activate the French translations - - ```jsonc { "id": "https://example.org/iiif/3d/anno9", @@ -2155,48 +1859,22 @@ Activating annotations are provided in a Container's `annotations` property. The ], "body": [ { - "id": "https://example.org/iiif/3d/anno-that-paints-desired-camera", + "id": "https://example.org/iiif/3d/anno-that-paints-desired-camera-to-view-tooth", "type": "Annotation" } ] } ``` -The pattern is similar to that for linking (ref) - -In a storytelling or exhibition scenario, the non-painting `annotations` might be carrying informative text, or even rich HTML bodies. They can be considered to be _steps_ in the story. The use of activating annotations allows a precise storytelling experience to be specified, including: - - - providing a specific viewpoint for each step of the narrative (or even a choice of viewpoints) - - modifying the lighting of the Scene for each step, for example shining a spotlight on a point of interest - - hiding models in the Scene at a particular step - - showing additional models at a particular step - -As in the above example, all the other annotations referred to by the activating annotations `target` and `body` properties are already present in the Scene from the beginning. Initially, many of them may have the behavior `hidden`, invisible until activated. - - -The `body` is anything that is can be activated: - -- Camera: if "hidden" the behavior is removed, and (crucially) this Camera becomes the viewport. -- AnimationSelector: A named animation within a model is played. -- (anything else yet?) - -## Showing and hiding resources +### Showing and hiding resources An activating annotation has two additional optional properties: * `enables`: For each annotation in the value, remove the 'hidden' behavior if it has it. * `disables`: For each annotation in the value, add the 'hidden' behavior if it does not have it. -Hidden resources cannot be active or activated. If the values are the `id` properties of painting resources that paint models, they are hidden or made visible. If Lights, they are turned on. - -### Example: a light switch - -* Initially, a model of a light switch is painted into the Scene. A PointLight is also painted, but with the `behavior` "hidden", which means it is inactive (i.e., off). A commenting annotation with the text "Click the switch to turn the light on or off" targets the light switch. An activating annotation targets the commenting annotation, so that user interaction with the commenting annotation will trigger the activating annotation. This activating annotation has no `body`, but it does have `enables` with values that are the `id` properties of the painting annotation for the light switch model, and the activating annotation that turns the light off. It also has a `disables` with the value of its own `id` - i.e., it disables _itself_. A further activating annotation has the opposite effect. Initially this has the `behavior` "hidden" - which means it is inactive. It also targets the commenting annotation, but has no effect while hidden. -* When the user interacts with the light switch model, the client processes any activating annotations that target it and are not hidden. In this case, the first activating annotation is triggered because while both target the switch, only the first is not hidden. This activation `enables` the light (i.e., removing its "hidden" `behavior` and therefore turning it on) and the other activating annotation, and `disables` itself. -* If the user clicks the light again, the client again processes any activating annotations that target it and are not hidden. This time the second annotation is the active one - and it `disables` the light (turning it off) and itself, and enables the first activating annotation again. -* Subsequent clicks simply alternate between these two states, indefinitely. - +Hidden resources cannot be active or activated. If the values are the `id` properties of painting resources that paint models, they are hidden or made visible. If Lights, they are turned on. The following example demonstrates a light switch that can be toggled on and off. ```jsonc { @@ -2305,6 +1983,12 @@ Hidden resources cannot be active or activated. If the values are the `id` prope } ``` +* Initially, a model of a light switch is painted into the Scene. A PointLight is also painted, but with the `behavior` "hidden", which means it is inactive (i.e., off). A commenting annotation with the text "Click the switch to turn the light on or off" targets the light switch. An activating annotation targets the commenting annotation, so that user interaction with the commenting annotation will trigger the activating annotation. This activating annotation has no `body`, but it does have `enables` with values that are the `id` properties of the painting annotation for the light switch model, and the activating annotation that turns the light off. It also has a `disables` with the value of its own `id` - i.e., it disables _itself_. A further activating annotation has the opposite effect. Initially this has the `behavior` "hidden" - which means it is inactive. It also targets the commenting annotation, but has no effect while hidden. +* When the user interacts with the light switch model, the client processes any activating annotations that target it and are not hidden. In this case, the first activating annotation is triggered because while both target the switch, only the first is not hidden. This activation `enables` the light (i.e., removing its "hidden" `behavior` and therefore turning it on) and the other activating annotation, and `disables` itself. +* If the user clicks the light again, the client again processes any activating annotations that target it and are not hidden. This time the second annotation is the active one - and it `disables` the light (turning it off) and itself, and enables the first activating annotation again. +* Subsequent clicks simply alternate between these two states, indefinitely. + + ### Triggering a named animation in a model Sometimes a model file has inbuilt animations. While a description of these is outside the scope of IIIF, because it is 3D-implementation-specific, as long as there is a way to refer to a model's animation(s) by name, we can connect the animation to IIIF resources. @@ -2342,52 +2026,179 @@ The format of the `value` string is implementation-specific, and will depend on } } ], - "annotations": [ + "annotations": [ + { + "id": "https://example.org/iiif/scene1/page/activators", + "type": "AnnotationPage", + "items": [ + { + "id": "https://example.org/iiif/3d/box-opening-commenting-anno", + "type": "Annotation", + "motivation": ["commenting"], + "body": [ + { + "type": "TextualBody", + "value": "Click the box to open the lid" + } + ], + "target": [ + { + "id": "https://example.org/iiif/3d/painting-anno-for-music-box", + "type": "Annotation" + } + ] + } + { + "id": "https://example.org/iiif/3d/box-opening-activating-anno", + "type": "Annotation", + "motivation": ["activating"], + "target": [ + { + "id": "https://example.org/iiif/3d/box-opening-commenting-anno", + "type": "Annotation" + } + ], + "body": [ + { + "type": "SpecificResource", + "source": "https://example.org/iiif/3d/painting-anno-for-music-box", + "selector": [ + { + "type": "AnimationSelector", + "value": "open-the-lid" + } + ] + } + ] + } + ] + } + ] + } + ] + } + ] +} +``` +### 3D Comments with Cameras + +In many complex 3D Scenes, it may not be clear what or how to look at a particular point of interest even when the commenting annotation targets a particular point. The view may be occluded by parts of the model, or other models in the Scene. In the following example, the user can explore the Scene freely, but when they select a particular comment, a specific Camera that was previously hidden (unavailable to the user) is activated, moving the user (i.e., setting the viewport) to a chosen position suitable for looking at the point of interest: + +```jsonc +{ + "id": "https://example.org/iiif/3d/whale_comment_scope_content_state.json", + "type": "Manifest", + "label": { "en": ["Whale Cranium and Mandible with Dynamic Commenting Annotations and Custom Per-Anno Views"] }, + "items": [ + { + "id": "https://example.org/iiif/scene1/page/p1/1", + "type": "Scene", + "label": { "en": ["A Scene Containing a Whale Cranium and Mandible"] }, + "items": [ + { + "id": "https://example.org/iiif/scene1/page/p1/1", + "type": "AnnotationPage", + "items": [ + { + "id": "https://example.org/iiif/3d/anno1", + "type": "Annotation", + "motivation": ["painting"], + "body": { + "id": "https://raw.githubusercontent.com/IIIF/3d/main/assets/whale/whale_mandible.glb", + "type": "Model" + }, + "target": { + // SpecificResource with PointSelector + } + }, + { + "id": "https://example.org/iiif/3d/anno-that-paints-desired-camera-to-view-tooth", + "type": "Annotation", + "motivation": ["painting"], + "behavior": ["hidden"], + "body": { + "type": "SpecificResource", + "source": [ + { + "id": "https://example.org/iiif/3d/cameras/1", + "type": "PerspectiveCamera", + "label": {"en": ["Perspective Camera Pointed At Front of Cranium and Mandible"]}, + "fieldOfView": 50.0, + "near": 0.10, + "far": 2000.0 + } + ] + }, + "target": { + "type": "SpecificResource", + "source": [ + { + "id": "https://example.org/iiif/scene1", + "type": "Scene" + } + ], + "selector": [ + { + "type": "PointSelector", + "x": 0.0, "y": 0.15, "z": 0.75 + } + ] + } + }, + { + "id": "https://example.org/iiif/3d/anno2", + "type": "Annotation", + "motivation": ["painting"], + "body": { + "id": "https://raw.githubusercontent.com/IIIF/3d/main/assets/whale/whale_cranium.glb", + "type": "Model" + }, + "target": { + // SpecificResource with PointSelector + } + } + ] + } + ] + } + ], + "annotations": [ + { + "id": "https://example.org/iiif/scene1/page/p1/annotations/1", + "type": "AnnotationPage", + "items": [ + { + "id": "https://example.org/iiif/3d/commenting-anno-for-mandibular-tooth", + "type": "Annotation", + "motivation": ["commenting"], + "bodyValue": "Mandibular tooth", + "target": { + // SpecificResource with PointSelector + } + }, + { + "id": "https://example.org/iiif/3d/commenting-anno-for-right-pterygoid-hamulus", + "type": "Annotation", + "motivation": ["commenting"], + "bodyValue": "Right pterygoid hamulus", + "target": { + // SpecificResource with PointSelector + } + }, + { + "id": "https://example.org/iiif/3d/anno9", + "type": "Annotation", + "motivation": ["activating"], + "target": [ + { + "id": "https://example.org/iiif/3d/commenting-anno-for-mandibular-tooth", + "type": "Annotation" + } + ], + "body": [ { - "id": "https://example.org/iiif/scene1/page/activators", - "type": "AnnotationPage", - "items": [ - { - "id": "https://example.org/iiif/3d/box-opening-commenting-anno", - "type": "Annotation", - "motivation": ["commenting"], - "body": [ - { - "type": "TextualBody", - "value": "Click the box to open the lid" - } - ], - "target": [ - { - "id": "https://example.org/iiif/3d/painting-anno-for-music-box", - "type": "Annotation" - } - ] - } - { - "id": "https://example.org/iiif/3d/box-opening-activating-anno", - "type": "Annotation", - "motivation": ["activating"], - "target": [ - { - "id": "https://example.org/iiif/3d/box-opening-commenting-anno", - "type": "Annotation" - } - ], - "body": [ - { - "type": "SpecificResource", - "source": "https://example.org/iiif/3d/painting-anno-for-music-box", - "selector": [ - { - "type": "AnimationSelector", - "value": "open-the-lid" - } - ] - } - ] - } - ] + "id": "https://example.org/iiif/3d/anno-that-paints-desired-camera-to-view-tooth", + "type": "Annotation" } ] } @@ -2397,6 +2208,8 @@ The format of the `value` string is implementation-specific, and will depend on } ``` +The client will render a UI that presents the two commenting annotations in some form and allows the user to navigate between them. An active Camera is not provided (while there is a Camera in the Scene it has `behavior` "hidden", i.e., it is inactive: not usable). The commenting annotations are ordered; while the user might explore them freely in the Scene they might also go "forward" from the first to the second commenting annotation and "back" to the first from the second. In either case the above example instructs the client to activate the Camera when the user interacts with the comment. The user is free to move away but any interaction with that comment will bring them back to the specific viewpoint. (forward ref to chains of activation example) + ### Modifying resource properties @@ -2509,6 +2322,187 @@ In the following simple example, the background color of the Scene is changed: } ``` +# Integration + +seeAlso, service(s), extensions +mention search, image api, auth + +profile for seeAlso + +partOf - + + + + + +# Content State + +(this + model doc should relieve Content State spec of modelling concerns and leave it entirely about protocol) + +A Content State is simply any valid IIIF Presentation Resource, or part of a Presentation resource. The following are all Content States that describe a "fragment" of IIIF: + +A "bare" Manifest URI: + +``` +https://example.org/manifests/1 +``` + +A reference to a Manifest: + +```json +{ + "id": "https://example.org/manifests/1", + "type": "Manifest" +} +``` + +A region of a Canvas within a Manifest: + +```json +{ + "id": "https://example.org/canvases/aabb#xywh=4500,1266,600,600", + "type": "Canvas", + "partOf": { + "id": "https://example.org/manifests/1", + "type": "Manifest" + } +} +``` + +Two versions of a painting from different publishers: + +```json +[ + { + "id": "https://gallery-1.org/iiif/sunflowers/canvas1", + "type": "Canvas", + "partOf": [ + { + "id": "https://gallery-1.org/iiif/sunflowers", + "type": "Manifest" + } + ] + }, + { + "id": "https://gallery-2.org/collection/sunflowers/c1", + "type": "Canvas", + "partOf": [ + { + "id": "https://gallery-2.org/collection/sunflowers", + "type": "Manifest" + } + ] + } +] +``` + +A Scene with a Camera at a particular point: + + +```json +{ + "id": "https://example.org/iiif/scene1/page/p1/1", + "type": "Scene", + "items": [ + { + "id": "https://example.org/iiif/3d/anno8", + "type": "Annotation", + "motivation": ["painting"], + "body": { + "type": "SpecificResource", + "source": [ + { + "id": "https://example.org/iiif/3d/cameras/1", + "type": "PerspectiveCamera", + "label": { + "en": [ + "Perspective Camera Pointed At Front of Cranium and Mandible" + ] + }, + "fieldOfView": 50.0, + "near": 0.1, + "far": 2000.0 + } + ] + }, + "target": { + "type": "SpecificResource", + "source": [ + { + "id": "https://example.org/iiif/scene1", + "type": "Scene" + } + ], + "selector": [ + { + "type": "PointSelector", + "x": 0.0, "y": 0.15, "z": 0.75 + } + ] + } + } + ] +} +``` + +The term _Content State_ is used for any arbitrary fragments of IIIF such as the above when they are used in the particular ways defined by this specification. A Content State is **usually** carried by the `target` of an annotation with the motivation `contentState`, or `body` of an annotation with the motivation `activating`, but in some scenarios may be transferred between client applications without an enclosing annotation, as a "bare" URI (see Content State 2.0 specification). + +Annotations with the motivation `contentState` are referred to as _content state_ annotations. + +Content States are used for the following applications: + +## Load a particular view of a resource or group of resources + +In this usage, an annotation with the motivation `contentState` is passed to a client to initialize it with a particular view of a resource. Almost all IIIF Clients initialize from the very simplest form of Content State - a Manifest URI. A more complex Content State might target a particular region of a particular canvas within a Manifest, as in the second example above. A client initialized from such a Content State would load the Manifest, show the particular Canvas, and perhaps zoom in on the target region. + +The mechanisms for passing Content State into a client, and exporting a Content State from a client, are given in the Content State Protocol API 2.0 specification, which describes the scenarios in which a URI, or Content State not carried by an annotation, should be interpreted by a Client as a Content State. + + +## Load a particular view of some resource and modify it + +⚠ what are we doing with this? Do we still allow it? It's a good use case... + +In the previous usage, the fragment of IIIF carried by the annotation with the motivation `contentState` provides enough information for a Client to load a resource and show it. This fragment can also carry additional IIIF Presentation API resources not shown in the referred-to resource. For example, in the following example the Content State carries additional annotations not present in the original published Manifest. A client initializing from this Content State would show these additional annotations to the user: + +What to do about activating annos in the introduced content? + +```json +{ + "id": "https://example.org/import/3", + "type": "Annotation", + "motivation": "contentState", + "target": { + "id": "https://example.org/canvases/aabb#xywh=4500,1266,600,600", + "type": "Canvas", + "partOf": { + "id": "https://example.org/manifests/nook12", + "type": "Manifest" + }, + "annotations": [ + { + "id": "https://my-annotation-store.org/user4532/notes-on-book12/p1", + "type": "AnnotationPage" + } + ] + } +} +``` + + +# Interactivity, Guided Viewing and Storytelling + + +A narrative might comprise an AnnotationPage of `commenting` annotations that target different parts of the Container, for example a guided tour of a painting or a map. For a Canvas or Timeline it is usually sufficient to leave the interactivity to the client; the fact that comments target different extents implies the client must offer some affordance for those comments (typically the user can click each one), and in response the client will move the current play point of the Timeline to the commenting annotation target, or pan and zoom the viewport to show the relevant part of an image. For 3D this may not be enough; a particular comment may only make sense from a certain viewpoint (i.e., Camera), or different steps of the story require different Lights to be active. + +In a storytelling or exhibition scenario, the non-painting `annotations` might be carrying informative text, or even rich HTML bodies. They can be considered to be _steps_ in the story. The use of activating annotations (back ref) allows a precise storytelling experience to be specified, including: + + - providing a specific viewpoint for each step of the narrative (or even a choice of viewpoints) + - modifying the lighting of the Scene for each step, for example shining a spotlight on a point of interest + - hiding models in the Scene at a particular step + - showing additional models at a particular step + +All the annotations referred to by the activating annotations' `target` and `body` properties are already present in the Scene from the beginning. Initially, many of them may have the behavior `hidden`, invisible until activated. + ## The `sequence` behavior @@ -2525,6 +2519,9 @@ Chaining together activating annotations can then allow the implementation of, a * Interactive components such as light switches (enable/disable a light), jukeboxes (enable/disable Audio Emitter) +## Storytelling example + +Something really cool that brings a lot of things together! # Conveying Physical Dimensions From 00f7630cd0955d94edd1f55c16b8a674e17ac3ed Mon Sep 17 00:00:00 2001 From: tomcrane Date: Wed, 29 Oct 2025 12:43:50 +0000 Subject: [PATCH 2/2] More activating anno earlier, leave storytelling for later --- source/presentation/4.0/index.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index b04d8bf26..66073fcca 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -2521,7 +2521,8 @@ Chaining together activating annotations can then allow the implementation of, a ## Storytelling example -Something really cool that brings a lot of things together! +* Something really cool that brings a lot of things together! +* Use JSONPatch to move a model too. # Conveying Physical Dimensions