Recipe #560: Resources on a Timeline

_includes/links.md

@@ -76,13 +76,13 @@
 
 [0464]: {{ site.cookbook_url | absolute_url }}/recipe/0464-reuse-manifest/ "Reuse parts of a Manifest"
 [0466]: {{ site.cookbook_url | absolute_url }}/recipe/0466-link-for-loading-manifest/ "Loading a manifest with a viewer using a link"
-
 [0485]: {{ site.cookbook_url | absolute_url }}/recipe/0485-contentstate-canvas-region/ "Open a specific region of a canvas in a viewer"
-
 [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"
 [0540]: {{ site.cookbook_url | absolute_url }}/recipe/0540-link-for-opening-multiple-canvases/ "Sharing a link for opening two or more Canvases"
 
+[0560]: {{ site.cookbook_url | absolute_url }}/recipe/0560-resources-on-a-timeline/ "Rendering Resources Sequentially on a Timeline"
+
 [cookbook-process]: {{site.cookbook_url | absolute_url }}/recipe
 
 [trc]: {{ site.root_url | absolute_url }}/community/trc/

index.md

@@ -117,6 +117,7 @@ _(leading on to segmentation examples later)_
 * [Multiple choice of images in a single view][0033] (29)
 * [Foldouts, Flaps, and Maps][0035]
 * [Composition from Multiple Images][0036] (30,31)
+* [Rendering Resources Sequentially on a Timeline][0560]
 * [Rendering Multiple Media Types on a Time-Based Canvas][0489]
 * Multiple images and multiple choices (32,33,34)
 * [Annotating part of an image to a Canvas][recipe-segment-image-part] (e.g., crop out scanner) (35,36,37,38)

recipe/0560-resources-on-a-timeline/index.md

@@ -0,0 +1,47 @@
+---
+title: Rendering Resources Sequentially on a Timeline
+id: 560
+layout: recipe
+tags: timeline
+summary: "Placing image resources on a timeline to be shown in a sequence"
+viewers:
+topic:
+ - realWorldObject
+---
+
+## Use Case
+
+You have a set of images you would like to present sequentially in time, in the manner of an automated slide show.
+
+## Implementation Notes
+
+This recipe is very similar to [Composition from Multiple Images][0036], which describes using multiple IIIF resources on a single Canvas. The substantial difference between that recipe and this one is the incorporation of [the `duration` property](https://iiif.io/api/presentation/3.0/#duration) and [`behavior` values](https://iiif.io/api/presentation/3.0/#behavior) for instructing viewers on Canvas sequencing.
+
+If a Canvas has a `duration` property, viewers have to process it, and can be helpful by providing an interactive means of displaying that Canvas for the value of the `duration`. To give a viewer instructions on showing a resource during all or part of that duration, the Canvas can use a media fragment on its `target` value, in the form `#t=`. For details on formats and semantics of this media fragment, see the [W3C Media Fragments section on Temporal Dimension](https://www.w3.org/TR/media-frags/#naming-time). Note that while the Media Fragments specification allows for values other than numbers of seconds, IIIF conventionally uses only whole and/or partial seconds. Fragment values can be individually or in the aggregate greater than the `duration` value. See [Rendering Multiple Media Types on a Time-Based Canvas][0489] for a brief explanation of the `timeMode` property and for more on the "t" parameter on a `target`.
+
+The Presentation API 3.0 is not explicit about whether a viewer should initiate play upon loading a Canvas with a `duration` property, even with a `start` value. In addition, for browser-based viewers, people may configure their browsers to disable autoplay. Consequently, manifest creators should not assume a resource with `duration` will begin without interaction.
+
+Once the timeline has started, the default action in IIIF is to display a Canvas for the `duration` value and stop, regardless of the individual or aggregate "t" parameter values on the `target`s of the Canvas's descendent `items`. To get the annotation sequence to repeat, the `behavior` value is set to `repeat`. This value is applicable only on Collections or Manifests containing Canvases with `duration`. Once the end of the `duration` (the end of the timeline) is reached, this behavior tells the viewer to start over at the beginning. Note that there is no mechanism for repeating a fixed number of times.
+
+Within a Canvas's annotations, the parameterized `target` values tell viewers to show each item for the "t" parameter value, not stopping until an appropriate interaction or until and unless it reaches a Canvas with no `behavior` or a Canvas with an explicit `no-auto-advance` behavior. (The default is `no-auto-advance`, so no `behavior` is functionally equivalent to declaring `no-auto-advance`.)
+
+## Restrictions
+
+No known restrictions, but a caution: When using timing, a high degree of precision is not likely to be achieved for all people. Resources may load slowly for many reasons, including image server issues, network traffic, or browser and client customizations. Except in a very predictable environment, timing should be considered approximate.
+
+## Example
+
+In this example (a minimal implementation of the use case), there are two paintings from Winslow Homer to be displayed one after the other in a loop. For demonstration purposes, the Canvas `duration` is quite short (4.0 seconds) while the timing in a real-world situation would probably be longer. The paintings are `items` on a single Canvas and should progress automatically once the timeline is started.
+
+{% include manifest_links.html viewers="" manifest="manifest.json" %}
+
+{% include jsonviewer.html src="manifest.json" config='data-line="10-12,19,43,63"' %}
+
+## Related Recipes
+
+* [Composition from Multiple Images][0036] for using multiple IIIF resources on a single Canvas
+* [Image and Canvas with Differing Dimensions][0004] for details about the way this recipe uses resources with different dimensions on a Canvas with unchanging dimensions.
+* [Rendering Multiple Media Types on a Time-Based Canvas][0489] is a more complex combination of still and time-based resources with various IIIF properties.
+
+{% include acronyms.md %}
+{% include links.md %}

recipe/0560-resources-on-a-timeline/manifest.json

@@ -0,0 +1,70 @@
+{
+  "@context": "http://iiif.io/api/presentation/3/context.json",
+  "id": "{{ id.url }}",
+  "type": "Manifest",
+  "label": {
+    "en": [
+      "Rendering Resources Sequentially on a Timeline"
+    ]
+  },
+  "behavior": [
+    "repeat"
+  ],
+  "items": [
+    {
+      "id": "{{ id.path }}/canvas1",
+      "type": "Canvas",
+      "height": 2572,
+      "width": 3764,
+      "duration": 4.0,
+      "items": [
+        {
+          "id": "{{ id.path }}/canvas1/page/p1/1",
+          "type": "AnnotationPage",
+          "items": [
+            {
+              "id": "{{ id.path }}/canvas1/annotation/p1a1-image",
+              "type": "Annotation",
+              "motivation": "painting",
+              "body": {
+                "id": "https://iiif.io/api/image/3.0/example/reference/329817fc8a251a01c393f517d8a17d87-Northeaster_by_Winslow_Homer_1895/full/max/0/default.jpg",
+                "type": "Image",
+                "format": "image/jpeg",
+                "height": 2572,
+                "width": 3764,
+                "service": [
+                  {
+                    "id": "https://iiif.io/api/image/3.0/example/reference/329817fc8a251a01c393f517d8a17d87-Northeaster_by_Winslow_Homer_1895/",
+                    "profile": "level1",
+                    "type": "ImageService3"
+                  }
+                ]
+              },
+              "target": "{{ id.path }}/canvas1&t=0,2"
+            },
+            {
+              "id": "{{ id.path }}/canvas1/annotation/p1a2-image",
+              "type": "Annotation",
+              "motivation": "painting",
+              "body": {
+                "id": "https://iiif.io/api/image/3.0/example/reference/329817fc8a251a01c393f517d8a17d87-Winslow_Homer_-_The_Gulf_Stream_-_Metropolitan_Museum_of_Art/full/max/0/default.jpg",
+                "type": "Image",
+                "format": "image/jpeg",
+                "height": 3540,
+                "width": 5886,
+                "service": [
+                  {
+                    "id": "https://iiif.io/api/image/3.0/example/reference/329817fc8a251a01c393f517d8a17d87-Winslow_Homer_-_The_Gulf_Stream_-_Metropolitan_Museum_of_Art/",
+                    "profile": "level1",
+                    "type": "ImageService3"
+                  }
+                ]
+              },
+              "target": "{{ id.path }}/canvas1&t=2,4"
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}