model text for activating

Author: tomcrane

source/presentation/4.0/index.md

@@ -2004,7 +2004,9 @@ The resource the user should be taken to is the `body` of the annotation, and th
 
 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 exhibitions, storytelling (fwd ref) and other interactive applications beyond simply conveying a set of static resources in a Container.
 
-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 volume 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. 
+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 volume of space in a Scene or an extent of time in a Container with `duration` could be the `target`. When the user triggers that volume or time extent - which might be the user entering that volume or the playhead reaching the extent - something happens. 
+
+> TODO - `target` is a cuboid volume (not a painted model) - one client might expect you to click on it (and show its edges somehow for affordance), another client might expect you to walk into it, and doesn't render the shape at all, it is just an invisible volume. Do we need an extension to distinguish the two interaction behaviors?
 
 The `body` of the annotation is then activated. This has different processing requirements depending on what the body is:
 
@@ -2041,12 +2043,12 @@ Activating annotations are provided in a Container's `annotations` property. The
 
 An activating annotation has two additional optional properties:
 
-* `enables`: For each Annotation or AnnotationPage in the value, remove the 'hidden' behavior if it has it.
+* `enables`: For each Annotation or AnnotationPage in the value, remove the 'hidden' behavior if it has it. 
 * `disables`: For each Annotation or AnnotationPage in the value, add the 'hidden' behavior if it does not have it.
 
 If the values are the `id` properties of painting annotations that paint models, `enables` makes them visible and `disables` hides them. If they paint Lights, `enables` turns them on and `disables` turns them off.
 
-Referencing a Painting Annotation as the `body` of an activating annotation implicitly enables it, as if it had been listed in `enables`. The inverse is not always true - for example, referencing a Camera in `enables` removes the "hidden" `behavior` and therefore allows it to be included in the client's evaluation of what the default camera is, but does not perform the additional action of changing the viewport to that Camera. For Lights and Models in a Scene, the two are equivalent because no _additional_ processing behavior is provided by this specification.
+For Lights and Models in a Scene, `enables` is equivalent to the Light or Model being activated (i.e., being the `body` of the activating annotation), because no _additional_ processing behavior is provided by this specification. For Cameras, `enables` removes the "hidden" `behavior` (allows the Camera to be used), but does not by itself make the Camera the active viewport.
 
 For many use cases, the activating annotations don't need bodies. The following example demonstrates a light switch that can be toggled on and off:
 
@@ -2238,10 +2240,11 @@ The format of the `value` string is implementation-specific, and will depend on
                       "source": "https://example.org/iiif/3d/painting-anno-for-music-box",
                       "selector": [
                         {
-                          "type": "AnimationSelector",
+                          "type": "ResourceStateSelector",
                           "value": "open-the-lid"
                         }
-                      ]
+                      ],
+                      "apply": ["playing"]
                     }
                   ]
                 }
@@ -2254,6 +2257,8 @@ The format of the `value` string is implementation-specific, and will depend on
   ]
 }
 ```
+
+
 ### 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:

source/presentation/4.0/model.md

@@ -1246,7 +1246,7 @@ Disjoint with `thumbnail-nav` and `no-nav`.|
 | `thumbnail-nav`{: style="white-space:nowrap;"} | Valid only on Ranges. Ranges that have this behavior _MAY_ be used by the client to present an alternative navigation or overview based on thumbnails, such as regular keyframes along a timeline for a video, or sections of a long scroll. Clients _SHOULD NOT_ use them to generate a conventional table of contents. Child Ranges of a Range with this behavior _MUST_ have a suitable `thumbnail` property. Disjoint with `sequence` and `no-nav`.|
 | `no-nav` | Valid only on Ranges. Ranges that have this behavior _MUST NOT_ be displayed to the user in a navigation hierarchy. This allows for Ranges to be present that capture unnamed regions with no interesting content, such as the set of blank pages at the beginning of a book, or dead air between parts of a performance, that are still part of the Manifest but do not need to be navigated to directly. Disjoint with `sequence` and `thumbnail-nav`.|
 | | **Miscellaneous Behaviors** |
-| `hidden`{: #hidden-value} | Valid on Annotation Collections, Annotation Pages, Annotations, Specific Resources, Lights, Cameras and Choices. If this behavior is provided, then the client _SHOULD NOT_ render the resource by default, but allow the user to turn it on and off. This behavior does not inherit, as it is not valid on Collections, Manifests, Ranges or Canvases. |
+| `hidden`{: #hidden-value} | Valid on Annotation Collections, Annotation Pages, Annotations, Specific Resources, Lights, Cameras and Choices. If this behavior is provided, then the client _SHOULD NOT_ render the resource by default, but allow the user to turn it on and off. This behavior does not inherit, as it is not valid on Collections, Manifests, Ranges or Canvases. TODO - this needs to talk about `hidden` on an activating annotation, which is not a visible (painted) resource. |
 {: .api-table #table-behavior}
 
 {% include api/code_header.html %}
@@ -1342,6 +1342,11 @@ The value _MUST_ be a positive floating point number.
 
 TODO
 
+does not reset the Container in any way, independent of where you are in a Container's `duration`, if you enable a video that is painted from t1-t2 then it will be playing if not paused and playhead is t1 < p < t2
+For non-duration containers it just appears and starts playing.
+Activating a video again does nothing if already activated/enabled
+
+
 
 ### exclude
 {: #exclude}
@@ -1793,20 +1798,9 @@ Additional motivations may be added to the Annotation to further clarify the int
 | ----- | ----------- |
 | `painting` | Resources associated with a Container by an Annotation that has the `motivation` value `painting`  _MUST_ be presented to the user as the representation of the Container. The content can be thought of as being _of_ the Container. The use of this motivation with target resources other than Containers is undefined. For example, an Annotation that has the `motivation` value `painting`, a body of an Image and the target of a Canvas is an instruction to present that Image as (part of) the visual representation of the Canvas. Similarly, a textual body is to be presented as (part of) the visual representation of the Container and not positioned in some other part of the user interface.|
 | `supplementing` | Resources associated with a Container by an Annotation that has the `motivation` value `supplementing`  _MAY_ be presented to the user as part of the representation of the Container, or _MAY_ be presented in a different part of the user interface. The content can be thought of as being _from_ the Container. The use of this motivation with target resources other than Containers is undefined. For example, an Annotation that has the `motivation` value `supplementing`, a body of an Image and the target of part of a Canvas is an instruction to present that Image to the user either in the Canvas's rendering area or somewhere associated with it, and could be used to present an easier to read representation of a diagram. Similarly, a textual body is to be presented either in the targeted region of the Container or otherwise associated with it, and might be OCR, a manual transcription or a translation of handwritten text, or captions for what is being said in a Timeline with audio content. |
-| `activating`   | 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. An annotation with the motivation `activating` has any valid IIIF Resource, or list of IIIF resources, or references to IIIF resources as its `target` property, and any potentially interactive resource as its `body`. It indicates that a user interaction will trigger a change in a Container, or play a named animation in a Model. If the `body` of the Annotation is of type `TextualBody` and the `target` is of type `SpecificResource` with a `selector` property of type `AnimationSelector`, then the client offers a UI such that when the user selects an interactive element labelled by the TextualBody, the named animation in the model painted by the `source` is played. |
+| `activating`   | 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. See [Dynamic Content]() for processing. |
 {: .api-table #table-motivations}
 
-#### Activating Annotations
-
-The client must render the target resource as an interactive element in the user interface, which the user can trigger (e.g., clicking, selecting, entering).
-
-The `body` of the annotation is then activated. This specification defines the following client behaviors; others may me found in the [IIIF Cookbook][ref].
-
-* If the body is a reference to a Painting Annotation:
- * if the annotation has the `behavior` "hidden", then remove "hidden" from the `behavior`.
- * if the annotation paints a Camera, make that Camera the active Camera (i.e., make this the viewport) (see [ref]).
-* If the body is a SpecificResource with a `selector` property with the type "AnimationSelector", play the animation named by the `value` property of the Selector. (see [ref]).
-
 
 ### navDate
 {: #navDate}
@@ -2958,6 +2952,61 @@ A number (floating point) giving the z coordinate of the point, relative to the
 { "z": 100 }
 ```
 
+## Dynamic Content
+{: #dynamic-content}
+
+An annotation with the motivation `activating` has any valid IIIF Resource, or list of IIIF resources, or references to IIIF resources as its `body` property, and any potentially interactable resource as its `target`. The `body` is activated by the `target`.
+
+There are two categories of activating annotation targets (interactable things):
+
+* Annotations - content of the container (a painting annotation rendered in the Scene) or content that targets the container (a commenting annotation, a map pin... which may have off-Container representations in a UI eg comments in a side panel). 
+* Extents of Containers - a volume of a Scene, region of a Canvas, or interval of time in any Container with a `duration` (the client may or may not render these "hit boxes")
+
+How the client makes these interactable is client-dependent.
+
+Need to cover:
+
+Clients supporting dynamic content need to support 
+
+ - non-painting annotations e.g., commenting annos (and other annos that usually have textual bodies that could be made clickable by a client, or map pin markers, etc)
+ - painted resources such as models
+ - volumes
+ - time extents
+ - other activating annos
+
+This specification defines the following client behaviors; others may be found in the [IIIF Cookbook][ref].
+
+### Showing and hiding content
+
+If the body is a reference to a Painting Annotation or a non-painting , the client must render the `target` resource as an interactive element in the user interface, which the user (or _Container time_) can trigger (e.g., clicking, selecting, entering). The `body` of the annotation is then activated by this interaction.
+
+ * if the annotation has the `behavior` "hidden", then remove "hidden" from the `behavior`.
+
+(example: click the comment, object appears, light goes on) 
+
+enables and disables
+
+### Activating Lights
+
+You can just use enables and disables
+
+### Activating Cameras
+
+ * if the annotation paints a Camera, make that Camera the active Camera (i.e., make this the viewport) (see [ref]).
+
+### Playing animations
+
+If the `body` is of type `SpecificResource` with a `selector` property of type `AnimationSelector`, the named animation in the model painted by the `source` is played when the `target` is activated. 
+* If the body is a SpecificResource with a `selector` property with the type "AnimationSelector", play the animation named by the `value` property of the Selector. (see [ref]).
+
+
+
+scope
+
+
+
+
+
 
 ## JSON-LD and Extensions
 {: #json-ld-and-extensions}

source/presentation/4.0/scratch.md

@@ -229,3 +229,30 @@ What to do about activating annos in the introduced content?
 }
 ```
 
+Activating by entering (or interacting with) a volume:
+
+```json
+{
+  "id": "https://example.org/iiif/3d/anno9",
+  "type": "Annotation",
+  "motivation": ["activating"],
+  "target": [
+    {
+        "id": "https://example.org/iiif/3d/anno9",
+        "type": "SpecificResource",
+        "selector": [
+            {
+                "type": "WktSelector",
+                "wktLiteral": "POLYHEDRALSURFACE Z (blah blah)"
+            }
+        ],
+        "source": "https://example.org/iiif/3d/Scene1"
+    }
+  ],
+  "body": [
+    {
+      "type": "JSONPatch that turns on the light"
+    }
+  ]
+}
+```