From 8ad34bd7ec25fd9d7a561ad300534c141ce4afe4 Mon Sep 17 00:00:00 2001 From: tomcrane Date: Thu, 24 Oct 2024 11:32:06 +0100 Subject: [PATCH 001/130] structure of Presentation 4 --- source/presentation/4.0/index.md | 156 ++++++++++++++++++++++++++ source/presentation/4.0/properties.md | 35 ++++++ source/presentation/4/context.json | 1 + 3 files changed, 192 insertions(+) create mode 100644 source/presentation/4.0/index.md create mode 100644 source/presentation/4.0/properties.md create mode 100644 source/presentation/4/context.json diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md new file mode 100644 index 000000000..fe5616888 --- /dev/null +++ b/source/presentation/4.0/index.md @@ -0,0 +1,156 @@ +# Presentation 4 + +## How this stuff works + +Manifests, Containers, Annotations oh my! +Manifest as unit of distribution + +## Content Resources? + +There is stuff that we want to show + +## Containers + +"painting" +"supplementing" + +"Nesting" (see 3d draft) + +### Timeline + +* has continuous duration in seconds + +### Canvas + +* has integer, unitless width and height +* has optional continuous duration in seconds + +### Scene + +* has continuous, unitless x,y,z cartesian coordinate space +* has optional continuous duration in seconds + +Bring in https://github.com/IIIF/3d/blob/main/temp-draft-4.md#scenes + + +## Putting stuff into Containers (composition) + +### Annotation + +"non-painting" + +"target" and "body" + + +### Annotation Page + +### Annotation Collection + + +### Manifest + +### Collection + +#### Paging + +### Range + +## Content State + +(introduce motivation and reasons) + +Separate Content State Sharing spec (protocols for sharing annotations) + +content state intended to: + + - load a view of some resource (existing spec) + - load a view of some resource AND modify the Container (show you my new anno, add camera) + - modify the Container in a particular context (`scope`, storytelling) + - contribute additional information permanently (rerum **inbox** - move to protocol doc) + + +## Selectors + +### SpecificResource + +### PointSelector + + +## Scene-Specific Resources + +### 3D considerations / principles + +"models" (content resources in 3D) +"local coordinate spaces" + +### Camera + +### Light + +### Transforms + +#### ScaleTransform + +#### RotateTransform + +#### TranslateTransform + +"Relative Rotation" + +"Excluding" + +## Advanced Association Features + + +### Segments + +### Embedded Content + +### Choice of Alternative Resources + +### Non Rectangular Segments + +### Style + +### Rotation + +### Comment Annotations + +### Hotspot Linking + +### Activation + +### Using Content State + + - modify the Container in a particular context (`scope`, storytelling) + + + +### Physical Dimension Service + + + +## HTTP Requests and Responses + +### URI Recommendations + +### Requests + +### Responses + +### Authentication + + +## Appendices + +### Summary of Property Requirements + +### Example Manifest Response + +### Versioning + +### Acknowledgements + +### Change Log + +"Exclude Audio" \ No newline at end of file diff --git a/source/presentation/4.0/properties.md b/source/presentation/4.0/properties.md new file mode 100644 index 000000000..a65d8bb14 --- /dev/null +++ b/source/presentation/4.0/properties.md @@ -0,0 +1,35 @@ +# Vocabulary? + +## Resource Properties + +### Descriptive Properties + +#### label (etc) + +### Linking Properties + +### Technical Properties + +### Structural Properties + +### Values + + + +## JSON-LD Considerations + +### Case Sensitivity + +### Resource Representations + +### Properties with Multiple Values + +### Language of Property Values + +### HTML Markup in Property Values + +### Linked Data Context and Extensions + +### Term Collisions between Contexts + +### Keyword Mappings \ No newline at end of file diff --git a/source/presentation/4/context.json b/source/presentation/4/context.json new file mode 100644 index 000000000..9e26dfeeb --- /dev/null +++ b/source/presentation/4/context.json @@ -0,0 +1 @@ +{} \ No newline at end of file From f7d2aafbb7d7449d884080e743e145d0aa9f7a6b Mon Sep 17 00:00:00 2001 From: tomcrane Date: Thu, 24 Oct 2024 11:37:58 +0100 Subject: [PATCH 002/130] container desc --- source/presentation/4.0/index.md | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index fe5616888..06f32011a 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -5,28 +5,39 @@ Manifests, Containers, Annotations oh my! Manifest as unit of distribution -## Content Resources? +## Content Resources -There is stuff that we want to show +There is stuff that we want to show - images, video, audio, 3D models etc ## Containers +This is where we put content resources "painting" + +And we can also put other things: "supplementing" +And we can nest them "Nesting" (see 3d draft) + ### Timeline +A Container that represents a bounded temporal range, without any spatial coordinates. + * has continuous duration in seconds ### Canvas +A Container that represents a bounded, two-dimensional space and has content resources associated with all or parts of it. It may also have a bounded temporal range in the same manner as a Timeline. + * has integer, unitless width and height * has optional continuous duration in seconds ### Scene +A Container that represents a boundless three-dimensional space and has content resources positioned at locations within it. Rendering a Scene requires the use of Cameras and Lights. It may also have a bounded temporal range in the same manner as a Timeline. + * has continuous, unitless x,y,z cartesian coordinate space * has optional continuous duration in seconds From ef1ee247c207a4aa541224b6caf1585bd1041333 Mon Sep 17 00:00:00 2001 From: tomcrane Date: Thu, 24 Oct 2024 11:59:46 +0100 Subject: [PATCH 003/130] add 3d props to properties doc --- source/presentation/4.0/properties.md | 154 ++++++++++++++++++++++++++ 1 file changed, 154 insertions(+) diff --git a/source/presentation/4.0/properties.md b/source/presentation/4.0/properties.md index a65d8bb14..ced32bfea 100644 --- a/source/presentation/4.0/properties.md +++ b/source/presentation/4.0/properties.md @@ -6,10 +6,164 @@ #### label (etc) + + ### Linking Properties ### Technical Properties +#### backgroundColor + +This property sets the background color behind any painted resources on a spatial resource, such as a Canvas or Scene. + +The value _MUST_ be string, which defines an RGB color. It SHOULD be a hex value starting with "#" and is treated in a case-insensitive fashion. If this property is not specified, then the default value is client-dependent. + + * A Canvas _MAY_ have the `backgroundColor` property
+ Clients _SHOULD_ render `backgroundColor` on any resource type. + * A Scene _MAY_ have the `backgroundColor` property
+ Clients _SHOULD_ render `backgroundColor` on any resource type. + * Other resources _MUST NOT_ have the `backgroundColor` property. + +```json +"backgroundColor": "#FFFFFF" +``` + +
+❓Can you set bgColor on a transparent image? An area? Conflict with `style` on a SpecificResource? +
+ + + +##### near + +This property gives the distance from the camera from which objects are visible. Objects closer to the camera than the `near` distance cannot be seen. + +The value is a non-negative floating point number. If this property is not specified, then the default value is client-dependent. + +* A Camera _MAY_ have the `near` property
+ Clients _SHOULD_ process the `near` property on Cameras. + +```json +"near": 1.5 +``` + +##### far + +This property gives the distance from the camera after which objects are no longer visible. Objects further from the camera than the `far` distance cannot be seen. + +The value is a non-negative floating point number, and _MUST_ be greater than the value for `near` on the same camera. If this property is not specified, then the default value is client-dependent. + +* A Camera _MAY_ have the `far` property
+ Clients _SHOULD_ process the `far` property on Cameras. + +```json +"far": 200.0 +``` + +##### fieldOfView + +_Summary here_ + +The value _MUST_ be a floating point number greater than 0 and less than 180. If this property is not specified, then the default value is client-dependent. + +* A PerspectiveCamera _SHOULD_ have the `fieldOfView` property.
+ Clients _SHOULD_ process the `fieldOfView` property on Cameras. + +```json + "fieldOfView": 50.0 +``` + +##### angle + +_Summary here_ + +The value _MUST_ be a floating point number greater than 0 and less than 90. If this property is not specified, then the default value is client-dependent. + +* A SpotLight _SHOULD_ have the `angle` property.
+ Clients _SHOULD_ process the `angle` property on SpotLights. + +```json + "angle": 15.0 +``` + +##### lookAt + +_Summary here_ + +The value _MUST_ be a JSON object, conforming to either a reference to an Annotation with an `id` and a `type` of "Anntoation", or a PointSelector. If this property is not specified, then the default value is null -- the camera or light is not looking at anything. + +```json +"lookAt": { + "type": "PointSelector", + "x": 3, + "y": 0, + "z": -10 +} +``` + +##### color + +This property sets the color of a Light. + +The value _MUST_ be string, which defines an RGB color. It SHOULD be a hex value starting with "#" and is treated in a case-insensitive fashion. If this property is not specified, then the default value is "#FFFFFF". + + * A Light _SHOULD_ have the `color` property
+ Clients _SHOULD_ render `color` on any resource type. + * Other resources _MUST NOT_ have the `color` property. + +```json +"color": "#FFA0A0" +``` + +##### intensity + +This property sets the strength or brightness of a Light. + +The value _MUST_ be a JSON object, that has the `type`, `value` and `unit` properties. All three properties are required. The value of `type` _MUST_ be the string "Value". The value of `value` is a floating point number. The value of `unit` is a string, drawn from a controlled vocabulary of units. If this property is not specified, then the default intensity value is client-dependent. + +This specification defines the unit value of "relative" which constrains the value to be a linear scale between 0.0 (no brightness) and 1.0 (as bright as the client will render). + +* A Light _SHOULD_ have the `intensity` property.
+ Clients _SHOULD_ process the `intensity` property on Lights. + +```json +{ + "intensity": {"type": "Value", "value": 0.5, "unit": "relative"} +} +``` + +##### Exclude + +_Summary here_ + +_On Annotation, a list of strings drawn from table_ + +| Value | Description | +|------------|-------------| +| Audio | | +| Animations | | +| Cameras | | +| Lights | | + +```json +"exclude": [ "Audio", "Lights", "Cameras", "Animations" ] +``` + + +##### transform + +_Summary here_ + +The value of this property is an array of JSON objects, each of which is a Transform. + +##### x + +##### y + +##### z + + + ### Structural Properties ### Values From 6d5bb5ed445848ae824912e7816c2090624bcff0 Mon Sep 17 00:00:00 2001 From: HackMD <37423+hackmd-hub[bot]@users.noreply.github.com> Date: Thu, 24 Oct 2024 10:56:13 +0000 Subject: [PATCH 004/130] last changed at Oct 24, 2024 11:55 AM, pushed by Julie Winchester --- source/presentation/4.0/index.md | 395 ++++++++++++++++++++++++++++++- 1 file changed, 388 insertions(+), 7 deletions(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index 06f32011a..fd8a73db0 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -1,10 +1,12 @@ # Presentation 4 -## How this stuff works +## Introduction Manifests, Containers, Annotations oh my! Manifest as unit of distribution + - + ## Content Resources There is stuff that we want to show - images, video, audio, 3D models etc @@ -20,12 +22,132 @@ And we can also put other things: And we can nest them "Nesting" (see 3d draft) +As multiple models, lights, cameras, and other resources can be associated with and placed within a Scene container, Scenes provide a straightforward way of grouping content resources together within a space. Scenes, as well as other IIIF containers such as Canvases, can also be embedded within a Scene, allowing for the nesting of content resources. + +A Scene or a Canvas may be treated as a content resource, referenced or described within the `body` of an Annotation. As with models and other resources, the Annotation is associated with a Scene into which the Scene or Canvas is to be nested through an Annotation `target`. The content resource Scene will be placed within the `target` Scene by aligning the coordinate origins of the two scenes. Alternately, Scene Annotations may use `PointSelector` to place the origin of the resource Scene at a specified coordinate within the `target` Scene. + +As with other resources, it may be appropriate to modify the initial scale, rotation, or translation of a content resource Scene prior to painting it within another Scene. Scenes associated with SpecificResources may be manipulated through the transforms described in [Transforms](transforms_section). + +A simple example painting one Scene into another: + +```json +{ + "id": "https://example.org/iiif/3d/anno1", + "type": "Annotation", + "motivation": ["painting"], + "body": { + "id": "https://example.org/iiif/scene1", + "type": "Scene" + }, + "target": "https://example.org/iiif/scene2" +} +``` + + +Content resources of the appropriate dimension(s) may be annotated into a Container that has those dimensions. + ### Timeline A Container that represents a bounded temporal range, without any spatial coordinates. * has continuous duration in seconds + for all or part of its duration. + + +A Timeline _MUST_ have a `duration` property that defines its length in seconds. The `duration` value must be a positive floating point number. + +An annotation that targets a Scene using a PointSelector without any temporal refinement implicitly targets the Scene's entire duration. + +A content resource may be annotated into a Scene for a period of time by use of a PointSelector that is temporally scoped by a [FragmentSelector](https://www.w3.org/TR/annotation-model/#fragment-selector). The FragmentSelector has a `value` property, the value of which follows the [media fragment syntax](https://www.w3.org/TR/media-frags/#naming-time) of `t=`. This annotation pattern uses the `refinedBy` property [defined by the W3C Web Annotation Data Model](https://www.w3.org/TR/annotation-model/#refinement-of-selection). + +```json +{ + "id": "https://example.org/iiif/3d/anno1", + "type": "Annotation", + "motivation": ["painting"], + "body": { + "id": "https://example.org/iiif/assets/model1.glb", + "type": "Model" + }, + "target": { + "type": "SpecificResource", + "source": [ + { + "id": "https://example.org/iiif/scene1", + "type": "Scene" + } + ], + "selector": [ + { + "type": "PointSelector", + "x": -1.0, + "y": -1.0, + "z": 3.0, + "refinedBy": { + "type": "FragmentSelector", + "value": "t=45,95" + } + } + ] + } +} +``` + +When using a URL fragment in place of a SpecificResource, the parameter `t` can be used to select the temporal region: + +```json +{ + "id": "https://example.org/iiif/3d/anno1", + "type": "Annotation", + "motivation": ["painting"], + "body": { + "id": "https://example.org/iiif/assets/model1.glb", + "type": "Model" + }, + "target": "https://example.org/iiif/scene1#xyz=-1,-1,3&t=45,95" +} +``` + +An Annotation may target a specific point in time using a PointSelector's `instant` property. The property's value must be a positive floating point number indicating a value in seconds that falls within the Scene's duration. + +```json +{ + "id": "https://example.org/iiif/3d/anno1", + "type": "Annotation", + "motivation": ["painting"], + "body": { + "id": "https://example.org/iiif/assets/model1.glb", + "type": "Model" + }, + "target": { + "type": "SpecificResource", + "source": [ + { + "id": "https://example.org/iiif/scene1", + "type": "Scene" + } + ], + "selector": [ + { + "type": "PointSelector", + "x": -1.0, + "y": -1.0, + "z": 3.0, + "instant": 45.0 + } + ] + } +} +``` + +The Annotation's [`timeMode` property](https://iiif.io/api/presentation/3.0/#timemode) can be used to indicate the desired behavior when the duration of the content resource that is not equal to the temporal region targeted by the annotation. + +It is an error to select a temporal region of a Scene that does not have a `duration`, or to select a temporal region that is not within the Scene's temporal extent. A Canvas or Scene with a `duration` may not be annotated as a content resource into a Scene that does not itself have a `duration`. + + + + ### Canvas @@ -41,13 +163,97 @@ A Container that represents a boundless three-dimensional space and has content * has continuous, unitless x,y,z cartesian coordinate space * has optional continuous duration in seconds -Bring in https://github.com/IIIF/3d/blob/main/temp-draft-4.md#scenes +A Scene in IIIF is a virtual container that represents a boundless three-dimensional space and has content resources, lights and cameras positioned at locations within it. It may also have a duration to allow the sequencing of events and timed media. Scenes have infinite height (y axis), width (x axis) and depth (z axis), where 0 on each axis (the origin of the coordinate system) is treated as the center of the scene's space. +The positive y axis points upwards, the positive x axis points to the right, and the positive z axis points forwards (a [right-handed cartesian coordinate system](link to wikipedia)). + +The axes of the coordinate system are measured in arbitrary units and these units do not necessarily correspond to any physical unit of measurement. This allows arbitrarily scaled models to be used, including very small or very large, without needing to deal with very small or very large values. If there is a correspondence to a physical scale, then this can be asserted using the [physical dimensions pattern](fwd-ref-to-phys-dims). + +diagram of Right handed cartesian coordinate system + + +As with other containers in IIIF, Annotations are used to target the Scene to place content such as 3d models into the scene. Annotations are also used to add lights and cameras. A Scene can have multiple models, lights, cameras and other resources, allowing them to be grouped together. Scenes and other IIIF containers, such as Canvases, may also be embedded within Scenes, as described below in the [nesting section][fwd-ref-to-nesting]. + +```json +{ + "id": "https://example.org/iiif/scenes/1", + "type": "Scene", + "label": {"en": ["Chessboard"]}, + "backgroundColor": "#000000", + "items": [ + "Note: Annotations Live Here" + ] +} +``` + ## Putting stuff into Containers (composition) ### Annotation + +Annotations follow the [Web Annotation][org-w3c-webanno] data model and are used to associate models, lights, cameras, and IIIF containers such as Canvases, with Scenes. They have a `type` of "Annotation", a `body` (being the resource to be added to the scene) and a `target` (being the scene or a position within the scene). They must have a `motivation` property with the value of "painting" to assert that the resource is being painted into the Scene, rather than the Annotation being a comment about the Scene. + +A construct called a Selector is used to select a part of a resource, such as a point within a Scene. The use of a Selector necessitates the creation of a `SpecificResource` that groups together the resource being selected (the `source`) and the instance of the Selector. This SpecificResource can then be used as either the `body` or the `target` of the Annotation. + +All resources that can be added to a Scene have an implicit (e.g. Lights, Cameras) or explicit (e.g. Models, Scenes), local coordinate space. If a resource does not have an explicit coordinate space, then it is positioned at the origin of its coordinate space. In order to add a resource with its local coordinate space into a Scene with its own coordinate space, these spaces must be aligned. This done by aligning the origins of the two coordinate spaces. + +Annotations may use a type of Selector called a `PointSelector` to align the Annotation to a point within the Scene that is not the Scene's origin. PointSelectors have three spatial properties, `x`, `y` and `z` which give the value on that axis. They also have a temporal property `instant` which can be used if the Scene has a duration, which gives the temporal point in seconds from the start of the duration, the use of which is defined in the [section on Scenes with Durations](). + +Example Annotation that positions a model at a point within a Scene: + +```json +{ + "id": "https://example.org/iiif/3d/anno1", + "type": "Annotation", + "motivation": ["painting"], + "body": { + "id": "https://example.org/iiif/assets/model1.glb", + "type": "Model" + }, + "target": { + "type": "SpecificResource", + "source": [ + { + "id": "https://example.org/iiif/scene1", + "type": "Scene" + } + ], + "selector": [ + { + "type": "PointSelector", + "x": -1.0, + "y": 0.0, + "z": 1.0 + } + ] + } +} +``` + +#### URI Fragments + +The point may instead be defined using a short-hand form of a URI Fragment at the end of the `id` of the Scene as the `target` of the Annotation. The name of the fragment parameter is `xyz` and its value is the x, y and z values separated by commas. Each value can be expressed as either an integer or a floating point number. + +The annotation above could be expressed as its fragment-based equivalent: + +```json +{ + "id": "https://example.org/iiif/3d/anno1", + "type": "Annotation", + "motivation": ["painting"], + "body": { + "id": "https://example.org/iiif/assets/model1.glb", + "type": "Model" + }, + "target": "https://example.org/iiif/scene1#xyz=-1,0,1" +} +``` + + + + + "non-painting" "target" and "body" @@ -96,22 +302,197 @@ content state intended to: ### Camera +A Camera provides a view of a region of the Scene's space from a particular position within the Scene; the client constructs a viewport into the Scene and uses the view of one or more Cameras to render that region. The size and aspect ratio of the viewport is client and device dependent. + +
+❓Does this prevent extension cameras from requiring a fixed aspect ratio? +
+ +This specification defines two types of Camera: + +| Class | Description | +| ------------------- | ------------ | +| `PerspectiveCamera` | `PerspectiveCamera` mimics the way the human eye sees, in that objects further from the camera are smaller | +| `OrthographicCamera` | `OrthographicCamera` removes visual perspective, resulting in object size remaining constant regardless of its distance from the camera | + +Cameras are positioned within the Scene facing in a specified direction. Both position and direction are defined through the Annotation which adds the Camera to the Scene, described below in the sections on [Painting Annotations][] and [Transforms][]. If either the position or direction is not specified, then the position defaults to the origin, and direction defaults to facing along the z axis towards negative infinity. + +The region of the Scene's space that is observable by the camera is bounded by two planes orthogonal to the direction the camera is facing, given in the `near` and `far` properties, and a vertical projection angle that provides the top and bottom planes of the region. + +The `near` property defines the minimum distance from the camera at which something in the space must exist in order to be viewed by the camera. Anything nearer to the camera than this distance will not be viewed. Conversely, the `far` property defines a maximum distance from the camera at which something in the space must exist in order to be viewed by the camera. Anything further away will not be viewed. + +For PerspectiveCameras, the vertical projection angle is specificed using the full angular extent in degrees from the top plane to the bottom plane using the `fieldOfView` property. The `fieldOfView` angle MUST be greater than 0 and less than 180. For OrthographicCameras, the vertical projection is always parallel and thus not defined. + +If any of these properties are not specified explicitly, they default to the choice of the client implementation. + +drawing of a geometrical frustrum truncated by near and far distances + + +If the Scene does not have any Cameras defined within it, then the client MUST provide a default Camera. The type, properties and position of this default camera are client-dependent. + +```json +{ + "id": "https://example.org/iiif/camera/1", + "type": "PerspectiveCamera", + "near": 1.0, + "far": 100.0, + "fieldOfView": 45.0 +} +``` + + + ### Light +One or more Lights MUST be present within the Scene in order to have objects within it be visible to the Cameras. + +This specification defines four types of Light: + +| Class | Description | +| ----- | ------------ | +| `AmbientLight` | AmbientLight evenly illuminates all objects in the scene, and does not have a direction or position. | +| `DirectionalLight` | DirectionalLight emits in a specific direction as if it is infinitely far away and the rays produced from it are all parallel. It does not have a specific position. | +| `PointLight` | PointLight emits from a single point within the scene in all directions. | +| `SpotLight` | SpotLight emits a cone of light from a single point in a given direction. | + +Lights defined in this specification have a `color` and an `intensity`. The color is given as an RGB value, such as "#FFFFFF" for white. The intensity is the strength or brightness of the light, and described using a `Value` construct. + +SpotLight has an additional property of `angle`, specified in degrees, which is the angle from the direction that the Light is facing to the outside extent of the cone. + +diagram of cone geometry showing how the angle of the cone is defined + +Lights that require a position and/or direction have these through the Annotation which associates them with the Scene, described below in the sections on [Painting Annotations][] and [Transforms][]. If a Light does not have an explicit direction, then the default is in the negative y direction (downwards). If a Light does not have an explicit position in the coordinate space, then the default is at the origin. + +This specification does not define other aspects of Lights, such as the rate of decay of the intensity of the light over a distance, the maximum range of the light, or the penumbra of a cone. Implementation of these aspects is client-dependent. + +If there are no Lights present within the Scene, then the viewer MUST add at least one Light. The types and properties of Lights added in this way are client-dependent. + +```json +{ + "id": "https://example.org/iiif/light/1", + "type": "AmbientLight", + "color": "#FFFFFF", + "intensity": {"type": "Value", "value": 0.6, "unit": "relativeUnit"} +} +``` + + + ### Transforms -#### ScaleTransform +The Annotation with a Selector on the target can paint a resource at a point other than the origin, however it will be at its initial scale and rotation, which may not be appropriate for the scene that is being constructed. + +This specification defines a new class of manipulations for SpecificResources called a `Transform`, with three specific sub-classes. Each Transform has three properties, `x`, `y` and `z` which determine how the Transform affects that axis in the local coordinate space. + + +| Class | Description | +| --------------- | ------------ | +| ScaleTransform | A ScaleTransform applies a multiplier to one or more axes in the local coordinate space. A point that was at 3.5, after applying a ScaleTransform of 2.0 would then be at 7.0. If an axis value is not specified, then it is not changed, resulting in a default of 1.0 | +| RotateTransform | A RotateTransform rotates the local coordinate space around the given axis in a counter-clockwise direction around the axis itself (e.g. around a pivot point of 0 on the axis). A point that was at x=1,y=1 and was rotated 90 degrees around the x axis would be at x=1,y=0,z=1. If an axis value is not specified, then it is not changed, resulting in a default of 0.0 | +| TranslateTransform | A TranslateTransform moves all of the objects in the local coordinate space the given distance along the axis. A point that was at x=1.0, after applying a TranslateTransform of x=1.0 would be at x=2.0. If an axis value is not specified then it is not changed, resulting in a default of 0.0 | -#### RotateTransform +Transforms are added to a SpecificResource using the `transform` property. The value of the property is an array, which determines the order in which the transforms are to be applied. The resulting state of the first transform is the input state for the second transform, and so on. Different orders of the same set of transforms can have different results, so attention must be paid when creating the array and when processing it. -#### TranslateTransform +The point around which RotateTransform rotates the space is the origin. This "pivot point" cannot be changed directly, but instead a TranslateTransform can be used to move the desired pivot point to the be at the origin, then the RotateTransform applied. + +Transforms are only used in the Presentation API when the SpecificResource is the `body` of the Annotation, and are applied before the resource is painted into the scene at the point given in the `target`. + +```json +{ + "type": "SpecificResource", + "source": { + "id": "https://example.org/iiif/assets/model1.glb", + "type": "Model" + }, + "transform": [ + { + "type": "RotateTransform", + "x": 0.0, + "y": 180.0, + "z": 0.0 + }, + { + "type": "TranslateTransform", + "x": 1.0, + "y": 0.0, + "z": 0.0 + } + ] +} +``` + + +#### Relative Rotation + +It is useful to be able to rotate a light or camera resource such that it is facing another object or point in the Scene, rather than calculating the angles within the Scene's coordinate space. This is accomplished with a property called `lookAt`, valid on DirectionalLight, SpotLight, and all Cameras. The value of the property is either a PointSelector or the URI of an Annotation which paints something into the current Scene. + +If the value is a PointSelector, then the light or camera resource is rotated around the x and y axes such that it is facing the given point. If the value is an Annotation which targets a point via a PointSelector, URI fragment or other mechanism, then the direction the resource is facing that point. + +
+❓What happens if the Annotation targets a Polygon or other non-Point? Calculate centroid? Error? First point given in the Poly / center of a sphere? +
+ +This rotation happens after the resource has been added to the Scene, and thus after any transforms have taken place in the local coordinate space. As the z axis is not affected by the rotation, any RotateTransform that changes z will be retained, but any change to x or y will be lost. + +```json +"lookAt": { + "type": "PointSelector", + "x": 3, + "y": 0, + "z": -10 +} +``` + + +#### Excluding + +Just as a Scene may contain multiple Annotations with model, light, and camera resources, a single 3D model file may contain a collection of 3D resources, including model geometry, assemblages of lights, and/or multiple cameras, with some of these potentially manipulated by animations. When painting Scenes or models that themselves may contain groups of resources within a single Scene, it may not always be appropriate to include all possible cameras, lights, or other resources, and it may be desirable to opt not to import some of these resources. This is accomplished through the Annotation property `exclude`, which prevents the import of audio, lights, cameras, or animations from a particular Scene or model prior to the Annotation being painted into a Scene. When `exclude` is used, the excluded resource type should not be loaded into the Scene, and it is not possible to reactivate or turn on these excluded resources after loading. + +Painting a Scene into another while excluding import of several types of resources: +```json +{ + "id": "https://example.org/iiif/3d/anno1", + "type": "Annotation", + "motivation": ["painting"], + "exclude": ["Audio", "Lights", "Cameras", "Animations"], + "body": { + "id": "https://example.org/iiif/scene1", + "type": "Scene" + }, + "target": "https://example.org/iiif/scene2" +} +``` -"Relative Rotation" -"Excluding" ## Advanced Association Features +### Nesting + +A Canvas can be painted into a Scene as an Annotation, but the 2D nature of Canvases requires special consideration due to important differences between Canvases and Scenes. A Canvas describes a bounded 2D space with finite `height` and `width` measured in pixels with a pixel origin at the top-left corner of the Canvas, while Scenes describe a boundless 3D space with x, y, and z axes of arbitrary coordinate units and a coordinate origin at the center of the space. It is important to note that in many cases the pixel scale used by a Canvas or a 2D image content resource will not be in proportion to the desired 3D coordinate unit scale in a Scene. + +When a Canvas is painted as an Annotation targeting a Scene, the top-left corner of the Canvas (the pixel origin) is aligned with the 3D coordinate origin of the Scene. The top edge of the Canvas is aligned with (e.g., is colinear to) the positive x axis extending from the coordinate origin. The left edge of the Canvas is aligned with (e.g., is colinear to) the negative y axis extending from the coordinate origin. The Canvas is scaled to the Scene such that the pixel dimensions correspond to 3D coordinate units - a Canvas 200 pixels wide and 400 pixels high will extend 200 coordinate units across the x axis and 400 coordinate units across the y axis. Please note: direction terms "top", "bottom", "right", and "left" used in this section refer to the frame of reference of the Canvas itself, not the Scene into which the Canvas is painted. + +A Canvas in a Scene has a specific forward face and a backward face. By default, the forward face of a Canvas should point in the direction of the positive z axis. If the property `backgroundColor` is used, this color should be used for the backward face of the Canvas. Otherwise, a reverse view of the forward face of the Canvas should be visible on the backward face. + +
+ To Do: Add an image demonstrating default Canvas placement in Scene +
+ +A `PointSelector` can be used to modify the point at which the Canvas will be painted, by establishing a new point to align with the top-left corner of the Canvas instead of the Scene coordinate origin. Transforms can also be used to modify Canvas rotation, scale, or translation. + +It may be desirable to exercise greater control over how the Canvas is painted into the Scene by selecting the coordinate points in the Scene that should correspond to each corner of the Canvas. This provides fine-grained manipulation of Canvas placement and/or scale, and for optionally introducing Canvas distortion or skew. Annotations may use a type of Selector called a `PolygonZSelector` to select different points in the Scene to align with the top-left, bottom-left, bottom-right, and top-right corners of the Canvas. PolygonZSelectors have a single property, `value`, which is a string listing a WKT `POLYGONZ` expression containing four coordinate points, with each coordinate separated by commas, and axes within a coordinate separated by spaces. The four Scene coordinates should be listed beginning with the coordinate corresponding to the top-left corner of the Canvas, and should proceed in a counter-clockwise winding order around the Canvas, with coordinates corresponding to bottom-left, bottom-right, and top-right corners in order respectively. The use of PolygonZSelector overrides any use of Transforms on the Canvas Annotation. + +Example placing top-left at (0, 1, 0); bottom-left at (0, 0, 0); bottom-right at (1, 0, 0); and top-right at (1, 1, 0): +```json +"selector": [ + { + "type": "PolygonZSelector", + "value": "POLYGONZ((0 1 0, 0 0 0, 1 0 0, 1 1 0))" + } +] +``` + ### Segments From bd0eca81ce8990741b2579d90953dcdb18a99b2e Mon Sep 17 00:00:00 2001 From: HackMD <37423+hackmd-hub[bot]@users.noreply.github.com> Date: Thu, 24 Oct 2024 12:03:38 +0000 Subject: [PATCH 005/130] last changed at Oct 24, 2024 1:01 PM, pushed by Julie Winchester --- source/presentation/4.0/properties.md | 956 +++++++++++++++++++++++++- 1 file changed, 944 insertions(+), 12 deletions(-) diff --git a/source/presentation/4.0/properties.md b/source/presentation/4.0/properties.md index ced32bfea..b41dcdfc9 100644 --- a/source/presentation/4.0/properties.md +++ b/source/presentation/4.0/properties.md @@ -4,14 +4,549 @@ ### Descriptive Properties -#### label (etc) +##### label + +A human readable label, name or title. The `label` property is intended to be displayed as a short, textual surrogate for the resource if a human needs to make a distinction between it and similar resources, for example between objects, pages, or options for a choice of images to display. The `label` property can be fully internationalized, and each language can have multiple values. This pattern is described in more detail in the [languages][prezi30-languages] section. + +The value of the property _MUST_ be a JSON object, as described in the [languages][prezi30-languages] section. + + * A Collection _MUST_ have the `label` property with at least one entry.
+ Clients _MUST_ render `label` on a Collection. + * A Manifest _MUST_ have the `label` property with at least one entry.
+ Clients _MUST_ render `label` on a Manifest. + * A Canvas _SHOULD_ have the `label` property with at least one entry.
+ Clients _MUST_ render `label` on a Canvas, and _SHOULD_ generate a `label` for Canvases that do not have them. + * A content resource _MAY_ have the `label` property with at least one entry. If there is a Choice of content resource for the same Canvas, then they _SHOULD_ each have at least the `label` property with at least one entry.
+ Clients _MAY_ render `label` on content resources, and _SHOULD_ render them when part of a Choice. + * A Range _SHOULD_ have the `label` property with at least one entry.
+ Clients _MUST_ render `label` on a Range. + * An Annotation Collection _SHOULD_ have the `label` property with at least one entry.
+ Clients _SHOULD_ render `label` on an Annotation Collection. + * Other types of resource _MAY_ have the `label` property with at least one entry.
+ Clients _MAY_ render `label` on other types of resource. + +{% include api/code_header.html %} +``` json-doc +{ "label": { "en": [ "Example Object Title" ] } } +``` +##### metadata + +An ordered list of descriptions to be displayed to the user when they interact with the resource, given as pairs of human readable `label` and `value` entries. The content of these entries is intended for presentation only; descriptive semantics _SHOULD NOT_ be inferred. An entry might be used to convey information about the creation of the object, a physical description, ownership information, or other purposes. + +The value of the `metadata` property _MUST_ be an array of JSON objects, where each item in the array has both `label` and `value` properties. The values of both `label` and `value` _MUST_ be JSON objects, as described in the [languages][prezi30-languages] section. + + * A Collection _SHOULD_ have the `metadata` property with at least one item.
+ Clients _MUST_ render `metadata` on a Collection. + * A Manifest _SHOULD_ have the `metadata` property with at least one item.
+ Clients _MUST_ render `metadata` on a Manifest. + * A Canvas _MAY_ have the `metadata` property with at least one item.
+ Clients _SHOULD_ render `metadata` on a Canvas. + * Other types of resource _MAY_ have the `metadata` property with at least one item.
+ Clients _MAY_ render `metadata` on other types of resource. + +Clients _SHOULD_ display the entries in the order provided. Clients _SHOULD_ expect to encounter long texts in the `value` property, and render them appropriately, such as with an expand button, or in a tabbed interface. + +{% include api/code_header.html %} +``` json-doc +{ + "metadata": [ + { + "label": { "en": [ "Creator" ] }, + "value": { "en": [ "Anne Artist (1776-1824)" ] } + } + ] +} +``` + +##### summary + +A short textual summary intended to be conveyed to the user when the `metadata` entries for the resource are not being displayed. This could be used as a brief description for item level search results, for small-screen environments, or as an alternative user interface when the `metadata` property is not currently being rendered. The `summary` property follows the same pattern as the `label` property described above. + +The value of the property _MUST_ be a JSON object, as described in the [languages][prezi30-languages] section. + + * A Collection _SHOULD_ have the `summary` property with at least one entry.
+ Clients _SHOULD_ render `summary` on a Collection. + * A Manifest _SHOULD_ have the `summary` property with at least one entry.
+ Clients _SHOULD_ render `summary` on a Manifest. + * A Canvas _MAY_ have the `summary` property with at least one entry.
+ Clients _SHOULD_ render `summary` on a Canvas. + * Other types of resource _MAY_ have the `summary` property with at least one entry.
+ Clients _MAY_ render `summary` on other types of resource. + +{% include api/code_header.html %} +``` json-doc +{ "summary": { "en": [ "This is a summary of the object." ] } } +``` + +##### requiredStatement + +Text that _MUST_ be displayed when the resource is displayed or used. For example, the `requiredStatement` property could be used to present copyright or ownership statements, an acknowledgement of the owning and/or publishing institution, or any other text that the publishing organization deems critical to display to the user. Given the wide variation of potential client user interfaces, it will not always be possible to display this statement to the user in the client's initial state. If initially hidden, clients _MUST_ make the method of revealing it as obvious as possible. + +The value of the property _MUST_ be a JSON object, that has the `label` and `value` properties, in the same way as a `metadata` property entry. The values of both `label` and `value` _MUST_ be JSON objects, as described in the [languages][prezi30-languages] section. + + * Any resource type _MAY_ have the `requiredStatement` property.
+ Clients _MUST_ render `requiredStatement` on every resource type. + +{% include api/code_header.html %} +``` json-doc +{ + "requiredStatement": { + "label": { "en": [ "Attribution" ] }, + "value": { "en": [ "Provided courtesy of Example Institution" ] } + } +} +``` + +##### rights + +A string that identifies a license or rights statement that applies to the content of the resource, such as the JSON of a Manifest or the pixels of an image. The value _MUST_ be drawn from the set of [Creative Commons][org-cc-licenses] license URIs, the [RightsStatements.org][org-rs-terms] rights statement URIs, or those added via the [extension][prezi30-ldce] mechanism. The inclusion of this property is informative, and for example could be used to display an icon representing the rights assertions. + +If displaying rights information directly to the user is the desired interaction, or a publisher-defined label is needed, then it is _RECOMMENDED_ to include the information using the `requiredStatement` property or in the `metadata` property. + +The value _MUST_ be a string. If the value is drawn from Creative Commons or RightsStatements.org, then the string _MUST_ be a URI defined by that specification. + + * Any resource type _MAY_ have the `rights` property.
+ Clients _MAY_ render `rights` on any resource type. + +{% include api/code_header.html %} +``` json-doc +{ "rights": "http://creativecommons.org/licenses/by/4.0/" } +``` + +__Machine actionable URIs and links for users__
+The machine actionable URIs for both Creative Commons licenses and RightsStatements.org right statements are `http` URIs. In both cases, human readable descriptions are available from equivalent `https` URIs. Clients may wish to rewrite links presented to users to use these equivalent `https` URIs. +{: .note} + +##### provider + +An organization or person that contributed to providing the content of the resource. Clients can then display this information to the user to acknowledge the provider's contributions. This differs from the `requiredStatement` property, in that the data is structured, allowing the client to do more than just present text but instead have richer information about the people and organizations to use in different interfaces. + +The organization or person is represented as an `Agent` resource. + +* Agents _MUST_ have the `id` property, and its value _MUST_ be a string. The string _MUST_ be a URI that identifies the agent. +* Agents _MUST_ have the `type` property, and its value _MUST_ be the string "Agent". +* Agents _MUST_ have the `label` property, and its value _MUST_ be a JSON object as described in the [languages][prezi30-languages] section. +* Agents _SHOULD_ have the `homepage` property, and its value _MUST_ be an array of JSON objects as described in the [homepage][prezi30-homepage] section. +* Agents _SHOULD_ have the `logo` property, and its value _MUST_ be an array of JSON objects as described in the [logo][prezi30-logo] section. +* Agents _MAY_ have the `seeAlso` property, and its value _MUST_ be an array of JSON object as described in the [seeAlso][prezi30-seealso] section. + +The value _MUST_ be an array of JSON objects, where each item in the array conforms to the structure of an Agent, as described above. + + * A Collection _SHOULD_ have the `provider` property with at least one item.
+ Clients _MUST_ render `provider` on a Collection. + * A Manifest _SHOULD_ have the `provider` property with at least one item.
+ Clients _MUST_ render `provider` on a Manifest. + * Other types of resource _MAY_ have the `provider` property with at least one item.
+ Clients _SHOULD_ render `provider` on other types of resource. + +{% include api/code_header.html %} +``` json-doc +{ + "provider": [ + { + "id": "https://example.org/about", + "type": "Agent", + "label": { "en": [ "Example Organization" ] }, + "homepage": [ + { + "id": "https://example.org/", + "type": "Text", + "label": { "en": [ "Example Organization Homepage" ] }, + "format": "text/html" + } + ], + "logo": [ + { + "id": "https://example.org/images/logo.png", + "type": "Image", + "format": "image/png", + "height": 100, + "width": 120 + } + ], + "seeAlso": [ + { + "id": "https://data.example.org/about/us.jsonld", + "type": "Dataset", + "format": "application/ld+json", + "profile": "https://schema.org/" + } + ] + } + ] +} +``` + +##### thumbnail + +A content resource, such as a small image or short audio clip, that represents the resource that has the `thumbnail` property. A resource _MAY_ have multiple thumbnail resources that have the same or different `type` and `format`. + +The value _MUST_ be an array of JSON objects, each of which _MUST_ have the `id` and `type` properties, and _SHOULD_ have the `format` property. Images and videos _SHOULD_ have the `width` and `height` properties, and time-based media _SHOULD_ have the `duration` property. It is _RECOMMENDED_ that a [IIIF Image API][image-api] service be available for images to enable manipulations such as resizing. + + * A Collection _SHOULD_ have the `thumbnail` property with at least one item.
+ Clients _SHOULD_ render `thumbnail` on a Collection. + * A Manifest _SHOULD_ have the `thumbnail` property with at least one item.
+ Clients _SHOULD_ render `thumbnail` on a Manifest. + * A Canvas _MAY_ have the `thumbnail` property with at least one item. A Canvas _SHOULD_ have the `thumbnail` property if there are multiple resources that make up the view.
+ Clients _SHOULD_ render `thumbnail` on a Canvas. + * A content resource _MAY_ have the `thumbnail` property with at least one item. Content resources _SHOULD_ have the `thumbnail` property with at least one item if it is an option in a Choice of resources.
+ Clients _SHOULD_ render `thumbnail` on a content resource. + * Other types of resource _MAY_ have the `thumbnail` property with at least one item.
+ Clients _MAY_ render `thumbnail` on other types of resource. + +{% include api/code_header.html %} +``` json-doc +{ + "thumbnail": [ + { + "id": "https://example.org/img/thumb.jpg", + "type": "Image", + "format": "image/jpeg", + "width": 300, + "height": 200 + } + ] +} +``` + +##### navDate + +A date that clients may use for navigation purposes when presenting the resource to the user in a date-based user interface, such as a calendar or timeline. More descriptive date ranges, intended for display directly to the user, _SHOULD_ be included in the `metadata` property for human consumption. If the resource contains Canvases that have the `duration` property, the datetime given corresponds to the navigation datetime of the start of the resource. For example, a Range that includes a Canvas that represents a set of video content recording a historical event, the `navDate` is the datetime of the first moment of the recorded event. + +The value _MUST_ be an [XSD dateTime literal][org-w3c-xsd-datetime]. The value _MUST_ have a timezone, and _SHOULD_ be given in UTC with the `Z` timezone indicator, but _MAY_ instead be given as an offset of the form `+hh:mm`. + + * A Collection _MAY_ have the `navDate` property.
+ Clients _MAY_ render `navDate` on a Collection. + * A Manifest _MAY_ have the `navDate` property.
+ Clients _MAY_ render `navDate` on a Manifest. + * A Range _MAY_ have the `navDate` property.
+ Clients _MAY_ render `navDate` on a Range. + * A Canvas _MAY_ have the `navDate` property.
+ Clients _MAY_ render `navDate` on a Canvas. + * Other types of resource _MUST NOT_ have the `navDate` property.
+ Clients _SHOULD_ ignore `navDate` on other types of resource. + +{% include api/code_header.html %} +``` json-doc +{ "navDate": "2010-01-01T00:00:00Z" } +``` + +##### placeholderCanvas + +A single Canvas that provides additional content for use before the main content of the resource that has the `placeholderCanvas` property is rendered, or as an advertisement or stand-in for that content. Examples include images, text and sound standing in for video content before the user initiates playback; or a film poster to attract user attention. The content provided by `placeholderCanvas` differs from a thumbnail: a client might use `thumbnail` to summarize and navigate multiple resources, then show content from `placeholderCanvas` as part of the initial presentation of a single resource. A placeholder Canvas is likely to have different dimensions to those of the Canvas(es) of the resource that has the `placeholderCanvas` property. + +Clients _MAY_ display the content of a linked placeholder Canvas when presenting the resource. When more than one such Canvas is available, for example if `placeholderCanvas` is provided for the currently selected Range and the current Manifest, the client _SHOULD_ pick the one most specific to the content. Publishers _SHOULD NOT_ assume that the placeholder Canvas will be processed by all clients. Clients _SHOULD_ take care to avoid conflicts between time-based media in the rendered placeholder Canvas and the content of the resource that has the `placeholderCanvas` property. + +The value _MUST_ be a JSON object with the `id` and `type` properties, and _MAY_ have other properties of Canvases. The value of `type` _MUST_ be the string `Canvas`. The object _MUST NOT_ have the `placeholderCanvas` property, nor the `accompanyingCanvas` property. + + * A Collection _MAY_ have the `placeholderCanvas` property.
+ Clients _MAY_ render `placeholderCanvas` on a Collection. + * A Manifest _MAY_ have the `placeholderCanvas` property.
+ Clients _MAY_ render `placeholderCanvas` on a Manifest. + * A Canvas _MAY_ have the `placeholderCanvas` property.
+ Clients _MAY_ render `placeholderCanvas` on a Canvas. + * A Range _MAY_ have the `placeholderCanvas` property.
+ Clients _MAY_ render `placeholderCanvas` on a Range. + * Other types of resource _MUST NOT_ have the `placeholderCanvas` property.
+ Clients _SHOULD_ ignore `placeholderCanvas` on other types of resource. + +{% include api/code_header.html %} +``` json-doc +{ + "placeholderCanvas": { + "id": "https://example.org/iiif/1/canvas/placeholder", + "type": "Canvas", + "height": 1400, + "width": 1200 + } +} +``` + +##### accompanyingCanvas + +A single Canvas that provides additional content for use while rendering the resource that has the `accompanyingCanvas` property. Examples include an image to show while a duration-only Canvas is playing audio; or background audio to play while a user is navigating an image-only Manifest. + +Clients _MAY_ display the content of an accompanying Canvas when presenting the resource. As with `placeholderCanvas` above, when more than one accompanying Canvas is available, the client _SHOULD_ pick the one most specific to the content. Publishers _SHOULD NOT_ assume that the accompanying Canvas will be processed by all clients. Clients _SHOULD_ take care to avoid conflicts between time-based media in the accompanying Canvas and the content of the resource that has the `accompanyingCanvas` property. + +The value _MUST_ be a JSON object with the `id` and `type` properties, and _MAY_ have other properties of Canvases. The value of `type` _MUST_ be the string `Canvas`. The object _MUST NOT_ have the `placeholderCanvas` property, nor the `accompanyingCanvas` property. + + * A Collection _MAY_ have the `accompanyingCanvas` property.
+ Clients _MAY_ render `accompanyingCanvas` on a Collection. + * A Manifest _MAY_ have the `accompanyingCanvas` property.
+ Clients _MAY_ render `accompanyingCanvas` on a Manifest. + * A Canvas _MAY_ have the `accompanyingCanvas` property.
+ Clients _MAY_ render `accompanyingCanvas` on a Canvas. + * A Range _MAY_ have the `accompanyingCanvas` property.
+ Clients _MAY_ render `accompanyingCanvas` on a Range. + * Other types of resource _MUST NOT_ have the `accompanyingCanvas` property.
+ Clients _SHOULD_ ignore `accompanyingCanvas` on other types of resource. + +{% include api/code_header.html %} +``` json-doc +{ + "accompanyingCanvas": { + "id": "https://example.org/iiif/1/canvas/accompany", + "type": "Canvas", + "duration": 180.0 + } +} +``` -### Linking Properties ### Technical Properties +##### id + +The URI that identifies the resource. If the resource is only available embedded within another resource (see the [terminology section][prezi30-terminology] for an explanation of "embedded"), such as a Range within a Manifest, then the URI _MAY_ be the URI of the embedding resource with a unique fragment on the end. This is not true for Canvases, which _MUST_ have their own URI without a fragment. + +The value _MUST_ be a string, and the value _MUST_ be an HTTP(S) URI for resources defined in this specification. If the resource is retrievable via HTTP(S), then the URI _MUST_ be the URI at which it is published. External resources, such as profiles, _MAY_ have non-HTTP(S) URIs defined by other communities. + +The existence of an HTTP(S) URI in the `id` property does not mean that the URI will always be dereferencable. If the resource with the `id` property is [embedded][prezi30-terminology], it _MAY_ also be dereferenceable. If the resource is referenced (again, see the [terminology section][prezi30-terminology] for an explanation of "referenced"), it _MUST_ be dereferenceable. The [definitions of the Resources][prezi30-resource-structure] give further guidance. + + * All resource types _MUST_ have the `id` property.
+ Clients _MAY_ render `id` on any resource type, and _SHOULD_ render `id` on Collections, Manifests and Canvases. + +{% include api/code_header.html %} +``` json-doc +{ "id": "https://example.org/iiif/1/manifest" } +``` + +##### type + +The type or class of the resource. For classes defined for this specification, the value of `type` will be described in the sections below describing each individual class. + +For content resources, the value of `type` is drawn from other specifications. Recommendations for common content types such as image, text or audio are given in the table below. + +The JSON objects that appear in the value of the `service` property will have many different classes, and can be used to distinguish the sort of service, with specific properties defined in a [registered context document][prezi30-ldce]. + +The value _MUST_ be a string. + + * All resource types _MUST_ have the `type` property.
+ Clients _MUST_ process, and _MAY_ render, `type` on any resource type. + +| Class | Description | +| ------------- | -------------------------------- | +| `Dataset` | Data not intended to be rendered to humans directly | +| `Image` | Two dimensional visual resources primarily intended to be seen, such as might be rendered with an <img> HTML tag | +| `Model` | A three (or more) dimensional model intended to be interacted with by humans | +| `Sound` | Auditory resources primarily intended to be heard, such as might be rendered with an <audio> HTML tag | +| `Text` | Resources primarily intended to be read | +| `Video` | Moving images, with or without accompanying audio, such as might be rendered with a <video> HTML tag | +{: .api-table #table-type} + +{% include api/code_header.html %} +``` json-doc +{ "type": "Image" } +``` + +##### format + +The specific media type (often called a MIME type) for a content resource, for example `image/jpeg`. This is important for distinguishing different formats of the same overall type of resource, such as distinguishing text in XML from plain text. + +Note that this is different to the `formats` property in the [Image API][image-api], which gives the extension to use within that API. It would be inappropriate to use in this case, as `format` can be used with any content resource, not just images. + +The value _MUST_ be a string, and it _SHOULD_ be the value of the `Content-Type` header returned when the resource is dereferenced. + + * A content resource _SHOULD_ have the `format` property.
+ Clients _MAY_ render the `format` of any content resource. + * Other types of resource _MUST NOT_ have the `format` property.
+ Clients _SHOULD_ ignore `format` on other types of resource. + +{% include api/code_header.html %} +``` json-doc +{ "format": "application/xml" } +``` + +##### language + +The language or languages used in the content of this external resource. This property is already available from the Web Annotation model for content resources that are the body or target of an Annotation, however it _MAY_ also be used for resources [referenced][prezi30-terminology] from `homepage`, `rendering`, and `partOf`. + +The value _MUST_ be an array of strings. Each item in the array _MUST_ be a valid language code, as described in the [languages section][prezi30-languages]. + + * An external resource _SHOULD_ have the `language` property with at least one item.
+ Clients _SHOULD_ process the `language` of external resources. + * Other types of resource _MUST NOT_ have the `language` property.
+ Clients _SHOULD_ ignore `language` on other types of resource. + +{% include api/code_header.html %} +``` json-doc +{ "language": [ "en" ] } +``` + +##### profile + +A schema or named set of functionality available from the resource. The profile can further clarify the `type` and/or `format` of an external resource or service, allowing clients to customize their handling of the resource that has the `profile` property. + +The value _MUST_ be a string, either taken from the [profiles registry][registry-profiles] or a URI. + +* Resources [referenced][prezi30-terminology] by the `seeAlso` or `service` properties _SHOULD_ have the `profile` property.
+ Clients _SHOULD_ process the `profile` of a service or external resource. +* Other types of resource _MAY_ have the `profile` property.
+ Clients _MAY_ process the `profile` of other types of resource. + +{% include api/code_header.html %} +``` json-doc +{ "profile": "https://example.org/profile/statuary" } +``` + +##### height + +The height of the Canvas or external content resource. For content resources, the value is in pixels. For Canvases, the value does not have a unit. In combination with the width, it conveys an aspect ratio for the space in which content resources are located. + +The value _MUST_ be a positive integer. + + * A Canvas _MAY_ have the `height` property. If it has a `height`, it _MUST_ also have a `width`.
+ Clients _MUST_ process `height` on a Canvas. + * Content resources _SHOULD_ have the `height` property, with the value given in pixels, if appropriate to the resource type.
+ Clients _SHOULD_ process `height` on content resources. + * Other types of resource _MUST NOT_ have the `height` property.
+ Clients _SHOULD_ ignore `height` on other types of resource. + +{% include api/code_header.html %} +``` json-doc +{ "height": 1800 } +``` + +##### width + +The width of the Canvas or external content resource. For content resources, the value is in pixels. For Canvases, the value does not have a unit. In combination with the height, it conveys an aspect ratio for the space in which content resources are located. + +The value _MUST_ be a positive integer. + + * A Canvas _MAY_ have the `width` property. If it has a `width`, it _MUST_ also have a `height`.
+ Clients _MUST_ process `width` on a Canvas. + * Content resources _SHOULD_ have the `width` property, with the value given in pixels, if appropriate to the resource type.
+ Clients _SHOULD_ process `width` on content resources. + * Other types of resource _MUST NOT_ have the `width` property.
+ Clients _SHOULD_ ignore `width` on other types of resource. + +{% include api/code_header.html %} +``` json-doc +{ "width": 1200 } +``` + +##### duration + +The duration of the Canvas or external content resource, given in seconds. + +The value _MUST_ be a positive floating point number. + + * A Canvas _MAY_ have the `duration` property.
+ Clients _MUST_ process `duration` on a Canvas. + * Content resources _SHOULD_ have the `duration` property, if appropriate to the resource type.
+ Clients _SHOULD_ process `duration` on content resources. + * Other types of resource _MUST NOT_ have a `duration`.
+ Clients _SHOULD_ ignore `duration` on other types of resource. + +{% include api/code_header.html %} +``` json-doc +{ "duration": 125.0 } +``` + +##### viewingDirection + +The direction in which a set of Canvases _SHOULD_ be displayed to the user. This specification defines four direction values in the table below. Others may be defined externally [as an extension][prezi30-ldce]. + +The value _MUST_ be a string. + + * A Collection _MAY_ have the `viewingDirection` property.
+ Clients _SHOULD_ process `viewingDirection` on a Collection. + * A Manifest _MAY_ have the `viewingDirection` property.
+ Clients _SHOULD_ process `viewingDirection` on a Manifest. + * A Range _MAY_ have the `viewingDirection` property.
+ Clients _MAY_ process `viewingDirection` on a Range. + * Other types of resource _MUST NOT_ have the `viewingDirection` property.
+ Clients _SHOULD_ ignore `viewingDirection` on other types of resource. + +| Value | Description | +| ----- | ----------- | +| `left-to-right` | The object is displayed from left to right. The default if not specified. | +| `right-to-left` | The object is displayed from right to left. | +| `top-to-bottom` | The object is displayed from the top to the bottom. | +| `bottom-to-top` | The object is displayed from the bottom to the top. | +{: .api-table #table-direction} + +{% include api/code_header.html %} +``` json-doc +{ "viewingDirection": "left-to-right" } +``` + +##### behavior + +A set of user experience features that the publisher of the content would prefer the client to use when presenting the resource. This specification defines the values in the table below. Others may be defined externally as an [extension][prezi30-ldce]. + +In order to determine the behaviors that are governing a particular resource, there are four inheritance rules from resources that reference the current resource: +* Collections inherit behaviors from their referencing Collection. +* Manifests **DO NOT** inherit behaviors from any referencing Collections. +* Canvases inherit behaviors from their referencing Manifest, but **DO NOT** inherit behaviors from any referencing Ranges, as there might be several with different behaviors. +* Ranges inherit behaviors from any referencing Range and referencing Manifest. + +Clients should interpret behaviors on a Range only when that Range is selected or is in some other way the context for the user's current interaction with the resources. A Range with the `behavior` value `continuous`, in a Manifest with the `behavior` value `paged`, would mean that the Manifest's Canvases should be rendered in a paged fashion, unless the range is selected to be viewed, and its included Canvases would be rendered in that context only as being virtually stitched together. This might occur, for example, when a physical scroll is cut into pages and bound into a codex with other pages, and the publisher would like to provide the user the experience of the scroll in its original form. + +The descriptions of the behavior values have a set of which other values they are disjoint with, meaning that the same resource _MUST NOT_ have both of two or more from that set. In order to determine which is in effect, the client _SHOULD_ follow the inheritance rules above, taking the value from the closest resource. The user interface effects of the possible permutations of non-disjoint behavior values are client dependent, and implementers are advised to look for relevant recipes in the [IIIF cookbook][annex-cookbook]. + +__Future Clarification Anticipated__
+Further clarifications about the implications of interactions between behavior values should be expected in subsequent minor releases. +{: .warning} + +The value _MUST_ be an array of strings. + + * Any resource type _MAY_ have the `behavior` property with at least one item.
+ Clients _SHOULD_ process `behavior` on any resource type. + +| Value | Description | +| ----- | ----------- | +|| **Temporal Behaviors** | +| `auto-advance`{: style="white-space:nowrap;"} | Valid on Collections, Manifests, Canvases, and Ranges that include or are Canvases with at least the `duration` dimension. When the client reaches the end of a Canvas, or segment thereof as specified in a Range, with a duration dimension that has this behavior, it _SHOULD_ immediately proceed to the next Canvas or segment and render it. If there is no subsequent Canvas in the current context, then this behavior should be ignored. When applied to a Collection, the client should treat the first Canvas of the next Manifest as following the last Canvas of the previous Manifest, respecting any `start` property specified. Disjoint with `no-auto-advance`. | +| `no-auto-advance`{: style="white-space:nowrap;"} | Valid on Collections, Manifests, Canvases, and Ranges that include or are Canvases with at least the `duration` dimension. When the client reaches the end of a Canvas or segment with a duration dimension that has this behavior, it _MUST NOT_ proceed to the next Canvas, if any. This is a default temporal behavior if not specified. Disjoint with `auto-advance`.| +| `repeat` | Valid on Collections and Manifests, that include Canvases that have at least the `duration` dimension. When the client reaches the end of the duration of the final Canvas in the resource, and the `behavior` value `auto-advance`{: style="white-space:nowrap;"} is also in effect, then the client _SHOULD_ return to the first Canvas, or segment of Canvas, in the resource that has the `behavior` value `repeat` and start playing again. If the `behavior` value `auto-advance` is not in effect, then the client _SHOULD_ render a navigation control for the user to manually return to the first Canvas or segment. Disjoint with `no-repeat`.| +| `no-repeat` | Valid on Collections and Manifests, that include Canvases that have at least the `duration` dimension. When the client reaches the end of the duration of the final Canvas in the resource, the client _MUST NOT_ return to the first Canvas, or segment of Canvas. This is a default temporal behavior if not specified. Disjoint with `repeat`.| +| | **Layout Behaviors** | +| `unordered` | Valid on Collections, Manifests and Ranges. The Canvases included in resources that have this behavior have no inherent order, and user interfaces _SHOULD_ avoid implying an order to the user. Disjoint with `individuals`, `continuous`, and `paged`.| +| `individuals` | Valid on Collections, Manifests, and Ranges. For Collections that have this behavior, each of the included Manifests are distinct objects in the given order. For Manifests and Ranges, the included Canvases are distinct views, and _SHOULD NOT_ be presented in a page-turning interface. This is the default layout behavior if not specified. Disjoint with `unordered`, `continuous`, and `paged`. | +| `continuous` | Valid on Collections, Manifests and Ranges, which include Canvases that have at least `height` and `width` dimensions. Canvases included in resources that have this behavior are partial views and an appropriate rendering might display all of the Canvases virtually stitched together, such as a long scroll split into sections. This behavior has no implication for audio resources. The `viewingDirection` of the Manifest will determine the appropriate arrangement of the Canvases. Disjoint with `unordered`, `individuals` and `paged`. | +| `paged` | Valid on Collections, Manifests and Ranges, which include Canvases that have at least `height` and `width` dimensions. Canvases included in resources that have this behavior represent views that _SHOULD_ be presented in a page-turning interface if one is available. The first canvas is a single view (the first recto) and thus the second canvas likely represents the back of the object in the first canvas. If this is not the case, see the `behavior` value `non-paged`. Disjoint with `unordered`, `individuals`, `continuous`, `facing-pages` and `non-paged`. | +| `facing-pages`{: style="white-space:nowrap;"} | Valid only on Canvases, where the Canvas has at least `height` and `width` dimensions. Canvases that have this behavior, in a Manifest that has the `behavior` value `paged`, _MUST_ be displayed by themselves, as they depict both parts of the opening. If all of the Canvases are like this, then page turning is not possible, so simply use `individuals` instead. Disjoint with `paged` and `non-paged`.| +| `non-paged` | Valid only on Canvases, where the Canvas has at least `height` and `width` dimensions. Canvases that have this behavior _MUST NOT_ be presented in a page turning interface, and _MUST_ be skipped over when determining the page order. This behavior _MUST_ be ignored if the current Manifest does not have the `behavior` value `paged`. Disjoint with `paged` and `facing-pages`. | +| | **Collection Behaviors** | +| `multi-part` | Valid only on Collections. Collections that have this behavior consist of multiple Manifests or Collections which together form part of a logical whole or a contiguous set, such as multi-volume books or a set of journal issues. Clients might render these Collections as a table of contents rather than with thumbnails, or provide viewing interfaces that can easily advance from one member to the next. Disjoint with `together`.| +| `together` | Valid only on Collections. A client _SHOULD_ present all of the child Manifests to the user at once in a separate viewing area with its own controls. Clients _SHOULD_ catch attempts to create too many viewing areas. This behavior _SHOULD NOT_ be interpreted as applying to the members of any child resources. Disjoint with `multi-part`.| +| | **Range Behaviors** | +| `sequence` | Valid only on Ranges, where the Range is [referenced][prezi30-terminology] in the `structures` property of a Manifest. Ranges that have this behavior represent different orderings of the Canvases listed in the `items` property of the Manifest, and user interfaces that interact with this order _SHOULD_ use the order within the selected Range, rather than the default order of `items`. 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` | Valid on Annotation Collections, Annotation Pages, Annotations, Specific Resources 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. | +{: .api-table #table-behavior} + +{% include api/code_header.html %} +``` json-doc +{ "behavior": [ "auto-advance", "individuals" ] } +``` + +##### timeMode + +A mode associated with an Annotation that is to be applied to the rendering of any time-based media, or otherwise could be considered to have a duration, used as a body resource of that Annotation. Note that the association of `timeMode` with the Annotation means that different resources in the body cannot have different values. This specification defines the values specified in the table below. Others may be defined externally as an [extension][prezi30-ldce]. + +The value _MUST_ be a string. + + * An Annotation _MAY_ have the `timeMode` property.
+ Clients _SHOULD_ process `timeMode` on an Annotation. + +| Value | Description | +| ----- | ----------- | +| `trim` | (default, if not supplied) If the content resource has a longer duration than the duration of portion of the Canvas it is associated with, then at the end of the Canvas's duration, the playback of the content resource _MUST_ also end. If the content resource has a shorter duration than the duration of the portion of the Canvas it is associated with, then, for video resources, the last frame _SHOULD_ persist on-screen until the end of the Canvas portion's duration. For example, a video of 120 seconds annotated to a Canvas with a duration of 100 seconds would play only the first 100 seconds and drop the last 20 second. | +| `scale` | Fit the duration of content resource to the duration of the portion of the Canvas it is associated with by scaling. For example, a video of 120 seconds annotated to a Canvas with a duration of 60 seconds would be played at double-speed. | +| `loop` | If the content resource is shorter than the `duration` of the Canvas, it _MUST_ be repeated to fill the entire duration. Resources longer than the `duration` _MUST_ be trimmed as described above. For example, if a 20 second duration audio stream is annotated onto a Canvas with duration 30 seconds, it will be played one and a half times. | +{: .api-table #table-timemode} + +{% include api/code_header.html %} +``` json-doc +{ "timeMode": "trim" } +``` + #### backgroundColor This property sets the background color behind any painted resources on a spatial resource, such as a Canvas or Scene. @@ -163,27 +698,424 @@ The value of this property is an array of JSON objects, each of which is a Trans ##### z +### Linking Properties + + +##### homepage + +A web page that is about the object represented by the resource that has the `homepage` property. The web page is usually published by the organization responsible for the object, and might be generated by a content management system or other cataloging system. The resource _MUST_ be able to be displayed directly to the user. Resources that are related, but not home pages, _MUST_ instead be added into the `metadata` property, with an appropriate `label` or `value` to describe the relationship. + +The value of this property _MUST_ be an array of JSON objects, each of which _MUST_ have the `id`, `type`, and `label` properties, _SHOULD_ have a `format` property, and _MAY_ have the `language` property. + + * Any resource type _MAY_ have the `homepage` property.
+ Clients _SHOULD_ render `homepage` on a Collection, Manifest or Canvas, and _MAY_ render `homepage` on other types of resource. + +__Model Alignment__
+Please note that this specification has stricter requirements about the JSON pattern used for the `homepage` property than the [Web Annotation Data Model][org-w3c-webanno]. The IIIF requirements are compatible, but the home page of an Agent found might have only a URI, or might be a JSON object with other properties. See the section on [collisions between contexts][prezi30-context-collisions] for more information. +{: .note} + +{% include api/code_header.html %} +``` json-doc +{ + "homepage": [ + { + "id": "https://example.com/info/", + "type": "Text", + "label": { "en": [ "Homepage for Example Object" ] }, + "format": "text/html", + "language": [ "en" ] + } + ] +} +``` + + +##### logo + +A small image resource that represents the Agent resource it is associated with. The logo _MUST_ be clearly rendered when the resource is displayed or used, without cropping, rotating or otherwise distorting the image. It is _RECOMMENDED_ that a [IIIF Image API][image-api] service be available for this image for other manipulations such as resizing. + +When more than one logo is present, the client _SHOULD_ pick only one of them, based on the information in the logo properties. For example, the client could select a logo of appropriate aspect ratio based on the `height` and `width` properties of the available logos. The client _MAY_ decide on the logo by inspecting properties defined as [extensions][prezi30-ldce]. + +The value of this property _MUST_ be an array of JSON objects, each of which _MUST_ have `id` and `type` properties, and _SHOULD_ have `format`. The value of `type` _MUST_ be "Image". + + * Agent resources _SHOULD_ have the `logo` property.
+ Clients _MUST_ render `logo` on Agent resources. + + +{% include api/code_header.html %} +``` json-doc +{ + "logo": [ + { + "id": "https://example.org/img/logo.jpg", + "type": "Image", + "format": "image/jpeg", + "height": 100, + "width": 120 + } + ] +} +``` + +##### rendering + +A resource that is an alternative, non-IIIF representation of the resource that has the `rendering` property. Such representations typically cannot be painted onto a single Canvas, as they either include too many views, have incompatible dimensions, or are compound resources requiring additional rendering functionality. The `rendering` resource _MUST_ be able to be displayed directly to a human user, although the presentation may be outside of the IIIF client. The resource _MUST NOT_ have a splash page or other interstitial resource that mediates access to it. If access control is required, then the [IIIF Authentication API][iiif-auth] is _RECOMMENDED_. Examples include a rendering of a book as a PDF or EPUB, a slide deck with images of a building, or a 3D model of a statue. + +The value _MUST_ be an array of JSON objects. Each item _MUST_ have the `id`, `type` and `label` properties, and _SHOULD_ have a `format` property. + + * Any resource type _MAY_ have the `rendering` property with at least one item.
+ Clients _SHOULD_ render `rendering` on a Collection, Manifest or Canvas, and _MAY_ render `rendering` on other types of resource. + +{% include api/code_header.html %} +``` json-doc +{ + "rendering": [ + { + "id": "https://example.org/1.pdf", + "type": "Text", + "label": { "en": [ "PDF Rendering of Book" ] }, + "format": "application/pdf" + } + ] +} +``` + +##### service + +A service that the client might interact with directly and gain additional information or functionality for using the resource that has the `service` property, such as from an Image to the base URI of an associated [IIIF Image API][image-api] service. The service resource _SHOULD_ have additional information associated with it in order to allow the client to determine how to make appropriate use of it. Please see the [Service Registry][registry-services] document for the details of currently known service types. + +The value _MUST_ be an array of JSON objects. Each object will have properties depending on the service's definition, but _MUST_ have either the `id` or `@id` and `type` or `@type` properties. Each object _SHOULD_ have a `profile` property. + + * Any resource type _MAY_ have the `service` property with at least one item.
+ Clients _MAY_ process `service` on any resource type, and _SHOULD_ process the IIIF Image API service. + +{% include api/code_header.html %} +``` json-doc +{ + "service": [ + { + "id": "https://example.org/service", + "type": "ExampleExtensionService", + "profile": "https://example.org/docs/service" + } + ] +} +``` + +For cross-version consistency, this specification defines the following values for the `type` or `@type` property for backwards compatibility with other IIIF APIs. Future versions of these APIs will define their own types. These `type` values are necessary extensions for compatibility of the older versions. + +| Value | Specification | +| -------------------- | ------------- | +| ImageService1 | [Image API version 1][image11] | +| ImageService2 | [Image API version 2][image21] | +| SearchService1 | [Search API version 1][search1] | +| AutoCompleteService1 | [Search API version 1][search1-autocomplete] | +| AuthCookieService1 | [Authentication API version 1][auth1-cookie-service] | +| AuthTokenService1 | [Authentication API version 1][auth1-token-service] | +| AuthLogoutService1 | [Authentication API version 1][auth1-logout-service] | +{: .api-table #table-service-types} + +Implementations _SHOULD_ be prepared to recognize the `@id` and `@type` property names used by older specifications, as well as `id` and `type`. Note that the `@context` key _SHOULD NOT_ be present within the `service`, but instead included at the beginning of the document. The example below includes both version 2 and version 3 IIIF Image API services. + +{% include api/code_header.html %} +``` json-doc +{ + "service": [ + { + "@id": "https://example.org/iiif2/image1/identifier", + "@type": "ImageService2", + "profile": "http://iiif.io/api/image/2/level2.json" + }, + { + "id": "https://example.org/iiif3/image1/identifier", + "type": "ImageService3", + "profile": "level2" + } + ] +} +``` + + +##### services + +A list of one or more service definitions on the top-most resource of the document, that are typically shared by more than one subsequent resource. This allows for these shared services to be collected together in a single place, rather than either having their information duplicated potentially many times throughout the document, or requiring a consuming client to traverse the entire document structure to find the information. The resource that the service applies to _MUST_ still have the `service` property, as described above, where the service resources have at least the `id` and `type` or `@id` and `@type` properties. This allows the client to know that the service applies to that resource. Usage of the `services` property is at the discretion of the publishing system. + +A client encountering a `service` property where the definition consists only of an `id` and `type` _SHOULD_ then check the `services` property on the top-most resource for an expanded definition. If the service is not present in the `services` list, and the client requires more information in order to use the service, then it _SHOULD_ dereference the `id` (or `@id`) of the service in order to retrieve a service description. + +The value _MUST_ be an array of JSON objects. Each object _MUST_ a service resource, as described above. + +* A Collection _MAY_ have the `services` property, if it is the topmost Collection in a response document.
+ Clients _SHOULD_ process `services` on a Collection. +* A Manifest _MAY_ have the `services` property.
+ Clients _SHOULD_ process `services` on a Manifest. + +{% include api/code_header.html %} +``` json-doc +{ + "services": [ + { + "@id": "https://example.org/iiif/auth/login", + "@type": "AuthCookieService1", + "profile": "http://iiif.io/api/auth/1/login", + "label": "Login to Example Institution", + "service": [ + { + "@id": "https://example.org/iiif/auth/token", + "@type": "AuthTokenService1", + "profile": "http://iiif.io/api/auth/1/token" + } + ] + } + ] +} +``` + + +##### seeAlso + +A machine-readable resource such as an XML or RDF description that is related to the current resource that has the `seeAlso` property. Properties of the resource should be given to help the client select between multiple descriptions (if provided), and to make appropriate use of the document. If the relationship between the resource and the document needs to be more specific, then the document should include that relationship rather than the IIIF resource. Other IIIF resources are also valid targets for `seeAlso`, for example to link to a Manifest that describes a related object. The URI of the document _MUST_ identify a single representation of the data in a particular format. For example, if the same data exists in JSON and XML, then separate resources should be added for each representation, with distinct `id` and `format` properties. + +The value _MUST_ be an array of JSON objects. Each item _MUST_ have the `id` and `type` properties, and _SHOULD_ have the `label`, `format` and `profile` properties. + + * Any resource type _MAY_ have the `seeAlso` property with at least one item.
+ Clients _MAY_ process `seeAlso` on any resource type. + +{% include api/code_header.html %} +``` json-doc +{ + "seeAlso": [ + { + "id": "https://example.org/library/catalog/book1.xml", + "type": "Dataset", + "label": { "en": [ "Bibliographic Description in XML" ] }, + "format": "text/xml", + "profile": "https://example.org/profiles/bibliographic" + } + ] +} +``` + +#### 3.3.2. Internal Links + +##### partOf + +A containing resource that includes the resource that has the `partOf` property. When a client encounters the `partOf` property, it might retrieve the [referenced][prezi30-terminology] containing resource, if it is not [embedded][prezi30-terminology] in the current representation, in order to contribute to the processing of the contained resource. For example, the `partOf` property on a Canvas can be used to reference an external Manifest in order to enable the discovery of further relevant information. Similarly, a Manifest can reference a containing Collection using `partOf` to aid in navigation. + +The value _MUST_ be an array of JSON objects. Each item _MUST_ have the `id` and `type` properties, and _SHOULD_ have the `label` property. + + * Any resource type _MAY_ have the `partOf` property with at least one item
+ Clients _MAY_ render `partOf` on any resource type. + +{% include api/code_header.html %} +``` json-doc +{ "partOf": [ { "id": "https://example.org/iiif/1", "type": "Manifest" } ] } +``` + +##### start + +A Canvas, or part of a Canvas, which the client _SHOULD_ show on initialization for the resource that has the `start` property. The reference to part of a Canvas is handled in the same way that Ranges reference parts of Canvases. This property allows the client to begin with the first Canvas that contains interesting content rather than requiring the user to manually navigate to find it. + +The value _MUST_ be a JSON object, which _MUST_ have the `id` and `type` properties. The object _MUST_ be either a Canvas (as in the first example below), or a Specific Resource with a Selector and a `source` property where the value is a Canvas (as in the second example below). + + * A Manifest _MAY_ have the `start` property.
+ Clients _SHOULD_ process `start` on a Manifest. + * A Range _MAY_ have the `start` property.
+ Clients _SHOULD_ process `start` on a Range. + * Other types of resource _MUST NOT_ have the `start` property.
+ Clients _SHOULD_ ignore `start` on other types of resource. + +{% include api/code_header.html %} +``` json-doc +{ "start": { "id": "https://example.org/iiif/1/canvas/1", "type": "Canvas" } } +``` + +{% include api/code_header.html %} +``` json-doc +{ + "start": { + "id": "https://example.org/iiif/1/canvas-segment/1", + "type": "SpecificResource", + "source": "https://example.org/iiif/1/canvas/1", + "selector": { + "type": "PointSelector", + "t": 14.5 + } + } +} +``` + +##### supplementary + +A link from this Range to an Annotation Collection that includes the `supplementing` Annotations of content resources for the Range. Clients might use this to present additional content to the user from a different Canvas when interacting with the Range, or to jump to the next part of the Range within the same Canvas. For example, the Range might represent a newspaper article that spans non-sequential pages, and then uses the `supplementary` property to reference an Annotation Collection that consists of the Annotations that record the text, split into Annotation Pages per newspaper page. Alternatively, the Range might represent the parts of a manuscript that have been transcribed or translated, when there are other parts that have yet to be worked on. The Annotation Collection would be the Annotations that transcribe or translate, respectively. + +The value _MUST_ be a JSON object, which _MUST_ have the `id` and `type` properties, and the `type` _MUST_ be `AnnotationCollection`. + + * A Range _MAY_ have the `supplementary` property.
+ Clients _MAY_ process `supplementary` on a Range. + * Other types of resource _MUST NOT_ have the `supplementary` property.
+ Clients _SHOULD_ ignore `supplementary` on other types of resource. + +{% include api/code_header.html %} +``` json-doc +{ "supplementary": { "id": "https://example.org/iiif/1/annos/1", "type": "AnnotationCollection" } } +``` ### Structural Properties -### Values +##### items + +Much of the functionality of the IIIF Presentation API is simply recording the order in which child resources occur within a parent resource, such as Collections or Manifests within a parent Collection, or Canvases within a Manifest. All of these situations are covered with a single property, `items`. + +The value _MUST_ be an array of JSON objects. Each item _MUST_ have the `id` and `type` properties. The items will be resources of different types, as described below. + + * A Collection _MUST_ have the `items` property. Each item _MUST_ be either a Collection or a Manifest.
+ Clients _MUST_ process `items` on a Collection. + * A Manifest _MUST_ have the `items` property with at least one item. Each item _MUST_ be a Canvas.
+ Clients _MUST_ process `items` on a Manifest. + * A Canvas _SHOULD_ have the `items` property with at least one item. Each item _MUST_ be an Annotation Page.
+ Clients _MUST_ process `items` on a Canvas. + * An Annotation Page _SHOULD_ have the `items` property with at least one item. Each item _MUST_ be an Annotation.
+ Clients _MUST_ process `items` on an Annotation Page. + * A Range _MUST_ have the `items` property with at least one item. Each item _MUST_ be a Range, a Canvas or a Specific Resource where the source is a Canvas.
+ Clients _SHOULD_ process `items` on a Range. + * Other types of resource _MUST NOT_ have the `items` property.
+ Clients _SHOULD_ ignore `items` on other types of resource. + +{% include api/code_header.html %} +``` json-doc +{ + "items": [ + { + "id": "https://example.org/iiif/manifest1", + "type": "Manifest" + }, + { + "id": "https://example.org/iiif/collection1", + "type": "Collection" + } + // ... + ] +} +``` + +##### structures + +The structure of an object represented as a Manifest can be described using a hierarchy of Ranges. Ranges can be used to describe the "table of contents" of the object or other structures that the user can interact with beyond the order given by the `items` property of the Manifest. The hierarchy is built by nesting the child Range resources in the `items` array of the higher level Range. The top level Ranges of these hierarchies are given in the `structures` property. + +The value _MUST_ be an array of JSON objects. Each item _MUST_ have the `id` and `type` properties, and the `type` _MUST_ be `Range`. + + * A Manifest _MAY_ have the `structures` property.
+ Clients _SHOULD_ process `structures` on a Manifest. The first hierarchy _SHOULD_ be presented to the user by default, and further hierarchies _SHOULD_ be able to be selected as alternative structures by the user. + * Other types of resource _MUST NOT_ have the `structures` property.
+ Clients _SHOULD_ ignore `structures` on other types of resource. + +{% include api/code_header.html %} +``` json-doc +{ + "structures": [ + { + "id": "https://example.org/iiif/range/1", + "type": "Range", + "items": [ { ... } ] + } + ] +} +``` + +##### annotations + +An ordered list of Annotation Pages that contain commentary or other Annotations about this resource, separate from the Annotations that are used to paint content on to a Canvas. The `motivation` of the Annotations _MUST NOT_ be `painting`, and the target of the Annotations _MUST_ include this resource or part of it. + +The value _MUST_ be an array of JSON objects. Each item _MUST_ have at least the `id` and `type` properties. + + * A Collection _MAY_ have the `annotations` property with at least one item.
+ Clients _SHOULD_ process `annotations` on a Collection. + * A Manifest _MAY_ have the `annotations` property with at least one item.
+ Clients _SHOULD_ process `annotations` on a Manifest,. + * A Canvas _MAY_ have the `annotations` property with at least one item.
+ Clients _SHOULD_ process `annotations` on a Canvas. + * A Range _MAY_ have the `annotations` property with at least one item.
+ Clients _SHOULD_ process `annotations` on a Range. + * A content resource _MAY_ have the `annotations` property with at least one item.
+ Clients _SHOULD_ process `annotations` on a content resource. + * Other types of resource _MUST NOT_ have the `annotations` property.
+ Clients _SHOULD_ ignore `annotations` on other types of resource. + +{% include api/code_header.html %} +``` json-doc +{ + "annotations": [ + { + "id": "https://example.org/iiif/annotationPage/1", + "type": "AnnotationPage", + "items": [ { ... } ] + } + ] +} +``` + +### 3.5. Values + +##### Values for motivation + +This specification defines two values for the Web Annotation property of `motivation`, or `purpose` when used on a Specific Resource or Textual Body. + +While any resource _MAY_ be the `target` of an Annotation, this specification defines only motivations for Annotations that target Canvases. These motivations allow clients to determine how the Annotation should be rendered, by distinguishing between Annotations that provide the content of the Canvas, from ones with externally defined motivations which are typically comments about the Canvas. + +Additional motivations may be added to the Annotation to further clarify the intent, drawn from [extensions][prezi30-ldce] or other sources. Clients _MUST_ ignore motivation values that they do not understand. Other motivation values given in the Web Annotation specification _SHOULD_ be used where appropriate, and examples are given in the [Presentation API Cookbook][annex-cookbook]. + +| Value | Description | +| ----- | ----------- | +| `painting` | Resources associated with a Canvas by an Annotation that has the `motivation` value `painting` _MUST_ be presented to the user as the representation of the Canvas. The content can be thought of as being _of_ the Canvas. The use of this motivation with target resources other than Canvases is undefined. For example, an Annotation that has the `motivation` value `painting`, a body of an Image and the target of the 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 Canvas and not positioned in some other part of the user interface.| +| `supplementing` | Resources associated with a Canvas by an Annotation that has the `motivation` value `supplementing` _MAY_ be presented to the user as part of the representation of the Canvas, or _MAY_ be presented in a different part of the user interface. The content can be thought of as being _from_ the Canvas. The use of this motivation with target resources other than Canvases is undefined. For example, an Annotation that has the `motivation` value `supplementing`, a body of an Image and the target of part of the 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 Canvas 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 Canvas with audio content. | +{: .api-table #table-motivations} + + + + +The top level resource in the response _MUST_ have the `@context` property, and it _SHOULD_ appear as the very first key/value pair of the JSON representation. This tells Linked Data processors how to interpret the document. The IIIF Presentation API context, below, _MUST_ occur once per response in the top-most resource, and thus _MUST NOT_ appear within [embedded][prezi30-terminology] resources. For example, when embedding a Canvas within a Manifest, the Canvas will not have the `@context` property. + +The value of the `@context` property _MUST_ be either the URI `http://iiif.io/api/presentation/{{ page.major }}/context.json` or a JSON array with the URI `http://iiif.io/api/presentation/{{ page.major }}/context.json` as the last item. Further contexts, such as those for local or [registered extensions][registry], _MUST_ be added at the beginning of the array. + +{% include api/code_header.html %} +``` json-doc +{ + "@context": "http://iiif.io/api/presentation/{{ page.major }}/context.json" +} +``` + +Any additional properties beyond those defined in this specification or the Web Annotation Data Model _SHOULD_ be mapped to RDF predicates using further context documents. These extensions _SHOULD_ be added to the top level `@context` property, and _MUST_ be added before the above context. The JSON-LD 1.1 functionality of predicate specific context definitions, known as [scoped contexts][org-w3c-json-ld-scoped-contexts], _MUST_ be used to minimize cross-extension collisions. Extensions intended for community use _SHOULD_ be [registered in the extensions registry][registry], but registration is not mandatory. + +{% include api/code_header.html %} +``` json-doc +{ + "@context": [ + "http://example.org/extension/context.json", + "http://iiif.io/api/presentation/{{ page.major }}/context.json" + ] +} +``` +The JSON representation _MUST NOT_ include the `@graph` key at the top level. This key might be created when serializing directly from RDF data using the JSON-LD 1.0 compaction algorithm. Instead, JSON-LD framing and/or custom code should be used to ensure the structure of the document is as defined by this specification. -## JSON-LD Considerations +### 4.7. Term Collisions between Contexts -### Case Sensitivity +There are some common terms used in more than one JSON-LD context document. Every attempt has been made to minimize these collisions, but some are inevitable. In order to know which specification is in effect at any given point, the class of the resource that has the property is the primary governing factor. Thus properties on Annotation based resources use the context from the [Web Annotation Data Model][org-w3c-webanno], whereas properties on classes defined by this specification use the IIIF Presentation API context's definition. -### Resource Representations +There is one property that is in direct conflict - the `label` property is defined by both and is available for every resource. The use of `label` in IIIF follows modern best practices for internationalization by allowing the language to be associated with the value using the language map construction [described above][prezi30-languages]. The Web Annotation Data Model uses it only for [Annotation Collections][prezi30-annocoll], and mandates the format is a string. For this property, the API overrides the definition from the Annotation model to ensure that labels can consistently be represented in multiple languages. -### Properties with Multiple Values +The following properties are defined by both, and the IIIF representation is more specific than the Web Annotation Data Model but are not in conflict, or are never used on the same resource: -### Language of Property Values +* `homepage`: In IIIF the home page of a resource is represented as a JSON object, whereas in the Web Annotation Data Model it can also be a string. +* `type`: In IIIF the type is singular, whereas in the Web Annotation Data Model there can be more than one type. +* `format`: In IIIF the format of a resource is also singular, whereas in the Web Annotation Data Model there can be more than one format. +* `language`: In IIIF the `language` property always takes an array, whereas in the Web Annotation Data Model it can be a single string. +* `start`: The `start` property is used on a Manifest to refer to the start Canvas or part of a Canvas and thus is a JSON object, whereas in the Web Annotation Data Model it is used on a TextPositionSelector to give the start offset into the textual content and is thus an integer. -### HTML Markup in Property Values +The `rights`, `partOf`, and `items` properties are defined by both in the same way. -### Linked Data Context and Extensions +### 4.8. Keyword Mappings -### Term Collisions between Contexts +The JSON-LD keywords `@id`, `@type` and `@none` are mapped to `id`, `type` and `none` by the Presentation API [linked data context][prezi30-ldce]. Thus in content conforming to this version of the Presentation API, the only JSON key beginning with `@` will be `@context`. However, the content may include data conforming to older specifications or external specifications that use keywords beginning with `@`. Clients should expect to encounter both syntaxes. -### Keyword Mappings \ No newline at end of file From 2ab23a2d8d4ce3151b9cb570eaccc95813e8219c Mon Sep 17 00:00:00 2001 From: HackMD <37423+hackmd-hub[bot]@users.noreply.github.com> Date: Thu, 24 Oct 2024 14:16:17 +0000 Subject: [PATCH 006/130] last changed at Oct 24, 2024 3:18 PM, pushed by Julie Winchester --- source/presentation/4.0/index.md | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index fd8a73db0..aa7b92b89 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -5,12 +5,22 @@ Manifests, Containers, Annotations oh my! Manifest as unit of distribution - - ## Content Resources There is stuff that we want to show - images, video, audio, 3D models etc +### type value of Content Resources + +| Class | Description | +| ------------- | -------------------------------- | +| `Image` | Two dimensional visual resources primarily intended to be seen, such as might be rendered with an <img> HTML tag | +| `Model` | A three (or more) dimensional model intended to be interacted with by humans | +| `Sound` | Auditory resources primarily intended to be heard, such as might be rendered with an <audio> HTML tag | +| `Text` | Resources primarily intended to be read | +| `Video` | Moving images, with or without accompanying audio, such as might be rendered with a <video> HTML tag | +{: .api-table #table-type} + ## Containers This is where we put content resources @@ -22,6 +32,8 @@ And we can also put other things: And we can nest them "Nesting" (see 3d draft) +The defined Container types are `Timeline`, `Canvas` and `Scene`. Extensions may define additional Container types. + As multiple models, lights, cameras, and other resources can be associated with and placed within a Scene container, Scenes provide a straightforward way of grouping content resources together within a space. Scenes, as well as other IIIF containers such as Canvases, can also be embedded within a Scene, allowing for the nesting of content resources. A Scene or a Canvas may be treated as a content resource, referenced or described within the `body` of an Annotation. As with models and other resources, the Annotation is associated with a Scene into which the Scene or Canvas is to be nested through an Annotation `target`. The content resource Scene will be placed within the `target` Scene by aligning the coordinate origins of the two scenes. Alternately, Scene Annotations may use `PointSelector` to place the origin of the resource Scene at a specified coordinate within the `target` Scene. @@ -285,6 +297,12 @@ content state intended to: - modify the Container in a particular context (`scope`, storytelling) - contribute additional information permanently (rerum **inbox** - move to protocol doc) +### reset + +"diff", "original state" etc + +behavior for "force-order"? +behavior: sequence ## Selectors From 93b99dee022519b66dc38665ecdd7644c139c92f Mon Sep 17 00:00:00 2001 From: HackMD <37423+hackmd-hub[bot]@users.noreply.github.com> Date: Thu, 24 Oct 2024 15:30:29 +0000 Subject: [PATCH 007/130] last changed at Oct 24, 2024 4:30 PM, pushed by Julie Winchester --- source/presentation/4.0/properties.md | 199 ++++++++++++++++++++------ 1 file changed, 153 insertions(+), 46 deletions(-) diff --git a/source/presentation/4.0/properties.md b/source/presentation/4.0/properties.md index b41dcdfc9..41391fa6e 100644 --- a/source/presentation/4.0/properties.md +++ b/source/presentation/4.0/properties.md @@ -1,5 +1,52 @@ # Vocabulary? +## Resource Classes + +* Collection +* CollectionPage +* Manifest +* Containers + * Timeline + * Canvas + * Scene +* Content Resources +* Range +* Cameras + * PerspectiveCamera + * OrthographicCamera +* Lights + * AmbientLight + * DirectionalLight + * PointLight + * SpotLight +* Transforms + * TranslateTransform + * RotateTransform + * ScaleTransform +* Selectors + * PointSelector + * WktSelector (need both LineString Z and Polygon Z) + * AudioContentSelector + * VisualContentSelector + * AnimationSelector + * ImageApiSelector +* Other Classes + * Agent + * Service + * Value (used for `intensity`) + +* Annotation Classes imported from WADM: + * Annotation + * AnnotationCollection + * AnnotationPage + * SpecificResource + * FragmentSelector + * SvgSelector + * CssStyle + * TextualBody + * Choice + + ## Resource Properties ### Descriptive Properties @@ -14,10 +61,10 @@ The value of the property _MUST_ be a JSON object, as described in the [language Clients _MUST_ render `label` on a Collection. * A Manifest _MUST_ have the `label` property with at least one entry.
Clients _MUST_ render `label` on a Manifest. - * A Canvas _SHOULD_ have the `label` property with at least one entry.
- Clients _MUST_ render `label` on a Canvas, and _SHOULD_ generate a `label` for Canvases that do not have them. - * A content resource _MAY_ have the `label` property with at least one entry. If there is a Choice of content resource for the same Canvas, then they _SHOULD_ each have at least the `label` property with at least one entry.
- Clients _MAY_ render `label` on content resources, and _SHOULD_ render them when part of a Choice. + * All Container types _SHOULD_ have the `label` property with at least one entry.
+ Clients _MUST_ render `label` on Container types, and _SHOULD_ generate a `label` for Containers that do not have them. + * All Content Resource types _MAY_ have the `label` property with at least one entry. If there is a Choice of Content Resource for the same Container, then they _SHOULD_ each have the `label` property with at least one entry.
+ Clients _MAY_ render `label` on Content Resources, and _SHOULD_ render them when part of a Choice. * A Range _SHOULD_ have the `label` property with at least one entry.
Clients _MUST_ render `label` on a Range. * An Annotation Collection _SHOULD_ have the `label` property with at least one entry.
@@ -40,8 +87,8 @@ The value of the `metadata` property _MUST_ be an array of JSON objects, where e Clients _MUST_ render `metadata` on a Collection. * A Manifest _SHOULD_ have the `metadata` property with at least one item.
Clients _MUST_ render `metadata` on a Manifest. - * A Canvas _MAY_ have the `metadata` property with at least one item.
- Clients _SHOULD_ render `metadata` on a Canvas. + * All Container types _MAY_ have the `metadata` property with at least one item.
+ Clients _SHOULD_ render `metadata` on Containers. * Other types of resource _MAY_ have the `metadata` property with at least one item.
Clients _MAY_ render `metadata` on other types of resource. @@ -69,8 +116,8 @@ The value of the property _MUST_ be a JSON object, as described in the [language Clients _SHOULD_ render `summary` on a Collection. * A Manifest _SHOULD_ have the `summary` property with at least one entry.
Clients _SHOULD_ render `summary` on a Manifest. - * A Canvas _MAY_ have the `summary` property with at least one entry.
- Clients _SHOULD_ render `summary` on a Canvas. + * All Container types _MAY_ have the `summary` property with at least one entry.
+ Clients _SHOULD_ render `summary` on Containers. * Other types of resource _MAY_ have the `summary` property with at least one entry.
Clients _MAY_ render `summary` on other types of resource. @@ -125,7 +172,7 @@ An organization or person that contributed to providing the content of the resou The organization or person is represented as an `Agent` resource. * Agents _MUST_ have the `id` property, and its value _MUST_ be a string. The string _MUST_ be a URI that identifies the agent. -* Agents _MUST_ have the `type` property, and its value _MUST_ be the string "Agent". +* Agents _MUST_ have the `type` property, and its value _MUST_ be the string `Agent`. * Agents _MUST_ have the `label` property, and its value _MUST_ be a JSON object as described in the [languages][prezi30-languages] section. * Agents _SHOULD_ have the `homepage` property, and its value _MUST_ be an array of JSON objects as described in the [homepage][prezi30-homepage] section. * Agents _SHOULD_ have the `logo` property, and its value _MUST_ be an array of JSON objects as described in the [logo][prezi30-logo] section. @@ -188,9 +235,9 @@ The value _MUST_ be an array of JSON objects, each of which _MUST_ have the `id` Clients _SHOULD_ render `thumbnail` on a Collection. * A Manifest _SHOULD_ have the `thumbnail` property with at least one item.
Clients _SHOULD_ render `thumbnail` on a Manifest. - * A Canvas _MAY_ have the `thumbnail` property with at least one item. A Canvas _SHOULD_ have the `thumbnail` property if there are multiple resources that make up the view.
- Clients _SHOULD_ render `thumbnail` on a Canvas. - * A content resource _MAY_ have the `thumbnail` property with at least one item. Content resources _SHOULD_ have the `thumbnail` property with at least one item if it is an option in a Choice of resources.
+ * All Container types _SHOULD_ have the `thumbnail` property with at least one item.
+ Clients _SHOULD_ render `thumbnail` on Containers. + * Content Resource types _MAY_ have the `thumbnail` property with at least one item. Content Resources _SHOULD_ have the `thumbnail` property with at least one item if it is an option in a Choice of resources.
Clients _SHOULD_ render `thumbnail` on a content resource. * Other types of resource _MAY_ have the `thumbnail` property with at least one item.
Clients _MAY_ render `thumbnail` on other types of resource. @@ -222,8 +269,10 @@ The value _MUST_ be an [XSD dateTime literal][org-w3c-xsd-datetime]. The value _ Clients _MAY_ render `navDate` on a Manifest. * A Range _MAY_ have the `navDate` property.
Clients _MAY_ render `navDate` on a Range. - * A Canvas _MAY_ have the `navDate` property.
- Clients _MAY_ render `navDate` on a Canvas. + * All Container types _MAY_ have the `navDate` property.
+ Clients _MAY_ render `navDate` on Containers. +* Annotations _MAY_ have the `navDate` property. + Clients _MAY_ render `navDate` on Annotations. * Other types of resource _MUST NOT_ have the `navDate` property.
Clients _SHOULD_ ignore `navDate` on other types of resource. @@ -232,29 +281,77 @@ The value _MUST_ be an [XSD dateTime literal][org-w3c-xsd-datetime]. The value _ { "navDate": "2010-01-01T00:00:00Z" } ``` -##### placeholderCanvas +##### navPlace + +A geographic location that clients may use for navigation purposes when presenting the resource to the user in a map-based user interface. + +The value of the property _MUST_ be a [GeoJSON Feature Collection](link) containing one or more [Features](link). The value _SHOULD_ be embedded and _MAY_ be a reference. Feature Collections referenced in the `navPlace` property _MUST_ have the `id` and `type` properties and _MUST NOT_ have the `features` property. + +* A Collection _MAY_ have the `navPlace` property.
+ Clients _MAY_ render `navPlace` on a Collection. +* A Manifest _MAY_ have the `navPlace` property.
+ Clients _MAY_ render `navPlace` on a Manifest. +* A Range _MAY_ have the `navPlace` property.
+ Clients _MAY_ render `navPlace` on a Range. +* All Container types _MAY_ have the `navPlace` property.
+ Clients _MAY_ render `navPlace` on Containers. +* Annotations _MAY_ have the `navPlace` property. + Clients _MAY_ render `navPlace` on Annotations. +* Other types of resource _MUST NOT_ have the `navPlace` property.
+ Clients _SHOULD_ ignore `navPlace` on other types of resource. + + +{% include api/code_header.html %} +```json-doc +{ + "navPlace":{ + "id": "http://example.com/feature-collection/1", + "type": "FeatureCollection", + "features":[ + { + "id": "http://example.com/feature/1", + "type": "Feature", + "properties":{}, + "geometry":{ + "type": "Point", + "coordinates":[ + 9.938, + 51.533 + ] + } + } + ] + } +} +``` + + + -A single Canvas that provides additional content for use before the main content of the resource that has the `placeholderCanvas` property is rendered, or as an advertisement or stand-in for that content. Examples include images, text and sound standing in for video content before the user initiates playback; or a film poster to attract user attention. The content provided by `placeholderCanvas` differs from a thumbnail: a client might use `thumbnail` to summarize and navigate multiple resources, then show content from `placeholderCanvas` as part of the initial presentation of a single resource. A placeholder Canvas is likely to have different dimensions to those of the Canvas(es) of the resource that has the `placeholderCanvas` property. -Clients _MAY_ display the content of a linked placeholder Canvas when presenting the resource. When more than one such Canvas is available, for example if `placeholderCanvas` is provided for the currently selected Range and the current Manifest, the client _SHOULD_ pick the one most specific to the content. Publishers _SHOULD NOT_ assume that the placeholder Canvas will be processed by all clients. Clients _SHOULD_ take care to avoid conflicts between time-based media in the rendered placeholder Canvas and the content of the resource that has the `placeholderCanvas` property. +##### placeholderContainer -The value _MUST_ be a JSON object with the `id` and `type` properties, and _MAY_ have other properties of Canvases. The value of `type` _MUST_ be the string `Canvas`. The object _MUST NOT_ have the `placeholderCanvas` property, nor the `accompanyingCanvas` property. +A single Container that provides additional content for use before the main content of the resource that has the `placeholderContainer` property is rendered, or as an advertisement or stand-in for that content. Examples include images, text and sound standing in for video content before the user initiates playback; or a film poster to attract user attention. The content provided by `placeholderContainer` differs from a thumbnail: a client might use `thumbnail` to summarize and navigate multiple resources, then show content from `placeholderContainer` as part of the initial presentation of a single resource. A placeholder Container is likely to have different dimensions to those of the Container(s) of the resource that has the `placeholderContainer` property. A placeholder Container may be of a different type from the resource that has the `placeholderContainer` property. For example, a `Scene` may have a placeholder Container of type `Canvas`. - * A Collection _MAY_ have the `placeholderCanvas` property.
- Clients _MAY_ render `placeholderCanvas` on a Collection. - * A Manifest _MAY_ have the `placeholderCanvas` property.
- Clients _MAY_ render `placeholderCanvas` on a Manifest. - * A Canvas _MAY_ have the `placeholderCanvas` property.
- Clients _MAY_ render `placeholderCanvas` on a Canvas. - * A Range _MAY_ have the `placeholderCanvas` property.
- Clients _MAY_ render `placeholderCanvas` on a Range. - * Other types of resource _MUST NOT_ have the `placeholderCanvas` property.
- Clients _SHOULD_ ignore `placeholderCanvas` on other types of resource. +Clients _MAY_ display the content of a linked placeholder Container when presenting the resource. When more than one such Container is available, for example if `placeholderContainer` is provided for the currently selected Range and the current Manifest, the client _SHOULD_ pick the one most specific to the content. Publishers _SHOULD NOT_ assume that the placeholder Container will be processed by all clients. Clients _SHOULD_ take care to avoid conflicts between time-based media in the rendered placeholder Container and the content of the resource that has the `placeholderContainer` property. + +The value of `placeholderContainer` _MUST_ be a JSON object with the `id` and `type` properties. The value of `type` _MUST_ be a Container type. The JSON object _MAY_ have other properties valid for that Container type. + + * A Collection _MAY_ have the `placeholderContainer` property.
+ Clients _MAY_ render `placeholderContainer` on a Collection. + * A Manifest _MAY_ have the `placeholderContainer` property.
+ Clients _MAY_ render `placeholderContainer` on a Manifest. + * All Container types _MAY_ have the `placeholderContainer` property.
+ Clients _MAY_ render `placeholderContainer` on Container types. + * A Range _MAY_ have the `placeholderContainer` property.
+ Clients _MAY_ render `placeholderContainer` on a Range. + * Other types of resource _MUST NOT_ have the `placeholderContainer` property.
+ Clients _SHOULD_ ignore `placeholderContainer` on other types of resource. {% include api/code_header.html %} ``` json-doc { - "placeholderCanvas": { + "placeholderContainer": { "id": "https://example.org/iiif/1/canvas/placeholder", "type": "Canvas", "height": 1400, @@ -263,31 +360,31 @@ The value _MUST_ be a JSON object with the `id` and `type` properties, and _MAY_ } ``` -##### accompanyingCanvas +##### accompanyingContainer -A single Canvas that provides additional content for use while rendering the resource that has the `accompanyingCanvas` property. Examples include an image to show while a duration-only Canvas is playing audio; or background audio to play while a user is navigating an image-only Manifest. +A single Container that provides additional content for use while rendering the resource that has the `accompanyingContainer` property. Examples include an image to show while a duration-only Canvas is playing audio; or background audio to play while a user is navigating an image-only Manifest. -Clients _MAY_ display the content of an accompanying Canvas when presenting the resource. As with `placeholderCanvas` above, when more than one accompanying Canvas is available, the client _SHOULD_ pick the one most specific to the content. Publishers _SHOULD NOT_ assume that the accompanying Canvas will be processed by all clients. Clients _SHOULD_ take care to avoid conflicts between time-based media in the accompanying Canvas and the content of the resource that has the `accompanyingCanvas` property. +Clients _MAY_ display the content of an accompanying Container when presenting the resource. As with `placeholderContainer` above, when more than one accompanying Container is available, the client _SHOULD_ pick the one most specific to the content. Publishers _SHOULD NOT_ assume that the accompanying Container will be processed by all clients. Clients _SHOULD_ take care to avoid conflicts between time-based media in the accompanying Container and the content of the resource that has the `accompanyingContainer` property. -The value _MUST_ be a JSON object with the `id` and `type` properties, and _MAY_ have other properties of Canvases. The value of `type` _MUST_ be the string `Canvas`. The object _MUST NOT_ have the `placeholderCanvas` property, nor the `accompanyingCanvas` property. +The value of `accompanyingContainer` _MUST_ be a JSON object with the `id` and `type` properties. The value of `type` _MUST_ be a Container type. The JSON object _MAY_ have other properties valid for that Container type. - * A Collection _MAY_ have the `accompanyingCanvas` property.
- Clients _MAY_ render `accompanyingCanvas` on a Collection. - * A Manifest _MAY_ have the `accompanyingCanvas` property.
- Clients _MAY_ render `accompanyingCanvas` on a Manifest. - * A Canvas _MAY_ have the `accompanyingCanvas` property.
- Clients _MAY_ render `accompanyingCanvas` on a Canvas. - * A Range _MAY_ have the `accompanyingCanvas` property.
- Clients _MAY_ render `accompanyingCanvas` on a Range. - * Other types of resource _MUST NOT_ have the `accompanyingCanvas` property.
- Clients _SHOULD_ ignore `accompanyingCanvas` on other types of resource. + * A Collection _MAY_ have the `accompanyingContainer` property.
+ Clients _MAY_ render `accompanyingContainer` on a Collection. + * A Manifest _MAY_ have the `accompanyingContainer` property.
+ Clients _MAY_ render `accompanyingContainer` on a Manifest. + * All Container types _MAY_ have the `accompanyingContainer` property.
+ Clients _MAY_ render `accompanyingContainer` on Container types. + * A Range _MAY_ have the `accompanyingContainer` property.
+ Clients _MAY_ render `accompanyingContainer` on a Range. + * Other types of resource _MUST NOT_ have the `accompanyingContainer` property.
+ Clients _SHOULD_ ignore `accompanyingContainer` on other types of resource. {% include api/code_header.html %} ``` json-doc { - "accompanyingCanvas": { - "id": "https://example.org/iiif/1/canvas/accompany", - "type": "Canvas", + "accompanyingContainer": { + "id": "https://example.org/iiif/1/timeline/accompany", + "type": "Timeline", "duration": 180.0 } } @@ -329,6 +426,7 @@ The value _MUST_ be a string. | Class | Description | | ------------- | -------------------------------- | | `Dataset` | Data not intended to be rendered to humans directly | +| `Abouty-Metadata` | Machine-readable _thing_ such as a linked art metadata JSON doc or a MARC record. | | `Image` | Two dimensional visual resources primarily intended to be seen, such as might be rendered with an <img> HTML tag | | `Model` | A three (or more) dimensional model intended to be interacted with by humans | | `Sound` | Auditory resources primarily intended to be heard, such as might be rendered with an <audio> HTML tag | @@ -895,6 +993,12 @@ The value _MUST_ be an array of JSON objects. Each item _MUST_ have the `id` and } ``` +Common types of seeAlso: + +| `Dataset` | Data not intended to be rendered to humans directly | +| `Abouty-Metadata` | Machine-readable _thing_ such as a linked art metadata JSON doc or a MARC record. | + + #### 3.3.2. Internal Links ##### partOf @@ -911,6 +1015,9 @@ The value _MUST_ be an array of JSON objects. Each item _MUST_ have the `id` and { "partOf": [ { "id": "https://example.org/iiif/1", "type": "Manifest" } ] } ``` +The resources referred to by the `accompanyingContainer` and `placeholderContainer` properties are `partOf` that referring Container. + + ##### start A Canvas, or part of a Canvas, which the client _SHOULD_ show on initialization for the resource that has the `start` property. The reference to part of a Canvas is handled in the same way that Ranges reference parts of Canvases. This property allows the client to begin with the first Canvas that contains interesting content rather than requiring the user to manually navigate to find it. From 623a7fe90ed4463e77966212b2b940ab743d5641 Mon Sep 17 00:00:00 2001 From: HackMD <37423+hackmd-hub[bot]@users.noreply.github.com> Date: Thu, 24 Oct 2024 14:16:17 +0000 Subject: [PATCH 008/130] last changed at Oct 24, 2024 3:18 PM, pushed by Julie Winchester From bfe9ff876208d6575b465c9a2a8c22248dd616f8 Mon Sep 17 00:00:00 2001 From: HackMD <37423+hackmd-hub[bot]@users.noreply.github.com> Date: Thu, 24 Oct 2024 16:01:09 +0000 Subject: [PATCH 009/130] last changed at Oct 24, 2024 4:58 PM, pushed by Julie Winchester --- source/presentation/4.0/properties.md | 18 +++++++----------- 1 file changed, 7 insertions(+), 11 deletions(-) diff --git a/source/presentation/4.0/properties.md b/source/presentation/4.0/properties.md index 41391fa6e..9275b1f0e 100644 --- a/source/presentation/4.0/properties.md +++ b/source/presentation/4.0/properties.md @@ -326,9 +326,6 @@ The value of the property _MUST_ be a [GeoJSON Feature Collection](link) contain ``` - - - ##### placeholderContainer A single Container that provides additional content for use before the main content of the resource that has the `placeholderContainer` property is rendered, or as an advertisement or stand-in for that content. Examples include images, text and sound standing in for video content before the user initiates playback; or a film poster to attract user attention. The content provided by `placeholderContainer` differs from a thumbnail: a client might use `thumbnail` to summarize and navigate multiple resources, then show content from `placeholderContainer` as part of the initial presentation of a single resource. A placeholder Container is likely to have different dimensions to those of the Container(s) of the resource that has the `placeholderContainer` property. A placeholder Container may be of a different type from the resource that has the `placeholderContainer` property. For example, a `Scene` may have a placeholder Container of type `Canvas`. @@ -342,7 +339,7 @@ The value of `placeholderContainer` _MUST_ be a JSON object with the `id` and `t * A Manifest _MAY_ have the `placeholderContainer` property.
Clients _MAY_ render `placeholderContainer` on a Manifest. * All Container types _MAY_ have the `placeholderContainer` property.
- Clients _MAY_ render `placeholderContainer` on Container types. + Clients _MAY_ render `placeholderContainer` on Containers. * A Range _MAY_ have the `placeholderContainer` property.
Clients _MAY_ render `placeholderContainer` on a Range. * Other types of resource _MUST NOT_ have the `placeholderContainer` property.
@@ -373,7 +370,7 @@ The value of `accompanyingContainer` _MUST_ be a JSON object with the `id` and ` * A Manifest _MAY_ have the `accompanyingContainer` property.
Clients _MAY_ render `accompanyingContainer` on a Manifest. * All Container types _MAY_ have the `accompanyingContainer` property.
- Clients _MAY_ render `accompanyingContainer` on Container types. + Clients _MAY_ render `accompanyingContainer` on Containers. * A Range _MAY_ have the `accompanyingContainer` property.
Clients _MAY_ render `accompanyingContainer` on a Range. * Other types of resource _MUST NOT_ have the `accompanyingContainer` property.
@@ -425,10 +422,9 @@ The value _MUST_ be a string. | Class | Description | | ------------- | -------------------------------- | -| `Dataset` | Data not intended to be rendered to humans directly | -| `Abouty-Metadata` | Machine-readable _thing_ such as a linked art metadata JSON doc or a MARC record. | +| `Dataset` | Data not intended to be rendered to humans directly, such as a CSV or RDF | | `Image` | Two dimensional visual resources primarily intended to be seen, such as might be rendered with an <img> HTML tag | -| `Model` | A three (or more) dimensional model intended to be interacted with by humans | +| `Model` | A three dimensional spatial model intended to be visualized, such as might be rendered with a 3d javascript library | | `Sound` | Auditory resources primarily intended to be heard, such as might be rendered with an <audio> HTML tag | | `Text` | Resources primarily intended to be read | | `Video` | Moving images, with or without accompanying audio, such as might be rendered with a <video> HTML tag | @@ -993,10 +989,10 @@ The value _MUST_ be an array of JSON objects. Each item _MUST_ have the `id` and } ``` -Common types of seeAlso: -| `Dataset` | Data not intended to be rendered to humans directly | -| `Abouty-Metadata` | Machine-readable _thing_ such as a linked art metadata JSON doc or a MARC record. | +#### abouty-field-name-here + +Point to a `Dataset` with more semantics than just `seeAlso` #### 3.3.2. Internal Links From 48ceb1288038224218553713807c309c9041bf9a Mon Sep 17 00:00:00 2001 From: HackMD <37423+hackmd-hub[bot]@users.noreply.github.com> Date: Fri, 25 Oct 2024 10:46:04 +0000 Subject: [PATCH 010/130] last changed at Oct 25, 2024 3:42 AM, pushed by Dawn Childress --- source/presentation/4.0/properties.md | 171 +++++++++++++++++++++++--- 1 file changed, 154 insertions(+), 17 deletions(-) diff --git a/source/presentation/4.0/properties.md b/source/presentation/4.0/properties.md index 9275b1f0e..8269ebd46 100644 --- a/source/presentation/4.0/properties.md +++ b/source/presentation/4.0/properties.md @@ -422,7 +422,7 @@ The value _MUST_ be a string. | Class | Description | | ------------- | -------------------------------- | -| `Dataset` | Data not intended to be rendered to humans directly, such as a CSV or RDF | +| `Dataset` | Data not intended to be rendered to humans directly, such as a CSV, an RDF serialization or a zip file | | `Image` | Two dimensional visual resources primarily intended to be seen, such as might be rendered with an <img> HTML tag | | `Model` | A three dimensional spatial model intended to be visualized, such as might be rendered with a 3d javascript library | | `Sound` | Auditory resources primarily intended to be heard, such as might be rendered with an <audio> HTML tag | @@ -598,12 +598,12 @@ The value _MUST_ be an array of strings. | `repeat` | Valid on Collections and Manifests, that include Canvases that have at least the `duration` dimension. When the client reaches the end of the duration of the final Canvas in the resource, and the `behavior` value `auto-advance`{: style="white-space:nowrap;"} is also in effect, then the client _SHOULD_ return to the first Canvas, or segment of Canvas, in the resource that has the `behavior` value `repeat` and start playing again. If the `behavior` value `auto-advance` is not in effect, then the client _SHOULD_ render a navigation control for the user to manually return to the first Canvas or segment. Disjoint with `no-repeat`.| | `no-repeat` | Valid on Collections and Manifests, that include Canvases that have at least the `duration` dimension. When the client reaches the end of the duration of the final Canvas in the resource, the client _MUST NOT_ return to the first Canvas, or segment of Canvas. This is a default temporal behavior if not specified. Disjoint with `repeat`.| | | **Layout Behaviors** | -| `unordered` | Valid on Collections, Manifests and Ranges. The Canvases included in resources that have this behavior have no inherent order, and user interfaces _SHOULD_ avoid implying an order to the user. Disjoint with `individuals`, `continuous`, and `paged`.| +| `unordered` | Valid on Collections, Manifests and Ranges. The resources included in resources that have this behavior have no inherent order, and user interfaces _SHOULD_ avoid implying an order to the user. Disjoint with `individuals`, `continuous`, and `paged`.| | `individuals` | Valid on Collections, Manifests, and Ranges. For Collections that have this behavior, each of the included Manifests are distinct objects in the given order. For Manifests and Ranges, the included Canvases are distinct views, and _SHOULD NOT_ be presented in a page-turning interface. This is the default layout behavior if not specified. Disjoint with `unordered`, `continuous`, and `paged`. | -| `continuous` | Valid on Collections, Manifests and Ranges, which include Canvases that have at least `height` and `width` dimensions. Canvases included in resources that have this behavior are partial views and an appropriate rendering might display all of the Canvases virtually stitched together, such as a long scroll split into sections. This behavior has no implication for audio resources. The `viewingDirection` of the Manifest will determine the appropriate arrangement of the Canvases. Disjoint with `unordered`, `individuals` and `paged`. | -| `paged` | Valid on Collections, Manifests and Ranges, which include Canvases that have at least `height` and `width` dimensions. Canvases included in resources that have this behavior represent views that _SHOULD_ be presented in a page-turning interface if one is available. The first canvas is a single view (the first recto) and thus the second canvas likely represents the back of the object in the first canvas. If this is not the case, see the `behavior` value `non-paged`. Disjoint with `unordered`, `individuals`, `continuous`, `facing-pages` and `non-paged`. | -| `facing-pages`{: style="white-space:nowrap;"} | Valid only on Canvases, where the Canvas has at least `height` and `width` dimensions. Canvases that have this behavior, in a Manifest that has the `behavior` value `paged`, _MUST_ be displayed by themselves, as they depict both parts of the opening. If all of the Canvases are like this, then page turning is not possible, so simply use `individuals` instead. Disjoint with `paged` and `non-paged`.| -| `non-paged` | Valid only on Canvases, where the Canvas has at least `height` and `width` dimensions. Canvases that have this behavior _MUST NOT_ be presented in a page turning interface, and _MUST_ be skipped over when determining the page order. This behavior _MUST_ be ignored if the current Manifest does not have the `behavior` value `paged`. Disjoint with `paged` and `facing-pages`. | +| `continuous` | Valid on Collections, Manifests and Ranges, which include Canvases. Canvases included in resources that have this behavior are partial views and an appropriate rendering might display all of the Canvases virtually stitched together, such as a long scroll split into sections. This behavior has no implication for audio resources. The `viewingDirection` of the Manifest will determine the appropriate arrangement of the Canvases. Disjoint with `unordered`, `individuals` and `paged`. | +| `paged` | Valid on Collections, Manifests and Ranges, which include Canvases. Canvases included in resources that have this behavior represent views that _SHOULD_ be presented in a page-turning interface if one is available. The first canvas is a single view (the first recto) and thus the second canvas likely represents the back of the object in the first canvas. If this is not the case, see the `behavior` value `non-paged`. Disjoint with `unordered`, `individuals`, and `continuous`. | +| `facing-pages`{: style="white-space:nowrap;"} | Valid only on Canvases. Canvases that have this behavior, in a Manifest that has the `behavior` value `paged`, _MUST_ be displayed by themselves, as they depict both parts of the opening. If all of the Canvases are like this, then page turning is not possible, so simply use `individuals` instead. Disjoint with `non-paged`.| +| `non-paged` | Valid only on Canvases. Canvases that have this behavior _MUST NOT_ be presented in a page-turning interface, and _MUST_ be skipped over when determining the page order. This behavior _MUST_ be ignored if the current Manifest does not have the `behavior` value `paged`. Disjoint with `facing-pages`. | | | **Collection Behaviors** | | `multi-part` | Valid only on Collections. Collections that have this behavior consist of multiple Manifests or Collections which together form part of a logical whole or a contiguous set, such as multi-volume books or a set of journal issues. Clients might render these Collections as a table of contents rather than with thumbnails, or provide viewing interfaces that can easily advance from one member to the next. Disjoint with `together`.| | `together` | Valid only on Collections. A client _SHOULD_ present all of the child Manifests to the user at once in a separate viewing area with its own controls. Clients _SHOULD_ catch attempts to create too many viewing areas. This behavior _SHOULD NOT_ be interpreted as applying to the members of any child resources. Disjoint with `multi-part`.| @@ -620,6 +620,42 @@ The value _MUST_ be an array of strings. { "behavior": [ "auto-advance", "individuals" ] } ``` +##### provides + +A set of features or additional functionality that a linked resource enables relative to the linking or including resource, which is not defined by the `type`, `format` or `profile` of the linked resource. It provides information as to why and how a client might want to interact with the resource, rather than what the resource is. For example, a text file (linked resource) that `provides` a `closedCaptions` for a Video (context resource), or an audio file (linked resource) that `provides` an `audioDescription` of a Canvas (context resource). + +The value _MUST_ be an array of strings, each string identifies a particular feature and _MUST_ be taken from the table below or the [provides registry][link]. + +Note that the majority of the values have been selected from [accessibility feature spec][link] and thus use the original form rather than being consistent with the hyphen-based form of the values of `behavior` and `viewingDirection`. + + +* Annotations with the `painting` motivation _SHOULD NOT_ have the `provides` property.
+ Clients _SHOULD_ ignore the `provides` property on Annotations with the `painting` motivation. +* Any resource linked to or included in another resource _MAY_ have the `provides` property.
+ Clients _SHOULD_ process the `provides` property on these resources. + +| Value | Description | +| ----- | ----------- | +| `closedCaptions` | ... | +| `alternativeText` | ... | +| `audioDescription` | ... | +| `longDescription` | ... | +| `signLanguage` | ... | +| `highContrastAudio` | ... | +| `highContrastDisplay` | ... | +| `braille` | ... | +| `tactileGraphic` | ... | +| `transcript` | ... | +| `translation` | (IIIF Defined) ... | +| `subtitles` | (IIIF Defined) ... | +{: .api-table #table-behavior} + +{% include api/code_header.html %} +``` json-doc +{ "provides": [ "closedCaption" ] } +``` + + ##### timeMode A mode associated with an Annotation that is to be applied to the rendering of any time-based media, or otherwise could be considered to have a duration, used as a body resource of that Annotation. Note that the association of `timeMode` with the Annotation means that different resources in the body cannot have different values. This specification defines the values specified in the table below. Others may be defined externally as an [extension][prezi30-ldce]. @@ -631,9 +667,9 @@ The value _MUST_ be a string. | Value | Description | | ----- | ----------- | -| `trim` | (default, if not supplied) If the content resource has a longer duration than the duration of portion of the Canvas it is associated with, then at the end of the Canvas's duration, the playback of the content resource _MUST_ also end. If the content resource has a shorter duration than the duration of the portion of the Canvas it is associated with, then, for video resources, the last frame _SHOULD_ persist on-screen until the end of the Canvas portion's duration. For example, a video of 120 seconds annotated to a Canvas with a duration of 100 seconds would play only the first 100 seconds and drop the last 20 second. | +| `trim` | (default, if not supplied) If the content resource has a longer duration than the duration of the portion of the Canvas it is associated with, then at the end of the Canvas's duration, the playback of the content resource _MUST_ also end. If the content resource has a shorter duration than the duration of the portion of the Canvas it is associated with, then, for video resources, the last frame _SHOULD_ persist on-screen until the end of the Canvas portion's duration. For example, a video of 120 seconds annotated to a Canvas with a duration of 100 seconds would play only the first 100 seconds and drop the last 20 seconds. | | `scale` | Fit the duration of content resource to the duration of the portion of the Canvas it is associated with by scaling. For example, a video of 120 seconds annotated to a Canvas with a duration of 60 seconds would be played at double-speed. | -| `loop` | If the content resource is shorter than the `duration` of the Canvas, it _MUST_ be repeated to fill the entire duration. Resources longer than the `duration` _MUST_ be trimmed as described above. For example, if a 20 second duration audio stream is annotated onto a Canvas with duration 30 seconds, it will be played one and a half times. | +| `loop` | If the content resource is shorter than the `duration` of the Canvas, it _MUST_ be repeated to fill the entire duration. Resources longer than the `duration` _MUST_ be trimmed as described above. For example, if a 20 second duration audio stream is annotated onto a Canvas with a duration of 30 seconds, it will be played one and a half times. | {: .api-table #table-timemode} {% include api/code_header.html %} @@ -830,7 +866,7 @@ A small image resource that represents the Agent resource it is associated with. When more than one logo is present, the client _SHOULD_ pick only one of them, based on the information in the logo properties. For example, the client could select a logo of appropriate aspect ratio based on the `height` and `width` properties of the available logos. The client _MAY_ decide on the logo by inspecting properties defined as [extensions][prezi30-ldce]. -The value of this property _MUST_ be an array of JSON objects, each of which _MUST_ have `id` and `type` properties, and _SHOULD_ have `format`. The value of `type` _MUST_ be "Image". +The value of this property _MUST_ be an array of JSON objects, each of which _MUST_ have `id` and `type` properties, and _SHOULD_ have `format`. The value of `type` _MUST_ be `Image`. * Agent resources _SHOULD_ have the `logo` property.
Clients _MUST_ render `logo` on Agent resources. @@ -855,7 +891,7 @@ The value of this property _MUST_ be an array of JSON objects, each of which _MU A resource that is an alternative, non-IIIF representation of the resource that has the `rendering` property. Such representations typically cannot be painted onto a single Canvas, as they either include too many views, have incompatible dimensions, or are compound resources requiring additional rendering functionality. The `rendering` resource _MUST_ be able to be displayed directly to a human user, although the presentation may be outside of the IIIF client. The resource _MUST NOT_ have a splash page or other interstitial resource that mediates access to it. If access control is required, then the [IIIF Authentication API][iiif-auth] is _RECOMMENDED_. Examples include a rendering of a book as a PDF or EPUB, a slide deck with images of a building, or a 3D model of a statue. -The value _MUST_ be an array of JSON objects. Each item _MUST_ have the `id`, `type` and `label` properties, and _SHOULD_ have a `format` property. +The value _MUST_ be an array of JSON objects. Each item _MUST_ have the `id`, `type` and `label` properties, and _SHOULD_ have the `format` and `language` properties. * Any resource type _MAY_ have the `rendering` property with at least one item.
Clients _SHOULD_ render `rendering` on a Collection, Manifest or Canvas, and _MAY_ render `rendering` on other types of resource. @@ -936,7 +972,7 @@ A list of one or more service definitions on the top-most resource of the docume A client encountering a `service` property where the definition consists only of an `id` and `type` _SHOULD_ then check the `services` property on the top-most resource for an expanded definition. If the service is not present in the `services` list, and the client requires more information in order to use the service, then it _SHOULD_ dereference the `id` (or `@id`) of the service in order to retrieve a service description. -The value _MUST_ be an array of JSON objects. Each object _MUST_ a service resource, as described above. +The value _MUST_ be an array of JSON objects. Each object _MUST_ be a service resource, as described above. * A Collection _MAY_ have the `services` property, if it is the topmost Collection in a response document.
Clients _SHOULD_ process `services` on a Collection. @@ -990,11 +1026,6 @@ The value _MUST_ be an array of JSON objects. Each item _MUST_ have the `id` and ``` -#### abouty-field-name-here - -Point to a `Dataset` with more semantics than just `seeAlso` - - #### 3.3.2. Internal Links ##### partOf @@ -1177,6 +1208,112 @@ Additional motivations may be added to the Annotation to further clarify the int + + + + +## 4. JSON-LD Considerations + +This section describes features applicable to all of the Presentation API content. For the most part, these are features of the JSON-LD specification that have particular uses within the API. + +### 4.1. Case Sensitivity + +Terms in JSON-LD are [case sensitive][org-w3c-json-ld-case]. The cases of properties and enumerated values in IIIF Presentation API responses _MUST_ match those used in this specification. For example to specify that a resource is a Manifest, the property _MUST_ be given as `type` and not `Type` or `tYpE`, and the value _MUST_ be given as `Manifest` and not `manifest` or `manIfEsT`. + +### 4.2. Resource Representations + +Resource descriptions _SHOULD_ be [embedded][prezi30-terminology] within the JSON description of parent resources, and _MAY_ also be available via separate requests from the HTTP(S) URI given in the resource's `id` property. Links to resources _MUST_ be given as a JSON object with the `id` and `type` properties and _SHOULD_ have `format` or `profile` to give a hint as to what sort of resource is being referred to. + +{% include api/code_header.html %} +``` json-doc +{ + "rendering": [ + { + "id": "https://example.org/content/book.pdf", + "type": "Text", + "label": { "en": [ "Example Book (pdf)" ] }, + "format": "application/pdf" + } + ] +} +``` + +### 4.3. Properties with Multiple Values + +Any of the properties in the API that can have multiple values _MUST_ always be given as an array of values, even if there is only a single item in that array. + +{% include api/code_header.html %} +``` json-doc +{ + "thumbnail": [ + { + "id": "https://example.org/images/thumb1.jpg", + "type": "Image", + "format": "image/jpeg" + } + ] +} +``` + +### 4.4. Language of Property Values +{: #language-of-property-values} + +Language _MAY_ be associated with strings that are intended to be displayed to the user for the `label` and `summary` properties, plus the `label` and `value` properties of the `metadata` and `requiredStatement` objects. + +The values of these properties _MUST_ be JSON objects, with the keys being the [BCP 47][org-bcp-47] language code for the language, or if the language is either not known or the string does not have a language, then the key _MUST_ be the string `none`. The associated values _MUST_ be arrays of strings, where each item is the content in the given language. + +{% include api/code_header.html %} +``` json-doc +{ + "label": { + "en": [ + "Whistler's Mother", + "Arrangement in Grey and Black No. 1: The Artist's Mother" + ], + "fr": [ + "Arrangement en gris et noir no 1", + "Portrait de la mère de l'artiste", + "La Mère de Whistler" + ], + "none": [ "Whistler (1871)" ] + } +} +``` + +Note that [BCP 47][org-bcp-47] allows the script of the text to be included after a hyphen, such as `ar-latn`, and clients should be aware of this possibility. + +In the case where multiple values are supplied, clients _MUST_ use the following algorithm to determine which values to display to the user. + +* If all of the values are associated with the `none` key, the client _MUST_ display all of those values. +* Else, the client should try to determine the user's language preferences, or failing that use some default language preferences. Then: + * If any of the values have a language associated with them, the client _MUST_ display all of the values associated with the language that best matches the language preference. + * If all of the values have a language associated with them, and none match the language preference, the client _MUST_ select a language and display all of the values associated with that language. + * If some of the values have a language associated with them, but none match the language preference, the client _MUST_ display all of the values that do not have a language associated with them. + +Note that this does not apply to [embedded][prezi30-terminology] textual bodies in Annotations, which use the Web Annotation pattern of `value` and `language` as separate properties. + +### 4.5. HTML Markup in Property Values + +Minimal HTML markup _MAY_ be included for processing in the `summary` property and the `value` property in the `metadata` and `requiredStatement` objects. It _MUST NOT_ be used in `label` or other properties. This is included to allow content publishers to add links and simple formatting instructions to blocks of text. The content _MUST_ be well-formed XML and therefore _MUST_ be wrapped in an element such as `p` or `span`. There _MUST NOT_ be whitespace on either side of the HTML string, and thus the first character in the string _MUST_ be a '<' character and the last character _MUST_ be '>', allowing a consuming application to test whether the value is HTML or plain text using these. To avoid a non-HTML string matching this, it is _RECOMMENDED_ that an additional whitespace character be added to the end of the value in situations where plain text happens to start and end this way. + +In order to avoid HTML or script injection attacks, clients _MUST_ remove: + + * Tags such as `script`, `style`, `object`, `form`, `input` and similar. + * All attributes other than `href` on the `a` tag, `src` and `alt` on the `img` tag. + * All `href` attributes that start with the strings other than "http:", "https:", and "mailto:". + * CData sections. + * XML Comments. + * Processing instructions. + +Clients _SHOULD_ allow only `a`, `b`, `br`, `i`, `img`, `p`, `small`, `span`, `sub` and `sup` tags. Clients _MAY_ choose to remove any and all tags, therefore it _SHOULD NOT_ be assumed that the formatting will always be rendered. Note that publishers _MAY_ include arbitrary HTML content for processing using customized or experimental applications, and the requirements for clients assume an untrusted or unknown publisher. + +{% include api/code_header.html %} +``` json-doc +{ "summary": { "en": [ "

Short summary of the resource.

" ] } } +``` + +### 4.6. Linked Data Context and Extensions + The top level resource in the response _MUST_ have the `@context` property, and it _SHOULD_ appear as the very first key/value pair of the JSON representation. This tells Linked Data processors how to interpret the document. The IIIF Presentation API context, below, _MUST_ occur once per response in the top-most resource, and thus _MUST NOT_ appear within [embedded][prezi30-terminology] resources. For example, when embedding a Canvas within a Manifest, the Canvas will not have the `@context` property. The value of the `@context` property _MUST_ be either the URI `http://iiif.io/api/presentation/{{ page.major }}/context.json` or a JSON array with the URI `http://iiif.io/api/presentation/{{ page.major }}/context.json` as the last item. Further contexts, such as those for local or [registered extensions][registry], _MUST_ be added at the beginning of the array. @@ -1206,7 +1343,7 @@ The JSON representation _MUST NOT_ include the `@graph` key at the top level. Th There are some common terms used in more than one JSON-LD context document. Every attempt has been made to minimize these collisions, but some are inevitable. In order to know which specification is in effect at any given point, the class of the resource that has the property is the primary governing factor. Thus properties on Annotation based resources use the context from the [Web Annotation Data Model][org-w3c-webanno], whereas properties on classes defined by this specification use the IIIF Presentation API context's definition. -There is one property that is in direct conflict - the `label` property is defined by both and is available for every resource. The use of `label` in IIIF follows modern best practices for internationalization by allowing the language to be associated with the value using the language map construction [described above][prezi30-languages]. The Web Annotation Data Model uses it only for [Annotation Collections][prezi30-annocoll], and mandates the format is a string. For this property, the API overrides the definition from the Annotation model to ensure that labels can consistently be represented in multiple languages. +There is one property that is in direct conflict - the `label` property is defined by both and is available for every resource. The use of `label` in IIIF follows modern best practices for internationalization by allowing the language to be associated with the value using the language map construction [described above][prezi30-languages], also allowing multiple languages to be used. The Web Annotation Data Model uses it only for [Annotation Collections][prezi30-annocoll], and mandates the format is a string. For this property, the API overrides the definition from the Annotation model to ensure that labels can consistently be represented in multiple languages. The following properties are defined by both, and the IIIF representation is more specific than the Web Annotation Data Model but are not in conflict, or are never used on the same resource: From 71bbd341fa0f32f43cf4ab480cf6f9f2b68d89e8 Mon Sep 17 00:00:00 2001 From: HackMD <37423+hackmd-hub[bot]@users.noreply.github.com> Date: Fri, 25 Oct 2024 10:50:55 +0000 Subject: [PATCH 011/130] last changed at Oct 25, 2024 3:48 AM, pushed by Dawn Childress --- source/presentation/4.0/index.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index aa7b92b89..38b43e277 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -273,8 +273,16 @@ The annotation above could be expressed as its fragment-based equivalent: ### Annotation Page +"Overlapping elements with a larger z-index cover those with a smaller one." +link to https://developer.mozilla.org/en-US/docs/Web/CSS/z-index + + ### Annotation Collection +deal with this: +https://github.com/IIIF/api/pull/2304/files#diff-cc70f02818f6bed2b14dfbf8bf3206e0825047951c8e83ad56fc73e489f82ac4R1757 + +use totalItems? https://iiif.io/api/discovery/1.0/#totalitems ### Manifest From 7398e18bf89d4a2569f23619007e9ed3b272368e Mon Sep 17 00:00:00 2001 From: tomcrane Date: Fri, 25 Oct 2024 12:43:45 +0100 Subject: [PATCH 012/130] placeholder sections in prezi4 incl. physical dimensions --- source/presentation/4.0/index.md | 84 +++++++++++++++++++++++++++++--- 1 file changed, 76 insertions(+), 8 deletions(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index 38b43e277..247b3f7ba 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -245,6 +245,8 @@ Example Annotation that positions a model at a point within a Scene: #### URI Fragments +(move up, include xywh) + The point may instead be defined using a short-hand form of a URI Fragment at the end of the `id` of the Scene as the `target` of the Annotation. The name of the fragment parameter is `xyz` and its value is the x, y and z values separated by commas. Each value can be expressed as either an integer or a floating point number. The annotation above could be expressed as its fragment-based equivalent: @@ -305,6 +307,10 @@ content state intended to: - modify the Container in a particular context (`scope`, storytelling) - contribute additional information permanently (rerum **inbox** - move to protocol doc) +### Using Content State + +(not in section 6) + ### reset "diff", "original state" etc @@ -314,8 +320,17 @@ behavior: sequence ## Selectors +preamble - cover all the use cases + ### SpecificResource +(This heading should be more descriptive) + +fragments/segments/parts of resources +SvgSelector +xywh + + ### PointSelector @@ -493,6 +508,8 @@ Painting a Scene into another while excluding import of several types of resourc ## Advanced Association Features +(This needs to be sprinkled throughout above - especially as SpecificResource must be introduced early for 3D) + ### Nesting A Canvas can be painted into a Scene as an Annotation, but the 2D nature of Canvases requires special consideration due to important differences between Canvases and Scenes. A Canvas describes a bounded 2D space with finite `height` and `width` measured in pixels with a pixel origin at the top-left corner of the Canvas, while Scenes describe a boundless 3D space with x, y, and z axes of arbitrary coordinate units and a coordinate origin at the center of the space. It is important to note that in many cases the pixel scale used by a Canvas or a 2D image content resource will not be in proportion to the desired 3D coordinate unit scale in a Scene. @@ -520,33 +537,77 @@ Example placing top-left at (0, 1, 0); bottom-left at (0, 0, 0); bottom-right at ``` -### Segments - ### Embedded Content +e.g., painting TextualBody on Canvas + + +### Comment Annotations + +(move to Annotation section) + + ### Choice of Alternative Resources +(move to Annotation section) + + ### Non Rectangular Segments +SvgSelector - move to SpecificResource too ^^ + + ### Style +Move to SpecificResource + + ### Rotation -### Comment Annotations -### Hotspot Linking +### Hotspot Linking and Activation -### Activation +Move to SpecificResource -### Using Content State - - modify the Container in a particular context (`scope`, storytelling) +## Conveying Physical Dimensions + +(why is this important!?) + +(move the props to vocab doc) + +### spatialScale + +### temporalScale + + +``` +{ + "spatialScale": { + "factor": 22.0, + "units": "m" + }, + + + // this would be rarely used + "temporalScale": { + "factor": 0.00001 + } + +} +``` +`factor` Required A floating point ratio. +`units` Required A real-world measuring unit. Always seconds for temporalScale. Possible values for spatialScale include: "m", "ft". (is that it?) -### Physical Dimension Service +For a Canvas, it's the physical "size" of each cartesian integer unit. +For a Scene, it's the physical size of the unit vector. +For a timeline it's the ratio of time in the recording to time in the real world. +(define props in the Vocabulary doc) + ## HTTP Requests and Responses @@ -559,6 +620,13 @@ Example placing top-left at (0, 1, 0); bottom-left at (0, 0, 0); bottom-right at ### Authentication +## Accessibility + +(new section) + +`provides` + + ## Appendices ### Summary of Property Requirements From 07dec3a4a85502fd1da7fd83b4e54522f77fcef6 Mon Sep 17 00:00:00 2001 From: Dawn Childress Date: Wed, 5 Feb 2025 09:27:38 -0800 Subject: [PATCH 013/130] add header to index.md --- source/presentation/4.0/index.md | 55 +++++++++++++++++++++++++++++++- 1 file changed, 54 insertions(+), 1 deletion(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index 247b3f7ba..bc250ace9 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -1,3 +1,56 @@ +--- +title: "Presentation API 4.0 - DRAFT" +title_override: "IIIF Presentation API 4.0" +id: presentation-api +layout: spec +cssversion: 3 +tags: [specifications, presentation-api] +major: 4 +minor: 0 +patch: 0 +pre: final +redirect_from: + - /presentation/index.html + - /presentation/4/index.html +editors: + - name: Michael Appleby + ORCID: https://orcid.org/0000-0002-1266-298X + institution: Yale University + - name: Tom Crane + ORCID: https://orcid.org/0000-0003-1881-243X + institution: Digirati + - name: Robert Sanderson + ORCID: https://orcid.org/0000-0003-4441-6852 + institution: J. Paul Getty Trust + - name: Dawn Childress + ORCID: + institution: UCLA + - name: Julie Winchester + ORCID: + institution: Duke University + - name: Jeff Mixter + ORCID: + institution: OCLC +hero: + image: '' +--- + +## Status of this Document +{:.no_toc} +__This Version:__ {{ page.major }}.{{ page.minor }}.{{ page.patch }}{% if page.pre != 'final' %}-{{ page.pre }}{% endif %} + +__Latest Stable Version:__ [{{ site.data.apis.presentation.latest.major }}.{{ site.data.apis.presentation.latest.minor }}.{{ site.data.apis.presentation.latest.patch }}][prezi-stable-version] + +__Previous Version:__ [3.0][prezi3] + +**Editors:** + +{% include api/editors.md editors=page.editors %} + +{% include copyright.md %} + +---- + # Presentation 4 ## Introduction @@ -639,4 +692,4 @@ For a timeline it's the ratio of time in the recording to time in the real world ### Change Log -"Exclude Audio" \ No newline at end of file +"Exclude Audio" From 00d8e9068ad01c06cb313ab79870cbb776c56abb Mon Sep 17 00:00:00 2001 From: Dawn Childress Date: Wed, 5 Feb 2025 09:54:42 -0800 Subject: [PATCH 014/130] Update index.md header --- source/presentation/4.0/index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index bc250ace9..6276819b5 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -1,5 +1,5 @@ --- -title: "Presentation API 4.0 - DRAFT" +title: "Presentation API 4.0" title_override: "IIIF Presentation API 4.0" id: presentation-api layout: spec @@ -8,7 +8,7 @@ tags: [specifications, presentation-api] major: 4 minor: 0 patch: 0 -pre: final +pre: redirect_from: - /presentation/index.html - /presentation/4/index.html @@ -41,7 +41,7 @@ __This Version:__ {{ page.major }}.{{ page.minor }}.{{ page.patch }}{% if page.p __Latest Stable Version:__ [{{ site.data.apis.presentation.latest.major }}.{{ site.data.apis.presentation.latest.minor }}.{{ site.data.apis.presentation.latest.patch }}][prezi-stable-version] -__Previous Version:__ [3.0][prezi3] +__Previous Version:__ [3.0][prezi30] **Editors:** From 8810338128ce1c99acef68c2292fa6d54e1b8013 Mon Sep 17 00:00:00 2001 From: Dawn Childress Date: Wed, 5 Feb 2025 11:13:55 -0800 Subject: [PATCH 015/130] fix internal link issues index.md --- source/presentation/4.0/index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index 6276819b5..f56f757f4 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -229,14 +229,14 @@ A Container that represents a boundless three-dimensional space and has content * has optional continuous duration in seconds A Scene in IIIF is a virtual container that represents a boundless three-dimensional space and has content resources, lights and cameras positioned at locations within it. It may also have a duration to allow the sequencing of events and timed media. Scenes have infinite height (y axis), width (x axis) and depth (z axis), where 0 on each axis (the origin of the coordinate system) is treated as the center of the scene's space. -The positive y axis points upwards, the positive x axis points to the right, and the positive z axis points forwards (a [right-handed cartesian coordinate system](link to wikipedia)). +The positive y axis points upwards, the positive x axis points to the right, and the positive z axis points forwards (a [right-handed cartesian coordinate system](https://en.wikipedia.org/wiki/Right-hand_rule)). -The axes of the coordinate system are measured in arbitrary units and these units do not necessarily correspond to any physical unit of measurement. This allows arbitrarily scaled models to be used, including very small or very large, without needing to deal with very small or very large values. If there is a correspondence to a physical scale, then this can be asserted using the [physical dimensions pattern](fwd-ref-to-phys-dims). +The axes of the coordinate system are measured in arbitrary units and these units do not necessarily correspond to any physical unit of measurement. This allows arbitrarily scaled models to be used, including very small or very large, without needing to deal with very small or very large values. If there is a correspondence to a physical scale, then this can be asserted using the physical dimensions pattern(fwd-ref-to-phys-dims). diagram of Right handed cartesian coordinate system -As with other containers in IIIF, Annotations are used to target the Scene to place content such as 3d models into the scene. Annotations are also used to add lights and cameras. A Scene can have multiple models, lights, cameras and other resources, allowing them to be grouped together. Scenes and other IIIF containers, such as Canvases, may also be embedded within Scenes, as described below in the [nesting section][fwd-ref-to-nesting]. +As with other containers in IIIF, Annotations are used to target the Scene to place content such as 3d models into the scene. Annotations are also used to add lights and cameras. A Scene can have multiple models, lights, cameras and other resources, allowing them to be grouped together. Scenes and other IIIF containers, such as Canvases, may also be embedded within Scenes, as described below in the nesting section [fwd-ref-to-nesting]. ```json { From a3ce43d65a52ff2987ede76561437c63983e7385 Mon Sep 17 00:00:00 2001 From: Dawn Childress Date: Wed, 5 Feb 2025 11:28:40 -0800 Subject: [PATCH 016/130] internal link fixes index.md --- source/presentation/4.0/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index f56f757f4..d2817da62 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -91,7 +91,7 @@ As multiple models, lights, cameras, and other resources can be associated with A Scene or a Canvas may be treated as a content resource, referenced or described within the `body` of an Annotation. As with models and other resources, the Annotation is associated with a Scene into which the Scene or Canvas is to be nested through an Annotation `target`. The content resource Scene will be placed within the `target` Scene by aligning the coordinate origins of the two scenes. Alternately, Scene Annotations may use `PointSelector` to place the origin of the resource Scene at a specified coordinate within the `target` Scene. -As with other resources, it may be appropriate to modify the initial scale, rotation, or translation of a content resource Scene prior to painting it within another Scene. Scenes associated with SpecificResources may be manipulated through the transforms described in [Transforms](transforms_section). +As with other resources, it may be appropriate to modify the initial scale, rotation, or translation of a content resource Scene prior to painting it within another Scene. Scenes associated with SpecificResources may be manipulated through the transforms described in Transforms(transforms_section). A simple example painting one Scene into another: From 602a853a463af14884e5f8fae5129ceadbe7280c Mon Sep 17 00:00:00 2001 From: Dawn Childress Date: Wed, 5 Feb 2025 11:52:12 -0800 Subject: [PATCH 017/130] add header to properties.md --- source/presentation/4.0/properties.md | 53 +++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) diff --git a/source/presentation/4.0/properties.md b/source/presentation/4.0/properties.md index 8269ebd46..b6d952cce 100644 --- a/source/presentation/4.0/properties.md +++ b/source/presentation/4.0/properties.md @@ -1,3 +1,56 @@ +--- +title: "Presentation API 4.0 Properties" +title_override: "IIIF Presentation API 4.0 Properties" +id: presentation-api-properties +layout: spec-properties +cssversion: 3 +tags: [specifications, presentation-api] +major: 4 +minor: 0 +patch: 0 +pre: +redirect_from: + - /presentation/properties.html + - /presentation/4/properties.html +editors: + - name: Michael Appleby + ORCID: https://orcid.org/0000-0002-1266-298X + institution: Yale University + - name: Tom Crane + ORCID: https://orcid.org/0000-0003-1881-243X + institution: Digirati + - name: Robert Sanderson + ORCID: https://orcid.org/0000-0003-4441-6852 + institution: J. Paul Getty Trust + - name: Dawn Childress + ORCID: + institution: UCLA + - name: Julie Winchester + ORCID: + institution: Duke University + - name: Jeff Mixter + ORCID: + institution: OCLC +hero: + image: '' +--- + +## Status of this Document +{:.no_toc} +__This Version:__ {{ page.major }}.{{ page.minor }}.{{ page.patch }}{% if page.pre != 'final' %}-{{ page.pre }}{% endif %} + +__Latest Stable Version:__ [{{ site.data.apis.presentation.latest.major }}.{{ site.data.apis.presentation.latest.minor }}.{{ site.data.apis.presentation.latest.patch }}][prezi-stable-version] + +__Previous Version:__ [3.0][prezi30] + +**Editors:** + +{% include api/editors.md editors=page.editors %} + +{% include copyright.md %} + +---- + # Vocabulary? ## Resource Classes From cb4338d127a432d28b0c8fa2f968bd2d89156c00 Mon Sep 17 00:00:00 2001 From: Rob Sanderson Date: Fri, 7 Feb 2025 14:26:24 -0500 Subject: [PATCH 018/130] updates --- source/presentation/4.0/properties.md | 135 ++++++++++++++++---------- 1 file changed, 86 insertions(+), 49 deletions(-) diff --git a/source/presentation/4.0/properties.md b/source/presentation/4.0/properties.md index b6d952cce..fc207c1d2 100644 --- a/source/presentation/4.0/properties.md +++ b/source/presentation/4.0/properties.md @@ -106,9 +106,9 @@ __Previous Version:__ [3.0][prezi30] ##### label -A human readable label, name or title. The `label` property is intended to be displayed as a short, textual surrogate for the resource if a human needs to make a distinction between it and similar resources, for example between objects, pages, or options for a choice of images to display. The `label` property can be fully internationalized, and each language can have multiple values. This pattern is described in more detail in the [languages][prezi30-languages] section. +A human readable label, name or title. The `label` property is intended to be displayed as a short, textual surrogate for the resource if a human needs to make a distinction between it and similar resources, for example between objects, pages, or options for a choice of images to display. The `label` property can be fully internationalized, and each language can have multiple values. This pattern is described in more detail in the [languages][prezi40-languages] section. -The value of the property _MUST_ be a JSON object, as described in the [languages][prezi30-languages] section. +The value of the property _MUST_ be a JSON object, as described in the [languages][prezi40-languages] section. * A Collection _MUST_ have the `label` property with at least one entry.
Clients _MUST_ render `label` on a Collection. @@ -134,7 +134,7 @@ The value of the property _MUST_ be a JSON object, as described in the [language An ordered list of descriptions to be displayed to the user when they interact with the resource, given as pairs of human readable `label` and `value` entries. The content of these entries is intended for presentation only; descriptive semantics _SHOULD NOT_ be inferred. An entry might be used to convey information about the creation of the object, a physical description, ownership information, or other purposes. -The value of the `metadata` property _MUST_ be an array of JSON objects, where each item in the array has both `label` and `value` properties. The values of both `label` and `value` _MUST_ be JSON objects, as described in the [languages][prezi30-languages] section. +The value of the `metadata` property _MUST_ be an array of JSON objects, where each item in the array has both `label` and `value` properties. The values of both `label` and `value` _MUST_ be JSON objects, as described in the [languages][prezi40-languages] section. * A Collection _SHOULD_ have the `metadata` property with at least one item.
Clients _MUST_ render `metadata` on a Collection. @@ -163,7 +163,7 @@ Clients _SHOULD_ display the entries in the order provided. Clients _SHOULD_ exp A short textual summary intended to be conveyed to the user when the `metadata` entries for the resource are not being displayed. This could be used as a brief description for item level search results, for small-screen environments, or as an alternative user interface when the `metadata` property is not currently being rendered. The `summary` property follows the same pattern as the `label` property described above. -The value of the property _MUST_ be a JSON object, as described in the [languages][prezi30-languages] section. +The value of the property _MUST_ be a JSON object, as described in the [languages][prezi40-languages] section. * A Collection _SHOULD_ have the `summary` property with at least one entry.
Clients _SHOULD_ render `summary` on a Collection. @@ -183,7 +183,7 @@ The value of the property _MUST_ be a JSON object, as described in the [language Text that _MUST_ be displayed when the resource is displayed or used. For example, the `requiredStatement` property could be used to present copyright or ownership statements, an acknowledgement of the owning and/or publishing institution, or any other text that the publishing organization deems critical to display to the user. Given the wide variation of potential client user interfaces, it will not always be possible to display this statement to the user in the client's initial state. If initially hidden, clients _MUST_ make the method of revealing it as obvious as possible. -The value of the property _MUST_ be a JSON object, that has the `label` and `value` properties, in the same way as a `metadata` property entry. The values of both `label` and `value` _MUST_ be JSON objects, as described in the [languages][prezi30-languages] section. +The value of the property _MUST_ be a JSON object, that has the `label` and `value` properties, in the same way as a `metadata` property entry. The values of both `label` and `value` _MUST_ be JSON objects, as described in the [languages][prezi40-languages] section. * Any resource type _MAY_ have the `requiredStatement` property.
Clients _MUST_ render `requiredStatement` on every resource type. @@ -200,7 +200,9 @@ The value of the property _MUST_ be a JSON object, that has the `label` and `val ##### rights -A string that identifies a license or rights statement that applies to the content of the resource, such as the JSON of a Manifest or the pixels of an image. The value _MUST_ be drawn from the set of [Creative Commons][org-cc-licenses] license URIs, the [RightsStatements.org][org-rs-terms] rights statement URIs, or those added via the [extension][prezi30-ldce] mechanism. The inclusion of this property is informative, and for example could be used to display an icon representing the rights assertions. +A string that identifies a license or rights statement that applies to the content of the resource, such as the JSON of a Manifest or the pixels of an image. The value _MUST_ be drawn from the set of [Creative Commons][org-cc-licenses] license URIs, the [RightsStatements.org][org-rs-terms] rights statement URIs, or those added via the [extension][prezi40-ldce] mechanism. The inclusion of this property is informative, and for example could be used to display an icon representing the rights assertions. + +!!! registration not extension If displaying rights information directly to the user is the desired interaction, or a publisher-defined label is needed, then it is _RECOMMENDED_ to include the information using the `requiredStatement` property or in the `metadata` property. @@ -336,7 +338,7 @@ The value _MUST_ be an [XSD dateTime literal][org-w3c-xsd-datetime]. The value _ ##### navPlace -A geographic location that clients may use for navigation purposes when presenting the resource to the user in a map-based user interface. +A geographic location that clients may use for navigation purposes when presenting the resource to the user in a map-based user interface. The location is identified using structured data, described below, with latitude and longitude based points or polygons. If the location is only textual, then the information should instead be included in the `metadata` property. The value of the property _MUST_ be a [GeoJSON Feature Collection](link) containing one or more [Features](link). The value _SHOULD_ be embedded and _MAY_ be a reference. Feature Collections referenced in the `navPlace` property _MUST_ have the `id` and `type` properties and _MUST NOT_ have the `features` property. @@ -358,14 +360,14 @@ The value of the property _MUST_ be a [GeoJSON Feature Collection](link) contain ```json-doc { "navPlace":{ - "id": "http://example.com/feature-collection/1", + "id": "https://example.com/feature-collection/1", "type": "FeatureCollection", "features":[ { - "id": "http://example.com/feature/1", + "id": "https://example.com/feature/1", "type": "Feature", - "properties":{}, "geometry":{ + "id": "https://example.com/geometry/1", "type": "Point", "coordinates":[ 9.938, @@ -544,7 +546,7 @@ The height of the Canvas or external content resource. For content resources, th The value _MUST_ be a positive integer. - * A Canvas _MAY_ have the `height` property. If it has a `height`, it _MUST_ also have a `width`.
+ * A Canvas _MUST_ have the `height` property.
Clients _MUST_ process `height` on a Canvas. * Content resources _SHOULD_ have the `height` property, with the value given in pixels, if appropriate to the resource type.
Clients _SHOULD_ process `height` on content resources. @@ -562,7 +564,7 @@ The width of the Canvas or external content resource. For content resources, the The value _MUST_ be a positive integer. - * A Canvas _MAY_ have the `width` property. If it has a `width`, it _MUST_ also have a `height`.
+ * A Canvas _MUST_ have the `width` property.
Clients _MUST_ process `width` on a Canvas. * Content resources _SHOULD_ have the `width` property, with the value given in pixels, if appropriate to the resource type.
Clients _SHOULD_ process `width` on content resources. @@ -576,12 +578,14 @@ The value _MUST_ be a positive integer. ##### duration -The duration of the Canvas or external content resource, given in seconds. +The duration of a container or external content resource, given in seconds. The value _MUST_ be a positive floating point number. - * A Canvas _MAY_ have the `duration` property.
- Clients _MUST_ process `duration` on a Canvas. + * A Timeline _MUST_ have the `duration` property.
+ Clients _MUST_ process `duration` on a Timeline. + * A Canvas or Scene _MAY_ have the `duration` property.
+ Clients _MUST_ process `duration` on a Canvas or Scene, if present. * Content resources _SHOULD_ have the `duration` property, if appropriate to the resource type.
Clients _SHOULD_ process `duration` on content resources. * Other types of resource _MUST NOT_ have a `duration`.
@@ -594,7 +598,9 @@ The value _MUST_ be a positive floating point number. ##### viewingDirection -The direction in which a set of Canvases _SHOULD_ be displayed to the user. This specification defines four direction values in the table below. Others may be defined externally [as an extension][prezi30-ldce]. +The direction in which a list of Containers _SHOULD_ be displayed to the user. This specification defines four direction values in the table below. Others may be defined externally [as an extension][prezi30-ldce]. For example, +if the `viewingDirection` value is `left-to-right`, then backwards in the list is to the left, and forwards in the +list is to the right. The value _MUST_ be a string. @@ -627,17 +633,13 @@ A set of user experience features that the publisher of the content would prefer In order to determine the behaviors that are governing a particular resource, there are four inheritance rules from resources that reference the current resource: * Collections inherit behaviors from their referencing Collection. * Manifests **DO NOT** inherit behaviors from any referencing Collections. -* Canvases inherit behaviors from their referencing Manifest, but **DO NOT** inherit behaviors from any referencing Ranges, as there might be several with different behaviors. +* Containers inherit behaviors from their referencing Manifest, but **DO NOT** inherit behaviors from any referencing Ranges, as there might be several with different behaviors. * Ranges inherit behaviors from any referencing Range and referencing Manifest. -Clients should interpret behaviors on a Range only when that Range is selected or is in some other way the context for the user's current interaction with the resources. A Range with the `behavior` value `continuous`, in a Manifest with the `behavior` value `paged`, would mean that the Manifest's Canvases should be rendered in a paged fashion, unless the range is selected to be viewed, and its included Canvases would be rendered in that context only as being virtually stitched together. This might occur, for example, when a physical scroll is cut into pages and bound into a codex with other pages, and the publisher would like to provide the user the experience of the scroll in its original form. +Clients should interpret behaviors on a Range only when that Range is selected or is in some other way the context for the user's current interaction with the resources. A Range with the `behavior` value `continuous`, in a Manifest with the `behavior` value `paged`, would mean that the Manifest's Containers should be rendered in a paged fashion, unless the range is selected to be viewed, and its included Containers would be rendered in that context only as being virtually stitched together. This might occur, for example, when a physical scroll is cut into pages and bound into a codex with other pages, and the publisher would like to provide the user the experience of the scroll in its original form. The descriptions of the behavior values have a set of which other values they are disjoint with, meaning that the same resource _MUST NOT_ have both of two or more from that set. In order to determine which is in effect, the client _SHOULD_ follow the inheritance rules above, taking the value from the closest resource. The user interface effects of the possible permutations of non-disjoint behavior values are client dependent, and implementers are advised to look for relevant recipes in the [IIIF cookbook][annex-cookbook]. -__Future Clarification Anticipated__
-Further clarifications about the implications of interactions between behavior values should be expected in subsequent minor releases. -{: .warning} - The value _MUST_ be an array of strings. * Any resource type _MAY_ have the `behavior` property with at least one item.
@@ -646,13 +648,13 @@ The value _MUST_ be an array of strings. | Value | Description | | ----- | ----------- | || **Temporal Behaviors** | -| `auto-advance`{: style="white-space:nowrap;"} | Valid on Collections, Manifests, Canvases, and Ranges that include or are Canvases with at least the `duration` dimension. When the client reaches the end of a Canvas, or segment thereof as specified in a Range, with a duration dimension that has this behavior, it _SHOULD_ immediately proceed to the next Canvas or segment and render it. If there is no subsequent Canvas in the current context, then this behavior should be ignored. When applied to a Collection, the client should treat the first Canvas of the next Manifest as following the last Canvas of the previous Manifest, respecting any `start` property specified. Disjoint with `no-auto-advance`. | -| `no-auto-advance`{: style="white-space:nowrap;"} | Valid on Collections, Manifests, Canvases, and Ranges that include or are Canvases with at least the `duration` dimension. When the client reaches the end of a Canvas or segment with a duration dimension that has this behavior, it _MUST NOT_ proceed to the next Canvas, if any. This is a default temporal behavior if not specified. Disjoint with `auto-advance`.| -| `repeat` | Valid on Collections and Manifests, that include Canvases that have at least the `duration` dimension. When the client reaches the end of the duration of the final Canvas in the resource, and the `behavior` value `auto-advance`{: style="white-space:nowrap;"} is also in effect, then the client _SHOULD_ return to the first Canvas, or segment of Canvas, in the resource that has the `behavior` value `repeat` and start playing again. If the `behavior` value `auto-advance` is not in effect, then the client _SHOULD_ render a navigation control for the user to manually return to the first Canvas or segment. Disjoint with `no-repeat`.| -| `no-repeat` | Valid on Collections and Manifests, that include Canvases that have at least the `duration` dimension. When the client reaches the end of the duration of the final Canvas in the resource, the client _MUST NOT_ return to the first Canvas, or segment of Canvas. This is a default temporal behavior if not specified. Disjoint with `repeat`.| +| `auto-advance`{: style="white-space:nowrap;"} | Valid on Collections, Manifests, Containers, and Ranges that include or are Containers with at least the `duration` dimension. When the client reaches the end of a Canvas, or segment thereof as specified in a Range, with a duration dimension that has this behavior, it _SHOULD_ immediately proceed to the next Container or segment and render it. If there is no subsequent Container in the current context, then this behavior should be ignored. When applied to a Collection, the client should treat the first Container of the next Manifest as following the last Container of the previous Manifest, respecting any `start` property specified. Disjoint with `no-auto-advance`. | +| `no-auto-advance`{: style="white-space:nowrap;"} | Valid on Collections, Manifests, Containers, and Ranges that include or are Containers with at least the `duration` dimension. When the client reaches the end of a Container or segment with a duration dimension that has this behavior, it _MUST NOT_ proceed to the next Container, if any. This is a default temporal behavior if not specified. Disjoint with `auto-advance`.| +| `repeat` | Valid on Collections and Manifests, that include Containers that have at least the `duration` dimension. When the client reaches the end of the duration of the final Container in the resource, and the `behavior` value `auto-advance`{: style="white-space:nowrap;"} is also in effect, then the client _SHOULD_ return to the first Container, or segment of a Container, in the resource that has the `behavior` value `repeat` and start playing again. If the `behavior` value `auto-advance` is not in effect, then the client _SHOULD_ render a navigation control for the user to manually return to the first Container or segment. Disjoint with `no-repeat`.| +| `no-repeat` | Valid on Collections and Manifests, that include Containers that have at least the `duration` dimension. When the client reaches the end of the duration of the final Container in the resource, the client _MUST NOT_ return to the first Container, or segment of Container. This is a default temporal behavior if not specified. Disjoint with `repeat`.| | | **Layout Behaviors** | | `unordered` | Valid on Collections, Manifests and Ranges. The resources included in resources that have this behavior have no inherent order, and user interfaces _SHOULD_ avoid implying an order to the user. Disjoint with `individuals`, `continuous`, and `paged`.| -| `individuals` | Valid on Collections, Manifests, and Ranges. For Collections that have this behavior, each of the included Manifests are distinct objects in the given order. For Manifests and Ranges, the included Canvases are distinct views, and _SHOULD NOT_ be presented in a page-turning interface. This is the default layout behavior if not specified. Disjoint with `unordered`, `continuous`, and `paged`. | +| `individuals` | Valid on Collections, Manifests, and Ranges. For Collections that have this behavior, each of the included Manifests are distinct objects in the given order. For Manifests and Ranges, the included Containers are distinct views, and _SHOULD NOT_ be presented in a page-turning interface. This is the default layout behavior if not specified. Disjoint with `unordered`, `continuous`, and `paged`. | | `continuous` | Valid on Collections, Manifests and Ranges, which include Canvases. Canvases included in resources that have this behavior are partial views and an appropriate rendering might display all of the Canvases virtually stitched together, such as a long scroll split into sections. This behavior has no implication for audio resources. The `viewingDirection` of the Manifest will determine the appropriate arrangement of the Canvases. Disjoint with `unordered`, `individuals` and `paged`. | | `paged` | Valid on Collections, Manifests and Ranges, which include Canvases. Canvases included in resources that have this behavior represent views that _SHOULD_ be presented in a page-turning interface if one is available. The first canvas is a single view (the first recto) and thus the second canvas likely represents the back of the object in the first canvas. If this is not the case, see the `behavior` value `non-paged`. Disjoint with `unordered`, `individuals`, and `continuous`. | | `facing-pages`{: style="white-space:nowrap;"} | Valid only on Canvases. Canvases that have this behavior, in a Manifest that has the `behavior` value `paged`, _MUST_ be displayed by themselves, as they depict both parts of the opening. If all of the Canvases are like this, then page turning is not possible, so simply use `individuals` instead. Disjoint with `non-paged`.| @@ -661,11 +663,11 @@ The value _MUST_ be an array of strings. | `multi-part` | Valid only on Collections. Collections that have this behavior consist of multiple Manifests or Collections which together form part of a logical whole or a contiguous set, such as multi-volume books or a set of journal issues. Clients might render these Collections as a table of contents rather than with thumbnails, or provide viewing interfaces that can easily advance from one member to the next. Disjoint with `together`.| | `together` | Valid only on Collections. A client _SHOULD_ present all of the child Manifests to the user at once in a separate viewing area with its own controls. Clients _SHOULD_ catch attempts to create too many viewing areas. This behavior _SHOULD NOT_ be interpreted as applying to the members of any child resources. Disjoint with `multi-part`.| | | **Range Behaviors** | -| `sequence` | Valid only on Ranges, where the Range is [referenced][prezi30-terminology] in the `structures` property of a Manifest. Ranges that have this behavior represent different orderings of the Canvases listed in the `items` property of the Manifest, and user interfaces that interact with this order _SHOULD_ use the order within the selected Range, rather than the default order of `items`. Disjoint with `thumbnail-nav` and `no-nav`.| +| `sequence` | Valid only on Ranges, where the Range is [referenced][prezi30-terminology] in the `structures` property of a Manifest. Ranges that have this behavior represent different orderings of the Containers listed in the `items` property of the Manifest, and user interfaces that interact with this order _SHOULD_ use the order within the selected Range, rather than the default order of `items`. 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` | Valid on Annotation Collections, Annotation Pages, Annotations, Specific Resources 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` | 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. | {: .api-table #table-behavior} {% include api/code_header.html %} @@ -708,6 +710,8 @@ Note that the majority of the values have been selected from [accessibility feat { "provides": [ "closedCaption" ] } ``` +!!! warning "This breaks the graph as the file doesn't provide X in all contexts" + ##### timeMode @@ -732,7 +736,7 @@ The value _MUST_ be a string. #### backgroundColor -This property sets the background color behind any painted resources on a spatial resource, such as a Canvas or Scene. +This property sets the background color behind any painted resources on a spatial Container, such as a Canvas or Scene. The value _MUST_ be string, which defines an RGB color. It SHOULD be a hex value starting with "#" and is treated in a case-insensitive fashion. If this property is not specified, then the default value is client-dependent. @@ -742,60 +746,86 @@ The value _MUST_ be string, which defines an RGB color. It SHOULD be a hex value Clients _SHOULD_ render `backgroundColor` on any resource type. * Other resources _MUST NOT_ have the `backgroundColor` property. -```json -"backgroundColor": "#FFFFFF" +```json-doc +{ "backgroundColor": "#FFFFFF" } ``` -
-❓Can you set bgColor on a transparent image? An area? Conflict with `style` on a SpecificResource? -
+##### position + +It is important to be able to position the (textual) body of an annotation within the Container's space that the annotation also targets. For example, a description of part of an image in a Canvas should be positioned such that it does not obscure the image region itself and labels to be displayed as part of a Scene should not be rendered such that the text is hidden by the three dimensional geometry of the model. If this property is not supplied, then the client should do its best to ensure the content is visible to the user. + +The value of this property _MUST_ be a JSON object conforming to the `SpecificResource` pattern of the Web Annotation Model. The Specific Resource _MUST_ have a `source` property that refers to a Container, and a `selector` that describes a point or region within the Container. +* A TextualBody _MAY_ have the `position` property.
+ Clients _SHOULD_ process the `position` property on TextualBody instances. +* Other classes _MUST NOT_ have the `position` property.
+ Clients _MUST_ ignore the `position` property on all other classes. + +```json-doc +{ "position": { + "type": "SpecificResource", + "source": [{ + "id": "https://example.org/iiif/scene1", + "type": "Scene" + }], + "selector": [{ + "type": "PointSelector", + "x": 1.0, + "y": 19.2, + "z": 2.7 + }] + } +} + +``` ##### near This property gives the distance from the camera from which objects are visible. Objects closer to the camera than the `near` distance cannot be seen. -The value is a non-negative floating point number. If this property is not specified, then the default value is client-dependent. +The value is a non-negative floating point number, in the coordinate space of the Scene in which the Camera is positioned. The value _MUST_ be less than the value for `far` for the same Camera. If this property is not specified, then the default value is client-dependent. * A Camera _MAY_ have the `near` property
Clients _SHOULD_ process the `near` property on Cameras. -```json -"near": 1.5 +```json-doc +{ "near": 1.5 } ``` ##### far This property gives the distance from the camera after which objects are no longer visible. Objects further from the camera than the `far` distance cannot be seen. -The value is a non-negative floating point number, and _MUST_ be greater than the value for `near` on the same camera. If this property is not specified, then the default value is client-dependent. +The value is a non-negative floating point number, in the coordinate space of the Scene in which the Camera is positioned. The value _MUST_ be greater than the value for `near` of the same Camera. If this property is not specified, then the default value is client-dependent. * A Camera _MAY_ have the `far` property
Clients _SHOULD_ process the `far` property on Cameras. -```json -"far": 200.0 +```json-doc +{ "far": 200.0 } ``` ##### fieldOfView -_Summary here_ +The angle which a PerspectiveCamera can "see". + +!!! warning "Need more info" -The value _MUST_ be a floating point number greater than 0 and less than 180. If this property is not specified, then the default value is client-dependent. +The value _MUST_ be a floating point number greater than 0 and less than 180, and is measured in degrees. If this property is not specified, then the default value is client-dependent. * A PerspectiveCamera _SHOULD_ have the `fieldOfView` property.
Clients _SHOULD_ process the `fieldOfView` property on Cameras. -```json - "fieldOfView": 50.0 +```json-doc +{ "fieldOfView": 50.0 } ``` ##### angle -_Summary here_ +!!! warning "Need more info" -The value _MUST_ be a floating point number greater than 0 and less than 90. If this property is not specified, then the default value is client-dependent. +The value _MUST_ be a floating point number greater than 0 and less than 90, and is measure in degrees. If this property is not specified, then the default value is client-dependent. * A SpotLight _SHOULD_ have the `angle` property.
Clients _SHOULD_ process the `angle` property on SpotLights. @@ -808,7 +838,11 @@ The value _MUST_ be a floating point number greater than 0 and less than 90. If _Summary here_ -The value _MUST_ be a JSON object, conforming to either a reference to an Annotation with an `id` and a `type` of "Anntoation", or a PointSelector. If this property is not specified, then the default value is null -- the camera or light is not looking at anything. +The value _MUST_ be a JSON object, conforming to either a reference to an Annotation, or an embedded PointSelector. If this property is not specified, then the default value for cameras is to look straight backwards (-Z) and for lights to point straight down (-Y). + +* A Camera _MAY_ have the `lookAt` property.
+ Clients _SHOULD_ process the `lookAt` property on Cameras. +* A SpotLight or a DirectionalLight _SHOULD_ have the `lookAt` property.
```json "lookAt": { @@ -850,7 +884,7 @@ This specification defines the unit value of "relative" which constrains the val } ``` -##### Exclude +##### exclude _Summary here_ @@ -868,6 +902,9 @@ _On Annotation, a list of strings drawn from table_ ``` + + + ##### transform _Summary here_ From 86cd0a9eab17fa99aadf7fdc5387ecf3053d4288 Mon Sep 17 00:00:00 2001 From: Dawn Childress Date: Tue, 11 Feb 2025 16:11:01 -0800 Subject: [PATCH 019/130] fix internal links --- source/presentation/4.0/properties.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/presentation/4.0/properties.md b/source/presentation/4.0/properties.md index fc207c1d2..d86fdc864 100644 --- a/source/presentation/4.0/properties.md +++ b/source/presentation/4.0/properties.md @@ -340,7 +340,7 @@ The value _MUST_ be an [XSD dateTime literal][org-w3c-xsd-datetime]. The value _ A geographic location that clients may use for navigation purposes when presenting the resource to the user in a map-based user interface. The location is identified using structured data, described below, with latitude and longitude based points or polygons. If the location is only textual, then the information should instead be included in the `metadata` property. -The value of the property _MUST_ be a [GeoJSON Feature Collection](link) containing one or more [Features](link). The value _SHOULD_ be embedded and _MAY_ be a reference. Feature Collections referenced in the `navPlace` property _MUST_ have the `id` and `type` properties and _MUST NOT_ have the `features` property. +The value of the property _MUST_ be a [GeoJSON Feature Collection] [link] containing one or more [Features] [link]. The value _SHOULD_ be embedded and _MAY_ be a reference. Feature Collections referenced in the `navPlace` property _MUST_ have the `id` and `type` properties and _MUST NOT_ have the `features` property. * A Collection _MAY_ have the `navPlace` property.
Clients _MAY_ render `navPlace` on a Collection. From 88b8d69682fb9319426e0132faee6c5542ce2fff Mon Sep 17 00:00:00 2001 From: Dawn Childress Date: Tue, 11 Feb 2025 16:33:42 -0800 Subject: [PATCH 020/130] fix layout in header --- source/presentation/4.0/properties.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/presentation/4.0/properties.md b/source/presentation/4.0/properties.md index fc207c1d2..355c1767c 100644 --- a/source/presentation/4.0/properties.md +++ b/source/presentation/4.0/properties.md @@ -2,7 +2,7 @@ title: "Presentation API 4.0 Properties" title_override: "IIIF Presentation API 4.0 Properties" id: presentation-api-properties -layout: spec-properties +layout: spec cssversion: 3 tags: [specifications, presentation-api] major: 4 From c2030dd2b87d05dd863b19339050966ae8e47003 Mon Sep 17 00:00:00 2001 From: Julie Winchester Date: Wed, 12 Feb 2025 11:42:52 -0600 Subject: [PATCH 021/130] Update index.md to include determinations from Oct 24 London working meeting --- source/presentation/4.0/index.md | 37 +++++++++++++++++++------------- 1 file changed, 22 insertions(+), 15 deletions(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index d2817da62..90031b658 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -296,6 +296,18 @@ Example Annotation that positions a model at a point within a Scene: } ``` +Annotations may alternately use a type of Selector called a `WktSelector` to align the Annotation to a region with the Scene that is not the Scene's origin. WktSelectors have a single property, `value`, which is a string conforming to a WKT Linestring, LineStringZ, Polygon, or PolygonZ list of 2D or 3D coordinate points. Whether and how a region defined by a WktSelector may be translated to a single 2D or 3D coordinate point, for targeting or other purposes, is client-dependent. + +
+❓Does WKTSelector have a duration/instant property? +
+ +Example Annotation that comments on a 3D polygon within a Scene: + +``` +Todo add example +``` + #### URI Fragments (move up, include xywh) @@ -398,10 +410,6 @@ xywh A Camera provides a view of a region of the Scene's space from a particular position within the Scene; the client constructs a viewport into the Scene and uses the view of one or more Cameras to render that region. The size and aspect ratio of the viewport is client and device dependent. -
-❓Does this prevent extension cameras from requiring a fixed aspect ratio? -
- This specification defines two types of Camera: | Class | Description | @@ -409,7 +417,7 @@ This specification defines two types of Camera: | `PerspectiveCamera` | `PerspectiveCamera` mimics the way the human eye sees, in that objects further from the camera are smaller | | `OrthographicCamera` | `OrthographicCamera` removes visual perspective, resulting in object size remaining constant regardless of its distance from the camera | -Cameras are positioned within the Scene facing in a specified direction. Both position and direction are defined through the Annotation which adds the Camera to the Scene, described below in the sections on [Painting Annotations][] and [Transforms][]. If either the position or direction is not specified, then the position defaults to the origin, and direction defaults to facing along the z axis towards negative infinity. +Cameras are positioned within the Scene facing in a specified direction. Both position and direction are defined through the Annotation which adds the Camera to the Scene, described below in the sections on [Painting Annotations][], [Transforms][], and [Relative Rotation][]. If either the position or direction is not specified, then the position defaults to the origin, and facing direction defaults to pointing along the z axis towards negative infinity. The camera's up direction by default points along the y axis towards positive infinity, but this may be modified by transforms. The region of the Scene's space that is observable by the camera is bounded by two planes orthogonal to the direction the camera is facing, given in the `near` and `far` properties, and a vertical projection angle that provides the top and bottom planes of the region. @@ -422,7 +430,7 @@ If any of these properties are not specified explicitly, they default to the cho drawing of a geometrical frustrum truncated by near and far distances -If the Scene does not have any Cameras defined within it, then the client MUST provide a default Camera. The type, properties and position of this default camera are client-dependent. +The first Camera defined and not hidden in a Scene is the default Camera used to display Scene contents. If the Scene does not have any Cameras defined within it, then the client MUST provide a default Camera. The type, properties and position of this default camera are client-dependent. ```json { @@ -518,15 +526,11 @@ Transforms are only used in the Presentation API when the SpecificResource is th #### Relative Rotation -It is useful to be able to rotate a light or camera resource such that it is facing another object or point in the Scene, rather than calculating the angles within the Scene's coordinate space. This is accomplished with a property called `lookAt`, valid on DirectionalLight, SpotLight, and all Cameras. The value of the property is either a PointSelector or the URI of an Annotation which paints something into the current Scene. +It is useful to be able to rotate a light or camera resource such that it is facing another object or point in the Scene, rather than calculating the angles within the Scene's coordinate space. This is accomplished with a property called `lookAt`, valid on DirectionalLight, SpotLight, and all Cameras. The value of the property is either a PointSelector, a WktSelector, the URI of an Annotation which paints something into the current Scene, or a Specific Resource with a selector identifying a point or region in an arbitrary container. -If the value is a PointSelector, then the light or camera resource is rotated around the x and y axes such that it is facing the given point. If the value is an Annotation which targets a point via a PointSelector, URI fragment or other mechanism, then the direction the resource is facing that point. - -
-❓What happens if the Annotation targets a Polygon or other non-Point? Calculate centroid? Error? First point given in the Poly / center of a sphere? -
+If the value is a PointSelector, then the light or camera resource is rotated around the x and y axes such that it is facing the given point. If the value is a WktSelector, then the resource should be rotated to face the given region. If the value is an Annotation which targets a point via a PointSelector, URI fragment or other mechanism, then the resource should be rotated to face that point. If the value is a Specific Resource, the source container for the Specific Resource must be painted into the current Scene, and the Specific Resource selector should identify a point or region in the source container. In this case, the light or camera resource should be rotated to face the point or region in the source container where the point or region is located within the current Scene's coordinate space. This allows light or camera resources to face a specific 2D point on a Canvas painted into a 3D scene. -This rotation happens after the resource has been added to the Scene, and thus after any transforms have taken place in the local coordinate space. As the z axis is not affected by the rotation, any RotateTransform that changes z will be retained, but any change to x or y will be lost. +This rotation happens after the resource has been added to the Scene, and thus after any transforms have taken place in the local coordinate space. ```json "lookAt": { @@ -577,23 +581,26 @@ A Canvas in a Scene has a specific forward face and a backward face. By default, A `PointSelector` can be used to modify the point at which the Canvas will be painted, by establishing a new point to align with the top-left corner of the Canvas instead of the Scene coordinate origin. Transforms can also be used to modify Canvas rotation, scale, or translation. -It may be desirable to exercise greater control over how the Canvas is painted into the Scene by selecting the coordinate points in the Scene that should correspond to each corner of the Canvas. This provides fine-grained manipulation of Canvas placement and/or scale, and for optionally introducing Canvas distortion or skew. Annotations may use a type of Selector called a `PolygonZSelector` to select different points in the Scene to align with the top-left, bottom-left, bottom-right, and top-right corners of the Canvas. PolygonZSelectors have a single property, `value`, which is a string listing a WKT `POLYGONZ` expression containing four coordinate points, with each coordinate separated by commas, and axes within a coordinate separated by spaces. The four Scene coordinates should be listed beginning with the coordinate corresponding to the top-left corner of the Canvas, and should proceed in a counter-clockwise winding order around the Canvas, with coordinates corresponding to bottom-left, bottom-right, and top-right corners in order respectively. The use of PolygonZSelector overrides any use of Transforms on the Canvas Annotation. +It may be desirable to exercise greater control over how the Canvas is painted into the Scene by selecting the coordinate points in the Scene that should correspond to each corner of the Canvas. This provides fine-grained manipulation of Canvas placement and/or scale, and for optionally introducing Canvas distortion or skew. Annotations may use a WktSelector to select different points in the Scene to align with the top-left, bottom-left, bottom-right, and top-right corners of the Canvas. In this case, the four Scene coordinates should be listed beginning with the coordinate corresponding to the top-left corner of the Canvas, and should proceed in a counter-clockwise winding order around the Canvas, with coordinates corresponding to bottom-left, bottom-right, and top-right corners in order respectively. The use of WktSelector for this purpose overrides any use of Transforms on the Canvas Annotation. Example placing top-left at (0, 1, 0); bottom-left at (0, 0, 0); bottom-right at (1, 0, 0); and top-right at (1, 1, 0): ```json "selector": [ { - "type": "PolygonZSelector", + "type": "WktSelector", "value": "POLYGONZ((0 1 0, 0 0 0, 1 0 0, 1 1 0))" } ] ``` +When a Scene is nested into another Scene, the `backgroundColor` of the Scene to be nested should be ignored as it is non-sensible to import. All Annotations painted into the Scene to be nested will be painted into the Scene into which content is being nested, including Light or Camera resources. If the Scene to be nested has one or more Camera Annotations while the Scene into which content is being nested does not, the first Camera Annotation from the nested Scene will become the default Camera for the overall Scene. ### Embedded Content e.g., painting TextualBody on Canvas +Todo: This is mostly copy-pasted from properties, is it needed here? +It is important to be able to position the textual body of an annotation within the Container's space that the annotation also targets. For example, a description of part of an image in a Canvas should be positioned such that it does not obscure the image region itself and labels to be displayed as part of a Scene should not be rendered such that the text is hidden by the three dimensional geometry of the model. The positioning of the textual body in a container is accomplished through the `position` property, which has as a value a Specific Resource identifying the targeted container as the source and a selector defining how the textual body should be positioned in the targeted container. If this property is not supplied, then the client should do its best to ensure the content is visible to the user. ### Comment Annotations From 849a5c2c83a34c82966a8ddb65c3182924041690 Mon Sep 17 00:00:00 2001 From: Rob Sanderson Date: Wed, 26 Feb 2025 12:22:33 -0500 Subject: [PATCH 022/130] updates --- .../4.0/{properties.md => model.md} | 259 ++++++++++++++---- 1 file changed, 206 insertions(+), 53 deletions(-) rename source/presentation/4.0/{properties.md => model.md} (82%) diff --git a/source/presentation/4.0/properties.md b/source/presentation/4.0/model.md similarity index 82% rename from source/presentation/4.0/properties.md rename to source/presentation/4.0/model.md index c51ceda39..48d778ee8 100644 --- a/source/presentation/4.0/properties.md +++ b/source/presentation/4.0/model.md @@ -21,7 +21,7 @@ editors: institution: Digirati - name: Robert Sanderson ORCID: https://orcid.org/0000-0003-4441-6852 - institution: J. Paul Getty Trust + institution: Yale University - name: Dawn Childress ORCID: institution: UCLA @@ -51,56 +51,202 @@ __Previous Version:__ [3.0][prezi30] ---- -# Vocabulary? - -## Resource Classes - -* Collection -* CollectionPage -* Manifest -* Containers - * Timeline - * Canvas - * Scene -* Content Resources -* Range -* Cameras - * PerspectiveCamera - * OrthographicCamera -* Lights - * AmbientLight - * DirectionalLight - * PointLight - * SpotLight -* Transforms - * TranslateTransform - * RotateTransform - * ScaleTransform -* Selectors - * PointSelector - * WktSelector (need both LineString Z and Polygon Z) - * AudioContentSelector - * VisualContentSelector - * AnimationSelector - * ImageApiSelector -* Other Classes - * Agent - * Service - * Value (used for `intensity`) - -* Annotation Classes imported from WADM: - * Annotation - * AnnotationCollection - * AnnotationPage - * SpecificResource - * FragmentSelector - * SvgSelector - * CssStyle - * TextualBody - * Choice - - -## Resource Properties +# IIIF Presentation API Data Model + +## Introduction + + +### 1.2. Terminology + +This specification uses the following terms: + +* __embedded__: When a resource (A) is embedded within an embedding resource (B), the complete JSON representation of resource A is present within the JSON representation of resource B, and dereferencing the URI of resource A will not result in additional information. Example: Canvas A is embedded in Manifest B. +* __referenced__: When a resource (A) is referenced from a referencing resource (B), an incomplete JSON representation of resource A is present within the JSON representation of resource B, and dereferencing the URI of resource A will result in additional information. Example: Manifest A is referenced from Collection B. +* __HTTP(S)__: The HTTP or HTTPS URI scheme and internet protocol. + +The terms _array_, _JSON object_, _number_, _string_, and _boolean_ in this document are to be interpreted as defined by the [Javascript Object Notation (JSON)][org-rfc-8259] specification. + +The key words _MUST_, _MUST NOT_, _REQUIRED_, _SHALL_, _SHALL NOT_, _SHOULD_, _SHOULD NOT_, _RECOMMENDED_, _MAY_, and _OPTIONAL_ in this document are to be interpreted as described in [RFC 2119][org-rfc-2119]. + + + +## Classes + +### Collection + +A Collection is an ordered list of Manifests, and/or Collections. Collections allow Manifests and child Collections to be grouped in a hierarchical structure for presentation, which can be for generating navigation, showing dynamic results from a search, or providing fixed sets of related resources for any other purpose. IIIF Collections might align with the curated management of cultural heritage resources in sets, also called "collections", but can also be used for many other purposes. + +The intended usage of Collections is to allow clients to: + + * Load a pre-defined set of Manifests at initialization time. + * Receive a set of Manifests, such as search results, for rendering. + * Visualize lists or hierarchies of related Manifests. + * Provide navigation through a list or hierarchy of available Manifests. + +The identifier in `id` _MUST_ be able to be dereferenced to retrieve the JSON description of the Collection, and thus _MUST_ use the HTTP(S) URI scheme. + +The members of a Collection are listed in the `items` property. The members _MAY_ include both other Collections and Manifests, in order, to form a tree-structured hierarchy. + +Member Collections _MAY_ be [embedded][prezi30-terminology] inline within other Collections, such as when the Collection is used primarily to subdivide a larger one into more manageable pieces, however Manifests _MUST NOT_ be [embedded][prezi30-terminology] within Collections. An [embedded][prezi30-terminology] Collection _SHOULD_ also have its own URI from which the JSON description is available. + +Manifests or Collections _MAY_ be [referenced][prezi30-terminology] from more than one Collection. For example, an institution might define four Collections: one for modern works, one for historical works, one for newspapers and one for books. The Manifest for a modern newspaper would then appear in both the modern Collection and the newspaper Collection. Alternatively, the institution may choose to have two separate newspaper Collections, and reference each as a sub-Collection of modern and historical. + +Collections with an empty `items` property are allowed but discouraged. For example, if the user performs a search that matches no Manifests, then the server _MAY_ return a Collection response with no Manifests. + +Collections or Manifests [referenced][prezi30-terminology] in the `items` property _MUST_ have the `id`, `type` and `label` properties. They _SHOULD_ have the `thumbnail` property. + + +#### CollectionPage + + + +### Manifest + +A Manifest is a description of the structure and properties of a single item to be presented to the user, such as a title and other descriptive and linking information about the object and/or the intellectual work that it conveys. The scope of what constitutes an item, and thus its Manifest, is up to the publisher of that Manifest. The Manifest contains sufficient information for the client to initialize itself and begin to display something quickly to the user. + +The identifier in `id` _MUST_ be able to be dereferenced to retrieve the JSON description of the Manifest, and thus _MUST_ use the HTTP(S) URI scheme. + +The members of a Manifest are listed in the `items` property. The members of Manifests _MUST_ be Containers, defined below, and are embedded within the Manifest. + +The Manifest _MAY_ also have a `structures` property listing one or more [Ranges][prezi30-range] which describe additional structure of the content, such as might be rendered as a table of contents. + +The Manifest _MAY_ have an `annotations` property, which includes Annotation Page resources where the Annotations have the Manifest as their `target`. These will typically be comment style Annotations, and _MUST NOT_ have `painting` as their `motivation`. + + +### Container Classes + +A Container is a frame of reference that allows the relative positioning of content, a concept borrowed from standards like PDF and HTML, or applications like Photoshop and PowerPoint, where an initially blank display surface has images, video, text and other content "painted" on to it. The frame is defined by a set of dimensions, with different types of Container having different dimensions. This specification defines three sub-classes of Container: Timeline (which only has a duration), Canvas (which has bounded height and width, and may have a duration), and Scene (which has infinite height, width and depth, and may have a duration). + +All Containers _MUST_ be identified by a URI and it _MUST_ be an HTTP(S) URI. The URI of the Container _MUST NOT_ contain a fragment (a `#` followed by further characters), as this would make it impossible to refer to a segment of the Container's area using the [media fragment syntax][org-w3c-media-frags] of `#xywh=` for spatial regions, and/or `#t=` for temporal segments. Containers _MAY_ be able to be dereferenced separately from the Manifest via their URIs as well as being [embedded][prezi30-terminology]. + +Containers have an `items` property which is a list of Annotation Pages. Each Annotation Page, defined below, maintains a list of Annotations, which associate Content Resources to be rendered as part of the Container. + +Annotations that do not associate content to be rendered, but instead are about the Container such as a comment or tag, are recorded using Annotation Pages in the `annotations` property of the Container. + +#### Timeline + +A Timeline is a Container that represents only a temporal duration, measured in seconds. Timelines allow audio content to be presented, but do not allow anything with a height or width like an image or video. The duration of the Timeline is given in the `duration` property. + +#### Canvas + +A Canvas is a Container that represents a particular rectangular 2 dimensional view of the object and has content resources associated with it or with parts of it. This aspect ratio is defined by the `height` and `width` properties. A Canvas _MAY_ also have a duration, given in the `duration` property, allowing audio and video to be correctly positioned in time as well as the 2 dimensional space. + +#### Scene + +A Scene is a Container that represents an infinitely large three-dimensional space, with an optional duration. As the Scene is infinite, it does not have `height`, `width` or `depth` properties. + +### Annotation Classes + +#### Annotation + +Annotations are primarily used to associate content resources with Containers. The same mechanism is used for the visible and/or audible resources as is used for transcriptions, commentary, tags and other content. This provides a single, unified method for aligning information, and provides a standards-based framework for distinguishing parts of resources and parts of Canvases. As Annotations can be added later, it promotes a distributed system in which publishers can align their content with the descriptions created by others. + +The IIIF Specifications adopt the W3C's [Web Annotation Data Model][org-w3c-webanno] and Vocabulary. Any necessary deviations from those specifications are explicitly noted and explained, such as the need for internationalization of labels. + +Annotations _MUST_ have their own HTTP(S) URIs, conveyed in the `id` property. The JSON-LD description of the Annotation _SHOULD_ be returned if the URI is dereferenced, according to the [Web Annotation Protocol][org-w3c-webanno-protocol]. + +When Annotations are used to associate content resources with a Canvas, the content resource is linked in the `body` of the Annotation. The URI of the Canvas _MUST_ be repeated in the `target` property of the Annotation, or the `source` property of a Specific Resource used in the `target` property. + +Content that is to be rendered as part of the Container _MUST_ be associated by an Annotation that has the `motivation` value `painting`. + + +Note that the Web Annotation data model defines different patterns for the `value` property compared to IIIF, when used within an Annotation. The `value` of a Textual Body or a Fragment Selector, for example, are strings rather than JSON objects with languages and values. Care must be taken to use the correct string form in these cases. + + +#### AnnotationCollection + +Annotation Collections allow groups of Annotations to be recorded. For example, all of the English translation Annotations of a medieval French document could be kept separate from the transcription or an edition in modern French, or the director's commentary on a film can be separated from the script. + +Annotation Collections _MUST_ have a URI, and it _SHOULD_ be an HTTP(S) URI. They _SHOULD_ have a `label` and _MAY_ have any of the other descriptive, linking or rights properties. + +Annotation Collections are paged rather than enumerated. The first page of items is linked using the `first` property, and the last page with the `last` property. The pages link to the next and previous pages in a chain, using the `next` and `prev` properties respectively. + + +#### AnnotationPage + +An ordered list of Annotations, typically associated with a Container, but may be referenced from other types of resource as well. Annotation Pages collect and order lists of Annotations. + +An Annotation Page _MUST_ have an HTTP(S) URI given in `id`, and _MAY_ have any of the other properties defined in this specification or the Web Annotation specification. The Annotations are listed in the `items` property of the Annotation Page. + +Annotations are embedded within an Annotation Page in the `items` property. + +__Incompatibility Warning__
+The definition of `label` in the Web Annotation specification does not produce JSON conformant with the structure defined in this specification for languages. Given the absolute requirement for internationalized labels and the strong desire for consistently handling properties, the `label` property on Annotation model classes does not conform to the string requirement of the Web Annotation Data Model. This [issue has been filed with the W3C][github-webanno-437] and will hopefully be addressed in a future version of the standard. +{: .warning} + + +#### SpecificResource +#### TextualBody +#### Choice +#### CssStyle + +### Content Resources + +Content resources are resources on the Web such as images, audio, video, or text which can be associated with a Container via an Annotation, or provide a representation of any resource. + +Content resources _MUST_ have an `id` property, with the value being the URI at which the resource can be obtained. + +The type of the content resource _MUST_ be included, and _SHOULD_ be taken from the table listed under the definition of `type`. The `format` of the resource _SHOULD_ be included and, if so, _SHOULD_ be the media type that is returned when the resource is dereferenced. The `profile` of the resource, if it has one, _SHOULD_ also be included. + +If the content resource is an Image, and a IIIF Image service is available for it, then the `id` property of the content resource _MAY_ be a complete URI to any particular representation supported by the Image Service, such as `https://example.org/image1/full/1000,/0/default.jpg`, but _MUST NOT_ be just the URI of the IIIF Image service. Its `type` value _MUST_ be the string `Image`. Its media type _MAY_ be listed in `format`, and its height and width _MAY_ be given as integer values for `height` and `width` respectively. The Image _SHOULD_ have the service [referenced][prezi30-terminology] from it using the `service` property. + +If there is a need to distinguish between content resources, then the resource _SHOULD_ have the `label` property. + +Containers _MAY_ be treated as content resources for the purposes of annotating on to other Containers. In this situation, the Container _MAY_ be [embedded][prezi30-terminology] within the Annotation, be a reference within the same Manifest, or require dereferencing to obtain its description. + + + +### Selectors +#### PointSelector +#### WktSelector +(need both LineString Z and Polygon Z) +#### AudioContentSelector +#### VisualContentSelector +#### AnimationSelector +#### ImageApiSelector +#### FragmentSelector +#### SvgSelector + +### Range + +Ranges are used to represent structure within an object beyond the default order of the Canvases in the `items` property of the Manifest, such as newspaper sections or articles, chapters within a book, or movements within a piece of music. Ranges can include Canvases, parts of Canvases, or other Ranges, creating a tree structure like a table of contents. + +The intent of adding a Range to the Manifest is to allow the client to display a linear or hierarchical navigation interface to enable the user to quickly move through the object's content. Clients _SHOULD_ present only Ranges that have the `label` property and do not have a `behavior` value `no-nav` to the user. Clients _SHOULD NOT_ render Canvas labels as part of the navigation, and a Range that wraps the Canvas _MUST_ be created if this is the desired presentation. + +If there is no Range that has the `behavior` value `sequence`, and the Manifest does not have the `behavior` value `unordered`, then the client _SHOULD_ treat the order of the Canvases in the Manifest's `items` array as the default order. If there is one Range that has the `behavior` value `sequence`, then the client _MUST_ instead use this Range for the ordering. If there is more than one Range that has the `behavior` value `sequence`, for example a second Range to represent an alternative ordering of the pages of a manuscript, the first Range _SHOULD_ be used as the default and the others _SHOULD_ be able to be selected. Ranges that have the `behavior` value `sequence` _MUST_ be directly within the `structures` property of the Manifest, and _MUST NOT_ be [embedded][prezi30-terminology] or [referenced][prezi30-terminology] within other Ranges. These Ranges may have limited hierarchical nesting, but clients are not expected to traverse very deep structures in determining the default order. If this Range includes parts of Canvases, then these parts are the content to render by default and would generate separate entries in a navigation display. This allows for the Canvas to include content outside of the default view, such as a color bar or ruler. + +Ranges _MUST_ have URIs and they _SHOULD_ be HTTP(S) URIs. Top level Ranges are [embedded][prezi30-terminology] or externally [referenced][prezi30-terminology] within the Manifest in a `structures` property. These top level Ranges then embed or reference other Ranges, Canvases or parts of Canvases in the `items` property. Each entry in the `items` property _MUST_ be a JSON object, and it _MUST_ have the `id` and `type` properties. If a top level Range needs to be dereferenced by the client, then it _MUST NOT_ have the `items` property, such that clients are able to recognize that it should be retrieved in order to be processed. + +All of the Canvases or parts that should be considered as being part of a Range _MUST_ be included within the Range's `items` property, or a descendant Range's `items`. + +The Canvases and parts of Canvases need not be contiguous or in the same order as in the Manifest's `items` property or any other Range. Examples include newspaper articles that are continued in different sections, a chapter that starts half way through a page, or time segments of a single canvas that represent different sections of a piece of music. + +Ranges _MAY_ link to an Annotation Collection that has the content of the Range using the `supplementary` property. The [referenced][prezi30-terminology] Annotation Collection will contain Annotations that target areas of Canvases within the Range and link content resources to those Canvases. + + + +### Scene Components +#### Cameras +##### PerspectiveCamera +##### OrthographicCamera +#### Lights +##### AmbientLight +##### DirectionalLight +##### PointLight +##### SpotLight +#### Transforms +##### TranslateTransform +##### RotateTransform +##### ScaleTransform + +### Other Classes +#### Agent +#### Service +#### Value + + + +## Properties ### Descriptive Properties @@ -598,6 +744,9 @@ The value _MUST_ be a positive floating point number. ##### viewingDirection +!!! Rewrite to be where is the navigation control to step to the next/ previous in the items of hte manifest + + The direction in which a list of Containers _SHOULD_ be displayed to the user. This specification defines four direction values in the table below. Others may be defined externally [as an extension][prezi30-ldce]. For example, if the `viewingDirection` value is `left-to-right`, then backwards in the list is to the left, and forwards in the list is to the right. @@ -645,6 +794,10 @@ The value _MUST_ be an array of strings. * Any resource type _MAY_ have the `behavior` property with at least one item.
Clients _SHOULD_ process `behavior` on any resource type. + +!!! Could continuous stitch together Timelines? + + | Value | Description | | ----- | ----------- | || **Temporal Behaviors** | @@ -871,7 +1024,7 @@ The value _MUST_ be string, which defines an RGB color. It SHOULD be a hex value This property sets the strength or brightness of a Light. -The value _MUST_ be a JSON object, that has the `type`, `value` and `unit` properties. All three properties are required. The value of `type` _MUST_ be the string "Value". The value of `value` is a floating point number. The value of `unit` is a string, drawn from a controlled vocabulary of units. If this property is not specified, then the default intensity value is client-dependent. +The value _MUST_ be a JSON object, that has the `type`, `value` and `unit` properties. All three properties are required. The value of `type` _MUST_ be the string "UnitValue". The value of `value` is a floating point number. The value of `unit` is a string, drawn from a controlled vocabulary of units. If this property is not specified, then the default intensity value is client-dependent. This specification defines the unit value of "relative" which constrains the value to be a linear scale between 0.0 (no brightness) and 1.0 (as bright as the client will render). @@ -880,7 +1033,7 @@ This specification defines the unit value of "relative" which constrains the val ```json { - "intensity": {"type": "Value", "value": 0.5, "unit": "relative"} + "intensity": {"id": "", "type": "UnitValue", "value": 0.5, "unit": "relative"} } ``` From d4b638105a44dcac4ef1e83de140ca0829f07f23 Mon Sep 17 00:00:00 2001 From: Rob Sanderson Date: Wed, 26 Feb 2025 16:29:27 -0500 Subject: [PATCH 023/130] updates for classes --- source/presentation/4.0/model.md | 170 +++++++++++++++++++++++++++++-- 1 file changed, 159 insertions(+), 11 deletions(-) diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index 48d778ee8..3b2e6b677 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -72,6 +72,10 @@ The key words _MUST_, _MUST NOT_, _REQUIRED_, _SHALL_, _SHALL NOT_, _SHOULD_, _S ## Classes +The following sub-sections define the classes used in the IIIF Presentation Data Model. The properties and relationships of the classes are defined in the following section, including which classes they are able to be used with. Only the semantics and core structural requirements are defined within this section, along with any deviations from other specifications that the classes might be drawn from. + +The descriptions also do not define how the classes are used, which is done in the Presentation API Processing Model. + ### Collection A Collection is an ordered list of Manifests, and/or Collections. Collections allow Manifests and child Collections to be grouped in a hierarchical structure for presentation, which can be for generating navigation, showing dynamic results from a search, or providing fixed sets of related resources for any other purpose. IIIF Collections might align with the curated management of cultural heritage resources in sets, also called "collections", but can also be used for many other purposes. @@ -85,7 +89,9 @@ The intended usage of Collections is to allow clients to: The identifier in `id` _MUST_ be able to be dereferenced to retrieve the JSON description of the Collection, and thus _MUST_ use the HTTP(S) URI scheme. -The members of a Collection are listed in the `items` property. The members _MAY_ include both other Collections and Manifests, in order, to form a tree-structured hierarchy. +The members of a Collection are typically listed in the `items` property. The members _MAY_ include both other Collections and Manifests, in order, to form a tree-structured hierarchy. + +If there are too many members in the collection to fit within a single document, then the members _MAY_ be listed in Collection Pages. A reference to the first page of members is given in the `first` property, and the last page in the `last` property. In this case, the Collection _MUST NOT_ use the `items` property. Member Collections _MAY_ be [embedded][prezi30-terminology] inline within other Collections, such as when the Collection is used primarily to subdivide a larger one into more manageable pieces, however Manifests _MUST NOT_ be [embedded][prezi30-terminology] within Collections. An [embedded][prezi30-terminology] Collection _SHOULD_ also have its own URI from which the JSON description is available. @@ -98,13 +104,18 @@ Collections or Manifests [referenced][prezi30-terminology] in the `items` proper #### CollectionPage +A Collection Page is an arbitrary division of members within the Collection to make it easier to consume. + +A Collection Page _MUST_ have an HTTP(S) URI given in `id`. It _MUST_ be able to be dereferenced to retrieve the JSON description of the Collection Page. + +Collection Pages follow the ActivityStreams model, as also used in Annotation Collections, the IIIF Change Discovery API, and the IIIF Search API. ### Manifest A Manifest is a description of the structure and properties of a single item to be presented to the user, such as a title and other descriptive and linking information about the object and/or the intellectual work that it conveys. The scope of what constitutes an item, and thus its Manifest, is up to the publisher of that Manifest. The Manifest contains sufficient information for the client to initialize itself and begin to display something quickly to the user. -The identifier in `id` _MUST_ be able to be dereferenced to retrieve the JSON description of the Manifest, and thus _MUST_ use the HTTP(S) URI scheme. +Manifests _MUST_ be identified by a URI and it _MUST_ be an HTTP(S) URI, given in the `id` property. It _MUST_ be able to be dereferenced to retrieve the JSON description of the Manifest. The members of a Manifest are listed in the `items` property. The members of Manifests _MUST_ be Containers, defined below, and are embedded within the Manifest. @@ -137,19 +148,18 @@ A Scene is a Container that represents an infinitely large three-dimensional spa ### Annotation Classes +The following set of classes are defined by the W3C's [Web Annotation Data Model][org-w3c-webanno] and Vocabulary, and are heavily used within the IIIF Data Model. Any necessary deviations from those specifications are explicitly noted and explained, such as the need for internationalization of labels. + #### Annotation Annotations are primarily used to associate content resources with Containers. The same mechanism is used for the visible and/or audible resources as is used for transcriptions, commentary, tags and other content. This provides a single, unified method for aligning information, and provides a standards-based framework for distinguishing parts of resources and parts of Canvases. As Annotations can be added later, it promotes a distributed system in which publishers can align their content with the descriptions created by others. -The IIIF Specifications adopt the W3C's [Web Annotation Data Model][org-w3c-webanno] and Vocabulary. Any necessary deviations from those specifications are explicitly noted and explained, such as the need for internationalization of labels. - Annotations _MUST_ have their own HTTP(S) URIs, conveyed in the `id` property. The JSON-LD description of the Annotation _SHOULD_ be returned if the URI is dereferenced, according to the [Web Annotation Protocol][org-w3c-webanno-protocol]. When Annotations are used to associate content resources with a Canvas, the content resource is linked in the `body` of the Annotation. The URI of the Canvas _MUST_ be repeated in the `target` property of the Annotation, or the `source` property of a Specific Resource used in the `target` property. Content that is to be rendered as part of the Container _MUST_ be associated by an Annotation that has the `motivation` value `painting`. - Note that the Web Annotation data model defines different patterns for the `value` property compared to IIIF, when used within an Annotation. The `value` of a Textual Body or a Fragment Selector, for example, are strings rather than JSON objects with languages and values. Care must be taken to use the correct string form in these cases. @@ -164,7 +174,7 @@ Annotation Collections are paged rather than enumerated. The first page of items #### AnnotationPage -An ordered list of Annotations, typically associated with a Container, but may be referenced from other types of resource as well. Annotation Pages collect and order lists of Annotations. +An ordered list of Annotations, typically associated with a Container, but may be referenced from other types of resource as well. Annotation Pages enumerate and order lists of Annotations, in the same way that Collection Pages order lists of Manifests and Collections within the containing Collection. An Annotation Page _MUST_ have an HTTP(S) URI given in `id`, and _MAY_ have any of the other properties defined in this specification or the Web Annotation specification. The Annotations are listed in the `items` property of the Annotation Page. @@ -176,9 +186,16 @@ The definition of `label` in the Web Annotation specification does not produce J #### SpecificResource + +A Specific Resource is a resource in the context of an Annotation. They are used to record further properties or relationships needed to understand the particular contextual use, such as which part of the resource is used or how it should be rendered. In IIIF, the Specific Resource model from the Web Annotation Data Model has some additional properties beyond those defined by the W3C, such as `transform`. + #### TextualBody + +A Textual Body is an embedded resource within an Annotation that carries, as the name suggests, a text as the body of the Annotation. It is defined by the Web Annotation Data Model, and this specification defines a new property for it `position` that allows it to be positioned within a Container. + #### Choice -#### CssStyle + +A Choice is a Web Annotation construction that allows one entry from a list to be selected for processing or display. This specification allows `behavior` to be added to a Choice to influence how it is processed. ### Content Resources @@ -194,18 +211,125 @@ If there is a need to distinguish between content resources, then the resource _ Containers _MAY_ be treated as content resources for the purposes of annotating on to other Containers. In this situation, the Container _MAY_ be [embedded][prezi30-terminology] within the Annotation, be a reference within the same Manifest, or require dereferencing to obtain its description. +### Selectors +The Web Annotation Data Model defines several Selectors, which describe how to find a specific segment of that resource to be used. As noted, the nature of Selectors are dependent on the type of resources that they select out of, and the methods needed for those descriptions will vary. The Selectors from the Web Annotation Data Model and other sources can be used within the IIIF Data Model. This specification defines additional Selector classes for use. -### Selectors #### PointSelector + +There are common use cases in which a point, rather than a range or area, is the target of the Annotation. For example, putting a pin in a map should result in an exact point, not a very small rectangle. Points in time are not very short durations, and user interfaces should also treat these differently. This is particularly important when zooming in (either spatially or temporally) beyond the scale of the frame of reference. + +Point Selectors have the following properties: + +| Name | Description | +|------|-------------| +| id | The HTTP(S) URI of the selector | +| type | The class of the selector, which must be "PointSelector" | +| x | A number (floating point or integer) giving the x coordinate of the point, relative to the dimensions of the source resource | +| y | A number (floating point or integer) giving the y coordinate of the point, relative to the dimensions of the source resource | +| z | A number (floating point or integer) giving the z coordinate of the point, relative to the dimensions of the source resource | +| t | A number (floating point or integer) giving the time of the point in seconds, relative to the duration of the source resource | + + +```json +{ + "id": "https://example.org/selectors/1", + "type": "PointSelector", + "x": 0.001, + "y": 12.3, + "z": 0, + "t": 180.0 +} +``` + + #### WktSelector -(need both LineString Z and Polygon Z) + +Well-known text, or WKT, is an ISO standard method for describing 2 and 3 dimensional geometries. This selector thus goes beyond what the Web Annotation's SvgSelector enables by incorporating the z axis, as well as additional types of selection such as MultiPolygon. Additional types, such as CIRCULARSTRING may also be supported. + +WKT Selectors have the following properties: + +| Name | Description | +|-------|-------------| +| id | The HTTP(S) URI of the selector | +| type | The class of the selector, which must be "VisualContentSelector" | +| value | The WKT string that defines the geometry to be selected | + +```json +{ + "id": "https://example.org/selectors/2", + "type": "WktSelector", + "value": "POLYGON Z (0 0 0, 10 0.5 3.2 10 5.0 0, 0 0 0)" +} +``` + + + + #### AudioContentSelector + +Video content resources consist of both visual and audio content within the same bit-level representation. There are situations when it is useful to refer to only one aspect of the content – either the visual or the audio, but not both. For example, an Annotation might associate only the visual content of a video that has spoken English in the audio, and an audio file that has the translation of that content in Spanish. The Audio Content Selector selects all of the audio content from an A/V content resource, and may be further refined with subsequent selectors to select a segment of it. + +Audio Content Selectors have the following properties: + +| Name | Description | +|------|-------------| +| id | The HTTP(S) URI of the selector | +| type | The class of the selector, which must be "AudioContentSelector" | + + +```json +{ + "id": "https://example.org/selectors/3", + "type": "AudioContentSelector" +} +``` + + #### VisualContentSelector + +Similar to Audio Content Selectors, Visual Content Selectors select the visual aspects of the content of an A/V content resource. They may be further refined by subsequent selectors that select an area or temporal segment of it. + +Visual Content Selectors have the following properties: + +| Name | Description | +|------|-------------| +| id | The HTTP(S) URI of the selector | +| type | The class of the selector, which must be "VisualContentSelector" | + +```json +{ + "id": "https://example.org/selectors/4", + "type": "VisualContentSelector" +} +``` + + #### AnimationSelector + +More interactive content resources, such as 3d models, may have activatable animations or similar features. For example, a model of a box might have an animation that opens the lid and a second animation that closes the lid. In order to activate those animations, they need to be selectable, and thus the specification defines an Animation Selector. + +Animation Selectors have the following properties: + +| Name | Description | +|-------|-------------| +| id | The HTTP(S) URI of the selector | +| type | The class of the selector, which must be "AnimationSelector" | +| value | The identity of the animation in whichever form is used by the source resource | + + +```json +{ + "id": "https://example.org/selectors/5", + "type": "AnimationSelector", + "value": "opening-1" +} +``` + #### ImageApiSelector -#### FragmentSelector -#### SvgSelector + + + ### Range @@ -828,6 +952,24 @@ The value _MUST_ be an array of strings. { "behavior": [ "auto-advance", "individuals" ] } ``` +##### interactionMode + +*within* the Scene, whereas viewingDirection and behavior are across containers. + +* Containers _MAY_ have the `interactionMode` + +Table here with values + + +locked +orbit +hemisphere-orbit +free +free-direction + +other examples: no-zoom, no-scrub, rti-mode + + ##### provides A set of features or additional functionality that a linked resource enables relative to the linking or including resource, which is not defined by the `type`, `format` or `profile` of the linked resource. It provides information as to why and how a client might want to interact with the resource, rather than what the resource is. For example, a text file (linked resource) that `provides` a `closedCaptions` for a Video (context resource), or an audio file (linked resource) that `provides` an `audioDescription` of a Canvas (context resource). @@ -1446,6 +1588,12 @@ Additional motivations may be added to the Annotation to further clarify the int | ----- | ----------- | | `painting` | Resources associated with a Canvas by an Annotation that has the `motivation` value `painting` _MUST_ be presented to the user as the representation of the Canvas. The content can be thought of as being _of_ the Canvas. The use of this motivation with target resources other than Canvases is undefined. For example, an Annotation that has the `motivation` value `painting`, a body of an Image and the target of the 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 Canvas and not positioned in some other part of the user interface.| | `supplementing` | Resources associated with a Canvas by an Annotation that has the `motivation` value `supplementing` _MAY_ be presented to the user as part of the representation of the Canvas, or _MAY_ be presented in a different part of the user interface. The content can be thought of as being _from_ the Canvas. The use of this motivation with target resources other than Canvases is undefined. For example, an Annotation that has the `motivation` value `supplementing`, a body of an Image and the target of part of the 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 Canvas 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 Canvas with audio content. | + +| `contentState` | ... content state here ...| + +| `activating` | ... activating annotations here ... | + + {: .api-table #table-motivations} From 45660d0f3bd4c144ec41858982684dea4beee40b Mon Sep 17 00:00:00 2001 From: Rob Sanderson Date: Wed, 26 Feb 2025 16:43:27 -0500 Subject: [PATCH 024/130] updates for classes --- source/presentation/4.0/model.md | 22 +++++++++------------- 1 file changed, 9 insertions(+), 13 deletions(-) diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index 3b2e6b677..03ca77df7 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -56,7 +56,7 @@ __Previous Version:__ [3.0][prezi30] ## Introduction -### 1.2. Terminology +### Terminology This specification uses the following terms: @@ -333,36 +333,32 @@ Animation Selectors have the following properties: ### Range -Ranges are used to represent structure within an object beyond the default order of the Canvases in the `items` property of the Manifest, such as newspaper sections or articles, chapters within a book, or movements within a piece of music. Ranges can include Canvases, parts of Canvases, or other Ranges, creating a tree structure like a table of contents. +Ranges are used to represent structure within a Manifest beyond the default order of the Containers in the `items` property of the Manifest, such as newspaper sections or articles, chapters within a book, or movements within a piece of music. Ranges can include Containers, parts of Containers via SpecificResources or fragment URIs, or other Ranges, creating a tree structure like a table of contents. The typical intent of adding a Range to the Manifest is to allow the client to display a linear or hierarchical navigation interface to enable the user to quickly move through the object's content. -The intent of adding a Range to the Manifest is to allow the client to display a linear or hierarchical navigation interface to enable the user to quickly move through the object's content. Clients _SHOULD_ present only Ranges that have the `label` property and do not have a `behavior` value `no-nav` to the user. Clients _SHOULD NOT_ render Canvas labels as part of the navigation, and a Range that wraps the Canvas _MUST_ be created if this is the desired presentation. - -If there is no Range that has the `behavior` value `sequence`, and the Manifest does not have the `behavior` value `unordered`, then the client _SHOULD_ treat the order of the Canvases in the Manifest's `items` array as the default order. If there is one Range that has the `behavior` value `sequence`, then the client _MUST_ instead use this Range for the ordering. If there is more than one Range that has the `behavior` value `sequence`, for example a second Range to represent an alternative ordering of the pages of a manuscript, the first Range _SHOULD_ be used as the default and the others _SHOULD_ be able to be selected. Ranges that have the `behavior` value `sequence` _MUST_ be directly within the `structures` property of the Manifest, and _MUST NOT_ be [embedded][prezi30-terminology] or [referenced][prezi30-terminology] within other Ranges. These Ranges may have limited hierarchical nesting, but clients are not expected to traverse very deep structures in determining the default order. If this Range includes parts of Canvases, then these parts are the content to render by default and would generate separate entries in a navigation display. This allows for the Canvas to include content outside of the default view, such as a color bar or ruler. - -Ranges _MUST_ have URIs and they _SHOULD_ be HTTP(S) URIs. Top level Ranges are [embedded][prezi30-terminology] or externally [referenced][prezi30-terminology] within the Manifest in a `structures` property. These top level Ranges then embed or reference other Ranges, Canvases or parts of Canvases in the `items` property. Each entry in the `items` property _MUST_ be a JSON object, and it _MUST_ have the `id` and `type` properties. If a top level Range needs to be dereferenced by the client, then it _MUST NOT_ have the `items` property, such that clients are able to recognize that it should be retrieved in order to be processed. - -All of the Canvases or parts that should be considered as being part of a Range _MUST_ be included within the Range's `items` property, or a descendant Range's `items`. - -The Canvases and parts of Canvases need not be contiguous or in the same order as in the Manifest's `items` property or any other Range. Examples include newspaper articles that are continued in different sections, a chapter that starts half way through a page, or time segments of a single canvas that represent different sections of a piece of music. - -Ranges _MAY_ link to an Annotation Collection that has the content of the Range using the `supplementary` property. The [referenced][prezi30-terminology] Annotation Collection will contain Annotations that target areas of Canvases within the Range and link content resources to those Canvases. +Ranges _MUST_ have URIs and they _SHOULD_ be HTTP(S) URIs. Top level Ranges are [embedded][prezi30-terminology] or externally [referenced][prezi30-terminology] within the Manifest in a `structures` property. These top level Ranges then embed or reference other Ranges, Containers or parts of Containers in the `items` property. Each entry in the `items` property _MUST_ be a JSON object, and it _MUST_ have the `id` and `type` properties. If a top level Range needs to be dereferenced by the client, then it _MUST NOT_ have the `items` property, such that clients are able to recognize that it should be retrieved in order to be processed. +The included Containers and parts of Containers need not be contiguous or in the same order as in the Manifest's `items` property or any other Range. Examples include newspaper articles that are continued in different sections, a chapter that starts half way through a page, or time segments of a single canvas that represent different sections of a piece of music. +Ranges _MAY_ link to an Annotation Collection that has the content of the Range using the `supplementary` property. The [referenced][prezi30-terminology] Annotation Collection will contain Annotations that target the Containers within the Range and link content resources to those Containers. ### Scene Components + #### Cameras ##### PerspectiveCamera ##### OrthographicCamera + #### Lights ##### AmbientLight ##### DirectionalLight ##### PointLight ##### SpotLight + #### Transforms ##### TranslateTransform ##### RotateTransform ##### ScaleTransform + ### Other Classes #### Agent #### Service From 323e8f58a5427c1db034632fa9434e2d9f6f36ae Mon Sep 17 00:00:00 2001 From: Michael Appleby Date: Fri, 14 Mar 2025 11:36:31 -0400 Subject: [PATCH 025/130] Fix type of WktSelector, fix small typo in TextualBody --- source/presentation/4.0/model.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index 03ca77df7..bdb567b40 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -191,7 +191,7 @@ A Specific Resource is a resource in the context of an Annotation. They are used #### TextualBody -A Textual Body is an embedded resource within an Annotation that carries, as the name suggests, a text as the body of the Annotation. It is defined by the Web Annotation Data Model, and this specification defines a new property for it `position` that allows it to be positioned within a Container. +A Textual Body is an embedded resource within an Annotation that carries, as the name suggests, a text as the body of the Annotation. It is defined by the Web Annotation Data Model, and this specification defines a new property for `position` that allows it to be positioned within a Container. #### Choice @@ -252,7 +252,7 @@ WKT Selectors have the following properties: | Name | Description | |-------|-------------| | id | The HTTP(S) URI of the selector | -| type | The class of the selector, which must be "VisualContentSelector" | +| type | The class of the selector, which must be "WktSelector" | | value | The WKT string that defines the geometry to be selected | ```json From 923d8404c509fd88d3e0d7d261cbd251278ae8c6 Mon Sep 17 00:00:00 2001 From: tomcrane Date: Sat, 15 Mar 2025 11:42:51 +0000 Subject: [PATCH 026/130] start content state 2 --- source/content-state/2.0/index.md | 840 ++++++++++++++++++++++++++++++ 1 file changed, 840 insertions(+) create mode 100644 source/content-state/2.0/index.md diff --git a/source/content-state/2.0/index.md b/source/content-state/2.0/index.md new file mode 100644 index 000000000..83cc641d2 --- /dev/null +++ b/source/content-state/2.0/index.md @@ -0,0 +1,840 @@ +--- +title: "IIIF Content State Protocols API 2.0" +title_override: "IIIF Content State Protocols API 2.0" +id: discovery-api-content-state +layout: spec +cssversion: 3 +tags: [specifications, presentation-api] +major: 2 +minor: 0 +patch: 0 +pre: draft +redirect_from: + - /content-state/index.html + - /content-state/2/index.html +pre: draft +editors: + - name: Michael Appleby + ORCID: https://orcid.org/0000-0002-1266-298X + institution: Yale University + - name: Dawn Childress + orcid: https://orcid.org/0000-0003-2602-2788 + institution: UCLA + - name: Tom Crane + ORCID: https://orcid.org/0000-0003-1881-243X + institution: Digirati + - name: Jeff Mixter + orcid: https://orcid.org/0000-0002-8411-2952 + institution: OCLC + - name: Robert Sanderson + ORCID: https://orcid.org/0000-0003-4441-6852 + institution: Yale University + - name: Julie Winchester + ORCID: + institution: Duke University +hero: + image: '' + +--- + + +## Status of this Document +{:.no_toc} +__This Version:__ {{ page.major }}.{{ page.minor }}.{{ page.patch }}{% if page.pre != 'final' %}-{{ page.pre }}{% endif %} + +__Latest Stable Version:__ [{{ site.data.apis.content-state.stable.major }}.{{ site.data.apis.content-state.stable.minor }}.{{ site.data.apis.content-state.stable.patch }}][contenstate-stable-version] + +__Previous Version:__ [1.0][contentstate09] + +**Editors** + +{% include api/editors.md editors=page.editors %} + +{% include copyright.md %} + + +---- + +## 1. Introduction +{: #introduction} + +The [IIIF Presentation API][prezi-api] defines a Content State as any IIIF Presentation API resource, or a part of a IIIF Presentation API resource, or group of resources. The Content State is a compact format that can be used to initialize a view of another (typically larger) IIIF Presentation resource in a client It might be generated by a client to transfer a particular view of a resource into another client. The [IIIF Presentation API][prezi-api] provides the format of the _content state_, and this specification T provides mechanisms for passing it between applications regardless of their different user interfaces and capabilities. + + +### 1.1. Objectives and Scope +{: #objectives-and-scope} + +The objective of the IIIF Content State API is to provide a standardized format for sharing of a particular view of one or more [IIIF Presentation API][prezi-api] resources, such as a Collection, a Manifest, or a particular part of a Manifest. + +Example use cases for sharing a resource, or a particular view of a resource, include: + +* A user follows a link from a search result, which opens a IIIF viewer. The viewer focuses on the relevant part of the object, such as a particular line of text that contains the searched-for term. +* A user opens several IIIF Manifests to compare paintings, then wishes to share this set of views with a colleague. + +Other examples include bookmarks, citations, playlists and deep linking into digital objects. + +This specification also describes how a content state is passed from one application to another, such as from a discovery platform to a viewer, so that the viewer can show the intended part of the resource (or resources) to the user. A simple example would be passing a content state description embedded within a query parameter of a URI that tells the viewer to load a IIIF Manifest. + +A viewer can also _export_ a content state, for example to enable a user to share a particular view with another user, or publish it as a reference or citation. Different IIIF clients will have different user interfaces and audiences, and may choose which of these mechanisms to support. Further detailed examples may be found in the [IIIF Cookbook][annex-cookbook]. + +The _content state_ is distinct from the state of any particular viewer's user interface. A viewer state is likely to be client-specific and would concern which panels are open, which options are selected and similar user interface details. Viewers with very different user interfaces can all implement support for the Content State API. + +This specification provides mechanisms that IIIF compatible software can use to expose, share and transfer content state descriptions, but does not specify what form IIIF compatible software itself should take. A web page, a JavaScript web application, a native mobile application, a desktop application, or display kiosk hardware are all capable of sending and receiving content states. + +The intended audience of this document is developers of applications that implement the Presentation API, although other communities may benefit as well. + + +### 1.2. Terminology +{: #terminology} + +The specification uses the following terms: + +* __HTTP(S)__: The HTTP or HTTPS URI scheme and internet protocol. + +* __array__, __JSON object__, __number__, and __string__ in this document are to be interpreted as defined by the [JavaScript Object Notation (JSON)][org-rfc-8259] specification. + +* __Annotation__ is to be interpreted as defined in the [W3C Web Annotation Data Model][org-w3c-webanno] specification. + +The key words _MUST_, _MUST NOT_, _REQUIRED_, _SHALL_, _SHALL NOT_, _SHOULD_, _SHOULD NOT_, _RECOMMENDED_, _MAY_, and _OPTIONAL_ in this document are to be interpreted as described in [RFC 2119][org-rfc-2119]. + +## 2. Content State +{: #content-state} + +A content state is a JSON-LD data structure that uses the models described by the [IIIF Presentation API][prezi-api] and [W3C Web Annotation Data Model][org-w3c-webanno] specifications. The data structure is a description of a resource, or part of a resource. This data structure can be used by clients to load the resource required, and present a particular part of the resource to the user. The state might be very simple: for example, a link to a Manifest. A more complex content state would provide more detail about the intended target. The following are all behaviors a passed-in content state might produce in a compatible client: + +* _load Manifest M_ +* _load Manifest M, navigate to Canvas C, and zoom in to the region defined by xywh=X,Y,W,H_ +* _load Manifest M, navigate such that Range R is selected, and start playing the time-based canvas C within Range R at time t=T_ + +These intentions can be expressed formally as an Annotation that targets the intended resource, or part of the resource. This content state Annotation can be easily passed into web applications, for example, as a query string parameter, or an HTML `data-` attribute, as defined in the following section on protocol and initialization mechanisms. + +### 2.1. Annotation Model for Content State + +The target of the Annotation is the described IIIF resource, using exactly the same patterns as any other IIIF-targeting Annotation that a IIIF viewer might encounter. + +The target could be any resource described by the Presentation API, for example, a: + +* Manifest +* Range +* Canvas +* spatial or temporal fragment of a Canvas +* spatial or temporal point on a Canvas + +The Annotation _MUST_ contain enough information about de-referenceable resources to show the content in context. For example, a Canvas is often not enough information for a viewer to show the intended view; the Manifest that the Canvas is part of needs to be declared so that the client can load that Manifest first, and then find the Canvas within it. + +### 2.2. Form of Annotation + +Annotations _MAY_ have one or more [motivations][org-w3c-webanno-motivation], that provide the reason(s) why it was created. For example, the `bookmarking` motivation is for annotations intended to convey a bookmark to a resource. + +A content state Annotation _MUST_ have the motivation `contentState`. This motivation is not defined by either the [W3C Web Annotation Data Model][org-w3c-webanno] or the IIIF Presentation API, and is chosen to avoid potential ambiguity when the target of the content state Annotation is itself an Annotation. The content state annotation _MAY_ also have additional motivations such as `bookmarking`, `identifying` and so on, but it is its particular `contentState` motivation that would trigger the required behavior in compatible software. + +A content state annotation can be provided in several forms, described in the following sections. + +Publishers _SHOULD_ provide the content state Annotation in one of the following forms. +A client _SHOULD_ be able to accept and process the content state in all of these forms. + +#### 2.2.1. Full Annotation + +The content state _MAY_ be supplied in JSON-LD as a fully formed Annotation compliant with the [W3C Web Annotation Data Model][org-w3c-webanno] with the motivation `contentState`, as in this example: + +```json +{ + "@context": "http://iiif.io/api/presentation/3/context.json", + "id": "https://example.org/Annotation-server/bookmarks/b1", + "type": "Annotation", + "motivation": ["contentState"], + "target": { + "id": "https://example.org/iiif/item1/manifest", + "type": "Manifest" + } +} +``` + +The target of the annotation is, in this case, a complete IIIF resource (here, a Manifest) but in more complex cases, the target could be a part of a IIIF resource. + +#### 2.2.2. Annotation URI + +The content state _MAY_ be supplied as a string whose value is the URI of an Annotation with the motivation `contentState`, that the client must dereference and process. For the example in 2.2.1 above, this would be the URI `https://example.org/Annotation-server/bookmarks/b1`. The response from that URI would be the JSON above. + +#### 2.2.3. Target Body + +The content state _MAY_ be supplied as JSON-LD, as the value of the `target` property of an implied Annotation with the motivation `contentState`. For the example in 2.2.1, this would be: + +```json +{ + "id": "https://example.org/iiif/item1/manifest", + "type": "Manifest" +} +``` + +This form is better suited to scenarios where compactness is important. + +#### 2.2.4. Target URI + +The content state _MAY_ be supplied as a string whose value is the `id` (the dereferenceable URI) of the `target` property only. This is the simplest form and is just the URI of a resource. For the example in 2.2.1, this would be the URI `https://example.org/iiif/item1/manifest`. The client would simply load this Manifest and display it. + +Examples 2.2.2 and 2.2.4 are both URIs. It is up to the client to recognise that 2.2.4 is a Manifest, whereas 2.2.2 is a content state Annotation that points to a Manifest. The client _MUST_ inspect the `type` property to determine what the dereferenced resource is. If the `type` is Annotation, the client _MUST_ also look at the `motivation` property to determine if the Annotation is a content state. If the `motivation` is not `contentState`, but the Annotation has been encountered where a content state is expected, the client _MUST_ assume that the Annotation itself is the intended IIIF content. + +If the `type` property of the target resource, once dereferenced, is `Canvas` or `Range`, then the resource _MUST_ include the Manifest URI that the Canvas or Range is to be found in, using the `partOf` property, as in example 2.2.5 below. + +#### 2.2.5. Limitations of Simple URIs + +While supporting many requirements for sharing resources and initializing a client application, the 2.2.4 form is not capable of expressing content states that are part of a IIIF resource, such as a region of a Canvas, or a Canvas URI that is not itself de-referenceable. One of the other forms must be used for these purposes. + +```json +{ + "@context": "http://iiif.io/api/presentation/3/context.json", + "id": "https://example.org/import/1", + "type": "Annotation", + "motivation": ["contentState"], + "target": { + "id": "https://example.org/object1/canvas7#xywh=1000,2000,1000,2000", + "type": "Canvas", + "partOf": [{ + "id": "https://example.org/object1/manifest", + "type": "Manifest" + }] + } +} +``` + +This description cannot be conveyed by just a Canvas URI or a Manifest URI; it needs the structure provided by a content state Annotation. It can be reduced to the target body form, but no further: + +```json +{ + "id": "https://example.org/object1/canvas7#xywh=1000,2000,1000,2000", + "type": "Canvas", + "partOf": [{ + "id": "https://example.org/object1/manifest", + "type": "Manifest" + }] +} +``` + +The requirement to dereference the URI before being able to process the content state might also have usability or performance implications around network latency. For example, if a client is processing a lot of content state Annotations, or the environment is untrusted and dereferencing unrecognized URIs to determine what they are might introduce the possibility of malicious URIs being constructed to adversely affect either the client or the publisher of the URI, then the other forms are likely to be preferred. + + +## 3. Protocols +{: #initialization} + +This section defines _Protocols_ for the transfer of this data, so that implementing software can send or receive a content state without specific knowledge of other participating software. These protocols make use of widely supported features of modern web browsers: + +* Passing a content state as a query string parameter in an HTTP GET request (3.1) +* Passing a content state as a parameter in an HTTP POST request (3.2) +* Reacting to the [Paste][org-mozilla-paste] event, where the pasted data is the URI of a content state or the full content state Annotation (3.3) +* Using the [Drag and Drop API][org-mozilla-drag-drop] to expose and accept content states (3.4) +* Uploading content state from the client machine via the [FileReader][org-mozilla-filereader] interface (3.5) +* Initialising a client via an HTML5 `data-*` attribute (3.6) + +The data structure _MAY_ be made available to the client using these protocols. Other mechanisms are possible, but outside the scope of the specification. + + +### 3.1. Linking: HTTP GET (Query String) Parameter +{: #initialization-mechanisms-link} + +If a client is capable of reading the content state from the value of an HTTP GET request parameter, it _MUST_ look for the content state in a request parameter called `iiif-content`. + +If the intention is that the linked-to client loads an entire IIIF resource without focusing on any particular part, the simplest form of the content state _SHOULD_ be used: + +```html +{% raw %} +Link to Viewer +{% endraw %} +``` + +In this case the client at `https://example.org/viewer` would load the resource at `https://damsssl.llgc.org.uk/iiif/2.0/4389767/manifest.json`, determine that it is a Manifest (rather than, say, a Collection), and process accordingly. + +When the intention is to initialize the viewer at a particular part of the resource, the client provides more than just a URI; it must provide either the full annotation as in 2.2.1., or, preferably (for brevity) the body of the annotation, as in 2.2.3. + +In both of these scenarios, the GET request parameter _MUST_ be content-state-encoded as described in [Section 6][contentstate-encoding] below. This is required to avoid potential corruption of the content state, as explained in [Section 6][contentstate-encoding]. + +In the following examples, the same Annotation is used each time. As the full JSON-LD annotation, this is: + +```json +{ + "@context": "http://iiif.io/api/presentation/3/context.json", + "id": "https://example.org/content-states/1", + "type": "Annotation", + "motivation": ["contentState"], + "target": { + "id": "https://damsssl.llgc.org.uk/iiif/2.0/4389767/canvas/4389772.json", + "type": "Canvas", + "partOf": [ + { + "id": "https://damsssl.llgc.org.uk/iiif/2.0/4389767/manifest.json", + "type": "Manifest" + } + ] + } +} +``` + +An example of this usage would be a link from search results to a particular page of a digitized book, or a stored bookmark of a particular page (i.e., Canvas). + +Without the required content-state-encoding, the (invalid) link to the viewer would look like this: + +```html +{% raw %} + +INVALID, unencoded link to Viewer +{% endraw %} +``` + +However, this JSON-LD content MUST be content-state-encoded as in [Section 6][contentstate-encoding] below: + +```html +{% raw %} +Link to Viewer +{% endraw %} +``` + +To reduce the size of the encoded content state, it _SHOULD_ be passed as just the `target` property of an implied Annotation with motivation `contentState`, that is, the fragment: + +```json +{ + "id": "https://damsssl.llgc.org.uk/iiif/2.0/4389767/canvas/4389772.json", + "type": "Canvas", + "partOf": [ + { + "id": "https://damsssl.llgc.org.uk/iiif/2.0/4389767/manifest.json", + "type": "Manifest" + } + ] +} +``` + +This results in a more compact form, unencoded (and invalid), this would be: + +```html +{% raw %} + +Link to Viewer +{% endraw %} +``` + +However, this fragment MUST be content-state-encoded as in [Section 6][contentstate-encoding] below: + +```html +{% raw %} +Link to Viewer +{% endraw %} +``` + +#### 3.1.1. Load by Reference + +This is a variant of the above, with the parameter value being a URI rather than the content itself. + +```html +Link to Viewer +``` + +If the Content State is a URI, it _MUST NOT_ be content-state-encoded. + +### 3.2. HTTP POST (Form) Parameter +{: #initialization-mechanisms-post} + + +The same data structure, in the same formats, may instead be passed to a server in an HTTP POST, for example by a JavaScript client. This is also suited to server-side web applications, such as a web page rendering citations or a view initialized on the server. It is not suitable for initialising a standalone JavaScript application, as the POST data is typically unavailable. + +The data _SHOULD_ be sent with the `Content-Type` header value `application/json`, and the body _MUST NOT_ be content-state-encoded. + +```javascript + +async function postContentState(url, contentState) { + // Default options are marked with * + const response = await fetch(url, { + method: 'POST', + mode: 'cors', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify(contentState) // body data type must match "Content-Type" header + }); + return response.json(); // parses JSON response into native JavaScript objects +} + +let target = 'https://example.com/bookmarking-service'; +let myBookmark = captureContentState(); // implementation not specified! + +postContentState(target, myBookmark) + .then(reply => { + console.log(reply); + }); +``` +In this example, the server at `https://example.com/bookmarking-service` should expect to process the _unencoded_ content state in the same forms and variants as above. + + +### 3.3. Accepting the Content State as a Paste Operation +{: #initialization-mechanisms-paste} + +The client allows the content state URI or data to be pasted into part of its UI (e.g., from a "Load..." option exposing a `textarea` element for the user to manually paste into). A client can also accept a paste operation transparently, by reading from the clipboard: + +```html + +``` + +The first parameter to `getData` is the content type, and for maximum interoperability within the scope of this specification this _MUST_ be `"text/plain"`. + +In that scenario the user can paste the content state directly into the application. If this scenario is supported, the client _SHOULD_ accept resource URIs directly, such as the URI of a Manifest. The content state _MUST NOT_ be content-state-encoded. + +Refer to [Section 3.7][contentstate-export] below for methods of exporting data, including the _Copy to Clipboard_ pattern, a natural pairing with a paste operation, from one viewer to another. + + +### 3.4. Drag and Drop +{: #initialization-mechanisms-dragdrop} + +In this scenario, one system provides a _draggable_ element: + +```html + + + +``` + +And another system provides an element capable of receiving a `drop` event: + +```html +
+ +
+ + +``` + +This technique can also be used within the same client, to drag a content state from one part to another. + +The first parameter to `setData` and `getData` is the content type, and for maximum interoperability within the scope of this specification this _MUST_ be `"text/plain"`. Applications can assert multiple additional content types for their own custom behavior, such as dragging from the application to the desktop and saving as a file, but this is outside the scope of the specification. In the above example, the content of the drag and drop operation could be a plain URI, or unencoded JSON-LD. It _MUST NOT_ be content-state-encoded. + + +### 3.5. Upload File + +A JavaScript client can accept content state from the local machine via the `FileReader` interface: + +```html +
+
+ +
+ + +``` + +The same rules apply; the viewer _MUST_ dereference and process the Annotation at that URI. The uploaded content _MUST NOT_ be content-state-encoded. + +### 3.6. Common Initialization Parameter + +If a IIIF client can accept a content state via a custom HTML attribute, then it _SHOULD_ use the attribute `data-iiif-content` for this purpose, to assist page developers using that client in understanding what the attribute is for. A viewer that accepts a content state _SHOULD_ process an Annotation in any of the forms described in the GET parameter section, but _MUST NOT_ be content-state-encoded. + +```html + +

Loading a whole manifest

+
+
+ +

Loading a manifest to show a particular Canvas

+
+
+``` + +### 3.7. Exporting Current Content State from Viewer +{: #export} + +There are further ways in which a client can _export_ its current content state, beyond populating a drag and drop operation as in example 3.4. While interoperability concerns require this specification to describe the ways in which a client can _accept_ state, the ways in which a content state might have arrived on a user's clipboard are out of scope here, and are covered in the [IIIF Cookbook][annex-cookbook]. These include: + +* Copy to Clipboard +* Download File +* Display for Copying +* Send to External Service + + +## 4. Processing Received Content States + +Once the content state has been created (following the patterns in section 2) and transferred to the receiving client (using a protocol described in section 3), the client must then process the received content state. + +If the content state is a simple URI, the client _MUST_ load the resource at that URI and process it. The resource at that URI _MUST_ be the full content state Annotation as in 2.2.2 or a IIIF Resource as in 2.2.4. That is, the dereferenced response _MUST_ be JSON-LD, and _SHOULD_ have a value of `type` taken from `Annotation`, `Collection`, `Manifest`, `Canvas` and `Range`. The response _MUST_ use UTF-8 encoding. + +If the content state is JSON-LD the client _MUST_ inspect the `type` property to decide whether the value is the full content state Annotation (indicated by the additional presence of the `contentState` motivation, as in example 2.2.1), or the value of the `target` property of an implied content state Annotation (as in example 2.2.3). + + +## 5. Examples of Content States + +The following examples demonstrate the use of the existing IIIF Presentation API and W3C Web Annotation Data Model to describe parts of resources. Any IIIF resource that can be expressed in the Presentation model can be used in a content state. The full form of the Annotation (as if it were available at the URI given in the `id` property) has been used in each case. Further examples can be found in the [IIIF Cookbook][annex-cookbook]. + +Publishers _SHOULD_ provide the simplest JSON-LD representation, and not assume that any client can handle arbitrarily complex content states. + +### 5.1. A Region of a Canvas in a Manifest + +```json +{ + "@context": "http://iiif.io/api/presentation/3/context.json", + "id": "https://example.org/import/1", + "type": "Annotation", + "motivation": ["contentState"], + "target": { + "id": "https://example.org/object1/canvas7#xywh=1000,2000,1000,2000", + "type": "Canvas", + "partOf": [{ + "id": "https://example.org/object1/manifest", + "type": "Manifest" + }] + } +} +``` + +When processed by a viewer, the user should see the rectangle `1000,2000,1000,2000` highlighted on the Canvas given in the `id` parameter; the viewer loads the manifest linked to in the `partOf` property and navigates to that canvas, and then fills the viewport with that rectangle or otherwise draws attention to it. + + +### 5.2. Start Playing at a Point in a Recording + +```json +{ + "@context": "http://iiif.io/api/presentation/3/context.json", + "id": "https://example.org/import/2", + "type": "Annotation", + "motivation": ["contentState"], + "target": { + "type": "SpecificResource", + "source": { + "id": "https://example.org/iiif/id1/canvas1", + "type": "Canvas", + "partOf": [{ + "id": "https://example.org/iiif/id1/manifest", + "type": "Manifest" + }] + }, + "selector": { + "type": "PointSelector", + "t": 14.5 + } + } +} +``` + +This example should cause a viewer to open Manifest `https://example.org/iiif/id1/manifest`, navigate to Canvas `https://example.org/iiif/id1/canvas1`, and start playing at 14.5 seconds into that canvas. + + +### 5.3. Multiple Targets for a Comparison View + +```json +{ + "@context": "http://iiif.io/api/presentation/3/context.json", + "id": "https://example.org/import/3", + "type": "Annotation", + "motivation": "contentState", + "target": [ + { + "id": "https://example.org/iiif/item1/canvas37", + "type": "Canvas", + "partOf": [ + { + "id": "https://example.org/iiif/item1/manifest", + "type": "Manifest" + } + ] + }, + { + "id": "https://example.org/iiif/item2/canvas99", + "type": "Canvas", + "partOf": [ + { + "id": "https://example.org/iiif/item2/manifest", + "type": "Manifest" + } + ] + } + ] +} +``` + +Here the viewer should open two manifests at once (if it is capable of such a view). + + +### 5.4. Search Results + +The following example uses the compact, query string form of the content state to demonstrate what HTML search results linking to a particular viewer might look like. + +Firstly, in non-valid, unencoded form to show the annotation: + +```html +

Results for "cats"

+
    +
  1. + +

    Alice in Wonderland

    +

    ...she has often seen a cat without a grin but never a grin without a cat

    +
    2. + +
+``` + +...and then in valid, content-state-encoded form: + +```html +

Results for "cats"

+
    +
  1. +

    Alice in Wonderland

    +

    ...she has often seen a cat without a grin but never a grin without a cat

    +
    2. + +
+``` + +## 6. Content State Encoding + +When a Content State is sent in an HTTP GET operation such as a query string parameter on a link in a search result or even an email, it is vulnerable to corruption - it might get encoded and re-encoded before it arrives at a viewer or other IIIF-compatible software. This section defines the requirements for safely encoding content states, to provide the string representation seen in the above examples. + +### 6.1. Choice of encoding mechanism + +A content state will contain characters from JSON syntax, and may contain strings from any language. The identifiers of annotations and other resources within the content state _MAY_ be Internationalized Resource Identifiers (IRIs), as defined in [RFC 3987][org-rfc-3987]. For these reasons the content state _MUST_ be _encoded_ using an encoding that: + +* Is simple to implement, for both decoding and encoding, in a web browser and on the server +* Will safely encode any UTF-16 string from JavaScript, avoiding known browser issues such as the ["Unicode Problem"][btoa-unicode-problem] +* Is impervious to _double encoding_ - that is, once encoded, any further likely encodings of any request or response parts will not change the already-encoded content state. + +This specification defines a two-step encoding that uses both the [encodeURIComponent][org-ecma-encodeuricomponent] function available in web browsers, followed by [Base 64 Encoding with URL and Filename Safe Alphabet][org-rfc-4648-5] ("base64url") encoding, with padding characters removed. The initial encodeURIComponent step allows any UTF-16 string in JavaScript to then be safely encoded to base64url in a web browser. The final step of removing padding removes the "=" character which might be subject to further percent-encoding as part of a URL. + +This process is described by the term _content-state-encoding_ throughout this specification. + +**Note that "base64url" is not the same encoding as "base64".** + +The process to encode a content state is: + +* encode to a UTF-8 string described by [encodeURIComponent][org-ecma-encodeuricomponent] +* encode the resulting UTF-8 string as [base64url][org-rfc-4648-5] +* remove any "=" padding characters from the end + +Conversely to decode a content state: + +* restore any removed "=" padding characters to the end of the string to make it a multiple of 4 characters long. +* decode the resulting string from base64url to a UTF-8 string +* decode the resulting UTF-8 string as described by [decodeURIComponent][org-ecma-decodeuricomponent] + +Code samples for these operations are given in the next section. + +### 6.2. Content State encoding and URI requirements + +* Any content state that is in JSON-LD form, rather than a simple URI string, _MUST_ be _content-state-encoded_ when passed as a GET parameter on a query string, and a client _MUST_ accept it in this form. + +* Content state resource identifiers must be URIs, for consistency with the IIIF Presentation API. They _MUST NOT_ contain characters that would make them [IRIs][org-rfc-3987] but not URIs, even though the [W3C Web Annotation Data Model][org-w3c-webanno] permits IRIs. + +* When the content state is a plain URI, rather than a JSON object, it _MUST NOT_ be content-state-encoded. + +* Any content state passed by mechanisms other than a HTTP GET request parameter _MUST NOT_ be content-state-encoded. + +* When published as inline, encoded JSON-LD in the full form given in section 2.2. above, the content state Annotation _MAY_ omit the `id` and `@context` properties. + +* When published on a server for clients to fetch over HTTP, in the same way a client would fetch a Manifest or Collection, content states _MUST_ be valid JSON-LD documents conforming to the [IIIF Presentation API][prezi-api] and served as described in [Section 7][contentstate-http] below. They _MUST NOT_ be content-state-encoded, but _MAY_ have other encodings appropriate for JSON content, such as `Content-Encoding: gzip` to reduce the response size. + + +### 6.3. Examples of Content State Encoding + +JavaScript and Python examples are given below. Examples for other languages and frameworks can be found in the [IIIF Cookbook][annex-cookbook]. + +#### 6.3.1. JavaScript + +```javascript +function encodeContentState(plainContentState) { + let uriEncoded = encodeURIComponent(plainContentState); // using built in function + let base64 = btoa(uriEncoded); // using built in function + let base64url = base64.replace(/\+/g, "-").replace(/\//g, "_"); + let base64urlNoPadding = base64url.replace(/=/g, ""); + return base64urlNoPadding; +} + + +function decodeContentState(encodedContentState) { + let base64url = restorePadding(encodedContentState); + let base64 = base64url.replace(/-/g, '+').replace(/_/g, '/'); + let base64Decoded = atob(base64); // using built in function + let uriDecoded = decodeURIComponent(base64Decoded); // using built in function + return uriDecoded; +} + + +function restorePadding(s) { + // The length of the restored string must be a multiple of 4 + let pad = s.length % 4; + let padding = ""; + if (pad) { + if (pad === 1) { + throw new Error('InvalidLengthError: Input base64url string is the wrong length to determine padding'); + } + s += '===='.slice(0, 4 - pad); + } + return s + padding; +} +``` + +#### 6.3.2. Python + +```python +import base64 +import urllib + +def encode_content_state(plain_content_state): + # The safe='' is required below, as the default is '/' + # We want to match the behavour of encodeURIComponent and encode '/' as '%2F' + uri_encoded = urllib.parse.quote(plain_content_state, safe='') # equivalent of encodeURIComponent + utf8_encoded = uri_encoded.encode("UTF-8") + base64url = base64.urlsafe_b64encode(utf8_encoded) + utf8_decoded = base64url.decode("UTF-8") + base64url_no_padding = utf8_decoded.replace("=", "") + return base64url_no_padding + + +def decode_content_state(encoded_content_state): + padded_content_state = restore_padding(encoded_content_state) + base64url_decoded = base64.urlsafe_b64decode(padded_content_state) + utf8_decoded = base64url_decoded.decode("UTF-8") + uri_decoded = urllib.parse.unquote(utf8_decoded) + return uri_decoded + + +def restore_padding(s): + # string length must be a multiple of 4 + pad = len(s) % 4 + padding = "" + if pad: + if pad == 1: + raise Exception("InvalidLengthError: Input base64url string is the wrong length to determine padding") + padding = "=" * (4 - pad) + return s + padding + +``` + +Given the following content state annotation: + +```json +{ + "id": "https://example.org/object1/canvas7#xywh=1000,2000,1000,2000", + "type": "Canvas", + "partOf": [{ + "id": "https://example.org/object1/manifest", + "type": "Manifest" + }] +} +``` + +The JSON can be optionally condensed to remove unnecessary whitespace: + +``` +{"id":"https://example.org/object1/canvas7#xywh=1000,2000,1000,2000","type":"Canvas","partOf":[{"id":"https://example.org/object1/manifest","type":"Manifest"}]} +``` + +The condensed form is then encoded (this example in Python): + +```python +>>> encode_content_state(condensed) + +'JTdCJTIyaWQlMjIlM0ElMjJodHRwcyUzQSUyRiUyRmV4YW1wbGUub3JnJTJGb2JqZWN0MSUyRmNhbnZhczclMjN4eXdoJTNEMTAwMCUyQzIwMDAlMkMxMDAwJTJDMjAwMCUyMiUyQyUyMnR5cGUlMjIlM0ElMjJDYW52YXMlMjIlMkMlMjJwYXJ0T2YlMjIlM0ElNUIlN0IlMjJpZCUyMiUzQSUyMmh0dHBzJTNBJTJGJTJGZXhhbXBsZS5vcmclMkZvYmplY3QxJTJGbWFuaWZlc3QlMjIlMkMlMjJ0eXBlJTIyJTNBJTIyTWFuaWZlc3QlMjIlN0QlNUQlN0Q' +``` + +The string "JTdC..." is the now URI-safe, encoded form of the content state, suitable for passing to and from web applications. + + + +## 7. HTTP Requests and Responses + +This section describes the _RECOMMENDED_ request and response interactions for the API, when served as JSON-LD bodies of HTTP responses. It does not apply to _inline_ content states, which are encoded as described in section 2.3, and transfered by the other mechanisms described above. This section follows the specification given in [Section 6][prezi30-http] of the Presentation API. + +### 7.1. Requests + +An HTTP request for a content state is the same as an HTTP request for a Presentation API resource. Unlike [IIIF Image API][image-api] requests, or other parameterized services, the URIs for Presentation API resources cannot be assumed to follow any particular pattern. A client that fetches URIs for content states and URIs for Presentation API resources (such as Manifests and Collections) by the same mechanism _MUST_ inspect the response to determine whether it is a Presentation API resource, or a content state that references part of a Presentation API resource. + +### 7.2. Responses + +The format for content states as HTTP responses is JSON, as described above. It is good practice for all resources with an HTTP(S) URI to provide their description when the URI is dereferenced. If a resource is [referenced][prezi30-terminology] within a response, rather than being [embedded][prezi30-terminology], then it _MUST_ be able to be dereferenced. + +If the server receives a request with an `Accept` header, it _SHOULD_ respond following the rules of [content negotiation][org-rfc-7231-conneg]. Note that content types provided in the `Accept` header of the request _MAY_ include parameters, for example `profile` or `charset`. + +If the request does not include an `Accept` header, the HTTP `Content-Type` header of the response _SHOULD_ have the value `application/ld+json` (JSON-LD) with the `profile` parameter given as the context document: `http://iiif.io/api/presentation/3/context.json`. + +``` none +Content-Type: application/ld+json;profile="http://iiif.io/api/presentation/3/context.json" +``` +{: .urltemplate} + +If the `Content-Type` header `application/ld+json` cannot be generated due to server configuration details, then the `Content-Type` header _SHOULD_ instead be `application/json` (regular JSON), without a `profile` parameter. + +``` none +Content-Type: application/json +``` +{: .urltemplate} + +The HTTP server _MUST_ follow the [CORS requirements][org-w3c-cors] to enable browser-based clients to retrieve the descriptions. Recipes for enabling CORS and conditional Content-Type headers are provided in the [Apache HTTP Server Implementation Notes][notes-apache]. + + +## Appendices + +### A. Acknowledgements +{: #acknowledgements} + +Many thanks to the members of the [IIIF community][iiif-community] for their continuous engagement, innovative ideas, and feedback. + +This version is due to the work of the [IIIF Discovery Technical Specification Group][groups-discovery], chaired by Antoine Isaac (Europeana), Matthew McGrattan (Digirati) and Rob Sanderson (Yale University). The IIIF Community thanks them for their leadership, and the members of the group for their tireless work. + +### B. Change Log +{: #change-log} + +| Date | Description | +| ---------- | ----------------------- | +| 2022-02-09 | Version 1.0 (Drop Dragon) | +| 2022-01-31 | Version 0.9.1 (unnamed) | +| 2021-06-21 | Version 0.9 (unnamed) | +| 2020-11-22 | Version 0.3 (unnamed) | +| 2019-02-04 | Version 0.2 (unnamed) | +| 2018-10-31 | Version 0.1 (unnamed) | + +{% include links.md %} From bf008fa19bfa5f7b444ec2c3b448653b2a73a7ec Mon Sep 17 00:00:00 2001 From: tomcrane Date: Sun, 16 Mar 2025 07:20:19 -0400 Subject: [PATCH 027/130] expansion of content state desc in P4 index.md --- source/presentation/4.0/index.md | 378 ++++++++++++++++++++++++++++++- source/presentation/4.0/model.md | 3 +- 2 files changed, 369 insertions(+), 12 deletions(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index 90031b658..0bf3c6cb9 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -361,25 +361,383 @@ use totalItems? https://iiif.io/api/discovery/1.0/#totalitems ## Content State -(introduce motivation and reasons) +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: -Separate Content State Sharing spec (protocols for sharing annotations) +A "bare" Manifest URI: -content state intended to: +``` +https://example.org/manifests/1 +``` - - load a view of some resource (existing spec) - - load a view of some resource AND modify the Container (show you my new anno, add camera) - - modify the Container in a particular context (`scope`, storytelling) - - contribute additional information permanently (rerum **inbox** - move to protocol doc) +A reference to a Manifest: -### Using Content State +```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). + +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](content-state-2) 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 + +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: + +```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" + } + ] + } +} +``` + +As well as adding resources not present in the referred-to resource, the Content State can also remove parts of the referred-to resource from the user's view by applying the behavior `hidden` to them: + +```jsonc +{ + // What does this actually look like? I want to load bnf_chateauroux example but HIDE the illumination + // ... + "id": "https://iiif.io/api/cookbook/recipe/0036-composition-from-multiple-images/annotation/p0001-image", + "type": "Annotation", + "motivation": "painting", + "behavior": ["hidden"] +} +``` + +TODO: what is the processing algorithm for applying incoming `hidden` ? + +When a Content State annotation carries a Scene, a view might be initialized from a Content State that introduces an additional Camera that shows the user the point of interest. + + +### Modify the Container in a particular context + +The techniques in the previous example are also used within a published IIIF Manifest 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. The `scope` property indicates to the client that the Content State provides valuable context for displaying some aspect of a Scene or other Container. In the case of a commenting annotation, this means that the Content State should be loaded when the commenting annotation is selected or otherwise highlighted. + + +Consider a Scene with two models, and two `commenting` annotations: + +```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/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/anno7", + "type": "Annotation", + "motivation": ["commenting"], + "bodyValue": "Mandibular tooth", + "target": { + // SpecificResource with PointSelector + } + }, + { + "id": "https://example.org/iiif/3d/anno5", + "type": "Annotation", + "motivation": ["commenting"], + "bodyValue": "Right pterygoid hamulus", + "target": { + // SpecificResource with PointSelector + } + } + ] + } + ] +} +``` + +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. It may be useful to light the Scene differently in different contexts. + +In the same way an incoming Content State can modify a Scene as it initializes the client, so can a Content State attached to each (non-`painting`) annotation target modify the Scene as the user moves between different annotations. + +The `scope` property of an annotation `target` provides _contextual_ Content State - the viewer should modify the Scene by applying the Content State carried by the `scope` property _only when the user is in the context of that annotation_. + +Taking the first commenting annotation from the above example and adding a `scope` property, whose value is an annotation with the motivation `contentState`, we can introduce a new Camera specifically for this particular annotation, so that when the user selects this comment, the client will switch the view to this camera. This example also changes the background color of the Scene: + +```jsonc +{ + "id": "https://example.org/iiif/3d/anno7", + "type": "Annotation", + "motivation": ["commenting"], + "bodyValue": "Mandibular tooth", + "target": { + + // SpecificResource with PointSelector + // "type": "SpecificResource", + // "source": ... the Scene... + // "selector": ... a point ... + + "scope": { // a modification to the Scene, only in the context of this annotation + + "id": "https://example.org/iiif/3d/anno4", + "type": "Annotation", + "motivation": ["contentState"], + "target": { + "id": "https://example.org/iiif/scene1/page/p1/1", + "type": "Scene", + "backgroundColor": "yellow", + "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.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 + } + ] + } + } + ] + } + } + } +} +``` + +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 `scope` 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 parts of the Scene for a step + - introducing additional models at a particular step + - (and many more!) + +Use of `scope` is permitted in annotations on any Container type, not just Scenes. For example, a 2D narrative around a Canvas might show or hide different `painting` annotations at each step. + +#### The `sequence` behavior + +// Is this right? Language... + +While all AnnotationPage `items` are inherently ordered, an Annotation Page with the behavior `sequence` is explicitly a narrative, and clients should prevent (dissuade) users from jumping about. The presence of `sequence` affects the way a client should interpret the `reset` property described below. + +### Content States on Manifests + +When an annotation with the motivation `contentState` is provided via the `annotations` property of a Manifest, rather than contextually via `scope`, it is assumed to be generally available for selection by the user at any time. A client may present such as annotations as a menu of views, allowing arbitrary jumping into any Scene (or Canvas or Timeline) from any other point. + +// Is there some overlap here with Range? + +### Processing Content States in Scopes: reset + +// This may not be what we have discussed... + +When a Content State is applied to a Container such as a Scene, it is assumed to be a "diff" - for example if 3 cameras and 4 lights are already present in the Scene, and a Content State asserts a single new Camera, the default behavior is to add this fourth Camera to the Scene and leave the existing resources as they are. + +The client should reset the Container to its original state before applying the diff operation. However, for narratives that cumulatively build a Scene this may lead to excessively verbose Manifests. When moving through the items of an Annotation page with the behavior `sequence`, the Container is not reset and the diff is cumulative; modifications from one `scope` persist into the next. If this behavior is not wanted, the `reset` property of the content state annotation should be set to `true`: + +```json +{ + "type": "Annotation", + "motivation": ["contentState"], + "reset": true +} +``` + +Before applying the content state to the Scene, the client should reset the Scene to its original state as provided by the Manifest. + +// I am assuming reset is always true except in `sequence` - otherwise it's completely unpredictable!! or is it... arbitrary navigation, state provided by initialization content states, etc... + +### Contribute additional information permanently + +Rerum inbox scenario - should be covered in CS2 protocol + +### activating + +Extension of hotspot linking + +An annotation with the motivation `activating` can also carry a Content State in its body. + +There are two uses of the `activating` annotation: + +- triggering a content state +- triggering a named animation -(not in section 6) ### reset -"diff", "original state" etc +See above... +"diff", "original state" etc behavior for "force-order"? behavior: sequence diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index 03ca77df7..4860f7bd6 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -1584,8 +1584,7 @@ Additional motivations may be added to the Annotation to further clarify the int | ----- | ----------- | | `painting` | Resources associated with a Canvas by an Annotation that has the `motivation` value `painting` _MUST_ be presented to the user as the representation of the Canvas. The content can be thought of as being _of_ the Canvas. The use of this motivation with target resources other than Canvases is undefined. For example, an Annotation that has the `motivation` value `painting`, a body of an Image and the target of the 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 Canvas and not positioned in some other part of the user interface.| | `supplementing` | Resources associated with a Canvas by an Annotation that has the `motivation` value `supplementing` _MAY_ be presented to the user as part of the representation of the Canvas, or _MAY_ be presented in a different part of the user interface. The content can be thought of as being _from_ the Canvas. The use of this motivation with target resources other than Canvases is undefined. For example, an Annotation that has the `motivation` value `supplementing`, a body of an Image and the target of part of the 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 Canvas 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 Canvas with audio content. | - -| `contentState` | ... content state here ...| +| `contentState` | An annotation with the motivation `contentState` | | `activating` | ... activating annotations here ... | From adfcc6d08e45a49eb86d34500e21bd0a43d32c27 Mon Sep 17 00:00:00 2001 From: tomcrane Date: Mon, 17 Mar 2025 05:41:55 -0400 Subject: [PATCH 028/130] describe activating motivation --- source/presentation/4.0/index.md | 161 +++++++++++++++++++++++++++++-- 1 file changed, 155 insertions(+), 6 deletions(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index 0bf3c6cb9..a23df8799 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -469,6 +469,8 @@ A Scene with a Camera at a particular point: 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 @@ -721,16 +723,163 @@ Before applying the content state to the Scene, the client should reset the Scen Rerum inbox scenario - should be covered in CS2 protocol -### activating +### activating - animation and interactions + +Annotations with the motivation `activating` are referred to as _activating_ annotations. + +There are two uses of `activating` annotations: -Extension of hotspot linking +#### Triggering a content state -An annotation with the motivation `activating` can also carry a Content State in its body. +An activating annotation links a painting annotation to a content state. When a user interacts with the painting annotation - whether through clicking it, tapping it, or other client-specific behaviors - the linked content state should be processed to modify the Scene or other Container, as in the previous examples. The painting annotation is the target of the activating annotation, and the content state is the body value. Only one content state may be specified in the body array, but the body array may include a `TextualBody` to provide a label for the interaction. The pattern is the same as for the `linking` motivation, but rather than the client opening a new browser window on the resource specified in the `body`, it applies the modification provided by the Content State. + +The activating annotation is provided in a Container's `annotations` property. In this (contrived for brevity) example, if the user clicks the mandible model, the Scene background changes color: + +```jsonc +{ + "id": "https://example.org/iiif/3d/activating.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/scene-with-activation", + "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/painting-anno-for-mandible", + "type": "Annotation", + "motivation": ["painting"], + "body": { + "id": "https://raw.githubusercontent.com/IIIF/3d/main/assets/whale/whale_mandible.glb", + "type": "Model" + }, + "target": { + // SpecificResource with PointSelector + } + } + ], + "annotations": [ + { + "id": "https://example.org/iiif/scene1/page/activators", + "type": "AnnotationPage", + "items": [ + { + "id": "https://example.org/iiif/3d/anno2", + "type": "Annotation", + "motivation": ["activating"], + "body": [ + { + "type": "TextualBody", + "value": "A label for the activation may be provided as a TextualBody" + }, + { + // A body where the type is a IIIF Resource (eg Scene) is the Content State to apply + "id": "https://example.org/iiif/scene1/scene-with-activation", + "type": "Scene", + "backgroundColor": "#FF99AA" + } + ], + "target": { + "id": "https://example.org/iiif/3d/painting-anno-for-mandible", + "type": "Annotation" + } + } + ] + } + ] + } + ] + } + ] +} +``` -There are two uses of the `activating` annotation: +// Can you put activating annotations in `manifest.annotations`? They would work there too, you have all the information. -- triggering a content state -- triggering a named animation + + +#### 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. + +This pattern is similar to the above, except that: + + - There is no Content State in the `body`, but there _MUST_ be a TextualBody to label the interaction. (?? must?) + - The `target` selects a _named animation_ in the model. The `target` MUST be a SpecificResource, where the `source` is the painting annotation that paints the model, and the `selector` is of type `AnimationSelector` with the `value` being a string that corresponds to the animation in the model. + + The format of the `value` string is implementation=specific, and will depend on how different 3D formats support addressing of animations within models. + + +```jsonc +{ + "id": "https://example.org/iiif/3d/activating-animation.json", + "type": "Manifest", + "label": { "en": ["Music Box with lid that opens as an internal animation"] }, + "items": [ + { + "id": "https://example.org/iiif/scene1/scene-with-activation-animation", + "type": "Scene", + "label": { "en": ["A Scene Containing a Music Box"] }, + "items": [ + { + "id": "https://example.org/iiif/scene-with-activation-animation/page/p1/1", + "type": "AnnotationPage", + "items": [ + { + "id": "https://example.org/iiif/3d/painting-anno-for-music-box", + "type": "Annotation", + "motivation": ["painting"], + "body": { + "id": "https://raw.githubusercontent.com/IIIF/3d/main/assets/music-box.glb", + "type": "Model" + }, + "target": { + // SpecificResource with PointSelector + } + } + ], + "annotations": [ + { + "id": "https://example.org/iiif/scene1/page/activators", + "type": "AnnotationPage", + "items": [ + { + "id": "https://example.org/iiif/3d/anno2", + "type": "Annotation", + "motivation": ["activating"], + "body": [ + { + "type": "TextualBody", + "value": "Click the box to open the lid" + } + ], + "target": [ + { + "type": "SpecificResource", + "source": "https://example.org/iiif/3d/painting-anno-for-music-box", + "selector": [ + { + "type": "AnimationSelector", + "value": "open-the-lid" + } + ] + } + ] + } + ] + } + ] + } + ] + } + ] +} +``` ### reset From 3a422f81cd91130836ed0b6129c3249b9cfc24c6 Mon Sep 17 00:00:00 2001 From: tomcrane Date: Mon, 17 Mar 2025 06:18:53 -0400 Subject: [PATCH 029/130] contentState and activating motivations, WIP --- source/presentation/4.0/index.md | 11 ++++++++++- source/presentation/4.0/model.md | 10 +++++----- 2 files changed, 15 insertions(+), 6 deletions(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index a23df8799..822e068f7 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -812,7 +812,8 @@ This pattern is similar to the above, except that: - There is no Content State in the `body`, but there _MUST_ be a TextualBody to label the interaction. (?? must?) - The `target` selects a _named animation_ in the model. The `target` MUST be a SpecificResource, where the `source` is the painting annotation that paints the model, and the `selector` is of type `AnimationSelector` with the `value` being a string that corresponds to the animation in the model. - The format of the `value` string is implementation=specific, and will depend on how different 3D formats support addressing of animations within models. + The format of the `value` string is implementation=specific, and will depend on how different 3D formats support addressing of animations within models. The same model can be painted multiple times into the scene, and you might want to activate only one model's animation, thus we need to refer to the annotation that paints the model, not the model directly. + ```jsonc @@ -881,6 +882,14 @@ This pattern is similar to the above, except that: } ``` +// TODO + +activating to apply a content state and activating to trigger a named animation - use of body and target... what if we want to click a painting anno to trigger the animation? +Can we ADD that to the target, alongside the SpecificResource with the AnimationSelector? + +if the `target` is an AnimationSelector, then the `body` can ONLY be TextualBody (or list of TextualBody)? + +There is a more general rule here! ### reset diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index 4860f7bd6..49d2cf69d 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -1582,12 +1582,12 @@ Additional motivations may be added to the Annotation to further clarify the int | Value | Description | | ----- | ----------- | -| `painting` | Resources associated with a Canvas by an Annotation that has the `motivation` value `painting` _MUST_ be presented to the user as the representation of the Canvas. The content can be thought of as being _of_ the Canvas. The use of this motivation with target resources other than Canvases is undefined. For example, an Annotation that has the `motivation` value `painting`, a body of an Image and the target of the 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 Canvas and not positioned in some other part of the user interface.| -| `supplementing` | Resources associated with a Canvas by an Annotation that has the `motivation` value `supplementing` _MAY_ be presented to the user as part of the representation of the Canvas, or _MAY_ be presented in a different part of the user interface. The content can be thought of as being _from_ the Canvas. The use of this motivation with target resources other than Canvases is undefined. For example, an Annotation that has the `motivation` value `supplementing`, a body of an Image and the target of part of the 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 Canvas 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 Canvas with audio content. | -| `contentState` | An annotation with the motivation `contentState` | - -| `activating` | ... activating annotations here ... | +| `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. | +| `contentState` | An annotation with the motivation `contentState` has any valid IIIF Resource, or list of IIIF resources, or references to IIIF resources as its `target` property. The client either loads the resource(s) indicated by the Content State annotation `target`, or modifies the view of a currently loaded resource by applying the changes implied by the annotation target - for example, adding a new Light to a Scene where the Light is first introduced in the annotation `target`. The expected interaction depends on how the annotation is linked to the resource the client is currently rendering, or how the annotation is introduced to the client. The [Content State Protocol API 2.0](link) describes the ways in which a Content State may be conveyed into a Client or exported from a Client, e.g., as an initialization parameter, or as an exported "Share..." state. Other parts (...) of this specification describe how a Content State in the context of a `commenting` or other annotation modifies the Container when the user selects that annotation, such as changing the camera, lighting or even the models in a Scene as the user progresses though the steps of a narrative conveyed by `describing` annotations. | +| `activating` | 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. It indicates that a user interaction will trigger a change in either the Container itself, 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. If the `body` contains IIIF resources, then the body is interpreted as a Content State, and when the user interacts with the IIIF resource provided by the `target`, the content state is applied to modify the Container. | +// See notes on activating in index {: .api-table #table-motivations} From f7c088ef4f97da9e85f716f9d8f6f388695a5341 Mon Sep 17 00:00:00 2001 From: tomcrane Date: Mon, 17 Mar 2025 16:42:41 -0400 Subject: [PATCH 030/130] new index --- source/content-state/2.0/index.md | 10 +- source/presentation/4.0/index-draft.md | 1218 ++++++++++++++++++++++++ source/presentation/4.0/index.md | 1158 ++-------------------- 3 files changed, 1306 insertions(+), 1080 deletions(-) create mode 100644 source/presentation/4.0/index-draft.md diff --git a/source/content-state/2.0/index.md b/source/content-state/2.0/index.md index 83cc641d2..9afb4e15f 100644 --- a/source/content-state/2.0/index.md +++ b/source/content-state/2.0/index.md @@ -156,7 +156,7 @@ The target of the annotation is, in this case, a complete IIIF resource (here, a The content state _MAY_ be supplied as a string whose value is the URI of an Annotation with the motivation `contentState`, that the client must dereference and process. For the example in 2.2.1 above, this would be the URI `https://example.org/Annotation-server/bookmarks/b1`. The response from that URI would be the JSON above. -#### 2.2.3. Target Body +#### 2.2.3. Target Body // see #2294 The content state _MAY_ be supplied as JSON-LD, as the value of the `target` property of an implied Annotation with the motivation `contentState`. For the example in 2.2.1, this would be: @@ -236,6 +236,8 @@ If a client is capable of reading the content state from the value of an HTTP GE If the intention is that the linked-to client loads an entire IIIF resource without focusing on any particular part, the simplest form of the content state _SHOULD_ be used: +// Talk about URI encoding here, as per #2292 + ```html {% raw %} Link to Viewer @@ -276,7 +278,7 @@ Without the required content-state-encoding, the (invalid) link to the viewer wo ```html {% raw %} -INVALID, unencoded link to Viewer +INVALID, unencoded link to Viewer {% endraw %} ``` @@ -571,7 +573,7 @@ This example should cause a viewer to open Manifest `https://example.org/iiif/id "@context": "http://iiif.io/api/presentation/3/context.json", "id": "https://example.org/import/3", "type": "Annotation", - "motivation": "contentState", + "motivation": ["contentState"], "target": [ { "id": "https://example.org/iiif/item1/canvas37", @@ -719,6 +721,8 @@ function restorePadding(s) { #### 6.3.2. Python +// Add in one for query string as #2292 + ```python import base64 import urllib diff --git a/source/presentation/4.0/index-draft.md b/source/presentation/4.0/index-draft.md new file mode 100644 index 000000000..822e068f7 --- /dev/null +++ b/source/presentation/4.0/index-draft.md @@ -0,0 +1,1218 @@ +--- +title: "Presentation API 4.0" +title_override: "IIIF Presentation API 4.0" +id: presentation-api +layout: spec +cssversion: 3 +tags: [specifications, presentation-api] +major: 4 +minor: 0 +patch: 0 +pre: +redirect_from: + - /presentation/index.html + - /presentation/4/index.html +editors: + - name: Michael Appleby + ORCID: https://orcid.org/0000-0002-1266-298X + institution: Yale University + - name: Tom Crane + ORCID: https://orcid.org/0000-0003-1881-243X + institution: Digirati + - name: Robert Sanderson + ORCID: https://orcid.org/0000-0003-4441-6852 + institution: J. Paul Getty Trust + - name: Dawn Childress + ORCID: + institution: UCLA + - name: Julie Winchester + ORCID: + institution: Duke University + - name: Jeff Mixter + ORCID: + institution: OCLC +hero: + image: '' +--- + +## Status of this Document +{:.no_toc} +__This Version:__ {{ page.major }}.{{ page.minor }}.{{ page.patch }}{% if page.pre != 'final' %}-{{ page.pre }}{% endif %} + +__Latest Stable Version:__ [{{ site.data.apis.presentation.latest.major }}.{{ site.data.apis.presentation.latest.minor }}.{{ site.data.apis.presentation.latest.patch }}][prezi-stable-version] + +__Previous Version:__ [3.0][prezi30] + +**Editors:** + +{% include api/editors.md editors=page.editors %} + +{% include copyright.md %} + +---- + +# Presentation 4 + +## Introduction + +Manifests, Containers, Annotations oh my! +Manifest as unit of distribution + + +## Content Resources + +There is stuff that we want to show - images, video, audio, 3D models etc + +### type value of Content Resources + +| Class | Description | +| ------------- | -------------------------------- | +| `Image` | Two dimensional visual resources primarily intended to be seen, such as might be rendered with an <img> HTML tag | +| `Model` | A three (or more) dimensional model intended to be interacted with by humans | +| `Sound` | Auditory resources primarily intended to be heard, such as might be rendered with an <audio> HTML tag | +| `Text` | Resources primarily intended to be read | +| `Video` | Moving images, with or without accompanying audio, such as might be rendered with a <video> HTML tag | +{: .api-table #table-type} + +## Containers + +This is where we put content resources +"painting" + +And we can also put other things: +"supplementing" + +And we can nest them +"Nesting" (see 3d draft) + +The defined Container types are `Timeline`, `Canvas` and `Scene`. Extensions may define additional Container types. + +As multiple models, lights, cameras, and other resources can be associated with and placed within a Scene container, Scenes provide a straightforward way of grouping content resources together within a space. Scenes, as well as other IIIF containers such as Canvases, can also be embedded within a Scene, allowing for the nesting of content resources. + +A Scene or a Canvas may be treated as a content resource, referenced or described within the `body` of an Annotation. As with models and other resources, the Annotation is associated with a Scene into which the Scene or Canvas is to be nested through an Annotation `target`. The content resource Scene will be placed within the `target` Scene by aligning the coordinate origins of the two scenes. Alternately, Scene Annotations may use `PointSelector` to place the origin of the resource Scene at a specified coordinate within the `target` Scene. + +As with other resources, it may be appropriate to modify the initial scale, rotation, or translation of a content resource Scene prior to painting it within another Scene. Scenes associated with SpecificResources may be manipulated through the transforms described in Transforms(transforms_section). + +A simple example painting one Scene into another: + +```json +{ + "id": "https://example.org/iiif/3d/anno1", + "type": "Annotation", + "motivation": ["painting"], + "body": { + "id": "https://example.org/iiif/scene1", + "type": "Scene" + }, + "target": "https://example.org/iiif/scene2" +} +``` + + +Content resources of the appropriate dimension(s) may be annotated into a Container that has those dimensions. + + +### Timeline + +A Container that represents a bounded temporal range, without any spatial coordinates. + +* has continuous duration in seconds + for all or part of its duration. + + +A Timeline _MUST_ have a `duration` property that defines its length in seconds. The `duration` value must be a positive floating point number. + +An annotation that targets a Scene using a PointSelector without any temporal refinement implicitly targets the Scene's entire duration. + +A content resource may be annotated into a Scene for a period of time by use of a PointSelector that is temporally scoped by a [FragmentSelector](https://www.w3.org/TR/annotation-model/#fragment-selector). The FragmentSelector has a `value` property, the value of which follows the [media fragment syntax](https://www.w3.org/TR/media-frags/#naming-time) of `t=`. This annotation pattern uses the `refinedBy` property [defined by the W3C Web Annotation Data Model](https://www.w3.org/TR/annotation-model/#refinement-of-selection). + +```json +{ + "id": "https://example.org/iiif/3d/anno1", + "type": "Annotation", + "motivation": ["painting"], + "body": { + "id": "https://example.org/iiif/assets/model1.glb", + "type": "Model" + }, + "target": { + "type": "SpecificResource", + "source": [ + { + "id": "https://example.org/iiif/scene1", + "type": "Scene" + } + ], + "selector": [ + { + "type": "PointSelector", + "x": -1.0, + "y": -1.0, + "z": 3.0, + "refinedBy": { + "type": "FragmentSelector", + "value": "t=45,95" + } + } + ] + } +} +``` + +When using a URL fragment in place of a SpecificResource, the parameter `t` can be used to select the temporal region: + +```json +{ + "id": "https://example.org/iiif/3d/anno1", + "type": "Annotation", + "motivation": ["painting"], + "body": { + "id": "https://example.org/iiif/assets/model1.glb", + "type": "Model" + }, + "target": "https://example.org/iiif/scene1#xyz=-1,-1,3&t=45,95" +} +``` + +An Annotation may target a specific point in time using a PointSelector's `instant` property. The property's value must be a positive floating point number indicating a value in seconds that falls within the Scene's duration. + +```json +{ + "id": "https://example.org/iiif/3d/anno1", + "type": "Annotation", + "motivation": ["painting"], + "body": { + "id": "https://example.org/iiif/assets/model1.glb", + "type": "Model" + }, + "target": { + "type": "SpecificResource", + "source": [ + { + "id": "https://example.org/iiif/scene1", + "type": "Scene" + } + ], + "selector": [ + { + "type": "PointSelector", + "x": -1.0, + "y": -1.0, + "z": 3.0, + "instant": 45.0 + } + ] + } +} +``` + +The Annotation's [`timeMode` property](https://iiif.io/api/presentation/3.0/#timemode) can be used to indicate the desired behavior when the duration of the content resource that is not equal to the temporal region targeted by the annotation. + +It is an error to select a temporal region of a Scene that does not have a `duration`, or to select a temporal region that is not within the Scene's temporal extent. A Canvas or Scene with a `duration` may not be annotated as a content resource into a Scene that does not itself have a `duration`. + + + + + +### Canvas + +A Container that represents a bounded, two-dimensional space and has content resources associated with all or parts of it. It may also have a bounded temporal range in the same manner as a Timeline. + +* has integer, unitless width and height +* has optional continuous duration in seconds + +### Scene + +A Container that represents a boundless three-dimensional space and has content resources positioned at locations within it. Rendering a Scene requires the use of Cameras and Lights. It may also have a bounded temporal range in the same manner as a Timeline. + +* has continuous, unitless x,y,z cartesian coordinate space +* has optional continuous duration in seconds + +A Scene in IIIF is a virtual container that represents a boundless three-dimensional space and has content resources, lights and cameras positioned at locations within it. It may also have a duration to allow the sequencing of events and timed media. Scenes have infinite height (y axis), width (x axis) and depth (z axis), where 0 on each axis (the origin of the coordinate system) is treated as the center of the scene's space. +The positive y axis points upwards, the positive x axis points to the right, and the positive z axis points forwards (a [right-handed cartesian coordinate system](https://en.wikipedia.org/wiki/Right-hand_rule)). + +The axes of the coordinate system are measured in arbitrary units and these units do not necessarily correspond to any physical unit of measurement. This allows arbitrarily scaled models to be used, including very small or very large, without needing to deal with very small or very large values. If there is a correspondence to a physical scale, then this can be asserted using the physical dimensions pattern(fwd-ref-to-phys-dims). + +diagram of Right handed cartesian coordinate system + + +As with other containers in IIIF, Annotations are used to target the Scene to place content such as 3d models into the scene. Annotations are also used to add lights and cameras. A Scene can have multiple models, lights, cameras and other resources, allowing them to be grouped together. Scenes and other IIIF containers, such as Canvases, may also be embedded within Scenes, as described below in the nesting section [fwd-ref-to-nesting]. + +```json +{ + "id": "https://example.org/iiif/scenes/1", + "type": "Scene", + "label": {"en": ["Chessboard"]}, + "backgroundColor": "#000000", + "items": [ + "Note: Annotations Live Here" + ] +} +``` + + + +## Putting stuff into Containers (composition) + +### Annotation + + +Annotations follow the [Web Annotation][org-w3c-webanno] data model and are used to associate models, lights, cameras, and IIIF containers such as Canvases, with Scenes. They have a `type` of "Annotation", a `body` (being the resource to be added to the scene) and a `target` (being the scene or a position within the scene). They must have a `motivation` property with the value of "painting" to assert that the resource is being painted into the Scene, rather than the Annotation being a comment about the Scene. + +A construct called a Selector is used to select a part of a resource, such as a point within a Scene. The use of a Selector necessitates the creation of a `SpecificResource` that groups together the resource being selected (the `source`) and the instance of the Selector. This SpecificResource can then be used as either the `body` or the `target` of the Annotation. + +All resources that can be added to a Scene have an implicit (e.g. Lights, Cameras) or explicit (e.g. Models, Scenes), local coordinate space. If a resource does not have an explicit coordinate space, then it is positioned at the origin of its coordinate space. In order to add a resource with its local coordinate space into a Scene with its own coordinate space, these spaces must be aligned. This done by aligning the origins of the two coordinate spaces. + +Annotations may use a type of Selector called a `PointSelector` to align the Annotation to a point within the Scene that is not the Scene's origin. PointSelectors have three spatial properties, `x`, `y` and `z` which give the value on that axis. They also have a temporal property `instant` which can be used if the Scene has a duration, which gives the temporal point in seconds from the start of the duration, the use of which is defined in the [section on Scenes with Durations](). + +Example Annotation that positions a model at a point within a Scene: + +```json +{ + "id": "https://example.org/iiif/3d/anno1", + "type": "Annotation", + "motivation": ["painting"], + "body": { + "id": "https://example.org/iiif/assets/model1.glb", + "type": "Model" + }, + "target": { + "type": "SpecificResource", + "source": [ + { + "id": "https://example.org/iiif/scene1", + "type": "Scene" + } + ], + "selector": [ + { + "type": "PointSelector", + "x": -1.0, + "y": 0.0, + "z": 1.0 + } + ] + } +} +``` + +Annotations may alternately use a type of Selector called a `WktSelector` to align the Annotation to a region with the Scene that is not the Scene's origin. WktSelectors have a single property, `value`, which is a string conforming to a WKT Linestring, LineStringZ, Polygon, or PolygonZ list of 2D or 3D coordinate points. Whether and how a region defined by a WktSelector may be translated to a single 2D or 3D coordinate point, for targeting or other purposes, is client-dependent. + +
+❓Does WKTSelector have a duration/instant property? +
+ +Example Annotation that comments on a 3D polygon within a Scene: + +``` +Todo add example +``` + +#### URI Fragments + +(move up, include xywh) + +The point may instead be defined using a short-hand form of a URI Fragment at the end of the `id` of the Scene as the `target` of the Annotation. The name of the fragment parameter is `xyz` and its value is the x, y and z values separated by commas. Each value can be expressed as either an integer or a floating point number. + +The annotation above could be expressed as its fragment-based equivalent: + +```json +{ + "id": "https://example.org/iiif/3d/anno1", + "type": "Annotation", + "motivation": ["painting"], + "body": { + "id": "https://example.org/iiif/assets/model1.glb", + "type": "Model" + }, + "target": "https://example.org/iiif/scene1#xyz=-1,0,1" +} +``` + + + + + +"non-painting" + +"target" and "body" + + +### Annotation Page + +"Overlapping elements with a larger z-index cover those with a smaller one." +link to https://developer.mozilla.org/en-US/docs/Web/CSS/z-index + + +### Annotation Collection + +deal with this: +https://github.com/IIIF/api/pull/2304/files#diff-cc70f02818f6bed2b14dfbf8bf3206e0825047951c8e83ad56fc73e489f82ac4R1757 + +use totalItems? https://iiif.io/api/discovery/1.0/#totalitems + +### Manifest + +### Collection + +#### Paging + +### Range + +## Content State + +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](content-state-2) 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 + +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: + +```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" + } + ] + } +} +``` + +As well as adding resources not present in the referred-to resource, the Content State can also remove parts of the referred-to resource from the user's view by applying the behavior `hidden` to them: + +```jsonc +{ + // What does this actually look like? I want to load bnf_chateauroux example but HIDE the illumination + // ... + "id": "https://iiif.io/api/cookbook/recipe/0036-composition-from-multiple-images/annotation/p0001-image", + "type": "Annotation", + "motivation": "painting", + "behavior": ["hidden"] +} +``` + +TODO: what is the processing algorithm for applying incoming `hidden` ? + +When a Content State annotation carries a Scene, a view might be initialized from a Content State that introduces an additional Camera that shows the user the point of interest. + + +### Modify the Container in a particular context + +The techniques in the previous example are also used within a published IIIF Manifest 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. The `scope` property indicates to the client that the Content State provides valuable context for displaying some aspect of a Scene or other Container. In the case of a commenting annotation, this means that the Content State should be loaded when the commenting annotation is selected or otherwise highlighted. + + +Consider a Scene with two models, and two `commenting` annotations: + +```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/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/anno7", + "type": "Annotation", + "motivation": ["commenting"], + "bodyValue": "Mandibular tooth", + "target": { + // SpecificResource with PointSelector + } + }, + { + "id": "https://example.org/iiif/3d/anno5", + "type": "Annotation", + "motivation": ["commenting"], + "bodyValue": "Right pterygoid hamulus", + "target": { + // SpecificResource with PointSelector + } + } + ] + } + ] +} +``` + +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. It may be useful to light the Scene differently in different contexts. + +In the same way an incoming Content State can modify a Scene as it initializes the client, so can a Content State attached to each (non-`painting`) annotation target modify the Scene as the user moves between different annotations. + +The `scope` property of an annotation `target` provides _contextual_ Content State - the viewer should modify the Scene by applying the Content State carried by the `scope` property _only when the user is in the context of that annotation_. + +Taking the first commenting annotation from the above example and adding a `scope` property, whose value is an annotation with the motivation `contentState`, we can introduce a new Camera specifically for this particular annotation, so that when the user selects this comment, the client will switch the view to this camera. This example also changes the background color of the Scene: + +```jsonc +{ + "id": "https://example.org/iiif/3d/anno7", + "type": "Annotation", + "motivation": ["commenting"], + "bodyValue": "Mandibular tooth", + "target": { + + // SpecificResource with PointSelector + // "type": "SpecificResource", + // "source": ... the Scene... + // "selector": ... a point ... + + "scope": { // a modification to the Scene, only in the context of this annotation + + "id": "https://example.org/iiif/3d/anno4", + "type": "Annotation", + "motivation": ["contentState"], + "target": { + "id": "https://example.org/iiif/scene1/page/p1/1", + "type": "Scene", + "backgroundColor": "yellow", + "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.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 + } + ] + } + } + ] + } + } + } +} +``` + +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 `scope` 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 parts of the Scene for a step + - introducing additional models at a particular step + - (and many more!) + +Use of `scope` is permitted in annotations on any Container type, not just Scenes. For example, a 2D narrative around a Canvas might show or hide different `painting` annotations at each step. + +#### The `sequence` behavior + +// Is this right? Language... + +While all AnnotationPage `items` are inherently ordered, an Annotation Page with the behavior `sequence` is explicitly a narrative, and clients should prevent (dissuade) users from jumping about. The presence of `sequence` affects the way a client should interpret the `reset` property described below. + +### Content States on Manifests + +When an annotation with the motivation `contentState` is provided via the `annotations` property of a Manifest, rather than contextually via `scope`, it is assumed to be generally available for selection by the user at any time. A client may present such as annotations as a menu of views, allowing arbitrary jumping into any Scene (or Canvas or Timeline) from any other point. + +// Is there some overlap here with Range? + +### Processing Content States in Scopes: reset + +// This may not be what we have discussed... + +When a Content State is applied to a Container such as a Scene, it is assumed to be a "diff" - for example if 3 cameras and 4 lights are already present in the Scene, and a Content State asserts a single new Camera, the default behavior is to add this fourth Camera to the Scene and leave the existing resources as they are. + +The client should reset the Container to its original state before applying the diff operation. However, for narratives that cumulatively build a Scene this may lead to excessively verbose Manifests. When moving through the items of an Annotation page with the behavior `sequence`, the Container is not reset and the diff is cumulative; modifications from one `scope` persist into the next. If this behavior is not wanted, the `reset` property of the content state annotation should be set to `true`: + +```json +{ + "type": "Annotation", + "motivation": ["contentState"], + "reset": true +} +``` + +Before applying the content state to the Scene, the client should reset the Scene to its original state as provided by the Manifest. + +// I am assuming reset is always true except in `sequence` - otherwise it's completely unpredictable!! or is it... arbitrary navigation, state provided by initialization content states, etc... + +### Contribute additional information permanently + +Rerum inbox scenario - should be covered in CS2 protocol + +### activating - animation and interactions + +Annotations with the motivation `activating` are referred to as _activating_ annotations. + +There are two uses of `activating` annotations: + +#### Triggering a content state + +An activating annotation links a painting annotation to a content state. When a user interacts with the painting annotation - whether through clicking it, tapping it, or other client-specific behaviors - the linked content state should be processed to modify the Scene or other Container, as in the previous examples. The painting annotation is the target of the activating annotation, and the content state is the body value. Only one content state may be specified in the body array, but the body array may include a `TextualBody` to provide a label for the interaction. The pattern is the same as for the `linking` motivation, but rather than the client opening a new browser window on the resource specified in the `body`, it applies the modification provided by the Content State. + +The activating annotation is provided in a Container's `annotations` property. In this (contrived for brevity) example, if the user clicks the mandible model, the Scene background changes color: + +```jsonc +{ + "id": "https://example.org/iiif/3d/activating.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/scene-with-activation", + "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/painting-anno-for-mandible", + "type": "Annotation", + "motivation": ["painting"], + "body": { + "id": "https://raw.githubusercontent.com/IIIF/3d/main/assets/whale/whale_mandible.glb", + "type": "Model" + }, + "target": { + // SpecificResource with PointSelector + } + } + ], + "annotations": [ + { + "id": "https://example.org/iiif/scene1/page/activators", + "type": "AnnotationPage", + "items": [ + { + "id": "https://example.org/iiif/3d/anno2", + "type": "Annotation", + "motivation": ["activating"], + "body": [ + { + "type": "TextualBody", + "value": "A label for the activation may be provided as a TextualBody" + }, + { + // A body where the type is a IIIF Resource (eg Scene) is the Content State to apply + "id": "https://example.org/iiif/scene1/scene-with-activation", + "type": "Scene", + "backgroundColor": "#FF99AA" + } + ], + "target": { + "id": "https://example.org/iiif/3d/painting-anno-for-mandible", + "type": "Annotation" + } + } + ] + } + ] + } + ] + } + ] +} +``` + +// Can you put activating annotations in `manifest.annotations`? They would work there too, you have all the information. + + + +#### 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. + +This pattern is similar to the above, except that: + + - There is no Content State in the `body`, but there _MUST_ be a TextualBody to label the interaction. (?? must?) + - The `target` selects a _named animation_ in the model. The `target` MUST be a SpecificResource, where the `source` is the painting annotation that paints the model, and the `selector` is of type `AnimationSelector` with the `value` being a string that corresponds to the animation in the model. + + The format of the `value` string is implementation=specific, and will depend on how different 3D formats support addressing of animations within models. The same model can be painted multiple times into the scene, and you might want to activate only one model's animation, thus we need to refer to the annotation that paints the model, not the model directly. + + + +```jsonc +{ + "id": "https://example.org/iiif/3d/activating-animation.json", + "type": "Manifest", + "label": { "en": ["Music Box with lid that opens as an internal animation"] }, + "items": [ + { + "id": "https://example.org/iiif/scene1/scene-with-activation-animation", + "type": "Scene", + "label": { "en": ["A Scene Containing a Music Box"] }, + "items": [ + { + "id": "https://example.org/iiif/scene-with-activation-animation/page/p1/1", + "type": "AnnotationPage", + "items": [ + { + "id": "https://example.org/iiif/3d/painting-anno-for-music-box", + "type": "Annotation", + "motivation": ["painting"], + "body": { + "id": "https://raw.githubusercontent.com/IIIF/3d/main/assets/music-box.glb", + "type": "Model" + }, + "target": { + // SpecificResource with PointSelector + } + } + ], + "annotations": [ + { + "id": "https://example.org/iiif/scene1/page/activators", + "type": "AnnotationPage", + "items": [ + { + "id": "https://example.org/iiif/3d/anno2", + "type": "Annotation", + "motivation": ["activating"], + "body": [ + { + "type": "TextualBody", + "value": "Click the box to open the lid" + } + ], + "target": [ + { + "type": "SpecificResource", + "source": "https://example.org/iiif/3d/painting-anno-for-music-box", + "selector": [ + { + "type": "AnimationSelector", + "value": "open-the-lid" + } + ] + } + ] + } + ] + } + ] + } + ] + } + ] +} +``` + +// TODO + +activating to apply a content state and activating to trigger a named animation - use of body and target... what if we want to click a painting anno to trigger the animation? +Can we ADD that to the target, alongside the SpecificResource with the AnimationSelector? + +if the `target` is an AnimationSelector, then the `body` can ONLY be TextualBody (or list of TextualBody)? + +There is a more general rule here! + +### reset + +See above... + +"diff", "original state" etc +behavior for "force-order"? +behavior: sequence + +## Selectors + +preamble - cover all the use cases + +### SpecificResource + +(This heading should be more descriptive) + +fragments/segments/parts of resources +SvgSelector +xywh + + +### PointSelector + + +## Scene-Specific Resources + +### 3D considerations / principles + +"models" (content resources in 3D) +"local coordinate spaces" + +### Camera + +A Camera provides a view of a region of the Scene's space from a particular position within the Scene; the client constructs a viewport into the Scene and uses the view of one or more Cameras to render that region. The size and aspect ratio of the viewport is client and device dependent. + +This specification defines two types of Camera: + +| Class | Description | +| ------------------- | ------------ | +| `PerspectiveCamera` | `PerspectiveCamera` mimics the way the human eye sees, in that objects further from the camera are smaller | +| `OrthographicCamera` | `OrthographicCamera` removes visual perspective, resulting in object size remaining constant regardless of its distance from the camera | + +Cameras are positioned within the Scene facing in a specified direction. Both position and direction are defined through the Annotation which adds the Camera to the Scene, described below in the sections on [Painting Annotations][], [Transforms][], and [Relative Rotation][]. If either the position or direction is not specified, then the position defaults to the origin, and facing direction defaults to pointing along the z axis towards negative infinity. The camera's up direction by default points along the y axis towards positive infinity, but this may be modified by transforms. + +The region of the Scene's space that is observable by the camera is bounded by two planes orthogonal to the direction the camera is facing, given in the `near` and `far` properties, and a vertical projection angle that provides the top and bottom planes of the region. + +The `near` property defines the minimum distance from the camera at which something in the space must exist in order to be viewed by the camera. Anything nearer to the camera than this distance will not be viewed. Conversely, the `far` property defines a maximum distance from the camera at which something in the space must exist in order to be viewed by the camera. Anything further away will not be viewed. + +For PerspectiveCameras, the vertical projection angle is specificed using the full angular extent in degrees from the top plane to the bottom plane using the `fieldOfView` property. The `fieldOfView` angle MUST be greater than 0 and less than 180. For OrthographicCameras, the vertical projection is always parallel and thus not defined. + +If any of these properties are not specified explicitly, they default to the choice of the client implementation. + +drawing of a geometrical frustrum truncated by near and far distances + + +The first Camera defined and not hidden in a Scene is the default Camera used to display Scene contents. If the Scene does not have any Cameras defined within it, then the client MUST provide a default Camera. The type, properties and position of this default camera are client-dependent. + +```json +{ + "id": "https://example.org/iiif/camera/1", + "type": "PerspectiveCamera", + "near": 1.0, + "far": 100.0, + "fieldOfView": 45.0 +} +``` + + + +### Light + +One or more Lights MUST be present within the Scene in order to have objects within it be visible to the Cameras. + +This specification defines four types of Light: + +| Class | Description | +| ----- | ------------ | +| `AmbientLight` | AmbientLight evenly illuminates all objects in the scene, and does not have a direction or position. | +| `DirectionalLight` | DirectionalLight emits in a specific direction as if it is infinitely far away and the rays produced from it are all parallel. It does not have a specific position. | +| `PointLight` | PointLight emits from a single point within the scene in all directions. | +| `SpotLight` | SpotLight emits a cone of light from a single point in a given direction. | + +Lights defined in this specification have a `color` and an `intensity`. The color is given as an RGB value, such as "#FFFFFF" for white. The intensity is the strength or brightness of the light, and described using a `Value` construct. + +SpotLight has an additional property of `angle`, specified in degrees, which is the angle from the direction that the Light is facing to the outside extent of the cone. + +diagram of cone geometry showing how the angle of the cone is defined + +Lights that require a position and/or direction have these through the Annotation which associates them with the Scene, described below in the sections on [Painting Annotations][] and [Transforms][]. If a Light does not have an explicit direction, then the default is in the negative y direction (downwards). If a Light does not have an explicit position in the coordinate space, then the default is at the origin. + +This specification does not define other aspects of Lights, such as the rate of decay of the intensity of the light over a distance, the maximum range of the light, or the penumbra of a cone. Implementation of these aspects is client-dependent. + +If there are no Lights present within the Scene, then the viewer MUST add at least one Light. The types and properties of Lights added in this way are client-dependent. + +```json +{ + "id": "https://example.org/iiif/light/1", + "type": "AmbientLight", + "color": "#FFFFFF", + "intensity": {"type": "Value", "value": 0.6, "unit": "relativeUnit"} +} +``` + + + +### Transforms + +The Annotation with a Selector on the target can paint a resource at a point other than the origin, however it will be at its initial scale and rotation, which may not be appropriate for the scene that is being constructed. + +This specification defines a new class of manipulations for SpecificResources called a `Transform`, with three specific sub-classes. Each Transform has three properties, `x`, `y` and `z` which determine how the Transform affects that axis in the local coordinate space. + + +| Class | Description | +| --------------- | ------------ | +| ScaleTransform | A ScaleTransform applies a multiplier to one or more axes in the local coordinate space. A point that was at 3.5, after applying a ScaleTransform of 2.0 would then be at 7.0. If an axis value is not specified, then it is not changed, resulting in a default of 1.0 | +| RotateTransform | A RotateTransform rotates the local coordinate space around the given axis in a counter-clockwise direction around the axis itself (e.g. around a pivot point of 0 on the axis). A point that was at x=1,y=1 and was rotated 90 degrees around the x axis would be at x=1,y=0,z=1. If an axis value is not specified, then it is not changed, resulting in a default of 0.0 | +| TranslateTransform | A TranslateTransform moves all of the objects in the local coordinate space the given distance along the axis. A point that was at x=1.0, after applying a TranslateTransform of x=1.0 would be at x=2.0. If an axis value is not specified then it is not changed, resulting in a default of 0.0 | + +Transforms are added to a SpecificResource using the `transform` property. The value of the property is an array, which determines the order in which the transforms are to be applied. The resulting state of the first transform is the input state for the second transform, and so on. Different orders of the same set of transforms can have different results, so attention must be paid when creating the array and when processing it. + +The point around which RotateTransform rotates the space is the origin. This "pivot point" cannot be changed directly, but instead a TranslateTransform can be used to move the desired pivot point to the be at the origin, then the RotateTransform applied. + +Transforms are only used in the Presentation API when the SpecificResource is the `body` of the Annotation, and are applied before the resource is painted into the scene at the point given in the `target`. + +```json +{ + "type": "SpecificResource", + "source": { + "id": "https://example.org/iiif/assets/model1.glb", + "type": "Model" + }, + "transform": [ + { + "type": "RotateTransform", + "x": 0.0, + "y": 180.0, + "z": 0.0 + }, + { + "type": "TranslateTransform", + "x": 1.0, + "y": 0.0, + "z": 0.0 + } + ] +} +``` + + +#### Relative Rotation + +It is useful to be able to rotate a light or camera resource such that it is facing another object or point in the Scene, rather than calculating the angles within the Scene's coordinate space. This is accomplished with a property called `lookAt`, valid on DirectionalLight, SpotLight, and all Cameras. The value of the property is either a PointSelector, a WktSelector, the URI of an Annotation which paints something into the current Scene, or a Specific Resource with a selector identifying a point or region in an arbitrary container. + +If the value is a PointSelector, then the light or camera resource is rotated around the x and y axes such that it is facing the given point. If the value is a WktSelector, then the resource should be rotated to face the given region. If the value is an Annotation which targets a point via a PointSelector, URI fragment or other mechanism, then the resource should be rotated to face that point. If the value is a Specific Resource, the source container for the Specific Resource must be painted into the current Scene, and the Specific Resource selector should identify a point or region in the source container. In this case, the light or camera resource should be rotated to face the point or region in the source container where the point or region is located within the current Scene's coordinate space. This allows light or camera resources to face a specific 2D point on a Canvas painted into a 3D scene. + +This rotation happens after the resource has been added to the Scene, and thus after any transforms have taken place in the local coordinate space. + +```json +"lookAt": { + "type": "PointSelector", + "x": 3, + "y": 0, + "z": -10 +} +``` + + +#### Excluding + +Just as a Scene may contain multiple Annotations with model, light, and camera resources, a single 3D model file may contain a collection of 3D resources, including model geometry, assemblages of lights, and/or multiple cameras, with some of these potentially manipulated by animations. When painting Scenes or models that themselves may contain groups of resources within a single Scene, it may not always be appropriate to include all possible cameras, lights, or other resources, and it may be desirable to opt not to import some of these resources. This is accomplished through the Annotation property `exclude`, which prevents the import of audio, lights, cameras, or animations from a particular Scene or model prior to the Annotation being painted into a Scene. When `exclude` is used, the excluded resource type should not be loaded into the Scene, and it is not possible to reactivate or turn on these excluded resources after loading. + +Painting a Scene into another while excluding import of several types of resources: +```json +{ + "id": "https://example.org/iiif/3d/anno1", + "type": "Annotation", + "motivation": ["painting"], + "exclude": ["Audio", "Lights", "Cameras", "Animations"], + "body": { + "id": "https://example.org/iiif/scene1", + "type": "Scene" + }, + "target": "https://example.org/iiif/scene2" +} +``` + + + +## Advanced Association Features + +(This needs to be sprinkled throughout above - especially as SpecificResource must be introduced early for 3D) + +### Nesting + +A Canvas can be painted into a Scene as an Annotation, but the 2D nature of Canvases requires special consideration due to important differences between Canvases and Scenes. A Canvas describes a bounded 2D space with finite `height` and `width` measured in pixels with a pixel origin at the top-left corner of the Canvas, while Scenes describe a boundless 3D space with x, y, and z axes of arbitrary coordinate units and a coordinate origin at the center of the space. It is important to note that in many cases the pixel scale used by a Canvas or a 2D image content resource will not be in proportion to the desired 3D coordinate unit scale in a Scene. + +When a Canvas is painted as an Annotation targeting a Scene, the top-left corner of the Canvas (the pixel origin) is aligned with the 3D coordinate origin of the Scene. The top edge of the Canvas is aligned with (e.g., is colinear to) the positive x axis extending from the coordinate origin. The left edge of the Canvas is aligned with (e.g., is colinear to) the negative y axis extending from the coordinate origin. The Canvas is scaled to the Scene such that the pixel dimensions correspond to 3D coordinate units - a Canvas 200 pixels wide and 400 pixels high will extend 200 coordinate units across the x axis and 400 coordinate units across the y axis. Please note: direction terms "top", "bottom", "right", and "left" used in this section refer to the frame of reference of the Canvas itself, not the Scene into which the Canvas is painted. + +A Canvas in a Scene has a specific forward face and a backward face. By default, the forward face of a Canvas should point in the direction of the positive z axis. If the property `backgroundColor` is used, this color should be used for the backward face of the Canvas. Otherwise, a reverse view of the forward face of the Canvas should be visible on the backward face. + +
+ To Do: Add an image demonstrating default Canvas placement in Scene +
+ +A `PointSelector` can be used to modify the point at which the Canvas will be painted, by establishing a new point to align with the top-left corner of the Canvas instead of the Scene coordinate origin. Transforms can also be used to modify Canvas rotation, scale, or translation. + +It may be desirable to exercise greater control over how the Canvas is painted into the Scene by selecting the coordinate points in the Scene that should correspond to each corner of the Canvas. This provides fine-grained manipulation of Canvas placement and/or scale, and for optionally introducing Canvas distortion or skew. Annotations may use a WktSelector to select different points in the Scene to align with the top-left, bottom-left, bottom-right, and top-right corners of the Canvas. In this case, the four Scene coordinates should be listed beginning with the coordinate corresponding to the top-left corner of the Canvas, and should proceed in a counter-clockwise winding order around the Canvas, with coordinates corresponding to bottom-left, bottom-right, and top-right corners in order respectively. The use of WktSelector for this purpose overrides any use of Transforms on the Canvas Annotation. + +Example placing top-left at (0, 1, 0); bottom-left at (0, 0, 0); bottom-right at (1, 0, 0); and top-right at (1, 1, 0): +```json +"selector": [ + { + "type": "WktSelector", + "value": "POLYGONZ((0 1 0, 0 0 0, 1 0 0, 1 1 0))" + } +] +``` + +When a Scene is nested into another Scene, the `backgroundColor` of the Scene to be nested should be ignored as it is non-sensible to import. All Annotations painted into the Scene to be nested will be painted into the Scene into which content is being nested, including Light or Camera resources. If the Scene to be nested has one or more Camera Annotations while the Scene into which content is being nested does not, the first Camera Annotation from the nested Scene will become the default Camera for the overall Scene. + +### Embedded Content + +e.g., painting TextualBody on Canvas + +Todo: This is mostly copy-pasted from properties, is it needed here? +It is important to be able to position the textual body of an annotation within the Container's space that the annotation also targets. For example, a description of part of an image in a Canvas should be positioned such that it does not obscure the image region itself and labels to be displayed as part of a Scene should not be rendered such that the text is hidden by the three dimensional geometry of the model. The positioning of the textual body in a container is accomplished through the `position` property, which has as a value a Specific Resource identifying the targeted container as the source and a selector defining how the textual body should be positioned in the targeted container. If this property is not supplied, then the client should do its best to ensure the content is visible to the user. + +### Comment Annotations + +(move to Annotation section) + + +### Choice of Alternative Resources + +(move to Annotation section) + + +### Non Rectangular Segments + +SvgSelector - move to SpecificResource too ^^ + + +### Style + +Move to SpecificResource + + +### Rotation + + +### Hotspot Linking and Activation + +Move to SpecificResource + + + +## Conveying Physical Dimensions + +(why is this important!?) + +(move the props to vocab doc) + +### spatialScale + +### temporalScale + + +``` +{ + "spatialScale": { + "factor": 22.0, + "units": "m" + }, + + + // this would be rarely used + "temporalScale": { + "factor": 0.00001 + } + +} +``` + +`factor` Required A floating point ratio. +`units` Required A real-world measuring unit. Always seconds for temporalScale. Possible values for spatialScale include: "m", "ft". (is that it?) + +For a Canvas, it's the physical "size" of each cartesian integer unit. +For a Scene, it's the physical size of the unit vector. +For a timeline it's the ratio of time in the recording to time in the real world. + + +(define props in the Vocabulary doc) + + +## HTTP Requests and Responses + +### URI Recommendations + +### Requests + +### Responses + +### Authentication + + +## Accessibility + +(new section) + +`provides` + + +## Appendices + +### Summary of Property Requirements + +### Example Manifest Response + +### Versioning + +### Acknowledgements + +### Change Log + +"Exclude Audio" diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index 822e068f7..906a57969 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -51,1168 +51,172 @@ __Previous Version:__ [3.0][prezi30] ---- -# Presentation 4 - ## Introduction -Manifests, Containers, Annotations oh my! -Manifest as unit of distribution - - -## Content Resources - -There is stuff that we want to show - images, video, audio, 3D models etc - -### type value of Content Resources +Presentation, the clue is in the name -| Class | Description | -| ------------- | -------------------------------- | -| `Image` | Two dimensional visual resources primarily intended to be seen, such as might be rendered with an <img> HTML tag | -| `Model` | A three (or more) dimensional model intended to be interacted with by humans | -| `Sound` | Auditory resources primarily intended to be heard, such as might be rendered with an <audio> HTML tag | -| `Text` | Resources primarily intended to be read | -| `Video` | Moving images, with or without accompanying audio, such as might be rendered with a <video> HTML tag | -{: .api-table #table-type} -## Containers +(non-exhaustive) List of use cases -This is where we put content resources -"painting" +1. Digitized books and manuscripts (images, paged things, transcripts, translations) +2. Artworks and Maps (navPlace, maybe commenting annos) +3. Audio and Video recordings (time-based, transcriptions) +4. 3D scans of objects (3D) +5. Periodicals (Collections, Ranges, navDate) +6. Archival collections (Collections, Ranges, navDate) +7. Storytelling and exhibitions (State, annotations) -And we can also put other things: -"supplementing" +see Terminology at the end -And we can nest them -"Nesting" (see 3d draft) +Mention model.md -The defined Container types are `Timeline`, `Canvas` and `Scene`. Extensions may define additional Container types. +Mention cookbook -As multiple models, lights, cameras, and other resources can be associated with and placed within a Scene container, Scenes provide a straightforward way of grouping content resources together within a space. Scenes, as well as other IIIF containers such as Canvases, can also be embedded within a Scene, allowing for the nesting of content resources. -A Scene or a Canvas may be treated as a content resource, referenced or described within the `body` of an Annotation. As with models and other resources, the Annotation is associated with a Scene into which the Scene or Canvas is to be nested through an Annotation `target`. The content resource Scene will be placed within the `target` Scene by aligning the coordinate origins of the two scenes. Alternately, Scene Annotations may use `PointSelector` to place the origin of the resource Scene at a specified coordinate within the `target` Scene. -As with other resources, it may be appropriate to modify the initial scale, rotation, or translation of a content resource Scene prior to painting it within another Scene. Scenes associated with SpecificResources may be manipulated through the transforms described in Transforms(transforms_section). - -A simple example painting one Scene into another: - -```json -{ - "id": "https://example.org/iiif/3d/anno1", - "type": "Annotation", - "motivation": ["painting"], - "body": { - "id": "https://example.org/iiif/scene1", - "type": "Scene" - }, - "target": "https://example.org/iiif/scene2" -} -``` +## Foundations +Simple model diagram -Content resources of the appropriate dimension(s) may be annotated into a Container that has those dimensions. +Manifests and Containers briefly -### Timeline - -A Container that represents a bounded temporal range, without any spatial coordinates. - -* has continuous duration in seconds - for all or part of its duration. - - -A Timeline _MUST_ have a `duration` property that defines its length in seconds. The `duration` value must be a positive floating point number. - -An annotation that targets a Scene using a PointSelector without any temporal refinement implicitly targets the Scene's entire duration. - -A content resource may be annotated into a Scene for a period of time by use of a PointSelector that is temporally scoped by a [FragmentSelector](https://www.w3.org/TR/annotation-model/#fragment-selector). The FragmentSelector has a `value` property, the value of which follows the [media fragment syntax](https://www.w3.org/TR/media-frags/#naming-time) of `t=`. This annotation pattern uses the `refinedBy` property [defined by the W3C Web Annotation Data Model](https://www.w3.org/TR/annotation-model/#refinement-of-selection). - -```json -{ - "id": "https://example.org/iiif/3d/anno1", - "type": "Annotation", - "motivation": ["painting"], - "body": { - "id": "https://example.org/iiif/assets/model1.glb", - "type": "Model" - }, - "target": { - "type": "SpecificResource", - "source": [ - { - "id": "https://example.org/iiif/scene1", - "type": "Scene" - } - ], - "selector": [ - { - "type": "PointSelector", - "x": -1.0, - "y": -1.0, - "z": 3.0, - "refinedBy": { - "type": "FragmentSelector", - "value": "t=45,95" - } - } - ] - } -} -``` - -When using a URL fragment in place of a SpecificResource, the parameter `t` can be used to select the temporal region: +### Manifests -```json -{ - "id": "https://example.org/iiif/3d/anno1", - "type": "Annotation", - "motivation": ["painting"], - "body": { - "id": "https://example.org/iiif/assets/model1.glb", - "type": "Model" - }, - "target": "https://example.org/iiif/scene1#xyz=-1,-1,3&t=45,95" -} -``` +The document, the unit of distribution of IIIF -An Annotation may target a specific point in time using a PointSelector's `instant` property. The property's value must be a positive floating point number indicating a value in seconds that falls within the Scene's duration. +A sequence of Containers that carry the content. -```json -{ - "id": "https://example.org/iiif/3d/anno1", - "type": "Annotation", - "motivation": ["painting"], - "body": { - "id": "https://example.org/iiif/assets/model1.glb", - "type": "Model" - }, - "target": { - "type": "SpecificResource", - "source": [ - { - "id": "https://example.org/iiif/scene1", - "type": "Scene" - } - ], - "selector": [ - { - "type": "PointSelector", - "x": -1.0, - "y": -1.0, - "z": 3.0, - "instant": 45.0 - } - ] - } -} -``` -The Annotation's [`timeMode` property](https://iiif.io/api/presentation/3.0/#timemode) can be used to indicate the desired behavior when the duration of the content resource that is not equal to the temporal region targeted by the annotation. +### Containers -It is an error to select a temporal region of a Scene that does not have a `duration`, or to select a temporal region that is not within the Scene's temporal extent. A Canvas or Scene with a `duration` may not be annotated as a content resource into a Scene that does not itself have a `duration`. +Timeline, Canvas, Scene +### Painting Annotations +Everything is an anno but these are special and core +### Content Resources -### Canvas +Image, Sound, Video, Model, Text +(see model) -A Container that represents a bounded, two-dimensional space and has content resources associated with all or parts of it. It may also have a bounded temporal range in the same manner as a Timeline. +SpecificResource -* has integer, unitless width and height -* has optional continuous duration in seconds -### Scene -A Container that represents a boundless three-dimensional space and has content resources positioned at locations within it. Rendering a Scene requires the use of Cameras and Lights. It may also have a bounded temporal range in the same manner as a Timeline. +## Presenting Content Resources - what you came here for -* has continuous, unitless x,y,z cartesian coordinate space -* has optional continuous duration in seconds +### Images -A Scene in IIIF is a virtual container that represents a boundless three-dimensional space and has content resources, lights and cameras positioned at locations within it. It may also have a duration to allow the sequencing of events and timed media. Scenes have infinite height (y axis), width (x axis) and depth (z axis), where 0 on each axis (the origin of the coordinate system) is treated as the center of the scene's space. -The positive y axis points upwards, the positive x axis points to the right, and the positive z axis points forwards (a [right-handed cartesian coordinate system](https://en.wikipedia.org/wiki/Right-hand_rule)). +A painting -The axes of the coordinate system are measured in arbitrary units and these units do not necessarily correspond to any physical unit of measurement. This allows arbitrarily scaled models to be used, including very small or very large, without needing to deal with very small or very large values. If there is a correspondence to a physical scale, then this can be asserted using the physical dimensions pattern(fwd-ref-to-phys-dims). +A paged thing -diagram of Right handed cartesian coordinate system +### Audio and Video -As with other containers in IIIF, Annotations are used to target the Scene to place content such as 3d models into the scene. Annotations are also used to add lights and cameras. A Scene can have multiple models, lights, cameras and other resources, allowing them to be grouped together. Scenes and other IIIF containers, such as Canvases, may also be embedded within Scenes, as described below in the nesting section [fwd-ref-to-nesting]. +A timeline - audio only -```json -{ - "id": "https://example.org/iiif/scenes/1", - "type": "Scene", - "label": {"en": ["Chessboard"]}, - "backgroundColor": "#000000", - "items": [ - "Note: Annotations Live Here" - ] -} -``` +A video on a Canvas with duration +### 3D -## Putting stuff into Containers (composition) +Whale bone with a camera and a light -### Annotation +## Annotations and State -Annotations follow the [Web Annotation][org-w3c-webanno] data model and are used to associate models, lights, cameras, and IIIF containers such as Canvases, with Scenes. They have a `type` of "Annotation", a `body` (being the resource to be added to the scene) and a `target` (being the scene or a position within the scene). They must have a `motivation` property with the value of "painting" to assert that the resource is being painted into the Scene, rather than the Annotation being a comment about the Scene. +### Annotations -A construct called a Selector is used to select a part of a resource, such as a point within a Scene. The use of a Selector necessitates the creation of a `SpecificResource` that groups together the resource being selected (the `source`) and the instance of the Selector. This SpecificResource can then be used as either the `body` or the `target` of the Annotation. +non-painting -All resources that can be added to a Scene have an implicit (e.g. Lights, Cameras) or explicit (e.g. Models, Scenes), local coordinate space. If a resource does not have an explicit coordinate space, then it is positioned at the origin of its coordinate space. In order to add a resource with its local coordinate space into a Scene with its own coordinate space, these spaces must be aligned. This done by aligning the origins of the two coordinate spaces. +Comments, tags, etc -Annotations may use a type of Selector called a `PointSelector` to align the Annotation to a point within the Scene that is not the Scene's origin. PointSelectors have three spatial properties, `x`, `y` and `z` which give the value on that axis. They also have a temporal property `instant` which can be used if the Scene has a duration, which gives the temporal point in seconds from the start of the duration, the use of which is defined in the [section on Scenes with Durations](). +transcripts (and back ref to OCR on images etc) -Example Annotation that positions a model at a point within a Scene: -```json -{ - "id": "https://example.org/iiif/3d/anno1", - "type": "Annotation", - "motivation": ["painting"], - "body": { - "id": "https://example.org/iiif/assets/model1.glb", - "type": "Model" - }, - "target": { - "type": "SpecificResource", - "source": [ - { - "id": "https://example.org/iiif/scene1", - "type": "Scene" - } - ], - "selector": [ - { - "type": "PointSelector", - "x": -1.0, - "y": 0.0, - "z": 1.0 - } - ] - } -} -``` +### State -Annotations may alternately use a type of Selector called a `WktSelector` to align the Annotation to a region with the Scene that is not the Scene's origin. WktSelectors have a single property, `value`, which is a string conforming to a WKT Linestring, LineStringZ, Polygon, or PolygonZ list of 2D or 3D coordinate points. Whether and how a region defined by a WktSelector may be translated to a single 2D or 3D coordinate point, for targeting or other purposes, is client-dependent. +Content State -
-❓Does WKTSelector have a duration/instant property? -
+Activating annos -Example Annotation that comments on a 3D polygon within a Scene: -``` -Todo add example -``` +## Navigation -#### URI Fragments +### navXXXX -(move up, include xywh) - -The point may instead be defined using a short-hand form of a URI Fragment at the end of the `id` of the Scene as the `target` of the Annotation. The name of the fragment parameter is `xyz` and its value is the x, y and z values separated by commas. Each value can be expressed as either an integer or a floating point number. - -The annotation above could be expressed as its fragment-based equivalent: - -```json -{ - "id": "https://example.org/iiif/3d/anno1", - "type": "Annotation", - "motivation": ["painting"], - "body": { - "id": "https://example.org/iiif/assets/model1.glb", - "type": "Model" - }, - "target": "https://example.org/iiif/scene1#xyz=-1,0,1" -} -``` - - - - - -"non-painting" - -"target" and "body" - - -### Annotation Page - -"Overlapping elements with a larger z-index cover those with a smaller one." -link to https://developer.mozilla.org/en-US/docs/Web/CSS/z-index - - -### Annotation Collection - -deal with this: -https://github.com/IIIF/api/pull/2304/files#diff-cc70f02818f6bed2b14dfbf8bf3206e0825047951c8e83ad56fc73e489f82ac4R1757 - -use totalItems? https://iiif.io/api/discovery/1.0/#totalitems - -### Manifest - -### Collection - -#### Paging - -### Range - -## Content State - -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: +These are just extracts as examples ```json -{ - "id": "https://example.org/manifests/1", - "type": "Manifest" -} +"navDate": "1776-01-01T00:00:00+00:00", ``` -A region of a Canvas within a Manifest: +See this in Periodicals -```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": [ +"navPlace": { + "id": "https://iiif.io/api/cookbook/recipe/0318-navPlace-navDate/feature-collection/1", + "type": "FeatureCollection", + "features": [ { - "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 - } - ] + "id": "https://iiif.io/api/cookbook/recipe/0318-navPlace-navDate/feature/1", + "type": "Feature", + "properties": { + "label": { "en": ["Castel Sant'Angelo, Rome"] } }, - "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](content-state-2) 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 - -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: - -```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" - } - ] - } -} -``` - -As well as adding resources not present in the referred-to resource, the Content State can also remove parts of the referred-to resource from the user's view by applying the behavior `hidden` to them: - -```jsonc -{ - // What does this actually look like? I want to load bnf_chateauroux example but HIDE the illumination - // ... - "id": "https://iiif.io/api/cookbook/recipe/0036-composition-from-multiple-images/annotation/p0001-image", - "type": "Annotation", - "motivation": "painting", - "behavior": ["hidden"] -} -``` - -TODO: what is the processing algorithm for applying incoming `hidden` ? - -When a Content State annotation carries a Scene, a view might be initialized from a Content State that introduces an additional Camera that shows the user the point of interest. - - -### Modify the Container in a particular context - -The techniques in the previous example are also used within a published IIIF Manifest 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. The `scope` property indicates to the client that the Content State provides valuable context for displaying some aspect of a Scene or other Container. In the case of a commenting annotation, this means that the Content State should be loaded when the commenting annotation is selected or otherwise highlighted. - - -Consider a Scene with two models, and two `commenting` annotations: - -```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/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/anno7", - "type": "Annotation", - "motivation": ["commenting"], - "bodyValue": "Mandibular tooth", - "target": { - // SpecificResource with PointSelector - } - }, - { - "id": "https://example.org/iiif/3d/anno5", - "type": "Annotation", - "motivation": ["commenting"], - "bodyValue": "Right pterygoid hamulus", - "target": { - // SpecificResource with PointSelector - } - } - ] - } - ] -} -``` - -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. It may be useful to light the Scene differently in different contexts. - -In the same way an incoming Content State can modify a Scene as it initializes the client, so can a Content State attached to each (non-`painting`) annotation target modify the Scene as the user moves between different annotations. - -The `scope` property of an annotation `target` provides _contextual_ Content State - the viewer should modify the Scene by applying the Content State carried by the `scope` property _only when the user is in the context of that annotation_. - -Taking the first commenting annotation from the above example and adding a `scope` property, whose value is an annotation with the motivation `contentState`, we can introduce a new Camera specifically for this particular annotation, so that when the user selects this comment, the client will switch the view to this camera. This example also changes the background color of the Scene: - -```jsonc -{ - "id": "https://example.org/iiif/3d/anno7", - "type": "Annotation", - "motivation": ["commenting"], - "bodyValue": "Mandibular tooth", - "target": { - - // SpecificResource with PointSelector - // "type": "SpecificResource", - // "source": ... the Scene... - // "selector": ... a point ... - - "scope": { // a modification to the Scene, only in the context of this annotation - - "id": "https://example.org/iiif/3d/anno4", - "type": "Annotation", - "motivation": ["contentState"], - "target": { - "id": "https://example.org/iiif/scene1/page/p1/1", - "type": "Scene", - "backgroundColor": "yellow", - "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.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 - } - ] - } - } - ] + "geometry": { + "type": "Point", + "coordinates": [12.4663, 41.9031] } } - } -} -``` - -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 `scope` 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 parts of the Scene for a step - - introducing additional models at a particular step - - (and many more!) - -Use of `scope` is permitted in annotations on any Container type, not just Scenes. For example, a 2D narrative around a Canvas might show or hide different `painting` annotations at each step. - -#### The `sequence` behavior - -// Is this right? Language... - -While all AnnotationPage `items` are inherently ordered, an Annotation Page with the behavior `sequence` is explicitly a narrative, and clients should prevent (dissuade) users from jumping about. The presence of `sequence` affects the way a client should interpret the `reset` property described below. - -### Content States on Manifests - -When an annotation with the motivation `contentState` is provided via the `annotations` property of a Manifest, rather than contextually via `scope`, it is assumed to be generally available for selection by the user at any time. A client may present such as annotations as a menu of views, allowing arbitrary jumping into any Scene (or Canvas or Timeline) from any other point. - -// Is there some overlap here with Range? - -### Processing Content States in Scopes: reset - -// This may not be what we have discussed... - -When a Content State is applied to a Container such as a Scene, it is assumed to be a "diff" - for example if 3 cameras and 4 lights are already present in the Scene, and a Content State asserts a single new Camera, the default behavior is to add this fourth Camera to the Scene and leave the existing resources as they are. - -The client should reset the Container to its original state before applying the diff operation. However, for narratives that cumulatively build a Scene this may lead to excessively verbose Manifests. When moving through the items of an Annotation page with the behavior `sequence`, the Container is not reset and the diff is cumulative; modifications from one `scope` persist into the next. If this behavior is not wanted, the `reset` property of the content state annotation should be set to `true`: - -```json -{ - "type": "Annotation", - "motivation": ["contentState"], - "reset": true -} -``` - -Before applying the content state to the Scene, the client should reset the Scene to its original state as provided by the Manifest. - -// I am assuming reset is always true except in `sequence` - otherwise it's completely unpredictable!! or is it... arbitrary navigation, state provided by initialization content states, etc... - -### Contribute additional information permanently - -Rerum inbox scenario - should be covered in CS2 protocol - -### activating - animation and interactions - -Annotations with the motivation `activating` are referred to as _activating_ annotations. - -There are two uses of `activating` annotations: - -#### Triggering a content state - -An activating annotation links a painting annotation to a content state. When a user interacts with the painting annotation - whether through clicking it, tapping it, or other client-specific behaviors - the linked content state should be processed to modify the Scene or other Container, as in the previous examples. The painting annotation is the target of the activating annotation, and the content state is the body value. Only one content state may be specified in the body array, but the body array may include a `TextualBody` to provide a label for the interaction. The pattern is the same as for the `linking` motivation, but rather than the client opening a new browser window on the resource specified in the `body`, it applies the modification provided by the Content State. - -The activating annotation is provided in a Container's `annotations` property. In this (contrived for brevity) example, if the user clicks the mandible model, the Scene background changes color: - -```jsonc -{ - "id": "https://example.org/iiif/3d/activating.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/scene-with-activation", - "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/painting-anno-for-mandible", - "type": "Annotation", - "motivation": ["painting"], - "body": { - "id": "https://raw.githubusercontent.com/IIIF/3d/main/assets/whale/whale_mandible.glb", - "type": "Model" - }, - "target": { - // SpecificResource with PointSelector - } - } - ], - "annotations": [ - { - "id": "https://example.org/iiif/scene1/page/activators", - "type": "AnnotationPage", - "items": [ - { - "id": "https://example.org/iiif/3d/anno2", - "type": "Annotation", - "motivation": ["activating"], - "body": [ - { - "type": "TextualBody", - "value": "A label for the activation may be provided as a TextualBody" - }, - { - // A body where the type is a IIIF Resource (eg Scene) is the Content State to apply - "id": "https://example.org/iiif/scene1/scene-with-activation", - "type": "Scene", - "backgroundColor": "#FF99AA" - } - ], - "target": { - "id": "https://example.org/iiif/3d/painting-anno-for-mandible", - "type": "Annotation" - } - } - ] - } - ] - } - ] - } ] } ``` +Map example -// Can you put activating annotations in `manifest.annotations`? They would work there too, you have all the information. - - - -#### 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. - -This pattern is similar to the above, except that: - - - There is no Content State in the `body`, but there _MUST_ be a TextualBody to label the interaction. (?? must?) - - The `target` selects a _named animation_ in the model. The `target` MUST be a SpecificResource, where the `source` is the painting annotation that paints the model, and the `selector` is of type `AnimationSelector` with the `value` being a string that corresponds to the animation in the model. - - The format of the `value` string is implementation=specific, and will depend on how different 3D formats support addressing of animations within models. The same model can be painted multiple times into the scene, and you might want to activate only one model's animation, thus we need to refer to the annotation that paints the model, not the model directly. - - - -```jsonc -{ - "id": "https://example.org/iiif/3d/activating-animation.json", - "type": "Manifest", - "label": { "en": ["Music Box with lid that opens as an internal animation"] }, - "items": [ - { - "id": "https://example.org/iiif/scene1/scene-with-activation-animation", - "type": "Scene", - "label": { "en": ["A Scene Containing a Music Box"] }, - "items": [ - { - "id": "https://example.org/iiif/scene-with-activation-animation/page/p1/1", - "type": "AnnotationPage", - "items": [ - { - "id": "https://example.org/iiif/3d/painting-anno-for-music-box", - "type": "Annotation", - "motivation": ["painting"], - "body": { - "id": "https://raw.githubusercontent.com/IIIF/3d/main/assets/music-box.glb", - "type": "Model" - }, - "target": { - // SpecificResource with PointSelector - } - } - ], - "annotations": [ - { - "id": "https://example.org/iiif/scene1/page/activators", - "type": "AnnotationPage", - "items": [ - { - "id": "https://example.org/iiif/3d/anno2", - "type": "Annotation", - "motivation": ["activating"], - "body": [ - { - "type": "TextualBody", - "value": "Click the box to open the lid" - } - ], - "target": [ - { - "type": "SpecificResource", - "source": "https://example.org/iiif/3d/painting-anno-for-music-box", - "selector": [ - { - "type": "AnimationSelector", - "value": "open-the-lid" - } - ] - } - ] - } - ] - } - ] - } - ] - } - ] -} -``` - -// TODO - -activating to apply a content state and activating to trigger a named animation - use of body and target... what if we want to click a painting anno to trigger the animation? -Can we ADD that to the target, alongside the SpecificResource with the AnimationSelector? - -if the `target` is an AnimationSelector, then the `body` can ONLY be TextualBody (or list of TextualBody)? - -There is a more general rule here! - -### reset - -See above... - -"diff", "original state" etc -behavior for "force-order"? -behavior: sequence - -## Selectors - -preamble - cover all the use cases - -### SpecificResource - -(This heading should be more descriptive) - -fragments/segments/parts of resources -SvgSelector -xywh - - -### PointSelector - - -## Scene-Specific Resources - -### 3D considerations / principles - -"models" (content resources in 3D) -"local coordinate spaces" - -### Camera - -A Camera provides a view of a region of the Scene's space from a particular position within the Scene; the client constructs a viewport into the Scene and uses the view of one or more Cameras to render that region. The size and aspect ratio of the viewport is client and device dependent. - -This specification defines two types of Camera: - -| Class | Description | -| ------------------- | ------------ | -| `PerspectiveCamera` | `PerspectiveCamera` mimics the way the human eye sees, in that objects further from the camera are smaller | -| `OrthographicCamera` | `OrthographicCamera` removes visual perspective, resulting in object size remaining constant regardless of its distance from the camera | - -Cameras are positioned within the Scene facing in a specified direction. Both position and direction are defined through the Annotation which adds the Camera to the Scene, described below in the sections on [Painting Annotations][], [Transforms][], and [Relative Rotation][]. If either the position or direction is not specified, then the position defaults to the origin, and facing direction defaults to pointing along the z axis towards negative infinity. The camera's up direction by default points along the y axis towards positive infinity, but this may be modified by transforms. - -The region of the Scene's space that is observable by the camera is bounded by two planes orthogonal to the direction the camera is facing, given in the `near` and `far` properties, and a vertical projection angle that provides the top and bottom planes of the region. - -The `near` property defines the minimum distance from the camera at which something in the space must exist in order to be viewed by the camera. Anything nearer to the camera than this distance will not be viewed. Conversely, the `far` property defines a maximum distance from the camera at which something in the space must exist in order to be viewed by the camera. Anything further away will not be viewed. - -For PerspectiveCameras, the vertical projection angle is specificed using the full angular extent in degrees from the top plane to the bottom plane using the `fieldOfView` property. The `fieldOfView` angle MUST be greater than 0 and less than 180. For OrthographicCameras, the vertical projection is always parallel and thus not defined. - -If any of these properties are not specified explicitly, they default to the choice of the client implementation. - -drawing of a geometrical frustrum truncated by near and far distances - - -The first Camera defined and not hidden in a Scene is the default Camera used to display Scene contents. If the Scene does not have any Cameras defined within it, then the client MUST provide a default Camera. The type, properties and position of this default camera are client-dependent. - -```json -{ - "id": "https://example.org/iiif/camera/1", - "type": "PerspectiveCamera", - "near": 1.0, - "far": 100.0, - "fieldOfView": 45.0 -} -``` - - - -### Light - -One or more Lights MUST be present within the Scene in order to have objects within it be visible to the Cameras. - -This specification defines four types of Light: - -| Class | Description | -| ----- | ------------ | -| `AmbientLight` | AmbientLight evenly illuminates all objects in the scene, and does not have a direction or position. | -| `DirectionalLight` | DirectionalLight emits in a specific direction as if it is infinitely far away and the rays produced from it are all parallel. It does not have a specific position. | -| `PointLight` | PointLight emits from a single point within the scene in all directions. | -| `SpotLight` | SpotLight emits a cone of light from a single point in a given direction. | - -Lights defined in this specification have a `color` and an `intensity`. The color is given as an RGB value, such as "#FFFFFF" for white. The intensity is the strength or brightness of the light, and described using a `Value` construct. - -SpotLight has an additional property of `angle`, specified in degrees, which is the angle from the direction that the Light is facing to the outside extent of the cone. - -diagram of cone geometry showing how the angle of the cone is defined - -Lights that require a position and/or direction have these through the Annotation which associates them with the Scene, described below in the sections on [Painting Annotations][] and [Transforms][]. If a Light does not have an explicit direction, then the default is in the negative y direction (downwards). If a Light does not have an explicit position in the coordinate space, then the default is at the origin. - -This specification does not define other aspects of Lights, such as the rate of decay of the intensity of the light over a distance, the maximum range of the light, or the penumbra of a cone. Implementation of these aspects is client-dependent. - -If there are no Lights present within the Scene, then the viewer MUST add at least one Light. The types and properties of Lights added in this way are client-dependent. - -```json -{ - "id": "https://example.org/iiif/light/1", - "type": "AmbientLight", - "color": "#FFFFFF", - "intensity": {"type": "Value", "value": 0.6, "unit": "relativeUnit"} -} -``` - - - -### Transforms - -The Annotation with a Selector on the target can paint a resource at a point other than the origin, however it will be at its initial scale and rotation, which may not be appropriate for the scene that is being constructed. - -This specification defines a new class of manipulations for SpecificResources called a `Transform`, with three specific sub-classes. Each Transform has three properties, `x`, `y` and `z` which determine how the Transform affects that axis in the local coordinate space. - - -| Class | Description | -| --------------- | ------------ | -| ScaleTransform | A ScaleTransform applies a multiplier to one or more axes in the local coordinate space. A point that was at 3.5, after applying a ScaleTransform of 2.0 would then be at 7.0. If an axis value is not specified, then it is not changed, resulting in a default of 1.0 | -| RotateTransform | A RotateTransform rotates the local coordinate space around the given axis in a counter-clockwise direction around the axis itself (e.g. around a pivot point of 0 on the axis). A point that was at x=1,y=1 and was rotated 90 degrees around the x axis would be at x=1,y=0,z=1. If an axis value is not specified, then it is not changed, resulting in a default of 0.0 | -| TranslateTransform | A TranslateTransform moves all of the objects in the local coordinate space the given distance along the axis. A point that was at x=1.0, after applying a TranslateTransform of x=1.0 would be at x=2.0. If an axis value is not specified then it is not changed, resulting in a default of 0.0 | - -Transforms are added to a SpecificResource using the `transform` property. The value of the property is an array, which determines the order in which the transforms are to be applied. The resulting state of the first transform is the input state for the second transform, and so on. Different orders of the same set of transforms can have different results, so attention must be paid when creating the array and when processing it. - -The point around which RotateTransform rotates the space is the origin. This "pivot point" cannot be changed directly, but instead a TranslateTransform can be used to move the desired pivot point to the be at the origin, then the RotateTransform applied. - -Transforms are only used in the Presentation API when the SpecificResource is the `body` of the Annotation, and are applied before the resource is painted into the scene at the point given in the `target`. - -```json -{ - "type": "SpecificResource", - "source": { - "id": "https://example.org/iiif/assets/model1.glb", - "type": "Model" - }, - "transform": [ - { - "type": "RotateTransform", - "x": 0.0, - "y": 180.0, - "z": 0.0 - }, - { - "type": "TranslateTransform", - "x": 1.0, - "y": 0.0, - "z": 0.0 - } - ] -} -``` - - -#### Relative Rotation - -It is useful to be able to rotate a light or camera resource such that it is facing another object or point in the Scene, rather than calculating the angles within the Scene's coordinate space. This is accomplished with a property called `lookAt`, valid on DirectionalLight, SpotLight, and all Cameras. The value of the property is either a PointSelector, a WktSelector, the URI of an Annotation which paints something into the current Scene, or a Specific Resource with a selector identifying a point or region in an arbitrary container. - -If the value is a PointSelector, then the light or camera resource is rotated around the x and y axes such that it is facing the given point. If the value is a WktSelector, then the resource should be rotated to face the given region. If the value is an Annotation which targets a point via a PointSelector, URI fragment or other mechanism, then the resource should be rotated to face that point. If the value is a Specific Resource, the source container for the Specific Resource must be painted into the current Scene, and the Specific Resource selector should identify a point or region in the source container. In this case, the light or camera resource should be rotated to face the point or region in the source container where the point or region is located within the current Scene's coordinate space. This allows light or camera resources to face a specific 2D point on a Canvas painted into a 3D scene. - -This rotation happens after the resource has been added to the Scene, and thus after any transforms have taken place in the local coordinate space. - -```json -"lookAt": { - "type": "PointSelector", - "x": 3, - "y": 0, - "z": -10 -} -``` - - -#### Excluding - -Just as a Scene may contain multiple Annotations with model, light, and camera resources, a single 3D model file may contain a collection of 3D resources, including model geometry, assemblages of lights, and/or multiple cameras, with some of these potentially manipulated by animations. When painting Scenes or models that themselves may contain groups of resources within a single Scene, it may not always be appropriate to include all possible cameras, lights, or other resources, and it may be desirable to opt not to import some of these resources. This is accomplished through the Annotation property `exclude`, which prevents the import of audio, lights, cameras, or animations from a particular Scene or model prior to the Annotation being painted into a Scene. When `exclude` is used, the excluded resource type should not be loaded into the Scene, and it is not possible to reactivate or turn on these excluded resources after loading. - -Painting a Scene into another while excluding import of several types of resources: -```json -{ - "id": "https://example.org/iiif/3d/anno1", - "type": "Annotation", - "motivation": ["painting"], - "exclude": ["Audio", "Lights", "Cameras", "Animations"], - "body": { - "id": "https://example.org/iiif/scene1", - "type": "Scene" - }, - "target": "https://example.org/iiif/scene2" -} -``` - - - -## Advanced Association Features - -(This needs to be sprinkled throughout above - especially as SpecificResource must be introduced early for 3D) - -### Nesting - -A Canvas can be painted into a Scene as an Annotation, but the 2D nature of Canvases requires special consideration due to important differences between Canvases and Scenes. A Canvas describes a bounded 2D space with finite `height` and `width` measured in pixels with a pixel origin at the top-left corner of the Canvas, while Scenes describe a boundless 3D space with x, y, and z axes of arbitrary coordinate units and a coordinate origin at the center of the space. It is important to note that in many cases the pixel scale used by a Canvas or a 2D image content resource will not be in proportion to the desired 3D coordinate unit scale in a Scene. - -When a Canvas is painted as an Annotation targeting a Scene, the top-left corner of the Canvas (the pixel origin) is aligned with the 3D coordinate origin of the Scene. The top edge of the Canvas is aligned with (e.g., is colinear to) the positive x axis extending from the coordinate origin. The left edge of the Canvas is aligned with (e.g., is colinear to) the negative y axis extending from the coordinate origin. The Canvas is scaled to the Scene such that the pixel dimensions correspond to 3D coordinate units - a Canvas 200 pixels wide and 400 pixels high will extend 200 coordinate units across the x axis and 400 coordinate units across the y axis. Please note: direction terms "top", "bottom", "right", and "left" used in this section refer to the frame of reference of the Canvas itself, not the Scene into which the Canvas is painted. - -A Canvas in a Scene has a specific forward face and a backward face. By default, the forward face of a Canvas should point in the direction of the positive z axis. If the property `backgroundColor` is used, this color should be used for the backward face of the Canvas. Otherwise, a reverse view of the forward face of the Canvas should be visible on the backward face. - -
- To Do: Add an image demonstrating default Canvas placement in Scene -
- -A `PointSelector` can be used to modify the point at which the Canvas will be painted, by establishing a new point to align with the top-left corner of the Canvas instead of the Scene coordinate origin. Transforms can also be used to modify Canvas rotation, scale, or translation. - -It may be desirable to exercise greater control over how the Canvas is painted into the Scene by selecting the coordinate points in the Scene that should correspond to each corner of the Canvas. This provides fine-grained manipulation of Canvas placement and/or scale, and for optionally introducing Canvas distortion or skew. Annotations may use a WktSelector to select different points in the Scene to align with the top-left, bottom-left, bottom-right, and top-right corners of the Canvas. In this case, the four Scene coordinates should be listed beginning with the coordinate corresponding to the top-left corner of the Canvas, and should proceed in a counter-clockwise winding order around the Canvas, with coordinates corresponding to bottom-left, bottom-right, and top-right corners in order respectively. The use of WktSelector for this purpose overrides any use of Transforms on the Canvas Annotation. - -Example placing top-left at (0, 1, 0); bottom-left at (0, 0, 0); bottom-right at (1, 0, 0); and top-right at (1, 1, 0): -```json -"selector": [ - { - "type": "WktSelector", - "value": "POLYGONZ((0 1 0, 0 0 0, 1 0 0, 1 1 0))" - } -] -``` - -When a Scene is nested into another Scene, the `backgroundColor` of the Scene to be nested should be ignored as it is non-sensible to import. All Annotations painted into the Scene to be nested will be painted into the Scene into which content is being nested, including Light or Camera resources. If the Scene to be nested has one or more Camera Annotations while the Scene into which content is being nested does not, the first Camera Annotation from the nested Scene will become the default Camera for the overall Scene. - -### Embedded Content - -e.g., painting TextualBody on Canvas - -Todo: This is mostly copy-pasted from properties, is it needed here? -It is important to be able to position the textual body of an annotation within the Container's space that the annotation also targets. For example, a description of part of an image in a Canvas should be positioned such that it does not obscure the image region itself and labels to be displayed as part of a Scene should not be rendered such that the text is hidden by the three dimensional geometry of the model. The positioning of the textual body in a container is accomplished through the `position` property, which has as a value a Specific Resource identifying the targeted container as the source and a selector defining how the textual body should be positioned in the targeted container. If this property is not supplied, then the client should do its best to ensure the content is visible to the user. - -### Comment Annotations - -(move to Annotation section) - - -### Choice of Alternative Resources - -(move to Annotation section) - - -### Non Rectangular Segments - -SvgSelector - move to SpecificResource too ^^ - - -### Style - -Move to SpecificResource - - -### Rotation - - -### Hotspot Linking and Activation - -Move to SpecificResource - - - -## Conveying Physical Dimensions - -(why is this important!?) - -(move the props to vocab doc) - -### spatialScale - -### temporalScale - - -``` -{ - "spatialScale": { - "factor": 22.0, - "units": "m" - }, - - - // this would be rarely used - "temporalScale": { - "factor": 0.00001 - } - -} -``` - -`factor` Required A floating point ratio. -`units` Required A real-world measuring unit. Always seconds for temporalScale. Possible values for spatialScale include: "m", "ft". (is that it?) - -For a Canvas, it's the physical "size" of each cartesian integer unit. -For a Scene, it's the physical size of the unit vector. -For a timeline it's the ratio of time in the recording to time in the real world. - +navDate +??? example -(define props in the Vocabulary doc) +### Ranges -## HTTP Requests and Responses +Periodical example - with navDate again +Table of Contents as simple example +thumbnail-nav +sequence -### URI Recommendations -### Requests +### Collections -### Responses +Multi-vol work +Archive example +back ref to periodical? -### Authentication +Paged collections and conceptual collections -## Accessibility -(new section) -`provides` +## Protocol -## Appendices -### Summary of Property Requirements +## Terminology -### Example Manifest Response +The principles of [Linked Data][org-linked-data] and the [Architecture of the Web][org-w3c-webarch] are adopted in order to provide a distributed and interoperable framework. The [Shared Canvas data model][shared-canvas] and [JSON-LD][org-w3c-json-ld] are leveraged to create an easy-to-implement, JSON-based format. -### Versioning +This specification uses the following terms: -### Acknowledgements +* __embedded__: When a resource (A) is embedded within an embedding resource (B), the complete JSON representation of resource A is present within the JSON representation of resource B, and dereferencing the URI of resource A will not result in additional information. Example: Canvas A is embedded in Manifest B. +* __referenced__: When a resource (A) is referenced from a referencing resource (B), an incomplete JSON representation of resource A is present within the JSON representation of resource B, and dereferencing the URI of resource A will result in additional information. Example: Manifest A is referenced from Collection B. +* __HTTP(S)__: The HTTP or HTTPS URI scheme and internet protocol. -### Change Log +The terms _array_, _JSON object_, _number_, _string_, and _boolean_ in this document are to be interpreted as defined by the [Javascript Object Notation (JSON)][org-rfc-8259] specification. -"Exclude Audio" +The key words _MUST_, _MUST NOT_, _REQUIRED_, _SHALL_, _SHALL NOT_, _SHOULD_, _SHOULD NOT_, _RECOMMENDED_, _MAY_, and _OPTIONAL_ in this document are to be interpreted as described in [RFC 2119][org-rfc-2119]. From e9b917debb9dee92c09b1930070dbe3307a7371c Mon Sep 17 00:00:00 2001 From: tomcrane Date: Mon, 17 Mar 2025 17:56:06 -0400 Subject: [PATCH 031/130] WIP prezi 4 --- source/presentation/4.0/index-draft.md | 108 +---------------------- source/presentation/4.0/index.md | 116 ++++++++++++++++++++++++- 2 files changed, 113 insertions(+), 111 deletions(-) diff --git a/source/presentation/4.0/index-draft.md b/source/presentation/4.0/index-draft.md index 822e068f7..bc498dde7 100644 --- a/source/presentation/4.0/index-draft.md +++ b/source/presentation/4.0/index-draft.md @@ -51,75 +51,10 @@ __Previous Version:__ [3.0][prezi30] ---- -# Presentation 4 - -## Introduction - -Manifests, Containers, Annotations oh my! -Manifest as unit of distribution - - -## Content Resources - -There is stuff that we want to show - images, video, audio, 3D models etc - -### type value of Content Resources - -| Class | Description | -| ------------- | -------------------------------- | -| `Image` | Two dimensional visual resources primarily intended to be seen, such as might be rendered with an <img> HTML tag | -| `Model` | A three (or more) dimensional model intended to be interacted with by humans | -| `Sound` | Auditory resources primarily intended to be heard, such as might be rendered with an <audio> HTML tag | -| `Text` | Resources primarily intended to be read | -| `Video` | Moving images, with or without accompanying audio, such as might be rendered with a <video> HTML tag | -{: .api-table #table-type} - -## Containers - -This is where we put content resources -"painting" - -And we can also put other things: -"supplementing" - -And we can nest them -"Nesting" (see 3d draft) - -The defined Container types are `Timeline`, `Canvas` and `Scene`. Extensions may define additional Container types. - -As multiple models, lights, cameras, and other resources can be associated with and placed within a Scene container, Scenes provide a straightforward way of grouping content resources together within a space. Scenes, as well as other IIIF containers such as Canvases, can also be embedded within a Scene, allowing for the nesting of content resources. - -A Scene or a Canvas may be treated as a content resource, referenced or described within the `body` of an Annotation. As with models and other resources, the Annotation is associated with a Scene into which the Scene or Canvas is to be nested through an Annotation `target`. The content resource Scene will be placed within the `target` Scene by aligning the coordinate origins of the two scenes. Alternately, Scene Annotations may use `PointSelector` to place the origin of the resource Scene at a specified coordinate within the `target` Scene. - -As with other resources, it may be appropriate to modify the initial scale, rotation, or translation of a content resource Scene prior to painting it within another Scene. Scenes associated with SpecificResources may be manipulated through the transforms described in Transforms(transforms_section). - -A simple example painting one Scene into another: - -```json -{ - "id": "https://example.org/iiif/3d/anno1", - "type": "Annotation", - "motivation": ["painting"], - "body": { - "id": "https://example.org/iiif/scene1", - "type": "Scene" - }, - "target": "https://example.org/iiif/scene2" -} -``` - - -Content resources of the appropriate dimension(s) may be annotated into a Container that has those dimensions. ### Timeline -A Container that represents a bounded temporal range, without any spatial coordinates. - -* has continuous duration in seconds - for all or part of its duration. - - A Timeline _MUST_ have a `duration` property that defines its length in seconds. The `duration` value must be a positive floating point number. An annotation that targets a Scene using a PointSelector without any temporal refinement implicitly targets the Scene's entire duration. @@ -213,47 +148,6 @@ It is an error to select a temporal region of a Scene that does not have a `dura - -### Canvas - -A Container that represents a bounded, two-dimensional space and has content resources associated with all or parts of it. It may also have a bounded temporal range in the same manner as a Timeline. - -* has integer, unitless width and height -* has optional continuous duration in seconds - -### Scene - -A Container that represents a boundless three-dimensional space and has content resources positioned at locations within it. Rendering a Scene requires the use of Cameras and Lights. It may also have a bounded temporal range in the same manner as a Timeline. - -* has continuous, unitless x,y,z cartesian coordinate space -* has optional continuous duration in seconds - -A Scene in IIIF is a virtual container that represents a boundless three-dimensional space and has content resources, lights and cameras positioned at locations within it. It may also have a duration to allow the sequencing of events and timed media. Scenes have infinite height (y axis), width (x axis) and depth (z axis), where 0 on each axis (the origin of the coordinate system) is treated as the center of the scene's space. -The positive y axis points upwards, the positive x axis points to the right, and the positive z axis points forwards (a [right-handed cartesian coordinate system](https://en.wikipedia.org/wiki/Right-hand_rule)). - -The axes of the coordinate system are measured in arbitrary units and these units do not necessarily correspond to any physical unit of measurement. This allows arbitrarily scaled models to be used, including very small or very large, without needing to deal with very small or very large values. If there is a correspondence to a physical scale, then this can be asserted using the physical dimensions pattern(fwd-ref-to-phys-dims). - -diagram of Right handed cartesian coordinate system - - -As with other containers in IIIF, Annotations are used to target the Scene to place content such as 3d models into the scene. Annotations are also used to add lights and cameras. A Scene can have multiple models, lights, cameras and other resources, allowing them to be grouped together. Scenes and other IIIF containers, such as Canvases, may also be embedded within Scenes, as described below in the nesting section [fwd-ref-to-nesting]. - -```json -{ - "id": "https://example.org/iiif/scenes/1", - "type": "Scene", - "label": {"en": ["Chessboard"]}, - "backgroundColor": "#000000", - "items": [ - "Note: Annotations Live Here" - ] -} -``` - - - -## Putting stuff into Containers (composition) - ### Annotation @@ -812,7 +706,7 @@ This pattern is similar to the above, except that: - There is no Content State in the `body`, but there _MUST_ be a TextualBody to label the interaction. (?? must?) - The `target` selects a _named animation_ in the model. The `target` MUST be a SpecificResource, where the `source` is the painting annotation that paints the model, and the `selector` is of type `AnimationSelector` with the `value` being a string that corresponds to the animation in the model. - The format of the `value` string is implementation=specific, and will depend on how different 3D formats support addressing of animations within models. The same model can be painted multiple times into the scene, and you might want to activate only one model's animation, thus we need to refer to the annotation that paints the model, not the model directly. + The format of the `value` string is implementation-specific, and will depend on how different 3D formats support addressing of animations within models. The same model can be painted multiple times into the scene, and you might want to activate only one model's animation, thus we need to refer to the annotation that paints the model, not the model directly. diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index 906a57969..8289b42e6 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -81,27 +81,89 @@ Simple model diagram Manifests and Containers briefly + ### Manifests -The document, the unit of distribution of IIIF +A Manifest is the primary unit of distribution of IIIF. It is a JSON document that provides a description of the structure and properties of a single item to be presented to the user, such as a title and other descriptive and linking information about the object and/or the intellectual work that it conveys. The scope of what constitutes an item, and thus its Manifest, is up to the publisher of that Manifest. The Manifest contains sufficient information for the client to initialize itself and begin to display something quickly to the user. + +The Manifest's `items` property is a list of _Containers_ of _Content Resources_ (images, 3D models, audio, etc). Client software loads the Manifest and presents the Content Resources to the user. The `items` property provides an order to the content. -A sequence of Containers that carry the content. +Manifests have descriptive, technical and linking properties. The required properties of Manifests are `id`, `type`, `items` and `label`. Additional descriptive properties include `summary`, `metadata`, `rights`, `thumbnail`, `homepage` and `provider`. + +[See Model Docs](manifest) + +``` +Manifest JSON +``` ### Containers -Timeline, Canvas, Scene +A Container is a frame of reference that allows the relative positioning of Content Resources, a concept borrowed from standards like PDF and HTML, or applications like Photoshop and PowerPoint, where an initially blank display surface has images, video, text and other content "painted" on to it. The frame is defined by a set of dimensions, with different types of Container having different dimensions. This specification defines three sub-classes of Container: Timeline (which only has a duration), Canvas (which has bounded height and width, and may have a duration), and Scene (which has infinite height, width and depth, and may have a duration). + +And we can also put other things: +"supplementing" + + + +The defined Container types are: + +#### Timeline + +A Container that represents a bounded temporal range, without any spatial coordinates. + +* has continuous duration in seconds for all or part of its duration. +* Typically used for audio-only content + +#### Canvas +A Container that represents a bounded, two-dimensional space and has content resources associated with all or parts of it. It may also have a bounded temporal range in the same manner as a Timeline. -### Painting Annotations +* has integer, unitless width and height +* has optional continuous duration in seconds +* Typically used for Image content, and with duration, for Video content. +#### Scene + +A Container that represents a boundless three-dimensional space and has content resources positioned at locations within it. Rendering a Scene requires the use of Cameras and Lights. It may also have a bounded temporal range in the same manner as a Timeline. + +* has continuous, unitless x,y,z cartesian coordinate space +* has optional continuous duration in seconds +* Typically used for 3D models, and can include audio, video and image content + + +### Annotations + +IIIF uses the concept of _Annotation_ to link resources together. Why is this a different sense from what I am used to? Because this: W3C go read that then come back. + +BUT it can be used for notes in the margin, commentary and all those more usual senses of the word, too. It's just that we borrow that linking mechanism for the Content Resources, too. + +Annotations are primarily used to associate content resources with Containers. The same mechanism is used for the visible and/or audible resources as is used for transcriptions, commentary, tags and other content. This provides a single, unified method for aligning information, and provides a standards-based framework for distinguishing parts of resources and parts of Canvases. As Annotations can be added later, it promotes a distributed system in which publishers can align their content with the descriptions created by others. + +Now that we have this linking mechanism... PAINTING + +Painting Annotations are used to associate models, lights, cameras, and IIIF containers such as Canvases, with Scenes. They have a `type` of "Annotation", a `body` (being the resource to be added to the scene) and a `target` (being the scene or a position within the scene). They must have a `motivation` property with the value of "painting" to assert that the resource is being painted into the Scene, rather than the Annotation being a comment about the Scene. Everything is an anno but these are special and core +There are other important uses of annotation, they are not all painting annos - see later... + +``` +JSON of painting anno +``` + +By the time you get here you are comfortable dropping the phrase "painting annotation" into casual conversation. + + ### Content Resources + +There is stuff that we want to show - images, video, audio, 3D models etc + Image, Sound, Video, Model, Text (see model) +And we can nest Containers so they are Content Resources too + SpecificResource @@ -124,6 +186,52 @@ A video on a Canvas with duration ### 3D +A Scene in IIIF is a virtual container that represents a boundless three-dimensional space and has content resources, lights and cameras positioned at locations within it. It may also have a duration to allow the sequencing of events and timed media. Scenes have infinite height (y axis), width (x axis) and depth (z axis), where 0 on each axis (the origin of the coordinate system) is treated as the center of the scene's space. +The positive y axis points upwards, the positive x axis points to the right, and the positive z axis points forwards (a [right-handed cartesian coordinate system](https://en.wikipedia.org/wiki/Right-hand_rule)). + +The axes of the coordinate system are measured in arbitrary units and these units do not necessarily correspond to any physical unit of measurement. This allows arbitrarily scaled models to be used, including very small or very large, without needing to deal with very small or very large values. If there is a correspondence to a physical scale, then this can be asserted using the physical dimensions pattern(fwd-ref-to-phys-dims). + +diagram of Right handed cartesian coordinate system + + + +As multiple models, lights, cameras, and other resources can be associated with and placed within a Scene container, Scenes provide a straightforward way of grouping content resources together within a space. Scenes, as well as other IIIF containers such as Canvases, can also be embedded within a Scene, allowing for the nesting of content resources. + +A Scene or a Canvas may be treated as a content resource, referenced or described within the `body` of an Annotation. As with models and other resources, the Annotation is associated with a Scene into which the Scene or Canvas is to be nested through an Annotation `target`. The content resource Scene will be placed within the `target` Scene by aligning the coordinate origins of the two scenes. Alternately, Scene Annotations may use `PointSelector` to place the origin of the resource Scene at a specified coordinate within the `target` Scene. + + +As with other containers in IIIF, Annotations are used to target the Scene to place content such as 3d models into the scene. Annotations are also used to add lights and cameras. A Scene can have multiple models, lights, cameras and other resources, allowing them to be grouped together. Scenes and other IIIF containers, such as Canvases, may also be embedded within Scenes, as described below in the nesting section [fwd-ref-to-nesting]. + +```json +{ + "id": "https://example.org/iiif/scenes/1", + "type": "Scene", + "label": {"en": ["Chessboard"]}, + "backgroundColor": "#000000", + "items": [ + "Note: Annotations Live Here" + ] +} +``` +As with other resources, it may be appropriate to modify the initial scale, rotation, or translation of a content resource Scene prior to painting it within another Scene. Scenes associated with SpecificResources may be manipulated through the transforms described in Transforms(transforms_section). + +A simple example painting one Scene into another: + +```json +{ + "id": "https://example.org/iiif/3d/anno1", + "type": "Annotation", + "motivation": ["painting"], + "body": { + "id": "https://example.org/iiif/scene1", + "type": "Scene" + }, + "target": "https://example.org/iiif/scene2" +} +``` + + + Whale bone with a camera and a light From debe57ca0dc64d716060f7b5ea3c8ab960456359 Mon Sep 17 00:00:00 2001 From: Rob Sanderson Date: Mon, 17 Mar 2025 17:55:53 -0400 Subject: [PATCH 032/130] updates --- source/presentation/4.0/model.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index 7b5859de4..55b5dad0c 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -113,7 +113,14 @@ Collection Pages follow the ActivityStreams model, as also used in Annotation Co ### Manifest -A Manifest is a description of the structure and properties of a single item to be presented to the user, such as a title and other descriptive and linking information about the object and/or the intellectual work that it conveys. The scope of what constitutes an item, and thus its Manifest, is up to the publisher of that Manifest. The Manifest contains sufficient information for the client to initialize itself and begin to display something quickly to the user. +A Manifest is the primary unit of distribution of IIIF and provides a description of the structure and properties of a single item to be presented to the user. + +A Manifest _MUST_ have the following properties: [id](#id), [type](#type), [label](#label), and [items](#items) + +A Manfiest _SHOULD_ have the following properties: [metadata](#metadata), [summary](#summary), [provider](#provider), and [thumbnail](#thumbnail) + +A Manifest _MAY_ have the following properties: [requiredStatement](#requiredStatement), rights, navDate, navPlace, placeholder, accompanying, viewingDirection, behavior, seeAlso, service, services, homepage, rendering, partOf, start, structures, and annotations. + Manifests _MUST_ be identified by a URI and it _MUST_ be an HTTP(S) URI, given in the `id` property. It _MUST_ be able to be dereferenced to retrieve the JSON description of the Manifest. @@ -126,7 +133,7 @@ The Manifest _MAY_ have an `annotations` property, which includes Annotation Pag ### Container Classes -A Container is a frame of reference that allows the relative positioning of content, a concept borrowed from standards like PDF and HTML, or applications like Photoshop and PowerPoint, where an initially blank display surface has images, video, text and other content "painted" on to it. The frame is defined by a set of dimensions, with different types of Container having different dimensions. This specification defines three sub-classes of Container: Timeline (which only has a duration), Canvas (which has bounded height and width, and may have a duration), and Scene (which has infinite height, width and depth, and may have a duration). +A Container is a frame of reference that allows the relative positioning of content. All Containers _MUST_ be identified by a URI and it _MUST_ be an HTTP(S) URI. The URI of the Container _MUST NOT_ contain a fragment (a `#` followed by further characters), as this would make it impossible to refer to a segment of the Container's area using the [media fragment syntax][org-w3c-media-frags] of `#xywh=` for spatial regions, and/or `#t=` for temporal segments. Containers _MAY_ be able to be dereferenced separately from the Manifest via their URIs as well as being [embedded][prezi30-terminology]. @@ -152,7 +159,7 @@ The following set of classes are defined by the W3C's [Web Annotation Data Model #### Annotation -Annotations are primarily used to associate content resources with Containers. The same mechanism is used for the visible and/or audible resources as is used for transcriptions, commentary, tags and other content. This provides a single, unified method for aligning information, and provides a standards-based framework for distinguishing parts of resources and parts of Canvases. As Annotations can be added later, it promotes a distributed system in which publishers can align their content with the descriptions created by others. +Annotations are used to associate content resources with Containers, as well as for transcriptions, commentary, tags and the association of other content. This provides a single, unified method for aligning information, and provides a standards-based framework for distinguishing parts of resources and parts of Canvases. Annotations _MUST_ have their own HTTP(S) URIs, conveyed in the `id` property. The JSON-LD description of the Annotation _SHOULD_ be returned if the URI is dereferenced, according to the [Web Annotation Protocol][org-w3c-webanno-protocol]. From ad03ad31ee3f7893854c2a25c4ffc61b5a7f1b6f Mon Sep 17 00:00:00 2001 From: Rob Sanderson Date: Tue, 18 Mar 2025 09:01:06 -0400 Subject: [PATCH 033/130] alphasort --- source/presentation/4.0/model.md | 1521 ++++++++++++++---------------- 1 file changed, 731 insertions(+), 790 deletions(-) diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index 55b5dad0c..2e63386b1 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -115,20 +115,17 @@ Collection Pages follow the ActivityStreams model, as also used in Annotation Co A Manifest is the primary unit of distribution of IIIF and provides a description of the structure and properties of a single item to be presented to the user. + A Manifest _MUST_ have the following properties: [id](#id), [type](#type), [label](#label), and [items](#items) A Manfiest _SHOULD_ have the following properties: [metadata](#metadata), [summary](#summary), [provider](#provider), and [thumbnail](#thumbnail) -A Manifest _MAY_ have the following properties: [requiredStatement](#requiredStatement), rights, navDate, navPlace, placeholder, accompanying, viewingDirection, behavior, seeAlso, service, services, homepage, rendering, partOf, start, structures, and annotations. +A Manifest _MAY_ have the following properties: [requiredStatement](#requiredStatement), [rights](#rights), [navDate](#navDate), [navPlace](#navPlace), [placeholder](#placeholder), [accompanyingContainer](#accompanyingContainer), [viewingDirection](#viewingDirection), [behavior](#behavior), [seeAlso](#seeAlso), [service](#service), [services](#services), [homepage](#homepage), [rendering](#rendering), [partOf](#partOf), [start](#start), [structures](#structures), and [annotations](#annotations). Manifests _MUST_ be identified by a URI and it _MUST_ be an HTTP(S) URI, given in the `id` property. It _MUST_ be able to be dereferenced to retrieve the JSON description of the Manifest. -The members of a Manifest are listed in the `items` property. The members of Manifests _MUST_ be Containers, defined below, and are embedded within the Manifest. - -The Manifest _MAY_ also have a `structures` property listing one or more [Ranges][prezi30-range] which describe additional structure of the content, such as might be rendered as a table of contents. - -The Manifest _MAY_ have an `annotations` property, which includes Annotation Page resources where the Annotations have the Manifest as their `target`. These will typically be comment style Annotations, and _MUST NOT_ have `painting` as their `motivation`. +The members of a Manifest are listed in the `items` property. The members of Manifests _MUST_ be Containers, defined below, and are embedded within the Manifest. The Manifest _MAY_ have a `structures` property listing one or more [Ranges][#range] which describe additional structure of the content, such as might be rendered as a table of contents. The Manifest _MAY_ have an `annotations` property, which includes Annotation Page resources where the Annotations have the Manifest as their `target`. These Annotations _MUST NOT_ have `painting` as their `motivation`. ### Container Classes @@ -137,9 +134,7 @@ A Container is a frame of reference that allows the relative positioning of cont All Containers _MUST_ be identified by a URI and it _MUST_ be an HTTP(S) URI. The URI of the Container _MUST NOT_ contain a fragment (a `#` followed by further characters), as this would make it impossible to refer to a segment of the Container's area using the [media fragment syntax][org-w3c-media-frags] of `#xywh=` for spatial regions, and/or `#t=` for temporal segments. Containers _MAY_ be able to be dereferenced separately from the Manifest via their URIs as well as being [embedded][prezi30-terminology]. -Containers have an `items` property which is a list of Annotation Pages. Each Annotation Page, defined below, maintains a list of Annotations, which associate Content Resources to be rendered as part of the Container. - -Annotations that do not associate content to be rendered, but instead are about the Container such as a comment or tag, are recorded using Annotation Pages in the `annotations` property of the Container. +Containers _MUST_ have an `items` property which is a list of Annotation Pages. Each Annotation Page, defined below, maintains a list of Annotations, which associate Content Resources to be rendered as part of the Container. Annotations that do not associate content to be rendered, but instead are about the Container such as a comment or tag, are recorded using Annotation Pages in the `annotations` property of the Container. #### Timeline @@ -375,350 +370,284 @@ Ranges _MAY_ link to an Annotation Collection that has the content of the Range ## Properties -### Descriptive Properties -##### label +##### accompanyingContainer -A human readable label, name or title. The `label` property is intended to be displayed as a short, textual surrogate for the resource if a human needs to make a distinction between it and similar resources, for example between objects, pages, or options for a choice of images to display. The `label` property can be fully internationalized, and each language can have multiple values. This pattern is described in more detail in the [languages][prezi40-languages] section. +A single Container that provides additional content for use while rendering the resource that has the `accompanyingContainer` property. Examples include an image to show while a duration-only Canvas is playing audio; or background audio to play while a user is navigating an image-only Manifest. -The value of the property _MUST_ be a JSON object, as described in the [languages][prezi40-languages] section. +Clients _MAY_ display the content of an accompanying Container when presenting the resource. As with `placeholderContainer` above, when more than one accompanying Container is available, the client _SHOULD_ pick the one most specific to the content. Publishers _SHOULD NOT_ assume that the accompanying Container will be processed by all clients. Clients _SHOULD_ take care to avoid conflicts between time-based media in the accompanying Container and the content of the resource that has the `accompanyingContainer` property. - * A Collection _MUST_ have the `label` property with at least one entry.
- Clients _MUST_ render `label` on a Collection. - * A Manifest _MUST_ have the `label` property with at least one entry.
- Clients _MUST_ render `label` on a Manifest. - * All Container types _SHOULD_ have the `label` property with at least one entry.
- Clients _MUST_ render `label` on Container types, and _SHOULD_ generate a `label` for Containers that do not have them. - * All Content Resource types _MAY_ have the `label` property with at least one entry. If there is a Choice of Content Resource for the same Container, then they _SHOULD_ each have the `label` property with at least one entry.
- Clients _MAY_ render `label` on Content Resources, and _SHOULD_ render them when part of a Choice. - * A Range _SHOULD_ have the `label` property with at least one entry.
- Clients _MUST_ render `label` on a Range. - * An Annotation Collection _SHOULD_ have the `label` property with at least one entry.
- Clients _SHOULD_ render `label` on an Annotation Collection. - * Other types of resource _MAY_ have the `label` property with at least one entry.
- Clients _MAY_ render `label` on other types of resource. +The value of `accompanyingContainer` _MUST_ be a JSON object with the `id` and `type` properties. The value of `type` _MUST_ be a Container type. The JSON object _MAY_ have other properties valid for that Container type. + + * A Collection _MAY_ have the `accompanyingContainer` property.
+ Clients _MAY_ render `accompanyingContainer` on a Collection. + * A Manifest _MAY_ have the `accompanyingContainer` property.
+ Clients _MAY_ render `accompanyingContainer` on a Manifest. + * All Container types _MAY_ have the `accompanyingContainer` property.
+ Clients _MAY_ render `accompanyingContainer` on Containers. + * A Range _MAY_ have the `accompanyingContainer` property.
+ Clients _MAY_ render `accompanyingContainer` on a Range. + * Other types of resource _MUST NOT_ have the `accompanyingContainer` property.
+ Clients _SHOULD_ ignore `accompanyingContainer` on other types of resource. {% include api/code_header.html %} ``` json-doc -{ "label": { "en": [ "Example Object Title" ] } } +{ + "accompanyingContainer": { + "id": "https://example.org/iiif/1/timeline/accompany", + "type": "Timeline", + "duration": 180.0 + } +} ``` -##### metadata +##### angle -An ordered list of descriptions to be displayed to the user when they interact with the resource, given as pairs of human readable `label` and `value` entries. The content of these entries is intended for presentation only; descriptive semantics _SHOULD NOT_ be inferred. An entry might be used to convey information about the creation of the object, a physical description, ownership information, or other purposes. +!!! warning "Need more info" -The value of the `metadata` property _MUST_ be an array of JSON objects, where each item in the array has both `label` and `value` properties. The values of both `label` and `value` _MUST_ be JSON objects, as described in the [languages][prezi40-languages] section. +The value _MUST_ be a floating point number greater than 0 and less than 90, and is measure in degrees. If this property is not specified, then the default value is client-dependent. - * A Collection _SHOULD_ have the `metadata` property with at least one item.
- Clients _MUST_ render `metadata` on a Collection. - * A Manifest _SHOULD_ have the `metadata` property with at least one item.
- Clients _MUST_ render `metadata` on a Manifest. - * All Container types _MAY_ have the `metadata` property with at least one item.
- Clients _SHOULD_ render `metadata` on Containers. - * Other types of resource _MAY_ have the `metadata` property with at least one item.
- Clients _MAY_ render `metadata` on other types of resource. +* A SpotLight _SHOULD_ have the `angle` property.
+ Clients _SHOULD_ process the `angle` property on SpotLights. -Clients _SHOULD_ display the entries in the order provided. Clients _SHOULD_ expect to encounter long texts in the `value` property, and render them appropriately, such as with an expand button, or in a tabbed interface. +```json + "angle": 15.0 +``` +##### annotations + +An ordered list of Annotation Pages that contain commentary or other Annotations about this resource, separate from the Annotations that are used to paint content on to a Canvas. The `motivation` of the Annotations _MUST NOT_ be `painting`, and the target of the Annotations _MUST_ include this resource or part of it. + +The value _MUST_ be an array of JSON objects. Each item _MUST_ have at least the `id` and `type` properties. + + * A Collection _MAY_ have the `annotations` property with at least one item.
+ Clients _SHOULD_ process `annotations` on a Collection. + * A Manifest _MAY_ have the `annotations` property with at least one item.
+ Clients _SHOULD_ process `annotations` on a Manifest,. + * A Canvas _MAY_ have the `annotations` property with at least one item.
+ Clients _SHOULD_ process `annotations` on a Canvas. + * A Range _MAY_ have the `annotations` property with at least one item.
+ Clients _SHOULD_ process `annotations` on a Range. + * A content resource _MAY_ have the `annotations` property with at least one item.
+ Clients _SHOULD_ process `annotations` on a content resource. + * Other types of resource _MUST NOT_ have the `annotations` property.
+ Clients _SHOULD_ ignore `annotations` on other types of resource. {% include api/code_header.html %} ``` json-doc { - "metadata": [ + "annotations": [ { - "label": { "en": [ "Creator" ] }, - "value": { "en": [ "Anne Artist (1776-1824)" ] } + "id": "https://example.org/iiif/annotationPage/1", + "type": "AnnotationPage", + "items": [ { ... } ] } ] } ``` -##### summary +##### backgroundColor -A short textual summary intended to be conveyed to the user when the `metadata` entries for the resource are not being displayed. This could be used as a brief description for item level search results, for small-screen environments, or as an alternative user interface when the `metadata` property is not currently being rendered. The `summary` property follows the same pattern as the `label` property described above. +This property sets the background color behind any painted resources on a spatial Container, such as a Canvas or Scene. -The value of the property _MUST_ be a JSON object, as described in the [languages][prezi40-languages] section. +The value _MUST_ be string, which defines an RGB color. It SHOULD be a hex value starting with "#" and is treated in a case-insensitive fashion. If this property is not specified, then the default value is client-dependent. - * A Collection _SHOULD_ have the `summary` property with at least one entry.
- Clients _SHOULD_ render `summary` on a Collection. - * A Manifest _SHOULD_ have the `summary` property with at least one entry.
- Clients _SHOULD_ render `summary` on a Manifest. - * All Container types _MAY_ have the `summary` property with at least one entry.
- Clients _SHOULD_ render `summary` on Containers. - * Other types of resource _MAY_ have the `summary` property with at least one entry.
- Clients _MAY_ render `summary` on other types of resource. + * A Canvas _MAY_ have the `backgroundColor` property
+ Clients _SHOULD_ render `backgroundColor` on any resource type. + * A Scene _MAY_ have the `backgroundColor` property
+ Clients _SHOULD_ render `backgroundColor` on any resource type. + * Other resources _MUST NOT_ have the `backgroundColor` property. -{% include api/code_header.html %} -``` json-doc -{ "summary": { "en": [ "This is a summary of the object." ] } } +```json-doc +{ "backgroundColor": "#FFFFFF" } ``` -##### requiredStatement +##### behavior -Text that _MUST_ be displayed when the resource is displayed or used. For example, the `requiredStatement` property could be used to present copyright or ownership statements, an acknowledgement of the owning and/or publishing institution, or any other text that the publishing organization deems critical to display to the user. Given the wide variation of potential client user interfaces, it will not always be possible to display this statement to the user in the client's initial state. If initially hidden, clients _MUST_ make the method of revealing it as obvious as possible. +A set of user experience features that the publisher of the content would prefer the client to use when presenting the resource. This specification defines the values in the table below. Others may be defined externally as an [extension][prezi30-ldce]. -The value of the property _MUST_ be a JSON object, that has the `label` and `value` properties, in the same way as a `metadata` property entry. The values of both `label` and `value` _MUST_ be JSON objects, as described in the [languages][prezi40-languages] section. +In order to determine the behaviors that are governing a particular resource, there are four inheritance rules from resources that reference the current resource: +* Collections inherit behaviors from their referencing Collection. +* Manifests **DO NOT** inherit behaviors from any referencing Collections. +* Containers inherit behaviors from their referencing Manifest, but **DO NOT** inherit behaviors from any referencing Ranges, as there might be several with different behaviors. +* Ranges inherit behaviors from any referencing Range and referencing Manifest. - * Any resource type _MAY_ have the `requiredStatement` property.
- Clients _MUST_ render `requiredStatement` on every resource type. +Clients should interpret behaviors on a Range only when that Range is selected or is in some other way the context for the user's current interaction with the resources. A Range with the `behavior` value `continuous`, in a Manifest with the `behavior` value `paged`, would mean that the Manifest's Containers should be rendered in a paged fashion, unless the range is selected to be viewed, and its included Containers would be rendered in that context only as being virtually stitched together. This might occur, for example, when a physical scroll is cut into pages and bound into a codex with other pages, and the publisher would like to provide the user the experience of the scroll in its original form. -{% include api/code_header.html %} -``` json-doc -{ - "requiredStatement": { - "label": { "en": [ "Attribution" ] }, - "value": { "en": [ "Provided courtesy of Example Institution" ] } - } -} -``` +The descriptions of the behavior values have a set of which other values they are disjoint with, meaning that the same resource _MUST NOT_ have both of two or more from that set. In order to determine which is in effect, the client _SHOULD_ follow the inheritance rules above, taking the value from the closest resource. The user interface effects of the possible permutations of non-disjoint behavior values are client dependent, and implementers are advised to look for relevant recipes in the [IIIF cookbook][annex-cookbook]. -##### rights +The value _MUST_ be an array of strings. -A string that identifies a license or rights statement that applies to the content of the resource, such as the JSON of a Manifest or the pixels of an image. The value _MUST_ be drawn from the set of [Creative Commons][org-cc-licenses] license URIs, the [RightsStatements.org][org-rs-terms] rights statement URIs, or those added via the [extension][prezi40-ldce] mechanism. The inclusion of this property is informative, and for example could be used to display an icon representing the rights assertions. + * Any resource type _MAY_ have the `behavior` property with at least one item.
+ Clients _SHOULD_ process `behavior` on any resource type. -!!! registration not extension -If displaying rights information directly to the user is the desired interaction, or a publisher-defined label is needed, then it is _RECOMMENDED_ to include the information using the `requiredStatement` property or in the `metadata` property. +!!! Could continuous stitch together Timelines? -The value _MUST_ be a string. If the value is drawn from Creative Commons or RightsStatements.org, then the string _MUST_ be a URI defined by that specification. - * Any resource type _MAY_ have the `rights` property.
- Clients _MAY_ render `rights` on any resource type. +| Value | Description | +| ----- | ----------- | +|| **Temporal Behaviors** | +| `auto-advance`{: style="white-space:nowrap;"} | Valid on Collections, Manifests, Containers, and Ranges that include or are Containers with at least the `duration` dimension. When the client reaches the end of a Canvas, or segment thereof as specified in a Range, with a duration dimension that has this behavior, it _SHOULD_ immediately proceed to the next Container or segment and render it. If there is no subsequent Container in the current context, then this behavior should be ignored. When applied to a Collection, the client should treat the first Container of the next Manifest as following the last Container of the previous Manifest, respecting any `start` property specified. Disjoint with `no-auto-advance`. | +| `no-auto-advance`{: style="white-space:nowrap;"} | Valid on Collections, Manifests, Containers, and Ranges that include or are Containers with at least the `duration` dimension. When the client reaches the end of a Container or segment with a duration dimension that has this behavior, it _MUST NOT_ proceed to the next Container, if any. This is a default temporal behavior if not specified. Disjoint with `auto-advance`.| +| `repeat` | Valid on Collections and Manifests, that include Containers that have at least the `duration` dimension. When the client reaches the end of the duration of the final Container in the resource, and the `behavior` value `auto-advance`{: style="white-space:nowrap;"} is also in effect, then the client _SHOULD_ return to the first Container, or segment of a Container, in the resource that has the `behavior` value `repeat` and start playing again. If the `behavior` value `auto-advance` is not in effect, then the client _SHOULD_ render a navigation control for the user to manually return to the first Container or segment. Disjoint with `no-repeat`.| +| `no-repeat` | Valid on Collections and Manifests, that include Containers that have at least the `duration` dimension. When the client reaches the end of the duration of the final Container in the resource, the client _MUST NOT_ return to the first Container, or segment of Container. This is a default temporal behavior if not specified. Disjoint with `repeat`.| +| | **Layout Behaviors** | +| `unordered` | Valid on Collections, Manifests and Ranges. The resources included in resources that have this behavior have no inherent order, and user interfaces _SHOULD_ avoid implying an order to the user. Disjoint with `individuals`, `continuous`, and `paged`.| +| `individuals` | Valid on Collections, Manifests, and Ranges. For Collections that have this behavior, each of the included Manifests are distinct objects in the given order. For Manifests and Ranges, the included Containers are distinct views, and _SHOULD NOT_ be presented in a page-turning interface. This is the default layout behavior if not specified. Disjoint with `unordered`, `continuous`, and `paged`. | +| `continuous` | Valid on Collections, Manifests and Ranges, which include Canvases. Canvases included in resources that have this behavior are partial views and an appropriate rendering might display all of the Canvases virtually stitched together, such as a long scroll split into sections. This behavior has no implication for audio resources. The `viewingDirection` of the Manifest will determine the appropriate arrangement of the Canvases. Disjoint with `unordered`, `individuals` and `paged`. | +| `paged` | Valid on Collections, Manifests and Ranges, which include Canvases. Canvases included in resources that have this behavior represent views that _SHOULD_ be presented in a page-turning interface if one is available. The first canvas is a single view (the first recto) and thus the second canvas likely represents the back of the object in the first canvas. If this is not the case, see the `behavior` value `non-paged`. Disjoint with `unordered`, `individuals`, and `continuous`. | +| `facing-pages`{: style="white-space:nowrap;"} | Valid only on Canvases. Canvases that have this behavior, in a Manifest that has the `behavior` value `paged`, _MUST_ be displayed by themselves, as they depict both parts of the opening. If all of the Canvases are like this, then page turning is not possible, so simply use `individuals` instead. Disjoint with `non-paged`.| +| `non-paged` | Valid only on Canvases. Canvases that have this behavior _MUST NOT_ be presented in a page-turning interface, and _MUST_ be skipped over when determining the page order. This behavior _MUST_ be ignored if the current Manifest does not have the `behavior` value `paged`. Disjoint with `facing-pages`. | +| | **Collection Behaviors** | +| `multi-part` | Valid only on Collections. Collections that have this behavior consist of multiple Manifests or Collections which together form part of a logical whole or a contiguous set, such as multi-volume books or a set of journal issues. Clients might render these Collections as a table of contents rather than with thumbnails, or provide viewing interfaces that can easily advance from one member to the next. Disjoint with `together`.| +| `together` | Valid only on Collections. A client _SHOULD_ present all of the child Manifests to the user at once in a separate viewing area with its own controls. Clients _SHOULD_ catch attempts to create too many viewing areas. This behavior _SHOULD NOT_ be interpreted as applying to the members of any child resources. Disjoint with `multi-part`.| +| | **Range Behaviors** | +| `sequence` | Valid only on Ranges, where the Range is [referenced][prezi30-terminology] in the `structures` property of a Manifest. Ranges that have this behavior represent different orderings of the Containers listed in the `items` property of the Manifest, and user interfaces that interact with this order _SHOULD_ use the order within the selected Range, rather than the default order of `items`. 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` | 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. | +{: .api-table #table-behavior} {% include api/code_header.html %} ``` json-doc -{ "rights": "http://creativecommons.org/licenses/by/4.0/" } +{ "behavior": [ "auto-advance", "individuals" ] } ``` +##### color -__Machine actionable URIs and links for users__
-The machine actionable URIs for both Creative Commons licenses and RightsStatements.org right statements are `http` URIs. In both cases, human readable descriptions are available from equivalent `https` URIs. Clients may wish to rewrite links presented to users to use these equivalent `https` URIs. -{: .note} +This property sets the color of a Light. -##### provider +The value _MUST_ be string, which defines an RGB color. It SHOULD be a hex value starting with "#" and is treated in a case-insensitive fashion. If this property is not specified, then the default value is "#FFFFFF". -An organization or person that contributed to providing the content of the resource. Clients can then display this information to the user to acknowledge the provider's contributions. This differs from the `requiredStatement` property, in that the data is structured, allowing the client to do more than just present text but instead have richer information about the people and organizations to use in different interfaces. + * A Light _SHOULD_ have the `color` property
+ Clients _SHOULD_ render `color` on any resource type. + * Other resources _MUST NOT_ have the `color` property. -The organization or person is represented as an `Agent` resource. +```json +"color": "#FFA0A0" +``` +##### duration -* Agents _MUST_ have the `id` property, and its value _MUST_ be a string. The string _MUST_ be a URI that identifies the agent. -* Agents _MUST_ have the `type` property, and its value _MUST_ be the string `Agent`. -* Agents _MUST_ have the `label` property, and its value _MUST_ be a JSON object as described in the [languages][prezi30-languages] section. -* Agents _SHOULD_ have the `homepage` property, and its value _MUST_ be an array of JSON objects as described in the [homepage][prezi30-homepage] section. -* Agents _SHOULD_ have the `logo` property, and its value _MUST_ be an array of JSON objects as described in the [logo][prezi30-logo] section. -* Agents _MAY_ have the `seeAlso` property, and its value _MUST_ be an array of JSON object as described in the [seeAlso][prezi30-seealso] section. +The duration of a container or external content resource, given in seconds. -The value _MUST_ be an array of JSON objects, where each item in the array conforms to the structure of an Agent, as described above. +The value _MUST_ be a positive floating point number. - * A Collection _SHOULD_ have the `provider` property with at least one item.
- Clients _MUST_ render `provider` on a Collection. - * A Manifest _SHOULD_ have the `provider` property with at least one item.
- Clients _MUST_ render `provider` on a Manifest. - * Other types of resource _MAY_ have the `provider` property with at least one item.
- Clients _SHOULD_ render `provider` on other types of resource. + * A Timeline _MUST_ have the `duration` property.
+ Clients _MUST_ process `duration` on a Timeline. + * A Canvas or Scene _MAY_ have the `duration` property.
+ Clients _MUST_ process `duration` on a Canvas or Scene, if present. + * Content resources _SHOULD_ have the `duration` property, if appropriate to the resource type.
+ Clients _SHOULD_ process `duration` on content resources. + * Other types of resource _MUST NOT_ have a `duration`.
+ Clients _SHOULD_ ignore `duration` on other types of resource. {% include api/code_header.html %} ``` json-doc -{ - "provider": [ - { - "id": "https://example.org/about", - "type": "Agent", - "label": { "en": [ "Example Organization" ] }, - "homepage": [ - { - "id": "https://example.org/", - "type": "Text", - "label": { "en": [ "Example Organization Homepage" ] }, - "format": "text/html" - } - ], - "logo": [ - { - "id": "https://example.org/images/logo.png", - "type": "Image", - "format": "image/png", - "height": 100, - "width": 120 - } - ], - "seeAlso": [ - { - "id": "https://data.example.org/about/us.jsonld", - "type": "Dataset", - "format": "application/ld+json", - "profile": "https://schema.org/" - } - ] - } - ] -} +{ "duration": 125.0 } ``` +##### exclude -##### thumbnail - -A content resource, such as a small image or short audio clip, that represents the resource that has the `thumbnail` property. A resource _MAY_ have multiple thumbnail resources that have the same or different `type` and `format`. +_Summary here_ -The value _MUST_ be an array of JSON objects, each of which _MUST_ have the `id` and `type` properties, and _SHOULD_ have the `format` property. Images and videos _SHOULD_ have the `width` and `height` properties, and time-based media _SHOULD_ have the `duration` property. It is _RECOMMENDED_ that a [IIIF Image API][image-api] service be available for images to enable manipulations such as resizing. +_On Annotation, a list of strings drawn from table_ - * A Collection _SHOULD_ have the `thumbnail` property with at least one item.
- Clients _SHOULD_ render `thumbnail` on a Collection. - * A Manifest _SHOULD_ have the `thumbnail` property with at least one item.
- Clients _SHOULD_ render `thumbnail` on a Manifest. - * All Container types _SHOULD_ have the `thumbnail` property with at least one item.
- Clients _SHOULD_ render `thumbnail` on Containers. - * Content Resource types _MAY_ have the `thumbnail` property with at least one item. Content Resources _SHOULD_ have the `thumbnail` property with at least one item if it is an option in a Choice of resources.
- Clients _SHOULD_ render `thumbnail` on a content resource. - * Other types of resource _MAY_ have the `thumbnail` property with at least one item.
- Clients _MAY_ render `thumbnail` on other types of resource. +| Value | Description | +|------------|-------------| +| Audio | | +| Animations | | +| Cameras | | +| Lights | | -{% include api/code_header.html %} -``` json-doc -{ - "thumbnail": [ - { - "id": "https://example.org/img/thumb.jpg", - "type": "Image", - "format": "image/jpeg", - "width": 300, - "height": 200 - } - ] -} +```json +"exclude": [ "Audio", "Lights", "Cameras", "Animations" ] ``` +##### far -##### navDate - -A date that clients may use for navigation purposes when presenting the resource to the user in a date-based user interface, such as a calendar or timeline. More descriptive date ranges, intended for display directly to the user, _SHOULD_ be included in the `metadata` property for human consumption. If the resource contains Canvases that have the `duration` property, the datetime given corresponds to the navigation datetime of the start of the resource. For example, a Range that includes a Canvas that represents a set of video content recording a historical event, the `navDate` is the datetime of the first moment of the recorded event. +This property gives the distance from the camera after which objects are no longer visible. Objects further from the camera than the `far` distance cannot be seen. -The value _MUST_ be an [XSD dateTime literal][org-w3c-xsd-datetime]. The value _MUST_ have a timezone, and _SHOULD_ be given in UTC with the `Z` timezone indicator, but _MAY_ instead be given as an offset of the form `+hh:mm`. +The value is a non-negative floating point number, in the coordinate space of the Scene in which the Camera is positioned. The value _MUST_ be greater than the value for `near` of the same Camera. If this property is not specified, then the default value is client-dependent. - * A Collection _MAY_ have the `navDate` property.
- Clients _MAY_ render `navDate` on a Collection. - * A Manifest _MAY_ have the `navDate` property.
- Clients _MAY_ render `navDate` on a Manifest. - * A Range _MAY_ have the `navDate` property.
- Clients _MAY_ render `navDate` on a Range. - * All Container types _MAY_ have the `navDate` property.
- Clients _MAY_ render `navDate` on Containers. -* Annotations _MAY_ have the `navDate` property. - Clients _MAY_ render `navDate` on Annotations. - * Other types of resource _MUST NOT_ have the `navDate` property.
- Clients _SHOULD_ ignore `navDate` on other types of resource. +* A Camera _MAY_ have the `far` property
+ Clients _SHOULD_ process the `far` property on Cameras. -{% include api/code_header.html %} -``` json-doc -{ "navDate": "2010-01-01T00:00:00Z" } +```json-doc +{ "far": 200.0 } ``` +##### fieldOfView -##### navPlace - -A geographic location that clients may use for navigation purposes when presenting the resource to the user in a map-based user interface. The location is identified using structured data, described below, with latitude and longitude based points or polygons. If the location is only textual, then the information should instead be included in the `metadata` property. +The angle which a PerspectiveCamera can "see". -The value of the property _MUST_ be a [GeoJSON Feature Collection] [link] containing one or more [Features] [link]. The value _SHOULD_ be embedded and _MAY_ be a reference. Feature Collections referenced in the `navPlace` property _MUST_ have the `id` and `type` properties and _MUST NOT_ have the `features` property. +!!! warning "Need more info" -* A Collection _MAY_ have the `navPlace` property.
- Clients _MAY_ render `navPlace` on a Collection. -* A Manifest _MAY_ have the `navPlace` property.
- Clients _MAY_ render `navPlace` on a Manifest. -* A Range _MAY_ have the `navPlace` property.
- Clients _MAY_ render `navPlace` on a Range. -* All Container types _MAY_ have the `navPlace` property.
- Clients _MAY_ render `navPlace` on Containers. -* Annotations _MAY_ have the `navPlace` property. - Clients _MAY_ render `navPlace` on Annotations. -* Other types of resource _MUST NOT_ have the `navPlace` property.
- Clients _SHOULD_ ignore `navPlace` on other types of resource. +The value _MUST_ be a floating point number greater than 0 and less than 180, and is measured in degrees. If this property is not specified, then the default value is client-dependent. +* A PerspectiveCamera _SHOULD_ have the `fieldOfView` property.
+ Clients _SHOULD_ process the `fieldOfView` property on Cameras. -{% include api/code_header.html %} ```json-doc -{ - "navPlace":{ - "id": "https://example.com/feature-collection/1", - "type": "FeatureCollection", - "features":[ - { - "id": "https://example.com/feature/1", - "type": "Feature", - "geometry":{ - "id": "https://example.com/geometry/1", - "type": "Point", - "coordinates":[ - 9.938, - 51.533 - ] - } - } - ] - } -} +{ "fieldOfView": 50.0 } ``` +##### format +The specific media type (often called a MIME type) for a content resource, for example `image/jpeg`. This is important for distinguishing different formats of the same overall type of resource, such as distinguishing text in XML from plain text. -##### placeholderContainer +Note that this is different to the `formats` property in the [Image API][image-api], which gives the extension to use within that API. It would be inappropriate to use in this case, as `format` can be used with any content resource, not just images. -A single Container that provides additional content for use before the main content of the resource that has the `placeholderContainer` property is rendered, or as an advertisement or stand-in for that content. Examples include images, text and sound standing in for video content before the user initiates playback; or a film poster to attract user attention. The content provided by `placeholderContainer` differs from a thumbnail: a client might use `thumbnail` to summarize and navigate multiple resources, then show content from `placeholderContainer` as part of the initial presentation of a single resource. A placeholder Container is likely to have different dimensions to those of the Container(s) of the resource that has the `placeholderContainer` property. A placeholder Container may be of a different type from the resource that has the `placeholderContainer` property. For example, a `Scene` may have a placeholder Container of type `Canvas`. +The value _MUST_ be a string, and it _SHOULD_ be the value of the `Content-Type` header returned when the resource is dereferenced. -Clients _MAY_ display the content of a linked placeholder Container when presenting the resource. When more than one such Container is available, for example if `placeholderContainer` is provided for the currently selected Range and the current Manifest, the client _SHOULD_ pick the one most specific to the content. Publishers _SHOULD NOT_ assume that the placeholder Container will be processed by all clients. Clients _SHOULD_ take care to avoid conflicts between time-based media in the rendered placeholder Container and the content of the resource that has the `placeholderContainer` property. + * A content resource _SHOULD_ have the `format` property.
+ Clients _MAY_ render the `format` of any content resource. + * Other types of resource _MUST NOT_ have the `format` property.
+ Clients _SHOULD_ ignore `format` on other types of resource. -The value of `placeholderContainer` _MUST_ be a JSON object with the `id` and `type` properties. The value of `type` _MUST_ be a Container type. The JSON object _MAY_ have other properties valid for that Container type. +{% include api/code_header.html %} +``` json-doc +{ "format": "application/xml" } +``` +##### height - * A Collection _MAY_ have the `placeholderContainer` property.
- Clients _MAY_ render `placeholderContainer` on a Collection. - * A Manifest _MAY_ have the `placeholderContainer` property.
- Clients _MAY_ render `placeholderContainer` on a Manifest. - * All Container types _MAY_ have the `placeholderContainer` property.
- Clients _MAY_ render `placeholderContainer` on Containers. - * A Range _MAY_ have the `placeholderContainer` property.
- Clients _MAY_ render `placeholderContainer` on a Range. - * Other types of resource _MUST NOT_ have the `placeholderContainer` property.
- Clients _SHOULD_ ignore `placeholderContainer` on other types of resource. +The height of the Canvas or external content resource. For content resources, the value is in pixels. For Canvases, the value does not have a unit. In combination with the width, it conveys an aspect ratio for the space in which content resources are located. + +The value _MUST_ be a positive integer. + + * A Canvas _MUST_ have the `height` property.
+ Clients _MUST_ process `height` on a Canvas. + * Content resources _SHOULD_ have the `height` property, with the value given in pixels, if appropriate to the resource type.
+ Clients _SHOULD_ process `height` on content resources. + * Other types of resource _MUST NOT_ have the `height` property.
+ Clients _SHOULD_ ignore `height` on other types of resource. {% include api/code_header.html %} ``` json-doc -{ - "placeholderContainer": { - "id": "https://example.org/iiif/1/canvas/placeholder", - "type": "Canvas", - "height": 1400, - "width": 1200 - } -} +{ "height": 1800 } ``` +##### homepage -##### accompanyingContainer - -A single Container that provides additional content for use while rendering the resource that has the `accompanyingContainer` property. Examples include an image to show while a duration-only Canvas is playing audio; or background audio to play while a user is navigating an image-only Manifest. +A web page that is about the object represented by the resource that has the `homepage` property. The web page is usually published by the organization responsible for the object, and might be generated by a content management system or other cataloging system. The resource _MUST_ be able to be displayed directly to the user. Resources that are related, but not home pages, _MUST_ instead be added into the `metadata` property, with an appropriate `label` or `value` to describe the relationship. -Clients _MAY_ display the content of an accompanying Container when presenting the resource. As with `placeholderContainer` above, when more than one accompanying Container is available, the client _SHOULD_ pick the one most specific to the content. Publishers _SHOULD NOT_ assume that the accompanying Container will be processed by all clients. Clients _SHOULD_ take care to avoid conflicts between time-based media in the accompanying Container and the content of the resource that has the `accompanyingContainer` property. +The value of this property _MUST_ be an array of JSON objects, each of which _MUST_ have the `id`, `type`, and `label` properties, _SHOULD_ have a `format` property, and _MAY_ have the `language` property. -The value of `accompanyingContainer` _MUST_ be a JSON object with the `id` and `type` properties. The value of `type` _MUST_ be a Container type. The JSON object _MAY_ have other properties valid for that Container type. + * Any resource type _MAY_ have the `homepage` property.
+ Clients _SHOULD_ render `homepage` on a Collection, Manifest or Canvas, and _MAY_ render `homepage` on other types of resource. - * A Collection _MAY_ have the `accompanyingContainer` property.
- Clients _MAY_ render `accompanyingContainer` on a Collection. - * A Manifest _MAY_ have the `accompanyingContainer` property.
- Clients _MAY_ render `accompanyingContainer` on a Manifest. - * All Container types _MAY_ have the `accompanyingContainer` property.
- Clients _MAY_ render `accompanyingContainer` on Containers. - * A Range _MAY_ have the `accompanyingContainer` property.
- Clients _MAY_ render `accompanyingContainer` on a Range. - * Other types of resource _MUST NOT_ have the `accompanyingContainer` property.
- Clients _SHOULD_ ignore `accompanyingContainer` on other types of resource. +__Model Alignment__
+Please note that this specification has stricter requirements about the JSON pattern used for the `homepage` property than the [Web Annotation Data Model][org-w3c-webanno]. The IIIF requirements are compatible, but the home page of an Agent found might have only a URI, or might be a JSON object with other properties. See the section on [collisions between contexts][prezi30-context-collisions] for more information. +{: .note} {% include api/code_header.html %} ``` json-doc { - "accompanyingContainer": { - "id": "https://example.org/iiif/1/timeline/accompany", - "type": "Timeline", - "duration": 180.0 - } + "homepage": [ + { + "id": "https://example.com/info/", + "type": "Text", + "label": { "en": [ "Homepage for Example Object" ] }, + "format": "text/html", + "language": [ "en" ] + } + ] } ``` - - - -### Technical Properties - ##### id The URI that identifies the resource. If the resource is only available embedded within another resource (see the [terminology section][prezi30-terminology] for an explanation of "embedded"), such as a Range within a Manifest, then the URI _MAY_ be the URI of the embedding resource with a unique fragment on the end. This is not true for Canvases, which _MUST_ have their own URI without a fragment. @@ -734,320 +663,310 @@ The existence of an HTTP(S) URI in the `id` property does not mean that the URI ``` json-doc { "id": "https://example.org/iiif/1/manifest" } ``` +##### intensity -##### type - -The type or class of the resource. For classes defined for this specification, the value of `type` will be described in the sections below describing each individual class. - -For content resources, the value of `type` is drawn from other specifications. Recommendations for common content types such as image, text or audio are given in the table below. - -The JSON objects that appear in the value of the `service` property will have many different classes, and can be used to distinguish the sort of service, with specific properties defined in a [registered context document][prezi30-ldce]. +This property sets the strength or brightness of a Light. -The value _MUST_ be a string. +The value _MUST_ be a JSON object, that has the `type`, `value` and `unit` properties. All three properties are required. The value of `type` _MUST_ be the string "UnitValue". The value of `value` is a floating point number. The value of `unit` is a string, drawn from a controlled vocabulary of units. If this property is not specified, then the default intensity value is client-dependent. - * All resource types _MUST_ have the `type` property.
- Clients _MUST_ process, and _MAY_ render, `type` on any resource type. +This specification defines the unit value of "relative" which constrains the value to be a linear scale between 0.0 (no brightness) and 1.0 (as bright as the client will render). -| Class | Description | -| ------------- | -------------------------------- | -| `Dataset` | Data not intended to be rendered to humans directly, such as a CSV, an RDF serialization or a zip file | -| `Image` | Two dimensional visual resources primarily intended to be seen, such as might be rendered with an <img> HTML tag | -| `Model` | A three dimensional spatial model intended to be visualized, such as might be rendered with a 3d javascript library | -| `Sound` | Auditory resources primarily intended to be heard, such as might be rendered with an <audio> HTML tag | -| `Text` | Resources primarily intended to be read | -| `Video` | Moving images, with or without accompanying audio, such as might be rendered with a <video> HTML tag | -{: .api-table #table-type} +* A Light _SHOULD_ have the `intensity` property.
+ Clients _SHOULD_ process the `intensity` property on Lights. -{% include api/code_header.html %} -``` json-doc -{ "type": "Image" } +```json +{ + "intensity": {"id": "", "type": "UnitValue", "value": 0.5, "unit": "relative"} +} ``` +##### interactionMode -##### format +*within* the Scene, whereas viewingDirection and behavior are across containers. -The specific media type (often called a MIME type) for a content resource, for example `image/jpeg`. This is important for distinguishing different formats of the same overall type of resource, such as distinguishing text in XML from plain text. +* Containers _MAY_ have the `interactionMode` -Note that this is different to the `formats` property in the [Image API][image-api], which gives the extension to use within that API. It would be inappropriate to use in this case, as `format` can be used with any content resource, not just images. +Table here with values -The value _MUST_ be a string, and it _SHOULD_ be the value of the `Content-Type` header returned when the resource is dereferenced. - * A content resource _SHOULD_ have the `format` property.
- Clients _MAY_ render the `format` of any content resource. - * Other types of resource _MUST NOT_ have the `format` property.
- Clients _SHOULD_ ignore `format` on other types of resource. +locked +orbit +hemisphere-orbit +free +free-direction -{% include api/code_header.html %} -``` json-doc -{ "format": "application/xml" } -``` +other examples: no-zoom, no-scrub, rti-mode +##### items -##### language +Much of the functionality of the IIIF Presentation API is simply recording the order in which child resources occur within a parent resource, such as Collections or Manifests within a parent Collection, or Canvases within a Manifest. All of these situations are covered with a single property, `items`. -The language or languages used in the content of this external resource. This property is already available from the Web Annotation model for content resources that are the body or target of an Annotation, however it _MAY_ also be used for resources [referenced][prezi30-terminology] from `homepage`, `rendering`, and `partOf`. +The value _MUST_ be an array of JSON objects. Each item _MUST_ have the `id` and `type` properties. The items will be resources of different types, as described below. -The value _MUST_ be an array of strings. Each item in the array _MUST_ be a valid language code, as described in the [languages section][prezi30-languages]. - - * An external resource _SHOULD_ have the `language` property with at least one item.
- Clients _SHOULD_ process the `language` of external resources. - * Other types of resource _MUST NOT_ have the `language` property.
- Clients _SHOULD_ ignore `language` on other types of resource. + * A Collection _MUST_ have the `items` property. Each item _MUST_ be either a Collection or a Manifest.
+ Clients _MUST_ process `items` on a Collection. + * A Manifest _MUST_ have the `items` property with at least one item. Each item _MUST_ be a Canvas.
+ Clients _MUST_ process `items` on a Manifest. + * A Canvas _SHOULD_ have the `items` property with at least one item. Each item _MUST_ be an Annotation Page.
+ Clients _MUST_ process `items` on a Canvas. + * An Annotation Page _SHOULD_ have the `items` property with at least one item. Each item _MUST_ be an Annotation.
+ Clients _MUST_ process `items` on an Annotation Page. + * A Range _MUST_ have the `items` property with at least one item. Each item _MUST_ be a Range, a Canvas or a Specific Resource where the source is a Canvas.
+ Clients _SHOULD_ process `items` on a Range. + * Other types of resource _MUST NOT_ have the `items` property.
+ Clients _SHOULD_ ignore `items` on other types of resource. {% include api/code_header.html %} ``` json-doc -{ "language": [ "en" ] } +{ + "items": [ + { + "id": "https://example.org/iiif/manifest1", + "type": "Manifest" + }, + { + "id": "https://example.org/iiif/collection1", + "type": "Collection" + } + // ... + ] +} ``` +##### label -##### profile - -A schema or named set of functionality available from the resource. The profile can further clarify the `type` and/or `format` of an external resource or service, allowing clients to customize their handling of the resource that has the `profile` property. +A human readable label, name or title. The `label` property is intended to be displayed as a short, textual surrogate for the resource if a human needs to make a distinction between it and similar resources, for example between objects, pages, or options for a choice of images to display. The `label` property can be fully internationalized, and each language can have multiple values. This pattern is described in more detail in the [languages][prezi40-languages] section. -The value _MUST_ be a string, either taken from the [profiles registry][registry-profiles] or a URI. +The value of the property _MUST_ be a JSON object, as described in the [languages][prezi40-languages] section. -* Resources [referenced][prezi30-terminology] by the `seeAlso` or `service` properties _SHOULD_ have the `profile` property.
- Clients _SHOULD_ process the `profile` of a service or external resource. -* Other types of resource _MAY_ have the `profile` property.
- Clients _MAY_ process the `profile` of other types of resource. + * A Collection _MUST_ have the `label` property with at least one entry.
+ Clients _MUST_ render `label` on a Collection. + * A Manifest _MUST_ have the `label` property with at least one entry.
+ Clients _MUST_ render `label` on a Manifest. + * All Container types _SHOULD_ have the `label` property with at least one entry.
+ Clients _MUST_ render `label` on Container types, and _SHOULD_ generate a `label` for Containers that do not have them. + * All Content Resource types _MAY_ have the `label` property with at least one entry. If there is a Choice of Content Resource for the same Container, then they _SHOULD_ each have the `label` property with at least one entry.
+ Clients _MAY_ render `label` on Content Resources, and _SHOULD_ render them when part of a Choice. + * A Range _SHOULD_ have the `label` property with at least one entry.
+ Clients _MUST_ render `label` on a Range. + * An Annotation Collection _SHOULD_ have the `label` property with at least one entry.
+ Clients _SHOULD_ render `label` on an Annotation Collection. + * Other types of resource _MAY_ have the `label` property with at least one entry.
+ Clients _MAY_ render `label` on other types of resource. {% include api/code_header.html %} ``` json-doc -{ "profile": "https://example.org/profile/statuary" } +{ "label": { "en": [ "Example Object Title" ] } } ``` +##### language -##### height - -The height of the Canvas or external content resource. For content resources, the value is in pixels. For Canvases, the value does not have a unit. In combination with the width, it conveys an aspect ratio for the space in which content resources are located. +The language or languages used in the content of this external resource. This property is already available from the Web Annotation model for content resources that are the body or target of an Annotation, however it _MAY_ also be used for resources [referenced][prezi30-terminology] from `homepage`, `rendering`, and `partOf`. -The value _MUST_ be a positive integer. +The value _MUST_ be an array of strings. Each item in the array _MUST_ be a valid language code, as described in the [languages section][prezi30-languages]. - * A Canvas _MUST_ have the `height` property.
- Clients _MUST_ process `height` on a Canvas. - * Content resources _SHOULD_ have the `height` property, with the value given in pixels, if appropriate to the resource type.
- Clients _SHOULD_ process `height` on content resources. - * Other types of resource _MUST NOT_ have the `height` property.
- Clients _SHOULD_ ignore `height` on other types of resource. + * An external resource _SHOULD_ have the `language` property with at least one item.
+ Clients _SHOULD_ process the `language` of external resources. + * Other types of resource _MUST NOT_ have the `language` property.
+ Clients _SHOULD_ ignore `language` on other types of resource. {% include api/code_header.html %} ``` json-doc -{ "height": 1800 } +{ "language": [ "en" ] } ``` +##### logo -##### width +A small image resource that represents the Agent resource it is associated with. The logo _MUST_ be clearly rendered when the resource is displayed or used, without cropping, rotating or otherwise distorting the image. It is _RECOMMENDED_ that a [IIIF Image API][image-api] service be available for this image for other manipulations such as resizing. -The width of the Canvas or external content resource. For content resources, the value is in pixels. For Canvases, the value does not have a unit. In combination with the height, it conveys an aspect ratio for the space in which content resources are located. +When more than one logo is present, the client _SHOULD_ pick only one of them, based on the information in the logo properties. For example, the client could select a logo of appropriate aspect ratio based on the `height` and `width` properties of the available logos. The client _MAY_ decide on the logo by inspecting properties defined as [extensions][prezi30-ldce]. -The value _MUST_ be a positive integer. +The value of this property _MUST_ be an array of JSON objects, each of which _MUST_ have `id` and `type` properties, and _SHOULD_ have `format`. The value of `type` _MUST_ be `Image`. + + * Agent resources _SHOULD_ have the `logo` property.
+ Clients _MUST_ render `logo` on Agent resources. - * A Canvas _MUST_ have the `width` property.
- Clients _MUST_ process `width` on a Canvas. - * Content resources _SHOULD_ have the `width` property, with the value given in pixels, if appropriate to the resource type.
- Clients _SHOULD_ process `width` on content resources. - * Other types of resource _MUST NOT_ have the `width` property.
- Clients _SHOULD_ ignore `width` on other types of resource. {% include api/code_header.html %} ``` json-doc -{ "width": 1200 } +{ + "logo": [ + { + "id": "https://example.org/img/logo.jpg", + "type": "Image", + "format": "image/jpeg", + "height": 100, + "width": 120 + } + ] +} ``` +##### lookAt -##### duration - -The duration of a container or external content resource, given in seconds. +_Summary here_ -The value _MUST_ be a positive floating point number. +The value _MUST_ be a JSON object, conforming to either a reference to an Annotation, or an embedded PointSelector. If this property is not specified, then the default value for cameras is to look straight backwards (-Z) and for lights to point straight down (-Y). - * A Timeline _MUST_ have the `duration` property.
- Clients _MUST_ process `duration` on a Timeline. - * A Canvas or Scene _MAY_ have the `duration` property.
- Clients _MUST_ process `duration` on a Canvas or Scene, if present. - * Content resources _SHOULD_ have the `duration` property, if appropriate to the resource type.
- Clients _SHOULD_ process `duration` on content resources. - * Other types of resource _MUST NOT_ have a `duration`.
- Clients _SHOULD_ ignore `duration` on other types of resource. +* A Camera _MAY_ have the `lookAt` property.
+ Clients _SHOULD_ process the `lookAt` property on Cameras. +* A SpotLight or a DirectionalLight _SHOULD_ have the `lookAt` property.
-{% include api/code_header.html %} -``` json-doc -{ "duration": 125.0 } +```json +"lookAt": { + "type": "PointSelector", + "x": 3, + "y": 0, + "z": -10 +} ``` +##### metadata -##### viewingDirection - -!!! Rewrite to be where is the navigation control to step to the next/ previous in the items of hte manifest - - -The direction in which a list of Containers _SHOULD_ be displayed to the user. This specification defines four direction values in the table below. Others may be defined externally [as an extension][prezi30-ldce]. For example, -if the `viewingDirection` value is `left-to-right`, then backwards in the list is to the left, and forwards in the -list is to the right. +An ordered list of descriptions to be displayed to the user when they interact with the resource, given as pairs of human readable `label` and `value` entries. The content of these entries is intended for presentation only; descriptive semantics _SHOULD NOT_ be inferred. An entry might be used to convey information about the creation of the object, a physical description, ownership information, or other purposes. -The value _MUST_ be a string. +The value of the `metadata` property _MUST_ be an array of JSON objects, where each item in the array has both `label` and `value` properties. The values of both `label` and `value` _MUST_ be JSON objects, as described in the [languages][prezi40-languages] section. - * A Collection _MAY_ have the `viewingDirection` property.
- Clients _SHOULD_ process `viewingDirection` on a Collection. - * A Manifest _MAY_ have the `viewingDirection` property.
- Clients _SHOULD_ process `viewingDirection` on a Manifest. - * A Range _MAY_ have the `viewingDirection` property.
- Clients _MAY_ process `viewingDirection` on a Range. - * Other types of resource _MUST NOT_ have the `viewingDirection` property.
- Clients _SHOULD_ ignore `viewingDirection` on other types of resource. + * A Collection _SHOULD_ have the `metadata` property with at least one item.
+ Clients _MUST_ render `metadata` on a Collection. + * A Manifest _SHOULD_ have the `metadata` property with at least one item.
+ Clients _MUST_ render `metadata` on a Manifest. + * All Container types _MAY_ have the `metadata` property with at least one item.
+ Clients _SHOULD_ render `metadata` on Containers. + * Other types of resource _MAY_ have the `metadata` property with at least one item.
+ Clients _MAY_ render `metadata` on other types of resource. -| Value | Description | -| ----- | ----------- | -| `left-to-right` | The object is displayed from left to right. The default if not specified. | -| `right-to-left` | The object is displayed from right to left. | -| `top-to-bottom` | The object is displayed from the top to the bottom. | -| `bottom-to-top` | The object is displayed from the bottom to the top. | -{: .api-table #table-direction} +Clients _SHOULD_ display the entries in the order provided. Clients _SHOULD_ expect to encounter long texts in the `value` property, and render them appropriately, such as with an expand button, or in a tabbed interface. {% include api/code_header.html %} ``` json-doc -{ "viewingDirection": "left-to-right" } +{ + "metadata": [ + { + "label": { "en": [ "Creator" ] }, + "value": { "en": [ "Anne Artist (1776-1824)" ] } + } + ] +} ``` +##### navDate -##### behavior - -A set of user experience features that the publisher of the content would prefer the client to use when presenting the resource. This specification defines the values in the table below. Others may be defined externally as an [extension][prezi30-ldce]. - -In order to determine the behaviors that are governing a particular resource, there are four inheritance rules from resources that reference the current resource: -* Collections inherit behaviors from their referencing Collection. -* Manifests **DO NOT** inherit behaviors from any referencing Collections. -* Containers inherit behaviors from their referencing Manifest, but **DO NOT** inherit behaviors from any referencing Ranges, as there might be several with different behaviors. -* Ranges inherit behaviors from any referencing Range and referencing Manifest. - -Clients should interpret behaviors on a Range only when that Range is selected or is in some other way the context for the user's current interaction with the resources. A Range with the `behavior` value `continuous`, in a Manifest with the `behavior` value `paged`, would mean that the Manifest's Containers should be rendered in a paged fashion, unless the range is selected to be viewed, and its included Containers would be rendered in that context only as being virtually stitched together. This might occur, for example, when a physical scroll is cut into pages and bound into a codex with other pages, and the publisher would like to provide the user the experience of the scroll in its original form. - -The descriptions of the behavior values have a set of which other values they are disjoint with, meaning that the same resource _MUST NOT_ have both of two or more from that set. In order to determine which is in effect, the client _SHOULD_ follow the inheritance rules above, taking the value from the closest resource. The user interface effects of the possible permutations of non-disjoint behavior values are client dependent, and implementers are advised to look for relevant recipes in the [IIIF cookbook][annex-cookbook]. - -The value _MUST_ be an array of strings. - - * Any resource type _MAY_ have the `behavior` property with at least one item.
- Clients _SHOULD_ process `behavior` on any resource type. - - -!!! Could continuous stitch together Timelines? +A date that clients may use for navigation purposes when presenting the resource to the user in a date-based user interface, such as a calendar or timeline. More descriptive date ranges, intended for display directly to the user, _SHOULD_ be included in the `metadata` property for human consumption. If the resource contains Canvases that have the `duration` property, the datetime given corresponds to the navigation datetime of the start of the resource. For example, a Range that includes a Canvas that represents a set of video content recording a historical event, the `navDate` is the datetime of the first moment of the recorded event. +The value _MUST_ be an [XSD dateTime literal][org-w3c-xsd-datetime]. The value _MUST_ have a timezone, and _SHOULD_ be given in UTC with the `Z` timezone indicator, but _MAY_ instead be given as an offset of the form `+hh:mm`. -| Value | Description | -| ----- | ----------- | -|| **Temporal Behaviors** | -| `auto-advance`{: style="white-space:nowrap;"} | Valid on Collections, Manifests, Containers, and Ranges that include or are Containers with at least the `duration` dimension. When the client reaches the end of a Canvas, or segment thereof as specified in a Range, with a duration dimension that has this behavior, it _SHOULD_ immediately proceed to the next Container or segment and render it. If there is no subsequent Container in the current context, then this behavior should be ignored. When applied to a Collection, the client should treat the first Container of the next Manifest as following the last Container of the previous Manifest, respecting any `start` property specified. Disjoint with `no-auto-advance`. | -| `no-auto-advance`{: style="white-space:nowrap;"} | Valid on Collections, Manifests, Containers, and Ranges that include or are Containers with at least the `duration` dimension. When the client reaches the end of a Container or segment with a duration dimension that has this behavior, it _MUST NOT_ proceed to the next Container, if any. This is a default temporal behavior if not specified. Disjoint with `auto-advance`.| -| `repeat` | Valid on Collections and Manifests, that include Containers that have at least the `duration` dimension. When the client reaches the end of the duration of the final Container in the resource, and the `behavior` value `auto-advance`{: style="white-space:nowrap;"} is also in effect, then the client _SHOULD_ return to the first Container, or segment of a Container, in the resource that has the `behavior` value `repeat` and start playing again. If the `behavior` value `auto-advance` is not in effect, then the client _SHOULD_ render a navigation control for the user to manually return to the first Container or segment. Disjoint with `no-repeat`.| -| `no-repeat` | Valid on Collections and Manifests, that include Containers that have at least the `duration` dimension. When the client reaches the end of the duration of the final Container in the resource, the client _MUST NOT_ return to the first Container, or segment of Container. This is a default temporal behavior if not specified. Disjoint with `repeat`.| -| | **Layout Behaviors** | -| `unordered` | Valid on Collections, Manifests and Ranges. The resources included in resources that have this behavior have no inherent order, and user interfaces _SHOULD_ avoid implying an order to the user. Disjoint with `individuals`, `continuous`, and `paged`.| -| `individuals` | Valid on Collections, Manifests, and Ranges. For Collections that have this behavior, each of the included Manifests are distinct objects in the given order. For Manifests and Ranges, the included Containers are distinct views, and _SHOULD NOT_ be presented in a page-turning interface. This is the default layout behavior if not specified. Disjoint with `unordered`, `continuous`, and `paged`. | -| `continuous` | Valid on Collections, Manifests and Ranges, which include Canvases. Canvases included in resources that have this behavior are partial views and an appropriate rendering might display all of the Canvases virtually stitched together, such as a long scroll split into sections. This behavior has no implication for audio resources. The `viewingDirection` of the Manifest will determine the appropriate arrangement of the Canvases. Disjoint with `unordered`, `individuals` and `paged`. | -| `paged` | Valid on Collections, Manifests and Ranges, which include Canvases. Canvases included in resources that have this behavior represent views that _SHOULD_ be presented in a page-turning interface if one is available. The first canvas is a single view (the first recto) and thus the second canvas likely represents the back of the object in the first canvas. If this is not the case, see the `behavior` value `non-paged`. Disjoint with `unordered`, `individuals`, and `continuous`. | -| `facing-pages`{: style="white-space:nowrap;"} | Valid only on Canvases. Canvases that have this behavior, in a Manifest that has the `behavior` value `paged`, _MUST_ be displayed by themselves, as they depict both parts of the opening. If all of the Canvases are like this, then page turning is not possible, so simply use `individuals` instead. Disjoint with `non-paged`.| -| `non-paged` | Valid only on Canvases. Canvases that have this behavior _MUST NOT_ be presented in a page-turning interface, and _MUST_ be skipped over when determining the page order. This behavior _MUST_ be ignored if the current Manifest does not have the `behavior` value `paged`. Disjoint with `facing-pages`. | -| | **Collection Behaviors** | -| `multi-part` | Valid only on Collections. Collections that have this behavior consist of multiple Manifests or Collections which together form part of a logical whole or a contiguous set, such as multi-volume books or a set of journal issues. Clients might render these Collections as a table of contents rather than with thumbnails, or provide viewing interfaces that can easily advance from one member to the next. Disjoint with `together`.| -| `together` | Valid only on Collections. A client _SHOULD_ present all of the child Manifests to the user at once in a separate viewing area with its own controls. Clients _SHOULD_ catch attempts to create too many viewing areas. This behavior _SHOULD NOT_ be interpreted as applying to the members of any child resources. Disjoint with `multi-part`.| -| | **Range Behaviors** | -| `sequence` | Valid only on Ranges, where the Range is [referenced][prezi30-terminology] in the `structures` property of a Manifest. Ranges that have this behavior represent different orderings of the Containers listed in the `items` property of the Manifest, and user interfaces that interact with this order _SHOULD_ use the order within the selected Range, rather than the default order of `items`. 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` | 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. | -{: .api-table #table-behavior} + * A Collection _MAY_ have the `navDate` property.
+ Clients _MAY_ render `navDate` on a Collection. + * A Manifest _MAY_ have the `navDate` property.
+ Clients _MAY_ render `navDate` on a Manifest. + * A Range _MAY_ have the `navDate` property.
+ Clients _MAY_ render `navDate` on a Range. + * All Container types _MAY_ have the `navDate` property.
+ Clients _MAY_ render `navDate` on Containers. +* Annotations _MAY_ have the `navDate` property. + Clients _MAY_ render `navDate` on Annotations. + * Other types of resource _MUST NOT_ have the `navDate` property.
+ Clients _SHOULD_ ignore `navDate` on other types of resource. {% include api/code_header.html %} ``` json-doc -{ "behavior": [ "auto-advance", "individuals" ] } +{ "navDate": "2010-01-01T00:00:00Z" } ``` +##### navPlace -##### interactionMode - -*within* the Scene, whereas viewingDirection and behavior are across containers. - -* Containers _MAY_ have the `interactionMode` +A geographic location that clients may use for navigation purposes when presenting the resource to the user in a map-based user interface. The location is identified using structured data, described below, with latitude and longitude based points or polygons. If the location is only textual, then the information should instead be included in the `metadata` property. -Table here with values +The value of the property _MUST_ be a [GeoJSON Feature Collection] [link] containing one or more [Features] [link]. The value _SHOULD_ be embedded and _MAY_ be a reference. Feature Collections referenced in the `navPlace` property _MUST_ have the `id` and `type` properties and _MUST NOT_ have the `features` property. +* A Collection _MAY_ have the `navPlace` property.
+ Clients _MAY_ render `navPlace` on a Collection. +* A Manifest _MAY_ have the `navPlace` property.
+ Clients _MAY_ render `navPlace` on a Manifest. +* A Range _MAY_ have the `navPlace` property.
+ Clients _MAY_ render `navPlace` on a Range. +* All Container types _MAY_ have the `navPlace` property.
+ Clients _MAY_ render `navPlace` on Containers. +* Annotations _MAY_ have the `navPlace` property. + Clients _MAY_ render `navPlace` on Annotations. +* Other types of resource _MUST NOT_ have the `navPlace` property.
+ Clients _SHOULD_ ignore `navPlace` on other types of resource. -locked -orbit -hemisphere-orbit -free -free-direction -other examples: no-zoom, no-scrub, rti-mode +{% include api/code_header.html %} +```json-doc +{ + "navPlace":{ + "id": "https://example.com/feature-collection/1", + "type": "FeatureCollection", + "features":[ + { + "id": "https://example.com/feature/1", + "type": "Feature", + "geometry":{ + "id": "https://example.com/geometry/1", + "type": "Point", + "coordinates":[ + 9.938, + 51.533 + ] + } + } + ] + } +} +``` +##### near +This property gives the distance from the camera from which objects are visible. Objects closer to the camera than the `near` distance cannot be seen. -##### provides +The value is a non-negative floating point number, in the coordinate space of the Scene in which the Camera is positioned. The value _MUST_ be less than the value for `far` for the same Camera. If this property is not specified, then the default value is client-dependent. -A set of features or additional functionality that a linked resource enables relative to the linking or including resource, which is not defined by the `type`, `format` or `profile` of the linked resource. It provides information as to why and how a client might want to interact with the resource, rather than what the resource is. For example, a text file (linked resource) that `provides` a `closedCaptions` for a Video (context resource), or an audio file (linked resource) that `provides` an `audioDescription` of a Canvas (context resource). +* A Camera _MAY_ have the `near` property
+ Clients _SHOULD_ process the `near` property on Cameras. -The value _MUST_ be an array of strings, each string identifies a particular feature and _MUST_ be taken from the table below or the [provides registry][link]. +```json-doc +{ "near": 1.5 } +``` -Note that the majority of the values have been selected from [accessibility feature spec][link] and thus use the original form rather than being consistent with the hyphen-based form of the values of `behavior` and `viewingDirection`. +##### partOf +A containing resource that includes the resource that has the `partOf` property. When a client encounters the `partOf` property, it might retrieve the [referenced][prezi30-terminology] containing resource, if it is not [embedded][prezi30-terminology] in the current representation, in order to contribute to the processing of the contained resource. For example, the `partOf` property on a Canvas can be used to reference an external Manifest in order to enable the discovery of further relevant information. Similarly, a Manifest can reference a containing Collection using `partOf` to aid in navigation. -* Annotations with the `painting` motivation _SHOULD NOT_ have the `provides` property.
- Clients _SHOULD_ ignore the `provides` property on Annotations with the `painting` motivation. -* Any resource linked to or included in another resource _MAY_ have the `provides` property.
- Clients _SHOULD_ process the `provides` property on these resources. +The value _MUST_ be an array of JSON objects. Each item _MUST_ have the `id` and `type` properties, and _SHOULD_ have the `label` property. -| Value | Description | -| ----- | ----------- | -| `closedCaptions` | ... | -| `alternativeText` | ... | -| `audioDescription` | ... | -| `longDescription` | ... | -| `signLanguage` | ... | -| `highContrastAudio` | ... | -| `highContrastDisplay` | ... | -| `braille` | ... | -| `tactileGraphic` | ... | -| `transcript` | ... | -| `translation` | (IIIF Defined) ... | -| `subtitles` | (IIIF Defined) ... | -{: .api-table #table-behavior} + * Any resource type _MAY_ have the `partOf` property with at least one item
+ Clients _MAY_ render `partOf` on any resource type. {% include api/code_header.html %} ``` json-doc -{ "provides": [ "closedCaption" ] } +{ "partOf": [ { "id": "https://example.org/iiif/1", "type": "Manifest" } ] } ``` -!!! warning "This breaks the graph as the file doesn't provide X in all contexts" - +The resources referred to by the `accompanyingContainer` and `placeholderContainer` properties are `partOf` that referring Container. -##### timeMode +##### placeholderContainer -A mode associated with an Annotation that is to be applied to the rendering of any time-based media, or otherwise could be considered to have a duration, used as a body resource of that Annotation. Note that the association of `timeMode` with the Annotation means that different resources in the body cannot have different values. This specification defines the values specified in the table below. Others may be defined externally as an [extension][prezi30-ldce]. +A single Container that provides additional content for use before the main content of the resource that has the `placeholderContainer` property is rendered, or as an advertisement or stand-in for that content. Examples include images, text and sound standing in for video content before the user initiates playback; or a film poster to attract user attention. The content provided by `placeholderContainer` differs from a thumbnail: a client might use `thumbnail` to summarize and navigate multiple resources, then show content from `placeholderContainer` as part of the initial presentation of a single resource. A placeholder Container is likely to have different dimensions to those of the Container(s) of the resource that has the `placeholderContainer` property. A placeholder Container may be of a different type from the resource that has the `placeholderContainer` property. For example, a `Scene` may have a placeholder Container of type `Canvas`. -The value _MUST_ be a string. +Clients _MAY_ display the content of a linked placeholder Container when presenting the resource. When more than one such Container is available, for example if `placeholderContainer` is provided for the currently selected Range and the current Manifest, the client _SHOULD_ pick the one most specific to the content. Publishers _SHOULD NOT_ assume that the placeholder Container will be processed by all clients. Clients _SHOULD_ take care to avoid conflicts between time-based media in the rendered placeholder Container and the content of the resource that has the `placeholderContainer` property. - * An Annotation _MAY_ have the `timeMode` property.
- Clients _SHOULD_ process `timeMode` on an Annotation. +The value of `placeholderContainer` _MUST_ be a JSON object with the `id` and `type` properties. The value of `type` _MUST_ be a Container type. The JSON object _MAY_ have other properties valid for that Container type. -| Value | Description | -| ----- | ----------- | -| `trim` | (default, if not supplied) If the content resource has a longer duration than the duration of the portion of the Canvas it is associated with, then at the end of the Canvas's duration, the playback of the content resource _MUST_ also end. If the content resource has a shorter duration than the duration of the portion of the Canvas it is associated with, then, for video resources, the last frame _SHOULD_ persist on-screen until the end of the Canvas portion's duration. For example, a video of 120 seconds annotated to a Canvas with a duration of 100 seconds would play only the first 100 seconds and drop the last 20 seconds. | -| `scale` | Fit the duration of content resource to the duration of the portion of the Canvas it is associated with by scaling. For example, a video of 120 seconds annotated to a Canvas with a duration of 60 seconds would be played at double-speed. | -| `loop` | If the content resource is shorter than the `duration` of the Canvas, it _MUST_ be repeated to fill the entire duration. Resources longer than the `duration` _MUST_ be trimmed as described above. For example, if a 20 second duration audio stream is annotated onto a Canvas with a duration of 30 seconds, it will be played one and a half times. | -{: .api-table #table-timemode} + * A Collection _MAY_ have the `placeholderContainer` property.
+ Clients _MAY_ render `placeholderContainer` on a Collection. + * A Manifest _MAY_ have the `placeholderContainer` property.
+ Clients _MAY_ render `placeholderContainer` on a Manifest. + * All Container types _MAY_ have the `placeholderContainer` property.
+ Clients _MAY_ render `placeholderContainer` on Containers. + * A Range _MAY_ have the `placeholderContainer` property.
+ Clients _MAY_ render `placeholderContainer` on a Range. + * Other types of resource _MUST NOT_ have the `placeholderContainer` property.
+ Clients _SHOULD_ ignore `placeholderContainer` on other types of resource. {% include api/code_header.html %} ``` json-doc -{ "timeMode": "trim" } -``` - -#### backgroundColor - -This property sets the background color behind any painted resources on a spatial Container, such as a Canvas or Scene. - -The value _MUST_ be string, which defines an RGB color. It SHOULD be a hex value starting with "#" and is treated in a case-insensitive fashion. If this property is not specified, then the default value is client-dependent. - - * A Canvas _MAY_ have the `backgroundColor` property
- Clients _SHOULD_ render `backgroundColor` on any resource type. - * A Scene _MAY_ have the `backgroundColor` property
- Clients _SHOULD_ render `backgroundColor` on any resource type. - * Other resources _MUST NOT_ have the `backgroundColor` property. - -```json-doc -{ "backgroundColor": "#FFFFFF" } +{ + "placeholderContainer": { + "id": "https://example.org/iiif/1/canvas/placeholder", + "type": "Canvas", + "height": 1400, + "width": 1200 + } +} ``` - ##### position It is important to be able to position the (textual) body of an annotation within the Container's space that the annotation also targets. For example, a description of part of an image in a Canvas should be positioned such that it does not obscure the image region itself and labels to be displayed as part of a Scene should not be rendered such that the text is hidden by the three dimensional geometry of the model. If this property is not supplied, then the client should do its best to ensure the content is visible to the user. @@ -1076,228 +995,203 @@ The value of this property _MUST_ be a JSON object conforming to the `SpecificRe } ``` +##### profile +A schema or named set of functionality available from the resource. The profile can further clarify the `type` and/or `format` of an external resource or service, allowing clients to customize their handling of the resource that has the `profile` property. -##### near - -This property gives the distance from the camera from which objects are visible. Objects closer to the camera than the `near` distance cannot be seen. - -The value is a non-negative floating point number, in the coordinate space of the Scene in which the Camera is positioned. The value _MUST_ be less than the value for `far` for the same Camera. If this property is not specified, then the default value is client-dependent. - -* A Camera _MAY_ have the `near` property
- Clients _SHOULD_ process the `near` property on Cameras. - -```json-doc -{ "near": 1.5 } -``` - -##### far - -This property gives the distance from the camera after which objects are no longer visible. Objects further from the camera than the `far` distance cannot be seen. - -The value is a non-negative floating point number, in the coordinate space of the Scene in which the Camera is positioned. The value _MUST_ be greater than the value for `near` of the same Camera. If this property is not specified, then the default value is client-dependent. - -* A Camera _MAY_ have the `far` property
- Clients _SHOULD_ process the `far` property on Cameras. - -```json-doc -{ "far": 200.0 } -``` - -##### fieldOfView - -The angle which a PerspectiveCamera can "see". - -!!! warning "Need more info" - -The value _MUST_ be a floating point number greater than 0 and less than 180, and is measured in degrees. If this property is not specified, then the default value is client-dependent. - -* A PerspectiveCamera _SHOULD_ have the `fieldOfView` property.
- Clients _SHOULD_ process the `fieldOfView` property on Cameras. - -```json-doc -{ "fieldOfView": 50.0 } -``` - -##### angle - -!!! warning "Need more info" - -The value _MUST_ be a floating point number greater than 0 and less than 90, and is measure in degrees. If this property is not specified, then the default value is client-dependent. - -* A SpotLight _SHOULD_ have the `angle` property.
- Clients _SHOULD_ process the `angle` property on SpotLights. - -```json - "angle": 15.0 -``` - -##### lookAt - -_Summary here_ - -The value _MUST_ be a JSON object, conforming to either a reference to an Annotation, or an embedded PointSelector. If this property is not specified, then the default value for cameras is to look straight backwards (-Z) and for lights to point straight down (-Y). - -* A Camera _MAY_ have the `lookAt` property.
- Clients _SHOULD_ process the `lookAt` property on Cameras. -* A SpotLight or a DirectionalLight _SHOULD_ have the `lookAt` property.
- -```json -"lookAt": { - "type": "PointSelector", - "x": 3, - "y": 0, - "z": -10 -} -``` - -##### color - -This property sets the color of a Light. - -The value _MUST_ be string, which defines an RGB color. It SHOULD be a hex value starting with "#" and is treated in a case-insensitive fashion. If this property is not specified, then the default value is "#FFFFFF". - - * A Light _SHOULD_ have the `color` property
- Clients _SHOULD_ render `color` on any resource type. - * Other resources _MUST NOT_ have the `color` property. - -```json -"color": "#FFA0A0" -``` - -##### intensity - -This property sets the strength or brightness of a Light. - -The value _MUST_ be a JSON object, that has the `type`, `value` and `unit` properties. All three properties are required. The value of `type` _MUST_ be the string "UnitValue". The value of `value` is a floating point number. The value of `unit` is a string, drawn from a controlled vocabulary of units. If this property is not specified, then the default intensity value is client-dependent. - -This specification defines the unit value of "relative" which constrains the value to be a linear scale between 0.0 (no brightness) and 1.0 (as bright as the client will render). - -* A Light _SHOULD_ have the `intensity` property.
- Clients _SHOULD_ process the `intensity` property on Lights. - -```json -{ - "intensity": {"id": "", "type": "UnitValue", "value": 0.5, "unit": "relative"} -} -``` - -##### exclude - -_Summary here_ - -_On Annotation, a list of strings drawn from table_ +The value _MUST_ be a string, either taken from the [profiles registry][registry-profiles] or a URI. -| Value | Description | -|------------|-------------| -| Audio | | -| Animations | | -| Cameras | | -| Lights | | +* Resources [referenced][prezi30-terminology] by the `seeAlso` or `service` properties _SHOULD_ have the `profile` property.
+ Clients _SHOULD_ process the `profile` of a service or external resource. +* Other types of resource _MAY_ have the `profile` property.
+ Clients _MAY_ process the `profile` of other types of resource. -```json -"exclude": [ "Audio", "Lights", "Cameras", "Animations" ] +{% include api/code_header.html %} +``` json-doc +{ "profile": "https://example.org/profile/statuary" } ``` +##### provider +An organization or person that contributed to providing the content of the resource. Clients can then display this information to the user to acknowledge the provider's contributions. This differs from the `requiredStatement` property, in that the data is structured, allowing the client to do more than just present text but instead have richer information about the people and organizations to use in different interfaces. +The organization or person is represented as an `Agent` resource. +* Agents _MUST_ have the `id` property, and its value _MUST_ be a string. The string _MUST_ be a URI that identifies the agent. +* Agents _MUST_ have the `type` property, and its value _MUST_ be the string `Agent`. +* Agents _MUST_ have the `label` property, and its value _MUST_ be a JSON object as described in the [languages][prezi30-languages] section. +* Agents _SHOULD_ have the `homepage` property, and its value _MUST_ be an array of JSON objects as described in the [homepage][prezi30-homepage] section. +* Agents _SHOULD_ have the `logo` property, and its value _MUST_ be an array of JSON objects as described in the [logo][prezi30-logo] section. +* Agents _MAY_ have the `seeAlso` property, and its value _MUST_ be an array of JSON object as described in the [seeAlso][prezi30-seealso] section. +The value _MUST_ be an array of JSON objects, where each item in the array conforms to the structure of an Agent, as described above. -##### transform - -_Summary here_ + * A Collection _SHOULD_ have the `provider` property with at least one item.
+ Clients _MUST_ render `provider` on a Collection. + * A Manifest _SHOULD_ have the `provider` property with at least one item.
+ Clients _MUST_ render `provider` on a Manifest. + * Other types of resource _MAY_ have the `provider` property with at least one item.
+ Clients _SHOULD_ render `provider` on other types of resource. -The value of this property is an array of JSON objects, each of which is a Transform. +{% include api/code_header.html %} +``` json-doc +{ + "provider": [ + { + "id": "https://example.org/about", + "type": "Agent", + "label": { "en": [ "Example Organization" ] }, + "homepage": [ + { + "id": "https://example.org/", + "type": "Text", + "label": { "en": [ "Example Organization Homepage" ] }, + "format": "text/html" + } + ], + "logo": [ + { + "id": "https://example.org/images/logo.png", + "type": "Image", + "format": "image/png", + "height": 100, + "width": 120 + } + ], + "seeAlso": [ + { + "id": "https://data.example.org/about/us.jsonld", + "type": "Dataset", + "format": "application/ld+json", + "profile": "https://schema.org/" + } + ] + } + ] +} +``` +##### provides -##### x +A set of features or additional functionality that a linked resource enables relative to the linking or including resource, which is not defined by the `type`, `format` or `profile` of the linked resource. It provides information as to why and how a client might want to interact with the resource, rather than what the resource is. For example, a text file (linked resource) that `provides` a `closedCaptions` for a Video (context resource), or an audio file (linked resource) that `provides` an `audioDescription` of a Canvas (context resource). -##### y +The value _MUST_ be an array of strings, each string identifies a particular feature and _MUST_ be taken from the table below or the [provides registry][link]. -##### z +Note that the majority of the values have been selected from [accessibility feature spec][link] and thus use the original form rather than being consistent with the hyphen-based form of the values of `behavior` and `viewingDirection`. -### Linking Properties +* Annotations with the `painting` motivation _SHOULD NOT_ have the `provides` property.
+ Clients _SHOULD_ ignore the `provides` property on Annotations with the `painting` motivation. +* Any resource linked to or included in another resource _MAY_ have the `provides` property.
+ Clients _SHOULD_ process the `provides` property on these resources. +| Value | Description | +| ----- | ----------- | +| `closedCaptions` | ... | +| `alternativeText` | ... | +| `audioDescription` | ... | +| `longDescription` | ... | +| `signLanguage` | ... | +| `highContrastAudio` | ... | +| `highContrastDisplay` | ... | +| `braille` | ... | +| `tactileGraphic` | ... | +| `transcript` | ... | +| `translation` | (IIIF Defined) ... | +| `subtitles` | (IIIF Defined) ... | +{: .api-table #table-behavior} -##### homepage +{% include api/code_header.html %} +``` json-doc +{ "provides": [ "closedCaption" ] } +``` -A web page that is about the object represented by the resource that has the `homepage` property. The web page is usually published by the organization responsible for the object, and might be generated by a content management system or other cataloging system. The resource _MUST_ be able to be displayed directly to the user. Resources that are related, but not home pages, _MUST_ instead be added into the `metadata` property, with an appropriate `label` or `value` to describe the relationship. +!!! warning "This breaks the graph as the file doesn't provide X in all contexts" +##### rendering -The value of this property _MUST_ be an array of JSON objects, each of which _MUST_ have the `id`, `type`, and `label` properties, _SHOULD_ have a `format` property, and _MAY_ have the `language` property. +A resource that is an alternative, non-IIIF representation of the resource that has the `rendering` property. Such representations typically cannot be painted onto a single Canvas, as they either include too many views, have incompatible dimensions, or are compound resources requiring additional rendering functionality. The `rendering` resource _MUST_ be able to be displayed directly to a human user, although the presentation may be outside of the IIIF client. The resource _MUST NOT_ have a splash page or other interstitial resource that mediates access to it. If access control is required, then the [IIIF Authentication API][iiif-auth] is _RECOMMENDED_. Examples include a rendering of a book as a PDF or EPUB, a slide deck with images of a building, or a 3D model of a statue. - * Any resource type _MAY_ have the `homepage` property.
- Clients _SHOULD_ render `homepage` on a Collection, Manifest or Canvas, and _MAY_ render `homepage` on other types of resource. +The value _MUST_ be an array of JSON objects. Each item _MUST_ have the `id`, `type` and `label` properties, and _SHOULD_ have the `format` and `language` properties. -__Model Alignment__
-Please note that this specification has stricter requirements about the JSON pattern used for the `homepage` property than the [Web Annotation Data Model][org-w3c-webanno]. The IIIF requirements are compatible, but the home page of an Agent found might have only a URI, or might be a JSON object with other properties. See the section on [collisions between contexts][prezi30-context-collisions] for more information. -{: .note} + * Any resource type _MAY_ have the `rendering` property with at least one item.
+ Clients _SHOULD_ render `rendering` on a Collection, Manifest or Canvas, and _MAY_ render `rendering` on other types of resource. {% include api/code_header.html %} ``` json-doc { - "homepage": [ + "rendering": [ { - "id": "https://example.com/info/", + "id": "https://example.org/1.pdf", "type": "Text", - "label": { "en": [ "Homepage for Example Object" ] }, - "format": "text/html", - "language": [ "en" ] + "label": { "en": [ "PDF Rendering of Book" ] }, + "format": "application/pdf" } ] } ``` +##### requiredStatement +Text that _MUST_ be displayed when the resource is displayed or used. For example, the `requiredStatement` property could be used to present copyright or ownership statements, an acknowledgement of the owning and/or publishing institution, or any other text that the publishing organization deems critical to display to the user. Given the wide variation of potential client user interfaces, it will not always be possible to display this statement to the user in the client's initial state. If initially hidden, clients _MUST_ make the method of revealing it as obvious as possible. -##### logo +The value of the property _MUST_ be a JSON object, that has the `label` and `value` properties, in the same way as a `metadata` property entry. The values of both `label` and `value` _MUST_ be JSON objects, as described in the [languages][prezi40-languages] section. -A small image resource that represents the Agent resource it is associated with. The logo _MUST_ be clearly rendered when the resource is displayed or used, without cropping, rotating or otherwise distorting the image. It is _RECOMMENDED_ that a [IIIF Image API][image-api] service be available for this image for other manipulations such as resizing. + * Any resource type _MAY_ have the `requiredStatement` property.
+ Clients _MUST_ render `requiredStatement` on every resource type. -When more than one logo is present, the client _SHOULD_ pick only one of them, based on the information in the logo properties. For example, the client could select a logo of appropriate aspect ratio based on the `height` and `width` properties of the available logos. The client _MAY_ decide on the logo by inspecting properties defined as [extensions][prezi30-ldce]. +{% include api/code_header.html %} +``` json-doc +{ + "requiredStatement": { + "label": { "en": [ "Attribution" ] }, + "value": { "en": [ "Provided courtesy of Example Institution" ] } + } +} +``` +##### rights -The value of this property _MUST_ be an array of JSON objects, each of which _MUST_ have `id` and `type` properties, and _SHOULD_ have `format`. The value of `type` _MUST_ be `Image`. +A string that identifies a license or rights statement that applies to the content of the resource, such as the JSON of a Manifest or the pixels of an image. The value _MUST_ be drawn from the set of [Creative Commons][org-cc-licenses] license URIs, the [RightsStatements.org][org-rs-terms] rights statement URIs, or those added via the [extension][prezi40-ldce] mechanism. The inclusion of this property is informative, and for example could be used to display an icon representing the rights assertions. - * Agent resources _SHOULD_ have the `logo` property.
- Clients _MUST_ render `logo` on Agent resources. +!!! registration not extension + +If displaying rights information directly to the user is the desired interaction, or a publisher-defined label is needed, then it is _RECOMMENDED_ to include the information using the `requiredStatement` property or in the `metadata` property. + +The value _MUST_ be a string. If the value is drawn from Creative Commons or RightsStatements.org, then the string _MUST_ be a URI defined by that specification. + * Any resource type _MAY_ have the `rights` property.
+ Clients _MAY_ render `rights` on any resource type. {% include api/code_header.html %} ``` json-doc -{ - "logo": [ - { - "id": "https://example.org/img/logo.jpg", - "type": "Image", - "format": "image/jpeg", - "height": 100, - "width": 120 - } - ] -} +{ "rights": "http://creativecommons.org/licenses/by/4.0/" } ``` -##### rendering +__Machine actionable URIs and links for users__
+The machine actionable URIs for both Creative Commons licenses and RightsStatements.org right statements are `http` URIs. In both cases, human readable descriptions are available from equivalent `https` URIs. Clients may wish to rewrite links presented to users to use these equivalent `https` URIs. +{: .note} -A resource that is an alternative, non-IIIF representation of the resource that has the `rendering` property. Such representations typically cannot be painted onto a single Canvas, as they either include too many views, have incompatible dimensions, or are compound resources requiring additional rendering functionality. The `rendering` resource _MUST_ be able to be displayed directly to a human user, although the presentation may be outside of the IIIF client. The resource _MUST NOT_ have a splash page or other interstitial resource that mediates access to it. If access control is required, then the [IIIF Authentication API][iiif-auth] is _RECOMMENDED_. Examples include a rendering of a book as a PDF or EPUB, a slide deck with images of a building, or a 3D model of a statue. +##### seeAlso -The value _MUST_ be an array of JSON objects. Each item _MUST_ have the `id`, `type` and `label` properties, and _SHOULD_ have the `format` and `language` properties. +A machine-readable resource such as an XML or RDF description that is related to the current resource that has the `seeAlso` property. Properties of the resource should be given to help the client select between multiple descriptions (if provided), and to make appropriate use of the document. If the relationship between the resource and the document needs to be more specific, then the document should include that relationship rather than the IIIF resource. Other IIIF resources are also valid targets for `seeAlso`, for example to link to a Manifest that describes a related object. The URI of the document _MUST_ identify a single representation of the data in a particular format. For example, if the same data exists in JSON and XML, then separate resources should be added for each representation, with distinct `id` and `format` properties. - * Any resource type _MAY_ have the `rendering` property with at least one item.
- Clients _SHOULD_ render `rendering` on a Collection, Manifest or Canvas, and _MAY_ render `rendering` on other types of resource. +The value _MUST_ be an array of JSON objects. Each item _MUST_ have the `id` and `type` properties, and _SHOULD_ have the `label`, `format` and `profile` properties. + + * Any resource type _MAY_ have the `seeAlso` property with at least one item.
+ Clients _MAY_ process `seeAlso` on any resource type. {% include api/code_header.html %} ``` json-doc { - "rendering": [ + "seeAlso": [ { - "id": "https://example.org/1.pdf", - "type": "Text", - "label": { "en": [ "PDF Rendering of Book" ] }, - "format": "application/pdf" + "id": "https://example.org/library/catalog/book1.xml", + "type": "Dataset", + "label": { "en": [ "Bibliographic Description in XML" ] }, + "format": "text/xml", + "profile": "https://example.org/profiles/bibliographic" } ] } ``` + ##### service A service that the client might interact with directly and gain additional information or functionality for using the resource that has the `service` property, such as from an Image to the base URI of an associated [IIIF Image API][image-api] service. The service resource _SHOULD_ have additional information associated with it in order to allow the client to determine how to make appropriate use of it. Please see the [Service Registry][registry-services] document for the details of currently known service types. @@ -1352,87 +1246,39 @@ Implementations _SHOULD_ be prepared to recognize the `@id` and `@type` property ] } ``` - - ##### services A list of one or more service definitions on the top-most resource of the document, that are typically shared by more than one subsequent resource. This allows for these shared services to be collected together in a single place, rather than either having their information duplicated potentially many times throughout the document, or requiring a consuming client to traverse the entire document structure to find the information. The resource that the service applies to _MUST_ still have the `service` property, as described above, where the service resources have at least the `id` and `type` or `@id` and `@type` properties. This allows the client to know that the service applies to that resource. Usage of the `services` property is at the discretion of the publishing system. -A client encountering a `service` property where the definition consists only of an `id` and `type` _SHOULD_ then check the `services` property on the top-most resource for an expanded definition. If the service is not present in the `services` list, and the client requires more information in order to use the service, then it _SHOULD_ dereference the `id` (or `@id`) of the service in order to retrieve a service description. - -The value _MUST_ be an array of JSON objects. Each object _MUST_ be a service resource, as described above. - -* A Collection _MAY_ have the `services` property, if it is the topmost Collection in a response document.
- Clients _SHOULD_ process `services` on a Collection. -* A Manifest _MAY_ have the `services` property.
- Clients _SHOULD_ process `services` on a Manifest. - -{% include api/code_header.html %} -``` json-doc -{ - "services": [ - { - "@id": "https://example.org/iiif/auth/login", - "@type": "AuthCookieService1", - "profile": "http://iiif.io/api/auth/1/login", - "label": "Login to Example Institution", - "service": [ - { - "@id": "https://example.org/iiif/auth/token", - "@type": "AuthTokenService1", - "profile": "http://iiif.io/api/auth/1/token" - } - ] - } - ] -} -``` - - -##### seeAlso - -A machine-readable resource such as an XML or RDF description that is related to the current resource that has the `seeAlso` property. Properties of the resource should be given to help the client select between multiple descriptions (if provided), and to make appropriate use of the document. If the relationship between the resource and the document needs to be more specific, then the document should include that relationship rather than the IIIF resource. Other IIIF resources are also valid targets for `seeAlso`, for example to link to a Manifest that describes a related object. The URI of the document _MUST_ identify a single representation of the data in a particular format. For example, if the same data exists in JSON and XML, then separate resources should be added for each representation, with distinct `id` and `format` properties. - -The value _MUST_ be an array of JSON objects. Each item _MUST_ have the `id` and `type` properties, and _SHOULD_ have the `label`, `format` and `profile` properties. - - * Any resource type _MAY_ have the `seeAlso` property with at least one item.
- Clients _MAY_ process `seeAlso` on any resource type. - -{% include api/code_header.html %} -``` json-doc -{ - "seeAlso": [ - { - "id": "https://example.org/library/catalog/book1.xml", - "type": "Dataset", - "label": { "en": [ "Bibliographic Description in XML" ] }, - "format": "text/xml", - "profile": "https://example.org/profiles/bibliographic" - } - ] -} -``` - - -#### 3.3.2. Internal Links - -##### partOf - -A containing resource that includes the resource that has the `partOf` property. When a client encounters the `partOf` property, it might retrieve the [referenced][prezi30-terminology] containing resource, if it is not [embedded][prezi30-terminology] in the current representation, in order to contribute to the processing of the contained resource. For example, the `partOf` property on a Canvas can be used to reference an external Manifest in order to enable the discovery of further relevant information. Similarly, a Manifest can reference a containing Collection using `partOf` to aid in navigation. +A client encountering a `service` property where the definition consists only of an `id` and `type` _SHOULD_ then check the `services` property on the top-most resource for an expanded definition. If the service is not present in the `services` list, and the client requires more information in order to use the service, then it _SHOULD_ dereference the `id` (or `@id`) of the service in order to retrieve a service description. -The value _MUST_ be an array of JSON objects. Each item _MUST_ have the `id` and `type` properties, and _SHOULD_ have the `label` property. +The value _MUST_ be an array of JSON objects. Each object _MUST_ be a service resource, as described above. - * Any resource type _MAY_ have the `partOf` property with at least one item
- Clients _MAY_ render `partOf` on any resource type. +* A Collection _MAY_ have the `services` property, if it is the topmost Collection in a response document.
+ Clients _SHOULD_ process `services` on a Collection. +* A Manifest _MAY_ have the `services` property.
+ Clients _SHOULD_ process `services` on a Manifest. {% include api/code_header.html %} ``` json-doc -{ "partOf": [ { "id": "https://example.org/iiif/1", "type": "Manifest" } ] } +{ + "services": [ + { + "@id": "https://example.org/iiif/auth/login", + "@type": "AuthCookieService1", + "profile": "http://iiif.io/api/auth/1/login", + "label": "Login to Example Institution", + "service": [ + { + "@id": "https://example.org/iiif/auth/token", + "@type": "AuthTokenService1", + "profile": "http://iiif.io/api/auth/1/token" + } + ] + } + ] +} ``` - -The resources referred to by the `accompanyingContainer` and `placeholderContainer` properties are `partOf` that referring Container. - - ##### start A Canvas, or part of a Canvas, which the client _SHOULD_ show on initialization for the resource that has the `start` property. The reference to part of a Canvas is handled in the same way that Ranges reference parts of Canvases. This property allows the client to begin with the first Canvas that contains interesting content rather than requiring the user to manually navigate to find it. @@ -1465,6 +1311,48 @@ The value _MUST_ be a JSON object, which _MUST_ have the `id` and `type` propert } } ``` +##### structures + +The structure of an object represented as a Manifest can be described using a hierarchy of Ranges. Ranges can be used to describe the "table of contents" of the object or other structures that the user can interact with beyond the order given by the `items` property of the Manifest. The hierarchy is built by nesting the child Range resources in the `items` array of the higher level Range. The top level Ranges of these hierarchies are given in the `structures` property. + +The value _MUST_ be an array of JSON objects. Each item _MUST_ have the `id` and `type` properties, and the `type` _MUST_ be `Range`. + + * A Manifest _MAY_ have the `structures` property.
+ Clients _SHOULD_ process `structures` on a Manifest. The first hierarchy _SHOULD_ be presented to the user by default, and further hierarchies _SHOULD_ be able to be selected as alternative structures by the user. + * Other types of resource _MUST NOT_ have the `structures` property.
+ Clients _SHOULD_ ignore `structures` on other types of resource. + +{% include api/code_header.html %} +``` json-doc +{ + "structures": [ + { + "id": "https://example.org/iiif/range/1", + "type": "Range", + "items": [ { ... } ] + } + ] +} +``` +##### summary + +A short textual summary intended to be conveyed to the user when the `metadata` entries for the resource are not being displayed. This could be used as a brief description for item level search results, for small-screen environments, or as an alternative user interface when the `metadata` property is not currently being rendered. The `summary` property follows the same pattern as the `label` property described above. + +The value of the property _MUST_ be a JSON object, as described in the [languages][prezi40-languages] section. + + * A Collection _SHOULD_ have the `summary` property with at least one entry.
+ Clients _SHOULD_ render `summary` on a Collection. + * A Manifest _SHOULD_ have the `summary` property with at least one entry.
+ Clients _SHOULD_ render `summary` on a Manifest. + * All Container types _MAY_ have the `summary` property with at least one entry.
+ Clients _SHOULD_ render `summary` on Containers. + * Other types of resource _MAY_ have the `summary` property with at least one entry.
+ Clients _MAY_ render `summary` on other types of resource. + +{% include api/code_header.html %} +``` json-doc +{ "summary": { "en": [ "This is a summary of the object." ] } } +``` ##### supplementary @@ -1482,100 +1370,153 @@ The value _MUST_ be a JSON object, which _MUST_ have the `id` and `type` propert { "supplementary": { "id": "https://example.org/iiif/1/annos/1", "type": "AnnotationCollection" } } ``` -### Structural Properties - - -##### items +##### thumbnail -Much of the functionality of the IIIF Presentation API is simply recording the order in which child resources occur within a parent resource, such as Collections or Manifests within a parent Collection, or Canvases within a Manifest. All of these situations are covered with a single property, `items`. +A content resource, such as a small image or short audio clip, that represents the resource that has the `thumbnail` property. A resource _MAY_ have multiple thumbnail resources that have the same or different `type` and `format`. -The value _MUST_ be an array of JSON objects. Each item _MUST_ have the `id` and `type` properties. The items will be resources of different types, as described below. +The value _MUST_ be an array of JSON objects, each of which _MUST_ have the `id` and `type` properties, and _SHOULD_ have the `format` property. Images and videos _SHOULD_ have the `width` and `height` properties, and time-based media _SHOULD_ have the `duration` property. It is _RECOMMENDED_ that a [IIIF Image API][image-api] service be available for images to enable manipulations such as resizing. - * A Collection _MUST_ have the `items` property. Each item _MUST_ be either a Collection or a Manifest.
- Clients _MUST_ process `items` on a Collection. - * A Manifest _MUST_ have the `items` property with at least one item. Each item _MUST_ be a Canvas.
- Clients _MUST_ process `items` on a Manifest. - * A Canvas _SHOULD_ have the `items` property with at least one item. Each item _MUST_ be an Annotation Page.
- Clients _MUST_ process `items` on a Canvas. - * An Annotation Page _SHOULD_ have the `items` property with at least one item. Each item _MUST_ be an Annotation.
- Clients _MUST_ process `items` on an Annotation Page. - * A Range _MUST_ have the `items` property with at least one item. Each item _MUST_ be a Range, a Canvas or a Specific Resource where the source is a Canvas.
- Clients _SHOULD_ process `items` on a Range. - * Other types of resource _MUST NOT_ have the `items` property.
- Clients _SHOULD_ ignore `items` on other types of resource. + * A Collection _SHOULD_ have the `thumbnail` property with at least one item.
+ Clients _SHOULD_ render `thumbnail` on a Collection. + * A Manifest _SHOULD_ have the `thumbnail` property with at least one item.
+ Clients _SHOULD_ render `thumbnail` on a Manifest. + * All Container types _SHOULD_ have the `thumbnail` property with at least one item.
+ Clients _SHOULD_ render `thumbnail` on Containers. + * Content Resource types _MAY_ have the `thumbnail` property with at least one item. Content Resources _SHOULD_ have the `thumbnail` property with at least one item if it is an option in a Choice of resources.
+ Clients _SHOULD_ render `thumbnail` on a content resource. + * Other types of resource _MAY_ have the `thumbnail` property with at least one item.
+ Clients _MAY_ render `thumbnail` on other types of resource. {% include api/code_header.html %} ``` json-doc { - "items": [ - { - "id": "https://example.org/iiif/manifest1", - "type": "Manifest" - }, + "thumbnail": [ { - "id": "https://example.org/iiif/collection1", - "type": "Collection" + "id": "https://example.org/img/thumb.jpg", + "type": "Image", + "format": "image/jpeg", + "width": 300, + "height": 200 } - // ... ] } ``` -##### structures +##### timeMode -The structure of an object represented as a Manifest can be described using a hierarchy of Ranges. Ranges can be used to describe the "table of contents" of the object or other structures that the user can interact with beyond the order given by the `items` property of the Manifest. The hierarchy is built by nesting the child Range resources in the `items` array of the higher level Range. The top level Ranges of these hierarchies are given in the `structures` property. +A mode associated with an Annotation that is to be applied to the rendering of any time-based media, or otherwise could be considered to have a duration, used as a body resource of that Annotation. Note that the association of `timeMode` with the Annotation means that different resources in the body cannot have different values. This specification defines the values specified in the table below. Others may be defined externally as an [extension][prezi30-ldce]. -The value _MUST_ be an array of JSON objects. Each item _MUST_ have the `id` and `type` properties, and the `type` _MUST_ be `Range`. +The value _MUST_ be a string. - * A Manifest _MAY_ have the `structures` property.
- Clients _SHOULD_ process `structures` on a Manifest. The first hierarchy _SHOULD_ be presented to the user by default, and further hierarchies _SHOULD_ be able to be selected as alternative structures by the user. - * Other types of resource _MUST NOT_ have the `structures` property.
- Clients _SHOULD_ ignore `structures` on other types of resource. + * An Annotation _MAY_ have the `timeMode` property.
+ Clients _SHOULD_ process `timeMode` on an Annotation. + +| Value | Description | +| ----- | ----------- | +| `trim` | (default, if not supplied) If the content resource has a longer duration than the duration of the portion of the Canvas it is associated with, then at the end of the Canvas's duration, the playback of the content resource _MUST_ also end. If the content resource has a shorter duration than the duration of the portion of the Canvas it is associated with, then, for video resources, the last frame _SHOULD_ persist on-screen until the end of the Canvas portion's duration. For example, a video of 120 seconds annotated to a Canvas with a duration of 100 seconds would play only the first 100 seconds and drop the last 20 seconds. | +| `scale` | Fit the duration of content resource to the duration of the portion of the Canvas it is associated with by scaling. For example, a video of 120 seconds annotated to a Canvas with a duration of 60 seconds would be played at double-speed. | +| `loop` | If the content resource is shorter than the `duration` of the Canvas, it _MUST_ be repeated to fill the entire duration. Resources longer than the `duration` _MUST_ be trimmed as described above. For example, if a 20 second duration audio stream is annotated onto a Canvas with a duration of 30 seconds, it will be played one and a half times. | +{: .api-table #table-timemode} {% include api/code_header.html %} ``` json-doc -{ - "structures": [ - { - "id": "https://example.org/iiif/range/1", - "type": "Range", - "items": [ { ... } ] - } - ] -} +{ "timeMode": "trim" } ``` -##### annotations -An ordered list of Annotation Pages that contain commentary or other Annotations about this resource, separate from the Annotations that are used to paint content on to a Canvas. The `motivation` of the Annotations _MUST NOT_ be `painting`, and the target of the Annotations _MUST_ include this resource or part of it. +##### transform -The value _MUST_ be an array of JSON objects. Each item _MUST_ have at least the `id` and `type` properties. +_Summary here_ - * A Collection _MAY_ have the `annotations` property with at least one item.
- Clients _SHOULD_ process `annotations` on a Collection. - * A Manifest _MAY_ have the `annotations` property with at least one item.
- Clients _SHOULD_ process `annotations` on a Manifest,. - * A Canvas _MAY_ have the `annotations` property with at least one item.
- Clients _SHOULD_ process `annotations` on a Canvas. - * A Range _MAY_ have the `annotations` property with at least one item.
- Clients _SHOULD_ process `annotations` on a Range. - * A content resource _MAY_ have the `annotations` property with at least one item.
- Clients _SHOULD_ process `annotations` on a content resource. - * Other types of resource _MUST NOT_ have the `annotations` property.
- Clients _SHOULD_ ignore `annotations` on other types of resource. +The value of this property is an array of JSON objects, each of which is a Transform. + +##### type + +The type or class of the resource. For classes defined for this specification, the value of `type` will be described in the sections below describing each individual class. + +For content resources, the value of `type` is drawn from other specifications. Recommendations for common content types such as image, text or audio are given in the table below. + +The JSON objects that appear in the value of the `service` property will have many different classes, and can be used to distinguish the sort of service, with specific properties defined in a [registered context document][prezi30-ldce]. + +The value _MUST_ be a string. + + * All resource types _MUST_ have the `type` property.
+ Clients _MUST_ process, and _MAY_ render, `type` on any resource type. + +| Class | Description | +| ------------- | -------------------------------- | +| `Dataset` | Data not intended to be rendered to humans directly, such as a CSV, an RDF serialization or a zip file | +| `Image` | Two dimensional visual resources primarily intended to be seen, such as might be rendered with an <img> HTML tag | +| `Model` | A three dimensional spatial model intended to be visualized, such as might be rendered with a 3d javascript library | +| `Sound` | Auditory resources primarily intended to be heard, such as might be rendered with an <audio> HTML tag | +| `Text` | Resources primarily intended to be read | +| `Video` | Moving images, with or without accompanying audio, such as might be rendered with a <video> HTML tag | +{: .api-table #table-type} {% include api/code_header.html %} ``` json-doc -{ - "annotations": [ - { - "id": "https://example.org/iiif/annotationPage/1", - "type": "AnnotationPage", - "items": [ { ... } ] - } - ] -} +{ "type": "Image" } +``` + +##### viewingDirection + +!!! Rewrite to be where is the navigation control to step to the next/ previous in the items of hte manifest + + +The direction in which a list of Containers _SHOULD_ be displayed to the user. This specification defines four direction values in the table below. Others may be defined externally [as an extension][prezi30-ldce]. For example, +if the `viewingDirection` value is `left-to-right`, then backwards in the list is to the left, and forwards in the +list is to the right. + +The value _MUST_ be a string. + + * A Collection _MAY_ have the `viewingDirection` property.
+ Clients _SHOULD_ process `viewingDirection` on a Collection. + * A Manifest _MAY_ have the `viewingDirection` property.
+ Clients _SHOULD_ process `viewingDirection` on a Manifest. + * A Range _MAY_ have the `viewingDirection` property.
+ Clients _MAY_ process `viewingDirection` on a Range. + * Other types of resource _MUST NOT_ have the `viewingDirection` property.
+ Clients _SHOULD_ ignore `viewingDirection` on other types of resource. + +| Value | Description | +| ----- | ----------- | +| `left-to-right` | The object is displayed from left to right. The default if not specified. | +| `right-to-left` | The object is displayed from right to left. | +| `top-to-bottom` | The object is displayed from the top to the bottom. | +| `bottom-to-top` | The object is displayed from the bottom to the top. | +{: .api-table #table-direction} + +{% include api/code_header.html %} +``` json-doc +{ "viewingDirection": "left-to-right" } +``` + +##### width + +The width of the Canvas or external content resource. For content resources, the value is in pixels. For Canvases, the value does not have a unit. In combination with the height, it conveys an aspect ratio for the space in which content resources are located. + +The value _MUST_ be a positive integer. + + * A Canvas _MUST_ have the `width` property.
+ Clients _MUST_ process `width` on a Canvas. + * Content resources _SHOULD_ have the `width` property, with the value given in pixels, if appropriate to the resource type.
+ Clients _SHOULD_ process `width` on content resources. + * Other types of resource _MUST NOT_ have the `width` property.
+ Clients _SHOULD_ ignore `width` on other types of resource. + +{% include api/code_header.html %} +``` json-doc +{ "width": 1200 } ``` +##### x + +##### y + +##### z + + + + ### 3.5. Values From f14cb5df64feb011eb280f2a33ead6d72acecd78 Mon Sep 17 00:00:00 2001 From: Rob Sanderson Date: Tue, 18 Mar 2025 09:12:25 -0400 Subject: [PATCH 034/130] add anchors --- source/presentation/4.0/model.md | 54 ++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index 2e63386b1..2480432f3 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -372,6 +372,7 @@ Ranges _MAY_ link to an Annotation Collection that has the content of the Range ##### accompanyingContainer +{: #accompanyingContainer} A single Container that provides additional content for use while rendering the resource that has the `accompanyingContainer` property. Examples include an image to show while a duration-only Canvas is playing audio; or background audio to play while a user is navigating an image-only Manifest. @@ -402,6 +403,7 @@ The value of `accompanyingContainer` _MUST_ be a JSON object with the `id` and ` ``` ##### angle +{: #angle} !!! warning "Need more info" @@ -414,6 +416,7 @@ The value _MUST_ be a floating point number greater than 0 and less than 90, and "angle": 15.0 ``` ##### annotations +{: #annotations} An ordered list of Annotation Pages that contain commentary or other Annotations about this resource, separate from the Annotations that are used to paint content on to a Canvas. The `motivation` of the Annotations _MUST NOT_ be `painting`, and the target of the Annotations _MUST_ include this resource or part of it. @@ -446,6 +449,7 @@ The value _MUST_ be an array of JSON objects. Each item _MUST_ have at least the ``` ##### backgroundColor +{: #backgroundColor} This property sets the background color behind any painted resources on a spatial Container, such as a Canvas or Scene. @@ -462,6 +466,7 @@ The value _MUST_ be string, which defines an RGB color. It SHOULD be a hex value ``` ##### behavior +{: #behavior} A set of user experience features that the publisher of the content would prefer the client to use when presenting the resource. This specification defines the values in the table below. Others may be defined externally as an [extension][prezi30-ldce]. @@ -513,7 +518,9 @@ The value _MUST_ be an array of strings. ``` json-doc { "behavior": [ "auto-advance", "individuals" ] } ``` + ##### color +{: #color} This property sets the color of a Light. @@ -526,7 +533,9 @@ The value _MUST_ be string, which defines an RGB color. It SHOULD be a hex value ```json "color": "#FFA0A0" ``` + ##### duration +{: #duration} The duration of a container or external content resource, given in seconds. @@ -545,7 +554,9 @@ The value _MUST_ be a positive floating point number. ``` json-doc { "duration": 125.0 } ``` + ##### exclude +{: #exclude} _Summary here_ @@ -561,7 +572,9 @@ _On Annotation, a list of strings drawn from table_ ```json "exclude": [ "Audio", "Lights", "Cameras", "Animations" ] ``` + ##### far +{: #far} This property gives the distance from the camera after which objects are no longer visible. Objects further from the camera than the `far` distance cannot be seen. @@ -574,6 +587,7 @@ The value is a non-negative floating point number, in the coordinate space of th { "far": 200.0 } ``` ##### fieldOfView +{: #fieldOfView} The angle which a PerspectiveCamera can "see". @@ -588,6 +602,7 @@ The value _MUST_ be a floating point number greater than 0 and less than 180, an { "fieldOfView": 50.0 } ``` ##### format +{: #format} The specific media type (often called a MIME type) for a content resource, for example `image/jpeg`. This is important for distinguishing different formats of the same overall type of resource, such as distinguishing text in XML from plain text. @@ -605,6 +620,7 @@ The value _MUST_ be a string, and it _SHOULD_ be the value of the `Content-Type` { "format": "application/xml" } ``` ##### height +{: #height} The height of the Canvas or external content resource. For content resources, the value is in pixels. For Canvases, the value does not have a unit. In combination with the width, it conveys an aspect ratio for the space in which content resources are located. @@ -622,6 +638,7 @@ The value _MUST_ be a positive integer. { "height": 1800 } ``` ##### homepage +{: #homepage} A web page that is about the object represented by the resource that has the `homepage` property. The web page is usually published by the organization responsible for the object, and might be generated by a content management system or other cataloging system. The resource _MUST_ be able to be displayed directly to the user. Resources that are related, but not home pages, _MUST_ instead be added into the `metadata` property, with an appropriate `label` or `value` to describe the relationship. @@ -649,6 +666,7 @@ Please note that this specification has stricter requirements about the JSON pat } ``` ##### id +{: #id} The URI that identifies the resource. If the resource is only available embedded within another resource (see the [terminology section][prezi30-terminology] for an explanation of "embedded"), such as a Range within a Manifest, then the URI _MAY_ be the URI of the embedding resource with a unique fragment on the end. This is not true for Canvases, which _MUST_ have their own URI without a fragment. @@ -664,6 +682,7 @@ The existence of an HTTP(S) URI in the `id` property does not mean that the URI { "id": "https://example.org/iiif/1/manifest" } ``` ##### intensity +{: #intensity} This property sets the strength or brightness of a Light. @@ -680,6 +699,7 @@ This specification defines the unit value of "relative" which constrains the val } ``` ##### interactionMode +{: #interactionMode} *within* the Scene, whereas viewingDirection and behavior are across containers. @@ -696,6 +716,7 @@ free-direction other examples: no-zoom, no-scrub, rti-mode ##### items +{: #items} Much of the functionality of the IIIF Presentation API is simply recording the order in which child resources occur within a parent resource, such as Collections or Manifests within a parent Collection, or Canvases within a Manifest. All of these situations are covered with a single property, `items`. @@ -731,6 +752,7 @@ The value _MUST_ be an array of JSON objects. Each item _MUST_ have the `id` and } ``` ##### label +{: #label} A human readable label, name or title. The `label` property is intended to be displayed as a short, textual surrogate for the resource if a human needs to make a distinction between it and similar resources, for example between objects, pages, or options for a choice of images to display. The `label` property can be fully internationalized, and each language can have multiple values. This pattern is described in more detail in the [languages][prezi40-languages] section. @@ -756,6 +778,7 @@ The value of the property _MUST_ be a JSON object, as described in the [language { "label": { "en": [ "Example Object Title" ] } } ``` ##### language +{: #language} The language or languages used in the content of this external resource. This property is already available from the Web Annotation model for content resources that are the body or target of an Annotation, however it _MAY_ also be used for resources [referenced][prezi30-terminology] from `homepage`, `rendering`, and `partOf`. @@ -771,6 +794,7 @@ The value _MUST_ be an array of strings. Each item in the array _MUST_ be a vali { "language": [ "en" ] } ``` ##### logo +{: #logo} A small image resource that represents the Agent resource it is associated with. The logo _MUST_ be clearly rendered when the resource is displayed or used, without cropping, rotating or otherwise distorting the image. It is _RECOMMENDED_ that a [IIIF Image API][image-api] service be available for this image for other manipulations such as resizing. @@ -797,6 +821,7 @@ The value of this property _MUST_ be an array of JSON objects, each of which _MU } ``` ##### lookAt +{: #lookAt} _Summary here_ @@ -815,6 +840,7 @@ The value _MUST_ be a JSON object, conforming to either a reference to an Annota } ``` ##### metadata +{: #metadata} An ordered list of descriptions to be displayed to the user when they interact with the resource, given as pairs of human readable `label` and `value` entries. The content of these entries is intended for presentation only; descriptive semantics _SHOULD NOT_ be inferred. An entry might be used to convey information about the creation of the object, a physical description, ownership information, or other purposes. @@ -843,6 +869,7 @@ Clients _SHOULD_ display the entries in the order provided. Clients _SHOULD_ exp } ``` ##### navDate +{: #navDate} A date that clients may use for navigation purposes when presenting the resource to the user in a date-based user interface, such as a calendar or timeline. More descriptive date ranges, intended for display directly to the user, _SHOULD_ be included in the `metadata` property for human consumption. If the resource contains Canvases that have the `duration` property, the datetime given corresponds to the navigation datetime of the start of the resource. For example, a Range that includes a Canvas that represents a set of video content recording a historical event, the `navDate` is the datetime of the first moment of the recorded event. @@ -866,6 +893,7 @@ The value _MUST_ be an [XSD dateTime literal][org-w3c-xsd-datetime]. The value _ { "navDate": "2010-01-01T00:00:00Z" } ``` ##### navPlace +{: #navPlace} A geographic location that clients may use for navigation purposes when presenting the resource to the user in a map-based user interface. The location is identified using structured data, described below, with latitude and longitude based points or polygons. If the location is only textual, then the information should instead be included in the `metadata` property. @@ -909,6 +937,7 @@ The value of the property _MUST_ be a [GeoJSON Feature Collection] [link] contai } ``` ##### near +{: #near} This property gives the distance from the camera from which objects are visible. Objects closer to the camera than the `near` distance cannot be seen. @@ -922,6 +951,7 @@ The value is a non-negative floating point number, in the coordinate space of th ``` ##### partOf +{: #partOf} A containing resource that includes the resource that has the `partOf` property. When a client encounters the `partOf` property, it might retrieve the [referenced][prezi30-terminology] containing resource, if it is not [embedded][prezi30-terminology] in the current representation, in order to contribute to the processing of the contained resource. For example, the `partOf` property on a Canvas can be used to reference an external Manifest in order to enable the discovery of further relevant information. Similarly, a Manifest can reference a containing Collection using `partOf` to aid in navigation. @@ -938,6 +968,7 @@ The value _MUST_ be an array of JSON objects. Each item _MUST_ have the `id` and The resources referred to by the `accompanyingContainer` and `placeholderContainer` properties are `partOf` that referring Container. ##### placeholderContainer +{: #placeholderContainer} A single Container that provides additional content for use before the main content of the resource that has the `placeholderContainer` property is rendered, or as an advertisement or stand-in for that content. Examples include images, text and sound standing in for video content before the user initiates playback; or a film poster to attract user attention. The content provided by `placeholderContainer` differs from a thumbnail: a client might use `thumbnail` to summarize and navigate multiple resources, then show content from `placeholderContainer` as part of the initial presentation of a single resource. A placeholder Container is likely to have different dimensions to those of the Container(s) of the resource that has the `placeholderContainer` property. A placeholder Container may be of a different type from the resource that has the `placeholderContainer` property. For example, a `Scene` may have a placeholder Container of type `Canvas`. @@ -968,6 +999,7 @@ The value of `placeholderContainer` _MUST_ be a JSON object with the `id` and `t } ``` ##### position +{: #position} It is important to be able to position the (textual) body of an annotation within the Container's space that the annotation also targets. For example, a description of part of an image in a Canvas should be positioned such that it does not obscure the image region itself and labels to be displayed as part of a Scene should not be rendered such that the text is hidden by the three dimensional geometry of the model. If this property is not supplied, then the client should do its best to ensure the content is visible to the user. @@ -996,6 +1028,7 @@ The value of this property _MUST_ be a JSON object conforming to the `SpecificRe ``` ##### profile +{: #profile} A schema or named set of functionality available from the resource. The profile can further clarify the `type` and/or `format` of an external resource or service, allowing clients to customize their handling of the resource that has the `profile` property. @@ -1011,6 +1044,7 @@ The value _MUST_ be a string, either taken from the [profiles registry][registry { "profile": "https://example.org/profile/statuary" } ``` ##### provider +{: #provider} An organization or person that contributed to providing the content of the resource. Clients can then display this information to the user to acknowledge the provider's contributions. This differs from the `requiredStatement` property, in that the data is structured, allowing the client to do more than just present text but instead have richer information about the people and organizations to use in different interfaces. @@ -1070,6 +1104,7 @@ The value _MUST_ be an array of JSON objects, where each item in the array confo } ``` ##### provides +{: #provides} A set of features or additional functionality that a linked resource enables relative to the linking or including resource, which is not defined by the `type`, `format` or `profile` of the linked resource. It provides information as to why and how a client might want to interact with the resource, rather than what the resource is. For example, a text file (linked resource) that `provides` a `closedCaptions` for a Video (context resource), or an audio file (linked resource) that `provides` an `audioDescription` of a Canvas (context resource). @@ -1106,6 +1141,7 @@ Note that the majority of the values have been selected from [accessibility feat !!! warning "This breaks the graph as the file doesn't provide X in all contexts" ##### rendering +{: #rendering} A resource that is an alternative, non-IIIF representation of the resource that has the `rendering` property. Such representations typically cannot be painted onto a single Canvas, as they either include too many views, have incompatible dimensions, or are compound resources requiring additional rendering functionality. The `rendering` resource _MUST_ be able to be displayed directly to a human user, although the presentation may be outside of the IIIF client. The resource _MUST NOT_ have a splash page or other interstitial resource that mediates access to it. If access control is required, then the [IIIF Authentication API][iiif-auth] is _RECOMMENDED_. Examples include a rendering of a book as a PDF or EPUB, a slide deck with images of a building, or a 3D model of a statue. @@ -1128,6 +1164,7 @@ The value _MUST_ be an array of JSON objects. Each item _MUST_ have the `id`, `t } ``` ##### requiredStatement +{: #requiredStatement} Text that _MUST_ be displayed when the resource is displayed or used. For example, the `requiredStatement` property could be used to present copyright or ownership statements, an acknowledgement of the owning and/or publishing institution, or any other text that the publishing organization deems critical to display to the user. Given the wide variation of potential client user interfaces, it will not always be possible to display this statement to the user in the client's initial state. If initially hidden, clients _MUST_ make the method of revealing it as obvious as possible. @@ -1146,6 +1183,7 @@ The value of the property _MUST_ be a JSON object, that has the `label` and `val } ``` ##### rights +{: #rights} A string that identifies a license or rights statement that applies to the content of the resource, such as the JSON of a Manifest or the pixels of an image. The value _MUST_ be drawn from the set of [Creative Commons][org-cc-licenses] license URIs, the [RightsStatements.org][org-rs-terms] rights statement URIs, or those added via the [extension][prezi40-ldce] mechanism. The inclusion of this property is informative, and for example could be used to display an icon representing the rights assertions. @@ -1168,6 +1206,7 @@ The machine actionable URIs for both Creative Commons licenses and RightsStateme {: .note} ##### seeAlso +{: #seeAlso} A machine-readable resource such as an XML or RDF description that is related to the current resource that has the `seeAlso` property. Properties of the resource should be given to help the client select between multiple descriptions (if provided), and to make appropriate use of the document. If the relationship between the resource and the document needs to be more specific, then the document should include that relationship rather than the IIIF resource. Other IIIF resources are also valid targets for `seeAlso`, for example to link to a Manifest that describes a related object. The URI of the document _MUST_ identify a single representation of the data in a particular format. For example, if the same data exists in JSON and XML, then separate resources should be added for each representation, with distinct `id` and `format` properties. @@ -1193,6 +1232,7 @@ The value _MUST_ be an array of JSON objects. Each item _MUST_ have the `id` and ##### service +{: #service} A service that the client might interact with directly and gain additional information or functionality for using the resource that has the `service` property, such as from an Image to the base URI of an associated [IIIF Image API][image-api] service. The service resource _SHOULD_ have additional information associated with it in order to allow the client to determine how to make appropriate use of it. Please see the [Service Registry][registry-services] document for the details of currently known service types. @@ -1247,6 +1287,7 @@ Implementations _SHOULD_ be prepared to recognize the `@id` and `@type` property } ``` ##### services +{: #services} A list of one or more service definitions on the top-most resource of the document, that are typically shared by more than one subsequent resource. This allows for these shared services to be collected together in a single place, rather than either having their information duplicated potentially many times throughout the document, or requiring a consuming client to traverse the entire document structure to find the information. The resource that the service applies to _MUST_ still have the `service` property, as described above, where the service resources have at least the `id` and `type` or `@id` and `@type` properties. This allows the client to know that the service applies to that resource. Usage of the `services` property is at the discretion of the publishing system. @@ -1280,6 +1321,7 @@ The value _MUST_ be an array of JSON objects. Each object _MUST_ be a service re } ``` ##### start +{: #start} A Canvas, or part of a Canvas, which the client _SHOULD_ show on initialization for the resource that has the `start` property. The reference to part of a Canvas is handled in the same way that Ranges reference parts of Canvases. This property allows the client to begin with the first Canvas that contains interesting content rather than requiring the user to manually navigate to find it. @@ -1312,6 +1354,7 @@ The value _MUST_ be a JSON object, which _MUST_ have the `id` and `type` propert } ``` ##### structures +{: #structures} The structure of an object represented as a Manifest can be described using a hierarchy of Ranges. Ranges can be used to describe the "table of contents" of the object or other structures that the user can interact with beyond the order given by the `items` property of the Manifest. The hierarchy is built by nesting the child Range resources in the `items` array of the higher level Range. The top level Ranges of these hierarchies are given in the `structures` property. @@ -1335,6 +1378,7 @@ The value _MUST_ be an array of JSON objects. Each item _MUST_ have the `id` and } ``` ##### summary +{: #summary} A short textual summary intended to be conveyed to the user when the `metadata` entries for the resource are not being displayed. This could be used as a brief description for item level search results, for small-screen environments, or as an alternative user interface when the `metadata` property is not currently being rendered. The `summary` property follows the same pattern as the `label` property described above. @@ -1355,6 +1399,7 @@ The value of the property _MUST_ be a JSON object, as described in the [language ``` ##### supplementary +{: #supplementary} A link from this Range to an Annotation Collection that includes the `supplementing` Annotations of content resources for the Range. Clients might use this to present additional content to the user from a different Canvas when interacting with the Range, or to jump to the next part of the Range within the same Canvas. For example, the Range might represent a newspaper article that spans non-sequential pages, and then uses the `supplementary` property to reference an Annotation Collection that consists of the Annotations that record the text, split into Annotation Pages per newspaper page. Alternatively, the Range might represent the parts of a manuscript that have been transcribed or translated, when there are other parts that have yet to be worked on. The Annotation Collection would be the Annotations that transcribe or translate, respectively. @@ -1371,6 +1416,7 @@ The value _MUST_ be a JSON object, which _MUST_ have the `id` and `type` propert ``` ##### thumbnail +{: #thumbnail} A content resource, such as a small image or short audio clip, that represents the resource that has the `thumbnail` property. A resource _MAY_ have multiple thumbnail resources that have the same or different `type` and `format`. @@ -1403,6 +1449,7 @@ The value _MUST_ be an array of JSON objects, each of which _MUST_ have the `id` ``` ##### timeMode +{: #timeMode} A mode associated with an Annotation that is to be applied to the rendering of any time-based media, or otherwise could be considered to have a duration, used as a body resource of that Annotation. Note that the association of `timeMode` with the Annotation means that different resources in the body cannot have different values. This specification defines the values specified in the table below. Others may be defined externally as an [extension][prezi30-ldce]. @@ -1425,12 +1472,14 @@ The value _MUST_ be a string. ##### transform +{: #transform} _Summary here_ The value of this property is an array of JSON objects, each of which is a Transform. ##### type +{: #type} The type or class of the resource. For classes defined for this specification, the value of `type` will be described in the sections below describing each individual class. @@ -1459,6 +1508,7 @@ The value _MUST_ be a string. ``` ##### viewingDirection +{: #viewingDirection} !!! Rewrite to be where is the navigation control to step to the next/ previous in the items of hte manifest @@ -1492,6 +1542,7 @@ The value _MUST_ be a string. ``` ##### width +{: #width} The width of the Canvas or external content resource. For content resources, the value is in pixels. For Canvases, the value does not have a unit. In combination with the height, it conveys an aspect ratio for the space in which content resources are located. @@ -1509,10 +1560,13 @@ The value _MUST_ be a positive integer. { "width": 1200 } ``` ##### x +{: #x} ##### y +{: #y} ##### z +{: #z} From d0deb0e4038ee9074042488cb714de5938913e4e Mon Sep 17 00:00:00 2001 From: Rob Sanderson Date: Tue, 18 Mar 2025 09:37:03 -0400 Subject: [PATCH 035/130] please build --- source/_includes/links.md | 2 +- source/image/1.1/index.html | 4 ++-- source/model/shared-canvas/1.0/index.html | 2 +- source/presentation/4.0/index.md | 13 ++++++------- source/registry/profiles/index.md | 2 +- 5 files changed, 11 insertions(+), 12 deletions(-) diff --git a/source/_includes/links.md b/source/_includes/links.md index 4e9560006..6c0e773e8 100644 --- a/source/_includes/links.md +++ b/source/_includes/links.md @@ -189,7 +189,7 @@ [org-open-annotation-multi]: http://www.openannotation.org/spec/core/multiplicity.html#Choice "Open Annotation: Multiplicity" [org-open-annotation-types]: http://www.openannotation.org/spec/core/core.html#BodyTargetType "Open Annotation: Body Target" [org-open-annotation]: http://www.openannotation.org/spec/core/ "Open Annotation" -[org-openarchives-rsync]: http://openarchives.org/rs/toc +[org-openarchives-rsync]: https://openarchives.org/rs/toc [org-rfc-2119]: https://tools.ietf.org/html/rfc2119 "RFC Keywords" [org-rfc-2617]: https://tools.ietf.org/html/rfc2617 "HTTP Authentication: Basic and Digest Access Authentication" [org-rfc-2818]: https://tools.ietf.org/html/rfc2818 "HTTP Over TLS" diff --git a/source/image/1.1/index.html b/source/image/1.1/index.html index 95de05280..72398da23 100644 --- a/source/image/1.1/index.html +++ b/source/image/1.1/index.html @@ -944,7 +944,7 @@

This API does not specify whether the image server will support authentication or what mechanism it might use. In the case of "401 Unauthorized" HTTP error response, the content of the WWW-Authenticate header will depend on the authentication mechanism supported by the server. If the server supports HTTP Basic or Digest authentication then the - header should follow RFC2617, for example: + header should follow RFC2617, for example:

WWW-Authenticate: Basic realm="Images" @@ -1002,7 +1002,7 @@

The URL syntax of this API relies upon slash (/) separators which MUST NOT be encoded. Clients MUST percent-encode special characters (the to-encode set below: percent and gen-delims of - RFC3986 except the colon) within the components + RFC3986 except the colon) within the components of requests. For example, any slashes within the identifier part of the URL MUST be percent-encoded. Encoding is necessary only for the identifier because other components will not include special characters.

diff --git a/source/model/shared-canvas/1.0/index.html b/source/model/shared-canvas/1.0/index.html index 5d4f0233a..2a07e7c8d 100644 --- a/source/model/shared-canvas/1.0/index.html +++ b/source/model/shared-canvas/1.0/index.html @@ -58,7 +58,7 @@

Abstract

parts thereof, via Open Annotations and the Annotations are grouped and ordered -in OAI-ORE +in OAI-ORE Aggregations.

diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index 8289b42e6..d5f1a0882 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -76,21 +76,20 @@ Mention cookbook ## Foundations -Simple model diagram - -Manifests and Containers briefly - +

+ Data Model
+

### Manifests -A Manifest is the primary unit of distribution of IIIF. It is a JSON document that provides a description of the structure and properties of a single item to be presented to the user, such as a title and other descriptive and linking information about the object and/or the intellectual work that it conveys. The scope of what constitutes an item, and thus its Manifest, is up to the publisher of that Manifest. The Manifest contains sufficient information for the client to initialize itself and begin to display something quickly to the user. +A Manifest is the primary unit of distribution of IIIF. Each Manifest usually describes how to present an object, such as a book, statue, music album or 3 dimensional scene. It is a JSON document that carries information needed for the client to present content to the user, such as a title and other descriptive information. The scope of what constitutes an object, and thus its Manifest, is up to the publisher of that Manifest. The Manifest contains sufficient information for the client to initialize itself and begin to display something quickly to the user. -The Manifest's `items` property is a list of _Containers_ of _Content Resources_ (images, 3D models, audio, etc). Client software loads the Manifest and presents the Content Resources to the user. The `items` property provides an order to the content. +The Manifest's `items` property is an ordered list of _Containers_ of _Content Resources_ (images, 3D models, audio, etc). Client software loads the Manifest and presents the Content Resources to the user in that order. Manifests have descriptive, technical and linking properties. The required properties of Manifests are `id`, `type`, `items` and `label`. Additional descriptive properties include `summary`, `metadata`, `rights`, `thumbnail`, `homepage` and `provider`. -[See Model Docs](manifest) +See the [Model Documentation](model/#manifest) for more information. ``` Manifest JSON diff --git a/source/registry/profiles/index.md b/source/registry/profiles/index.md index 8c38c1130..79c524561 100644 --- a/source/registry/profiles/index.md +++ b/source/registry/profiles/index.md @@ -68,7 +68,7 @@ This table summarizes the known profiles available, for use with the [Presentati | http://www.loc.gov/standards/alto | The URI for identifying [ALTO](https://www.loc.gov/standards/alto/) which is used for encoding OCR text. | | http://www.loc.gov/standards/marcxml | The URI for identifying [MarcXML](https://www.loc.gov/standards/marcxml/) metadata records. | | http://purl.org/dc/terms/ | The URI for identifying records that follow the [Dublin Core Metadata Initiative Metadata Terms](https://www.dublincore.org/specifications/dublin-core/dcmi-terms/) (NB: these are different from the legacy Dublin Core Metadata Element Set, Version 1.1, refered to as http://purl.org/dc/elements/1.1/). | -| http://www.europeana.eu/schemas/edm/ | The URI for identifying [EDM (Europeana Data Model)](https://pro.europeana.eu/page/edm-documentation) metadata records. | +| https://www.europeana.eu/schemas/edm/ | The URI for identifying [EDM (Europeana Data Model)](https://pro.europeana.eu/page/edm-documentation) metadata records. | {: .api-table} From 2dfc182183ca3fe49469e54f9ba023a775a6fdb7 Mon Sep 17 00:00:00 2001 From: Rob Sanderson Date: Tue, 18 Mar 2025 10:10:38 -0400 Subject: [PATCH 036/130] fix links --- source/presentation/4.0/index-draft.md | 2 +- source/presentation/4.0/index.md | 40 +++++++++----------------- source/presentation/4.0/model.md | 4 +-- 3 files changed, 17 insertions(+), 29 deletions(-) diff --git a/source/presentation/4.0/index-draft.md b/source/presentation/4.0/index-draft.md index bc498dde7..1e9aa7573 100644 --- a/source/presentation/4.0/index-draft.md +++ b/source/presentation/4.0/index-draft.md @@ -371,7 +371,7 @@ Content States are used for the following applications: 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](content-state-2) 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. +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 diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index d5f1a0882..b8c9b1220 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -100,59 +100,47 @@ Manifest JSON A Container is a frame of reference that allows the relative positioning of Content Resources, a concept borrowed from standards like PDF and HTML, or applications like Photoshop and PowerPoint, where an initially blank display surface has images, video, text and other content "painted" on to it. The frame is defined by a set of dimensions, with different types of Container having different dimensions. This specification defines three sub-classes of Container: Timeline (which only has a duration), Canvas (which has bounded height and width, and may have a duration), and Scene (which has infinite height, width and depth, and may have a duration). -And we can also put other things: -"supplementing" - - - The defined Container types are: #### Timeline A Container that represents a bounded temporal range, without any spatial coordinates. -* has continuous duration in seconds for all or part of its duration. -* Typically used for audio-only content +* A Timeline has continuous duration in seconds for all or part of its duration. +* A Timeline is typically used for audio-only content #### Canvas A Container that represents a bounded, two-dimensional space and has content resources associated with all or parts of it. It may also have a bounded temporal range in the same manner as a Timeline. -* has integer, unitless width and height -* has optional continuous duration in seconds -* Typically used for Image content, and with duration, for Video content. +* A Canvas has a width and height, given as unitless integers +* A Canvas has an optional continuous duration in seconds +* A Canvas is typically used for Image content, and with duration, for Video content. #### Scene A Container that represents a boundless three-dimensional space and has content resources positioned at locations within it. Rendering a Scene requires the use of Cameras and Lights. It may also have a bounded temporal range in the same manner as a Timeline. -* has continuous, unitless x,y,z cartesian coordinate space -* has optional continuous duration in seconds -* Typically used for 3D models, and can include audio, video and image content +* A Scene has a continuous, unitless x,y,z cartesian coordinate space +* A Scene has an optional continuous duration in seconds +* A Scene is typically used for 3D models, and can include audio, video and image content +```json +Manifest JSON with a Timeline, a Canvas and a Scene +``` ### Annotations -IIIF uses the concept of _Annotation_ to link resources together. Why is this a different sense from what I am used to? Because this: W3C go read that then come back. +IIIF uses the concept of _Annotation_ to link resources together from around the web. This specification uses a World Wide Web Consortium (W3C) standard for this called the [Web Annotation Data Model][org-web-anno]. This is a structured linking mechanism useful for making comments about Content Resources, but IIIF's primary use of it is to associate the images, audio and other Content Resources with their Containers for presentation. -BUT it can be used for notes in the margin, commentary and all those more usual senses of the word, too. It's just that we borrow that linking mechanism for the Content Resources, too. +Different uses of Annotation are distinguished through their `motivation` property. This specification defines a value for `motivation` called `painting` for associating Content Resources with Containers, which this specification calls a Painting Annotation. This is from the notion of painting onto a canvas, a metaphor borrowed from art and used for image-based digital applications, and expanded by IIIF into "painting" any Content Resource into a Container of any number of dimensions. -Annotations are primarily used to associate content resources with Containers. The same mechanism is used for the visible and/or audible resources as is used for transcriptions, commentary, tags and other content. This provides a single, unified method for aligning information, and provides a standards-based framework for distinguishing parts of resources and parts of Canvases. As Annotations can be added later, it promotes a distributed system in which publishers can align their content with the descriptions created by others. - -Now that we have this linking mechanism... PAINTING - -Painting Annotations are used to associate models, lights, cameras, and IIIF containers such as Canvases, with Scenes. They have a `type` of "Annotation", a `body` (being the resource to be added to the scene) and a `target` (being the scene or a position within the scene). They must have a `motivation` property with the value of "painting" to assert that the resource is being painted into the Scene, rather than the Annotation being a comment about the Scene. -Everything is an anno but these are special and core - -There are other important uses of annotation, they are not all painting annos - see later... +The same linking mechanism is also used in IIIF with other motivations for transcriptions, commentary, tags and other content. This provides a single, unified method for aligning content, and provides a standards-based framework for referencing parts of resources. As Annotations can be added later, it promotes a distributed system in which further content such as commentary can be aligned with the objects published on the web. ``` JSON of painting anno ``` -By the time you get here you are comfortable dropping the phrase "painting annotation" into casual conversation. - - ### Content Resources diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index 2480432f3..4bf507ee0 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -120,7 +120,7 @@ A Manifest _MUST_ have the following properties: [id](#id), [type](#type), [labe A Manfiest _SHOULD_ have the following properties: [metadata](#metadata), [summary](#summary), [provider](#provider), and [thumbnail](#thumbnail) -A Manifest _MAY_ have the following properties: [requiredStatement](#requiredStatement), [rights](#rights), [navDate](#navDate), [navPlace](#navPlace), [placeholder](#placeholder), [accompanyingContainer](#accompanyingContainer), [viewingDirection](#viewingDirection), [behavior](#behavior), [seeAlso](#seeAlso), [service](#service), [services](#services), [homepage](#homepage), [rendering](#rendering), [partOf](#partOf), [start](#start), [structures](#structures), and [annotations](#annotations). +A Manifest _MAY_ have the following properties: [requiredStatement](#requiredStatement), [rights](#rights), [navDate](#navDate), [navPlace](#navPlace), [placeholderContainer](#placeholderContainer), [accompanyingContainer](#accompanyingContainer), [viewingDirection](#viewingDirection), [behavior](#behavior), [seeAlso](#seeAlso), [service](#service), [services](#services), [homepage](#homepage), [rendering](#rendering), [partOf](#partOf), [start](#start), [structures](#structures), and [annotations](#annotations). Manifests _MUST_ be identified by a URI and it _MUST_ be an HTTP(S) URI, given in the `id` property. It _MUST_ be able to be dereferenced to retrieve the JSON description of the Manifest. @@ -1586,7 +1586,7 @@ 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. | -| `contentState` | An annotation with the motivation `contentState` has any valid IIIF Resource, or list of IIIF resources, or references to IIIF resources as its `target` property. The client either loads the resource(s) indicated by the Content State annotation `target`, or modifies the view of a currently loaded resource by applying the changes implied by the annotation target - for example, adding a new Light to a Scene where the Light is first introduced in the annotation `target`. The expected interaction depends on how the annotation is linked to the resource the client is currently rendering, or how the annotation is introduced to the client. The [Content State Protocol API 2.0](link) describes the ways in which a Content State may be conveyed into a Client or exported from a Client, e.g., as an initialization parameter, or as an exported "Share..." state. Other parts (...) of this specification describe how a Content State in the context of a `commenting` or other annotation modifies the Container when the user selects that annotation, such as changing the camera, lighting or even the models in a Scene as the user progresses though the steps of a narrative conveyed by `describing` annotations. | +| `contentState` | An annotation with the motivation `contentState` has any valid IIIF Resource, or list of IIIF resources, or references to IIIF resources as its `target` property. The client either loads the resource(s) indicated by the Content State annotation `target`, or modifies the view of a currently loaded resource by applying the changes implied by the annotation target - for example, adding a new Light to a Scene where the Light is first introduced in the annotation `target`. The expected interaction depends on how the annotation is linked to the resource the client is currently rendering, or how the annotation is introduced to the client. The _Content State Protocol API 2.0_ describes the ways in which a Content State may be conveyed into a Client or exported from a Client, e.g., as an initialization parameter, or as an exported "Share..." state. Other parts (...) of this specification describe how a Content State in the context of a `commenting` or other annotation modifies the Container when the user selects that annotation, such as changing the camera, lighting or even the models in a Scene as the user progresses though the steps of a narrative conveyed by `describing` annotations. | | `activating` | 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. It indicates that a user interaction will trigger a change in either the Container itself, 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. If the `body` contains IIIF resources, then the body is interpreted as a Content State, and when the user interacts with the IIIF resource provided by the `target`, the content state is applied to modify the Container. | // See notes on activating in index From e44ca1e9907037c8b6224f994aa3828eaf9b3194 Mon Sep 17 00:00:00 2001 From: Rob Sanderson Date: Tue, 18 Mar 2025 11:53:26 -0400 Subject: [PATCH 037/130] updates --- source/presentation/4.0/index.md | 69 +++++++++++++++++++++++--------- source/presentation/4.0/model.md | 2 + 2 files changed, 51 insertions(+), 20 deletions(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index b8c9b1220..7cda8acc9 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -87,9 +87,9 @@ A Manifest is the primary unit of distribution of IIIF. Each Manifest usually de The Manifest's `items` property is an ordered list of _Containers_ of _Content Resources_ (images, 3D models, audio, etc). Client software loads the Manifest and presents the Content Resources to the user in that order. -Manifests have descriptive, technical and linking properties. The required properties of Manifests are `id`, `type`, `items` and `label`. Additional descriptive properties include `summary`, `metadata`, `rights`, `thumbnail`, `homepage` and `provider`. +Manifests have descriptive, technical and linking properties. The required properties of Manifests are `id`, `type`, `items` and `label`. Other commonly used properties include `summary`, `metadata`, `rights`, `thumbnail`, `homepage` and `provider`. -See the [Model Documentation](model/#manifest) for more information. +(👀) [Model Documentation](model/#manifest) ``` Manifest JSON @@ -100,30 +100,30 @@ Manifest JSON A Container is a frame of reference that allows the relative positioning of Content Resources, a concept borrowed from standards like PDF and HTML, or applications like Photoshop and PowerPoint, where an initially blank display surface has images, video, text and other content "painted" on to it. The frame is defined by a set of dimensions, with different types of Container having different dimensions. This specification defines three sub-classes of Container: Timeline (which only has a duration), Canvas (which has bounded height and width, and may have a duration), and Scene (which has infinite height, width and depth, and may have a duration). +The required properties of all Containers are `id`, and `type`. Most Containers also have the `items` and `label` properties. Further properties are required for the different types of Container. + The defined Container types are: #### Timeline -A Container that represents a bounded temporal range, without any spatial coordinates. +A Container that represents a bounded temporal range, without any spatial coordinates. It is typically used for audio-only content. + +Timelines have an additional required property of `duration`, which gives the extent of the Timeline as a floating point number of seconds. -* A Timeline has continuous duration in seconds for all or part of its duration. -* A Timeline is typically used for audio-only content #### Canvas -A Container that represents a bounded, two-dimensional space and has content resources associated with all or parts of it. It may also have a bounded temporal range in the same manner as a Timeline. +A Container that represents a bounded, two-dimensional space, optionally with a bounded temporal range. Canvases are typically used for Image and Video content. -* A Canvas has a width and height, given as unitless integers -* A Canvas has an optional continuous duration in seconds -* A Canvas is typically used for Image content, and with duration, for Video content. +Canvases have two additional required properties: `height` and `width`, which give the spatial extent as unitless integers. Canvases may also have the `duration` property in the same manner as Timelines. #### Scene -A Container that represents a boundless three-dimensional space and has content resources positioned at locations within it. Rendering a Scene requires the use of Cameras and Lights. It may also have a bounded temporal range in the same manner as a Timeline. +A Container that represents a boundless three-dimensional space, optionally with a bounded temporal range. Scenes are typically used for rendering 3D models, and can additionally have Cameras and Lights. + +Scenes may also have the `duration` property in the same manner as Timelines. -* A Scene has a continuous, unitless x,y,z cartesian coordinate space -* A Scene has an optional continuous duration in seconds -* A Scene is typically used for 3D models, and can include audio, video and image content +(👀) [Model Documentation](model/#containers) ```json Manifest JSON with a Timeline, a Canvas and a Scene @@ -133,26 +133,55 @@ Manifest JSON with a Timeline, a Canvas and a Scene IIIF uses the concept of _Annotation_ to link resources together from around the web. This specification uses a World Wide Web Consortium (W3C) standard for this called the [Web Annotation Data Model][org-web-anno]. This is a structured linking mechanism useful for making comments about Content Resources, but IIIF's primary use of it is to associate the images, audio and other Content Resources with their Containers for presentation. -Different uses of Annotation are distinguished through their `motivation` property. This specification defines a value for `motivation` called `painting` for associating Content Resources with Containers, which this specification calls a Painting Annotation. This is from the notion of painting onto a canvas, a metaphor borrowed from art and used for image-based digital applications, and expanded by IIIF into "painting" any Content Resource into a Container of any number of dimensions. +Different uses of Annotation are distinguished through their `motivation` property. This specification defines a value for `motivation` called `painting` for associating Content Resources with Containers, which this specification calls a Painting Annotation. The verb "paint" is also used to refer to the associating of a Content Resource with a Container by a Painting Annotation. This is from the notion of painting onto a canvas, a metaphor borrowed from art and used for image-based digital applications, and expanded by IIIF into "painting" any Content Resource into a Container of any number of dimensions. The same linking mechanism is also used in IIIF with other motivations for transcriptions, commentary, tags and other content. This provides a single, unified method for aligning content, and provides a standards-based framework for referencing parts of resources. As Annotations can be added later, it promotes a distributed system in which further content such as commentary can be aligned with the objects published on the web. +The required properties of Annotations are `id`, `type`, `motivation`, and `target`. Most Annotations also have the `body` property. + +(👀) [Model Documentation](model/#annotations) + ``` -JSON of painting anno +JSON of painting anno - image to canvas ``` ### Content Resources +Content Resources are external web resources, including images, video, audio, 3D models, data, web pages or any other format. Typically these are the resources that will be "painted" onto a Container using a Painting Annotation. + +The required properties of Content Resources are `id` and `type`. Other commonly used properties include `format`, and `width`, `height` and `duration` as appropriate to the Content Resource format. + + +#### Containers as Content Resources + +Containers may also be treated as Content Resources and painted into other Containers. This allows rich composition of content, such as painting a Canvas bearing a Video into a Scene, or painting a 3D model along with its associated Lights into an encompassing Scene. + +#### Referencing Parts of Resources -There is stuff that we want to show - images, video, audio, 3D models etc +A common requirement is to refer to only part of a resource, either a Container or a Content Resource. There are two primary methods for achieving this: adding a fragment to the end of the URI for the resource, or creating a Specific Resource that describes the method for selecting the desired part. -Image, Sound, Video, Model, Text -(see model) +##### Fragments -And we can nest Containers so they are Content Resources too +Parts of resources on the Web are identified using URIs with a fragment component that both describes how to select the part from the resource, and, as a URI, also identifies it. In HTML this is frequently used to refer to part of the web page, called an anchor. The URI with the fragment can be used in place of the URI without the fragment in order to refer to this part. -SpecificResource +There are different types of fragment based on the format of the resource. The most commonly used type in IIIF is the W3C's Media Fragments specification, as it can define a temporal and 2D spatial region. +``` +comment annotation about part of the previous example's Canvas using #Fragment +``` + + +##### Specific Resource + +URIs with fragments are insufficient for complex referencing, like circular regions or arbitrary text spans, and do not support other useful features such as describing styling or transformation. The Web Annotation Data Model introduces a class called `SpecificResource` that represents the resource in a specific context or role, which IIIF uses to describe these more complex requirements. The Specific Resource then identifies the part, and the description of how to extract it is given as an instance of a `Selector` class associated with it. + +Several different classes of Selector are used in IIIF, including an alternative implementation of the fragment pattern called `FragmentSelector`. The fragment is given in the `value` property of the `FragmentSelector`, and the resource it should be applied to is given in `source`. + +The required properties of Specific Resources are `id`, `type`, and `source`. Other commonly used properties include `selector`, `transform`, and `scope`. + +``` +comment annotation about part of the previous example's Canvas using FragmentSelector +``` ## Presenting Content Resources - what you came here for diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index 4bf507ee0..d0b200ff2 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -129,6 +129,7 @@ The members of a Manifest are listed in the `items` property. The members of Man ### Container Classes +{: #containers} A Container is a frame of reference that allows the relative positioning of content. @@ -149,6 +150,7 @@ A Canvas is a Container that represents a particular rectangular 2 dimensional v A Scene is a Container that represents an infinitely large three-dimensional space, with an optional duration. As the Scene is infinite, it does not have `height`, `width` or `depth` properties. ### Annotation Classes +{: #annotations} The following set of classes are defined by the W3C's [Web Annotation Data Model][org-w3c-webanno] and Vocabulary, and are heavily used within the IIIF Data Model. Any necessary deviations from those specifications are explicitly noted and explained, such as the need for internationalization of labels. From 1b9645b8a56494391d64e1b0623516668a9efc36 Mon Sep 17 00:00:00 2001 From: tomcrane Date: Tue, 18 Mar 2025 13:32:37 -0400 Subject: [PATCH 038/130] remove draft, move all to p4 index --- .gitignore | 2 + source/presentation/4.0/index-draft.md | 1112 ------------------------ source/presentation/4.0/index.md | 1036 +++++++++++++++++++++- 3 files changed, 1036 insertions(+), 1114 deletions(-) delete mode 100644 source/presentation/4.0/index-draft.md diff --git a/.gitignore b/.gitignore index 2a8d1df61..ca4b5a24c 100644 --- a/.gitignore +++ b/.gitignore @@ -11,3 +11,5 @@ tmp/ iiifc-theme Gemfile.lock vendor + +.vscode diff --git a/source/presentation/4.0/index-draft.md b/source/presentation/4.0/index-draft.md deleted file mode 100644 index 1e9aa7573..000000000 --- a/source/presentation/4.0/index-draft.md +++ /dev/null @@ -1,1112 +0,0 @@ ---- -title: "Presentation API 4.0" -title_override: "IIIF Presentation API 4.0" -id: presentation-api -layout: spec -cssversion: 3 -tags: [specifications, presentation-api] -major: 4 -minor: 0 -patch: 0 -pre: -redirect_from: - - /presentation/index.html - - /presentation/4/index.html -editors: - - name: Michael Appleby - ORCID: https://orcid.org/0000-0002-1266-298X - institution: Yale University - - name: Tom Crane - ORCID: https://orcid.org/0000-0003-1881-243X - institution: Digirati - - name: Robert Sanderson - ORCID: https://orcid.org/0000-0003-4441-6852 - institution: J. Paul Getty Trust - - name: Dawn Childress - ORCID: - institution: UCLA - - name: Julie Winchester - ORCID: - institution: Duke University - - name: Jeff Mixter - ORCID: - institution: OCLC -hero: - image: '' ---- - -## Status of this Document -{:.no_toc} -__This Version:__ {{ page.major }}.{{ page.minor }}.{{ page.patch }}{% if page.pre != 'final' %}-{{ page.pre }}{% endif %} - -__Latest Stable Version:__ [{{ site.data.apis.presentation.latest.major }}.{{ site.data.apis.presentation.latest.minor }}.{{ site.data.apis.presentation.latest.patch }}][prezi-stable-version] - -__Previous Version:__ [3.0][prezi30] - -**Editors:** - -{% include api/editors.md editors=page.editors %} - -{% include copyright.md %} - ----- - - - -### Timeline - -A Timeline _MUST_ have a `duration` property that defines its length in seconds. The `duration` value must be a positive floating point number. - -An annotation that targets a Scene using a PointSelector without any temporal refinement implicitly targets the Scene's entire duration. - -A content resource may be annotated into a Scene for a period of time by use of a PointSelector that is temporally scoped by a [FragmentSelector](https://www.w3.org/TR/annotation-model/#fragment-selector). The FragmentSelector has a `value` property, the value of which follows the [media fragment syntax](https://www.w3.org/TR/media-frags/#naming-time) of `t=`. This annotation pattern uses the `refinedBy` property [defined by the W3C Web Annotation Data Model](https://www.w3.org/TR/annotation-model/#refinement-of-selection). - -```json -{ - "id": "https://example.org/iiif/3d/anno1", - "type": "Annotation", - "motivation": ["painting"], - "body": { - "id": "https://example.org/iiif/assets/model1.glb", - "type": "Model" - }, - "target": { - "type": "SpecificResource", - "source": [ - { - "id": "https://example.org/iiif/scene1", - "type": "Scene" - } - ], - "selector": [ - { - "type": "PointSelector", - "x": -1.0, - "y": -1.0, - "z": 3.0, - "refinedBy": { - "type": "FragmentSelector", - "value": "t=45,95" - } - } - ] - } -} -``` - -When using a URL fragment in place of a SpecificResource, the parameter `t` can be used to select the temporal region: - -```json -{ - "id": "https://example.org/iiif/3d/anno1", - "type": "Annotation", - "motivation": ["painting"], - "body": { - "id": "https://example.org/iiif/assets/model1.glb", - "type": "Model" - }, - "target": "https://example.org/iiif/scene1#xyz=-1,-1,3&t=45,95" -} -``` - -An Annotation may target a specific point in time using a PointSelector's `instant` property. The property's value must be a positive floating point number indicating a value in seconds that falls within the Scene's duration. - -```json -{ - "id": "https://example.org/iiif/3d/anno1", - "type": "Annotation", - "motivation": ["painting"], - "body": { - "id": "https://example.org/iiif/assets/model1.glb", - "type": "Model" - }, - "target": { - "type": "SpecificResource", - "source": [ - { - "id": "https://example.org/iiif/scene1", - "type": "Scene" - } - ], - "selector": [ - { - "type": "PointSelector", - "x": -1.0, - "y": -1.0, - "z": 3.0, - "instant": 45.0 - } - ] - } -} -``` - -The Annotation's [`timeMode` property](https://iiif.io/api/presentation/3.0/#timemode) can be used to indicate the desired behavior when the duration of the content resource that is not equal to the temporal region targeted by the annotation. - -It is an error to select a temporal region of a Scene that does not have a `duration`, or to select a temporal region that is not within the Scene's temporal extent. A Canvas or Scene with a `duration` may not be annotated as a content resource into a Scene that does not itself have a `duration`. - - - - -### Annotation - - -Annotations follow the [Web Annotation][org-w3c-webanno] data model and are used to associate models, lights, cameras, and IIIF containers such as Canvases, with Scenes. They have a `type` of "Annotation", a `body` (being the resource to be added to the scene) and a `target` (being the scene or a position within the scene). They must have a `motivation` property with the value of "painting" to assert that the resource is being painted into the Scene, rather than the Annotation being a comment about the Scene. - -A construct called a Selector is used to select a part of a resource, such as a point within a Scene. The use of a Selector necessitates the creation of a `SpecificResource` that groups together the resource being selected (the `source`) and the instance of the Selector. This SpecificResource can then be used as either the `body` or the `target` of the Annotation. - -All resources that can be added to a Scene have an implicit (e.g. Lights, Cameras) or explicit (e.g. Models, Scenes), local coordinate space. If a resource does not have an explicit coordinate space, then it is positioned at the origin of its coordinate space. In order to add a resource with its local coordinate space into a Scene with its own coordinate space, these spaces must be aligned. This done by aligning the origins of the two coordinate spaces. - -Annotations may use a type of Selector called a `PointSelector` to align the Annotation to a point within the Scene that is not the Scene's origin. PointSelectors have three spatial properties, `x`, `y` and `z` which give the value on that axis. They also have a temporal property `instant` which can be used if the Scene has a duration, which gives the temporal point in seconds from the start of the duration, the use of which is defined in the [section on Scenes with Durations](). - -Example Annotation that positions a model at a point within a Scene: - -```json -{ - "id": "https://example.org/iiif/3d/anno1", - "type": "Annotation", - "motivation": ["painting"], - "body": { - "id": "https://example.org/iiif/assets/model1.glb", - "type": "Model" - }, - "target": { - "type": "SpecificResource", - "source": [ - { - "id": "https://example.org/iiif/scene1", - "type": "Scene" - } - ], - "selector": [ - { - "type": "PointSelector", - "x": -1.0, - "y": 0.0, - "z": 1.0 - } - ] - } -} -``` - -Annotations may alternately use a type of Selector called a `WktSelector` to align the Annotation to a region with the Scene that is not the Scene's origin. WktSelectors have a single property, `value`, which is a string conforming to a WKT Linestring, LineStringZ, Polygon, or PolygonZ list of 2D or 3D coordinate points. Whether and how a region defined by a WktSelector may be translated to a single 2D or 3D coordinate point, for targeting or other purposes, is client-dependent. - -
-❓Does WKTSelector have a duration/instant property? -
- -Example Annotation that comments on a 3D polygon within a Scene: - -``` -Todo add example -``` - -#### URI Fragments - -(move up, include xywh) - -The point may instead be defined using a short-hand form of a URI Fragment at the end of the `id` of the Scene as the `target` of the Annotation. The name of the fragment parameter is `xyz` and its value is the x, y and z values separated by commas. Each value can be expressed as either an integer or a floating point number. - -The annotation above could be expressed as its fragment-based equivalent: - -```json -{ - "id": "https://example.org/iiif/3d/anno1", - "type": "Annotation", - "motivation": ["painting"], - "body": { - "id": "https://example.org/iiif/assets/model1.glb", - "type": "Model" - }, - "target": "https://example.org/iiif/scene1#xyz=-1,0,1" -} -``` - - - - - -"non-painting" - -"target" and "body" - - -### Annotation Page - -"Overlapping elements with a larger z-index cover those with a smaller one." -link to https://developer.mozilla.org/en-US/docs/Web/CSS/z-index - - -### Annotation Collection - -deal with this: -https://github.com/IIIF/api/pull/2304/files#diff-cc70f02818f6bed2b14dfbf8bf3206e0825047951c8e83ad56fc73e489f82ac4R1757 - -use totalItems? https://iiif.io/api/discovery/1.0/#totalitems - -### Manifest - -### Collection - -#### Paging - -### Range - -## Content State - -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 - -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: - -```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" - } - ] - } -} -``` - -As well as adding resources not present in the referred-to resource, the Content State can also remove parts of the referred-to resource from the user's view by applying the behavior `hidden` to them: - -```jsonc -{ - // What does this actually look like? I want to load bnf_chateauroux example but HIDE the illumination - // ... - "id": "https://iiif.io/api/cookbook/recipe/0036-composition-from-multiple-images/annotation/p0001-image", - "type": "Annotation", - "motivation": "painting", - "behavior": ["hidden"] -} -``` - -TODO: what is the processing algorithm for applying incoming `hidden` ? - -When a Content State annotation carries a Scene, a view might be initialized from a Content State that introduces an additional Camera that shows the user the point of interest. - - -### Modify the Container in a particular context - -The techniques in the previous example are also used within a published IIIF Manifest 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. The `scope` property indicates to the client that the Content State provides valuable context for displaying some aspect of a Scene or other Container. In the case of a commenting annotation, this means that the Content State should be loaded when the commenting annotation is selected or otherwise highlighted. - - -Consider a Scene with two models, and two `commenting` annotations: - -```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/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/anno7", - "type": "Annotation", - "motivation": ["commenting"], - "bodyValue": "Mandibular tooth", - "target": { - // SpecificResource with PointSelector - } - }, - { - "id": "https://example.org/iiif/3d/anno5", - "type": "Annotation", - "motivation": ["commenting"], - "bodyValue": "Right pterygoid hamulus", - "target": { - // SpecificResource with PointSelector - } - } - ] - } - ] -} -``` - -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. It may be useful to light the Scene differently in different contexts. - -In the same way an incoming Content State can modify a Scene as it initializes the client, so can a Content State attached to each (non-`painting`) annotation target modify the Scene as the user moves between different annotations. - -The `scope` property of an annotation `target` provides _contextual_ Content State - the viewer should modify the Scene by applying the Content State carried by the `scope` property _only when the user is in the context of that annotation_. - -Taking the first commenting annotation from the above example and adding a `scope` property, whose value is an annotation with the motivation `contentState`, we can introduce a new Camera specifically for this particular annotation, so that when the user selects this comment, the client will switch the view to this camera. This example also changes the background color of the Scene: - -```jsonc -{ - "id": "https://example.org/iiif/3d/anno7", - "type": "Annotation", - "motivation": ["commenting"], - "bodyValue": "Mandibular tooth", - "target": { - - // SpecificResource with PointSelector - // "type": "SpecificResource", - // "source": ... the Scene... - // "selector": ... a point ... - - "scope": { // a modification to the Scene, only in the context of this annotation - - "id": "https://example.org/iiif/3d/anno4", - "type": "Annotation", - "motivation": ["contentState"], - "target": { - "id": "https://example.org/iiif/scene1/page/p1/1", - "type": "Scene", - "backgroundColor": "yellow", - "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.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 - } - ] - } - } - ] - } - } - } -} -``` - -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 `scope` 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 parts of the Scene for a step - - introducing additional models at a particular step - - (and many more!) - -Use of `scope` is permitted in annotations on any Container type, not just Scenes. For example, a 2D narrative around a Canvas might show or hide different `painting` annotations at each step. - -#### The `sequence` behavior - -// Is this right? Language... - -While all AnnotationPage `items` are inherently ordered, an Annotation Page with the behavior `sequence` is explicitly a narrative, and clients should prevent (dissuade) users from jumping about. The presence of `sequence` affects the way a client should interpret the `reset` property described below. - -### Content States on Manifests - -When an annotation with the motivation `contentState` is provided via the `annotations` property of a Manifest, rather than contextually via `scope`, it is assumed to be generally available for selection by the user at any time. A client may present such as annotations as a menu of views, allowing arbitrary jumping into any Scene (or Canvas or Timeline) from any other point. - -// Is there some overlap here with Range? - -### Processing Content States in Scopes: reset - -// This may not be what we have discussed... - -When a Content State is applied to a Container such as a Scene, it is assumed to be a "diff" - for example if 3 cameras and 4 lights are already present in the Scene, and a Content State asserts a single new Camera, the default behavior is to add this fourth Camera to the Scene and leave the existing resources as they are. - -The client should reset the Container to its original state before applying the diff operation. However, for narratives that cumulatively build a Scene this may lead to excessively verbose Manifests. When moving through the items of an Annotation page with the behavior `sequence`, the Container is not reset and the diff is cumulative; modifications from one `scope` persist into the next. If this behavior is not wanted, the `reset` property of the content state annotation should be set to `true`: - -```json -{ - "type": "Annotation", - "motivation": ["contentState"], - "reset": true -} -``` - -Before applying the content state to the Scene, the client should reset the Scene to its original state as provided by the Manifest. - -// I am assuming reset is always true except in `sequence` - otherwise it's completely unpredictable!! or is it... arbitrary navigation, state provided by initialization content states, etc... - -### Contribute additional information permanently - -Rerum inbox scenario - should be covered in CS2 protocol - -### activating - animation and interactions - -Annotations with the motivation `activating` are referred to as _activating_ annotations. - -There are two uses of `activating` annotations: - -#### Triggering a content state - -An activating annotation links a painting annotation to a content state. When a user interacts with the painting annotation - whether through clicking it, tapping it, or other client-specific behaviors - the linked content state should be processed to modify the Scene or other Container, as in the previous examples. The painting annotation is the target of the activating annotation, and the content state is the body value. Only one content state may be specified in the body array, but the body array may include a `TextualBody` to provide a label for the interaction. The pattern is the same as for the `linking` motivation, but rather than the client opening a new browser window on the resource specified in the `body`, it applies the modification provided by the Content State. - -The activating annotation is provided in a Container's `annotations` property. In this (contrived for brevity) example, if the user clicks the mandible model, the Scene background changes color: - -```jsonc -{ - "id": "https://example.org/iiif/3d/activating.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/scene-with-activation", - "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/painting-anno-for-mandible", - "type": "Annotation", - "motivation": ["painting"], - "body": { - "id": "https://raw.githubusercontent.com/IIIF/3d/main/assets/whale/whale_mandible.glb", - "type": "Model" - }, - "target": { - // SpecificResource with PointSelector - } - } - ], - "annotations": [ - { - "id": "https://example.org/iiif/scene1/page/activators", - "type": "AnnotationPage", - "items": [ - { - "id": "https://example.org/iiif/3d/anno2", - "type": "Annotation", - "motivation": ["activating"], - "body": [ - { - "type": "TextualBody", - "value": "A label for the activation may be provided as a TextualBody" - }, - { - // A body where the type is a IIIF Resource (eg Scene) is the Content State to apply - "id": "https://example.org/iiif/scene1/scene-with-activation", - "type": "Scene", - "backgroundColor": "#FF99AA" - } - ], - "target": { - "id": "https://example.org/iiif/3d/painting-anno-for-mandible", - "type": "Annotation" - } - } - ] - } - ] - } - ] - } - ] -} -``` - -// Can you put activating annotations in `manifest.annotations`? They would work there too, you have all the information. - - - -#### 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. - -This pattern is similar to the above, except that: - - - There is no Content State in the `body`, but there _MUST_ be a TextualBody to label the interaction. (?? must?) - - The `target` selects a _named animation_ in the model. The `target` MUST be a SpecificResource, where the `source` is the painting annotation that paints the model, and the `selector` is of type `AnimationSelector` with the `value` being a string that corresponds to the animation in the model. - - The format of the `value` string is implementation-specific, and will depend on how different 3D formats support addressing of animations within models. The same model can be painted multiple times into the scene, and you might want to activate only one model's animation, thus we need to refer to the annotation that paints the model, not the model directly. - - - -```jsonc -{ - "id": "https://example.org/iiif/3d/activating-animation.json", - "type": "Manifest", - "label": { "en": ["Music Box with lid that opens as an internal animation"] }, - "items": [ - { - "id": "https://example.org/iiif/scene1/scene-with-activation-animation", - "type": "Scene", - "label": { "en": ["A Scene Containing a Music Box"] }, - "items": [ - { - "id": "https://example.org/iiif/scene-with-activation-animation/page/p1/1", - "type": "AnnotationPage", - "items": [ - { - "id": "https://example.org/iiif/3d/painting-anno-for-music-box", - "type": "Annotation", - "motivation": ["painting"], - "body": { - "id": "https://raw.githubusercontent.com/IIIF/3d/main/assets/music-box.glb", - "type": "Model" - }, - "target": { - // SpecificResource with PointSelector - } - } - ], - "annotations": [ - { - "id": "https://example.org/iiif/scene1/page/activators", - "type": "AnnotationPage", - "items": [ - { - "id": "https://example.org/iiif/3d/anno2", - "type": "Annotation", - "motivation": ["activating"], - "body": [ - { - "type": "TextualBody", - "value": "Click the box to open the lid" - } - ], - "target": [ - { - "type": "SpecificResource", - "source": "https://example.org/iiif/3d/painting-anno-for-music-box", - "selector": [ - { - "type": "AnimationSelector", - "value": "open-the-lid" - } - ] - } - ] - } - ] - } - ] - } - ] - } - ] -} -``` - -// TODO - -activating to apply a content state and activating to trigger a named animation - use of body and target... what if we want to click a painting anno to trigger the animation? -Can we ADD that to the target, alongside the SpecificResource with the AnimationSelector? - -if the `target` is an AnimationSelector, then the `body` can ONLY be TextualBody (or list of TextualBody)? - -There is a more general rule here! - -### reset - -See above... - -"diff", "original state" etc -behavior for "force-order"? -behavior: sequence - -## Selectors - -preamble - cover all the use cases - -### SpecificResource - -(This heading should be more descriptive) - -fragments/segments/parts of resources -SvgSelector -xywh - - -### PointSelector - - -## Scene-Specific Resources - -### 3D considerations / principles - -"models" (content resources in 3D) -"local coordinate spaces" - -### Camera - -A Camera provides a view of a region of the Scene's space from a particular position within the Scene; the client constructs a viewport into the Scene and uses the view of one or more Cameras to render that region. The size and aspect ratio of the viewport is client and device dependent. - -This specification defines two types of Camera: - -| Class | Description | -| ------------------- | ------------ | -| `PerspectiveCamera` | `PerspectiveCamera` mimics the way the human eye sees, in that objects further from the camera are smaller | -| `OrthographicCamera` | `OrthographicCamera` removes visual perspective, resulting in object size remaining constant regardless of its distance from the camera | - -Cameras are positioned within the Scene facing in a specified direction. Both position and direction are defined through the Annotation which adds the Camera to the Scene, described below in the sections on [Painting Annotations][], [Transforms][], and [Relative Rotation][]. If either the position or direction is not specified, then the position defaults to the origin, and facing direction defaults to pointing along the z axis towards negative infinity. The camera's up direction by default points along the y axis towards positive infinity, but this may be modified by transforms. - -The region of the Scene's space that is observable by the camera is bounded by two planes orthogonal to the direction the camera is facing, given in the `near` and `far` properties, and a vertical projection angle that provides the top and bottom planes of the region. - -The `near` property defines the minimum distance from the camera at which something in the space must exist in order to be viewed by the camera. Anything nearer to the camera than this distance will not be viewed. Conversely, the `far` property defines a maximum distance from the camera at which something in the space must exist in order to be viewed by the camera. Anything further away will not be viewed. - -For PerspectiveCameras, the vertical projection angle is specificed using the full angular extent in degrees from the top plane to the bottom plane using the `fieldOfView` property. The `fieldOfView` angle MUST be greater than 0 and less than 180. For OrthographicCameras, the vertical projection is always parallel and thus not defined. - -If any of these properties are not specified explicitly, they default to the choice of the client implementation. - -drawing of a geometrical frustrum truncated by near and far distances - - -The first Camera defined and not hidden in a Scene is the default Camera used to display Scene contents. If the Scene does not have any Cameras defined within it, then the client MUST provide a default Camera. The type, properties and position of this default camera are client-dependent. - -```json -{ - "id": "https://example.org/iiif/camera/1", - "type": "PerspectiveCamera", - "near": 1.0, - "far": 100.0, - "fieldOfView": 45.0 -} -``` - - - -### Light - -One or more Lights MUST be present within the Scene in order to have objects within it be visible to the Cameras. - -This specification defines four types of Light: - -| Class | Description | -| ----- | ------------ | -| `AmbientLight` | AmbientLight evenly illuminates all objects in the scene, and does not have a direction or position. | -| `DirectionalLight` | DirectionalLight emits in a specific direction as if it is infinitely far away and the rays produced from it are all parallel. It does not have a specific position. | -| `PointLight` | PointLight emits from a single point within the scene in all directions. | -| `SpotLight` | SpotLight emits a cone of light from a single point in a given direction. | - -Lights defined in this specification have a `color` and an `intensity`. The color is given as an RGB value, such as "#FFFFFF" for white. The intensity is the strength or brightness of the light, and described using a `Value` construct. - -SpotLight has an additional property of `angle`, specified in degrees, which is the angle from the direction that the Light is facing to the outside extent of the cone. - -diagram of cone geometry showing how the angle of the cone is defined - -Lights that require a position and/or direction have these through the Annotation which associates them with the Scene, described below in the sections on [Painting Annotations][] and [Transforms][]. If a Light does not have an explicit direction, then the default is in the negative y direction (downwards). If a Light does not have an explicit position in the coordinate space, then the default is at the origin. - -This specification does not define other aspects of Lights, such as the rate of decay of the intensity of the light over a distance, the maximum range of the light, or the penumbra of a cone. Implementation of these aspects is client-dependent. - -If there are no Lights present within the Scene, then the viewer MUST add at least one Light. The types and properties of Lights added in this way are client-dependent. - -```json -{ - "id": "https://example.org/iiif/light/1", - "type": "AmbientLight", - "color": "#FFFFFF", - "intensity": {"type": "Value", "value": 0.6, "unit": "relativeUnit"} -} -``` - - - -### Transforms - -The Annotation with a Selector on the target can paint a resource at a point other than the origin, however it will be at its initial scale and rotation, which may not be appropriate for the scene that is being constructed. - -This specification defines a new class of manipulations for SpecificResources called a `Transform`, with three specific sub-classes. Each Transform has three properties, `x`, `y` and `z` which determine how the Transform affects that axis in the local coordinate space. - - -| Class | Description | -| --------------- | ------------ | -| ScaleTransform | A ScaleTransform applies a multiplier to one or more axes in the local coordinate space. A point that was at 3.5, after applying a ScaleTransform of 2.0 would then be at 7.0. If an axis value is not specified, then it is not changed, resulting in a default of 1.0 | -| RotateTransform | A RotateTransform rotates the local coordinate space around the given axis in a counter-clockwise direction around the axis itself (e.g. around a pivot point of 0 on the axis). A point that was at x=1,y=1 and was rotated 90 degrees around the x axis would be at x=1,y=0,z=1. If an axis value is not specified, then it is not changed, resulting in a default of 0.0 | -| TranslateTransform | A TranslateTransform moves all of the objects in the local coordinate space the given distance along the axis. A point that was at x=1.0, after applying a TranslateTransform of x=1.0 would be at x=2.0. If an axis value is not specified then it is not changed, resulting in a default of 0.0 | - -Transforms are added to a SpecificResource using the `transform` property. The value of the property is an array, which determines the order in which the transforms are to be applied. The resulting state of the first transform is the input state for the second transform, and so on. Different orders of the same set of transforms can have different results, so attention must be paid when creating the array and when processing it. - -The point around which RotateTransform rotates the space is the origin. This "pivot point" cannot be changed directly, but instead a TranslateTransform can be used to move the desired pivot point to the be at the origin, then the RotateTransform applied. - -Transforms are only used in the Presentation API when the SpecificResource is the `body` of the Annotation, and are applied before the resource is painted into the scene at the point given in the `target`. - -```json -{ - "type": "SpecificResource", - "source": { - "id": "https://example.org/iiif/assets/model1.glb", - "type": "Model" - }, - "transform": [ - { - "type": "RotateTransform", - "x": 0.0, - "y": 180.0, - "z": 0.0 - }, - { - "type": "TranslateTransform", - "x": 1.0, - "y": 0.0, - "z": 0.0 - } - ] -} -``` - - -#### Relative Rotation - -It is useful to be able to rotate a light or camera resource such that it is facing another object or point in the Scene, rather than calculating the angles within the Scene's coordinate space. This is accomplished with a property called `lookAt`, valid on DirectionalLight, SpotLight, and all Cameras. The value of the property is either a PointSelector, a WktSelector, the URI of an Annotation which paints something into the current Scene, or a Specific Resource with a selector identifying a point or region in an arbitrary container. - -If the value is a PointSelector, then the light or camera resource is rotated around the x and y axes such that it is facing the given point. If the value is a WktSelector, then the resource should be rotated to face the given region. If the value is an Annotation which targets a point via a PointSelector, URI fragment or other mechanism, then the resource should be rotated to face that point. If the value is a Specific Resource, the source container for the Specific Resource must be painted into the current Scene, and the Specific Resource selector should identify a point or region in the source container. In this case, the light or camera resource should be rotated to face the point or region in the source container where the point or region is located within the current Scene's coordinate space. This allows light or camera resources to face a specific 2D point on a Canvas painted into a 3D scene. - -This rotation happens after the resource has been added to the Scene, and thus after any transforms have taken place in the local coordinate space. - -```json -"lookAt": { - "type": "PointSelector", - "x": 3, - "y": 0, - "z": -10 -} -``` - - -#### Excluding - -Just as a Scene may contain multiple Annotations with model, light, and camera resources, a single 3D model file may contain a collection of 3D resources, including model geometry, assemblages of lights, and/or multiple cameras, with some of these potentially manipulated by animations. When painting Scenes or models that themselves may contain groups of resources within a single Scene, it may not always be appropriate to include all possible cameras, lights, or other resources, and it may be desirable to opt not to import some of these resources. This is accomplished through the Annotation property `exclude`, which prevents the import of audio, lights, cameras, or animations from a particular Scene or model prior to the Annotation being painted into a Scene. When `exclude` is used, the excluded resource type should not be loaded into the Scene, and it is not possible to reactivate or turn on these excluded resources after loading. - -Painting a Scene into another while excluding import of several types of resources: -```json -{ - "id": "https://example.org/iiif/3d/anno1", - "type": "Annotation", - "motivation": ["painting"], - "exclude": ["Audio", "Lights", "Cameras", "Animations"], - "body": { - "id": "https://example.org/iiif/scene1", - "type": "Scene" - }, - "target": "https://example.org/iiif/scene2" -} -``` - - - -## Advanced Association Features - -(This needs to be sprinkled throughout above - especially as SpecificResource must be introduced early for 3D) - -### Nesting - -A Canvas can be painted into a Scene as an Annotation, but the 2D nature of Canvases requires special consideration due to important differences between Canvases and Scenes. A Canvas describes a bounded 2D space with finite `height` and `width` measured in pixels with a pixel origin at the top-left corner of the Canvas, while Scenes describe a boundless 3D space with x, y, and z axes of arbitrary coordinate units and a coordinate origin at the center of the space. It is important to note that in many cases the pixel scale used by a Canvas or a 2D image content resource will not be in proportion to the desired 3D coordinate unit scale in a Scene. - -When a Canvas is painted as an Annotation targeting a Scene, the top-left corner of the Canvas (the pixel origin) is aligned with the 3D coordinate origin of the Scene. The top edge of the Canvas is aligned with (e.g., is colinear to) the positive x axis extending from the coordinate origin. The left edge of the Canvas is aligned with (e.g., is colinear to) the negative y axis extending from the coordinate origin. The Canvas is scaled to the Scene such that the pixel dimensions correspond to 3D coordinate units - a Canvas 200 pixels wide and 400 pixels high will extend 200 coordinate units across the x axis and 400 coordinate units across the y axis. Please note: direction terms "top", "bottom", "right", and "left" used in this section refer to the frame of reference of the Canvas itself, not the Scene into which the Canvas is painted. - -A Canvas in a Scene has a specific forward face and a backward face. By default, the forward face of a Canvas should point in the direction of the positive z axis. If the property `backgroundColor` is used, this color should be used for the backward face of the Canvas. Otherwise, a reverse view of the forward face of the Canvas should be visible on the backward face. - -
- To Do: Add an image demonstrating default Canvas placement in Scene -
- -A `PointSelector` can be used to modify the point at which the Canvas will be painted, by establishing a new point to align with the top-left corner of the Canvas instead of the Scene coordinate origin. Transforms can also be used to modify Canvas rotation, scale, or translation. - -It may be desirable to exercise greater control over how the Canvas is painted into the Scene by selecting the coordinate points in the Scene that should correspond to each corner of the Canvas. This provides fine-grained manipulation of Canvas placement and/or scale, and for optionally introducing Canvas distortion or skew. Annotations may use a WktSelector to select different points in the Scene to align with the top-left, bottom-left, bottom-right, and top-right corners of the Canvas. In this case, the four Scene coordinates should be listed beginning with the coordinate corresponding to the top-left corner of the Canvas, and should proceed in a counter-clockwise winding order around the Canvas, with coordinates corresponding to bottom-left, bottom-right, and top-right corners in order respectively. The use of WktSelector for this purpose overrides any use of Transforms on the Canvas Annotation. - -Example placing top-left at (0, 1, 0); bottom-left at (0, 0, 0); bottom-right at (1, 0, 0); and top-right at (1, 1, 0): -```json -"selector": [ - { - "type": "WktSelector", - "value": "POLYGONZ((0 1 0, 0 0 0, 1 0 0, 1 1 0))" - } -] -``` - -When a Scene is nested into another Scene, the `backgroundColor` of the Scene to be nested should be ignored as it is non-sensible to import. All Annotations painted into the Scene to be nested will be painted into the Scene into which content is being nested, including Light or Camera resources. If the Scene to be nested has one or more Camera Annotations while the Scene into which content is being nested does not, the first Camera Annotation from the nested Scene will become the default Camera for the overall Scene. - -### Embedded Content - -e.g., painting TextualBody on Canvas - -Todo: This is mostly copy-pasted from properties, is it needed here? -It is important to be able to position the textual body of an annotation within the Container's space that the annotation also targets. For example, a description of part of an image in a Canvas should be positioned such that it does not obscure the image region itself and labels to be displayed as part of a Scene should not be rendered such that the text is hidden by the three dimensional geometry of the model. The positioning of the textual body in a container is accomplished through the `position` property, which has as a value a Specific Resource identifying the targeted container as the source and a selector defining how the textual body should be positioned in the targeted container. If this property is not supplied, then the client should do its best to ensure the content is visible to the user. - -### Comment Annotations - -(move to Annotation section) - - -### Choice of Alternative Resources - -(move to Annotation section) - - -### Non Rectangular Segments - -SvgSelector - move to SpecificResource too ^^ - - -### Style - -Move to SpecificResource - - -### Rotation - - -### Hotspot Linking and Activation - -Move to SpecificResource - - - -## Conveying Physical Dimensions - -(why is this important!?) - -(move the props to vocab doc) - -### spatialScale - -### temporalScale - - -``` -{ - "spatialScale": { - "factor": 22.0, - "units": "m" - }, - - - // this would be rarely used - "temporalScale": { - "factor": 0.00001 - } - -} -``` - -`factor` Required A floating point ratio. -`units` Required A real-world measuring unit. Always seconds for temporalScale. Possible values for spatialScale include: "m", "ft". (is that it?) - -For a Canvas, it's the physical "size" of each cartesian integer unit. -For a Scene, it's the physical size of the unit vector. -For a timeline it's the ratio of time in the recording to time in the real world. - - -(define props in the Vocabulary doc) - - -## HTTP Requests and Responses - -### URI Recommendations - -### Requests - -### Responses - -### Authentication - - -## Accessibility - -(new section) - -`provides` - - -## Appendices - -### Summary of Property Requirements - -### Example Manifest Response - -### Versioning - -### Acknowledgements - -### Change Log - -"Exclude Audio" diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index 7cda8acc9..8e4665f2d 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -248,6 +248,358 @@ A simple example painting one Scene into another: +A content resource may be annotated into a Scene for a period of time by use of a PointSelector that is temporally scoped by a [FragmentSelector](https://www.w3.org/TR/annotation-model/#fragment-selector). The FragmentSelector has a `value` property, the value of which follows the [media fragment syntax](https://www.w3.org/TR/media-frags/#naming-time) of `t=`. This annotation pattern uses the `refinedBy` property [defined by the W3C Web Annotation Data Model](https://www.w3.org/TR/annotation-model/#refinement-of-selection). + +```json +{ + "id": "https://example.org/iiif/3d/anno1", + "type": "Annotation", + "motivation": ["painting"], + "body": { + "id": "https://example.org/iiif/assets/model1.glb", + "type": "Model" + }, + "target": { + "type": "SpecificResource", + "source": [ + { + "id": "https://example.org/iiif/scene1", + "type": "Scene" + } + ], + "selector": [ + { + "type": "PointSelector", + "x": -1.0, + "y": -1.0, + "z": 3.0, + "refinedBy": { + "type": "FragmentSelector", + "value": "t=45,95" + } + } + ] + } +} +``` + +When using a URL fragment in place of a SpecificResource, the parameter `t` can be used to select the temporal region: + +```json +{ + "id": "https://example.org/iiif/3d/anno1", + "type": "Annotation", + "motivation": ["painting"], + "body": { + "id": "https://example.org/iiif/assets/model1.glb", + "type": "Model" + }, + "target": "https://example.org/iiif/scene1#xyz=-1,-1,3&t=45,95" +} +``` + +An Annotation may target a specific point in time using a PointSelector's `instant` property. The property's value must be a positive floating point number indicating a value in seconds that falls within the Scene's duration. + +```json +{ + "id": "https://example.org/iiif/3d/anno1", + "type": "Annotation", + "motivation": ["painting"], + "body": { + "id": "https://example.org/iiif/assets/model1.glb", + "type": "Model" + }, + "target": { + "type": "SpecificResource", + "source": [ + { + "id": "https://example.org/iiif/scene1", + "type": "Scene" + } + ], + "selector": [ + { + "type": "PointSelector", + "x": -1.0, + "y": -1.0, + "z": 3.0, + "instant": 45.0 + } + ] + } +} +``` + +The Annotation's [`timeMode` property](https://iiif.io/api/presentation/3.0/#timemode) can be used to indicate the desired behavior when the duration of the content resource that is not equal to the temporal region targeted by the annotation. + +It is an error to select a temporal region of a Scene that does not have a `duration`, or to select a temporal region that is not within the Scene's temporal extent. A Canvas or Scene with a `duration` may not be annotated as a content resource into a Scene that does not itself have a `duration`. + + +An annotation that targets a Scene using a PointSelector without any temporal refinement implicitly targets the Scene's entire duration. + + +All resources that can be added to a Scene have an implicit (e.g. Lights, Cameras) or explicit (e.g. Models, Scenes), local coordinate space. If a resource does not have an explicit coordinate space, then it is positioned at the origin of its coordinate space. In order to add a resource with its local coordinate space into a Scene with its own coordinate space, these spaces must be aligned. This done by aligning the origins of the two coordinate spaces. + +Annotations may use a type of Selector called a `PointSelector` to align the Annotation to a point within the Scene that is not the Scene's origin. PointSelectors have three spatial properties, `x`, `y` and `z` which give the value on that axis. They also have a temporal property `instant` which can be used if the Scene has a duration, which gives the temporal point in seconds from the start of the duration, the use of which is defined in the [section on Scenes with Durations](). + +Example Annotation that positions a model at a point within a Scene: + +```json +{ + "id": "https://example.org/iiif/3d/anno1", + "type": "Annotation", + "motivation": ["painting"], + "body": { + "id": "https://example.org/iiif/assets/model1.glb", + "type": "Model" + }, + "target": { + "type": "SpecificResource", + "source": [ + { + "id": "https://example.org/iiif/scene1", + "type": "Scene" + } + ], + "selector": [ + { + "type": "PointSelector", + "x": -1.0, + "y": 0.0, + "z": 1.0 + } + ] + } +} +``` + +Annotations may alternately use a type of Selector called a `WktSelector` to align the Annotation to a region with the Scene that is not the Scene's origin. WktSelectors have a single property, `value`, which is a string conforming to a WKT Linestring, LineStringZ, Polygon, or PolygonZ list of 2D or 3D coordinate points. Whether and how a region defined by a WktSelector may be translated to a single 2D or 3D coordinate point, for targeting or other purposes, is client-dependent. + +
+❓Does WKTSelector have a duration/instant property? +
+ +Example Annotation that comments on a 3D polygon within a Scene: + +``` +Todo add example +``` + + + +## Scene-Specific Resources + +### 3D considerations / principles + +"models" (content resources in 3D) +"local coordinate spaces" + +### Camera + +A Camera provides a view of a region of the Scene's space from a particular position within the Scene; the client constructs a viewport into the Scene and uses the view of one or more Cameras to render that region. The size and aspect ratio of the viewport is client and device dependent. + +This specification defines two types of Camera: + +| Class | Description | +| ------------------- | ------------ | +| `PerspectiveCamera` | `PerspectiveCamera` mimics the way the human eye sees, in that objects further from the camera are smaller | +| `OrthographicCamera` | `OrthographicCamera` removes visual perspective, resulting in object size remaining constant regardless of its distance from the camera | + +Cameras are positioned within the Scene facing in a specified direction. Both position and direction are defined through the Annotation which adds the Camera to the Scene, described below in the sections on [Painting Annotations][], [Transforms][], and [Relative Rotation][]. If either the position or direction is not specified, then the position defaults to the origin, and facing direction defaults to pointing along the z axis towards negative infinity. The camera's up direction by default points along the y axis towards positive infinity, but this may be modified by transforms. + +The region of the Scene's space that is observable by the camera is bounded by two planes orthogonal to the direction the camera is facing, given in the `near` and `far` properties, and a vertical projection angle that provides the top and bottom planes of the region. + +The `near` property defines the minimum distance from the camera at which something in the space must exist in order to be viewed by the camera. Anything nearer to the camera than this distance will not be viewed. Conversely, the `far` property defines a maximum distance from the camera at which something in the space must exist in order to be viewed by the camera. Anything further away will not be viewed. + +For PerspectiveCameras, the vertical projection angle is specificed using the full angular extent in degrees from the top plane to the bottom plane using the `fieldOfView` property. The `fieldOfView` angle MUST be greater than 0 and less than 180. For OrthographicCameras, the vertical projection is always parallel and thus not defined. + +If any of these properties are not specified explicitly, they default to the choice of the client implementation. + +drawing of a geometrical frustrum truncated by near and far distances + + +The first Camera defined and not hidden in a Scene is the default Camera used to display Scene contents. If the Scene does not have any Cameras defined within it, then the client MUST provide a default Camera. The type, properties and position of this default camera are client-dependent. + +```json +{ + "id": "https://example.org/iiif/camera/1", + "type": "PerspectiveCamera", + "near": 1.0, + "far": 100.0, + "fieldOfView": 45.0 +} +``` + + + +### Light + +One or more Lights MUST be present within the Scene in order to have objects within it be visible to the Cameras. + +This specification defines four types of Light: + +| Class | Description | +| ----- | ------------ | +| `AmbientLight` | AmbientLight evenly illuminates all objects in the scene, and does not have a direction or position. | +| `DirectionalLight` | DirectionalLight emits in a specific direction as if it is infinitely far away and the rays produced from it are all parallel. It does not have a specific position. | +| `PointLight` | PointLight emits from a single point within the scene in all directions. | +| `SpotLight` | SpotLight emits a cone of light from a single point in a given direction. | + +Lights defined in this specification have a `color` and an `intensity`. The color is given as an RGB value, such as "#FFFFFF" for white. The intensity is the strength or brightness of the light, and described using a `Value` construct. + +SpotLight has an additional property of `angle`, specified in degrees, which is the angle from the direction that the Light is facing to the outside extent of the cone. + +diagram of cone geometry showing how the angle of the cone is defined + +Lights that require a position and/or direction have these through the Annotation which associates them with the Scene, described below in the sections on [Painting Annotations][] and [Transforms][]. If a Light does not have an explicit direction, then the default is in the negative y direction (downwards). If a Light does not have an explicit position in the coordinate space, then the default is at the origin. + +This specification does not define other aspects of Lights, such as the rate of decay of the intensity of the light over a distance, the maximum range of the light, or the penumbra of a cone. Implementation of these aspects is client-dependent. + +If there are no Lights present within the Scene, then the viewer MUST add at least one Light. The types and properties of Lights added in this way are client-dependent. + +```json +{ + "id": "https://example.org/iiif/light/1", + "type": "AmbientLight", + "color": "#FFFFFF", + "intensity": {"type": "Value", "value": 0.6, "unit": "relativeUnit"} +} +``` + + + +### Transforms + +The Annotation with a Selector on the target can paint a resource at a point other than the origin, however it will be at its initial scale and rotation, which may not be appropriate for the scene that is being constructed. + +This specification defines a new class of manipulations for SpecificResources called a `Transform`, with three specific sub-classes. Each Transform has three properties, `x`, `y` and `z` which determine how the Transform affects that axis in the local coordinate space. + + +| Class | Description | +| --------------- | ------------ | +| ScaleTransform | A ScaleTransform applies a multiplier to one or more axes in the local coordinate space. A point that was at 3.5, after applying a ScaleTransform of 2.0 would then be at 7.0. If an axis value is not specified, then it is not changed, resulting in a default of 1.0 | +| RotateTransform | A RotateTransform rotates the local coordinate space around the given axis in a counter-clockwise direction around the axis itself (e.g. around a pivot point of 0 on the axis). A point that was at x=1,y=1 and was rotated 90 degrees around the x axis would be at x=1,y=0,z=1. If an axis value is not specified, then it is not changed, resulting in a default of 0.0 | +| TranslateTransform | A TranslateTransform moves all of the objects in the local coordinate space the given distance along the axis. A point that was at x=1.0, after applying a TranslateTransform of x=1.0 would be at x=2.0. If an axis value is not specified then it is not changed, resulting in a default of 0.0 | + +Transforms are added to a SpecificResource using the `transform` property. The value of the property is an array, which determines the order in which the transforms are to be applied. The resulting state of the first transform is the input state for the second transform, and so on. Different orders of the same set of transforms can have different results, so attention must be paid when creating the array and when processing it. + +The point around which RotateTransform rotates the space is the origin. This "pivot point" cannot be changed directly, but instead a TranslateTransform can be used to move the desired pivot point to the be at the origin, then the RotateTransform applied. + +Transforms are only used in the Presentation API when the SpecificResource is the `body` of the Annotation, and are applied before the resource is painted into the scene at the point given in the `target`. + +```json +{ + "type": "SpecificResource", + "source": { + "id": "https://example.org/iiif/assets/model1.glb", + "type": "Model" + }, + "transform": [ + { + "type": "RotateTransform", + "x": 0.0, + "y": 180.0, + "z": 0.0 + }, + { + "type": "TranslateTransform", + "x": 1.0, + "y": 0.0, + "z": 0.0 + } + ] +} +``` + + +#### Relative Rotation + +It is useful to be able to rotate a light or camera resource such that it is facing another object or point in the Scene, rather than calculating the angles within the Scene's coordinate space. This is accomplished with a property called `lookAt`, valid on DirectionalLight, SpotLight, and all Cameras. The value of the property is either a PointSelector, a WktSelector, the URI of an Annotation which paints something into the current Scene, or a Specific Resource with a selector identifying a point or region in an arbitrary container. + +If the value is a PointSelector, then the light or camera resource is rotated around the x and y axes such that it is facing the given point. If the value is a WktSelector, then the resource should be rotated to face the given region. If the value is an Annotation which targets a point via a PointSelector, URI fragment or other mechanism, then the resource should be rotated to face that point. If the value is a Specific Resource, the source container for the Specific Resource must be painted into the current Scene, and the Specific Resource selector should identify a point or region in the source container. In this case, the light or camera resource should be rotated to face the point or region in the source container where the point or region is located within the current Scene's coordinate space. This allows light or camera resources to face a specific 2D point on a Canvas painted into a 3D scene. + +This rotation happens after the resource has been added to the Scene, and thus after any transforms have taken place in the local coordinate space. + +```json +"lookAt": { + "type": "PointSelector", + "x": 3, + "y": 0, + "z": -10 +} +``` + + +#### Excluding + +Just as a Scene may contain multiple Annotations with model, light, and camera resources, a single 3D model file may contain a collection of 3D resources, including model geometry, assemblages of lights, and/or multiple cameras, with some of these potentially manipulated by animations. When painting Scenes or models that themselves may contain groups of resources within a single Scene, it may not always be appropriate to include all possible cameras, lights, or other resources, and it may be desirable to opt not to import some of these resources. This is accomplished through the Annotation property `exclude`, which prevents the import of audio, lights, cameras, or animations from a particular Scene or model prior to the Annotation being painted into a Scene. When `exclude` is used, the excluded resource type should not be loaded into the Scene, and it is not possible to reactivate or turn on these excluded resources after loading. + +Painting a Scene into another while excluding import of several types of resources: +```json +{ + "id": "https://example.org/iiif/3d/anno1", + "type": "Annotation", + "motivation": ["painting"], + "exclude": ["Audio", "Lights", "Cameras", "Animations"], + "body": { + "id": "https://example.org/iiif/scene1", + "type": "Scene" + }, + "target": "https://example.org/iiif/scene2" +} +``` + + + + + + + +### Nesting + +A Canvas can be painted into a Scene as an Annotation, but the 2D nature of Canvases requires special consideration due to important differences between Canvases and Scenes. A Canvas describes a bounded 2D space with finite `height` and `width` measured in pixels with a pixel origin at the top-left corner of the Canvas, while Scenes describe a boundless 3D space with x, y, and z axes of arbitrary coordinate units and a coordinate origin at the center of the space. It is important to note that in many cases the pixel scale used by a Canvas or a 2D image content resource will not be in proportion to the desired 3D coordinate unit scale in a Scene. + +When a Canvas is painted as an Annotation targeting a Scene, the top-left corner of the Canvas (the pixel origin) is aligned with the 3D coordinate origin of the Scene. The top edge of the Canvas is aligned with (e.g., is colinear to) the positive x axis extending from the coordinate origin. The left edge of the Canvas is aligned with (e.g., is colinear to) the negative y axis extending from the coordinate origin. The Canvas is scaled to the Scene such that the pixel dimensions correspond to 3D coordinate units - a Canvas 200 pixels wide and 400 pixels high will extend 200 coordinate units across the x axis and 400 coordinate units across the y axis. Please note: direction terms "top", "bottom", "right", and "left" used in this section refer to the frame of reference of the Canvas itself, not the Scene into which the Canvas is painted. + +A Canvas in a Scene has a specific forward face and a backward face. By default, the forward face of a Canvas should point in the direction of the positive z axis. If the property `backgroundColor` is used, this color should be used for the backward face of the Canvas. Otherwise, a reverse view of the forward face of the Canvas should be visible on the backward face. + +
+ To Do: Add an image demonstrating default Canvas placement in Scene +
+ +A `PointSelector` can be used to modify the point at which the Canvas will be painted, by establishing a new point to align with the top-left corner of the Canvas instead of the Scene coordinate origin. Transforms can also be used to modify Canvas rotation, scale, or translation. + +It may be desirable to exercise greater control over how the Canvas is painted into the Scene by selecting the coordinate points in the Scene that should correspond to each corner of the Canvas. This provides fine-grained manipulation of Canvas placement and/or scale, and for optionally introducing Canvas distortion or skew. Annotations may use a WktSelector to select different points in the Scene to align with the top-left, bottom-left, bottom-right, and top-right corners of the Canvas. In this case, the four Scene coordinates should be listed beginning with the coordinate corresponding to the top-left corner of the Canvas, and should proceed in a counter-clockwise winding order around the Canvas, with coordinates corresponding to bottom-left, bottom-right, and top-right corners in order respectively. The use of WktSelector for this purpose overrides any use of Transforms on the Canvas Annotation. + +Example placing top-left at (0, 1, 0); bottom-left at (0, 0, 0); bottom-right at (1, 0, 0); and top-right at (1, 1, 0): +```json +"selector": [ + { + "type": "WktSelector", + "value": "POLYGONZ((0 1 0, 0 0 0, 1 0 0, 1 1 0))" + } +] +``` + +When a Scene is nested into another Scene, the `backgroundColor` of the Scene to be nested should be ignored as it is non-sensible to import. All Annotations painted into the Scene to be nested will be painted into the Scene into which content is being nested, including Light or Camera resources. If the Scene to be nested has one or more Camera Annotations while the Scene into which content is being nested does not, the first Camera Annotation from the nested Scene will become the default Camera for the overall Scene. + + + + + + + + + + + + + + + + + + Whale bone with a camera and a light @@ -262,11 +614,612 @@ Comments, tags, etc transcripts (and back ref to OCR on images etc) +### Comment Annotations + + + +### Choice of Alternative Resources + + +### Embedded Content + +e.g., painting TextualBody on Canvas + +Todo: This is mostly copy-pasted from properties, is it needed here? +It is important to be able to position the textual body of an annotation within the Container's space that the annotation also targets. For example, a description of part of an image in a Canvas should be positioned such that it does not obscure the image region itself and labels to be displayed as part of a Scene should not be rendered such that the text is hidden by the three dimensional geometry of the model. The positioning of the textual body in a container is accomplished through the `position` property, which has as a value a Specific Resource identifying the targeted container as the source and a selector defining how the textual body should be positioned in the targeted container. If this property is not supplied, then the client should do its best to ensure the content is visible to the user. + + + + + +### Non Rectangular Segments + +SvgSelector - move to SpecificResource too ^^ + + +### Style + +Move to SpecificResource + + +### Rotation + + +### Hotspot Linking and Activation + +Move to SpecificResource + + + + +#### Annotation Page + +"Overlapping elements with a larger z-index cover those with a smaller one." +link to https://developer.mozilla.org/en-US/docs/Web/CSS/z-index + + + +#### Annotation Collection + +deal with this: +https://github.com/IIIF/api/pull/2304/files#diff-cc70f02818f6bed2b14dfbf8bf3206e0825047951c8e83ad56fc73e489f82ac4R1757 + +use totalItems? https://iiif.io/api/discovery/1.0/#totalitems + + + + + + ### State -Content State -Activating annos +## Content State + +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](content-state-2) 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 + +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: + +```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" + } + ] + } +} +``` + +As well as adding resources not present in the referred-to resource, the Content State can also remove parts of the referred-to resource from the user's view by applying the behavior `hidden` to them: + +```jsonc +{ + // What does this actually look like? I want to load bnf_chateauroux example but HIDE the illumination + // ... + "id": "https://iiif.io/api/cookbook/recipe/0036-composition-from-multiple-images/annotation/p0001-image", + "type": "Annotation", + "motivation": "painting", + "behavior": ["hidden"] +} +``` + +TODO: what is the processing algorithm for applying incoming `hidden` ? + +When a Content State annotation carries a Scene, a view might be initialized from a Content State that introduces an additional Camera that shows the user the point of interest. + + +### Modify the Container in a particular context + +The techniques in the previous example are also used within a published IIIF Manifest 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. The `scope` property indicates to the client that the Content State provides valuable context for displaying some aspect of a Scene or other Container. In the case of a commenting annotation, this means that the Content State should be loaded when the commenting annotation is selected or otherwise highlighted. + + +Consider a Scene with two models, and two `commenting` annotations: + +```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/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/anno7", + "type": "Annotation", + "motivation": ["commenting"], + "bodyValue": "Mandibular tooth", + "target": { + // SpecificResource with PointSelector + } + }, + { + "id": "https://example.org/iiif/3d/anno5", + "type": "Annotation", + "motivation": ["commenting"], + "bodyValue": "Right pterygoid hamulus", + "target": { + // SpecificResource with PointSelector + } + } + ] + } + ] +} +``` + +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. It may be useful to light the Scene differently in different contexts. + +In the same way an incoming Content State can modify a Scene as it initializes the client, so can a Content State attached to each (non-`painting`) annotation target modify the Scene as the user moves between different annotations. + +The `scope` property of an annotation `target` provides _contextual_ Content State - the viewer should modify the Scene by applying the Content State carried by the `scope` property _only when the user is in the context of that annotation_. + +Taking the first commenting annotation from the above example and adding a `scope` property, whose value is an annotation with the motivation `contentState`, we can introduce a new Camera specifically for this particular annotation, so that when the user selects this comment, the client will switch the view to this camera. This example also changes the background color of the Scene: + +```jsonc +{ + "id": "https://example.org/iiif/3d/anno7", + "type": "Annotation", + "motivation": ["commenting"], + "bodyValue": "Mandibular tooth", + "target": { + + // SpecificResource with PointSelector + // "type": "SpecificResource", + // "source": ... the Scene... + // "selector": ... a point ... + + "scope": { // a modification to the Scene, only in the context of this annotation + + "id": "https://example.org/iiif/3d/anno4", + "type": "Annotation", + "motivation": ["contentState"], + "target": { + "id": "https://example.org/iiif/scene1/page/p1/1", + "type": "Scene", + "backgroundColor": "yellow", + "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.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 + } + ] + } + } + ] + } + } + } +} +``` + +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 `scope` 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 parts of the Scene for a step + - introducing additional models at a particular step + - (and many more!) + +Use of `scope` is permitted in annotations on any Container type, not just Scenes. For example, a 2D narrative around a Canvas might show or hide different `painting` annotations at each step. + + + + + + +#### The `sequence` behavior + +// Is this right? Language... + +While all AnnotationPage `items` are inherently ordered, an Annotation Page with the behavior `sequence` is explicitly a narrative, and clients should prevent (dissuade) users from jumping about. The presence of `sequence` affects the way a client should interpret the `reset` property described below. + +### Content States on Manifests + +When an annotation with the motivation `contentState` is provided via the `annotations` property of a Manifest, rather than contextually via `scope`, it is assumed to be generally available for selection by the user at any time. A client may present such as annotations as a menu of views, allowing arbitrary jumping into any Scene (or Canvas or Timeline) from any other point. + +// Is there some overlap here with Range? + +### Processing Content States in Scopes: reset + +// This may not be what we have discussed... + +When a Content State is applied to a Container such as a Scene, it is assumed to be a "diff" - for example if 3 cameras and 4 lights are already present in the Scene, and a Content State asserts a single new Camera, the default behavior is to add this fourth Camera to the Scene and leave the existing resources as they are. + +The client should reset the Container to its original state before applying the diff operation. However, for narratives that cumulatively build a Scene this may lead to excessively verbose Manifests. When moving through the items of an Annotation page with the behavior `sequence`, the Container is not reset and the diff is cumulative; modifications from one `scope` persist into the next. If this behavior is not wanted, the `reset` property of the content state annotation should be set to `true`: + +```json +{ + "type": "Annotation", + "motivation": ["contentState"], + "reset": true +} +``` + +Before applying the content state to the Scene, the client should reset the Scene to its original state as provided by the Manifest. + +// I am assuming reset is always true except in `sequence` - otherwise it's completely unpredictable!! or is it... arbitrary navigation, state provided by initialization content states, etc... + +### Contribute additional information permanently + +Rerum inbox scenario - should be covered in CS2 protocol + +### activating - animation and interactions + +Annotations with the motivation `activating` are referred to as _activating_ annotations. + +There are two uses of `activating` annotations: + +#### Triggering a content state + +An activating annotation links a painting annotation to a content state. When a user interacts with the painting annotation - whether through clicking it, tapping it, or other client-specific behaviors - the linked content state should be processed to modify the Scene or other Container, as in the previous examples. The painting annotation is the target of the activating annotation, and the content state is the body value. Only one content state may be specified in the body array, but the body array may include a `TextualBody` to provide a label for the interaction. The pattern is the same as for the `linking` motivation, but rather than the client opening a new browser window on the resource specified in the `body`, it applies the modification provided by the Content State. + +The activating annotation is provided in a Container's `annotations` property. In this (contrived for brevity) example, if the user clicks the mandible model, the Scene background changes color: + +```jsonc +{ + "id": "https://example.org/iiif/3d/activating.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/scene-with-activation", + "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/painting-anno-for-mandible", + "type": "Annotation", + "motivation": ["painting"], + "body": { + "id": "https://raw.githubusercontent.com/IIIF/3d/main/assets/whale/whale_mandible.glb", + "type": "Model" + }, + "target": { + // SpecificResource with PointSelector + } + } + ], + "annotations": [ + { + "id": "https://example.org/iiif/scene1/page/activators", + "type": "AnnotationPage", + "items": [ + { + "id": "https://example.org/iiif/3d/anno2", + "type": "Annotation", + "motivation": ["activating"], + "body": [ + { + "type": "TextualBody", + "value": "A label for the activation may be provided as a TextualBody" + }, + { + // A body where the type is a IIIF Resource (eg Scene) is the Content State to apply + "id": "https://example.org/iiif/scene1/scene-with-activation", + "type": "Scene", + "backgroundColor": "#FF99AA" + } + ], + "target": { + "id": "https://example.org/iiif/3d/painting-anno-for-mandible", + "type": "Annotation" + } + } + ] + } + ] + } + ] + } + ] +} +``` + +// Can you put activating annotations in `manifest.annotations`? They would work there too, you have all the information. + + + +#### 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. + +This pattern is similar to the above, except that: + + - There is no Content State in the `body`, but there _MUST_ be a TextualBody to label the interaction. (?? must?) + - The `target` selects a _named animation_ in the model. The `target` MUST be a SpecificResource, where the `source` is the painting annotation that paints the model, and the `selector` is of type `AnimationSelector` with the `value` being a string that corresponds to the animation in the model. + + The format of the `value` string is implementation-specific, and will depend on how different 3D formats support addressing of animations within models. The same model can be painted multiple times into the scene, and you might want to activate only one model's animation, thus we need to refer to the annotation that paints the model, not the model directly. + + + +```jsonc +{ + "id": "https://example.org/iiif/3d/activating-animation.json", + "type": "Manifest", + "label": { "en": ["Music Box with lid that opens as an internal animation"] }, + "items": [ + { + "id": "https://example.org/iiif/scene1/scene-with-activation-animation", + "type": "Scene", + "label": { "en": ["A Scene Containing a Music Box"] }, + "items": [ + { + "id": "https://example.org/iiif/scene-with-activation-animation/page/p1/1", + "type": "AnnotationPage", + "items": [ + { + "id": "https://example.org/iiif/3d/painting-anno-for-music-box", + "type": "Annotation", + "motivation": ["painting"], + "body": { + "id": "https://raw.githubusercontent.com/IIIF/3d/main/assets/music-box.glb", + "type": "Model" + }, + "target": { + // SpecificResource with PointSelector + } + } + ], + "annotations": [ + { + "id": "https://example.org/iiif/scene1/page/activators", + "type": "AnnotationPage", + "items": [ + { + "id": "https://example.org/iiif/3d/anno2", + "type": "Annotation", + "motivation": ["activating"], + "body": [ + { + "type": "TextualBody", + "value": "Click the box to open the lid" + } + ], + "target": [ + { + "type": "SpecificResource", + "source": "https://example.org/iiif/3d/painting-anno-for-music-box", + "selector": [ + { + "type": "AnimationSelector", + "value": "open-the-lid" + } + ] + } + ] + } + ] + } + ] + } + ] + } + ] +} +``` + +// TODO + +activating to apply a content state and activating to trigger a named animation - use of body and target... what if we want to click a painting anno to trigger the animation? +Can we ADD that to the target, alongside the SpecificResource with the AnimationSelector? + +if the `target` is an AnimationSelector, then the `body` can ONLY be TextualBody (or list of TextualBody)? + +There is a more general rule here! + +### reset + +See above... + + + + + + ## Navigation @@ -327,10 +1280,77 @@ Paged collections and conceptual collections + +## Conveying Physical Dimensions + +(why is this important!?) + +(move the props to vocab doc) + +### spatialScale + +### temporalScale + + +``` +{ + "spatialScale": { + "factor": 22.0, + "units": "m" + }, + + + // this would be rarely used + "temporalScale": { + "factor": 0.00001 + } + +} +``` + +`factor` Required A floating point ratio. +`units` Required A real-world measuring unit. Always seconds for temporalScale. Possible values for spatialScale include: "m", "ft". (is that it?) + +For a Canvas, it's the physical "size" of each cartesian integer unit. +For a Scene, it's the physical size of the unit vector. +For a timeline it's the ratio of time in the recording to time in the real world. + + +(define props in the Vocabulary doc) + + + + ## Protocol +## HTTP Requests and Responses + +### URI Recommendations + +### Requests + +### Responses + +### Authentication + + + + + + +## Accessibility + +(new section) + +`provides` + + + + + + ## Terminology The principles of [Linked Data][org-linked-data] and the [Architecture of the Web][org-w3c-webarch] are adopted in order to provide a distributed and interoperable framework. The [Shared Canvas data model][shared-canvas] and [JSON-LD][org-w3c-json-ld] are leveraged to create an easy-to-implement, JSON-based format. @@ -344,3 +1364,15 @@ This specification uses the following terms: The terms _array_, _JSON object_, _number_, _string_, and _boolean_ in this document are to be interpreted as defined by the [Javascript Object Notation (JSON)][org-rfc-8259] specification. The key words _MUST_, _MUST NOT_, _REQUIRED_, _SHALL_, _SHALL NOT_, _SHOULD_, _SHOULD NOT_, _RECOMMENDED_, _MAY_, and _OPTIONAL_ in this document are to be interpreted as described in [RFC 2119][org-rfc-2119]. + + + +## Appendices + +### Versioning + +### Acknowledgements + +### Change Log + +"Exclude Audio" From 6eacf9d0160d24af2de7b8b6a432e4b78e89ec71 Mon Sep 17 00:00:00 2001 From: tomcrane Date: Tue, 18 Mar 2025 14:15:08 -0400 Subject: [PATCH 039/130] skeleton of Image and AV sections --- source/presentation/4.0/index.md | 64 ++++++++++++++++++++++++++++---- 1 file changed, 57 insertions(+), 7 deletions(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index 8e4665f2d..ae0ccf9fe 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -184,25 +184,59 @@ comment annotation about part of the previous example's Canvas using FragmentSel ``` -## Presenting Content Resources - what you came here for +## Presenting Content Resources + +This section of the specification uses the use cases listed in the introduction to demonstrate the use of the IIIF Presentation API and introduce additional features. + ### Images -A painting +#### Example 1: a painting + +This example demonstrates the use of the properties `label`, `metadata`, ... + +``` +Example: a painting {} +Will demonstrate: + +Manifest -> items -> Canvas -> items -> AnnoPage -> items -> Anno -> body -> Image +label, summary, metadata, rights, provider, homepage, thumbnail +``` + +Some text, maybe mention requiredStatement + +#### Example 2: a digitized book + +``` +Example: a paged thing - a book +requiredStatement, behavior, viewingDirection, (no Ranges), rendering - PDF version, start +``` + +Introduce new props used, link to model -A paged thing +More text - paging behaviors - ref the Model ### Audio and Video -A timeline - audio only +#### Example: a short recording with a transcript -A video on a Canvas with duration +``` +Timeline +duration, format, annotations (transcript), language, accompanyingContainer +``` + +#### Example: a movie with subtitles + +``` +Canvas +duration, format, Choice of video 720p, 4K? (forward ref), timeMode, placeholderContainer +``` ### 3D -A Scene in IIIF is a virtual container that represents a boundless three-dimensional space and has content resources, lights and cameras positioned at locations within it. It may also have a duration to allow the sequencing of events and timed media. Scenes have infinite height (y axis), width (x axis) and depth (z axis), where 0 on each axis (the origin of the coordinate system) is treated as the center of the scene's space. +Scenes have infinite height (y axis), width (x axis) and depth (z axis), where 0 on each axis (the origin of the coordinate system) is treated as the center of the scene's space. The positive y axis points upwards, the positive x axis points to the right, and the positive z axis points forwards (a [right-handed cartesian coordinate system](https://en.wikipedia.org/wiki/Right-hand_rule)). The axes of the coordinate system are measured in arbitrary units and these units do not necessarily correspond to any physical unit of measurement. This allows arbitrarily scaled models to be used, including very small or very large, without needing to deal with very small or very large values. If there is a correspondence to a physical scale, then this can be asserted using the physical dimensions pattern(fwd-ref-to-phys-dims). @@ -211,7 +245,6 @@ The axes of the coordinate system are measured in arbitrary units and these unit -As multiple models, lights, cameras, and other resources can be associated with and placed within a Scene container, Scenes provide a straightforward way of grouping content resources together within a space. Scenes, as well as other IIIF containers such as Canvases, can also be embedded within a Scene, allowing for the nesting of content resources. A Scene or a Canvas may be treated as a content resource, referenced or described within the `body` of an Annotation. As with models and other resources, the Annotation is associated with a Scene into which the Scene or Canvas is to be nested through an Annotation `target`. The content resource Scene will be placed within the `target` Scene by aligning the coordinate origins of the two scenes. Alternately, Scene Annotations may use `PointSelector` to place the origin of the resource Scene at a specified coordinate within the `target` Scene. @@ -620,6 +653,8 @@ transcripts (and back ref to OCR on images etc) ### Choice of Alternative Resources +Multispectral here + ### Embedded Content @@ -1268,6 +1303,10 @@ Table of Contents as simple example thumbnail-nav sequence +`structures` property + +supplementary + ### Collections @@ -1277,8 +1316,19 @@ back ref to periodical? Paged collections and conceptual collections +partOf + +Periodicals - navDate, navPlace + + +## Integration + +seeAlso, service(s), extensions +mention search, image api, auth +profile for seeAlso +partOf - ## Conveying Physical Dimensions From 251268bf09712a8cd257eecd1c8a038d182cd573 Mon Sep 17 00:00:00 2001 From: tomcrane Date: Tue, 18 Mar 2025 15:13:20 -0400 Subject: [PATCH 040/130] Image and Audio examples --- source/presentation/4.0/index.md | 38 +++++++++++++++++++++++--------- 1 file changed, 27 insertions(+), 11 deletions(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index ae0ccf9fe..11cbfa8af 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -139,6 +139,8 @@ The same linking mechanism is also used in IIIF with other motivations for trans The required properties of Annotations are `id`, `type`, `motivation`, and `target`. Most Annotations also have the `body` property. +The relationship between a Container and a painting annotation is not direct. Annotations are grouped within the `items` property of an Annotation Page, and the `items` property of the Container is a list of Annotation Pages. + (👀) [Model Documentation](model/#annotations) ``` @@ -191,9 +193,9 @@ This section of the specification uses the use cases listed in the introduction ### Images -#### Example 1: a painting +#### Use Case 1: Artwork -This example demonstrates the use of the properties `label`, `metadata`, ... +This example is a Manifest with one Canvas, with an image of an artwork "painted" onto the Canvas. It demonstrates the use of the common descriptive properties `label` for the title of the artwork, `metadata` for additional information to display to the user, `summary` for a brief description of the artwork, `rights` to assert a rights statement or license from a controlled vocabulary, `homepage` to link to the artwork's specific web page, `thumbnail` to provide a small image to stand for the Manifest, and `provider` to give information about the publisher of the Manifest. ``` Example: a painting {} @@ -203,34 +205,45 @@ Manifest -> items -> Canvas -> items -> AnnoPage -> items -> Anno -> body -> Ima label, summary, metadata, rights, provider, homepage, thumbnail ``` -Some text, maybe mention requiredStatement +Notice that the painting Annotation is a member of the `items` property of an Annotation Page. While in this case there is only one Annotation Page and one Annotation, the mechanism is needed for consistency when there are multiple Annotation Pages, and it allows for Annotation Pages in general to be separate resources on the web. + -#### Example 2: a digitized book +#### Example 2: Book + +This example is a Manifest with multiple Canvases, each of which represents a page of a book. It demonstrates the use of the `behavior` property to indicate to a client that the object is _paged_: this helps a client generate the correct user experience. The `viewingDirection` property indicates that the book is read left-to-right. In this case, the property is redundant as `left-to-right` is the default value. The Manifest has a `rendering` property linking to a PDF representation; typically a client would offer this as a download or "view as" option. The `start` property is used to tell a client to initialize the view on a particular Canvas, useful if the digitized work contains a large amount of irrelevant front matter or blank pages. The `requiredStatement` is a message that a client MUST show to the user when presenting the Manifest. ``` Example: a paged thing - a book requiredStatement, behavior, viewingDirection, (no Ranges), rendering - PDF version, start ``` -Introduce new props used, link to model - -More text - paging behaviors - ref the Model ### Audio and Video -#### Example: a short recording with a transcript +#### Example: a 45 single with one Timeline per song/side + +This example is a Manifest with two Timelines, each of which represent a temporal extent during which a song is played. As in most cases, the Timeline `duration` is the same length as that of Content Resource painted into it. This example is a recording digitized from a 45 RPM 7 inch single. It demonstrates the use of `format` for the audio files' content type, `language` (One song is in English and one is in German), `behavior` with value "autoPlay" that tells a client to automatically advance to the second Timeline after playing the first, `annotations` that link to Annotation Pages of annotations with the motivation `supplementing` that provide the lyrics (one example is given afterwards) - and an `accompanyingContainer` that carries a picture of the single's cover that is shown while the songs are playing. + ``` Timeline -duration, format, annotations (transcript), language, accompanyingContainer +duration, autoPlay, format, annotations (transcript), language, accompanyingContainer +``` + +``` +... + (A single supplementing annotation for a line of the song) t= fragment +... ``` #### Example: a movie with subtitles +This example is a Manifest with one Canvas that represents the temporal extent of the movie (the Canvas `duration`) and its aspect ratio (given by the `width` and `height` of the Canvas). The example demonstrates the use of a `Choice` annotation body to give two alternative versions of the movie, the `timeMode` property + ``` Canvas -duration, format, Choice of video 720p, 4K? (forward ref), timeMode, placeholderContainer +duration, behavior=autoplay, format, Choice of video 720p, 4K? (forward ref), timeMode, placeholderContainer ``` @@ -244,7 +257,8 @@ The axes of the coordinate system are measured in arbitrary units and these unit diagram of Right handed cartesian coordinate system - +``` +``` A Scene or a Canvas may be treated as a content resource, referenced or described within the `body` of an Annotation. As with models and other resources, the Annotation is associated with a Scene into which the Scene or Canvas is to be nested through an Annotation `target`. The content resource Scene will be placed within the `target` Scene by aligning the coordinate origins of the two scenes. Alternately, Scene Annotations may use `PointSelector` to place the origin of the resource Scene at a specified coordinate within the `target` Scene. @@ -1395,6 +1409,8 @@ For a timeline it's the ratio of time in the recording to time in the real world (new section) `provides` +`provides[]` + From c1bfe1e51848f5d015afe86c02a67bc8be2c2c4c Mon Sep 17 00:00:00 2001 From: tomcrane Date: Tue, 18 Mar 2025 16:10:24 -0400 Subject: [PATCH 041/130] Periodicals example --- source/presentation/4.0/index.md | 49 ++++++++++++++++++++++++++++++-- 1 file changed, 46 insertions(+), 3 deletions(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index 11cbfa8af..237b7a931 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -63,8 +63,7 @@ Presentation, the clue is in the name 3. Audio and Video recordings (time-based, transcriptions) 4. 3D scans of objects (3D) 5. Periodicals (Collections, Ranges, navDate) -6. Archival collections (Collections, Ranges, navDate) -7. Storytelling and exhibitions (State, annotations) +6. Storytelling and exhibitions (State, annotations) see Terminology at the end @@ -239,16 +238,31 @@ duration, autoPlay, format, annotations (transcript), language, accompanyingCont #### Example: a movie with subtitles -This example is a Manifest with one Canvas that represents the temporal extent of the movie (the Canvas `duration`) and its aspect ratio (given by the `width` and `height` of the Canvas). The example demonstrates the use of a `Choice` annotation body to give two alternative versions of the movie, the `timeMode` property +This example is a Manifest with one Canvas that represents the temporal extent of the movie (the Canvas `duration`) and its aspect ratio (given by the `width` and `height` of the Canvas). The example demonstrates the use of a `Choice` annotation body to give two alternative versions of the movie, the `timeMode` property ..., and `placeholderContainer` that provides a poster image to show in place of the video file before the user initiates playback. ``` Canvas duration, behavior=autoplay, format, Choice of video 720p, 4K? (forward ref), timeMode, placeholderContainer ``` +{ + Canvas + duration: 3600 + movie.mp4 + duration: 3599.68 + movie.flv + duration: 3600.8 + +} + +Sometimes, two different formats derived from the same source may have slightly different durations, perhaps a few milliseconds out. What to do... + ### 3D +Need to get PointSelector in early + + Scenes have infinite height (y axis), width (x axis) and depth (z axis), where 0 on each axis (the origin of the coordinate system) is treated as the center of the scene's space. The positive y axis points upwards, the positive x axis points to the right, and the positive z axis points forwards (a [right-handed cartesian coordinate system](https://en.wikipedia.org/wiki/Right-hand_rule)). @@ -1273,6 +1287,33 @@ See above... ## Navigation +### Collection + +IIIF Collections are ordered lists of Manifests, Collections, and/or Specific Resources. Collections allow these resources to be grouped in a hierarchical structure for navigation and other purposes. + +:eyes: + +### Range + +IIIF Ranges are used to represent structure _WITHIN_ a Manifest beyond the default order of the Containers in the `items` property. Example uses include newspaper sections or articles, chapters within a book for a table of contents, or movements within a piece of music. Ranges can include Containers, parts of Containers via Specific Resources or fragment URIs, or other Ranges, creating a tree structure like a table of contents. The typical intent of adding a Range to the Manifest is to allow the client to display a linear or hierarchical navigation interface to enable the user to quickly move through the object's content. + +:eyes: + +### Example: Periodical + +This example demonstrates the use of IIIF Collections to group Manifests into a hierarchy. In this case, there is a Collection for a publishing run of the _The Tombstone Epitaph_ from 1880 to 1920. This contains 41 child Collections each representing a year's worth of issues. Each of these year Collections in turn has one Manifest for each daily issue of the newspaper. + +Within each Manifest, the `structures` property provides Ranges which are used to identify individual sections of the Newspaper, and individual stories within the sections which may be spread across multiple columns and pages. + +Each Manifest has a `navDate` property that could be used to plot the issues on a calendar-style user interface. +The top level Collection has a `navPlace` property that could be used on a "Newspapers of America" map to allow users to view newspapers by location. Each story's Range links to an Annotation Collection that provides the text of the story via the `supplementary` property. + + +``` +demonstrates navDate, navPlace, structures (Ranges), supplementary, Collections +... +``` + ### navXXXX These are just extracts as examples @@ -1312,6 +1353,8 @@ navDate ### Ranges + + Periodical example - with navDate again Table of Contents as simple example thumbnail-nav From 36c8f816e3f7a5d6b140415d33e2a8bbba6c2a92 Mon Sep 17 00:00:00 2001 From: tomcrane Date: Tue, 18 Mar 2025 16:26:53 -0400 Subject: [PATCH 042/130] move content state below navigation --- source/presentation/4.0/index.md | 174 +++++++++++++------------------ 1 file changed, 72 insertions(+), 102 deletions(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index 237b7a931..404c64477 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -734,7 +734,78 @@ use totalItems? https://iiif.io/api/discovery/1.0/#totalitems -### State + + +## Navigation + +### Collection + +IIIF Collections are ordered lists of Manifests, Collections, and/or Specific Resources. Collections allow these resources to be grouped in a hierarchical structure for navigation and other purposes. + +:eyes: + +### Range + +IIIF Ranges are used to represent structure _WITHIN_ a Manifest beyond the default order of the Containers in the `items` property. Example uses include newspaper sections or articles, chapters within a book for a table of contents, or movements within a piece of music. Ranges can include Containers, parts of Containers via Specific Resources or fragment URIs, or other Ranges, creating a tree structure like a table of contents. The typical intent of adding a Range to the Manifest is to allow the client to display a linear or hierarchical navigation interface to enable the user to quickly move through the object's content. + +:eyes: + +### Example: Periodical + +This example demonstrates the use of IIIF Collections to group Manifests into a hierarchy. In this case, there is a Collection for a publishing run of the _The Tombstone Epitaph_ from 1880 to 1920. This contains 41 child Collections each representing a year's worth of issues. Each of these year Collections in turn has one Manifest for each daily issue of the newspaper. + +Within each Manifest, the `structures` property provides Ranges which are used to identify individual sections of the Newspaper, and individual stories within the sections which may be spread across multiple columns and pages. + +Each Manifest has a `navDate` property that could be used to plot the issues on a calendar-style user interface. +The top level Collection has a `navPlace` property that could be used on a "Newspapers of America" map to allow users to view newspapers by location. Each story's Range links to an Annotation Collection that provides the text of the story via the `supplementary` property. + + +``` +demonstrates navDate, navPlace, structures (Ranges), supplementary, Collections +... +``` + + + +```json +"navPlace": { + "id": "https://iiif.io/api/cookbook/recipe/0318-navPlace-navDate/feature-collection/1", + "type": "FeatureCollection", + "features": [ + { + "id": "https://iiif.io/api/cookbook/recipe/0318-navPlace-navDate/feature/1", + "type": "Feature", + "properties": { + "label": { "en": ["Castel Sant'Angelo, Rome"] } + }, + "geometry": { + "type": "Point", + "coordinates": [12.4663, 41.9031] + } + } + ] +} +``` + + +thumbnail-nav +sequence + + + +## Integration + +seeAlso, service(s), extensions +mention search, image api, auth + +profile for seeAlso + +partOf - + + + + +## State ## Content State @@ -1285,107 +1356,6 @@ See above... -## Navigation - -### Collection - -IIIF Collections are ordered lists of Manifests, Collections, and/or Specific Resources. Collections allow these resources to be grouped in a hierarchical structure for navigation and other purposes. - -:eyes: - -### Range - -IIIF Ranges are used to represent structure _WITHIN_ a Manifest beyond the default order of the Containers in the `items` property. Example uses include newspaper sections or articles, chapters within a book for a table of contents, or movements within a piece of music. Ranges can include Containers, parts of Containers via Specific Resources or fragment URIs, or other Ranges, creating a tree structure like a table of contents. The typical intent of adding a Range to the Manifest is to allow the client to display a linear or hierarchical navigation interface to enable the user to quickly move through the object's content. - -:eyes: - -### Example: Periodical - -This example demonstrates the use of IIIF Collections to group Manifests into a hierarchy. In this case, there is a Collection for a publishing run of the _The Tombstone Epitaph_ from 1880 to 1920. This contains 41 child Collections each representing a year's worth of issues. Each of these year Collections in turn has one Manifest for each daily issue of the newspaper. - -Within each Manifest, the `structures` property provides Ranges which are used to identify individual sections of the Newspaper, and individual stories within the sections which may be spread across multiple columns and pages. - -Each Manifest has a `navDate` property that could be used to plot the issues on a calendar-style user interface. -The top level Collection has a `navPlace` property that could be used on a "Newspapers of America" map to allow users to view newspapers by location. Each story's Range links to an Annotation Collection that provides the text of the story via the `supplementary` property. - - -``` -demonstrates navDate, navPlace, structures (Ranges), supplementary, Collections -... -``` - -### navXXXX - -These are just extracts as examples - -```json -"navDate": "1776-01-01T00:00:00+00:00", -``` - -See this in Periodicals - - - -```json -"navPlace": { - "id": "https://iiif.io/api/cookbook/recipe/0318-navPlace-navDate/feature-collection/1", - "type": "FeatureCollection", - "features": [ - { - "id": "https://iiif.io/api/cookbook/recipe/0318-navPlace-navDate/feature/1", - "type": "Feature", - "properties": { - "label": { "en": ["Castel Sant'Angelo, Rome"] } - }, - "geometry": { - "type": "Point", - "coordinates": [12.4663, 41.9031] - } - } - ] -} -``` -Map example - -navDate -??? example - - -### Ranges - - - -Periodical example - with navDate again -Table of Contents as simple example -thumbnail-nav -sequence - -`structures` property - -supplementary - - -### Collections - -Multi-vol work -Archive example -back ref to periodical? - -Paged collections and conceptual collections - -partOf - -Periodicals - navDate, navPlace - - -## Integration - -seeAlso, service(s), extensions -mention search, image api, auth - -profile for seeAlso - -partOf - ## Conveying Physical Dimensions From 19ff0190eee7a50704c6982430f2ecf0a18c3c98 Mon Sep 17 00:00:00 2001 From: tomcrane Date: Tue, 18 Mar 2025 17:11:09 -0400 Subject: [PATCH 043/130] porygonz --- source/presentation/4.0/index.md | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index 404c64477..821810ae7 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -58,6 +58,18 @@ Presentation, the clue is in the name (non-exhaustive) List of use cases +1. Artwork +2. Book +3. 45 Single +4. Movie +5. 3D 1 (Single model at 0,0,0 in Scene with ambient Light and Camera) +6. 3D 2 (Complex stuff) +7. Periodical +8. 3D 3 (storytelling) +9. Manuscript (integration) + + + 1. Digitized books and manuscripts (images, paged things, transcripts, translations) 2. Artworks and Maps (navPlace, maybe commenting annos) 3. Audio and Video recordings (time-based, transcriptions) @@ -262,6 +274,12 @@ Sometimes, two different formats derived from the same source may have slightly Need to get PointSelector in early +Example 3D 1 + +Example 3D 2 + +backgroundColor, exclude, color, intensity, far, fieldOfView, near, viewHeight, interactionMode, lookAt + Scenes have infinite height (y axis), width (x axis) and depth (z axis), where 0 on each axis (the origin of the coordinate system) is treated as the center of the scene's space. The positive y axis points upwards, the positive x axis points to the right, and the positive z axis points forwards (a [right-handed cartesian coordinate system](https://en.wikipedia.org/wiki/Right-hand_rule)). @@ -637,7 +655,7 @@ Example placing top-left at (0, 1, 0); bottom-left at (0, 0, 0); bottom-right at "selector": [ { "type": "WktSelector", - "value": "POLYGONZ((0 1 0, 0 0 0, 1 0 0, 1 1 0))" + "value": "POLYGON Z ((0 1 0, 0 0 0, 1 0 0, 1 1 0))" } ] ``` From e9dcc5ee6f5ba91b00bf0d05ab867117e2b19e24 Mon Sep 17 00:00:00 2001 From: Rob Sanderson Date: Tue, 18 Mar 2025 17:19:55 -0400 Subject: [PATCH 044/130] update --- source/presentation/4.0/model.md | 17 +++++------------ 1 file changed, 5 insertions(+), 12 deletions(-) diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index d0b200ff2..3f34143a2 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -78,14 +78,7 @@ The descriptions also do not define how the classes are used, which is done in t ### Collection -A Collection is an ordered list of Manifests, and/or Collections. Collections allow Manifests and child Collections to be grouped in a hierarchical structure for presentation, which can be for generating navigation, showing dynamic results from a search, or providing fixed sets of related resources for any other purpose. IIIF Collections might align with the curated management of cultural heritage resources in sets, also called "collections", but can also be used for many other purposes. - -The intended usage of Collections is to allow clients to: - - * Load a pre-defined set of Manifests at initialization time. - * Receive a set of Manifests, such as search results, for rendering. - * Visualize lists or hierarchies of related Manifests. - * Provide navigation through a list or hierarchy of available Manifests. +A Collection is an ordered list of Manifests, and/or Collections. The identifier in `id` _MUST_ be able to be dereferenced to retrieve the JSON description of the Collection, and thus _MUST_ use the HTTP(S) URI scheme. @@ -231,8 +224,8 @@ Point Selectors have the following properties: | type | The class of the selector, which must be "PointSelector" | | x | A number (floating point or integer) giving the x coordinate of the point, relative to the dimensions of the source resource | | y | A number (floating point or integer) giving the y coordinate of the point, relative to the dimensions of the source resource | -| z | A number (floating point or integer) giving the z coordinate of the point, relative to the dimensions of the source resource | -| t | A number (floating point or integer) giving the time of the point in seconds, relative to the duration of the source resource | +| z | A number (floating point) giving the z coordinate of the point, relative to the dimensions of the source resource | +| t | A number (floating point) giving the time of the point in seconds, relative to the duration of the source resource | ```json @@ -337,7 +330,7 @@ Animation Selectors have the following properties: ### Range -Ranges are used to represent structure within a Manifest beyond the default order of the Containers in the `items` property of the Manifest, such as newspaper sections or articles, chapters within a book, or movements within a piece of music. Ranges can include Containers, parts of Containers via SpecificResources or fragment URIs, or other Ranges, creating a tree structure like a table of contents. The typical intent of adding a Range to the Manifest is to allow the client to display a linear or hierarchical navigation interface to enable the user to quickly move through the object's content. +Ranges are used to represent structure within a Manifest beyond the default order of the Containers in the `items` property. Ranges _MUST_ have URIs and they _SHOULD_ be HTTP(S) URIs. Top level Ranges are [embedded][prezi30-terminology] or externally [referenced][prezi30-terminology] within the Manifest in a `structures` property. These top level Ranges then embed or reference other Ranges, Containers or parts of Containers in the `items` property. Each entry in the `items` property _MUST_ be a JSON object, and it _MUST_ have the `id` and `type` properties. If a top level Range needs to be dereferenced by the client, then it _MUST NOT_ have the `items` property, such that clients are able to recognize that it should be retrieved in order to be processed. @@ -376,7 +369,7 @@ Ranges _MAY_ link to an Annotation Collection that has the content of the Range ##### accompanyingContainer {: #accompanyingContainer} -A single Container that provides additional content for use while rendering the resource that has the `accompanyingContainer` property. Examples include an image to show while a duration-only Canvas is playing audio; or background audio to play while a user is navigating an image-only Manifest. +A Container that provides additional content for use while the resource that has the `accompanyingContainer` property is shown or played. Examples include an image to show while a duration-only Canvas is playing audio; or background audio to play while a user is navigating an image-only Manifest. Clients _MAY_ display the content of an accompanying Container when presenting the resource. As with `placeholderContainer` above, when more than one accompanying Container is available, the client _SHOULD_ pick the one most specific to the content. Publishers _SHOULD NOT_ assume that the accompanying Container will be processed by all clients. Clients _SHOULD_ take care to avoid conflicts between time-based media in the accompanying Container and the content of the resource that has the `accompanyingContainer` property. From 61d00e7becd23fbefca37979e88c8db89f7cff8b Mon Sep 17 00:00:00 2001 From: Rob Sanderson Date: Tue, 18 Mar 2025 18:00:57 -0400 Subject: [PATCH 045/130] smoot --- source/presentation/4.0/index.md | 16 +++++++++------- source/presentation/4.0/model.md | 18 +++++++++++++++--- 2 files changed, 24 insertions(+), 10 deletions(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index 821810ae7..f178c7657 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -1382,22 +1382,24 @@ See above... (move the props to vocab doc) -### spatialScale - -### temporalScale +Continental drift simulation example ``` { + "type": "Scene", + "spatialScale": { - "factor": 22.0, - "units": "m" + "type": "UnitValue", + "value": 22.0, + "unit": "m" }, - // this would be rarely used "temporalScale": { - "factor": 0.00001 + "type": "UnitValue", + "value": 0.00001, + "unit": "s" } } diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index 3f34143a2..071e45510 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -216,6 +216,10 @@ The Web Annotation Data Model defines several Selectors, which describe how to f There are common use cases in which a point, rather than a range or area, is the target of the Annotation. For example, putting a pin in a map should result in an exact point, not a very small rectangle. Points in time are not very short durations, and user interfaces should also treat these differently. This is particularly important when zooming in (either spatially or temporally) beyond the scale of the frame of reference. + +* FIXME: either supply instant, or all applicable dimensions for the source + + Point Selectors have the following properties: | Name | Description | @@ -225,7 +229,7 @@ Point Selectors have the following properties: | x | A number (floating point or integer) giving the x coordinate of the point, relative to the dimensions of the source resource | | y | A number (floating point or integer) giving the y coordinate of the point, relative to the dimensions of the source resource | | z | A number (floating point) giving the z coordinate of the point, relative to the dimensions of the source resource | -| t | A number (floating point) giving the time of the point in seconds, relative to the duration of the source resource | +| instant | A number (floating point) giving the time of the point in seconds, relative to the duration of the source resource | ```json @@ -235,7 +239,7 @@ Point Selectors have the following properties: "x": 0.001, "y": 12.3, "z": 0, - "t": 180.0 + "instant": 180.0 } ``` @@ -325,6 +329,8 @@ Animation Selectors have the following properties: #### ImageApiSelector +FIXME: write this + @@ -359,7 +365,7 @@ Ranges _MAY_ link to an Annotation Collection that has the content of the Range ### Other Classes #### Agent #### Service -#### Value +#### UnitValue @@ -1502,6 +1508,12 @@ The value _MUST_ be a string. { "type": "Image" } ``` +##### unit + +FIXME: possible values are 'm' and 's' and 'relative' and not 'smoot' + + + ##### viewingDirection {: #viewingDirection} From eb6de24378ed0904769a1a26dd6b929b6fa4f307 Mon Sep 17 00:00:00 2001 From: tomcrane Date: Wed, 19 Mar 2025 08:27:53 -0400 Subject: [PATCH 046/130] Re-calibrate markdown ## headings --- source/presentation/4.0/index.md | 61 +++++++++++++++----------------- 1 file changed, 28 insertions(+), 33 deletions(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index f178c7657..3470886c0 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -466,14 +466,9 @@ Todo add example -## Scene-Specific Resources +#### Scene-Specific Resources -### 3D considerations / principles - -"models" (content resources in 3D) -"local coordinate spaces" - -### Camera +##### Camera A Camera provides a view of a region of the Scene's space from a particular position within the Scene; the client constructs a viewport into the Scene and uses the view of one or more Cameras to render that region. The size and aspect ratio of the viewport is client and device dependent. @@ -511,7 +506,7 @@ The first Camera defined and not hidden in a Scene is the default Camera used to -### Light +##### Light One or more Lights MUST be present within the Scene in order to have objects within it be visible to the Cameras. @@ -547,7 +542,7 @@ If there are no Lights present within the Scene, then the viewer MUST add at lea -### Transforms +#### Transforms The Annotation with a Selector on the target can paint a resource at a point other than the origin, however it will be at its initial scale and rotation, which may not be appropriate for the scene that is being constructed. @@ -634,7 +629,7 @@ Painting a Scene into another while excluding import of several types of resourc -### Nesting +#### Nesting A Canvas can be painted into a Scene as an Annotation, but the 2D nature of Canvases requires special consideration due to important differences between Canvases and Scenes. A Canvas describes a bounded 2D space with finite `height` and `width` measured in pixels with a pixel origin at the top-left corner of the Canvas, while Scenes describe a boundless 3D space with x, y, and z axes of arbitrary coordinate units and a coordinate origin at the center of the space. It is important to note that in many cases the pixel scale used by a Canvas or a 2D image content resource will not be in proportion to the desired 3D coordinate unit scale in a Scene. @@ -693,16 +688,16 @@ Comments, tags, etc transcripts (and back ref to OCR on images etc) -### Comment Annotations +#### Comment Annotations -### Choice of Alternative Resources +#### Choice of Alternative Resources Multispectral here -### Embedded Content +#### Embedded Content e.g., painting TextualBody on Canvas @@ -713,20 +708,20 @@ It is important to be able to position the textual body of an annotation within -### Non Rectangular Segments +#### Non Rectangular Segments SvgSelector - move to SpecificResource too ^^ -### Style +#### Style Move to SpecificResource -### Rotation +#### Rotation -### Hotspot Linking and Activation +#### Hotspot Linking and Activation Move to SpecificResource @@ -826,7 +821,7 @@ partOf - ## State -## Content State +### Content State 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: @@ -940,14 +935,14 @@ Annotations with the motivation `contentState` are referred to as _content state Content States are used for the following applications: -### Load a particular view of a resource or group of resources +#### 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](content-state-2) 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 +#### Load a particular view of some resource and modify it 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: @@ -991,7 +986,7 @@ TODO: what is the processing algorithm for applying incoming `hidden` ? When a Content State annotation carries a Scene, a view might be initialized from a Content State that introduces an additional Camera that shows the user the point of interest. -### Modify the Container in a particular context +#### Modify the Container in a particular context The techniques in the previous example are also used within a published IIIF Manifest 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. The `scope` property indicates to the client that the Content State provides valuable context for displaying some aspect of a Scene or other Container. In the case of a commenting annotation, this means that the Content State should be loaded when the commenting annotation is selected or otherwise highlighted. @@ -1165,13 +1160,13 @@ Use of `scope` is permitted in annotations on any Container type, not just Scene While all AnnotationPage `items` are inherently ordered, an Annotation Page with the behavior `sequence` is explicitly a narrative, and clients should prevent (dissuade) users from jumping about. The presence of `sequence` affects the way a client should interpret the `reset` property described below. -### Content States on Manifests +#### Content States on Manifests When an annotation with the motivation `contentState` is provided via the `annotations` property of a Manifest, rather than contextually via `scope`, it is assumed to be generally available for selection by the user at any time. A client may present such as annotations as a menu of views, allowing arbitrary jumping into any Scene (or Canvas or Timeline) from any other point. // Is there some overlap here with Range? -### Processing Content States in Scopes: reset +#### Processing Content States in Scopes: reset // This may not be what we have discussed... @@ -1191,17 +1186,17 @@ Before applying the content state to the Scene, the client should reset the Scen // I am assuming reset is always true except in `sequence` - otherwise it's completely unpredictable!! or is it... arbitrary navigation, state provided by initialization content states, etc... -### Contribute additional information permanently +#### Contribute additional information permanently Rerum inbox scenario - should be covered in CS2 protocol -### activating - animation and interactions +#### activating - animation and interactions Annotations with the motivation `activating` are referred to as _activating_ annotations. There are two uses of `activating` annotations: -#### Triggering a content state +##### Triggering a content state An activating annotation links a painting annotation to a content state. When a user interacts with the painting annotation - whether through clicking it, tapping it, or other client-specific behaviors - the linked content state should be processed to modify the Scene or other Container, as in the previous examples. The painting annotation is the target of the activating annotation, and the content state is the body value. Only one content state may be specified in the body array, but the body array may include a `TextualBody` to provide a label for the interaction. The pattern is the same as for the `linking` motivation, but rather than the client opening a new browser window on the resource specified in the `body`, it applies the modification provided by the Content State. @@ -1275,7 +1270,7 @@ The activating annotation is provided in a Container's `annotations` property. I -#### Triggering a named animation in a model +##### 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. @@ -1363,7 +1358,7 @@ if the `target` is an AnimationSelector, then the `body` can ONLY be TextualBody There is a more general rule here! -### reset +#### reset See above... @@ -1422,15 +1417,15 @@ For a timeline it's the ratio of time in the recording to time in the real world -## HTTP Requests and Responses +### HTTP Requests and Responses -### URI Recommendations +#### URI Recommendations -### Requests +#### Requests -### Responses +#### Responses -### Authentication +#### Authentication From dca504005f46f86fd7b33301d890e60f10dcfb12 Mon Sep 17 00:00:00 2001 From: Michael Appleby Date: Wed, 19 Mar 2025 08:53:06 -0400 Subject: [PATCH 047/130] Remove link to Content State 2 --- source/presentation/4.0/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index 3470886c0..3cfd7a6e8 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -939,7 +939,7 @@ Content States are used for the following applications: 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](content-state-2) 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. +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 From 1d50ea8cac71827b2398a9ed8410bde68f8f9bc8 Mon Sep 17 00:00:00 2001 From: Rob Sanderson Date: Wed, 19 Mar 2025 09:22:34 -0400 Subject: [PATCH 048/130] test blocks --- source/presentation/4.0/model.md | 248 +++++++++++++++++-------------- 1 file changed, 135 insertions(+), 113 deletions(-) diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index 071e45510..6f45ef149 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -70,6 +70,110 @@ The key words _MUST_, _MUST NOT_, _REQUIRED_, _SHALL_, _SHALL NOT_, _SHOULD_, _S + + +## JSON Considerations + +This section describes features applicable to all of the Presentation API content. + +### Case Sensitivity + +Keys in JSON objects are [case sensitive][org-w3c-json-ld-case]. The cases of properties and enumerated values in IIIF Presentation API responses _MUST_ match those used in this specification. For example to specify that a resource is a Manifest, the property _MUST_ be given as `type` and not `Type` or `tYpE`, and the value _MUST_ be given as `Manifest` and not `manifest` or `manIfEsT`. + +### Properties with Multiple Values + +Any of the properties in the API that can have multiple values _MUST_ always be given as an array of values, even if there is only a single item in that array. + +{% include api/code_header.html %} +``` json-doc +{ + "thumbnail": [ + { + "id": "https://example.org/images/thumb1.jpg", + "type": "Image", + "format": "image/jpeg" + } + ] +} +``` + +### Language of Property Values +{: #language-of-property-values} + +Language _SHOULD_ be associated with strings that are intended to be displayed to the user for the `label` and `summary` properties, plus the `label` and `value` properties of the `metadata` and `requiredStatement` objects. + +The values of these properties _MUST_ be JSON objects, with the keys being the [BCP 47][org-bcp-47] language code for the language, or if the language is either not known or the string does not have a language, then the key _MUST_ be the string `none`. The associated values _MUST_ be arrays of strings, where each item is the content in the given language. + +{% include api/code_header.html %} +``` json-doc +{ + "label": { + "en": [ + "Whistler's Mother", + "Arrangement in Grey and Black No. 1: The Artist's Mother" + ], + "fr": [ + "Arrangement en gris et noir no 1", + "Portrait de la mère de l'artiste", + "La Mère de Whistler" + ], + "none": [ "Whistler (1871)" ] + } +} +``` + +Note that [BCP 47][org-bcp-47] allows the script of the text to be included after a hyphen, such as `ar-latn`, and clients should be aware of this possibility. + +In the case where multiple values are supplied, clients _MUST_ use the following algorithm to determine which values to display to the user. + +* If all of the values are associated with the `none` key, the client _MUST_ display all of those values. +* Else, the client should try to determine the user's language preferences, or failing that use some default language preferences. Then: + * If any of the values have a language associated with them, the client _MUST_ display all of the values associated with the language that best matches the language preference. + * If all of the values have a language associated with them, and none match the language preference, the client _MUST_ select a language and display all of the values associated with that language. + * If some of the values have a language associated with them, but none match the language preference, the client _MUST_ display all of the values that do not have a language associated with them. + +Note that this does not apply to [embedded][prezi30-terminology] textual bodies in Annotations, which use the Web Annotation pattern of `value` and `language` as separate properties. + +### HTML Markup in Property Values + +Minimal HTML markup _MAY_ be included for processing in the `summary` property and the `value` property in the `metadata` and `requiredStatement` objects. It _MUST NOT_ be used in `label` or other properties. This is included to allow content publishers to add links and simple formatting instructions to blocks of text. The content _MUST_ be well-formed XML and therefore _MUST_ be wrapped in an element such as `p` or `span`. There _MUST NOT_ be whitespace on either side of the HTML string, and thus the first character in the string _MUST_ be a '<' character and the last character _MUST_ be '>', allowing a consuming application to test whether the value is HTML or plain text using these. To avoid a non-HTML string matching this, it is _RECOMMENDED_ that an additional whitespace character be added to the end of the value in situations where plain text happens to start and end this way. + +In order to avoid HTML or script injection attacks, clients _MUST_ remove: + + * Tags such as `script`, `style`, `object`, `form`, `input` and similar. + * All attributes other than `href` on the `a` tag, `src` and `alt` on the `img` tag. + * All `href` attributes that start with the strings other than "http:", "https:", and "mailto:". + * CData sections. + * XML Comments. + * Processing instructions. + +Clients _SHOULD_ allow only `a`, `b`, `br`, `i`, `img`, `p`, `small`, `span`, `sub` and `sup` tags. Clients _MAY_ choose to remove any and all tags, therefore it _SHOULD NOT_ be assumed that the formatting will always be rendered. Note that publishers _MAY_ include arbitrary HTML content for processing using customized or experimental applications, and the requirements for clients assume an untrusted or unknown publisher. + +{% include api/code_header.html %} +``` json-doc +{ "summary": { "en": [ "

Short summary of the resource.

" ] } } +``` + +### JSON Description Availability + +JSON descriptions _SHOULD_ be [embedded][prezi30-terminology] within the JSON of parent resources, and _MAY_ also be available via separate requests from the HTTP(S) URI given in the resource's `id` property. Links to Content Resources _MUST_ be given as a JSON object with the `id` and `type` properties and _SHOULD_ have `format` or `profile` to give a hint as to what sort of resource is being referred to. + +{% include api/code_header.html %} +``` json-doc +{ + "rendering": [ + { + "id": "https://example.org/content/book.pdf", + "type": "Text", + "label": { "en": [ "Example Book (pdf)" ] }, + "format": "application/pdf" + } + ] +} +``` + + + ## Classes The following sub-sections define the classes used in the IIIF Presentation Data Model. The properties and relationships of the classes are defined in the following section, including which classes they are able to be used with. Only the semantics and core structural requirements are defined within this section, along with any deviations from other specifications that the classes might be drawn from. @@ -108,7 +212,12 @@ Collection Pages follow the ActivityStreams model, as also used in Annotation Co A Manifest is the primary unit of distribution of IIIF and provides a description of the structure and properties of a single item to be presented to the user. +Manifests _MUST_ be identified by a URI and it _MUST_ be an HTTP(S) URI, given in the `id` property. It _MUST_ be able to be dereferenced to retrieve the JSON description of the Manifest. +The members of a Manifest are listed in the `items` property. The members of Manifests _MUST_ be Containers, defined below, and are embedded within the Manifest. The Manifest _MAY_ have a `structures` property listing one or more [Ranges][#range] which describe additional structure of the content, such as might be rendered as a table of contents. The Manifest _MAY_ have an `annotations` property, which includes Annotation Page resources where the Annotations have the Manifest as their `target`. These Annotations _MUST NOT_ have `painting` as their `motivation`. + + +!!! Properties A Manifest _MUST_ have the following properties: [id](#id), [type](#type), [label](#label), and [items](#items) A Manfiest _SHOULD_ have the following properties: [metadata](#metadata), [summary](#summary), [provider](#provider), and [thumbnail](#thumbnail) @@ -116,11 +225,6 @@ A Manfiest _SHOULD_ have the following properties: [metadata](#metadata), [summa A Manifest _MAY_ have the following properties: [requiredStatement](#requiredStatement), [rights](#rights), [navDate](#navDate), [navPlace](#navPlace), [placeholderContainer](#placeholderContainer), [accompanyingContainer](#accompanyingContainer), [viewingDirection](#viewingDirection), [behavior](#behavior), [seeAlso](#seeAlso), [service](#service), [services](#services), [homepage](#homepage), [rendering](#rendering), [partOf](#partOf), [start](#start), [structures](#structures), and [annotations](#annotations). -Manifests _MUST_ be identified by a URI and it _MUST_ be an HTTP(S) URI, given in the `id` property. It _MUST_ be able to be dereferenced to retrieve the JSON description of the Manifest. - -The members of a Manifest are listed in the `items` property. The members of Manifests _MUST_ be Containers, defined below, and are embedded within the Manifest. The Manifest _MAY_ have a `structures` property listing one or more [Ranges][#range] which describe additional structure of the content, such as might be rendered as a table of contents. The Manifest _MAY_ have an `annotations` property, which includes Annotation Page resources where the Annotations have the Manifest as their `target`. These Annotations _MUST NOT_ have `painting` as their `motivation`. - - ### Container Classes {: #containers} @@ -1510,7 +1614,21 @@ The value _MUST_ be a string. ##### unit -FIXME: possible values are 'm' and 's' and 'relative' and not 'smoot' +FIXME: possible values are 'm' and 's' and 'relative' + + +##### value + + +metadata: + +{label: value: {"en": ["foo"]}} + +UnitValue + +unit: value: 0.1234123 + +FIXME: use scoped context for UnitValue to change the meaning of `value` @@ -1602,112 +1720,9 @@ Additional motivations may be added to the Annotation to further clarify the int +## JSON-LD and Extensions - - - - -## 4. JSON-LD Considerations - -This section describes features applicable to all of the Presentation API content. For the most part, these are features of the JSON-LD specification that have particular uses within the API. - -### 4.1. Case Sensitivity - -Terms in JSON-LD are [case sensitive][org-w3c-json-ld-case]. The cases of properties and enumerated values in IIIF Presentation API responses _MUST_ match those used in this specification. For example to specify that a resource is a Manifest, the property _MUST_ be given as `type` and not `Type` or `tYpE`, and the value _MUST_ be given as `Manifest` and not `manifest` or `manIfEsT`. - -### 4.2. Resource Representations - -Resource descriptions _SHOULD_ be [embedded][prezi30-terminology] within the JSON description of parent resources, and _MAY_ also be available via separate requests from the HTTP(S) URI given in the resource's `id` property. Links to resources _MUST_ be given as a JSON object with the `id` and `type` properties and _SHOULD_ have `format` or `profile` to give a hint as to what sort of resource is being referred to. - -{% include api/code_header.html %} -``` json-doc -{ - "rendering": [ - { - "id": "https://example.org/content/book.pdf", - "type": "Text", - "label": { "en": [ "Example Book (pdf)" ] }, - "format": "application/pdf" - } - ] -} -``` - -### 4.3. Properties with Multiple Values - -Any of the properties in the API that can have multiple values _MUST_ always be given as an array of values, even if there is only a single item in that array. - -{% include api/code_header.html %} -``` json-doc -{ - "thumbnail": [ - { - "id": "https://example.org/images/thumb1.jpg", - "type": "Image", - "format": "image/jpeg" - } - ] -} -``` - -### 4.4. Language of Property Values -{: #language-of-property-values} - -Language _MAY_ be associated with strings that are intended to be displayed to the user for the `label` and `summary` properties, plus the `label` and `value` properties of the `metadata` and `requiredStatement` objects. - -The values of these properties _MUST_ be JSON objects, with the keys being the [BCP 47][org-bcp-47] language code for the language, or if the language is either not known or the string does not have a language, then the key _MUST_ be the string `none`. The associated values _MUST_ be arrays of strings, where each item is the content in the given language. - -{% include api/code_header.html %} -``` json-doc -{ - "label": { - "en": [ - "Whistler's Mother", - "Arrangement in Grey and Black No. 1: The Artist's Mother" - ], - "fr": [ - "Arrangement en gris et noir no 1", - "Portrait de la mère de l'artiste", - "La Mère de Whistler" - ], - "none": [ "Whistler (1871)" ] - } -} -``` - -Note that [BCP 47][org-bcp-47] allows the script of the text to be included after a hyphen, such as `ar-latn`, and clients should be aware of this possibility. - -In the case where multiple values are supplied, clients _MUST_ use the following algorithm to determine which values to display to the user. - -* If all of the values are associated with the `none` key, the client _MUST_ display all of those values. -* Else, the client should try to determine the user's language preferences, or failing that use some default language preferences. Then: - * If any of the values have a language associated with them, the client _MUST_ display all of the values associated with the language that best matches the language preference. - * If all of the values have a language associated with them, and none match the language preference, the client _MUST_ select a language and display all of the values associated with that language. - * If some of the values have a language associated with them, but none match the language preference, the client _MUST_ display all of the values that do not have a language associated with them. - -Note that this does not apply to [embedded][prezi30-terminology] textual bodies in Annotations, which use the Web Annotation pattern of `value` and `language` as separate properties. - -### 4.5. HTML Markup in Property Values - -Minimal HTML markup _MAY_ be included for processing in the `summary` property and the `value` property in the `metadata` and `requiredStatement` objects. It _MUST NOT_ be used in `label` or other properties. This is included to allow content publishers to add links and simple formatting instructions to blocks of text. The content _MUST_ be well-formed XML and therefore _MUST_ be wrapped in an element such as `p` or `span`. There _MUST NOT_ be whitespace on either side of the HTML string, and thus the first character in the string _MUST_ be a '<' character and the last character _MUST_ be '>', allowing a consuming application to test whether the value is HTML or plain text using these. To avoid a non-HTML string matching this, it is _RECOMMENDED_ that an additional whitespace character be added to the end of the value in situations where plain text happens to start and end this way. - -In order to avoid HTML or script injection attacks, clients _MUST_ remove: - - * Tags such as `script`, `style`, `object`, `form`, `input` and similar. - * All attributes other than `href` on the `a` tag, `src` and `alt` on the `img` tag. - * All `href` attributes that start with the strings other than "http:", "https:", and "mailto:". - * CData sections. - * XML Comments. - * Processing instructions. - -Clients _SHOULD_ allow only `a`, `b`, `br`, `i`, `img`, `p`, `small`, `span`, `sub` and `sup` tags. Clients _MAY_ choose to remove any and all tags, therefore it _SHOULD NOT_ be assumed that the formatting will always be rendered. Note that publishers _MAY_ include arbitrary HTML content for processing using customized or experimental applications, and the requirements for clients assume an untrusted or unknown publisher. - -{% include api/code_header.html %} -``` json-doc -{ "summary": { "en": [ "

Short summary of the resource.

" ] } } -``` - -### 4.6. Linked Data Context and Extensions +### JSON-LD Contexts and Extensions The top level resource in the response _MUST_ have the `@context` property, and it _SHOULD_ appear as the very first key/value pair of the JSON representation. This tells Linked Data processors how to interpret the document. The IIIF Presentation API context, below, _MUST_ occur once per response in the top-most resource, and thus _MUST NOT_ appear within [embedded][prezi30-terminology] resources. For example, when embedding a Canvas within a Manifest, the Canvas will not have the `@context` property. @@ -1734,7 +1749,7 @@ Any additional properties beyond those defined in this specification or the Web The JSON representation _MUST NOT_ include the `@graph` key at the top level. This key might be created when serializing directly from RDF data using the JSON-LD 1.0 compaction algorithm. Instead, JSON-LD framing and/or custom code should be used to ensure the structure of the document is as defined by this specification. -### 4.7. Term Collisions between Contexts +### Term Collisions between Contexts There are some common terms used in more than one JSON-LD context document. Every attempt has been made to minimize these collisions, but some are inevitable. In order to know which specification is in effect at any given point, the class of the resource that has the property is the primary governing factor. Thus properties on Annotation based resources use the context from the [Web Annotation Data Model][org-w3c-webanno], whereas properties on classes defined by this specification use the IIIF Presentation API context's definition. @@ -1750,7 +1765,14 @@ The following properties are defined by both, and the IIIF representation is mor The `rights`, `partOf`, and `items` properties are defined by both in the same way. -### 4.8. Keyword Mappings +### Keyword Mappings The JSON-LD keywords `@id`, `@type` and `@none` are mapped to `id`, `type` and `none` by the Presentation API [linked data context][prezi30-ldce]. Thus in content conforming to this version of the Presentation API, the only JSON key beginning with `@` will be `@context`. However, the content may include data conforming to older specifications or external specifications that use keywords beginning with `@`. Clients should expect to encounter both syntaxes. +### Registries of Values + +FIXME: Describe the registries + + + + From 3600f9f97e29e527412a15706b47e128d0ed298a Mon Sep 17 00:00:00 2001 From: Rob Sanderson Date: Wed, 19 Mar 2025 10:24:27 -0400 Subject: [PATCH 049/130] testing class --- source/presentation/4.0/index.md | 67 ++++++++++++++----- source/presentation/4.0/model.md | 110 +++++++++++++++++++++++++------ 2 files changed, 141 insertions(+), 36 deletions(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index 3cfd7a6e8..f17d41878 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -69,14 +69,6 @@ Presentation, the clue is in the name 9. Manuscript (integration) - -1. Digitized books and manuscripts (images, paged things, transcripts, translations) -2. Artworks and Maps (navPlace, maybe commenting annos) -3. Audio and Video recordings (time-based, transcriptions) -4. 3D scans of objects (3D) -5. Periodicals (Collections, Ranges, navDate) -6. Storytelling and exhibitions (State, annotations) - see Terminology at the end Mention model.md @@ -84,6 +76,8 @@ Mention model.md Mention cookbook +Consider diagrams + ## Foundations @@ -272,17 +266,59 @@ Sometimes, two different formats derived from the same source may have slightly ### 3D -Need to get PointSelector in early +3D Content Resources are painted into Scenes. + +Scenes have infinite height (y axis), width (x axis) and depth (z axis), where 0 on each axis (the origin of the coordinate system) is treated as the center of the scene's space. + +The positive y axis points upwards, the positive x axis points to the right, and the positive z axis points forwards (a [right-handed cartesian coordinate system](https://en.wikipedia.org/wiki/Right-hand_rule)). + + +#### Example: Static 3D Model of a Spacesuit + + +This example is a Manifest with a single Scene, with a single model of a space suit painted at the Scene's origin. + + + + +The model also has its own local coordinate space, which may be scaled differently from the Scene's coordinate space. + +Unlike when you paint a resource into a Canvas where it fills the space, instead targeting the Scene is equivalent to having a point selector that targets the origin. + + + + +```jsonc + +manifest + scene + annotationpage + annotation + model +``` + + +model +light Ambient color +camera (put it in the right place looking -Z) near, far, fieldOfView, lookAt (note that Orthographic w/ viewHeight possible) +backgroundColor: #000 +point selector for positioning + + +#### Example: 3D Model of a Chessboard + +Chessboard is a Canvas with image +more than one model +transforms for scale and rotation +Scene in Scene +Exclude +interactionMode + -Example 3D 1 -Example 3D 2 -backgroundColor, exclude, color, intensity, far, fieldOfView, near, viewHeight, interactionMode, lookAt -Scenes have infinite height (y axis), width (x axis) and depth (z axis), where 0 on each axis (the origin of the coordinate system) is treated as the center of the scene's space. -The positive y axis points upwards, the positive x axis points to the right, and the positive z axis points forwards (a [right-handed cartesian coordinate system](https://en.wikipedia.org/wiki/Right-hand_rule)). The axes of the coordinate system are measured in arbitrary units and these units do not necessarily correspond to any physical unit of measurement. This allows arbitrarily scaled models to be used, including very small or very large, without needing to deal with very small or very large values. If there is a correspondence to a physical scale, then this can be asserted using the physical dimensions pattern(fwd-ref-to-phys-dims). @@ -491,7 +527,6 @@ If any of these properties are not specified explicitly, they default to the cho drawing of a geometrical frustrum truncated by near and far distances - The first Camera defined and not hidden in a Scene is the default Camera used to display Scene contents. If the Scene does not have any Cameras defined within it, then the client MUST provide a default Camera. The type, properties and position of this default camera are client-dependent. ```json @@ -508,8 +543,6 @@ The first Camera defined and not hidden in a Scene is the default Camera used to ##### Light -One or more Lights MUST be present within the Scene in order to have objects within it be visible to the Cameras. - This specification defines four types of Light: | Class | Description | diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index 6f45ef149..d89f29aad 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -70,8 +70,6 @@ The key words _MUST_, _MUST NOT_, _REQUIRED_, _SHALL_, _SHALL NOT_, _SHOULD_, _S - - ## JSON Considerations This section describes features applicable to all of the Presentation API content. @@ -178,9 +176,16 @@ JSON descriptions _SHOULD_ be [embedded][prezi30-terminology] within the JSON of The following sub-sections define the classes used in the IIIF Presentation Data Model. The properties and relationships of the classes are defined in the following section, including which classes they are able to be used with. Only the semantics and core structural requirements are defined within this section, along with any deviations from other specifications that the classes might be drawn from. -The descriptions also do not define how the classes are used, which is done in the Presentation API Processing Model. +Each class has a + +The descriptions also do not define how the classes are used, which is done in the Presentation API Overview. + + ### Collection +{: #Collection} + +`"type": "Collection"` A Collection is an ordered list of Manifests, and/or Collections. @@ -199,7 +204,10 @@ Collections with an empty `items` property are allowed but discouraged. For exa Collections or Manifests [referenced][prezi30-terminology] in the `items` property _MUST_ have the `id`, `type` and `label` properties. They _SHOULD_ have the `thumbnail` property. -#### CollectionPage +#### Collection Page +{: #CollectionPage} + +Class: `CollectionPage` A Collection Page is an arbitrary division of members within the Collection to make it easier to consume. @@ -214,6 +222,8 @@ A Manifest is the primary unit of distribution of IIIF and provides a descriptio Manifests _MUST_ be identified by a URI and it _MUST_ be an HTTP(S) URI, given in the `id` property. It _MUST_ be able to be dereferenced to retrieve the JSON description of the Manifest. +The `type` property of a Manifest _MUST_ have the value `"Manifest"`. + The members of a Manifest are listed in the `items` property. The members of Manifests _MUST_ be Containers, defined below, and are embedded within the Manifest. The Manifest _MAY_ have a `structures` property listing one or more [Ranges][#range] which describe additional structure of the content, such as might be rendered as a table of contents. The Manifest _MAY_ have an `annotations` property, which includes Annotation Page resources where the Annotations have the Manifest as their `target`. These Annotations _MUST NOT_ have `painting` as their `motivation`. @@ -242,9 +252,17 @@ A Timeline is a Container that represents only a temporal duration, measured in A Canvas is a Container that represents a particular rectangular 2 dimensional view of the object and has content resources associated with it or with parts of it. This aspect ratio is defined by the `height` and `width` properties. A Canvas _MAY_ also have a duration, given in the `duration` property, allowing audio and video to be correctly positioned in time as well as the 2 dimensional space. +FIXME: arbitrary units + #### Scene -A Scene is a Container that represents an infinitely large three-dimensional space, with an optional duration. As the Scene is infinite, it does not have `height`, `width` or `depth` properties. +A Scene is a Container that represents an infinitely large three-dimensional space, with an optional `duration` property. Scenes have infinite height (y axis), width (x axis) and depth (z axis), where 0 on each axis (the origin of the coordinate system) is treated as the center of the scene's space. From a perspective looking along the z axis towards negative infinity, the positive y axis points upwards and the positive x axis points to the right (a [right-handed Cartesian coordinate system](https://en.wikipedia.org/wiki/Right-hand_rule)). + +diagram of Right handed cartesian coordinate system + +The axes of the coordinate system are measured in arbitrary units and these units do not necessarily correspond to any physical unit of measurement, unless `spatialScale` is supplied. + + ### Annotation Classes {: #annotations} @@ -264,7 +282,7 @@ Content that is to be rendered as part of the Container _MUST_ be associated by Note that the Web Annotation data model defines different patterns for the `value` property compared to IIIF, when used within an Annotation. The `value` of a Textual Body or a Fragment Selector, for example, are strings rather than JSON objects with languages and values. Care must be taken to use the correct string form in these cases. -#### AnnotationCollection +#### Annotation Collection Annotation Collections allow groups of Annotations to be recorded. For example, all of the English translation Annotations of a medieval French document could be kept separate from the transcription or an edition in modern French, or the director's commentary on a film can be separated from the script. @@ -273,7 +291,7 @@ Annotation Collections _MUST_ have a URI, and it _SHOULD_ be an HTTP(S) URI. The Annotation Collections are paged rather than enumerated. The first page of items is linked using the `first` property, and the last page with the `last` property. The pages link to the next and previous pages in a chain, using the `next` and `prev` properties respectively. -#### AnnotationPage +#### Annotation Page An ordered list of Annotations, typically associated with a Container, but may be referenced from other types of resource as well. Annotation Pages enumerate and order lists of Annotations, in the same way that Collection Pages order lists of Manifests and Collections within the containing Collection. @@ -286,11 +304,11 @@ The definition of `label` in the Web Annotation specification does not produce J {: .warning} -#### SpecificResource +#### Specific Resource A Specific Resource is a resource in the context of an Annotation. They are used to record further properties or relationships needed to understand the particular contextual use, such as which part of the resource is used or how it should be rendered. In IIIF, the Specific Resource model from the Web Annotation Data Model has some additional properties beyond those defined by the W3C, such as `transform`. -#### TextualBody +#### Textual Body A Textual Body is an embedded resource within an Annotation that carries, as the name suggests, a text as the body of the Annotation. It is defined by the Web Annotation Data Model, and this specification defines a new property for `position` that allows it to be positioned within a Container. @@ -298,6 +316,7 @@ A Textual Body is an embedded resource within an Annotation that carries, as the A Choice is a Web Annotation construction that allows one entry from a list to be selected for processing or display. This specification allows `behavior` to be added to a Choice to influence how it is processed. + ### Content Resources Content resources are resources on the Web such as images, audio, video, or text which can be associated with a Container via an Annotation, or provide a representation of any resource. @@ -316,7 +335,7 @@ Containers _MAY_ be treated as content resources for the purposes of annotating The Web Annotation Data Model defines several Selectors, which describe how to find a specific segment of that resource to be used. As noted, the nature of Selectors are dependent on the type of resources that they select out of, and the methods needed for those descriptions will vary. The Selectors from the Web Annotation Data Model and other sources can be used within the IIIF Data Model. This specification defines additional Selector classes for use. -#### PointSelector +#### Point Selector There are common use cases in which a point, rather than a range or area, is the target of the Annotation. For example, putting a pin in a map should result in an exact point, not a very small rectangle. Points in time are not very short durations, and user interfaces should also treat these differently. This is particularly important when zooming in (either spatially or temporally) beyond the scale of the frame of reference. @@ -330,9 +349,7 @@ Point Selectors have the following properties: |------|-------------| | id | The HTTP(S) URI of the selector | | type | The class of the selector, which must be "PointSelector" | -| x | A number (floating point or integer) giving the x coordinate of the point, relative to the dimensions of the source resource | -| y | A number (floating point or integer) giving the y coordinate of the point, relative to the dimensions of the source resource | -| z | A number (floating point) giving the z coordinate of the point, relative to the dimensions of the source resource | + | instant | A number (floating point) giving the time of the point in seconds, relative to the duration of the source resource | @@ -348,7 +365,7 @@ Point Selectors have the following properties: ``` -#### WktSelector +#### WKT Selector Well-known text, or WKT, is an ISO standard method for describing 2 and 3 dimensional geometries. This selector thus goes beyond what the Web Annotation's SvgSelector enables by incorporating the z axis, as well as additional types of selection such as MultiPolygon. Additional types, such as CIRCULARSTRING may also be supported. @@ -371,7 +388,7 @@ WKT Selectors have the following properties: -#### AudioContentSelector +#### Audio Content Selector Video content resources consist of both visual and audio content within the same bit-level representation. There are situations when it is useful to refer to only one aspect of the content – either the visual or the audio, but not both. For example, an Annotation might associate only the visual content of a video that has spoken English in the audio, and an audio file that has the translation of that content in Spanish. The Audio Content Selector selects all of the audio content from an A/V content resource, and may be further refined with subsequent selectors to select a segment of it. @@ -391,7 +408,7 @@ Audio Content Selectors have the following properties: ``` -#### VisualContentSelector +#### Visual Content Selector Similar to Audio Content Selectors, Visual Content Selectors select the visual aspects of the content of an A/V content resource. They may be further refined by subsequent selectors that select an area or temporal segment of it. @@ -410,7 +427,7 @@ Visual Content Selectors have the following properties: ``` -#### AnimationSelector +#### Animation Selector More interactive content resources, such as 3d models, may have activatable animations or similar features. For example, a model of a box might have an animation that opens the lid and a second animation that closes the lid. In order to activate those animations, they need to be selectable, and thus the specification defines an Animation Selector. @@ -448,25 +465,74 @@ The included Containers and parts of Containers need not be contiguous or in the Ranges _MAY_ link to an Annotation Collection that has the content of the Range using the `supplementary` property. The [referenced][prezi30-terminology] Annotation Collection will contain Annotations that target the Containers within the Range and link content resources to those Containers. + ### Scene Components #### Cameras + +A Camera provides a view of a region of the Scene's space from a particular position within the Scene; the client constructs a viewport into the Scene and uses the view of one or more Cameras to render that region. The size and aspect ratio of the viewport is client and device dependent. + ##### PerspectiveCamera + +`PerspectiveCamera` mimics the way the human eye sees, in that objects further from the camera are smaller + +!!! Properties +... + + +```json +{ + "id": "https://example.org/iiif/camera/1", + "type": "PerspectiveCamera", + "near": 1.0, + "far": 100.0, + "fieldOfView": 45.0 +} +``` + + ##### OrthographicCamera +`OrthographicCamera` removes visual perspective, resulting in object size remaining constant regardless of its distance from the camera + + + + + + + + #### Lights + + ##### AmbientLight + +AmbientLight evenly illuminates all objects in the scene, and does not have a direction or position. + + ##### DirectionalLight + +DirectionalLight emits in a specific direction as if it is infinitely far away and the rays produced from it are all parallel. It does not have a specific position. + + ##### PointLight + + PointLight emits from a single point within the scene in all directions. + ##### SpotLight +SpotLight emits a cone of light from a single point in a given direction. + + + + #### Transforms ##### TranslateTransform ##### RotateTransform ##### ScaleTransform -### Other Classes +### Utility Classes #### Agent #### Service #### UnitValue @@ -1684,16 +1750,22 @@ The value _MUST_ be a positive integer. ``` json-doc { "width": 1200 } ``` + ##### x {: #x} +A number (floating point or integer) giving the x coordinate of the point, relative to the dimensions of the source resource + + ##### y {: #y} +A number (floating point or integer) giving the y coordinate of the point, relative to the dimensions of the source resource + ##### z {: #z} - +A number (floating point) giving the z coordinate of the point, relative to the dimensions of the source resource From b83852b726896e3bcf51e90c57d55d7c40b9b12b Mon Sep 17 00:00:00 2001 From: Rob Sanderson Date: Wed, 19 Mar 2025 10:57:57 -0400 Subject: [PATCH 050/130] model stuff --- source/presentation/4.0/index.md | 28 +++++++---- source/presentation/4.0/model.md | 82 +++++++++++++++++++++----------- 2 files changed, 73 insertions(+), 37 deletions(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index f17d41878..7dff58071 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -318,12 +318,9 @@ interactionMode +This (no units for scale) allows arbitrarily scaled models to be used, including very small or very large, without needing to deal with very small or very large values. If there is a correspondence to a physical scale, then this can be asserted using the physical dimensions pattern(fwd-ref-to-phys-dims). -The axes of the coordinate system are measured in arbitrary units and these units do not necessarily correspond to any physical unit of measurement. This allows arbitrarily scaled models to be used, including very small or very large, without needing to deal with very small or very large values. If there is a correspondence to a physical scale, then this can be asserted using the physical dimensions pattern(fwd-ref-to-phys-dims). - -diagram of Right handed cartesian coordinate system - ``` ``` @@ -490,9 +487,6 @@ Example Annotation that positions a model at a point within a Scene: Annotations may alternately use a type of Selector called a `WktSelector` to align the Annotation to a region with the Scene that is not the Scene's origin. WktSelectors have a single property, `value`, which is a string conforming to a WKT Linestring, LineStringZ, Polygon, or PolygonZ list of 2D or 3D coordinate points. Whether and how a region defined by a WktSelector may be translated to a single 2D or 3D coordinate point, for targeting or other purposes, is client-dependent. -
-❓Does WKTSelector have a duration/instant property? -
Example Annotation that comments on a 3D polygon within a Scene: @@ -501,6 +495,9 @@ Todo add example ``` +### Give example of refinedBy ? e.g. WktSelector + Instant + + #### Scene-Specific Resources @@ -515,7 +512,10 @@ This specification defines two types of Camera: | `PerspectiveCamera` | `PerspectiveCamera` mimics the way the human eye sees, in that objects further from the camera are smaller | | `OrthographicCamera` | `OrthographicCamera` removes visual perspective, resulting in object size remaining constant regardless of its distance from the camera | -Cameras are positioned within the Scene facing in a specified direction. Both position and direction are defined through the Annotation which adds the Camera to the Scene, described below in the sections on [Painting Annotations][], [Transforms][], and [Relative Rotation][]. If either the position or direction is not specified, then the position defaults to the origin, and facing direction defaults to pointing along the z axis towards negative infinity. The camera's up direction by default points along the y axis towards positive infinity, but this may be modified by transforms. +Cameras are positioned within the Scene facing in a specified direction. Both position and direction are defined through the Annotation which adds the Camera to the Scene, described below in the sections on [Painting Annotations][], [Transforms][], and [Relative Rotation][]. + +If either the position or direction is not specified, then the position defaults to the origin, and facing direction defaults to pointing along the z axis towards negative infinity. + The region of the Scene's space that is observable by the camera is bounded by two planes orthogonal to the direction the camera is facing, given in the `near` and `far` properties, and a vertical projection angle that provides the top and bottom planes of the region. @@ -558,7 +558,11 @@ SpotLight has an additional property of `angle`, specified in degrees, which is diagram of cone geometry showing how the angle of the cone is defined -Lights that require a position and/or direction have these through the Annotation which associates them with the Scene, described below in the sections on [Painting Annotations][] and [Transforms][]. If a Light does not have an explicit direction, then the default is in the negative y direction (downwards). If a Light does not have an explicit position in the coordinate space, then the default is at the origin. +Lights that require a position and/or direction have these through the Annotation which associates them with the Scene, described below in the sections on [Painting Annotations][] and [Transforms][]. + + + If a Light does not have an explicit direction, then the default is in the negative y direction (downwards). + If a Light does not have an explicit position in the coordinate space, then the default is at the origin. This specification does not define other aspects of Lights, such as the rate of decay of the intensity of the light over a distance, the maximum range of the light, or the penumbra of a cone. Implementation of these aspects is client-dependent. @@ -1211,10 +1215,14 @@ The client should reset the Container to its original state before applying the { "type": "Annotation", "motivation": ["contentState"], - "reset": true + "behavior": ["reset"] } ``` +behavior: `linear-nav` -- cannot jump around only one step forward/back + + + Before applying the content state to the Scene, the client should reset the Scene to its original state as provided by the Manifest. // I am assuming reset is always true except in `sequence` - otherwise it's completely unpredictable!! or is it... arbitrary navigation, state provided by initialization content states, etc... diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index d89f29aad..e4ab3db8d 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -174,13 +174,9 @@ JSON descriptions _SHOULD_ be [embedded][prezi30-terminology] within the JSON of ## Classes -The following sub-sections define the classes used in the IIIF Presentation Data Model. The properties and relationships of the classes are defined in the following section, including which classes they are able to be used with. Only the semantics and core structural requirements are defined within this section, along with any deviations from other specifications that the classes might be drawn from. - -Each class has a - -The descriptions also do not define how the classes are used, which is done in the Presentation API Overview. - +The following sub-sections define the classes used in the IIIF Presentation Data Model. Only the semantics and core structural requirements are defined within this section, along with any deviations from other specifications that the classes might be drawn from. The descriptions do not define how the classes are used together, which is done in the Presentation API Overview. +The name of each class is given at the top of its definition below. The exact string _MUST_ be used as the value of `type` in the JSON for the class. ### Collection {: #Collection} @@ -337,20 +333,13 @@ The Web Annotation Data Model defines several Selectors, which describe how to f #### Point Selector +`"type": "PointSelector"` + There are common use cases in which a point, rather than a range or area, is the target of the Annotation. For example, putting a pin in a map should result in an exact point, not a very small rectangle. Points in time are not very short durations, and user interfaces should also treat these differently. This is particularly important when zooming in (either spatially or temporally) beyond the scale of the frame of reference. * FIXME: either supply instant, or all applicable dimensions for the source - - -Point Selectors have the following properties: - -| Name | Description | -|------|-------------| -| id | The HTTP(S) URI of the selector | -| type | The class of the selector, which must be "PointSelector" | - -| instant | A number (floating point) giving the time of the point in seconds, relative to the duration of the source resource | + list properties here like manifest ```json @@ -472,6 +461,16 @@ Ranges _MAY_ link to an Annotation Collection that has the content of the Range A Camera provides a view of a region of the Scene's space from a particular position within the Scene; the client constructs a viewport into the Scene and uses the view of one or more Cameras to render that region. The size and aspect ratio of the viewport is client and device dependent. +FIXME: If either the position or direction is not specified, then the position defaults to the origin, and facing direction defaults to pointing along the z axis towards negative infinity. + +The region of the Scene's space that is observable by the camera is bounded by two planes orthogonal to the direction the camera is facing, given in the `near` and `far` properties, (PERSPECTIVE) and a vertical projection angle that provides the top and bottom planes of the region. (viewHeight?) + + +##### OrthographicCamera + +`OrthographicCamera` removes visual perspective, resulting in object size remaining constant regardless of its distance from the camera + + ##### PerspectiveCamera `PerspectiveCamera` mimics the way the human eye sees, in that objects further from the camera are smaller @@ -491,9 +490,7 @@ A Camera provides a view of a region of the Scene's space from a particular posi ``` -##### OrthographicCamera -`OrthographicCamera` removes visual perspective, resulting in object size remaining constant regardless of its distance from the camera @@ -505,32 +502,50 @@ A Camera provides a view of a region of the Scene's space from a particular posi #### Lights -##### AmbientLight -AmbientLight evenly illuminates all objects in the scene, and does not have a direction or position. +##### Ambient Light + +Ambient Lights evenly illuminates all objects in the scene, and does not have a direction or position. -##### DirectionalLight +##### Directional Light -DirectionalLight emits in a specific direction as if it is infinitely far away and the rays produced from it are all parallel. It does not have a specific position. +Directional Lights emits in a specific direction as if it is infinitely far away and the rays produced from it are all parallel. It does not have a specific position. + If a DirectionalLight does not have an explicit direction, then the default is in the negative y direction (downwards). -##### PointLight - PointLight emits from a single point within the scene in all directions. +##### Point Light -##### SpotLight + Point Lights emits from a single point within the scene in all directions. -SpotLight emits a cone of light from a single point in a given direction. +##### Spot Light +Spot Lights emit a cone of light from a single point in a given direction. + + If a SpotLight does not have an explicit direction, then the default is in the negative y direction (downwards). #### Transforms -##### TranslateTransform + +here are the rules about transforms? + + + ##### RotateTransform + +A RotateTransform rotates the local coordinate space around the given axis in a counter-clockwise direction around the axis itself (e.g. around a pivot point of 0 on the axis). A point that was at x=1,y=1 and was rotated 90 degrees around the x axis would be at x=1,y=0,z=1. If an axis value is not specified, then it is not changed, resulting in a default of 0.0 + + ##### ScaleTransform +A ScaleTransform applies a multiplier to one or more axes in the local coordinate space. A point that was at 3.5, after applying a ScaleTransform of 2.0 would then be at 7.0. If an axis value is not specified, then it is not changed, resulting in a default of 1.0 + +##### TranslateTransform + +A TranslateTransform moves all of the objects in the local coordinate space the given distance along the axis. A point that was at x=1.0, after applying a TranslateTransform of x=1.0 would be at x=2.0. If an axis value is not specified then it is not changed, resulting in a default of 0.0 + ### Utility Classes #### Agent @@ -852,6 +867,15 @@ The existence of an HTTP(S) URI in the `id` property does not mean that the URI ``` json-doc { "id": "https://example.org/iiif/1/manifest" } ``` + +##### instant +{: #instant} + +A number (floating point) giving the time of the point in seconds, relative to the duration of the source resource + +FIXME: fix + + ##### intensity {: #intensity} @@ -1649,6 +1673,10 @@ _Summary here_ The value of this property is an array of JSON objects, each of which is a Transform. +Process them in order. + + + ##### type {: #type} From 998ddbd6be61759ba66abf3ac42a1a1466fb508b Mon Sep 17 00:00:00 2001 From: tomcrane Date: Wed, 19 Mar 2025 13:16:44 -0400 Subject: [PATCH 051/130] linear-nav --- source/presentation/4.0/index.md | 66 +++++++++++++++++++++++++++++--- 1 file changed, 60 insertions(+), 6 deletions(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index 7dff58071..a669e93ee 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -1205,22 +1205,76 @@ When an annotation with the motivation `contentState` is provided via the `annot #### Processing Content States in Scopes: reset -// This may not be what we have discussed... - When a Content State is applied to a Container such as a Scene, it is assumed to be a "diff" - for example if 3 cameras and 4 lights are already present in the Scene, and a Content State asserts a single new Camera, the default behavior is to add this fourth Camera to the Scene and leave the existing resources as they are. -The client should reset the Container to its original state before applying the diff operation. However, for narratives that cumulatively build a Scene this may lead to excessively verbose Manifests. When moving through the items of an Annotation page with the behavior `sequence`, the Container is not reset and the diff is cumulative; modifications from one `scope` persist into the next. If this behavior is not wanted, the `reset` property of the content state annotation should be set to `true`: +The client should reset the Container to its original state before applying the diff operation. However, for narratives that cumulatively build a Scene this may lead to excessively verbose Manifests. When moving through the items of an Annotation page with the behavior `linear-nav`, the Container is not reset and the diff is cumulative; modifications from one `scope` persist into the next. This can be overridden for an individual annotation with the behavior `reset`: + +`linear-nav` does not inherit, but `reset` does. `reset` is the default behavior for AnnotationPage and Annotation. ```json { - "type": "Annotation", - "motivation": ["contentState"], - "behavior": ["reset"] + // a story, but we reset the Scene for each content state + "type": "AnnotationPage", + "behavior": ["linear-nav"], + "items": [ + + ] } ``` +```json +{ + // a story, but the application of content-state is cumulative + // what if you go backwards? + // What if other content states have been applied before you start the story? + // **** Is linear-nav implicitly reset on the first anno? + // Should all anno pages reset the Scene - no because I might send you a view with a content state + "type": "AnnotationPage", + "behavior": ["linear-nav", "no-reset"], // no-reset is a behavior for the annos not the page + "items": [ + + ] +} +``` + +```jsonc +[ + { + "id": "https://.../step-1", + "type": "Annotation", + "motivation": ["contentState"] + // if you really want to ensure that any ad-hoc applied content states are wiped out, + // then put an explicit reset here. But usually, we can start the nav by applying + // the content state in the scope to the Scene without worrying that someone has + // modified the Scene already. + }, + // .... + + + { + "id": "https://.../step-20", + "type": "Annotation", + "motivation": ["contentState"] + // inherit no-reset + }, + + + { + // However, this particular step (step 37) needs to reset the Scene to the initial state. + "id": "https://.../step-37", + "type": "Annotation", + "motivation": ["contentState"], + "behavior": ["reset"] + } +] +``` + behavior: `linear-nav` -- cannot jump around only one step forward/back +client _MUST_ support forward nav and _MAY_ support backward nav + +If you go backwards from step n in a linear-nav, **and** you have applied one or more content states during the linear-nav, the client _MAY_ reset the whole Scene to default condition and then replay the linear-nav up to step n-1. (client doesn't have to maintain infinite undo history) + Before applying the content state to the Scene, the client should reset the Scene to its original state as provided by the Manifest. From 17fb09ceadd432e6c8262fa19057184af520a6cc Mon Sep 17 00:00:00 2001 From: Rob Sanderson Date: Wed, 19 Mar 2025 14:25:51 -0400 Subject: [PATCH 052/130] Audio --- source/presentation/4.0/index.md | 21 ++++++-- source/presentation/4.0/model.md | 87 +++++++++++++++++++++++++++++++- 2 files changed, 103 insertions(+), 5 deletions(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index a669e93ee..fc8fb49a0 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -278,9 +278,6 @@ The positive y axis points upwards, the positive x axis points to the right, and This example is a Manifest with a single Scene, with a single model of a space suit painted at the Scene's origin. - - - The model also has its own local coordinate space, which may be scaled differently from the Scene's coordinate space. Unlike when you paint a resource into a Canvas where it fills the space, instead targeting the Scene is equivalent to having a point selector that targets the origin. @@ -318,6 +315,8 @@ interactionMode + + This (no units for scale) allows arbitrarily scaled models to be used, including very small or very large, without needing to deal with very small or very large values. If there is a correspondence to a physical scale, then this can be asserted using the physical dimensions pattern(fwd-ref-to-phys-dims). @@ -450,6 +449,22 @@ It is an error to select a temporal region of a Scene that does not have a `dura An annotation that targets a Scene using a PointSelector without any temporal refinement implicitly targets the Scene's entire duration. +Audio and 3D + + +AmbientAudio (everywhere) +PointAudio (sphere) +SpotAudio (cone) + + source: Audio (id, type, format, profile, duration, label) + volume: UnitValue (value: 0.3, unit: relative) + angle: degrees of the cone, per SpotLight + +Ambient and Point can be painted on to Canvas +hidden on audio = inaudible + + + All resources that can be added to a Scene have an implicit (e.g. Lights, Cameras) or explicit (e.g. Models, Scenes), local coordinate space. If a resource does not have an explicit coordinate space, then it is positioned at the origin of its coordinate space. In order to add a resource with its local coordinate space into a Scene with its own coordinate space, these spaces must be aligned. This done by aligning the origins of the two coordinate spaces. Annotations may use a type of Selector called a `PointSelector` to align the Annotation to a point within the Scene that is not the Scene's origin. PointSelectors have three spatial properties, `x`, `y` and `z` which give the value on that axis. They also have a temporal property `instant` which can be used if the Scene has a duration, which gives the temporal point in seconds from the start of the duration, the use of which is defined in the [section on Scenes with Durations](). diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index e4ab3db8d..6d54613bd 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -240,6 +240,11 @@ All Containers _MUST_ be identified by a URI and it _MUST_ be an HTTP(S) URI. Th Containers _MUST_ have an `items` property which is a list of Annotation Pages. Each Annotation Page, defined below, maintains a list of Annotations, which associate Content Resources to be rendered as part of the Container. Annotations that do not associate content to be rendered, but instead are about the Container such as a comment or tag, are recorded using Annotation Pages in the `annotations` property of the Container. +FIXME: It is an error to select a temporal region of a Scene that does not have a `duration`, or to select a temporal region that is not within the Scene's temporal extent. A Canvas or Scene with a `duration` may not be annotated as a content resource into a Scene that does not itself have a `duration`. + + + + #### Timeline A Timeline is a Container that represents only a temporal duration, measured in seconds. Timelines allow audio content to be presented, but do not allow anything with a height or width like an image or video. The duration of the Timeline is given in the `duration` property. @@ -258,6 +263,10 @@ A Scene is a Container that represents an infinitely large three-dimensional spa The axes of the coordinate system are measured in arbitrary units and these units do not necessarily correspond to any physical unit of measurement, unless `spatialScale` is supplied. +All resources that can be added to a Scene have an implicit (e.g. Lights, Cameras) or explicit (e.g. Models, Scenes), local coordinate space. + + + ### Annotation Classes @@ -327,6 +336,13 @@ If there is a need to distinguish between content resources, then the resource _ Containers _MAY_ be treated as content resources for the purposes of annotating on to other Containers. In this situation, the Container _MAY_ be [embedded][prezi30-terminology] within the Annotation, be a reference within the same Manifest, or require dereferencing to obtain its description. + +### Audio Content + + + + + ### Selectors The Web Annotation Data Model defines several Selectors, which describe how to find a specific segment of that resource to be used. As noted, the nature of Selectors are dependent on the type of resources that they select out of, and the methods needed for those descriptions will vary. The Selectors from the Web Annotation Data Model and other sources can be used within the IIIF Data Model. This specification defines additional Selector classes for use. @@ -515,6 +531,10 @@ Directional Lights emits in a specific direction as if it is infinitely far away If a DirectionalLight does not have an explicit direction, then the default is in the negative y direction (downwards). +this is really that the light always has a direction of (-y) and is rotated from there. So no rotation = "default" direction. + + + ##### Point Light Point Lights emits from a single point within the scene in all directions. @@ -527,6 +547,53 @@ Spot Lights emit a cone of light from a single point in a given direction. +#### Audio in Scenes + +All have `source`, `volume` + +##### Ambient Audio + + +##### Point Audio + + +##### Spot Audio + + +```json + + +"body": +{ + "id": "iiif/my/spotAudio", + "type": "SpotAudio", + "source": { + "id": "/path/to/my.mp3", + "type": "Audio", + "format": "audio/mp3", + "profile": "some profile thing of mp3" + }, + "angle": 45.0 +} +"target": + { + "type": "SpecificResource", + "selector": [{ + "type": "PointSelector" + "x", "y", "z" + }, + "transform": + {"RotateTransform"} + } + + +`angle` + +No default direction, MUST provide a Rotate Transform. + + + + #### Transforms here are the rules about transforms? @@ -746,6 +813,9 @@ The value _MUST_ be a positive floating point number. _Summary here_ +Just as a Scene may contain multiple Annotations with model, light, and camera resources, a single 3D model file may contain a collection of 3D resources, including model geometry, assemblages of lights, and/or multiple cameras, with some of these potentially manipulated by animations. When painting Scenes or models that themselves may contain groups of resources within a single Scene, it may not always be appropriate to include all possible cameras, lights, or other resources, and it may be desirable to opt not to import some of these resources. This is accomplished through the Annotation property `exclude`, which prevents the import of audio, lights, cameras, or animations from a particular Scene or model prior to the Annotation being painted into a Scene. When `exclude` is used, the excluded resource type should not be loaded into the Scene, and it is not possible to reactivate or turn on these excluded resources after loading. + + _On Annotation, a list of strings drawn from table_ | Value | Description | @@ -1019,12 +1089,20 @@ The value of this property _MUST_ be an array of JSON objects, each of which _MU {: #lookAt} _Summary here_ +It is useful to be able to rotate a light or camera or audio resource such that it is facing another object or point in the Scene, rather than calculating the angles within the Scene's coordinate space. This is accomplished with a property called `lookAt`, valid on DirectionalLight, SpotLight, and all Cameras. The value of the property is either a PointSelector, a WktSelector, the URI of an Annotation which paints something into the current Scene, or a Specific Resource with a selector identifying a point or region in an arbitrary container. + +If the value is a PointSelector, then the light or camera resource is rotated around the x and y axes such that it is facing the given point. If the value is a WktSelector, then the resource should be rotated to face the given region. If the value is an Annotation which targets a point via a PointSelector, URI fragment or other mechanism, then the resource should be rotated to face that point. If the value is a Specific Resource, the source container for the Specific Resource must be painted into the current Scene, and the Specific Resource selector should identify a point or region in the source container. In this case, the light or camera resource should be rotated to face the point or region in the source container where the point or region is located within the current Scene's coordinate space. This allows light or camera resources to face a specific 2D point on a Canvas painted into a 3D scene. + +This rotation happens after the resource has been added to the Scene, and thus after any transforms have taken place in the local coordinate space. + The value _MUST_ be a JSON object, conforming to either a reference to an Annotation, or an embedded PointSelector. If this property is not specified, then the default value for cameras is to look straight backwards (-Z) and for lights to point straight down (-Y). * A Camera _MAY_ have the `lookAt` property.
Clients _SHOULD_ process the `lookAt` property on Cameras. * A SpotLight or a DirectionalLight _SHOULD_ have the `lookAt` property.
+* A SpotSound _SHOULD_ have the `lookAt` property. + ```json "lookAt": { @@ -1673,7 +1751,7 @@ _Summary here_ The value of this property is an array of JSON objects, each of which is a Transform. -Process them in order. +Process them in order given. @@ -1693,14 +1771,19 @@ The value _MUST_ be a string. | Class | Description | | ------------- | -------------------------------- | +| `Audio` | Auditory resources primarily intended to be heard, such as might be rendered with an <audio> HTML tag | | `Dataset` | Data not intended to be rendered to humans directly, such as a CSV, an RDF serialization or a zip file | | `Image` | Two dimensional visual resources primarily intended to be seen, such as might be rendered with an <img> HTML tag | | `Model` | A three dimensional spatial model intended to be visualized, such as might be rendered with a 3d javascript library | -| `Sound` | Auditory resources primarily intended to be heard, such as might be rendered with an <audio> HTML tag | + | `Text` | Resources primarily intended to be read | | `Video` | Moving images, with or without accompanying audio, such as might be rendered with a <video> HTML tag | {: .api-table #table-type} +!!! note +For compatibility with previous versions, clients _SHOULD_ accept `Sound` as a synonym for `Audio`. + + {% include api/code_header.html %} ``` json-doc { "type": "Image" } From ea1d5aa60607657cfbd3e9dffc2ecdbe67e6047f Mon Sep 17 00:00:00 2001 From: Rob Sanderson Date: Wed, 19 Mar 2025 14:37:16 -0400 Subject: [PATCH 053/130] please build --- source/presentation/4.0/index.md | 17 ++++++----------- source/presentation/4.0/model.md | 29 ++++++++--------------------- 2 files changed, 14 insertions(+), 32 deletions(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index fc8fb49a0..de0b9a8e2 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -317,6 +317,9 @@ interactionMode + +#### Merge the below into the examples or into model + This (no units for scale) allows arbitrarily scaled models to be used, including very small or very large, without needing to deal with very small or very large values. If there is a correspondence to a physical scale, then this can be asserted using the physical dimensions pattern(fwd-ref-to-phys-dims). @@ -709,28 +712,20 @@ Example placing top-left at (0, 1, 0); bottom-left at (0, 0, 0); bottom-right at When a Scene is nested into another Scene, the `backgroundColor` of the Scene to be nested should be ignored as it is non-sensible to import. All Annotations painted into the Scene to be nested will be painted into the Scene into which content is being nested, including Light or Camera resources. If the Scene to be nested has one or more Camera Annotations while the Scene into which content is being nested does not, the first Camera Annotation from the nested Scene will become the default Camera for the overall Scene. +--- +## Annotations and State +### Example: Multi-spectral Images with Comments - - - - - - -Whale bone with a camera and a light - - -## Annotations and State - ### Annotations non-painting diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index 6d54613bd..8ff6323d6 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -228,7 +228,7 @@ A Manifest _MUST_ have the following properties: [id](#id), [type](#type), [labe A Manfiest _SHOULD_ have the following properties: [metadata](#metadata), [summary](#summary), [provider](#provider), and [thumbnail](#thumbnail) -A Manifest _MAY_ have the following properties: [requiredStatement](#requiredStatement), [rights](#rights), [navDate](#navDate), [navPlace](#navPlace), [placeholderContainer](#placeholderContainer), [accompanyingContainer](#accompanyingContainer), [viewingDirection](#viewingDirection), [behavior](#behavior), [seeAlso](#seeAlso), [service](#service), [services](#services), [homepage](#homepage), [rendering](#rendering), [partOf](#partOf), [start](#start), [structures](#structures), and [annotations](#annotations). +A Manifest _MAY_ have the following properties: [requiredStatement](#requiredStatement), [rights](#rights), [navDate](#navDate), [navPlace](#navPlace), [placeholderContainer](#placeholdercontainer), [accompanyingContainer](#accompanyingcontainer), [viewingDirection](#viewingdirection), [behavior](#behavior), [seeAlso](#seealso), [service](#service), [services](#services), [homepage](#homepage), [rendering](#rendering), [partOf](#partof), [start](#start), [structures](#structures), and [annotations](#annotations). ### Container Classes @@ -561,33 +561,17 @@ All have `source`, `volume` ```json - - -"body": { "id": "iiif/my/spotAudio", "type": "SpotAudio", "source": { "id": "/path/to/my.mp3", "type": "Audio", - "format": "audio/mp3", - "profile": "some profile thing of mp3" + "format": "audio/mp3" }, "angle": 45.0 } -"target": - { - "type": "SpecificResource", - "selector": [{ - "type": "PointSelector" - "x", "y", "z" - }, - "transform": - {"RotateTransform"} - } - - -`angle` +``` No default direction, MUST provide a Rotate Transform. @@ -625,7 +609,7 @@ A TranslateTransform moves all of the objects in the local coordinate space the ##### accompanyingContainer -{: #accompanyingContainer} +{: #accompanyingcontainer} A Container that provides additional content for use while the resource that has the `accompanyingContainer` property is shown or played. Examples include an image to show while a duration-only Canvas is playing audio; or background audio to play while a user is navigating an image-only Manifest. @@ -759,12 +743,15 @@ The value _MUST_ be an array of strings. | | **Collection Behaviors** | | `multi-part` | Valid only on Collections. Collections that have this behavior consist of multiple Manifests or Collections which together form part of a logical whole or a contiguous set, such as multi-volume books or a set of journal issues. Clients might render these Collections as a table of contents rather than with thumbnails, or provide viewing interfaces that can easily advance from one member to the next. Disjoint with `together`.| | `together` | Valid only on Collections. A client _SHOULD_ present all of the child Manifests to the user at once in a separate viewing area with its own controls. Clients _SHOULD_ catch attempts to create too many viewing areas. This behavior _SHOULD NOT_ be interpreted as applying to the members of any child resources. Disjoint with `multi-part`.| -| | **Range Behaviors** | +| | **Navigation Behaviors** | | `sequence` | Valid only on Ranges, where the Range is [referenced][prezi30-terminology] in the `structures` property of a Manifest. Ranges that have this behavior represent different orderings of the Containers listed in the `items` property of the Manifest, and user interfaces that interact with this order _SHOULD_ use the order within the selected Range, rather than the default order of `items`. 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`.| +| `linear-nav` | FIXME: ... | | | **Miscellaneous Behaviors** | | `hidden` | 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. | +| `reset` | Valid on Annotations with a scope property. FIXME: ... | +| `no-reset` | Valid on Annotations with a scope property. FIXME: ... | {: .api-table #table-behavior} {% include api/code_header.html %} From c764eec3d5e298e885ec5d9c3050dd172aa59413 Mon Sep 17 00:00:00 2001 From: Rob Sanderson Date: Wed, 19 Mar 2025 14:41:39 -0400 Subject: [PATCH 054/130] revert case of anchors --- source/presentation/4.0/model.md | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index 8ff6323d6..cd5c1e049 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -223,13 +223,11 @@ The `type` property of a Manifest _MUST_ have the value `"Manifest"`. The members of a Manifest are listed in the `items` property. The members of Manifests _MUST_ be Containers, defined below, and are embedded within the Manifest. The Manifest _MAY_ have a `structures` property listing one or more [Ranges][#range] which describe additional structure of the content, such as might be rendered as a table of contents. The Manifest _MAY_ have an `annotations` property, which includes Annotation Page resources where the Annotations have the Manifest as their `target`. These Annotations _MUST NOT_ have `painting` as their `motivation`. -!!! Properties -A Manifest _MUST_ have the following properties: [id](#id), [type](#type), [label](#label), and [items](#items) - -A Manfiest _SHOULD_ have the following properties: [metadata](#metadata), [summary](#summary), [provider](#provider), and [thumbnail](#thumbnail) - -A Manifest _MAY_ have the following properties: [requiredStatement](#requiredStatement), [rights](#rights), [navDate](#navDate), [navPlace](#navPlace), [placeholderContainer](#placeholdercontainer), [accompanyingContainer](#accompanyingcontainer), [viewingDirection](#viewingdirection), [behavior](#behavior), [seeAlso](#seealso), [service](#service), [services](#services), [homepage](#homepage), [rendering](#rendering), [partOf](#partof), [start](#start), [structures](#structures), and [annotations](#annotations). - +__Properties__
+A Manifest _MUST_ have the following properties: [id](#id), [type](#type), [label](#label), and [items](#items)
+A Manifest _SHOULD_ have the following properties: [metadata](#metadata), [summary](#summary), [provider](#provider), and [thumbnail](#thumbnail)
+A Manifest _MAY_ have the following properties: [requiredStatement](#requiredStatement), [rights](#rights), [navDate](#navDate), [navPlace](#navPlace), [placeholderContainer](#placeholderContainer), [accompanyingContainer](#accompanyingContainer), [viewingDirection](#viewingDirection), [behavior](#behavior), [seeAlso](#seeAlso), [service](#service), [services](#services), [homepage](#homepage), [rendering](#rendering), [partOf](#partOf), [start](#start), [structures](#structures), and [annotations](#annotations). +{: .note} ### Container Classes {: #containers} @@ -609,7 +607,7 @@ A TranslateTransform moves all of the objects in the local coordinate space the ##### accompanyingContainer -{: #accompanyingcontainer} +{: #accompanyingContainer} A Container that provides additional content for use while the resource that has the `accompanyingContainer` property is shown or played. Examples include an image to show while a duration-only Canvas is playing audio; or background audio to play while a user is navigating an image-only Manifest. From 99fb71e47bff592bf0e7b3dfa7845727ea51959f Mon Sep 17 00:00:00 2001 From: Rob Sanderson Date: Wed, 19 Mar 2025 14:52:39 -0400 Subject: [PATCH 055/130] update --- source/presentation/4.0/model.md | 33 +++++++++++++++++++++++++++----- 1 file changed, 28 insertions(+), 5 deletions(-) diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index cd5c1e049..9b40d5770 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -203,7 +203,7 @@ Collections or Manifests [referenced][prezi30-terminology] in the `items` proper #### Collection Page {: #CollectionPage} -Class: `CollectionPage` +`"type": "CollectionPage"` A Collection Page is an arbitrary division of members within the Collection to make it easier to consume. @@ -214,18 +214,18 @@ Collection Pages follow the ActivityStreams model, as also used in Annotation Co ### Manifest +`"type": "Manifest"` + A Manifest is the primary unit of distribution of IIIF and provides a description of the structure and properties of a single item to be presented to the user. Manifests _MUST_ be identified by a URI and it _MUST_ be an HTTP(S) URI, given in the `id` property. It _MUST_ be able to be dereferenced to retrieve the JSON description of the Manifest. -The `type` property of a Manifest _MUST_ have the value `"Manifest"`. - The members of a Manifest are listed in the `items` property. The members of Manifests _MUST_ be Containers, defined below, and are embedded within the Manifest. The Manifest _MAY_ have a `structures` property listing one or more [Ranges][#range] which describe additional structure of the content, such as might be rendered as a table of contents. The Manifest _MAY_ have an `annotations` property, which includes Annotation Page resources where the Annotations have the Manifest as their `target`. These Annotations _MUST NOT_ have `painting` as their `motivation`. __Properties__
-A Manifest _MUST_ have the following properties: [id](#id), [type](#type), [label](#label), and [items](#items)
-A Manifest _SHOULD_ have the following properties: [metadata](#metadata), [summary](#summary), [provider](#provider), and [thumbnail](#thumbnail)
+A Manifest _MUST_ have the following properties: [id](#id), [type](#type), [label](#label), and [items](#items)

+A Manifest _SHOULD_ have the following properties: [metadata](#metadata), [summary](#summary), [provider](#provider), and [thumbnail](#thumbnail)

A Manifest _MAY_ have the following properties: [requiredStatement](#requiredStatement), [rights](#rights), [navDate](#navDate), [navPlace](#navPlace), [placeholderContainer](#placeholderContainer), [accompanyingContainer](#accompanyingContainer), [viewingDirection](#viewingDirection), [behavior](#behavior), [seeAlso](#seeAlso), [service](#service), [services](#services), [homepage](#homepage), [rendering](#rendering), [partOf](#partOf), [start](#start), [structures](#structures), and [annotations](#annotations). {: .note} @@ -827,6 +827,10 @@ The value is a non-negative floating point number, in the coordinate space of th ```json-doc { "far": 200.0 } ``` + +##### first + + ##### fieldOfView {: #fieldOfView} @@ -1043,6 +1047,9 @@ The value _MUST_ be an array of strings. Each item in the array _MUST_ be a vali ``` json-doc { "language": [ "en" ] } ``` + +##### last + ##### logo {: #logo} @@ -1070,6 +1077,7 @@ The value of this property _MUST_ be an array of JSON objects, each of which _MU ] } ``` + ##### lookAt {: #lookAt} @@ -1194,6 +1202,7 @@ The value of the property _MUST_ be a [GeoJSON Feature Collection] [link] contai } } ``` + ##### near {: #near} @@ -1208,6 +1217,11 @@ The value is a non-negative floating point number, in the coordinate space of th { "near": 1.5 } ``` +##### next + +... + + ##### partOf {: #partOf} @@ -1285,6 +1299,10 @@ The value of this property _MUST_ be a JSON object conforming to the `SpecificRe } ``` + +##### prev + + ##### profile {: #profile} @@ -1729,6 +1747,11 @@ The value _MUST_ be a string. ``` +##### totalItems + +For compatability with the Web Annotation Data Model, clients _SHOULD_ also accept `total` as the name of this property when used on the `AnnotationCollection` class. + + ##### transform {: #transform} From 049829809d6ad781bf19078abdf5159255347820 Mon Sep 17 00:00:00 2001 From: tomcrane Date: Wed, 19 Mar 2025 15:09:44 -0400 Subject: [PATCH 056/130] Add type: ClassName to all Classes --- source/presentation/4.0/index.md | 2 +- source/presentation/4.0/model.md | 120 ++++++++++++++++++++----------- 2 files changed, 78 insertions(+), 44 deletions(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index de0b9a8e2..1c4f43d0d 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -1289,7 +1289,7 @@ If you go backwards from step n in a linear-nav, **and** you have applied one or Before applying the content state to the Scene, the client should reset the Scene to its original state as provided by the Manifest. -// I am assuming reset is always true except in `sequence` - otherwise it's completely unpredictable!! or is it... arbitrary navigation, state provided by initialization content states, etc... +// I am assuming reset is always true except in `linear-nav` - otherwise it's completely unpredictable!! or is it... arbitrary navigation, state provided by initialization content states, etc... #### Contribute additional information permanently diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index 9b40d5770..ce1b35615 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -245,16 +245,22 @@ FIXME: It is an error to select a temporal region of a Scene that does not have #### Timeline +`"type": "Timeline"` + A Timeline is a Container that represents only a temporal duration, measured in seconds. Timelines allow audio content to be presented, but do not allow anything with a height or width like an image or video. The duration of the Timeline is given in the `duration` property. #### Canvas +`"type": "Canvas"` + A Canvas is a Container that represents a particular rectangular 2 dimensional view of the object and has content resources associated with it or with parts of it. This aspect ratio is defined by the `height` and `width` properties. A Canvas _MAY_ also have a duration, given in the `duration` property, allowing audio and video to be correctly positioned in time as well as the 2 dimensional space. FIXME: arbitrary units #### Scene +`"type": "Scene"` + A Scene is a Container that represents an infinitely large three-dimensional space, with an optional `duration` property. Scenes have infinite height (y axis), width (x axis) and depth (z axis), where 0 on each axis (the origin of the coordinate system) is treated as the center of the scene's space. From a perspective looking along the z axis towards negative infinity, the positive y axis points upwards and the positive x axis points to the right (a [right-handed Cartesian coordinate system](https://en.wikipedia.org/wiki/Right-hand_rule)). diagram of Right handed cartesian coordinate system @@ -274,6 +280,8 @@ The following set of classes are defined by the W3C's [Web Annotation Data Model #### Annotation +`"type": "Annotation"` + Annotations are used to associate content resources with Containers, as well as for transcriptions, commentary, tags and the association of other content. This provides a single, unified method for aligning information, and provides a standards-based framework for distinguishing parts of resources and parts of Canvases. Annotations _MUST_ have their own HTTP(S) URIs, conveyed in the `id` property. The JSON-LD description of the Annotation _SHOULD_ be returned if the URI is dereferenced, according to the [Web Annotation Protocol][org-w3c-webanno-protocol]. @@ -287,6 +295,8 @@ Note that the Web Annotation data model defines different patterns for the `valu #### Annotation Collection +`"type": "AnnotationCollection"` + Annotation Collections allow groups of Annotations to be recorded. For example, all of the English translation Annotations of a medieval French document could be kept separate from the transcription or an edition in modern French, or the director's commentary on a film can be separated from the script. Annotation Collections _MUST_ have a URI, and it _SHOULD_ be an HTTP(S) URI. They _SHOULD_ have a `label` and _MAY_ have any of the other descriptive, linking or rights properties. @@ -296,6 +306,8 @@ Annotation Collections are paged rather than enumerated. The first page of items #### Annotation Page +`"type": "AnnotationPage"` + An ordered list of Annotations, typically associated with a Container, but may be referenced from other types of resource as well. Annotation Pages enumerate and order lists of Annotations, in the same way that Collection Pages order lists of Manifests and Collections within the containing Collection. An Annotation Page _MUST_ have an HTTP(S) URI given in `id`, and _MAY_ have any of the other properties defined in this specification or the Web Annotation specification. The Annotations are listed in the `items` property of the Annotation Page. @@ -309,14 +321,20 @@ The definition of `label` in the Web Annotation specification does not produce J #### Specific Resource +`"type": "SpecificResource"` + A Specific Resource is a resource in the context of an Annotation. They are used to record further properties or relationships needed to understand the particular contextual use, such as which part of the resource is used or how it should be rendered. In IIIF, the Specific Resource model from the Web Annotation Data Model has some additional properties beyond those defined by the W3C, such as `transform`. #### Textual Body +`"type": "TextualBody"` + A Textual Body is an embedded resource within an Annotation that carries, as the name suggests, a text as the body of the Annotation. It is defined by the Web Annotation Data Model, and this specification defines a new property for `position` that allows it to be positioned within a Container. #### Choice +`"type": "Choice"` + A Choice is a Web Annotation construction that allows one entry from a list to be selected for processing or display. This specification allows `behavior` to be added to a Choice to influence how it is processed. @@ -370,15 +388,11 @@ There are common use cases in which a point, rather than a range or area, is the #### WKT Selector -Well-known text, or WKT, is an ISO standard method for describing 2 and 3 dimensional geometries. This selector thus goes beyond what the Web Annotation's SvgSelector enables by incorporating the z axis, as well as additional types of selection such as MultiPolygon. Additional types, such as CIRCULARSTRING may also be supported. +`"type": "WktSelector"` -WKT Selectors have the following properties: +Well-known text, or WKT, is an ISO standard method for describing 2 and 3 dimensional geometries. This selector thus goes beyond what the Web Annotation's SvgSelector enables by incorporating the z axis, as well as additional types of selection such as MultiPolygon. Additional types, such as CIRCULARSTRING may also be supported. -| Name | Description | -|-------|-------------| -| id | The HTTP(S) URI of the selector | -| type | The class of the selector, which must be "WktSelector" | -| value | The WKT string that defines the geometry to be selected | +WKT Selectors _MUST_ have a `value` property, which is the WKT string that defines the geometry to be selected. ```json { @@ -393,14 +407,9 @@ WKT Selectors have the following properties: #### Audio Content Selector -Video content resources consist of both visual and audio content within the same bit-level representation. There are situations when it is useful to refer to only one aspect of the content – either the visual or the audio, but not both. For example, an Annotation might associate only the visual content of a video that has spoken English in the audio, and an audio file that has the translation of that content in Spanish. The Audio Content Selector selects all of the audio content from an A/V content resource, and may be further refined with subsequent selectors to select a segment of it. - -Audio Content Selectors have the following properties: +`"type": "AudioContentSelector"` -| Name | Description | -|------|-------------| -| id | The HTTP(S) URI of the selector | -| type | The class of the selector, which must be "AudioContentSelector" | +Video content resources consist of both visual and audio content within the same bit-level representation. There are situations when it is useful to refer to only one aspect of the content – either the visual or the audio, but not both. For example, an Annotation might associate only the visual content of a video that has spoken English in the audio, and an audio file that has the translation of that content in Spanish. The Audio Content Selector selects all of the audio content from an A/V content resource, and may be further refined with subsequent selectors to select a segment of it. ```json @@ -413,14 +422,9 @@ Audio Content Selectors have the following properties: #### Visual Content Selector -Similar to Audio Content Selectors, Visual Content Selectors select the visual aspects of the content of an A/V content resource. They may be further refined by subsequent selectors that select an area or temporal segment of it. - -Visual Content Selectors have the following properties: +`"type": "VisualContentSelector"` -| Name | Description | -|------|-------------| -| id | The HTTP(S) URI of the selector | -| type | The class of the selector, which must be "VisualContentSelector" | +Similar to Audio Content Selectors, Visual Content Selectors select the visual aspects of the content of an A/V content resource. They may be further refined by subsequent selectors that select an area or temporal segment of it. ```json { @@ -432,16 +436,11 @@ Visual Content Selectors have the following properties: #### Animation Selector -More interactive content resources, such as 3d models, may have activatable animations or similar features. For example, a model of a box might have an animation that opens the lid and a second animation that closes the lid. In order to activate those animations, they need to be selectable, and thus the specification defines an Animation Selector. - -Animation Selectors have the following properties: +`"type": "AnimationSelector"` -| Name | Description | -|-------|-------------| -| id | The HTTP(S) URI of the selector | -| type | The class of the selector, which must be "AnimationSelector" | -| value | The identity of the animation in whichever form is used by the source resource | +More interactive content resources, such as 3D models, may have animations or similar features that can be _activated_ by user interaction. For example, a model of a box might have an animation that opens the lid and a second animation that closes the lid. In order to activate those animations, they need to be selectable, and thus the specification defines an Animation Selector. +Animation Selectors _MUST_ have a `value` property, which is the identity of the animation in whichever form is used by the source resource. ```json { @@ -451,7 +450,9 @@ Animation Selectors have the following properties: } ``` -#### ImageApiSelector +#### IIIF Image API Selector + +`"type": "ImageApiSelector"` FIXME: write this @@ -460,6 +461,8 @@ FIXME: write this ### Range +`"type": "Range"` + Ranges are used to represent structure within a Manifest beyond the default order of the Containers in the `items` property. Ranges _MUST_ have URIs and they _SHOULD_ be HTTP(S) URIs. Top level Ranges are [embedded][prezi30-terminology] or externally [referenced][prezi30-terminology] within the Manifest in a `structures` property. These top level Ranges then embed or reference other Ranges, Containers or parts of Containers in the `items` property. Each entry in the `items` property _MUST_ be a JSON object, and it _MUST_ have the `id` and `type` properties. If a top level Range needs to be dereferenced by the client, then it _MUST NOT_ have the `items` property, such that clients are able to recognize that it should be retrieved in order to be processed. @@ -480,17 +483,20 @@ FIXME: If either the position or direction is not specified, then the position d The region of the Scene's space that is observable by the camera is bounded by two planes orthogonal to the direction the camera is facing, given in the `near` and `far` properties, (PERSPECTIVE) and a vertical projection angle that provides the top and bottom planes of the region. (viewHeight?) -##### OrthographicCamera +##### Orthographic Camera + +`"type": "OrthographicCamera"` `OrthographicCamera` removes visual perspective, resulting in object size remaining constant regardless of its distance from the camera -##### PerspectiveCamera +##### Perspective Camera + +`"type": "PerspectiveCamera"` `PerspectiveCamera` mimics the way the human eye sees, in that objects further from the camera are smaller -!!! Properties -... +Properties... ```json @@ -519,29 +525,37 @@ The region of the Scene's space that is observable by the camera is bounded by t ##### Ambient Light +`"type": "AmbientLight"` + Ambient Lights evenly illuminates all objects in the scene, and does not have a direction or position. ##### Directional Light -Directional Lights emits in a specific direction as if it is infinitely far away and the rays produced from it are all parallel. It does not have a specific position. +`"type": "DirectionalLight"` - If a DirectionalLight does not have an explicit direction, then the default is in the negative y direction (downwards). +Directional Lights emits in a specific direction as if it is infinitely far away and the rays produced from it are all parallel. It does not have a specific position. +If a DirectionalLight does not have an explicit direction, then the default is in the negative y direction (downwards). -this is really that the light always has a direction of (-y) and is rotated from there. So no rotation = "default" direction. +This is really that the light always has a direction of (-y) and is rotated from there. So no rotation = "default" direction. ##### Point Light - Point Lights emits from a single point within the scene in all directions. +`"type": "PointLight"` + +Point Lights emits from a single point within the scene in all directions. + ##### Spot Light +`"type": "SpotLight"` + Spot Lights emit a cone of light from a single point in a given direction. - If a SpotLight does not have an explicit direction, then the default is in the negative y direction (downwards). +If a SpotLight does not have an explicit direction, then the default is in the negative y direction (downwards). @@ -551,12 +565,16 @@ All have `source`, `volume` ##### Ambient Audio +`"type": "AmbientAudio"` + ##### Point Audio +`"type": "PointAudio"` ##### Spot Audio +`"type": "SpotAudio"` ```json { @@ -582,24 +600,39 @@ here are the rules about transforms? -##### RotateTransform +##### Rotate Transform + +`"type": "RotateTransform"` A RotateTransform rotates the local coordinate space around the given axis in a counter-clockwise direction around the axis itself (e.g. around a pivot point of 0 on the axis). A point that was at x=1,y=1 and was rotated 90 degrees around the x axis would be at x=1,y=0,z=1. If an axis value is not specified, then it is not changed, resulting in a default of 0.0 -##### ScaleTransform +##### Scale Transform + +`"type": "ScaleTransform"` A ScaleTransform applies a multiplier to one or more axes in the local coordinate space. A point that was at 3.5, after applying a ScaleTransform of 2.0 would then be at 7.0. If an axis value is not specified, then it is not changed, resulting in a default of 1.0 -##### TranslateTransform +##### Translate Transform + +`"type": "TranslateTransform"` A TranslateTransform moves all of the objects in the local coordinate space the given distance along the axis. A point that was at x=1.0, after applying a TranslateTransform of x=1.0 would be at x=2.0. If an axis value is not specified then it is not changed, resulting in a default of 0.0 ### Utility Classes + #### Agent + +`"type": "Agent"` + #### Service -#### UnitValue + +`"type": "Service"` + +#### Unit Value + +`"type": "UnitValue"` @@ -650,6 +683,7 @@ The value _MUST_ be a floating point number greater than 0 and less than 90, and ```json "angle": 15.0 ``` + ##### annotations {: #annotations} From a581beb0a3e7bd58c78f786d842ca10793d20bde Mon Sep 17 00:00:00 2001 From: Rob Sanderson Date: Wed, 19 Mar 2025 17:38:14 -0400 Subject: [PATCH 057/130] push --- source/presentation/4.0/model.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index ce1b35615..d7b471e2d 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -234,7 +234,7 @@ A Manifest _MAY_ have the following properties: [requiredStatement](#requiredSta A Container is a frame of reference that allows the relative positioning of content. -All Containers _MUST_ be identified by a URI and it _MUST_ be an HTTP(S) URI. The URI of the Container _MUST NOT_ contain a fragment (a `#` followed by further characters), as this would make it impossible to refer to a segment of the Container's area using the [media fragment syntax][org-w3c-media-frags] of `#xywh=` for spatial regions, and/or `#t=` for temporal segments. Containers _MAY_ be able to be dereferenced separately from the Manifest via their URIs as well as being [embedded][prezi30-terminology]. +All Containers _MUST_ be identified by a URI and it _MUST_ be an HTTP(S) URI. The URI of the Container _MUST NOT_ contain a fragment (a `#` followed by further characters), as this would make it impossible to refer to a segment of the Container's area using the [media fragment syntax][org-w3c-media-frags] of `#xywh=` for spatial regions, and/or `#t=` for temporal segments. The temporal segment _MUST_ be expressed using seconds. Containers _MAY_ be able to be dereferenced separately from the Manifest via their URIs as well as being [embedded][prezi30-terminology]. Containers _MUST_ have an `items` property which is a list of Annotation Pages. Each Annotation Page, defined below, maintains a list of Annotations, which associate Content Resources to be rendered as part of the Container. Annotations that do not associate content to be rendered, but instead are about the Container such as a comment or tag, are recorded using Annotation Pages in the `annotations` property of the Container. @@ -639,7 +639,7 @@ A TranslateTransform moves all of the objects in the local coordinate space the ## Properties -##### accompanyingContainer +### accompanyingContainer {: #accompanyingContainer} A Container that provides additional content for use while the resource that has the `accompanyingContainer` property is shown or played. Examples include an image to show while a duration-only Canvas is playing audio; or background audio to play while a user is navigating an image-only Manifest. @@ -670,7 +670,7 @@ The value of `accompanyingContainer` _MUST_ be a JSON object with the `id` and ` } ``` -##### angle +### angle {: #angle} !!! warning "Need more info" @@ -684,7 +684,7 @@ The value _MUST_ be a floating point number greater than 0 and less than 90, and "angle": 15.0 ``` -##### annotations +### annotations {: #annotations} An ordered list of Annotation Pages that contain commentary or other Annotations about this resource, separate from the Annotations that are used to paint content on to a Canvas. The `motivation` of the Annotations _MUST NOT_ be `painting`, and the target of the Annotations _MUST_ include this resource or part of it. @@ -717,7 +717,7 @@ The value _MUST_ be an array of JSON objects. Each item _MUST_ have at least the } ``` -##### backgroundColor +### backgroundColor {: #backgroundColor} This property sets the background color behind any painted resources on a spatial Container, such as a Canvas or Scene. From 29bd63fa804609c6271189633870370155bcaa2e Mon Sep 17 00:00:00 2001 From: tomcrane Date: Wed, 19 Mar 2025 17:38:57 -0400 Subject: [PATCH 058/130] add TODO referencing issue --- source/presentation/4.0/model.md | 1 + 1 file changed, 1 insertion(+) diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index ce1b35615..ea0458df6 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -757,6 +757,7 @@ The value _MUST_ be an array of strings. !!! Could continuous stitch together Timelines? +TODO: Address https://github.com/IIIF/api/issues/2318 | Value | Description | | ----- | ----------- | From 3c97d66b889eefd35549c75b75f703f3deae1e08 Mon Sep 17 00:00:00 2001 From: Rob Sanderson Date: Wed, 19 Mar 2025 17:39:34 -0400 Subject: [PATCH 059/130] hello toc --- source/presentation/4.0/model.md | 108 +++++++++++++++---------------- 1 file changed, 54 insertions(+), 54 deletions(-) diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index 426c208dd..0fc8da575 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -734,7 +734,7 @@ The value _MUST_ be string, which defines an RGB color. It SHOULD be a hex value { "backgroundColor": "#FFFFFF" } ``` -##### behavior +### behavior {: #behavior} A set of user experience features that the publisher of the content would prefer the client to use when presenting the resource. This specification defines the values in the table below. Others may be defined externally as an [extension][prezi30-ldce]. @@ -792,7 +792,7 @@ TODO: Address https://github.com/IIIF/api/issues/2318 { "behavior": [ "auto-advance", "individuals" ] } ``` -##### color +### color {: #color} This property sets the color of a Light. @@ -807,7 +807,7 @@ The value _MUST_ be string, which defines an RGB color. It SHOULD be a hex value "color": "#FFA0A0" ``` -##### duration +### duration {: #duration} The duration of a container or external content resource, given in seconds. @@ -828,7 +828,7 @@ The value _MUST_ be a positive floating point number. { "duration": 125.0 } ``` -##### exclude +### exclude {: #exclude} _Summary here_ @@ -849,7 +849,7 @@ _On Annotation, a list of strings drawn from table_ "exclude": [ "Audio", "Lights", "Cameras", "Animations" ] ``` -##### far +### far {: #far} This property gives the distance from the camera after which objects are no longer visible. Objects further from the camera than the `far` distance cannot be seen. @@ -863,10 +863,10 @@ The value is a non-negative floating point number, in the coordinate space of th { "far": 200.0 } ``` -##### first +### first -##### fieldOfView +### fieldOfView {: #fieldOfView} The angle which a PerspectiveCamera can "see". @@ -881,7 +881,7 @@ The value _MUST_ be a floating point number greater than 0 and less than 180, an ```json-doc { "fieldOfView": 50.0 } ``` -##### format +### format {: #format} The specific media type (often called a MIME type) for a content resource, for example `image/jpeg`. This is important for distinguishing different formats of the same overall type of resource, such as distinguishing text in XML from plain text. @@ -899,7 +899,7 @@ The value _MUST_ be a string, and it _SHOULD_ be the value of the `Content-Type` ``` json-doc { "format": "application/xml" } ``` -##### height +### height {: #height} The height of the Canvas or external content resource. For content resources, the value is in pixels. For Canvases, the value does not have a unit. In combination with the width, it conveys an aspect ratio for the space in which content resources are located. @@ -917,7 +917,7 @@ The value _MUST_ be a positive integer. ``` json-doc { "height": 1800 } ``` -##### homepage +### homepage {: #homepage} A web page that is about the object represented by the resource that has the `homepage` property. The web page is usually published by the organization responsible for the object, and might be generated by a content management system or other cataloging system. The resource _MUST_ be able to be displayed directly to the user. Resources that are related, but not home pages, _MUST_ instead be added into the `metadata` property, with an appropriate `label` or `value` to describe the relationship. @@ -945,7 +945,7 @@ Please note that this specification has stricter requirements about the JSON pat ] } ``` -##### id +### id {: #id} The URI that identifies the resource. If the resource is only available embedded within another resource (see the [terminology section][prezi30-terminology] for an explanation of "embedded"), such as a Range within a Manifest, then the URI _MAY_ be the URI of the embedding resource with a unique fragment on the end. This is not true for Canvases, which _MUST_ have their own URI without a fragment. @@ -962,7 +962,7 @@ The existence of an HTTP(S) URI in the `id` property does not mean that the URI { "id": "https://example.org/iiif/1/manifest" } ``` -##### instant +### instant {: #instant} A number (floating point) giving the time of the point in seconds, relative to the duration of the source resource @@ -970,7 +970,7 @@ A number (floating point) giving the time of the point in seconds, relative to t FIXME: fix -##### intensity +### intensity {: #intensity} This property sets the strength or brightness of a Light. @@ -987,7 +987,7 @@ This specification defines the unit value of "relative" which constrains the val "intensity": {"id": "", "type": "UnitValue", "value": 0.5, "unit": "relative"} } ``` -##### interactionMode +### interactionMode {: #interactionMode} *within* the Scene, whereas viewingDirection and behavior are across containers. @@ -1004,7 +1004,7 @@ free free-direction other examples: no-zoom, no-scrub, rti-mode -##### items +### items {: #items} Much of the functionality of the IIIF Presentation API is simply recording the order in which child resources occur within a parent resource, such as Collections or Manifests within a parent Collection, or Canvases within a Manifest. All of these situations are covered with a single property, `items`. @@ -1040,7 +1040,7 @@ The value _MUST_ be an array of JSON objects. Each item _MUST_ have the `id` and ] } ``` -##### label +### label {: #label} A human readable label, name or title. The `label` property is intended to be displayed as a short, textual surrogate for the resource if a human needs to make a distinction between it and similar resources, for example between objects, pages, or options for a choice of images to display. The `label` property can be fully internationalized, and each language can have multiple values. This pattern is described in more detail in the [languages][prezi40-languages] section. @@ -1066,7 +1066,7 @@ The value of the property _MUST_ be a JSON object, as described in the [language ``` json-doc { "label": { "en": [ "Example Object Title" ] } } ``` -##### language +### language {: #language} The language or languages used in the content of this external resource. This property is already available from the Web Annotation model for content resources that are the body or target of an Annotation, however it _MAY_ also be used for resources [referenced][prezi30-terminology] from `homepage`, `rendering`, and `partOf`. @@ -1083,9 +1083,9 @@ The value _MUST_ be an array of strings. Each item in the array _MUST_ be a vali { "language": [ "en" ] } ``` -##### last +### last -##### logo +### logo {: #logo} A small image resource that represents the Agent resource it is associated with. The logo _MUST_ be clearly rendered when the resource is displayed or used, without cropping, rotating or otherwise distorting the image. It is _RECOMMENDED_ that a [IIIF Image API][image-api] service be available for this image for other manipulations such as resizing. @@ -1113,7 +1113,7 @@ The value of this property _MUST_ be an array of JSON objects, each of which _MU } ``` -##### lookAt +### lookAt {: #lookAt} _Summary here_ @@ -1140,7 +1140,7 @@ The value _MUST_ be a JSON object, conforming to either a reference to an Annota "z": -10 } ``` -##### metadata +### metadata {: #metadata} An ordered list of descriptions to be displayed to the user when they interact with the resource, given as pairs of human readable `label` and `value` entries. The content of these entries is intended for presentation only; descriptive semantics _SHOULD NOT_ be inferred. An entry might be used to convey information about the creation of the object, a physical description, ownership information, or other purposes. @@ -1169,7 +1169,7 @@ Clients _SHOULD_ display the entries in the order provided. Clients _SHOULD_ exp ] } ``` -##### navDate +### navDate {: #navDate} A date that clients may use for navigation purposes when presenting the resource to the user in a date-based user interface, such as a calendar or timeline. More descriptive date ranges, intended for display directly to the user, _SHOULD_ be included in the `metadata` property for human consumption. If the resource contains Canvases that have the `duration` property, the datetime given corresponds to the navigation datetime of the start of the resource. For example, a Range that includes a Canvas that represents a set of video content recording a historical event, the `navDate` is the datetime of the first moment of the recorded event. @@ -1193,7 +1193,7 @@ The value _MUST_ be an [XSD dateTime literal][org-w3c-xsd-datetime]. The value _ ``` json-doc { "navDate": "2010-01-01T00:00:00Z" } ``` -##### navPlace +### navPlace {: #navPlace} A geographic location that clients may use for navigation purposes when presenting the resource to the user in a map-based user interface. The location is identified using structured data, described below, with latitude and longitude based points or polygons. If the location is only textual, then the information should instead be included in the `metadata` property. @@ -1238,7 +1238,7 @@ The value of the property _MUST_ be a [GeoJSON Feature Collection] [link] contai } ``` -##### near +### near {: #near} This property gives the distance from the camera from which objects are visible. Objects closer to the camera than the `near` distance cannot be seen. @@ -1252,12 +1252,12 @@ The value is a non-negative floating point number, in the coordinate space of th { "near": 1.5 } ``` -##### next +### next ... -##### partOf +### partOf {: #partOf} A containing resource that includes the resource that has the `partOf` property. When a client encounters the `partOf` property, it might retrieve the [referenced][prezi30-terminology] containing resource, if it is not [embedded][prezi30-terminology] in the current representation, in order to contribute to the processing of the contained resource. For example, the `partOf` property on a Canvas can be used to reference an external Manifest in order to enable the discovery of further relevant information. Similarly, a Manifest can reference a containing Collection using `partOf` to aid in navigation. @@ -1274,7 +1274,7 @@ The value _MUST_ be an array of JSON objects. Each item _MUST_ have the `id` and The resources referred to by the `accompanyingContainer` and `placeholderContainer` properties are `partOf` that referring Container. -##### placeholderContainer +### placeholderContainer {: #placeholderContainer} A single Container that provides additional content for use before the main content of the resource that has the `placeholderContainer` property is rendered, or as an advertisement or stand-in for that content. Examples include images, text and sound standing in for video content before the user initiates playback; or a film poster to attract user attention. The content provided by `placeholderContainer` differs from a thumbnail: a client might use `thumbnail` to summarize and navigate multiple resources, then show content from `placeholderContainer` as part of the initial presentation of a single resource. A placeholder Container is likely to have different dimensions to those of the Container(s) of the resource that has the `placeholderContainer` property. A placeholder Container may be of a different type from the resource that has the `placeholderContainer` property. For example, a `Scene` may have a placeholder Container of type `Canvas`. @@ -1305,7 +1305,7 @@ The value of `placeholderContainer` _MUST_ be a JSON object with the `id` and `t } } ``` -##### position +### position {: #position} It is important to be able to position the (textual) body of an annotation within the Container's space that the annotation also targets. For example, a description of part of an image in a Canvas should be positioned such that it does not obscure the image region itself and labels to be displayed as part of a Scene should not be rendered such that the text is hidden by the three dimensional geometry of the model. If this property is not supplied, then the client should do its best to ensure the content is visible to the user. @@ -1335,10 +1335,10 @@ The value of this property _MUST_ be a JSON object conforming to the `SpecificRe ``` -##### prev +### prev -##### profile +### profile {: #profile} A schema or named set of functionality available from the resource. The profile can further clarify the `type` and/or `format` of an external resource or service, allowing clients to customize their handling of the resource that has the `profile` property. @@ -1354,7 +1354,7 @@ The value _MUST_ be a string, either taken from the [profiles registry][registry ``` json-doc { "profile": "https://example.org/profile/statuary" } ``` -##### provider +### provider {: #provider} An organization or person that contributed to providing the content of the resource. Clients can then display this information to the user to acknowledge the provider's contributions. This differs from the `requiredStatement` property, in that the data is structured, allowing the client to do more than just present text but instead have richer information about the people and organizations to use in different interfaces. @@ -1414,7 +1414,7 @@ The value _MUST_ be an array of JSON objects, where each item in the array confo ] } ``` -##### provides +### provides {: #provides} A set of features or additional functionality that a linked resource enables relative to the linking or including resource, which is not defined by the `type`, `format` or `profile` of the linked resource. It provides information as to why and how a client might want to interact with the resource, rather than what the resource is. For example, a text file (linked resource) that `provides` a `closedCaptions` for a Video (context resource), or an audio file (linked resource) that `provides` an `audioDescription` of a Canvas (context resource). @@ -1451,7 +1451,7 @@ Note that the majority of the values have been selected from [accessibility feat ``` !!! warning "This breaks the graph as the file doesn't provide X in all contexts" -##### rendering +### rendering {: #rendering} A resource that is an alternative, non-IIIF representation of the resource that has the `rendering` property. Such representations typically cannot be painted onto a single Canvas, as they either include too many views, have incompatible dimensions, or are compound resources requiring additional rendering functionality. The `rendering` resource _MUST_ be able to be displayed directly to a human user, although the presentation may be outside of the IIIF client. The resource _MUST NOT_ have a splash page or other interstitial resource that mediates access to it. If access control is required, then the [IIIF Authentication API][iiif-auth] is _RECOMMENDED_. Examples include a rendering of a book as a PDF or EPUB, a slide deck with images of a building, or a 3D model of a statue. @@ -1474,7 +1474,7 @@ The value _MUST_ be an array of JSON objects. Each item _MUST_ have the `id`, `t ] } ``` -##### requiredStatement +### requiredStatement {: #requiredStatement} Text that _MUST_ be displayed when the resource is displayed or used. For example, the `requiredStatement` property could be used to present copyright or ownership statements, an acknowledgement of the owning and/or publishing institution, or any other text that the publishing organization deems critical to display to the user. Given the wide variation of potential client user interfaces, it will not always be possible to display this statement to the user in the client's initial state. If initially hidden, clients _MUST_ make the method of revealing it as obvious as possible. @@ -1493,7 +1493,7 @@ The value of the property _MUST_ be a JSON object, that has the `label` and `val } } ``` -##### rights +### rights {: #rights} A string that identifies a license or rights statement that applies to the content of the resource, such as the JSON of a Manifest or the pixels of an image. The value _MUST_ be drawn from the set of [Creative Commons][org-cc-licenses] license URIs, the [RightsStatements.org][org-rs-terms] rights statement URIs, or those added via the [extension][prezi40-ldce] mechanism. The inclusion of this property is informative, and for example could be used to display an icon representing the rights assertions. @@ -1516,7 +1516,7 @@ __Machine actionable URIs and links for users__
The machine actionable URIs for both Creative Commons licenses and RightsStatements.org right statements are `http` URIs. In both cases, human readable descriptions are available from equivalent `https` URIs. Clients may wish to rewrite links presented to users to use these equivalent `https` URIs. {: .note} -##### seeAlso +### seeAlso {: #seeAlso} A machine-readable resource such as an XML or RDF description that is related to the current resource that has the `seeAlso` property. Properties of the resource should be given to help the client select between multiple descriptions (if provided), and to make appropriate use of the document. If the relationship between the resource and the document needs to be more specific, then the document should include that relationship rather than the IIIF resource. Other IIIF resources are also valid targets for `seeAlso`, for example to link to a Manifest that describes a related object. The URI of the document _MUST_ identify a single representation of the data in a particular format. For example, if the same data exists in JSON and XML, then separate resources should be added for each representation, with distinct `id` and `format` properties. @@ -1542,7 +1542,7 @@ The value _MUST_ be an array of JSON objects. Each item _MUST_ have the `id` and ``` -##### service +### service {: #service} A service that the client might interact with directly and gain additional information or functionality for using the resource that has the `service` property, such as from an Image to the base URI of an associated [IIIF Image API][image-api] service. The service resource _SHOULD_ have additional information associated with it in order to allow the client to determine how to make appropriate use of it. Please see the [Service Registry][registry-services] document for the details of currently known service types. @@ -1597,7 +1597,7 @@ Implementations _SHOULD_ be prepared to recognize the `@id` and `@type` property ] } ``` -##### services +### services {: #services} A list of one or more service definitions on the top-most resource of the document, that are typically shared by more than one subsequent resource. This allows for these shared services to be collected together in a single place, rather than either having their information duplicated potentially many times throughout the document, or requiring a consuming client to traverse the entire document structure to find the information. The resource that the service applies to _MUST_ still have the `service` property, as described above, where the service resources have at least the `id` and `type` or `@id` and `@type` properties. This allows the client to know that the service applies to that resource. Usage of the `services` property is at the discretion of the publishing system. @@ -1631,7 +1631,7 @@ The value _MUST_ be an array of JSON objects. Each object _MUST_ be a service re ] } ``` -##### start +### start {: #start} A Canvas, or part of a Canvas, which the client _SHOULD_ show on initialization for the resource that has the `start` property. The reference to part of a Canvas is handled in the same way that Ranges reference parts of Canvases. This property allows the client to begin with the first Canvas that contains interesting content rather than requiring the user to manually navigate to find it. @@ -1664,7 +1664,7 @@ The value _MUST_ be a JSON object, which _MUST_ have the `id` and `type` propert } } ``` -##### structures +### structures {: #structures} The structure of an object represented as a Manifest can be described using a hierarchy of Ranges. Ranges can be used to describe the "table of contents" of the object or other structures that the user can interact with beyond the order given by the `items` property of the Manifest. The hierarchy is built by nesting the child Range resources in the `items` array of the higher level Range. The top level Ranges of these hierarchies are given in the `structures` property. @@ -1688,7 +1688,7 @@ The value _MUST_ be an array of JSON objects. Each item _MUST_ have the `id` and ] } ``` -##### summary +### summary {: #summary} A short textual summary intended to be conveyed to the user when the `metadata` entries for the resource are not being displayed. This could be used as a brief description for item level search results, for small-screen environments, or as an alternative user interface when the `metadata` property is not currently being rendered. The `summary` property follows the same pattern as the `label` property described above. @@ -1709,7 +1709,7 @@ The value of the property _MUST_ be a JSON object, as described in the [language { "summary": { "en": [ "This is a summary of the object." ] } } ``` -##### supplementary +### supplementary {: #supplementary} A link from this Range to an Annotation Collection that includes the `supplementing` Annotations of content resources for the Range. Clients might use this to present additional content to the user from a different Canvas when interacting with the Range, or to jump to the next part of the Range within the same Canvas. For example, the Range might represent a newspaper article that spans non-sequential pages, and then uses the `supplementary` property to reference an Annotation Collection that consists of the Annotations that record the text, split into Annotation Pages per newspaper page. Alternatively, the Range might represent the parts of a manuscript that have been transcribed or translated, when there are other parts that have yet to be worked on. The Annotation Collection would be the Annotations that transcribe or translate, respectively. @@ -1726,7 +1726,7 @@ The value _MUST_ be a JSON object, which _MUST_ have the `id` and `type` propert { "supplementary": { "id": "https://example.org/iiif/1/annos/1", "type": "AnnotationCollection" } } ``` -##### thumbnail +### thumbnail {: #thumbnail} A content resource, such as a small image or short audio clip, that represents the resource that has the `thumbnail` property. A resource _MAY_ have multiple thumbnail resources that have the same or different `type` and `format`. @@ -1759,7 +1759,7 @@ The value _MUST_ be an array of JSON objects, each of which _MUST_ have the `id` } ``` -##### timeMode +### timeMode {: #timeMode} A mode associated with an Annotation that is to be applied to the rendering of any time-based media, or otherwise could be considered to have a duration, used as a body resource of that Annotation. Note that the association of `timeMode` with the Annotation means that different resources in the body cannot have different values. This specification defines the values specified in the table below. Others may be defined externally as an [extension][prezi30-ldce]. @@ -1782,12 +1782,12 @@ The value _MUST_ be a string. ``` -##### totalItems +### totalItems For compatability with the Web Annotation Data Model, clients _SHOULD_ also accept `total` as the name of this property when used on the `AnnotationCollection` class. -##### transform +### transform {: #transform} _Summary here_ @@ -1798,7 +1798,7 @@ Process them in order given. -##### type +### type {: #type} The type or class of the resource. For classes defined for this specification, the value of `type` will be described in the sections below describing each individual class. @@ -1832,12 +1832,12 @@ For compatibility with previous versions, clients _SHOULD_ accept `Sound` as a s { "type": "Image" } ``` -##### unit +### unit FIXME: possible values are 'm' and 's' and 'relative' -##### value +### value metadata: @@ -1852,7 +1852,7 @@ FIXME: use scoped context for UnitValue to change the meaning of `value` -##### viewingDirection +### viewingDirection {: #viewingDirection} !!! Rewrite to be where is the navigation control to step to the next/ previous in the items of hte manifest @@ -1886,7 +1886,7 @@ The value _MUST_ be a string. { "viewingDirection": "left-to-right" } ``` -##### width +### width {: #width} The width of the Canvas or external content resource. For content resources, the value is in pixels. For Canvases, the value does not have a unit. In combination with the height, it conveys an aspect ratio for the space in which content resources are located. @@ -1905,18 +1905,18 @@ The value _MUST_ be a positive integer. { "width": 1200 } ``` -##### x +### x {: #x} A number (floating point or integer) giving the x coordinate of the point, relative to the dimensions of the source resource -##### y +### y {: #y} A number (floating point or integer) giving the y coordinate of the point, relative to the dimensions of the source resource -##### z +### z {: #z} A number (floating point) giving the z coordinate of the point, relative to the dimensions of the source resource From 429f7a12d386e1cc3c0583e07f89d1fb54d05357 Mon Sep 17 00:00:00 2001 From: Michael Appleby Date: Tue, 1 Apr 2025 18:36:35 -0400 Subject: [PATCH 060/130] Changes to UnitValue, inensity, lights --- source/presentation/4.0/model.md | 80 +++++++++++++++++--------------- 1 file changed, 43 insertions(+), 37 deletions(-) diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index 0fc8da575..563c0a544 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -509,54 +509,35 @@ Properties... } ``` - - - - - - - - - - #### Lights - - - + ##### Ambient Light `"type": "AmbientLight"` -Ambient Lights evenly illuminates all objects in the scene, and does not have a direction or position. - +Ambient Light evenly illuminates all objects in the Scene, and does not have a direction or position. ##### Directional Light `"type": "DirectionalLight"` -Directional Lights emits in a specific direction as if it is infinitely far away and the rays produced from it are all parallel. It does not have a specific position. - -If a DirectionalLight does not have an explicit direction, then the default is in the negative y direction (downwards). - -This is really that the light always has a direction of (-y) and is rotated from there. So no rotation = "default" direction. - +Directional Light emits in a specific direction as if it is infinitely far away and the rays produced from it are all parallel. It does not have a specific position. +The light emits in the negative Y (-y) direction by default, but the orientation of the light can be altered by subsequent transforms. ##### Point Light `"type": "PointLight"` -Point Lights emits from a single point within the scene in all directions. - +Point Light emits from a single point within the Scene in all directions. ##### Spot Light `"type": "SpotLight"` -Spot Lights emit a cone of light from a single point in a given direction. - -If a SpotLight does not have an explicit direction, then the default is in the negative y direction (downwards). +Spot Light emits a cone of light from a single point in a given direction. The Spot Light's `angle` property defines the radius of the cone. +The light emits in the negative Y (-y) direction by default, but the orientation of the light can be altered by subsequent transforms. #### Audio in Scenes @@ -632,9 +613,9 @@ A TranslateTransform moves all of the objects in the local coordinate space the #### Unit Value -`"type": "UnitValue"` - +A UnitValue expresses a quantity through a numerical value and associated unit of measurement. +`"type": "UnitValue"` ## Properties @@ -973,18 +954,24 @@ FIXME: fix ### intensity {: #intensity} -This property sets the strength or brightness of a Light. - -The value _MUST_ be a JSON object, that has the `type`, `value` and `unit` properties. All three properties are required. The value of `type` _MUST_ be the string "UnitValue". The value of `value` is a floating point number. The value of `unit` is a string, drawn from a controlled vocabulary of units. If this property is not specified, then the default intensity value is client-dependent. +This property sets the strength or brightness of a Light. If this property is not specified, then the default intensity value is client-dependent. -This specification defines the unit value of "relative" which constrains the value to be a linear scale between 0.0 (no brightness) and 1.0 (as bright as the client will render). +The value of this proerty _MUST_ be a UnitValue object. +The `unit` property of the UnitValue _MUST_ be `relative`. +The `value` property of the UnitValue _MUST_ be between 0.0 and 1.0. * A Light _SHOULD_ have the `intensity` property.
- Clients _SHOULD_ process the `intensity` property on Lights. + Clients _SHOULD_ process the `intensity` property on Lights.
+ Clients _SHOULD_ interpret the `value` on a linear scale between 0.0 (no brightness) and 1.0 (as bright as the client will render) +* Other resources _MUST NOT_ have the `intensity` property. ```json { - "intensity": {"id": "", "type": "UnitValue", "value": 0.5, "unit": "relative"} + "intensity": { + "id": "https://example.org/iiif/intensity/1", + "type": "UnitValue", + "value": 0.5, + "unit": "relative"} } ``` ### interactionMode @@ -1834,8 +1821,19 @@ For compatibility with previous versions, clients _SHOULD_ accept `Sound` as a s ### unit -FIXME: possible values are 'm' and 's' and 'relative' +The unit of measurement of a quantity expressed by a UnitValue. +The value _MUST_ be a string value. This specification defines the values in the table below. Others may be defined externally as an [extension][prezi30-ldce]. + +| Value | Unit | +|----------|-----------| +| m | meters | +| s | seconds | +| relative | relative | + +* A UnitValue _MUST_ have the `unit` property + +FIXME: possible values are 'm' and 's' and 'relative'. Is relative always 0-1.0, or context-dependent (see def of intensity)? Allow extensions? ### value @@ -1844,13 +1842,21 @@ metadata: {label: value: {"en": ["foo"]}} -UnitValue +### value (UnitValue) + +The `value` property of a UnitValue represents the numerical component of a quantity. + +The value _MUST_ be a floating point number. + +* A UnitValue _MUST_ have the `value` property. -unit: value: 0.1234123 +`"value": 0.1234123` FIXME: use scoped context for UnitValue to change the meaning of `value` +### value (WktSelector) +FIXME: another value value! ### viewingDirection {: #viewingDirection} From 1a13e1fac4565792c6681682cf37250157c56c7e Mon Sep 17 00:00:00 2001 From: Michael Appleby Date: Wed, 2 Apr 2025 11:23:56 -0400 Subject: [PATCH 061/130] Work on audio --- source/presentation/4.0/model.md | 73 ++++++++++++++++++++++++++------ 1 file changed, 59 insertions(+), 14 deletions(-) diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index 563c0a544..59be01cbe 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -523,7 +523,7 @@ Ambient Light evenly illuminates all objects in the Scene, and does not have a d Directional Light emits in a specific direction as if it is infinitely far away and the rays produced from it are all parallel. It does not have a specific position. -The light emits in the negative Y (-y) direction by default, but the orientation of the light can be altered by subsequent transforms. +The light is emitted in the negative Y (-y) direction by default, but the orientation of the light can be altered by subsequent transforms. ##### Point Light @@ -537,42 +537,66 @@ Point Light emits from a single point within the Scene in all directions. Spot Light emits a cone of light from a single point in a given direction. The Spot Light's `angle` property defines the radius of the cone. -The light emits in the negative Y (-y) direction by default, but the orientation of the light can be altered by subsequent transforms. +The Spot Light emits in the negative Y (-y) direction by default, but the orientation of the light can be altered by subsequent transforms. +```json +{ + "id": "https://example.org/iiif/spotLight/1", + "type": "SpotLight", + "angle": 15.0, + "color": "#FFFFFF", + "intensity": { + "type": "UnitValue", + "unit": "relative", + "value": 0.5 + } +} +``` #### Audio in Scenes -All have `source`, `volume` +Positional audio is supported through the use of Audio resources annotated into Scenes. +Audio resources _MUST_ have a `source` property that references an audio Content Resource, and _SHOULD_ have a `volume` property. ##### Ambient Audio `"type": "AmbientAudio"` +Ambient Audio emits equally throughout the Scene, and does not have a position or direction. ##### Point Audio `"type": "PointAudio"` +Point Audio emits from a single point in the Scene in all directions. + ##### Spot Audio `"type": "SpotAudio"` +Spot Audio emits a cone of sound from a single point in a given direction. The Spot Audio's `angle` property defines the radius of the cone. + +The Spot Audio emits in the negative Y (-y) direction by default, but the orientation of the sound can be altered by subsequent transforms. + ```json { - "id": "iiif/my/spotAudio", + "id": "https://example.org/iiif/spotAudio/1", "type": "SpotAudio", "source": { - "id": "/path/to/my.mp3", + "id": "https://example.org/media/path/to/my.mp3", "type": "Audio", "format": "audio/mp3" }, - "angle": 45.0 + "angle": 45.0, + "volume": { + "type": "UnitValue", + "unit": "relative", + "value": 2.0 + } } ``` -No default direction, MUST provide a Rotate Transform. - - +FIXME: "No default direction, MUST provide a Rotate Transform.", changed language to default to -y to match Spot Light #### Transforms @@ -954,16 +978,15 @@ FIXME: fix ### intensity {: #intensity} -This property sets the strength or brightness of a Light. If this property is not specified, then the default intensity value is client-dependent. +This property sets the strength or brightness of a Light. The `value` of the referenced UnitValue indicates the desired intensity on a linear scale between 0.0 (no brightness) and 1.0 (as bright as the client will render). If this property is not specified, then the default intensity value is client-dependent. -The value of this proerty _MUST_ be a UnitValue object. +The value of this proerty _MUST_ be a UnitValue. The `unit` property of the UnitValue _MUST_ be `relative`. The `value` property of the UnitValue _MUST_ be between 0.0 and 1.0. * A Light _SHOULD_ have the `intensity` property.
- Clients _SHOULD_ process the `intensity` property on Lights.
- Clients _SHOULD_ interpret the `value` on a linear scale between 0.0 (no brightness) and 1.0 (as bright as the client will render) -* Other resources _MUST NOT_ have the `intensity` property. + Clients _SHOULD_ process the `intensity` property on a Light. +* Other types of resource _MUST NOT_ have the `intensity` property. ```json { @@ -1438,6 +1461,7 @@ Note that the majority of the values have been selected from [accessibility feat ``` !!! warning "This breaks the graph as the file doesn't provide X in all contexts" + ### rendering {: #rendering} @@ -1618,6 +1642,15 @@ The value _MUST_ be an array of JSON objects. Each object _MUST_ be a service re ] } ``` + +### source +{: #source} + +A Content Resource that is used as the souce of audio information in an Audio resource. The value _MUST_ be a Content Resource with the `id`, `type`, and `format` properties. + +* Audio resources _MUST_ have the `source` property.
+ Clients _SHOULD_ process the `source` property on an Audio resource. + ### start {: #start} @@ -1892,6 +1925,18 @@ The value _MUST_ be a string. { "viewingDirection": "left-to-right" } ``` +### volume +{: #volume} + +The volume propery represents the relative volume of an audio source. The `value` of the specified UnitValue represents the desired volume on a linear scale from 0.0 (silence) to 1.0 (maximum volume). If this property is not specified, then the default volume value is client-dependent. + +The value of this property _MUST_ be a UnitValue. +The `unit` property of the UnitValue _MUST_ be `relative`. +The `value` property of the UnitValue _MUST_ be between 0.0 and 1.0. + +* Audio resource types _SHOULD_ have the `volume` property.
+ Clients _SHOULD_ process the `volume` property on an Audio resource. + ### width {: #width} From ec905def3b7227440be50aaaaabb8283e5d62998 Mon Sep 17 00:00:00 2001 From: Michael Appleby Date: Wed, 2 Apr 2025 11:31:50 -0400 Subject: [PATCH 062/130] Changes to intensity and source --- source/presentation/4.0/model.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index 59be01cbe..3955ed9cf 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -986,7 +986,6 @@ The `value` property of the UnitValue _MUST_ be between 0.0 and 1.0. * A Light _SHOULD_ have the `intensity` property.
Clients _SHOULD_ process the `intensity` property on a Light. -* Other types of resource _MUST NOT_ have the `intensity` property. ```json { @@ -1646,7 +1645,7 @@ The value _MUST_ be an array of JSON objects. Each object _MUST_ be a service re ### source {: #source} -A Content Resource that is used as the souce of audio information in an Audio resource. The value _MUST_ be a Content Resource with the `id`, `type`, and `format` properties. +A Content Resource that is used as the souce of audio information in an Audio resource. The value _MUST_ be a Content Resource with the `id`, `type` properties. * Audio resources _MUST_ have the `source` property.
Clients _SHOULD_ process the `source` property on an Audio resource. From 95ff1d347e3a1bebb6e67d0bee89f730ba523637 Mon Sep 17 00:00:00 2001 From: Michael Appleby Date: Fri, 4 Apr 2025 13:54:15 -0400 Subject: [PATCH 063/130] Fix property typo --- source/presentation/4.0/model.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index 3955ed9cf..2212e863d 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -1927,7 +1927,7 @@ The value _MUST_ be a string. ### volume {: #volume} -The volume propery represents the relative volume of an audio source. The `value` of the specified UnitValue represents the desired volume on a linear scale from 0.0 (silence) to 1.0 (maximum volume). If this property is not specified, then the default volume value is client-dependent. +The volume property represents the relative volume of an audio source. The `value` of the specified UnitValue represents the desired volume on a linear scale from 0.0 (silence) to 1.0 (maximum volume). If this property is not specified, then the default volume value is client-dependent. The value of this property _MUST_ be a UnitValue. The `unit` property of the UnitValue _MUST_ be `relative`. From 5693034b4c90dfa5a11011f499b1d4f140a945e7 Mon Sep 17 00:00:00 2001 From: Rob Sanderson Date: Fri, 4 Apr 2025 16:13:26 -0400 Subject: [PATCH 064/130] updates --- source/presentation/4.0/model.md | 112 ++++++++++++++++++++----------- 1 file changed, 74 insertions(+), 38 deletions(-) diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index 2212e863d..3c674e8f0 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -1,7 +1,7 @@ --- title: "Presentation API 4.0 Properties" title_override: "IIIF Presentation API 4.0 Properties" -id: presentation-api-properties +id: presentation-api-model layout: spec cssversion: 3 tags: [specifications, presentation-api] @@ -10,8 +10,8 @@ minor: 0 patch: 0 pre: redirect_from: - - /presentation/properties.html - - /presentation/4/properties.html + - /presentation/model.html + - /presentation/4/model.html editors: - name: Michael Appleby ORCID: https://orcid.org/0000-0002-1266-298X @@ -55,6 +55,9 @@ __Previous Version:__ [3.0][prezi30] ## Introduction +The IIIF Presentation API is backed by a standards-based data model inspired by both earlier tree structured representations of cultural heritage objects, as well as linked data approaches with the same goal. It comprises four main types of resource: Structural (such as Collections, Manifests, and Ranges), Presentational Containers (Canvas, Scene and Timeline), Linking (Annotations), and Content (the images, texts, audio, video and models to be displayed). +The model intentionaly does not include any semantic or descriptive relationships or properties such as the author of a book or the place where a statue was sculpted; it is solely for presenting content in a structured fashion to human users. + ### Terminology @@ -69,7 +72,6 @@ The terms _array_, _JSON object_, _number_, _string_, and _boolean_ in this docu The key words _MUST_, _MUST NOT_, _REQUIRED_, _SHALL_, _SHALL NOT_, _SHOULD_, _SHOULD NOT_, _RECOMMENDED_, _MAY_, and _OPTIONAL_ in this document are to be interpreted as described in [RFC 2119][org-rfc-2119]. - ## JSON Considerations This section describes features applicable to all of the Presentation API content. @@ -100,7 +102,7 @@ Any of the properties in the API that can have multiple values _MUST_ always be Language _SHOULD_ be associated with strings that are intended to be displayed to the user for the `label` and `summary` properties, plus the `label` and `value` properties of the `metadata` and `requiredStatement` objects. -The values of these properties _MUST_ be JSON objects, with the keys being the [BCP 47][org-bcp-47] language code for the language, or if the language is either not known or the string does not have a language, then the key _MUST_ be the string `none`. The associated values _MUST_ be arrays of strings, where each item is the content in the given language. +The values of these properties _MUST_ be JSON objects, with the keys being the [BCP 47][org-bcp-47] language code for the language, or if the language is either not known or the string does not have a language, then the key _MUST_ be the string `none`. The script _SHOULD NOT_ be included in the tag, even though BCP 47 allows for this possibility. The associated values _MUST_ be arrays of strings, where each item is the content in the given language. {% include api/code_header.html %} ``` json-doc @@ -120,8 +122,6 @@ The values of these properties _MUST_ be JSON objects, with the keys being the [ } ``` -Note that [BCP 47][org-bcp-47] allows the script of the text to be included after a hyphen, such as `ar-latn`, and clients should be aware of this possibility. - In the case where multiple values are supplied, clients _MUST_ use the following algorithm to determine which values to display to the user. * If all of the values are associated with the `none` key, the client _MUST_ display all of those values. @@ -134,7 +134,7 @@ Note that this does not apply to [embedded][prezi30-terminology] textual bodies ### HTML Markup in Property Values -Minimal HTML markup _MAY_ be included for processing in the `summary` property and the `value` property in the `metadata` and `requiredStatement` objects. It _MUST NOT_ be used in `label` or other properties. This is included to allow content publishers to add links and simple formatting instructions to blocks of text. The content _MUST_ be well-formed XML and therefore _MUST_ be wrapped in an element such as `p` or `span`. There _MUST NOT_ be whitespace on either side of the HTML string, and thus the first character in the string _MUST_ be a '<' character and the last character _MUST_ be '>', allowing a consuming application to test whether the value is HTML or plain text using these. To avoid a non-HTML string matching this, it is _RECOMMENDED_ that an additional whitespace character be added to the end of the value in situations where plain text happens to start and end this way. +Minimal HTML markup _MAY_ be included for processing in the `summary` property and the `value` property in the `metadata` and `requiredStatement` objects. It _MUST NOT_ be used in `label` or other properties. This is included to allow content publishers to add links and simple formatting instructions to blocks of text. The content _MUST_ be well-formed XML and wrapped in a single element such as `div`, `p` or `span`. There _MUST NOT_ be whitespace on either side of the HTML string, and thus the first character in the string _MUST_ be a '<' character and the last character _MUST_ be '>', allowing a consuming application to test whether the value is HTML or plain text using these. To avoid a non-HTML string matching this, it is _RECOMMENDED_ that an additional whitespace character be added to the end of the value in situations where plain text happens to start and end this way. In order to avoid HTML or script injection attacks, clients _MUST_ remove: @@ -145,7 +145,7 @@ In order to avoid HTML or script injection attacks, clients _MUST_ remove: * XML Comments. * Processing instructions. -Clients _SHOULD_ allow only `a`, `b`, `br`, `i`, `img`, `p`, `small`, `span`, `sub` and `sup` tags. Clients _MAY_ choose to remove any and all tags, therefore it _SHOULD NOT_ be assumed that the formatting will always be rendered. Note that publishers _MAY_ include arbitrary HTML content for processing using customized or experimental applications, and the requirements for clients assume an untrusted or unknown publisher. +Clients _SHOULD_ allow only `a`, `b`, `br`, `div`, `i`, `img`, `p`, `small`, `span`, `sub` and `sup` tags. Clients _MAY_ choose to remove any and all tags, therefore it _SHOULD NOT_ be assumed that the formatting will always be rendered. Note that publishers _MAY_ include arbitrary HTML content for processing using customized or experimental applications, and the requirements for clients assume an untrusted or unknown publisher. {% include api/code_header.html %} ``` json-doc @@ -154,7 +154,7 @@ Clients _SHOULD_ allow only `a`, `b`, `br`, `i`, `img`, `p`, `small`, `span`, `s ### JSON Description Availability -JSON descriptions _SHOULD_ be [embedded][prezi30-terminology] within the JSON of parent resources, and _MAY_ also be available via separate requests from the HTTP(S) URI given in the resource's `id` property. Links to Content Resources _MUST_ be given as a JSON object with the `id` and `type` properties and _SHOULD_ have `format` or `profile` to give a hint as to what sort of resource is being referred to. +JSON descriptions _SHOULD_ be embedded within the JSON of parent resources, and _MAY_ also be available via separate requests from the HTTP(S) URI given in the resource's `id` property. Links to Content Resources _MUST_ be given as a JSON object with the `id` and `type` properties and _SHOULD_ have `format` or `profile` to give a hint as to what sort of resource is being referred to. {% include api/code_header.html %} ``` json-doc @@ -170,8 +170,6 @@ JSON descriptions _SHOULD_ be [embedded][prezi30-terminology] within the JSON of } ``` - - ## Classes The following sub-sections define the classes used in the IIIF Presentation Data Model. Only the semantics and core structural requirements are defined within this section, along with any deviations from other specifications that the classes might be drawn from. The descriptions do not define how the classes are used together, which is done in the Presentation API Overview. @@ -181,44 +179,57 @@ The name of each class is given at the top of its definition below. The exact st ### Collection {: #Collection} -`"type": "Collection"` +> `"type": "Collection"` A Collection is an ordered list of Manifests, and/or Collections. -The identifier in `id` _MUST_ be able to be dereferenced to retrieve the JSON description of the Collection, and thus _MUST_ use the HTTP(S) URI scheme. +A Collection _MUST_ have an HTTP(S) URI given in `id`. It _MUST_ be able to be dereferenced to retrieve the JSON description. -The members of a Collection are typically listed in the `items` property. The members _MAY_ include both other Collections and Manifests, in order, to form a tree-structured hierarchy. +The members of a Collection are typically listed in the `items` property or in a series of Collection Pages. The members _MAY_ include both other Collections and Manifests, in order, to form a tree-structured hierarchy. Collections without any members are allowed but discouraged. For example, a collection that had its last member removed might still be valuable to maintain as an empty collection. -If there are too many members in the collection to fit within a single document, then the members _MAY_ be listed in Collection Pages. A reference to the first page of members is given in the `first` property, and the last page in the `last` property. In this case, the Collection _MUST NOT_ use the `items` property. +If there are too many members in the collection to fit within a single document, then the members _MAY_ be listed in Collection Pages. A reference to the first page of members is given in the `first` property, and the last page in the `last` property. In this case, the Collection _MUST NOT_ use the `items` property. Collections with pages _MUST_ have at least two pages, otherwise the members should be included in `items` on the Collection. Collection Pages _MUST NOT_ be embedded within the Collection for the same reason. -Member Collections _MAY_ be [embedded][prezi30-terminology] inline within other Collections, such as when the Collection is used primarily to subdivide a larger one into more manageable pieces, however Manifests _MUST NOT_ be [embedded][prezi30-terminology] within Collections. An [embedded][prezi30-terminology] Collection _SHOULD_ also have its own URI from which the JSON description is available. +Member Collections _MAY_ be embedded inline within other Collections, however Manifests _MUST NOT_ be embedded within Collections. An embedded Collection _SHOULD_ also have its own URI from which the JSON description is available. Manifests or Collections _MAY_ be [referenced][prezi30-terminology] from more than one Collection. For example, an institution might define four Collections: one for modern works, one for historical works, one for newspapers and one for books. The Manifest for a modern newspaper would then appear in both the modern Collection and the newspaper Collection. Alternatively, the institution may choose to have two separate newspaper Collections, and reference each as a sub-Collection of modern and historical. -Collections with an empty `items` property are allowed but discouraged. For example, if the user performs a search that matches no Manifests, then the server _MAY_ return a Collection response with no Manifests. -Collections or Manifests [referenced][prezi30-terminology] in the `items` property _MUST_ have the `id`, `type` and `label` properties. They _SHOULD_ have the `thumbnail` property. +Collections or Manifests referenced in the `items` property _MUST_ have the `id`, `type` and `label` properties. They _SHOULD_ have the `thumbnail` property. + +__Properties__
+A Collection _MUST_ have the following properties: [id](#id), [type](#type), and [label](#label)

+A Collection _SHOULD_ have the following properties: [metadata](#metadata), [summary](#summary), [provider](#provider), [thumbnail](#thumbnail), and [items](#items)

+A Collection _MAY_ have the following properties: [requiredStatement](#requiredStatement), [rights](#rights), [navDate](#navDate), [navPlace](#navPlace), [placeholderContainer](#placeholderContainer), [accompanyingContainer](#accompanyingContainer), [viewingDirection](#viewingDirection), [behavior](#behavior), [seeAlso](#seeAlso), [service](#service), [services](#services), [homepage](#homepage), [rendering](#rendering), [partOf](#partOf), [start](#start), [first](#first), [last](#last), [total](#total) and [annotations](#annotations). +{: .note} + #### Collection Page {: #CollectionPage} -`"type": "CollectionPage"` +> `"type": "CollectionPage"` + +A Collection Page is an arbitrary division of members within the Collection to make it easier to consume by clients. It does not have any semantic implications by itself. The Collection Page model follows the ActivityStreams OrderedCollection model, as also used in Annotation Collections, the IIIF Change Discovery API, and the IIIF Search API. -A Collection Page is an arbitrary division of members within the Collection to make it easier to consume. +A Collection Page _MUST_ have an HTTP(S) URI given in `id`. It _MUST_ be able to be dereferenced to retrieve the JSON description. Collection Pages _MUST NOT_ be embedded within Collections. -A Collection Page _MUST_ have an HTTP(S) URI given in `id`. It _MUST_ be able to be dereferenced to retrieve the JSON description of the Collection Page. +All Collection Pages in a Collection, with the exception of the last page, _MUST_ have the `next` property, which provides a reference to the following Collection Page. All Collection Pages in a Collection, with the exception of the first page, _MUST_ have the `prev` property, which provides a reference to the preceding Collection Page. These properties allow the navigation backwards and forwards within the overall set of pages. There is no way to jump to arbitrary positions in the sequence of pages, and clients _MUST NOT_ attempt to infer such methods from the structure of the URI of the Collection Page. Collection Pages _MUST_ have the `partOf` property, refering to the Collection of which they are part. -Collection Pages follow the ActivityStreams model, as also used in Annotation Collections, the IIIF Change Discovery API, and the IIIF Search API. +__Properties__
+A Collection Page _MUST_ have the following properties: [id](#id), [type](#type), [partOf](#partOf) and [items](#items)

+A Collection Page _SHOULD_ have the following properties: [next](#next), and [prev](#prev)

+A Collection Page _MAY_ have the following properties: [startIndex](#startIndex), [metadata](#metadata), [summary](#summary), [provider](#provider), [thumbnail](#thumbnail), [requiredStatement](#requiredStatement), [rights](#rights), [behavior](#behavior), [seeAlso](#seeAlso), [service](#service), and [annotations](#annotations). +{: .note} ### Manifest +{: #Manifest} -`"type": "Manifest"` +> `"type": "Manifest"` A Manifest is the primary unit of distribution of IIIF and provides a description of the structure and properties of a single item to be presented to the user. -Manifests _MUST_ be identified by a URI and it _MUST_ be an HTTP(S) URI, given in the `id` property. It _MUST_ be able to be dereferenced to retrieve the JSON description of the Manifest. +Manifests _MUST_ be identified by a URI and it _MUST_ be an HTTP(S) URI, given in the `id` property. It _MUST_ be able to be dereferenced to retrieve the JSON description. The members of a Manifest are listed in the `items` property. The members of Manifests _MUST_ be Containers, defined below, and are embedded within the Manifest. The Manifest _MAY_ have a `structures` property listing one or more [Ranges][#range] which describe additional structure of the content, such as might be rendered as a table of contents. The Manifest _MAY_ have an `annotations` property, which includes Annotation Page resources where the Annotations have the Manifest as their `target`. These Annotations _MUST NOT_ have `painting` as their `motivation`. @@ -234,32 +245,44 @@ A Manifest _MAY_ have the following properties: [requiredStatement](#requiredSta A Container is a frame of reference that allows the relative positioning of content. -All Containers _MUST_ be identified by a URI and it _MUST_ be an HTTP(S) URI. The URI of the Container _MUST NOT_ contain a fragment (a `#` followed by further characters), as this would make it impossible to refer to a segment of the Container's area using the [media fragment syntax][org-w3c-media-frags] of `#xywh=` for spatial regions, and/or `#t=` for temporal segments. The temporal segment _MUST_ be expressed using seconds. Containers _MAY_ be able to be dereferenced separately from the Manifest via their URIs as well as being [embedded][prezi30-terminology]. +All Containers _MUST_ be identified by a URI and it _MUST_ be an HTTP(S) URI. The URI of the Container _MUST NOT_ contain a fragment (a `#` followed by further characters), as this would make it impossible to refer to a segment of the Container's area using the [media fragment syntax][org-w3c-media-frags] of `#xywh=` for spatial regions, and/or `#t=` for temporal segments. The temporal segment _MUST_ be expressed using seconds. Containers _MAY_ be able to be dereferenced separately from the Manifest via their URIs as well as being embedded. Containers _MUST_ have an `items` property which is a list of Annotation Pages. Each Annotation Page, defined below, maintains a list of Annotations, which associate Content Resources to be rendered as part of the Container. Annotations that do not associate content to be rendered, but instead are about the Container such as a comment or tag, are recorded using Annotation Pages in the `annotations` property of the Container. -FIXME: It is an error to select a temporal region of a Scene that does not have a `duration`, or to select a temporal region that is not within the Scene's temporal extent. A Canvas or Scene with a `duration` may not be annotated as a content resource into a Scene that does not itself have a `duration`. - +For Timelines and Canvases, Annotations _MUST NOT_ target spatial or temporal points or regions outside of the bounds of the Container. For Scenes with a `duration`, Annotations _MUST NOT_ target temporal points or regions outside of that duration. Scenes, Canvases and other content with spatial extents _MUST NOT_ be annotated directly onto a Timeline which does not have a spatial extent. Resources with a `duration`, including Timelines and Canvases, _MAY_ be painted into Canvases and Scenes without a `duration`, however the playback of the resource will not able to be controlled or synchronized without other time-based media. +__Properties__
+All Containers _MUST_ have the following properties: [id](#id), and [type](#type)

+All Containers _SHOULD_ have the following properties: [label](#label), and [items](#items)

+All Containers _MAY_ have the following properites: [metadata](#metadata), [summary](#summary), [provider](#provider), [thumbnail](#thumbnail), [requiredStatement](#requiredStatement), [rights](#rights), [navDate](#navDate), [navPlace](#navPlace), [placeholderContainer](#placeholderContainer), [accompanyingContainer](#accompanyingContainer), [behavior](#behavior), [seeAlso](#seeAlso), [service](#service), [homepage](#homepage), [rendering](#rendering), [partOf](#partOf), and [annotations](#annotations). +{: .note} #### Timeline -`"type": "Timeline"` +> `"type": "Timeline"` A Timeline is a Container that represents only a temporal duration, measured in seconds. Timelines allow audio content to be presented, but do not allow anything with a height or width like an image or video. The duration of the Timeline is given in the `duration` property. +__Properties__
+A Timeline _MUST_ have the following additional properties: [duration](#duration). +{: .note} + #### Canvas -`"type": "Canvas"` +> `"type": "Canvas"` + +A Canvas is a Container that represents a particular rectangular 2 dimensional view of the object and has content resources associated with it or with parts of it. This aspect ratio is defined by the `height` and `width` properties. The values of these properties are not pixels, but arbitrary units into which pixel-based resources can be scaled. A Canvas _MAY_ also have a duration, given in the `duration` property, allowing audio and video to be correctly positioned in time as well as the 2 dimensional space. -A Canvas is a Container that represents a particular rectangular 2 dimensional view of the object and has content resources associated with it or with parts of it. This aspect ratio is defined by the `height` and `width` properties. A Canvas _MAY_ also have a duration, given in the `duration` property, allowing audio and video to be correctly positioned in time as well as the 2 dimensional space. +__Properties__
+A Canvas _MUST_ have the following additional properties: [height](#height), and [width](#width).

+A Canvas _MAY_ have the following additional properties: [duration](#duration). +{: .note} -FIXME: arbitrary units #### Scene -`"type": "Scene"` +> `"type": "Scene"` A Scene is a Container that represents an infinitely large three-dimensional space, with an optional `duration` property. Scenes have infinite height (y axis), width (x axis) and depth (z axis), where 0 on each axis (the origin of the coordinate system) is treated as the center of the scene's space. From a perspective looking along the z axis towards negative infinity, the positive y axis points upwards and the positive x axis points to the right (a [right-handed Cartesian coordinate system](https://en.wikipedia.org/wiki/Right-hand_rule)). @@ -269,7 +292,9 @@ The axes of the coordinate system are measured in arbitrary units and these unit All resources that can be added to a Scene have an implicit (e.g. Lights, Cameras) or explicit (e.g. Models, Scenes), local coordinate space. - +__Properties__
+A Scene _MAY_ have the following additional properties: [duration](#duration). +{: .note} @@ -280,7 +305,7 @@ The following set of classes are defined by the W3C's [Web Annotation Data Model #### Annotation -`"type": "Annotation"` +> `"type": "Annotation"` Annotations are used to associate content resources with Containers, as well as for transcriptions, commentary, tags and the association of other content. This provides a single, unified method for aligning information, and provides a standards-based framework for distinguishing parts of resources and parts of Canvases. @@ -1653,10 +1678,14 @@ A Content Resource that is used as the souce of audio information in an Audio re ### start {: #start} -A Canvas, or part of a Canvas, which the client _SHOULD_ show on initialization for the resource that has the `start` property. The reference to part of a Canvas is handled in the same way that Ranges reference parts of Canvases. This property allows the client to begin with the first Canvas that contains interesting content rather than requiring the user to manually navigate to find it. +A Canvas, or part of a Canvas, which the client _SHOULD_ show on initialization for the resource that has the `start` property. The reference to part of a Canvas is handled in the same way that Ranges reference parts of Canvases by using either a Canvas URI, a Canvas URI with a fragment in the URI, or a SpecificResource with a Selector. This property allows the client to begin with the first Canvas that contains interesting content rather than requiring the user to manually navigate to find it. + +If the resource with the `start` property is a Collection, then the Canvas (or SpecificResource) _MUST_ have the `partOf` property refering to the Manifest that it is part of, such that the client can retrieve it. The value _MUST_ be a JSON object, which _MUST_ have the `id` and `type` properties. The object _MUST_ be either a Canvas (as in the first example below), or a Specific Resource with a Selector and a `source` property where the value is a Canvas (as in the second example below). + * A Collection _MAY_ have the `start` property.
+ Clients _SHOULD_ process `start` on a Collection. * A Manifest _MAY_ have the `start` property.
Clients _SHOULD_ process `start` on a Manifest. * A Range _MAY_ have the `start` property.
@@ -1683,6 +1712,12 @@ The value _MUST_ be a JSON object, which _MUST_ have the `id` and `type` propert } } ``` + +### startIndex +{: #startIndex} + + + ### structures {: #structures} @@ -1801,9 +1836,10 @@ The value _MUST_ be a string. ``` -### totalItems +### total -For compatability with the Web Annotation Data Model, clients _SHOULD_ also accept `total` as the name of this property when used on the `AnnotationCollection` class. +For compatability with ActivityStreams and the Change Discovery API, clients _SHOULD_ also accept `totalItems` as the name of this property. +{: .note} ### transform From 18fb1a5b033a48d18a2acf130f105267fb261ab4 Mon Sep 17 00:00:00 2001 From: Rob Sanderson Date: Fri, 4 Apr 2025 17:40:51 -0400 Subject: [PATCH 065/130] update --- source/presentation/4.0/model.md | 127 ++++++++++++++++++++++--------- 1 file changed, 91 insertions(+), 36 deletions(-) diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index 3c674e8f0..3fd81106d 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -176,6 +176,10 @@ The following sub-sections define the classes used in the IIIF Presentation Data The name of each class is given at the top of its definition below. The exact string _MUST_ be used as the value of `type` in the JSON for the class. +__Properties__
+All resources _MUST_ have the following properties: [id](#id), and [type](#type). +{: .note} + ### Collection {: #Collection} @@ -199,7 +203,7 @@ Collections or Manifests referenced in the `items` property _MUST_ have the `id` __Properties__
A Collection _MUST_ have the following properties: [id](#id), [type](#type), and [label](#label)

A Collection _SHOULD_ have the following properties: [metadata](#metadata), [summary](#summary), [provider](#provider), [thumbnail](#thumbnail), and [items](#items)

-A Collection _MAY_ have the following properties: [requiredStatement](#requiredStatement), [rights](#rights), [navDate](#navDate), [navPlace](#navPlace), [placeholderContainer](#placeholderContainer), [accompanyingContainer](#accompanyingContainer), [viewingDirection](#viewingDirection), [behavior](#behavior), [seeAlso](#seeAlso), [service](#service), [services](#services), [homepage](#homepage), [rendering](#rendering), [partOf](#partOf), [start](#start), [first](#first), [last](#last), [total](#total) and [annotations](#annotations). +A Collection _MAY_ have the following properties: [requiredStatement](#requiredStatement), [rights](#rights), [navDate](#navDate), [navPlace](#navPlace), [placeholderContainer](#placeholderContainer), [accompanyingContainer](#accompanyingContainer), [viewingDirection](#viewingDirection), [behavior](#behavior), [seeAlso](#seeAlso), [service](#service), [services](#services), [homepage](#homepage), [rendering](#rendering), [partOf](#partOf), [start](#start), [first](#first), [last](#last), [total](#total), [canonical](#canonical), [via](#via), and [annotations](#annotations). {: .note} @@ -218,7 +222,7 @@ All Collection Pages in a Collection, with the exception of the last page, _MUST __Properties__
A Collection Page _MUST_ have the following properties: [id](#id), [type](#type), [partOf](#partOf) and [items](#items)

A Collection Page _SHOULD_ have the following properties: [next](#next), and [prev](#prev)

-A Collection Page _MAY_ have the following properties: [startIndex](#startIndex), [metadata](#metadata), [summary](#summary), [provider](#provider), [thumbnail](#thumbnail), [requiredStatement](#requiredStatement), [rights](#rights), [behavior](#behavior), [seeAlso](#seeAlso), [service](#service), and [annotations](#annotations). +A Collection Page _MAY_ have the following properties: [startIndex](#startIndex), [metadata](#metadata), [summary](#summary), [provider](#provider), [thumbnail](#thumbnail), [requiredStatement](#requiredStatement), [rights](#rights), [behavior](#behavior), [seeAlso](#seeAlso), [service](#service), [homepage](#homepage), [rendering](#rendering), [canonical](#canonical), [via](#via), and [annotations](#annotations). {: .note} @@ -237,7 +241,7 @@ The members of a Manifest are listed in the `items` property. The members of Man __Properties__
A Manifest _MUST_ have the following properties: [id](#id), [type](#type), [label](#label), and [items](#items)

A Manifest _SHOULD_ have the following properties: [metadata](#metadata), [summary](#summary), [provider](#provider), and [thumbnail](#thumbnail)

-A Manifest _MAY_ have the following properties: [requiredStatement](#requiredStatement), [rights](#rights), [navDate](#navDate), [navPlace](#navPlace), [placeholderContainer](#placeholderContainer), [accompanyingContainer](#accompanyingContainer), [viewingDirection](#viewingDirection), [behavior](#behavior), [seeAlso](#seeAlso), [service](#service), [services](#services), [homepage](#homepage), [rendering](#rendering), [partOf](#partOf), [start](#start), [structures](#structures), and [annotations](#annotations). +A Manifest _MAY_ have the following properties: [requiredStatement](#requiredStatement), [rights](#rights), [navDate](#navDate), [navPlace](#navPlace), [placeholderContainer](#placeholderContainer), [accompanyingContainer](#accompanyingContainer), [viewingDirection](#viewingDirection), [behavior](#behavior), [seeAlso](#seeAlso), [service](#service), [services](#services), [homepage](#homepage), [rendering](#rendering), [partOf](#partOf), [start](#start), [canonical](#canonical), [via](#via), [structures](#structures), and [annotations](#annotations). {: .note} ### Container Classes @@ -254,7 +258,7 @@ For Timelines and Canvases, Annotations _MUST NOT_ target spatial or temporal po __Properties__
All Containers _MUST_ have the following properties: [id](#id), and [type](#type)

All Containers _SHOULD_ have the following properties: [label](#label), and [items](#items)

-All Containers _MAY_ have the following properites: [metadata](#metadata), [summary](#summary), [provider](#provider), [thumbnail](#thumbnail), [requiredStatement](#requiredStatement), [rights](#rights), [navDate](#navDate), [navPlace](#navPlace), [placeholderContainer](#placeholderContainer), [accompanyingContainer](#accompanyingContainer), [behavior](#behavior), [seeAlso](#seeAlso), [service](#service), [homepage](#homepage), [rendering](#rendering), [partOf](#partOf), and [annotations](#annotations). +All Containers _MAY_ have the following properites: [metadata](#metadata), [summary](#summary), [provider](#provider), [thumbnail](#thumbnail), [requiredStatement](#requiredStatement), [rights](#rights), [navDate](#navDate), [navPlace](#navPlace), [placeholderContainer](#placeholderContainer), [accompanyingContainer](#accompanyingContainer), [behavior](#behavior), [seeAlso](#seeAlso), [service](#service), [homepage](#homepage), [rendering](#rendering), [partOf](#partOf), [canonical](#canonical), [via](#via), and [annotations](#annotations). {: .note} @@ -309,58 +313,92 @@ The following set of classes are defined by the W3C's [Web Annotation Data Model Annotations are used to associate content resources with Containers, as well as for transcriptions, commentary, tags and the association of other content. This provides a single, unified method for aligning information, and provides a standards-based framework for distinguishing parts of resources and parts of Canvases. -Annotations _MUST_ have their own HTTP(S) URIs, conveyed in the `id` property. The JSON-LD description of the Annotation _SHOULD_ be returned if the URI is dereferenced, according to the [Web Annotation Protocol][org-w3c-webanno-protocol]. +An Annotation _MUST_ have an HTTP(S) URI given in `id`. The JSON-LD description of the Annotation _SHOULD_ be returned if the URI is dereferenced, according to the [Web Annotation Protocol][org-w3c-webanno-protocol]. -When Annotations are used to associate content resources with a Canvas, the content resource is linked in the `body` of the Annotation. The URI of the Canvas _MUST_ be repeated in the `target` property of the Annotation, or the `source` property of a Specific Resource used in the `target` property. +When Annotations are used to associate content resources with a Canvas, the content resource is linked in the `body` of the Annotation. The URI of the Canvas _MUST_ be repeated in the `target` property of the Annotation, or the `source` property of a Specific Resource used in the `target` property. Content that is to be rendered as part of the Container _MUST_ be associated by an Annotation that has the `motivation` value `painting`. -Content that is to be rendered as part of the Container _MUST_ be associated by an Annotation that has the `motivation` value `painting`. +Annotations _SHOULD NOT_ use the `bodyValue` property defined by the Web Annotation Data Model, but instead use the more consistent TextualBody class. -Note that the Web Annotation data model defines different patterns for the `value` property compared to IIIF, when used within an Annotation. The `value` of a Textual Body or a Fragment Selector, for example, are strings rather than JSON objects with languages and values. Care must be taken to use the correct string form in these cases. +__Properties__
+An Annotation _MUST_ have the following properties: [id](#id), [type](#type), [target](#target), [motivation](#motivation).

+An Annotation _SHOULD_ have the following properties: [body](#body).

+An Annotation _MAY_ have the following properties: [label](#label), [metadata](#metadata), [summary](#summary), [provider](#provider), [thumbnail](#thumbnail), [requiredStatement](#requiredStatement), [rights](#rights), [navDate](#navDate), [navPlace](#navPlace), [provides](#provides), [behavior](#behavior), [timeMode](#timeMode), [stylesheet](#stylesheet), [seeAlso](#seeAlso), [service](#service), [homepage](#homepage), [rendering](#rendering), [partOf](#partOf), [canonical](#canonical), and [via](#via).

+{: .note} #### Annotation Collection -`"type": "AnnotationCollection"` +> `"type": "AnnotationCollection"` Annotation Collections allow groups of Annotations to be recorded. For example, all of the English translation Annotations of a medieval French document could be kept separate from the transcription or an edition in modern French, or the director's commentary on a film can be separated from the script. -Annotation Collections _MUST_ have a URI, and it _SHOULD_ be an HTTP(S) URI. They _SHOULD_ have a `label` and _MAY_ have any of the other descriptive, linking or rights properties. +Annotation Collections _MUST_ have an HTTP(S) URI. The JSON-LD description _SHOULD_ be returned if the URI is dereferenced. -Annotation Collections are paged rather than enumerated. The first page of items is linked using the `first` property, and the last page with the `last` property. The pages link to the next and previous pages in a chain, using the `next` and `prev` properties respectively. +Annotation Collections are always paged using `first` and `last`, rather than `items` as with IIIF Collections. + +__Properties__
+An Annotation Collection _MUST_ have the following properties: [id](#id), [type](#type), [label](#label), [first](#first), and [last](#last).

+An Annotation Collection _SHOULD_ have the following properties: [metadata](#metadata), [summary](#summary), [provider](#provider), [thumbnail](#thumbnail).

+An Annotation Collection _MAY_ have the following properties: [requiredStatement](#requiredStatement), [rights](#rights), [navDate](#navDate), [navPlace](#navPlace), [placeholderContainer](#placeholderContainer), [accompanyingContainer](#accompanyingContainer), [viewingDirection](#viewingDirection), [behavior](#behavior), [seeAlso](#seeAlso), [service](#service), [services](#services), [homepage](#homepage), [rendering](#rendering), [partOf](#partOf), [start](#start), [first](#first), [last](#last), [total](#total), [canonical](#canonical), [via](#via), and [annotations](#annotations). +{: .note} #### Annotation Page -`"type": "AnnotationPage"` +> `"type": "AnnotationPage"` An ordered list of Annotations, typically associated with a Container, but may be referenced from other types of resource as well. Annotation Pages enumerate and order lists of Annotations, in the same way that Collection Pages order lists of Manifests and Collections within the containing Collection. -An Annotation Page _MUST_ have an HTTP(S) URI given in `id`, and _MAY_ have any of the other properties defined in this specification or the Web Annotation specification. The Annotations are listed in the `items` property of the Annotation Page. +An Annotation Page _MUST_ have an HTTP(S) URI given in `id`. The Annotations are listed in the `items` property of the Annotation Page. -Annotations are embedded within an Annotation Page in the `items` property. - -__Incompatibility Warning__
-The definition of `label` in the Web Annotation specification does not produce JSON conformant with the structure defined in this specification for languages. Given the absolute requirement for internationalized labels and the strong desire for consistently handling properties, the `label` property on Annotation model classes does not conform to the string requirement of the Web Annotation Data Model. This [issue has been filed with the W3C][github-webanno-437] and will hopefully be addressed in a future version of the standard. -{: .warning} +__Properties__
+An Annotation Page _MUST_ have the following properties: [id](#id), [type](#type), and [items](#items)

+An Annotation Page _SHOULD_ have the following properties: [next](#next), [prev](#prev), and [partOf](#partOf)

+An Annotation Page _MAY_ have the following properties: [label](#label), [startIndex](#startIndex), [metadata](#metadata), [summary](#summary), [provider](#provider), [thumbnail](#thumbnail), [requiredStatement](#requiredStatement), [rights](#rights), [behavior](#behavior), [seeAlso](#seeAlso), [service](#service), [homepage](#homepage), [rendering](#rendering), [canonical](#canonical), [via](#via), and [annotations](#annotations). +{: .note} #### Specific Resource -`"type": "SpecificResource"` +> `"type": "SpecificResource"` -A Specific Resource is a resource in the context of an Annotation. They are used to record further properties or relationships needed to understand the particular contextual use, such as which part of the resource is used or how it should be rendered. In IIIF, the Specific Resource model from the Web Annotation Data Model has some additional properties beyond those defined by the W3C, such as `transform`. +A Specific Resource is a resource in the context of an Annotation. They are used to record further properties or relationships needed to understand the particular contextual use, such as which part of the resource is used or how it should be rendered. In IIIF, the Specific Resource model from the Web Annotation Data Model has some additional properties beyond those defined by the W3C, such as `transform` and `position`. + +A Specific Resource _MUST_ have an HTTP(S) URI given in `id`. This allows for it to be addressed by other parts of the model, such as Content State Annotations. + +__Properties__
+A Specific Resource _MUST_ have the following properties: [id](#id), [type](#type), [source](#source)

+A Specific Resource _SHOULD_ have the following properties: [selector](#selector)

+A Specific Resource _MAY_ have the following properties: [position](#position), [transform](#transform), [scope](#scope), [styleClass](#styleClass), [height](#height), [width](#width), [duration](#duration), [language](#language), [label](#label), [metadata](#metadata), [summary](#summary), [provider](#provider), [thumbnail](#thumbnail), [requiredStatement](#requiredStatement), [rights](#rights), [behavior](#behavior), [seeAlso](#seeAlso), [service](#service), [homepage](#homepage), [rendering](#rendering), [canonical](#canonical), [via](#via), and [annotations](#annotations).

+{: .note} #### Textual Body -`"type": "TextualBody"` +> `"type": "TextualBody"` A Textual Body is an embedded resource within an Annotation that carries, as the name suggests, a text as the body of the Annotation. It is defined by the Web Annotation Data Model, and this specification defines a new property for `position` that allows it to be positioned within a Container. +A Textual Body _MUST_ have an HTTP(S) URI given in `id`. This allows for it to be addressed by other parts of the model, such as Content State Annotations. + +__Properties__
+A Textual Body _MUST_ have the following properties: [id](#id), [type](#type), [value](#value)

+A Specific Resource _MAY_ have the following properties: [position](#position), [transform](#transform), [scope](#scope), [styleClass](#styleClass), [height](#height), [width](#width), [duration](#duration), [language](#language), [format](#format), [label](#label), [metadata](#metadata), [summary](#summary), [provider](#provider), [thumbnail](#thumbnail), [requiredStatement](#requiredStatement), [rights](#rights), [behavior](#behavior), [seeAlso](#seeAlso), [service](#service), [homepage](#homepage), [rendering](#rendering), [canonical](#canonical), [via](#via), and [annotations](#annotations).

+{: .note} + + #### Choice -`"type": "Choice"` +> `"type": "Choice"` + +A Choice is a Web Annotation construction that allows one entry from a list to be selected for processing or display. This specification allows `behavior` and other properties to be added to a Choice to influence how it is processed. -A Choice is a Web Annotation construction that allows one entry from a list to be selected for processing or display. This specification allows `behavior` to be added to a Choice to influence how it is processed. +A Choice _MUST_ have an HTTP(S) URI given in `id`. It _SHOULD_ have a `label` in order to present the choice to the user, along with its items. This allows for it to be addressed by other parts of the model, such as Content State Annotations. + +__Properties__
+A Choice _MUST_ have the following properties: [id](#id), [type](#type), [items](#items)

+A Choice _SHOULD_ have the following properties: [label](#label)

+A Choice _MAY_ have the following properties: [metadata](#metadata), [summary](#summary), [provider](#provider), [thumbnail](#thumbnail), [requiredStatement](#requiredStatement), [behavior](#behavior), and [seeAlso](#seeAlso).

+{: .note} ### Content Resources @@ -378,12 +416,6 @@ If there is a need to distinguish between content resources, then the resource _ Containers _MAY_ be treated as content resources for the purposes of annotating on to other Containers. In this situation, the Container _MAY_ be [embedded][prezi30-terminology] within the Annotation, be a reference within the same Manifest, or require dereferencing to obtain its description. -### Audio Content - - - - - ### Selectors The Web Annotation Data Model defines several Selectors, which describe how to find a specific segment of that resource to be used. As noted, the nature of Selectors are dependent on the type of resources that they select out of, and the methods needed for those descriptions will vary. The Selectors from the Web Annotation Data Model and other sources can be used within the IIIF Data Model. This specification defines additional Selector classes for use. @@ -822,6 +854,10 @@ TODO: Address https://github.com/IIIF/api/issues/2318 { "behavior": [ "auto-advance", "individuals" ] } ``` +### canonical +{: #canonical} + + ### color {: #color} @@ -1670,10 +1706,8 @@ The value _MUST_ be an array of JSON objects. Each object _MUST_ be a service re ### source {: #source} -A Content Resource that is used as the souce of audio information in an Audio resource. The value _MUST_ be a Content Resource with the `id`, `type` properties. -* Audio resources _MUST_ have the `source` property.
- Clients _SHOULD_ process the `source` property on an Audio resource. + ### start {: #start} @@ -1742,6 +1776,14 @@ The value _MUST_ be an array of JSON objects. Each item _MUST_ have the `id` and ] } ``` + +### styleClass +{: #styleClass} + +### stylesheet +{: #stylesheet} + + ### summary {: #summary} @@ -1905,8 +1947,7 @@ FIXME: possible values are 'm' and 's' and 'relative'. Is relative always 0-1.0 ### value - -metadata: +within metadata: {label: value: {"en": ["foo"]}} @@ -1922,9 +1963,15 @@ The value _MUST_ be a floating point number. FIXME: use scoped context for UnitValue to change the meaning of `value` -### value (WktSelector) +### value (WktSelector, TextualBody) + +FIXME: string value! + + +### via + + -FIXME: another value value! ### viewingDirection {: #viewingDirection} @@ -2067,6 +2114,14 @@ There are some common terms used in more than one JSON-LD context document. Ever There is one property that is in direct conflict - the `label` property is defined by both and is available for every resource. The use of `label` in IIIF follows modern best practices for internationalization by allowing the language to be associated with the value using the language map construction [described above][prezi30-languages], also allowing multiple languages to be used. The Web Annotation Data Model uses it only for [Annotation Collections][prezi30-annocoll], and mandates the format is a string. For this property, the API overrides the definition from the Annotation model to ensure that labels can consistently be represented in multiple languages. +__Incompatibility Warning__
+The definition of `label` in the Web Annotation specification does not produce JSON conformant with the structure defined in this specification for languages. Given the absolute requirement for internationalized labels and the strong desire for consistently handling properties, the `label` property on Annotation model classes does not conform to the string requirement of the Web Annotation Data Model. This [issue has been filed with the W3C][github-webanno-437] and will hopefully be addressed in a future version of the standard. +{: .warning} + + +### FIXME: value, value, and value + + The following properties are defined by both, and the IIIF representation is more specific than the Web Annotation Data Model but are not in conflict, or are never used on the same resource: * `homepage`: In IIIF the home page of a resource is represented as a JSON object, whereas in the Web Annotation Data Model it can also be a string. From 54737e3020065557db96cb14841522bea9705909 Mon Sep 17 00:00:00 2001 From: Rob Sanderson Date: Fri, 4 Apr 2025 21:02:17 -0400 Subject: [PATCH 066/130] more class updates --- source/presentation/4.0/model.md | 91 +++++++++++++++++++++++--------- 1 file changed, 67 insertions(+), 24 deletions(-) diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index 3fd81106d..9f9f02585 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -403,33 +403,40 @@ A Choice _MAY_ have the following properties: [metadata](#metadata), [summary](# ### Content Resources -Content resources are resources on the Web such as images, audio, video, or text which can be associated with a Container via an Annotation, or provide a representation of any resource. +Content Resources are resources on the Web such as images, audio, video, 3d models, or text which can be associated with a Container via an Annotation, or be used with `thumbnail`, `rendering` or similar properties. -Content resources _MUST_ have an `id` property, with the value being the URI at which the resource can be obtained. +Content Resources _MUST_ have an HTTP(s) given in `id`. It _MUST_ be able to be dereferenced to retrieve the representation of the Content Resource. -The type of the content resource _MUST_ be included, and _SHOULD_ be taken from the table listed under the definition of `type`. The `format` of the resource _SHOULD_ be included and, if so, _SHOULD_ be the media type that is returned when the resource is dereferenced. The `profile` of the resource, if it has one, _SHOULD_ also be included. +If the Content Resource is an Image, and a IIIF Image service is available for it, then the `id` property of the Content Resource _MAY_ be a complete URI to any particular representation supported by the Image Service, such as `https://example.org/image1/full/1000,/0/default.jpg`, but _MUST NOT_ be just the URI of the Image Service. The Image _SHOULD_ have the service referenced from it using the `service` property. -If the content resource is an Image, and a IIIF Image service is available for it, then the `id` property of the content resource _MAY_ be a complete URI to any particular representation supported by the Image Service, such as `https://example.org/image1/full/1000,/0/default.jpg`, but _MUST NOT_ be just the URI of the IIIF Image service. Its `type` value _MUST_ be the string `Image`. Its media type _MAY_ be listed in `format`, and its height and width _MAY_ be given as integer values for `height` and `width` respectively. The Image _SHOULD_ have the service [referenced][prezi30-terminology] from it using the `service` property. - -If there is a need to distinguish between content resources, then the resource _SHOULD_ have the `label` property. +If there is a need to distinguish between Content Resources, then the resource _SHOULD_ have the `label` property. Containers _MAY_ be treated as content resources for the purposes of annotating on to other Containers. In this situation, the Container _MAY_ be [embedded][prezi30-terminology] within the Annotation, be a reference within the same Manifest, or require dereferencing to obtain its description. +__Properties__
+A Content Resource _MUST_ have the following properties: [id](#id), and [type](#type)

+A Content Resource _SHOULD_ have the following properties: [label](#label)

+A Content Resource _MAY_ have the following properties: [height](#height), [width](#width), [duration](#duration), [language](#language), [format](#format), [metadata](#metadata), [summary](#summary), [provider](#provider), [thumbnail](#thumbnail), [requiredStatement](#requiredStatement), [rights](#rights), [behavior](#behavior), [profile](#profile), [seeAlso](#seeAlso), [service](#service), [homepage](#homepage), [rendering](#rendering), [canonical](#canonical), [via](#via), and [annotations](#annotations).

+{: .note} + ### Selectors The Web Annotation Data Model defines several Selectors, which describe how to find a specific segment of that resource to be used. As noted, the nature of Selectors are dependent on the type of resources that they select out of, and the methods needed for those descriptions will vary. The Selectors from the Web Annotation Data Model and other sources can be used within the IIIF Data Model. This specification defines additional Selector classes for use. -#### Point Selector -`"type": "PointSelector"` +#### Point Selector -There are common use cases in which a point, rather than a range or area, is the target of the Annotation. For example, putting a pin in a map should result in an exact point, not a very small rectangle. Points in time are not very short durations, and user interfaces should also treat these differently. This is particularly important when zooming in (either spatially or temporally) beyond the scale of the frame of reference. +> `"type": "PointSelector"` +There are common use cases in which a point, rather than a range or area, is the target of the Annotation. For example, putting a pin in a map should result in an exact point, not a very small rectangle. Points in time are not very short durations, and user interfaces should, equally, treat these differently. This is particularly important when zooming in (either spatially or temporally) beyond the scale of the frame of reference. -* FIXME: either supply instant, or all applicable dimensions for the source - list properties here like manifest +If `instant` is not supplied, and the target resource has a `duration`, the selector is interpreted as targeting the entire duration. If `instant` is supplied, but no spatial point, the selector is interpreted as targeting the entire spatial aspect of the resource. +__Properties__
+A Point Selector _MUST_ have the following properties: [id](#id), and [type](#type)

+A Point Selector _MAY_ have the following properties: [x](#x), [y](#y), [z](#z), and [instant](#instant).

+{: .note} ```json { @@ -445,11 +452,15 @@ There are common use cases in which a point, rather than a range or area, is the #### WKT Selector -`"type": "WktSelector"` +> `"type": "WktSelector"` Well-known text, or WKT, is an ISO standard method for describing 2 and 3 dimensional geometries. This selector thus goes beyond what the Web Annotation's SvgSelector enables by incorporating the z axis, as well as additional types of selection such as MultiPolygon. Additional types, such as CIRCULARSTRING may also be supported. -WKT Selectors _MUST_ have a `value` property, which is the WKT string that defines the geometry to be selected. +The text representation is given in the `value` property of the selector. + +__Properties__
+A WKT Selector _MUST_ have the following properties: [id](#id), [type](#type), and [value](#value). +{: .note} ```json { @@ -459,15 +470,15 @@ WKT Selectors _MUST_ have a `value` property, which is the WKT string that defin } ``` - - - #### Audio Content Selector -`"type": "AudioContentSelector"` +> `"type": "AudioContentSelector"` Video content resources consist of both visual and audio content within the same bit-level representation. There are situations when it is useful to refer to only one aspect of the content – either the visual or the audio, but not both. For example, an Annotation might associate only the visual content of a video that has spoken English in the audio, and an audio file that has the translation of that content in Spanish. The Audio Content Selector selects all of the audio content from an A/V content resource, and may be further refined with subsequent selectors to select a segment of it. +__Properties__
+An Audio Content Selector _MUST_ have the following properties: [id](#id), and [type](#type). +{: .note} ```json { @@ -479,7 +490,7 @@ Video content resources consist of both visual and audio content within the same #### Visual Content Selector -`"type": "VisualContentSelector"` +> `"type": "VisualContentSelector"` Similar to Audio Content Selectors, Visual Content Selectors select the visual aspects of the content of an A/V content resource. They may be further refined by subsequent selectors that select an area or temporal segment of it. @@ -490,14 +501,20 @@ Similar to Audio Content Selectors, Visual Content Selectors select the visual a } ``` +__Properties__
+A Visual Content Selector _MUST_ have the following properties: [id](#id), and [type](#type). +{: .note} + #### Animation Selector -`"type": "AnimationSelector"` +> `"type": "AnimationSelector"` -More interactive content resources, such as 3D models, may have animations or similar features that can be _activated_ by user interaction. For example, a model of a box might have an animation that opens the lid and a second animation that closes the lid. In order to activate those animations, they need to be selectable, and thus the specification defines an Animation Selector. +More interactive content resources, such as 3D models, may have animations or similar features that can be _activated_ by user interaction. For example, a model of a box might have an animation that opens the lid and a second animation that closes the lid. In order to activate those animations, they need to be selectable, and thus the specification defines an Animation Selector. The identity of the activatable aspect is given in the `value` property. -Animation Selectors _MUST_ have a `value` property, which is the identity of the animation in whichever form is used by the source resource. +__Properties__
+An Animation Selector _MUST_ have the following properties: [id](#id), [type](#type), and [value](#value). +{: .note} ```json { @@ -509,16 +526,38 @@ Animation Selectors _MUST_ have a `value` property, which is the identity of the #### IIIF Image API Selector -`"type": "ImageApiSelector"` +> `"type": "ImageApiSelector"` -FIXME: write this +The Image API Selector is used to describe the operations available via the Image API in order to retrieve a particular image representation. In this case the resource is the abstract image as identified by the [IIIF Image API][image-api] base URI plus identifier, and the retrieval process involves adding the correct parameters after that base URI. +The Image API Selector has properties following the parameters from the API, and record the values needed to fill out the URL structure in the request. If the property is not given, then a default should be used. +| Property | Default | Description | +| -------- | --------- | ----------------------------------------------------- | +| region | "full" | The string to put in the region parameter of the URI. | +| size | "max" | The string to put in the size parameter of the URI. If used with a version 2.0 Image API server, the default should be considered to be "full". | +| rotation | "0" | The string to put in the rotation parameter of the URI. Note that this must be a string in order to allow mirroring, for example "!90". | +| quality | "default" | The string to put in the quality parameter of the URI. | +| format | "jpg" | The string to put in the format parameter of the URI. Note that the '.' character is not part of the format, just the URI syntax. | +{: .api-table} +__Properties__
+A IIIF Image API Selector _MUST_ have the following properties: [id](#id), [type](#type).

+A IIIF Image API Selector _MAY_ have the following properties: [region](#region), [size](#size), [rotation](#rotation), [quality](#quality), [format](#format). +{: .note} + +```json +{ + "id": "https://example.org/selectors/6", + "type": "ImageApiSelector", + "region": "0,0,256,256", + "rotation": "90" +} +``` ### Range -`"type": "Range"` +> `"type": "Range"` Ranges are used to represent structure within a Manifest beyond the default order of the Containers in the `items` property. @@ -698,6 +737,10 @@ A UnitValue expresses a quantity through a numerical value and associated unit o `"type": "UnitValue"` + + + + ## Properties From 4d212f9d0a6b9244a370470068b1ad2959790aff Mon Sep 17 00:00:00 2001 From: Rob Sanderson Date: Fri, 4 Apr 2025 21:47:04 -0400 Subject: [PATCH 067/130] more class updates --- source/presentation/4.0/model.md | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index 9f9f02585..88f394b3a 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -561,18 +561,28 @@ A IIIF Image API Selector _MAY_ have the following properties: [region](#region) Ranges are used to represent structure within a Manifest beyond the default order of the Containers in the `items` property. -Ranges _MUST_ have URIs and they _SHOULD_ be HTTP(S) URIs. Top level Ranges are [embedded][prezi30-terminology] or externally [referenced][prezi30-terminology] within the Manifest in a `structures` property. These top level Ranges then embed or reference other Ranges, Containers or parts of Containers in the `items` property. Each entry in the `items` property _MUST_ be a JSON object, and it _MUST_ have the `id` and `type` properties. If a top level Range needs to be dereferenced by the client, then it _MUST NOT_ have the `items` property, such that clients are able to recognize that it should be retrieved in order to be processed. +Ranges _MUST_ have an HTTP(s) given in `id`. Top level Ranges are embedded or externally referenced within the Manifest in a `structures` property. These top level Ranges then embed or reference other Ranges, Containers or parts of Containers in the `items` property. Each entry in the `items` property _MUST_ be a JSON object, and it _MUST_ have the `id` and `type` properties. If a top level Range needs to be dereferenced by the client, then it _MUST NOT_ have the `items` property, such that clients are able to recognize that it should be retrieved. The included Containers and parts of Containers need not be contiguous or in the same order as in the Manifest's `items` property or any other Range. Examples include newspaper articles that are continued in different sections, a chapter that starts half way through a page, or time segments of a single canvas that represent different sections of a piece of music. -Ranges _MAY_ link to an Annotation Collection that has the content of the Range using the `supplementary` property. The [referenced][prezi30-terminology] Annotation Collection will contain Annotations that target the Containers within the Range and link content resources to those Containers. +Ranges _MAY_ link to an Annotation Collection that has the content of the Range using the `supplementary` property. The referenced Annotation Collection will contain Annotations that target the Containers within the Range and link content resources to those Containers. + +__Properties__
+A Range _MUST_ have the following properties: [id](#id), and [type](#type).

+A Range _SHOULD_ have the following properties: . +A Range _MAY_ have the following properties: . +{: .note} + ### Scene Components +The following classes are only usable within Scenes. + + #### Cameras -A Camera provides a view of a region of the Scene's space from a particular position within the Scene; the client constructs a viewport into the Scene and uses the view of one or more Cameras to render that region. The size and aspect ratio of the viewport is client and device dependent. +A Camera provides a view of a region of a Scene's space from a particular position within the Scene; the client constructs a viewport into the Scene and uses the Camera to render that region. The size and aspect ratio of the viewport is client and device dependent. FIXME: If either the position or direction is not specified, then the position defaults to the origin, and facing direction defaults to pointing along the z axis towards negative infinity. From a967c3ebec9bbc5908bede9702c31e4106af1779 Mon Sep 17 00:00:00 2001 From: Glen Robson Date: Wed, 16 Apr 2025 17:40:47 +0100 Subject: [PATCH 068/130] Temporarily disabling internal link checking --- .github/workflows/preview.yml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/workflows/preview.yml b/.github/workflows/preview.yml index 90595a6d3..740c20086 100644 --- a/.github/workflows/preview.yml +++ b/.github/workflows/preview.yml @@ -32,10 +32,10 @@ jobs: # A workflow run is made up of one or more jobs that can run sequentially run: bundle exec rake build:preview - name: Test html run: bundle exec rake test:html - - name: Test internal links - run: bundle exec rake test:links:internal - - name: Test *iiif.io* links - run: bundle exec rake test:links:iiif +# - name: Test internal links +# run: bundle exec rake test:links:internal +# - name: Test *iiif.io* links +# run: bundle exec rake test:links:iiif - name: Spec tests run: bundle exec rake api:spec - name: Create GitHub deployment # Deploy to Preview site From 661a867311dba7082ca8653f81f51264f5d22cc3 Mon Sep 17 00:00:00 2001 From: Julie Winchester Date: Wed, 23 Apr 2025 11:34:13 -0500 Subject: [PATCH 069/130] Add interactionMode description to model --- source/presentation/4.0/model.md | 32 ++++++++++++++++++++++++-------- 1 file changed, 24 insertions(+), 8 deletions(-) diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index 88f394b3a..19086da77 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -1113,18 +1113,34 @@ The `value` property of the UnitValue _MUST_ be between 0.0 and 1.0. ### interactionMode {: #interactionMode} -*within* the Scene, whereas viewingDirection and behavior are across containers. +A set of features that guide or limit user interaction with Cameras viewing 3D content within a Scene that the publisher of the content would prefer the client to use when presenting the resource. This specification defines the values in the table below. Others may be defined externally as an [extension][prezi30-ldce]. The client _SHOULD_ use `interactionMode` to determine the user experience features and approaches whereby users are permitted to change or adjust Camera perspectives when viewing content within a Scene (e.g., orbiting around the scene or locking the user to a first-person perspective). -* Containers _MAY_ have the `interactionMode` +When more than one interaction mode is present, the client _SHOULD_ pick the first interaction mode that the client is capable of supporting. -Table here with values +For interaction modes that involve a Camera orbiting around a target point, the target point _SHOULD_ be the same as the Camera's `lookAt` property. +The value _MUST_ be an array of strings. + +* A Container (scene?) _MAY_ have the `interactionMode` property.
+ Clients _SHOULD_ process `interactionMode` on a Container. +* Other types of resource _MUST NOT_ have the `interactionMode` property.
+ Clients _SHOULD_ ignore `interactionMode` on other types of resource. + +| Value | Description | +| ----- | ----------- | +| `locked` | Camera is locked. User interaction _MUST NOT_ modify Camera. | +| `orbit` | Camera orbits around a target point in response to user interaction. A client _MAY_ allow user interacton to truck, dolly, or zoom Camera. | +| `hemisphere-orbit` | Camera orbits around a target point in response to user interaction, but orbital freedom is limited to a hemisphere. A client _MAY_ allow Camera truck, dolly, or zoom. | +| `free` | Camera mimics a first-person perspective. User interaction pans or tilts Camera perspective, trucks Camera position, and/or dollies or zooms Camera. | +| `free-direction` | Camera mimics a first-person perspective, but Camera position is fixed. User interaction pans or tilts Camera perspective. | +{: .api-table #table-interaction} -locked -orbit -hemisphere-orbit -free -free-direction +?: Allow dolly/zoom in `locked` or `free-direction`? + +{% include api/code_header.html %} +``` json-doc +{ "interactionMode": [ "hemisphere-orbit", "orbit" ] } +``` other examples: no-zoom, no-scrub, rti-mode ### items From af55f9d1032a5b34f4160a11422dd8500fca041e Mon Sep 17 00:00:00 2001 From: Julie Winchester Date: Wed, 23 Apr 2025 13:28:16 -0500 Subject: [PATCH 070/130] Update interactionMode language --- source/presentation/4.0/model.md | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index 19086da77..c5eae9a54 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -1113,7 +1113,7 @@ The `value` property of the UnitValue _MUST_ be between 0.0 and 1.0. ### interactionMode {: #interactionMode} -A set of features that guide or limit user interaction with Cameras viewing 3D content within a Scene that the publisher of the content would prefer the client to use when presenting the resource. This specification defines the values in the table below. Others may be defined externally as an [extension][prezi30-ldce]. The client _SHOULD_ use `interactionMode` to determine the user experience features and approaches whereby users are permitted to change or adjust Camera perspectives when viewing content within a Scene (e.g., orbiting around the scene or locking the user to a first-person perspective). +A set of features that guide or limit user interaction with content within a Container that the publisher of the content would prefer the client to use when presenting the resource. This specification defines values in the table below that guide interactions with Cameras within a Scene. Other values for other Container types or specifying other interaction modes for 3D content may be defined externally as an [extension][prezi30-ldce]. For interaction modes pertaining to Cameras within a Scene, the client _SHOULD_ use `interactionMode` to determine the user experience features and approaches whereby users are permitted to change or adjust Cameras when viewing content within a Scene (e.g., orbiting around the scene or locking the user to a first-person perspective). When more than one interaction mode is present, the client _SHOULD_ pick the first interaction mode that the client is capable of supporting. @@ -1121,7 +1121,7 @@ For interaction modes that involve a Camera orbiting around a target point, the The value _MUST_ be an array of strings. -* A Container (scene?) _MAY_ have the `interactionMode` property.
+* A Container _MAY_ have the `interactionMode` property.
Clients _SHOULD_ process `interactionMode` on a Container. * Other types of resource _MUST NOT_ have the `interactionMode` property.
Clients _SHOULD_ ignore `interactionMode` on other types of resource. @@ -1129,20 +1129,16 @@ The value _MUST_ be an array of strings. | Value | Description | | ----- | ----------- | | `locked` | Camera is locked. User interaction _MUST NOT_ modify Camera. | -| `orbit` | Camera orbits around a target point in response to user interaction. A client _MAY_ allow user interacton to truck, dolly, or zoom Camera. | -| `hemisphere-orbit` | Camera orbits around a target point in response to user interaction, but orbital freedom is limited to a hemisphere. A client _MAY_ allow Camera truck, dolly, or zoom. | +| `orbit` | Camera orbits around a target point in response to user interaction. | +| `hemisphere-orbit` | Camera orbits around a target point in response to user interaction, but orbital freedom is limited to a hemisphere. | | `free` | Camera mimics a first-person perspective. User interaction pans or tilts Camera perspective, trucks Camera position, and/or dollies or zooms Camera. | | `free-direction` | Camera mimics a first-person perspective, but Camera position is fixed. User interaction pans or tilts Camera perspective. | {: .api-table #table-interaction} -?: Allow dolly/zoom in `locked` or `free-direction`? - {% include api/code_header.html %} ``` json-doc { "interactionMode": [ "hemisphere-orbit", "orbit" ] } ``` - -other examples: no-zoom, no-scrub, rti-mode ### items {: #items} From 70c3e740e9897948134abff68f238804d6fddcf3 Mon Sep 17 00:00:00 2001 From: Rob Sanderson Date: Fri, 25 Apr 2025 16:19:20 -0400 Subject: [PATCH 071/130] update --- source/presentation/4.0/model.md | 48 ++++++++++++++++++++------------ 1 file changed, 30 insertions(+), 18 deletions(-) diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index c5eae9a54..477ec2266 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -102,7 +102,7 @@ Any of the properties in the API that can have multiple values _MUST_ always be Language _SHOULD_ be associated with strings that are intended to be displayed to the user for the `label` and `summary` properties, plus the `label` and `value` properties of the `metadata` and `requiredStatement` objects. -The values of these properties _MUST_ be JSON objects, with the keys being the [BCP 47][org-bcp-47] language code for the language, or if the language is either not known or the string does not have a language, then the key _MUST_ be the string `none`. The script _SHOULD NOT_ be included in the tag, even though BCP 47 allows for this possibility. The associated values _MUST_ be arrays of strings, where each item is the content in the given language. +The values of these properties _MUST_ be JSON objects, with the keys being the [BCP 47][org-bcp-47] language code for the language, or if the language is either not known or the string does not have a language, then the key _MUST_ be the string `none`. The locale, script and other subtags _MAY_ be included. Clients _SHOULD_ process subtags when comparing the values with the user's provided preferences, however _MAY_ simply reduce all tags down to just the language, discarding everything after the first hyphen, and display all matching values. The associated values _MUST_ be arrays of strings, where each item is the content in the given language. {% include api/code_header.html %} ``` json-doc @@ -454,7 +454,7 @@ A Point Selector _MAY_ have the following properties: [x](#x), [y](#y), [z](#z), > `"type": "WktSelector"` -Well-known text, or WKT, is an ISO standard method for describing 2 and 3 dimensional geometries. This selector thus goes beyond what the Web Annotation's SvgSelector enables by incorporating the z axis, as well as additional types of selection such as MultiPolygon. Additional types, such as CIRCULARSTRING may also be supported. +Well-known text, or WKT, is an ISO standard method for describing 2 and 3 dimensional geometries. This selector thus goes beyond what the Web Annotation's SvgSelector enables by incorporating the z axis, as well as additional types of selection such as MULTIPOLYGON. Additional types, such as CIRCULARSTRING may also be supported. The text representation is given in the `value` property of the selector. @@ -528,7 +528,7 @@ An Animation Selector _MUST_ have the following properties: [id](#id), [type](#t > `"type": "ImageApiSelector"` -The Image API Selector is used to describe the operations available via the Image API in order to retrieve a particular image representation. In this case the resource is the abstract image as identified by the [IIIF Image API][image-api] base URI plus identifier, and the retrieval process involves adding the correct parameters after that base URI. +The Image API Selector is used to describe the operations available via the IIIF Image API in order to retrieve a particular image representation. In this case the resource is the abstract image as identified by the [IIIF Image API][image-api] base URI plus identifier, and the retrieval process involves adding the correct parameters after that base URI. The Image API Selector has properties following the parameters from the API, and record the values needed to fill out the URL structure in the request. If the property is not given, then a default should be used. @@ -565,42 +565,47 @@ Ranges _MUST_ have an HTTP(s) given in `id`. Top level Ranges are embedded or ex The included Containers and parts of Containers need not be contiguous or in the same order as in the Manifest's `items` property or any other Range. Examples include newspaper articles that are continued in different sections, a chapter that starts half way through a page, or time segments of a single canvas that represent different sections of a piece of music. -Ranges _MAY_ link to an Annotation Collection that has the content of the Range using the `supplementary` property. The referenced Annotation Collection will contain Annotations that target the Containers within the Range and link content resources to those Containers. - __Properties__
A Range _MUST_ have the following properties: [id](#id), and [type](#type).

-A Range _SHOULD_ have the following properties: . -A Range _MAY_ have the following properties: . +A Range _SHOULD_ have the following properties: [label](#label), and [items](#items)

. +A Range _MAY_ have the following properties: [start](#start), [supplementary](#supplementary), [metadata](#metadata), [summary](#summary), [provider](#provider), [thumbnail](#thumbnail), [requiredStatement](#requiredStatement), [rights](#rights), [navDate](#navDate), [navPlace](#navPlace), [placeholderContainer](#placeholderContainer), [accompanyingContainer](#accompanyingContainer), [viewingDirection](#viewingDirection), [behavior](#behavior), [seeAlso](#seeAlso), [service](#service), [homepage](#homepage), [rendering](#rendering), [partOf](#partOf), [canonical](#canonical), [via](#via), and [annotations](#annotations). {: .note} - ### Scene Components The following classes are only usable within Scenes. - #### Cameras A Camera provides a view of a region of a Scene's space from a particular position within the Scene; the client constructs a viewport into the Scene and uses the Camera to render that region. The size and aspect ratio of the viewport is client and device dependent. -FIXME: If either the position or direction is not specified, then the position defaults to the origin, and facing direction defaults to pointing along the z axis towards negative infinity. +If either the position or direction is not specified, then the position defaults to the origin of the Scene, and the direction defaults to pointing along the z axis towards negative infinity. -The region of the Scene's space that is observable by the camera is bounded by two planes orthogonal to the direction the camera is facing, given in the `near` and `far` properties, (PERSPECTIVE) and a vertical projection angle that provides the top and bottom planes of the region. (viewHeight?) +__Properties__
+All Cameras _MUST_ have the following properties: [id](#id), and [type](#type).

+All Cameras _MAY_ have the following properties: [label](#label), [lookAt](#lookAt), [near](#near), and [far](#far) +{: .note} ##### Orthographic Camera -`"type": "OrthographicCamera"` +> `"type": "OrthographicCamera"` + +An Orthographic Camera removes visual perspective, resulting in object size remaining constant regardless of its distance from the camera. -`OrthographicCamera` removes visual perspective, resulting in object size remaining constant regardless of its distance from the camera +__Properties__
+Orthographic Cameras _SHOULD_ have the following additional properties: [viewHeight](#viewHeight). +{: .note} ##### Perspective Camera -`"type": "PerspectiveCamera"` +> `"type": "PerspectiveCamera"` -`PerspectiveCamera` mimics the way the human eye sees, in that objects further from the camera are smaller +`PerspectiveCamera` mimics the way the human eye sees, in that objects further from the camera are smaller. + +The region of the Scene's space that is observable by the camera is bounded by two planes orthogonal to the direction the camera is facing, given in the `near` and `far` properties, and a vertical projection angle that provides the top and bottom planes of the region in the `fieldOfView` property. Properties... @@ -662,7 +667,10 @@ The Spot Light emits in the negative Y (-y) direction by default, but the orient #### Audio in Scenes Positional audio is supported through the use of Audio resources annotated into Scenes. -Audio resources _MUST_ have a `source` property that references an audio Content Resource, and _SHOULD_ have a `volume` property. +Audio resources _MUST_ have a `source` property that references an audio Content Resource, and _SHOULD_ have a `volume` property. Positional Audio classes are subclasses of SpecificResource. + +Volume is relative to the input audio source's volume. + ##### Ambient Audio @@ -684,6 +692,9 @@ Spot Audio emits a cone of sound from a single point in a given direction. The The Spot Audio emits in the negative Y (-y) direction by default, but the orientation of the sound can be altered by subsequent transforms. +Can have a Timeline as the source of the audio? + + ```json { "id": "https://example.org/iiif/spotAudio/1", @@ -697,8 +708,9 @@ The Spot Audio emits in the negative Y (-y) direction by default, but the orient "volume": { "type": "UnitValue", "unit": "relative", - "value": 2.0 - } + "value": 1.0 + }, + "transform": [] } ``` From ee74f6a92e1d3ea6cf15088b30c9425127097bc5 Mon Sep 17 00:00:00 2001 From: Rob Sanderson Date: Fri, 25 Apr 2025 16:55:53 -0400 Subject: [PATCH 072/130] minor updates --- source/presentation/4.0/model.md | 99 ++++++++++++++++++++++++++------ 1 file changed, 82 insertions(+), 17 deletions(-) diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index 477ec2266..7c953dc18 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -598,6 +598,16 @@ __Properties__
Orthographic Cameras _SHOULD_ have the following additional properties: [viewHeight](#viewHeight). {: .note} +```json +{ + "id": "https://example.org/iiif/camera/1", + "type": "OrthographicCamera", + "near": 1.0, + "far": 100.0, + "viewHeight": 40.0 +} +``` + ##### Perspective Camera @@ -607,12 +617,14 @@ Orthographic Cameras _SHOULD_ have the following additional properties: [viewHei The region of the Scene's space that is observable by the camera is bounded by two planes orthogonal to the direction the camera is facing, given in the `near` and `far` properties, and a vertical projection angle that provides the top and bottom planes of the region in the `fieldOfView` property. -Properties... +__Properties__
+Perspective Cameras _SHOULD_ have the following additional properties: [fieldOfView](#fieldOfView). +{: .note} ```json { - "id": "https://example.org/iiif/camera/1", + "id": "https://example.org/iiif/camera/2", "type": "PerspectiveCamera", "near": 1.0, "far": 100.0, @@ -621,42 +633,95 @@ Properties... ``` #### Lights + +It is necessary for there to be a Light within a Scene that illuminates the objects. If no Light is provided by the Scene's description, then the client _MUST_ add a Light. + +This specification does not define other aspects of Lights, such as the rate of decay of the intensity of the light over a distance, the maximum range of the light, or the penumbra of a cone. Implementation of these aspects is client-dependent. + +The specification defines four types of Light, below. + +__Properties__
+All Lights _MUST_ have the following properties: [id](#id), and [type](#type).

+All Lights _SHOULD_ have the following properties: [color](#color), and [intensity](#intensity).

+All Lights _MAY_ have the following properties: [label](#label). +{: .note} + ##### Ambient Light -`"type": "AmbientLight"` +> `"type": "AmbientLight"` -Ambient Light evenly illuminates all objects in the Scene, and does not have a direction or position. +Ambient Light evenly illuminates all objects in the Scene, and does not have a direction or position. It does not have any new properties. The Light itself _MUST_ be added into the scene at a specific position, however this is only such that editing interfaces can render the object to the user. + +```json +{ + "id": "https://example.org/iiif/light/1", + "type": "AmbientLight", + "color": "#F0A0F0", +} +``` ##### Directional Light -`"type": "DirectionalLight"` +> `"type": "DirectionalLight"` + +Directional Lights emit their light in a specific direction as if infinitely far away, and as such the light does not come from a specific position. The rays produced are all parallel. The Light itself _MUST_ be added into the scene at a specific position, however this is only such that editing interfaces can render the object to the user. -Directional Light emits in a specific direction as if it is infinitely far away and the rays produced from it are all parallel. It does not have a specific position. +The light is emitted in the negative Y (-y) direction by default, thus straight down, but the orientation of the light can be altered with `lookAt` or with a `RotationTransform`. -The light is emitted in the negative Y (-y) direction by default, but the orientation of the light can be altered by subsequent transforms. +__Properties__
+Directional Lights _MAY_ have the following additional properties: [lookAt](#lookAt) +{: .note} + +```json +{ + "id": "https://example.org/iiif/light/2", + "type": "DirectionalLight", + "color": "#A0A0F0", + "lookAt": {"id": "https://example.org/iiif/annotations/models/1"} +} +``` ##### Point Light -`"type": "PointLight"` +> `"type": "PointLight"` + +Point Lights emit from a single point within the Scene in all directions. + +```json +{ + "id": "https://example.org/iiif/light/3", + "type": "PointLight", + "color": "#A0F0F0" +} +``` -Point Light emits from a single point within the Scene in all directions. ##### Spot Light -`"type": "SpotLight"` +> `"type": "SpotLight"` Spot Light emits a cone of light from a single point in a given direction. The Spot Light's `angle` property defines the radius of the cone. The Spot Light emits in the negative Y (-y) direction by default, but the orientation of the light can be altered by subsequent transforms. +diagram of cone geometry showing how the angle of the cone is defined + +__Properties__
+Spot Lights _SHOULD_ have the following additional properties: [angle](#angle)

+Spot Lights _MAY_ have the following additional properties: [lookAt](#lookAt) +{: .note} + + + ```json { - "id": "https://example.org/iiif/spotLight/1", + "id": "https://example.org/iiif/spotlight/1", "type": "SpotLight", "angle": 15.0, "color": "#FFFFFF", "intensity": { + "id": "https://example.org/iiif/spotlight/1/value", "type": "UnitValue", "unit": "relative", "value": 0.5 @@ -674,19 +739,19 @@ Volume is relative to the input audio source's volume. ##### Ambient Audio -`"type": "AmbientAudio"` +> `"type": "AmbientAudio"` Ambient Audio emits equally throughout the Scene, and does not have a position or direction. ##### Point Audio -`"type": "PointAudio"` +> `"type": "PointAudio"` Point Audio emits from a single point in the Scene in all directions. ##### Spot Audio -`"type": "SpotAudio"` +> `"type": "SpotAudio"` Spot Audio emits a cone of sound from a single point in a given direction. The Spot Audio's `angle` property defines the radius of the cone. @@ -725,20 +790,20 @@ here are the rules about transforms? ##### Rotate Transform -`"type": "RotateTransform"` +> `"type": "RotateTransform"` A RotateTransform rotates the local coordinate space around the given axis in a counter-clockwise direction around the axis itself (e.g. around a pivot point of 0 on the axis). A point that was at x=1,y=1 and was rotated 90 degrees around the x axis would be at x=1,y=0,z=1. If an axis value is not specified, then it is not changed, resulting in a default of 0.0 ##### Scale Transform -`"type": "ScaleTransform"` +> `"type": "ScaleTransform"` A ScaleTransform applies a multiplier to one or more axes in the local coordinate space. A point that was at 3.5, after applying a ScaleTransform of 2.0 would then be at 7.0. If an axis value is not specified, then it is not changed, resulting in a default of 1.0 ##### Translate Transform -`"type": "TranslateTransform"` +> `"type": "TranslateTransform"` A TranslateTransform moves all of the objects in the local coordinate space the given distance along the axis. A point that was at x=1.0, after applying a TranslateTransform of x=1.0 would be at x=2.0. If an axis value is not specified then it is not changed, resulting in a default of 0.0 From 76b78f051ce1f0cc44b50cb6a23f9aed5f40e82a Mon Sep 17 00:00:00 2001 From: tomcrane Date: Fri, 9 May 2025 16:19:01 +0100 Subject: [PATCH 073/130] temporal and spatial scale in Prez4 model --- source/presentation/4.0/model.md | 50 ++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index 7c953dc18..0279e8efc 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -1849,6 +1849,29 @@ The value _MUST_ be an array of JSON objects. Each object _MUST_ be a service re {: #source} +### spatialScale +{: #spatialScale} + +A single UnitValue that defines a real-world scale factor for the coordinate units of a Canvas or Scene. A Canvas with a `width` of 5000 and a `spatialScale` with `value` 0.00008 represents a physical space 0.4 metres wide. The value of `unit` _MUST_ always be `m`, i.e., metres. + + +{% include api/code_header.html %} +``` json-doc +{ + "type": "Scene", + + "spatialScale": { + "type": "UnitValue", + "value": 22.0, + "unit": "m" + } +} +``` + + * A Canvas _MAY_ have the `spatialScale` property.
+ Clients _SHOULD_ process `spatialScale` on a Canvas. + * A Scene _MAY_ have the `spatialScale` property.
+ Clients _SHOULD_ process `spatialScale` on a Scene. ### start @@ -1964,6 +1987,33 @@ The value _MUST_ be a JSON object, which _MUST_ have the `id` and `type` propert { "supplementary": { "id": "https://example.org/iiif/1/annos/1", "type": "AnnotationCollection" } } ``` +### temporalScale +{: #temporalScale} + +A single UnitValue that defines a multiplier or scale factor for the `duration` property of a Container, indicating that one second in "Container time" represents some other real world duration. A Canvas with a `duration` of 450 seconds and a `temporalScale` with `value` 1000 represents a real-world duration of 450,000 seconds (5.2 days), for example a time-lapse video of a growing plant. The value of `unit` _MUST_ always be `s`, i.e., seconds. + + +{% include api/code_header.html %} +``` json-doc +{ + "type": "Canvas", + + "temporalScale": { + "type": "UnitValue", + "value": 1000, + "unit": "s" + } +} +``` + + * A Timeline _MAY_ have the `temporalScale` property.
+ Clients _MAY_ process `temporalScale` on a Timeline. + * A Canvas _MAY_ have the `temporalScale` property.
+ Clients _MAY_ process `temporalScale` on a Canvas. + * A Scene _MAY_ have the `temporalScale` property.
+ Clients _MAY_ process `temporalScale` on a Scene. + + ### thumbnail {: #thumbnail} From 6eefe1fd4789620cec3710cb2c1e4ee209acaadb Mon Sep 17 00:00:00 2001 From: tomcrane Date: Fri, 9 May 2025 16:38:33 +0100 Subject: [PATCH 074/130] phys dims in index.md --- source/presentation/4.0/index.md | 38 +++++--------------------------- 1 file changed, 5 insertions(+), 33 deletions(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index 1c4f43d0d..632cea93b 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -1478,43 +1478,15 @@ See above... ## Conveying Physical Dimensions -(why is this important!?) +It is often important to know how big something is, especially when comparing objects together. The dimensions of a Canvas, or the pixel density of a photograph, are unrelated to the real-world size of the object they show. A large wall painting and a tiny miniature may both be conveyed by 20 megapixel source images on a 4000 by 3000 unit Canvas. -(move the props to vocab doc) +The `spatialScale` property of a Canvas or Scene provides a corresponding real-world scale for a unit of the Canvas or Scene coordinate system, allowing clients to provide scale information to users, for example by an on-screen virtual ruler. In a 2-up viewer, a client could scale two views to convey the true relative sizes of two objects. +The value of `spatialScale` is a `UnitValue` (ref) that always has the value "m", i.e., metres. If source size metadata is machine readable (or parse-able) in other measurement systems (e.g., feet and inches) then it should be converted to metres for use in `spatialScale`. Publishers may wish to present the original given measure (e.g., from catalogue metadata) in a `metadata` field for context. -Continental drift simulation example - -``` -{ - "type": "Scene", - - "spatialScale": { - "type": "UnitValue", - "value": 22.0, - "unit": "m" - }, - - // this would be rarely used - "temporalScale": { - "type": "UnitValue", - "value": 0.00001, - "unit": "s" - } - -} -``` - -`factor` Required A floating point ratio. -`units` Required A real-world measuring unit. Always seconds for temporalScale. Possible values for spatialScale include: "m", "ft". (is that it?) - -For a Canvas, it's the physical "size" of each cartesian integer unit. -For a Scene, it's the physical size of the unit vector. -For a timeline it's the ratio of time in the recording to time in the real world. - - -(define props in the Vocabulary doc) +The Presentation API also offers a corresponding `temporalScale` property for the `duration` dimension of a Container, when 1 second in the Container does not correspond to 1 second of real time. This is useful for speeded-up or slowed-down audio or video. +An extreme example of both physical dimension properties together is a Canvas showing an animation of continental drift over the course of Earth history, where the spatialScale could convey that each Canvas unit is several thousand metres, and each second of the Canvas `duration` is several million years. From 41a97e5c9897622ce832cb9e364d523294d1e4dd Mon Sep 17 00:00:00 2001 From: tomcrane Date: Fri, 9 May 2025 18:14:20 +0100 Subject: [PATCH 075/130] Rationalise ### headings in P4 index --- source/presentation/4.0/index.md | 91 +++++++++++++------------------- 1 file changed, 36 insertions(+), 55 deletions(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index 1c4f43d0d..3174f957f 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -191,14 +191,10 @@ comment annotation about part of the previous example's Canvas using FragmentSel ``` -## Presenting Content Resources -This section of the specification uses the use cases listed in the introduction to demonstrate the use of the IIIF Presentation API and introduce additional features. +## Image Content - -### Images - -#### Use Case 1: Artwork +### Use Case 1: Artwork This example is a Manifest with one Canvas, with an image of an artwork "painted" onto the Canvas. It demonstrates the use of the common descriptive properties `label` for the title of the artwork, `metadata` for additional information to display to the user, `summary` for a brief description of the artwork, `rights` to assert a rights statement or license from a controlled vocabulary, `homepage` to link to the artwork's specific web page, `thumbnail` to provide a small image to stand for the Manifest, and `provider` to give information about the publisher of the Manifest. @@ -213,7 +209,7 @@ label, summary, metadata, rights, provider, homepage, thumbnail Notice that the painting Annotation is a member of the `items` property of an Annotation Page. While in this case there is only one Annotation Page and one Annotation, the mechanism is needed for consistency when there are multiple Annotation Pages, and it allows for Annotation Pages in general to be separate resources on the web. -#### Example 2: Book +### Example 2: Book This example is a Manifest with multiple Canvases, each of which represents a page of a book. It demonstrates the use of the `behavior` property to indicate to a client that the object is _paged_: this helps a client generate the correct user experience. The `viewingDirection` property indicates that the book is read left-to-right. In this case, the property is redundant as `left-to-right` is the default value. The Manifest has a `rendering` property linking to a PDF representation; typically a client would offer this as a download or "view as" option. The `start` property is used to tell a client to initialize the view on a particular Canvas, useful if the digitized work contains a large amount of irrelevant front matter or blank pages. The `requiredStatement` is a message that a client MUST show to the user when presenting the Manifest. @@ -224,9 +220,9 @@ requiredStatement, behavior, viewingDirection, (no Ranges), rendering - PDF vers -### Audio and Video +## Audio and Video -#### Example: a 45 single with one Timeline per song/side +### Example: a 45 single with one Timeline per song/side This example is a Manifest with two Timelines, each of which represent a temporal extent during which a song is played. As in most cases, the Timeline `duration` is the same length as that of Content Resource painted into it. This example is a recording digitized from a 45 RPM 7 inch single. It demonstrates the use of `format` for the audio files' content type, `language` (One song is in English and one is in German), `behavior` with value "autoPlay" that tells a client to automatically advance to the second Timeline after playing the first, `annotations` that link to Annotation Pages of annotations with the motivation `supplementing` that provide the lyrics (one example is given afterwards) - and an `accompanyingContainer` that carries a picture of the single's cover that is shown while the songs are playing. @@ -242,7 +238,7 @@ duration, autoPlay, format, annotations (transcript), language, accompanyingCont ... ``` -#### Example: a movie with subtitles +### Example: a movie with subtitles This example is a Manifest with one Canvas that represents the temporal extent of the movie (the Canvas `duration`) and its aspect ratio (given by the `width` and `height` of the Canvas). The example demonstrates the use of a `Choice` annotation body to give two alternative versions of the movie, the `timeMode` property ..., and `placeholderContainer` that provides a poster image to show in place of the video file before the user initiates playback. @@ -264,7 +260,7 @@ duration, behavior=autoplay, format, Choice of video 720p, 4K? (forward ref), ti Sometimes, two different formats derived from the same source may have slightly different durations, perhaps a few milliseconds out. What to do... -### 3D +## 3D 3D Content Resources are painted into Scenes. @@ -273,7 +269,7 @@ Scenes have infinite height (y axis), width (x axis) and depth (z axis), where 0 The positive y axis points upwards, the positive x axis points to the right, and the positive z axis points forwards (a [right-handed cartesian coordinate system](https://en.wikipedia.org/wiki/Right-hand_rule)). -#### Example: Static 3D Model of a Spacesuit +### Example: Static 3D Model of a Spacesuit This example is a Manifest with a single Scene, with a single model of a space suit painted at the Scene's origin. @@ -302,7 +298,7 @@ backgroundColor: #000 point selector for positioning -#### Example: 3D Model of a Chessboard +### Example: 3D Model of a Chessboard Chessboard is a Canvas with image more than one model @@ -318,7 +314,7 @@ interactionMode -#### Merge the below into the examples or into model +### Merge the below into the examples or into model This (no units for scale) allows arbitrarily scaled models to be used, including very small or very large, without needing to deal with very small or very large values. If there is a correspondence to a physical scale, then this can be asserted using the physical dimensions pattern(fwd-ref-to-phys-dims). @@ -517,9 +513,9 @@ Todo add example -#### Scene-Specific Resources +### Scene-Specific Resources -##### Camera +#### Camera A Camera provides a view of a region of the Scene's space from a particular position within the Scene; the client constructs a viewport into the Scene and uses the view of one or more Cameras to render that region. The size and aspect ratio of the viewport is client and device dependent. @@ -559,7 +555,7 @@ The first Camera defined and not hidden in a Scene is the default Camera used to -##### Light +#### Light This specification defines four types of Light: @@ -718,33 +714,20 @@ When a Scene is nested into another Scene, the `backgroundColor` of the Scene to -## Annotations and State - - - -### Example: Multi-spectral Images with Comments - +## Annotations -### Annotations - -non-painting - -Comments, tags, etc -transcripts (and back ref to OCR on images etc) +### Comment Annotations -#### Comment Annotations +### Choice of Alternative Resources +Example: Multi-spectral Images with Comments -#### Choice of Alternative Resources -Multispectral here - - -#### Embedded Content +### Embedded Content e.g., painting TextualBody on Canvas @@ -755,34 +738,34 @@ It is important to be able to position the textual body of an annotation within -#### Non Rectangular Segments +### Non Rectangular Segments SvgSelector - move to SpecificResource too ^^ -#### Style +### Style Move to SpecificResource -#### Rotation +### Rotation -#### Hotspot Linking and Activation +### Hotspot Linking and Activation Move to SpecificResource -#### Annotation Page +### Annotation Page "Overlapping elements with a larger z-index cover those with a smaller one." link to https://developer.mozilla.org/en-US/docs/Web/CSS/z-index -#### Annotation Collection +### Annotation Collection deal with this: https://github.com/IIIF/api/pull/2304/files#diff-cc70f02818f6bed2b14dfbf8bf3206e0825047951c8e83ad56fc73e489f82ac4R1757 @@ -865,10 +848,8 @@ partOf - -## State - -### Content State +## Content State 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: @@ -982,14 +963,14 @@ Annotations with the motivation `contentState` are referred to as _content state Content States are used for the following applications: -#### Load a particular view of a resource or group of resources +### 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 +### Load a particular view of some resource and modify it 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: @@ -1033,7 +1014,7 @@ TODO: what is the processing algorithm for applying incoming `hidden` ? When a Content State annotation carries a Scene, a view might be initialized from a Content State that introduces an additional Camera that shows the user the point of interest. -#### Modify the Container in a particular context +### Modify the Container in a particular context The techniques in the previous example are also used within a published IIIF Manifest 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. The `scope` property indicates to the client that the Content State provides valuable context for displaying some aspect of a Scene or other Container. In the case of a commenting annotation, this means that the Content State should be loaded when the commenting annotation is selected or otherwise highlighted. @@ -1201,19 +1182,19 @@ Use of `scope` is permitted in annotations on any Container type, not just Scene -#### The `sequence` behavior +### The `sequence` behavior // Is this right? Language... While all AnnotationPage `items` are inherently ordered, an Annotation Page with the behavior `sequence` is explicitly a narrative, and clients should prevent (dissuade) users from jumping about. The presence of `sequence` affects the way a client should interpret the `reset` property described below. -#### Content States on Manifests +### Content States on Manifests When an annotation with the motivation `contentState` is provided via the `annotations` property of a Manifest, rather than contextually via `scope`, it is assumed to be generally available for selection by the user at any time. A client may present such as annotations as a menu of views, allowing arbitrary jumping into any Scene (or Canvas or Timeline) from any other point. // Is there some overlap here with Range? -#### Processing Content States in Scopes: reset +### Processing Content States in Scopes: reset When a Content State is applied to a Container such as a Scene, it is assumed to be a "diff" - for example if 3 cameras and 4 lights are already present in the Scene, and a Content State asserts a single new Camera, the default behavior is to add this fourth Camera to the Scene and leave the existing resources as they are. @@ -1291,17 +1272,17 @@ Before applying the content state to the Scene, the client should reset the Scen // I am assuming reset is always true except in `linear-nav` - otherwise it's completely unpredictable!! or is it... arbitrary navigation, state provided by initialization content states, etc... -#### Contribute additional information permanently +### Contribute additional information permanently Rerum inbox scenario - should be covered in CS2 protocol -#### activating - animation and interactions +### activating - animation and interactions Annotations with the motivation `activating` are referred to as _activating_ annotations. There are two uses of `activating` annotations: -##### Triggering a content state +#### Triggering a content state An activating annotation links a painting annotation to a content state. When a user interacts with the painting annotation - whether through clicking it, tapping it, or other client-specific behaviors - the linked content state should be processed to modify the Scene or other Container, as in the previous examples. The painting annotation is the target of the activating annotation, and the content state is the body value. Only one content state may be specified in the body array, but the body array may include a `TextualBody` to provide a label for the interaction. The pattern is the same as for the `linking` motivation, but rather than the client opening a new browser window on the resource specified in the `body`, it applies the modification provided by the Content State. @@ -1375,7 +1356,7 @@ The activating annotation is provided in a Container's `annotations` property. I -##### Triggering a named animation in a model +#### 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. @@ -1463,7 +1444,7 @@ if the `target` is an AnimationSelector, then the `body` can ONLY be TextualBody There is a more general rule here! -#### reset +### reset See above... From 829d911e6893b567d4feec97932728a28280ceee Mon Sep 17 00:00:00 2001 From: tomcrane Date: Mon, 19 May 2025 18:22:27 +0100 Subject: [PATCH 076/130] expand the index.md text for containers and annotation --- source/presentation/4.0/index.md | 220 +++++++++++++++++++++++++++---- 1 file changed, 197 insertions(+), 23 deletions(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index 3174f957f..9fa43a2c9 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -53,27 +53,29 @@ __Previous Version:__ [3.0][prezi30] ## Introduction -Presentation, the clue is in the name +The purpose of the IIIF Presentation API specification is to provide a [model](model) and JSON serialization format of that model. +It provides a document format - the IIIF Manifest - for cultural heritage organizations (and anyone else) to publish standardized, interoperable objects. This allows compatible software such as viewers and annotation tools to load and present complex digital objects on the web. -(non-exhaustive) List of use cases +The specification is solely concerned with presentation - providing enough information to render an object in compatible software, and leaving the meaning of the object to external descriptive metadata standards. -1. Artwork -2. Book -3. 45 Single -4. Movie -5. 3D 1 (Single model at 0,0,0 in Scene with ambient Light and Camera) -6. 3D 2 (Complex stuff) -7. Periodical -8. 3D 3 (storytelling) -9. Manuscript (integration) +_Presentation, the clue is in the name_ +This specification is presented in two parts. This document acts as an introduction to the specification through a set of typical (but non-exhaustive) use cases. The model [model](model) provides the formal specification of the terms used in this introduction. -see Terminology at the end +### IIIF Use cases -Mention model.md +1. **Artwork** - a IIIF Manifest that represents a painting, comprising a single image and accompanying display information. +2. **Book** - a IIIF Manifest that represents a digitized bound volume made up many separate images in order. The IIIF model provides structural elements to indicate the chapters. The text of the book is made available in machine-readable form as Web Annotations. +3. **45 Single** - a IIIF Manifest that represents the digitized audio from the two sides of a vinyl 7 inch record. +4. **Movie** - a IIIF Manifest that represents the digitized video of a film. A transcript of the audio is provided as Web Annotations, and additional machine-readable files provide subtitles and captions. +5. **Simple 3D Model** - a IIIF Manifest that publishes a single 3D model. +6. **Complex Scene** - a IIIF Manifest that publishes a complex 3D scene comprising multiple models, lights and cameras. +7. **Periodical** - a IIIF Collection that provides multiple IIIF child IIIF Collections and Manifests, representing the publication run of a newspaper over many years. The IIIF model provides structural elements to indicate individual articles and other elements. +8. **Storytelling in 3D** - a IIIF Manifest that defines a sequence of states in a complex scene for the purposes of guiding a user through a particular experience. +9. **Manuscript** - (integration) -Mention cookbook +These use case were chosen as a broad sample to introduce IIIF Concepts. Many more use cases are provided as recipes in the [IIIF Cookbook](link). Consider diagrams @@ -81,6 +83,8 @@ Consider diagrams ## Foundations +(needs updating) +

Data Model

@@ -96,8 +100,19 @@ Manifests have descriptive, technical and linking properties. The required prope (👀) [Model Documentation](model/#manifest) -``` -Manifest JSON + +```json +{ + "@context": "http://iiif.io/api/presentation/4/context.json", + "id": "https://iiif.io/api/cookbook/recipe/0001-mvm-image/manifest.json", + "type": "Manifest", + "label": { + "en": [ "Single Image Example" ] + }, + "items": [ + // A list of Containers + ] +} ``` @@ -122,6 +137,7 @@ A Container that represents a bounded, two-dimensional space, optionally with a Canvases have two additional required properties: `height` and `width`, which give the spatial extent as unitless integers. Canvases may also have the `duration` property in the same manner as Timelines. + #### Scene A Container that represents a boundless three-dimensional space, optionally with a bounded temporal range. Scenes are typically used for rendering 3D models, and can additionally have Cameras and Lights. @@ -131,15 +147,112 @@ Scenes may also have the `duration` property in the same manner as Timelines. (👀) [Model Documentation](model/#containers) ```json -Manifest JSON with a Timeline, a Canvas and a Scene +{ + "@context": "http://iiif.io/api/presentation/4/context.json", + "id": "https://iiif.io/api/presentation/examples/manifest-with-containers", + "type": "Manifest", + "label": { + "en": [ "A Manifest with all three types of Container" ] + }, + "items": [ + { + "id": "https://iiif.io/api/presentation/examples/manifest-with-containers/timeline", + "type": "Timeline", + "duration": 32.76, + "items": [ + { + "id": "https://iiif.io/api/presentation/examples/manifest-with-containers/page/p1", + "type": "AnnotationPage", + "items": [ + { + "id": "https://iiif.io/api/presentation/examples/manifest-with-containers/annotation/t1", + "type": "Annotation", + "motivation": "painting", + "body": { + "id": "https://iiif.io/api/presentation/example-content-resources/audio/clip.mp3", + "type": "Audio", + "format": "audio/mp3", + "duration": 32.76, + }, + "target": "https://iiif.io/api/presentation/examples/manifest-with-containers/timeline" + } + ] + } + ] + }, + { + "id": "https://iiif.io/api/presentation/examples/manifest-with-containers/canvas", + "type": "Canvas", + "width": 12000, + "height": 9000, + "items": [ + { + "id": "https://iiif.io/api/presentation/examples/manifest-with-containers/page/p2", + "type": "AnnotationPage", + "items": [ + { + "id": "https://iiif.io/api/presentation/examples/manifest-with-containers/annotation/c1", + "type": "Annotation", + "motivation": "painting", + "body": { + "id": "https://iiif.io/api/presentation/example-content-resources/image/painting.jpg", + "type": "Image", + "format": "image/jpeg", + "width": 4000, + "height": 3000 + }, + "target": "https://iiif.io/api/presentation/examples/manifest-with-containers/canvas" + } + ] + } + ] + }, + { + "id": "https://iiif.io/api/presentation/examples/manifest-with-containers/scene", + "type": "Scene", + "items": [ + { + "id": "https://iiif.io/api/presentation/examples/manifest-with-containers/page/p3", + "type": "AnnotationPage", + "items": [ + { + "id": "https://iiif.io/api/presentation/examples/manifest-with-containers/annotation/s1", + "type": "Annotation", + "motivation": "painting", + "body": { + "id": "https://iiif.io/api/presentation/example-content-resources/models/astronaut.glb", + "type": "Model", + "format": "model/gltf-binary" + }, + "target": "https://iiif.io/api/presentation/examples/manifest-with-containers/scene" + } + ] + } + ] + } + ] +} ``` +The above Manifest has three Containers, one of each type. While contrived, it is still valid and the expected user experience would be for a viewer to begin on the Timeline Container, presenting UI for the user to play the audio. The viewer would also present navigation elements to move to the next Container (the Canvas) or otherwise navigate the available Content Containers. Usually, even when a Manifest has a large number of Containers in its `items` property, they are of the same type (e.g., a 100 page book is modelled as a Manifest with 100 Canvases, each bearing an image of one page). But it is not a requirement that all Containers in a Manifest must be of the same type. + +In each of the three Containers, an **Annotation** links the Container to a Content Resource. The Content Resource is _painted_ into the Container by an Annotation whose `target` property is the `id` of the Container. In all three simple cases here the `target` property is the the `id` of the Container with no further qualification. + + + ### Annotations IIIF uses the concept of _Annotation_ to link resources together from around the web. This specification uses a World Wide Web Consortium (W3C) standard for this called the [Web Annotation Data Model][org-web-anno]. This is a structured linking mechanism useful for making comments about Content Resources, but IIIF's primary use of it is to associate the images, audio and other Content Resources with their Containers for presentation. Different uses of Annotation are distinguished through their `motivation` property. This specification defines a value for `motivation` called `painting` for associating Content Resources with Containers, which this specification calls a Painting Annotation. The verb "paint" is also used to refer to the associating of a Content Resource with a Container by a Painting Annotation. This is from the notion of painting onto a canvas, a metaphor borrowed from art and used for image-based digital applications, and expanded by IIIF into "painting" any Content Resource into a Container of any number of dimensions. +In the example Manifest above the first Container is a Timeline. One content resource, an MP3 file, is associated with the Timeline via a Painting Annotation for its entire duration. Typically the duration of the Timeline matches the duration of its content. This is the simplest time-based use case. The `target` property of the Painting Annotation is the whole Timeline, because it is simply the `id` of the Timeline without further qualification. In this simple case, playing the Timeline is the same as playing the MP3. + +The second Container is a Canvas, representing a 2D surface. In this case the Canvas represents an artwork, and there is no duration property. The content resource, a JPEG image of the artwork, is associated with the Canvas via a Painting Annotation. The unit integer coordinates of the Canvas (12000 x 9000) are not the same as the pixel dimensions of the JPEG image (4000 x 3000), but they are proportional - the Canvas has a 4:3 landscape aspect ratio, and so does the JPEG image. The `target` property of the Annotation is the Canvas `id`, unqualified by any particular region; this is taken to mean the content (the image) should fill the Canvas completely. As the Canvas and the image are the same aspect ratio, no distortion will occur. This approach allows the current image to be replaced by a higher resolution image in future, on the same Canvas. The Canvas dimensions establish a coordinate system for _painting annotations_ and other kinds of annotation that link content with the Canvas; they are not pixels of images. + +The third Container is a Scene. Unlike a Canvas, it is not a bounded spatial extent, but may be a bounded temporal extent if it has the optional duration property. It still establishes a coordinate space (x, y, z) but doesn't need any spatial properties to do so as it is always the same, infinite unbounded space. The Annotation paints the astronaut model into the Scene. As no further qualification is given, the astronaut model is placed at the (0,0,0) origin of the Scene. Later examples will show how to control the lighting and camera position(s) and properties, but this is not required; a IIIF viewer is expected to supply ambient light and a default camera position in the absence of specific values. + + The same linking mechanism is also used in IIIF with other motivations for transcriptions, commentary, tags and other content. This provides a single, unified method for aligning content, and provides a standards-based framework for referencing parts of resources. As Annotations can be added later, it promotes a distributed system in which further content such as commentary can be aligned with the objects published on the web. The required properties of Annotations are `id`, `type`, `motivation`, and `target`. Most Annotations also have the `body` property. @@ -148,8 +261,34 @@ The relationship between a Container and a painting annotation is not direct. An (👀) [Model Documentation](model/#annotations) -``` -JSON of painting anno - image to canvas +```json +{ + "id": "https://iiif.io/api/presentation/examples/manifest-with-containers/canvas", + "type": "Canvas", + "width": 12000, + "height": 9000, + "items": [ + { + "id": "https://iiif.io/api/presentation/examples/manifest-with-containers/page/p2", + "type": "AnnotationPage", + "items": [ + { + "id": "https://iiif.io/api/presentation/examples/manifest-with-containers/annotation/c1", + "type": "Annotation", + "motivation": "painting", + "body": { + "id": "https://iiif.io/api/presentation/example-content-resources/image/painting.jpg", + "type": "Image", + "format": "image/jpeg", + "width": 4000, + "height": 3000 + }, + "target": "https://iiif.io/api/presentation/examples/manifest-with-containers/canvas" + } + ] + } + ] +} ``` ### Content Resources @@ -158,6 +297,7 @@ Content Resources are external web resources, including images, video, audio, 3D The required properties of Content Resources are `id` and `type`. Other commonly used properties include `format`, and `width`, `height` and `duration` as appropriate to the Content Resource format. +The Containers example also demonstrates that if you have existing content resources with web URIs - images, audio, video and models - you can quite easily publish IIIF Manifests for them by constructing the appropriate JSON around them and publishing the JSON documents. This requires careful consideration of the URI schemes for `id` properties of Containers and their Manifests to ensure they remain referenceable in the future. The choice of Timeline or Canvas dimensions (duration, width, height) can usually be derived simply from the content; the same duration as the audio or video, and the same unit Canvas dimensions as the image or video pixel dimensions, with the caveat that you should avoid low values for `width` and `height` (ref model). #### Containers as Content Resources @@ -173,10 +313,23 @@ Parts of resources on the Web are identified using URIs with a fragment componen There are different types of fragment based on the format of the resource. The most commonly used type in IIIF is the W3C's Media Fragments specification, as it can define a temporal and 2D spatial region. -``` -comment annotation about part of the previous example's Canvas using #Fragment +```json +{ + "id": "https://iiif.io/api/presentation/examples/manifest-with-containers/comments/c1", + "type": "Annotation", + "motivation": "commenting", + "body": { + "type": "TextualBody", + "value": "Koto with a cover being carried", + "language": "en", + "format": "text/plain" + }, + "target": "https://iiif.io/api/presentation/examples/manifest-with-containers/canvas#xywh=6050,3220,925,1250" +} ``` +Here the Canvas `id` from the earlier example is still the `target` of an Annotation, but it has been qualified to a specific region of that Canvas by a Fragment Selector `#xywh=6050,3220,925,1250`. Note that the x, y, w, and h are in the Canvas coordinate space, not the pixel dimensions space. This annotation has no knowledge of or dependency on the particular image we painted onto the Canvas; we could replace that image with one of a different, higher resolution without affecting this annotation or the region of the Canvas it targets. + ##### Specific Resource @@ -186,8 +339,29 @@ Several different classes of Selector are used in IIIF, including an alternative The required properties of Specific Resources are `id`, `type`, and `source`. Other commonly used properties include `selector`, `transform`, and `scope`. -``` -comment annotation about part of the previous example's Canvas using FragmentSelector +```json +{ + "id": "https://iiif.io/api/presentation/examples/manifest-with-containers/comments/c1", + "type": "Annotation", + "motivation": "commenting", + "body": { + "type": "TextualBody", + "value": "Koto with a cover being carried", + "language": "en", + "format": "text/plain" + }, + "target": { + "type": "SpecificResource", + "source": { + "id": "https://iiif.io/api/presentation/examples/manifest-with-containers/canvas", + "type": "Canvas" + }, + "selector": { + "type": "FragmentSelector", + "value": "xywh=6050,3220,925,1250" + } + } +} ``` From 0bf6b9f76032f9151d193f7918c24c6bb30d6dbd Mon Sep 17 00:00:00 2001 From: Tom Crane Date: Wed, 21 May 2025 13:38:34 +0100 Subject: [PATCH 077/130] Apply suggestions from code review Co-authored-by: Julie Winchester --- source/presentation/4.0/index.md | 2 +- source/presentation/4.0/model.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index 632cea93b..bb3c2b938 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -1478,7 +1478,7 @@ See above... ## Conveying Physical Dimensions -It is often important to know how big something is, especially when comparing objects together. The dimensions of a Canvas, or the pixel density of a photograph, are unrelated to the real-world size of the object they show. A large wall painting and a tiny miniature may both be conveyed by 20 megapixel source images on a 4000 by 3000 unit Canvas. +In many cases, the dimensions of a Canvas, or the pixel density of a photograph, are not necessarily related to the real-world size of the object they show. A large wall painting and a tiny miniature may both be conveyed by 20 megapixel source images on a 4000 by 3000 unit Canvas. But it can be important to know how big something is or if there is a relationship between pixel density and physical length, especially when comparing objects together. An X-Ray image may have a tight expectation for the physical distance between two adjacent pixels, or a scanned 3D model may be constructed such that each 3D coordinate unit corresponds to one meter of physical distance. The `spatialScale` property of a Canvas or Scene provides a corresponding real-world scale for a unit of the Canvas or Scene coordinate system, allowing clients to provide scale information to users, for example by an on-screen virtual ruler. In a 2-up viewer, a client could scale two views to convey the true relative sizes of two objects. diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index 0279e8efc..9a837fc8b 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -1852,7 +1852,7 @@ The value _MUST_ be an array of JSON objects. Each object _MUST_ be a service re ### spatialScale {: #spatialScale} -A single UnitValue that defines a real-world scale factor for the coordinate units of a Canvas or Scene. A Canvas with a `width` of 5000 and a `spatialScale` with `value` 0.00008 represents a physical space 0.4 metres wide. The value of `unit` _MUST_ always be `m`, i.e., metres. +A single UnitValue that defines a real-world scale factor for the coordinate units of a Canvas or Scene. For a Canvas, this defines the physical distance between adjacent units horizontally and vertically. A Canvas with a `width` of 5000 and a `spatialScale` with `value` 0.00008 represents a physical space 0.4 metres wide. For a Scene, this defines the physical distance corresponding to the XYZ coordinate units, or in other words, the physical distance length of a unit vector in the 3D coordinate space. The value of `unit` _MUST_ always be `m`, i.e., metres. {% include api/code_header.html %} From bd809b889128fa4bbe178bec54702f3783e7e395 Mon Sep 17 00:00:00 2001 From: Michael Appleby Date: Wed, 21 May 2025 11:18:40 -0400 Subject: [PATCH 078/130] AnnotationCollection and AnnotationPage properties --- source/presentation/4.0/model.md | 81 +++++++++++++++++++++++++++++++- 1 file changed, 80 insertions(+), 1 deletion(-) diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index 7c953dc18..829ecbf4b 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -1060,7 +1060,24 @@ The value is a non-negative floating point number, in the coordinate space of th ``` ### first +{: #first} +This property references the first Annotation Page within an Annotation Collection. + +The value _MUST_ be a JSON object with `id` and `type` properties. The `id` _MUST_ be the HTTP(S) URI of the referenced Annotation Page. The value of `type` _MUST_ be `AnnotationPage`. + +* A non-empty AnnotationCollection _MUST_ have the `first` property.
+ Clients _MUST_ process the `first` property on an AnnotationCollection. + +{% include api/code_header.html %} +``` json-doc +{ + "first": { + "id": "https://example.org/iiif/annotationPage/1", + "type": "AnnotationPage" + } +} +``` ### fieldOfView {: #fieldOfView} @@ -1296,6 +1313,24 @@ The value _MUST_ be an array of strings. Each item in the array _MUST_ be a vali ``` ### last +{: #lsst} + +This property references the last Annotation Page within an Annotation Collection. + +The value _MUST_ be a JSON object with `id` and `type` properties. The `id` _MUST_ be the HTTP(S) URI of the referenced Annotation Page. The value of `type` _MUST_ be `AnnotationPage`. + +* A non-empty AnnotationCollection _SHOULD_ have the `last` property.
+ Clients _SHOULD_ process the `last` property on an AnnotationCollection. + +{% include api/code_header.html %} +``` json-doc +{ + "last": { + "id": "https://example.org/iiif/annotationPage/17", + "type": "AnnotationPage" + } +} +``` ### logo {: #logo} @@ -1465,9 +1500,24 @@ The value is a non-negative floating point number, in the coordinate space of th ``` ### next +{: #next} + +A reference from an Annotation Page to the following Annotation Page within an Annotation Collection. + +The value must be a JSON object, with the `id` and `type` properties. The value of the `id` property must be a string, and must be the HTTP(S) URI of the following Annotation Page. The value of the `type` property must be the string `AnnotationPage`. -... +* An AnnotationPage _MUST_ have a `next` property, unless it is the last page in the AnnotationCollection.
+ Clients _MUST_ processs the `next` property on an AnnotationPage. +{% include api/code_header.html %} +``` json-doc +{ + "next": { + "id": "https://example.org/iiif/annotationPage/3", + "type": "AnnotationPage" + } +} +``` ### partOf {: #partOf} @@ -1548,7 +1598,24 @@ The value of this property _MUST_ be a JSON object conforming to the `SpecificRe ``` ### prev +{: #prev} +A reference from an Annotation Page to the preceding Annotation Page within an Annotation Collection. + +The value must be a JSON object, with the `id` and `type` properties. The value of the `id` property must be a string, and must be the HTTP(S) URI of the preceding Annotation Page. The value of the `type` property must be the string `AnnotationPage`. + +* An AnnotationPage _SHOULD_ have a `prev` property, unless it is the first page in the AnnotationCollection.
+ Clients _SHOULD_ processs the `prev` property on an AnnotationPage. + +{% include api/code_header.html %} +``` json-doc +{ + "prev": { + "id": "https://example.org/iiif/annotationPage/1", + "type": "AnnotationPage" + } +} +``` ### profile {: #profile} @@ -2021,10 +2088,22 @@ The value _MUST_ be a string. ### total +{: #total} For compatability with ActivityStreams and the Change Discovery API, clients _SHOULD_ also accept `totalItems` as the name of this property. {: .note} +The `total` property indicates the total number of annotations contained in an Annotation Collection. + +The value of this property _MUST_ be a non-negative integer. + +* An AnnotationCollection _SHOULD_ have the `total` property.
+ Clients _SHOULD_ process the `total` property on an AnnotationCollection. + +{% include api/code_header.html %} +``` json-doc +{ "total": 1701 } +``` ### transform {: #transform} From 49dcef6e76624c84f339d88403ca9e5543553677 Mon Sep 17 00:00:00 2001 From: Michael Appleby Date: Wed, 21 May 2025 11:22:28 -0400 Subject: [PATCH 079/130] a->the and alpha order --- source/presentation/4.0/model.md | 34 +++++++++++++++++--------------- 1 file changed, 18 insertions(+), 16 deletions(-) diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index 829ecbf4b..073a38ad3 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -1059,6 +1059,22 @@ The value is a non-negative floating point number, in the coordinate space of th { "far": 200.0 } ``` +### fieldOfView +{: #fieldOfView} + +The angle which a PerspectiveCamera can "see". + +!!! warning "Need more info" + +The value _MUST_ be a floating point number greater than 0 and less than 180, and is measured in degrees. If this property is not specified, then the default value is client-dependent. + +* A PerspectiveCamera _SHOULD_ have the `fieldOfView` property.
+ Clients _SHOULD_ process the `fieldOfView` property on Cameras. + +```json-doc +{ "fieldOfView": 50.0 } +``` + ### first {: #first} @@ -1079,21 +1095,7 @@ The value _MUST_ be a JSON object with `id` and `type` properties. The `id` _M } ``` -### fieldOfView -{: #fieldOfView} - -The angle which a PerspectiveCamera can "see". - -!!! warning "Need more info" -The value _MUST_ be a floating point number greater than 0 and less than 180, and is measured in degrees. If this property is not specified, then the default value is client-dependent. - -* A PerspectiveCamera _SHOULD_ have the `fieldOfView` property.
- Clients _SHOULD_ process the `fieldOfView` property on Cameras. - -```json-doc -{ "fieldOfView": 50.0 } -``` ### format {: #format} @@ -1506,7 +1508,7 @@ A reference from an Annotation Page to the following Annotation Page within an A The value must be a JSON object, with the `id` and `type` properties. The value of the `id` property must be a string, and must be the HTTP(S) URI of the following Annotation Page. The value of the `type` property must be the string `AnnotationPage`. -* An AnnotationPage _MUST_ have a `next` property, unless it is the last page in the AnnotationCollection.
+* An AnnotationPage _MUST_ have the `next` property, unless it is the last page in the AnnotationCollection.
Clients _MUST_ processs the `next` property on an AnnotationPage. {% include api/code_header.html %} @@ -1604,7 +1606,7 @@ A reference from an Annotation Page to the preceding Annotation Page within an A The value must be a JSON object, with the `id` and `type` properties. The value of the `id` property must be a string, and must be the HTTP(S) URI of the preceding Annotation Page. The value of the `type` property must be the string `AnnotationPage`. -* An AnnotationPage _SHOULD_ have a `prev` property, unless it is the first page in the AnnotationCollection.
+* An AnnotationPage _SHOULD_ have the `prev` property, unless it is the first page in the AnnotationCollection.
Clients _SHOULD_ processs the `prev` property on an AnnotationPage. {% include api/code_header.html %} From d9d168e0031987504da20cf6b49606d03061dc28 Mon Sep 17 00:00:00 2001 From: Julie Winchester Date: Thu, 22 May 2025 12:31:39 -0500 Subject: [PATCH 080/130] Update transform property and class definitions --- source/presentation/4.0/model.md | 65 +++++++++++++++++++++++++++----- 1 file changed, 55 insertions(+), 10 deletions(-) diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index 7c953dc18..6b858caac 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -781,32 +781,62 @@ Can have a Timeline as the source of the audio? FIXME: "No default direction, MUST provide a Rotate Transform.", changed language to default to -y to match Spot Light - #### Transforms -here are the rules about transforms? - +An operation to transform a 3D resource. Transforms are specified by the [transform](#transform) property on a Specific Resource. Transforms are carried out on a resource in the implicit or explicit local coordinate space of the resource, and are performed prior to painting that resource into the relatively more global coordinate space of a Scene. +__Properties__
+All Transforms _MUST_ have the following properties: [type](#type).

+All Transforms _MAY_ have the following properties: [x](#x), [y](#y), and [z](#z). +{: .note} ##### Rotate Transform > `"type": "RotateTransform"` -A RotateTransform rotates the local coordinate space around the given axis in a counter-clockwise direction around the axis itself (e.g. around a pivot point of 0 on the axis). A point that was at x=1,y=1 and was rotated 90 degrees around the x axis would be at x=1,y=0,z=1. If an axis value is not specified, then it is not changed, resulting in a default of 0.0 +A RotateTransform rotates the resource around one or more axes. If present, the values of properties `x`, `y`, and `z` _MUST_ be angular values in degrees that specify the extent of rotation around each axis. Positive angular values indicate counter-clockwise rotation around the axis due to coordinate right-handedness. Axis rotation is performed with a pivot point at the origin of the local coordinate space. As an example, for a point at (1, 1, 0) in local coordinate space, rotating 90 degrees around the x axis would transform the point to be at (1, 0, 1). If any property `x`, `y`, or `z` is not specified or is specified to be 0.0, rotation around that axis does not occur. When more than one axis rotation is specified through multiple non-zero values for `x`, `y`, and `z`, rotations comprise an Euler angle with ordering x-y-z, and rotation _MUST_ be carried out first around the x axis, second around the y axis, and third around the z axis. +{% include api/code_header.html %} +```json +{ + "type": "RotateTransform", + "x": 0.0, + "y": 180.0, + "z": 0.0 +} +``` ##### Scale Transform > `"type": "ScaleTransform"` -A ScaleTransform applies a multiplier to one or more axes in the local coordinate space. A point that was at 3.5, after applying a ScaleTransform of 2.0 would then be at 7.0. If an axis value is not specified, then it is not changed, resulting in a default of 1.0 +A ScaleTransform scales the resource along one or more axes. If present, the values of properties `x`, `y`, and `z` _MUST_ be multiplicative scale factors that specify the extent of scaling along each axis. As an example, for a point at 3.5 along the x axis in local coordinate space, scaling along the x axis by 2.0 would result in the point being at 7.0. If any property `x`, `y`, or `z` is not specified or is specified to be 1.0, scaling does not occur along that axis. Negative scale factor values indicate mirroring as well as scaling along that axis. + +{% include api/code_header.html %} +```json +{ + "type": "ScaleTransform", + "x": 2.0, + "y": 2.0, + "z": 2.0 +} +``` ##### Translate Transform > `"type": "TranslateTransform"` -A TranslateTransform moves all of the objects in the local coordinate space the given distance along the axis. A point that was at x=1.0, after applying a TranslateTransform of x=1.0 would be at x=2.0. If an axis value is not specified then it is not changed, resulting in a default of 0.0 +A TranslateTransform translates or moves the resource across one or more axes. If present, the values of properties `x`, `y`, and `z` _MUST_ be coordinate unit distances that specify the distance across each axis to translate the resource. As an example, for a point at 1.0 along the x axis, translating across the x axis by 3.0 would result in the point being at 4.0. If any property `x`, `y`, or `z` is not present or is specified to be 0.0, translation does not occur across that axis. +{% include api/code_header.html %} +```json +{ + "type": "TranslateTransform", + "x": -1.0, + "y": 0.0, + "z": 0.0 +} +``` ### Utility Classes @@ -2029,13 +2059,28 @@ For compatability with ActivityStreams and the Change Discovery API, clients _SH ### transform {: #transform} -_Summary here_ - -The value of this property is an array of JSON objects, each of which is a Transform. +An ordered list of 3D transform operations (translation, rotation, and scale) to be performed on a resource prior to painting that resource into a Scene. Transforms _MUST_ be applied to the resource in the order given. The resulting state of the resource after applying a transform _MUST_ be the input state for the subsequent transform in the ordered list. Therefore, transforms are not independent, and different orders of the same set of transforms can produce different results. The list of transforms _MAY_ include multiple transforms of the same type, e.g., multiple rotation operations. -Process them in order given. +The value of this property _MUST_ be array of JSON objects, each of which _MUST_ be a Transform. +* A Specific Resource _MAY_ have the `transform` property.
+ Clients _SHOULD_ process the `transform` property on Specific Resources. +* Other classes _MUST NOT_ have the `transform` property.
+ Clients _MUST_ ignore the `transform` property on all other classes. +{% include api/code_header.html %} +```json +{ + "transform": [ + { + "type": "RotateTransform", + "x": 0.0, + "y": 180.0, + "z": 0.0 + } + ] +} +``` ### type {: #type} From b851906c73bb0bf6f1161a9e4a6dc40cba0e07fc Mon Sep 17 00:00:00 2001 From: Julie Winchester Date: Thu, 22 May 2025 13:03:15 -0500 Subject: [PATCH 081/130] Update source/presentation/4.0/model.md --- source/presentation/4.0/model.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index 073a38ad3..23f74b0bc 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -1315,7 +1315,7 @@ The value _MUST_ be an array of strings. Each item in the array _MUST_ be a vali ``` ### last -{: #lsst} +{: #last} This property references the last Annotation Page within an Annotation Collection. From 4b793fca8ac9b1b29429c778444f160e3a1b9407 Mon Sep 17 00:00:00 2001 From: Rob Sanderson Date: Tue, 27 May 2025 12:08:17 -0400 Subject: [PATCH 082/130] merge conflict --- source/presentation/4.0/model.md | 96 ++++++++++++++++++++------------ 1 file changed, 60 insertions(+), 36 deletions(-) diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index 02f3584fd..399c073dd 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -8,7 +8,7 @@ tags: [specifications, presentation-api] major: 4 minor: 0 patch: 0 -pre: +pre: redirect_from: - /presentation/model.html - /presentation/4/model.html @@ -26,10 +26,10 @@ editors: ORCID: institution: UCLA - name: Julie Winchester - ORCID: + ORCID: institution: Duke University - name: Jeff Mixter - ORCID: + ORCID: institution: OCLC hero: image: '' @@ -613,7 +613,7 @@ Orthographic Cameras _SHOULD_ have the following additional properties: [viewHei > `"type": "PerspectiveCamera"` -`PerspectiveCamera` mimics the way the human eye sees, in that objects further from the camera are smaller. +A Perspective Camera mimics the way the human eye sees, in that objects further from the camera are smaller. The region of the Scene's space that is observable by the camera is bounded by two planes orthogonal to the direction the camera is facing, given in the `near` and `far` properties, and a vertical projection angle that provides the top and bottom planes of the region in the `fieldOfView` property. @@ -646,7 +646,7 @@ All Lights _SHOULD_ have the following properties: [color](#color), and [intensi All Lights _MAY_ have the following properties: [label](#label). {: .note} - + ##### Ambient Light > `"type": "AmbientLight"` @@ -667,7 +667,7 @@ Ambient Light evenly illuminates all objects in the Scene, and does not have a d Directional Lights emit their light in a specific direction as if infinitely far away, and as such the light does not come from a specific position. The rays produced are all parallel. The Light itself _MUST_ be added into the scene at a specific position, however this is only such that editing interfaces can render the object to the user. -The light is emitted in the negative Y (-y) direction by default, thus straight down, but the orientation of the light can be altered with `lookAt` or with a `RotationTransform`. +The light is emitted in the negative Y direction by default, thus straight down, but the orientation of the light can be altered with `lookAt` or with a `RotationTransform`. __Properties__
Directional Lights _MAY_ have the following additional properties: [lookAt](#lookAt) @@ -686,7 +686,7 @@ Directional Lights _MAY_ have the following additional properties: [lookAt](#loo > `"type": "PointLight"` -Point Lights emit from a single point within the Scene in all directions. +Point Lights emit in all directions from a single point within the Scene. ```json { @@ -701,9 +701,9 @@ Point Lights emit from a single point within the Scene in all directions. > `"type": "SpotLight"` -Spot Light emits a cone of light from a single point in a given direction. The Spot Light's `angle` property defines the radius of the cone. +Spot Light emits a cone of light in a given direction from a single point. The Spot Light's `angle` property defines the radius of the cone. The default angle is client dependent if not specified. -The Spot Light emits in the negative Y (-y) direction by default, but the orientation of the light can be altered by subsequent transforms. +The Spot Light emits in the negative Y direction by default, but the orientation of the light can be altered by subsequent transforms, or by setting the `lookAt` property. diagram of cone geometry showing how the angle of the cone is defined @@ -712,8 +712,6 @@ Spot Lights _SHOULD_ have the following additional properties: [angle](#angle) +All Audio Emitters _MUST_ have the following properties: [id](#id), [type](#type) and [source](#source).

+All Audio Emitters _SHOULD_ have the following properties: [volume](#volume).

+All Audio Emitters _MAY_ have the following properties: [label](#label). +{: .note} ##### Ambient Audio > `"type": "AmbientAudio"` -Ambient Audio emits equally throughout the Scene, and does not have a position or direction. +Ambient Audio emits equally throughout the Scene, and does not have a position or direction. The Emitter _MUST_ be annotated somewhere within the Scene so that it can be rendered by editing interfaces, and exists within the Scene's hierarchy. + +```json +{ + "id": "https://example.org/iiif/audio/1", + "type": "AmbientAudio", + "source": { + "id": "https://example.org/media/path/to/my.mp3", + "type": "Audio", + "format": "audio/mp3" + } +} +``` ##### Point Audio > `"type": "PointAudio"` -Point Audio emits from a single point in the Scene in all directions. +Point Audio emits in all directions from a single point in the Scene. + +```json +{ + "id": "https://example.org/iiif/audio/2", + "type": "PointAudio", + "source": { + "id": "https://example.org/media/path/to/my.mp3", + "type": "Audio", + "format": "audio/mp3" + } +} +``` ##### Spot Audio > `"type": "SpotAudio"` -Spot Audio emits a cone of sound from a single point in a given direction. The Spot Audio's `angle` property defines the radius of the cone. +Spot Audio emits a cone of sound in a given direction from a single point. The Spot Audio's `angle` property defines the radius of the cone. The default angle is client dependent if not specified. -The Spot Audio emits in the negative Y (-y) direction by default, but the orientation of the sound can be altered by subsequent transforms. +The Spot Audio emits in the negative Y direction by default, but the orientation of the sound can be altered by subsequent transforms, or by setting the `lookAt` property. -Can have a Timeline as the source of the audio? +__Properties__
+Spot Audio Emitters _SHOULD_ have the following additional properties: [angle](#angle)

+Spot Audio Emitters _MAY_ have the following additional properties: [lookAt](#lookAt) +{: .note} ```json { - "id": "https://example.org/iiif/spotAudio/1", + "id": "https://example.org/iiif/audio/3", "type": "SpotAudio", "source": { "id": "https://example.org/media/path/to/my.mp3", @@ -774,16 +805,13 @@ Can have a Timeline as the source of the audio? "type": "UnitValue", "unit": "relative", "value": 1.0 - }, - "transform": [] + } } ``` -FIXME: "No default direction, MUST provide a Rotate Transform.", changed language to default to -y to match Spot Light - #### Transforms -An operation to transform a 3D resource. Transforms are specified by the [transform](#transform) property on a Specific Resource. Transforms are carried out on a resource in the implicit or explicit local coordinate space of the resource, and are performed prior to painting that resource into the relatively more global coordinate space of a Scene. +An operation to transform a 3D resource. Transforms are specified by the [transform](#transform) property on a Specific Resource. Transforms are carried out on a resource in the implicit or explicit local coordinate space of the resource, and are performed prior to painting that resource into the relatively more global coordinate space of a Scene. __Properties__
All Transforms _MUST_ have the following properties: [type](#type).

@@ -794,7 +822,7 @@ All Transforms _MAY_ have the following properties: [x](#x), [y](#y), and [z](#z > `"type": "RotateTransform"` -A RotateTransform rotates the resource around one or more axes. If present, the values of properties `x`, `y`, and `z` _MUST_ be angular values in degrees that specify the extent of rotation around each axis. Positive angular values indicate counter-clockwise rotation around the axis due to coordinate right-handedness. Axis rotation is performed with a pivot point at the origin of the local coordinate space. As an example, for a point at (1, 1, 0) in local coordinate space, rotating 90 degrees around the x axis would transform the point to be at (1, 0, 1). If any property `x`, `y`, or `z` is not specified or is specified to be 0.0, rotation around that axis does not occur. When more than one axis rotation is specified through multiple non-zero values for `x`, `y`, and `z`, rotations comprise an Euler angle with ordering x-y-z, and rotation _MUST_ be carried out first around the x axis, second around the y axis, and third around the z axis. +A RotateTransform rotates the resource around one or more axes. If present, the values of properties `x`, `y`, and `z` _MUST_ be angular values in degrees that specify the extent of rotation around each axis. Positive angular values indicate counter-clockwise rotation around the axis due to coordinate right-handedness. Axis rotation is performed with a pivot point at the origin of the local coordinate space. As an example, for a point at (1, 1, 0) in local coordinate space, rotating 90 degrees around the x axis would transform the point to be at (1, 0, 1). If any property `x`, `y`, or `z` is not specified or is specified to be 0.0, rotation around that axis does not occur. When more than one axis rotation is specified through multiple non-zero values for `x`, `y`, and `z`, rotations comprise an Euler angle with ordering x-y-z, and rotation _MUST_ be carried out first around the x axis, second around the y axis, and third around the z axis. {% include api/code_header.html %} ```json @@ -810,7 +838,7 @@ A RotateTransform rotates the resource around one or more axes. If present, the > `"type": "ScaleTransform"` -A ScaleTransform scales the resource along one or more axes. If present, the values of properties `x`, `y`, and `z` _MUST_ be multiplicative scale factors that specify the extent of scaling along each axis. As an example, for a point at 3.5 along the x axis in local coordinate space, scaling along the x axis by 2.0 would result in the point being at 7.0. If any property `x`, `y`, or `z` is not specified or is specified to be 1.0, scaling does not occur along that axis. Negative scale factor values indicate mirroring as well as scaling along that axis. +A ScaleTransform scales the resource along one or more axes. If present, the values of properties `x`, `y`, and `z` _MUST_ be multiplicative scale factors that specify the extent of scaling along each axis. As an example, for a point at 3.5 along the x axis in local coordinate space, scaling along the x axis by 2.0 would result in the point being at 7.0. If any property `x`, `y`, or `z` is not specified or is specified to be 1.0, scaling does not occur along that axis. Negative scale factor values indicate mirroring as well as scaling along that axis. {% include api/code_header.html %} ```json @@ -826,7 +854,7 @@ A ScaleTransform scales the resource along one or more axes. If present, the val > `"type": "TranslateTransform"` -A TranslateTransform translates or moves the resource across one or more axes. If present, the values of properties `x`, `y`, and `z` _MUST_ be coordinate unit distances that specify the distance across each axis to translate the resource. As an example, for a point at 1.0 along the x axis, translating across the x axis by 3.0 would result in the point being at 4.0. If any property `x`, `y`, or `z` is not present or is specified to be 0.0, translation does not occur across that axis. +A TranslateTransform translates or moves the resource across one or more axes. If present, the values of properties `x`, `y`, and `z` _MUST_ be coordinate unit distances that specify the distance across each axis to translate the resource. As an example, for a point at 1.0 along the x axis, translating across the x axis by 3.0 would result in the point being at 4.0. If any property `x`, `y`, or `z` is not present or is specified to be 0.0, translation does not occur across that axis. {% include api/code_header.html %} ```json @@ -852,7 +880,7 @@ A TranslateTransform translates or moves the resource across one or more axes. I A UnitValue expresses a quantity through a numerical value and associated unit of measurement. -`"type": "UnitValue"` +`"type": "UnitValue"` @@ -1241,7 +1269,7 @@ The `value` property of the UnitValue _MUST_ be between 0.0 and 1.0. A set of features that guide or limit user interaction with content within a Container that the publisher of the content would prefer the client to use when presenting the resource. This specification defines values in the table below that guide interactions with Cameras within a Scene. Other values for other Container types or specifying other interaction modes for 3D content may be defined externally as an [extension][prezi30-ldce]. For interaction modes pertaining to Cameras within a Scene, the client _SHOULD_ use `interactionMode` to determine the user experience features and approaches whereby users are permitted to change or adjust Cameras when viewing content within a Scene (e.g., orbiting around the scene or locking the user to a first-person perspective). -When more than one interaction mode is present, the client _SHOULD_ pick the first interaction mode that the client is capable of supporting. +When more than one interaction mode is present, the client _SHOULD_ pick the first interaction mode that the client is capable of supporting. For interaction modes that involve a Camera orbiting around a target point, the target point _SHOULD_ be the same as the Camera's `lookAt` property. @@ -2142,7 +2170,7 @@ The value of this property _MUST_ be a non-negative integer. An ordered list of 3D transform operations (translation, rotation, and scale) to be performed on a resource prior to painting that resource into a Scene. Transforms _MUST_ be applied to the resource in the order given. The resulting state of the resource after applying a transform _MUST_ be the input state for the subsequent transform in the ordered list. Therefore, transforms are not independent, and different orders of the same set of transforms can produce different results. The list of transforms _MAY_ include multiple transforms of the same type, e.g., multiple rotation operations. -The value of this property _MUST_ be array of JSON objects, each of which _MUST_ be a Transform. +The value of this property _MUST_ be array of JSON objects, each of which _MUST_ be a Transform. * A Specific Resource _MAY_ have the `transform` property.
Clients _SHOULD_ process the `transform` property on Specific Resources. @@ -2407,7 +2435,3 @@ The JSON-LD keywords `@id`, `@type` and `@none` are mapped to `id`, `type` and ` ### Registries of Values FIXME: Describe the registries - - - - From 9ed1fb36369e9a96965da3d1557e9c4914a1af13 Mon Sep 17 00:00:00 2001 From: Rob Sanderson Date: Tue, 27 May 2025 15:02:05 -0400 Subject: [PATCH 083/130] Updates --- source/presentation/4.0/model.md | 43 ++++++++++++++++++++++++-------- 1 file changed, 32 insertions(+), 11 deletions(-) diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index 399c073dd..a441cc400 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -811,22 +811,23 @@ Spot Audio Emitters _MAY_ have the following additional properties: [lookAt](#lo #### Transforms -An operation to transform a 3D resource. Transforms are specified by the [transform](#transform) property on a Specific Resource. Transforms are carried out on a resource in the implicit or explicit local coordinate space of the resource, and are performed prior to painting that resource into the relatively more global coordinate space of a Scene. +An operation to transform a 3D resource. Transforms are specified by the [transform](#transform) property on a Specific Resource. Transforms are carried out on a resource in the implicit or explicit local coordinate space of the resource, and are performed prior to painting that resource into any subsequent coordinate space. __Properties__
-All Transforms _MUST_ have the following properties: [type](#type).

-All Transforms _MAY_ have the following properties: [x](#x), [y](#y), and [z](#z). +All Transforms _MUST_ have the following properties: [id](#id), [type](#type).

+All Transforms _MAY_ have the following properties: [label](#label), [x](#x), [y](#y), and [z](#z). {: .note} ##### Rotate Transform > `"type": "RotateTransform"` -A RotateTransform rotates the resource around one or more axes. If present, the values of properties `x`, `y`, and `z` _MUST_ be angular values in degrees that specify the extent of rotation around each axis. Positive angular values indicate counter-clockwise rotation around the axis due to coordinate right-handedness. Axis rotation is performed with a pivot point at the origin of the local coordinate space. As an example, for a point at (1, 1, 0) in local coordinate space, rotating 90 degrees around the x axis would transform the point to be at (1, 0, 1). If any property `x`, `y`, or `z` is not specified or is specified to be 0.0, rotation around that axis does not occur. When more than one axis rotation is specified through multiple non-zero values for `x`, `y`, and `z`, rotations comprise an Euler angle with ordering x-y-z, and rotation _MUST_ be carried out first around the x axis, second around the y axis, and third around the z axis. +A Rotate Transform rotates the resource around one or more axes. If present, the values of properties `x`, `y`, and `z` _MUST_ be angular values in degrees that specify the extent of rotation around each axis. Positive angular values indicate counter-clockwise rotation around the axis due to coordinate right-handedness. Axis rotation is performed with a pivot point at the origin of the local coordinate space. As an example, for a point at (1, 1, 0) in local coordinate space, rotating 90 degrees around the x axis would transform the point to be at (1, 0, 1). If any property `x`, `y`, or `z` is not specified or is specified to be 0.0, rotation around that axis does not occur. When more than one axis rotation is specified through multiple non-zero values for `x`, `y`, and `z`, rotations comprise a Euler angle with ordering x-y-z, and rotation _MUST_ be carried out first around the x axis, second around the y axis, and third around the z axis. {% include api/code_header.html %} ```json { + "id": "https://example.org/iiif/transform/1", "type": "RotateTransform", "x": 0.0, "y": 180.0, @@ -838,11 +839,12 @@ A RotateTransform rotates the resource around one or more axes. If present, the > `"type": "ScaleTransform"` -A ScaleTransform scales the resource along one or more axes. If present, the values of properties `x`, `y`, and `z` _MUST_ be multiplicative scale factors that specify the extent of scaling along each axis. As an example, for a point at 3.5 along the x axis in local coordinate space, scaling along the x axis by 2.0 would result in the point being at 7.0. If any property `x`, `y`, or `z` is not specified or is specified to be 1.0, scaling does not occur along that axis. Negative scale factor values indicate mirroring as well as scaling along that axis. +A Scale Transform scales the resource along one or more axes. If present, the values of properties `x`, `y`, and `z` _MUST_ be multiplicative scale factors that specify the extent of scaling along each axis. As an example, for a point at 3.5 along the x axis in local coordinate space, scaling along the x axis by 2.0 would result in the point being at 7.0. If any property `x`, `y`, or `z` is not specified or is specified to be 1.0, scaling does not occur along that axis. Negative scale factor values indicate mirroring as well as scaling along that axis. {% include api/code_header.html %} ```json { + "id": "https://example.org/iiif/transform/2", "type": "ScaleTransform", "x": 2.0, "y": 2.0, @@ -854,11 +856,12 @@ A ScaleTransform scales the resource along one or more axes. If present, the val > `"type": "TranslateTransform"` -A TranslateTransform translates or moves the resource across one or more axes. If present, the values of properties `x`, `y`, and `z` _MUST_ be coordinate unit distances that specify the distance across each axis to translate the resource. As an example, for a point at 1.0 along the x axis, translating across the x axis by 3.0 would result in the point being at 4.0. If any property `x`, `y`, or `z` is not present or is specified to be 0.0, translation does not occur across that axis. +A Translate Transform translates or moves the resource across one or more axes. If present, the values of properties `x`, `y`, and `z` _MUST_ be coordinate unit distances that specify the distance across each axis to translate the resource. As an example, for a point at 1.0 along the x axis, translating across the x axis by 3.0 would result in the point being at 4.0. If any property `x`, `y`, or `z` is not present or is specified to be 0.0, translation does not occur across that axis. {% include api/code_header.html %} ```json { + "id": "https://example.org/iiif/transform/3", "type": "TranslateTransform", "x": -1.0, "y": 0.0, @@ -870,19 +873,37 @@ A TranslateTransform translates or moves the resource across one or more axes. I #### Agent -`"type": "Agent"` +> `"type": "Agent"` + +An Agent represents a person or organization, typically referenced with the `provider` property. +The Agent is not intended to be used as a primary identifier for the person or organization, nor to provide structured metadata, but instead to ensure that the information to be rendered to the user can be kept together in the situation when there are multiple agents being referenced. + +__Properties__
+An Agent _MUST_ have the following properties: [id](#id), [type](#type), and [label](#label).

+An Agent _SHOULD_ have the following properties: [homepage](#homepage), and [logo](#logo)

. +An Agent _MAY_ have the following properties: [seeAlso](#seeAlso), and [summary](#summary). +{: .note} + #### Service -`"type": "Service"` +> `"type": "Service"` -#### Unit Value +A Service is a software application outside of the Manifest that a client might interact with to gain additional information or functionality for the resource that is associated with the Service. The IIIF Image API is an example of a Service, as are the Auth API services. Known types of Service are registered in the Service Registry. -A UnitValue expresses a quantity through a numerical value and associated unit of measurement. +__Properties__
+A Service _MUST_ have the following properties: [id](#id), and [type](#type).

+A Service _SHOULD_ have the following properties: [label](#label), [profile](#profile).

+A Service _MAY_ have the following properties: [service](#service).

+Services will also have specific requirements as to additional properties based on the type of service. +{: .note} -`"type": "UnitValue"` +#### Unit Value + +> `"type": "UnitValue"` +A UnitValue expresses a quantity through a numerical value and associated unit of measurement. From 451563df18a00ecef9f059527409826df802076d Mon Sep 17 00:00:00 2001 From: Rob Sanderson Date: Thu, 29 May 2025 09:54:32 -0400 Subject: [PATCH 084/130] More work on classes --- source/presentation/4.0/model.md | 55 ++++++++++++++++++++++++++++++-- 1 file changed, 52 insertions(+), 3 deletions(-) diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index a441cc400..df8086f87 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -621,7 +621,7 @@ __Properties__
Perspective Cameras _SHOULD_ have the following additional properties: [fieldOfView](#fieldOfView). {: .note} - +{% include api/code_header.html %} ```json { "id": "https://example.org/iiif/camera/2", @@ -653,6 +653,7 @@ All Lights _MAY_ have the following properties: [label](#label). Ambient Light evenly illuminates all objects in the Scene, and does not have a direction or position. It does not have any new properties. The Light itself _MUST_ be added into the scene at a specific position, however this is only such that editing interfaces can render the object to the user. +{% include api/code_header.html %} ```json { "id": "https://example.org/iiif/light/1", @@ -673,6 +674,7 @@ __Properties__
Directional Lights _MAY_ have the following additional properties: [lookAt](#lookAt) {: .note} +{% include api/code_header.html %} ```json { "id": "https://example.org/iiif/light/2", @@ -688,6 +690,7 @@ Directional Lights _MAY_ have the following additional properties: [lookAt](#loo Point Lights emit in all directions from a single point within the Scene. +{% include api/code_header.html %} ```json { "id": "https://example.org/iiif/light/3", @@ -712,6 +715,7 @@ Spot Lights _SHOULD_ have the following additional properties: [angle](#angle) `"type": "UnitValue"` -A UnitValue expresses a quantity through a numerical value and associated unit of measurement. +A UnitValue expresses a quantity through a numerical value and associated unit of measurement. The unit _MUST_ be drawn from the +__Properties__
+A Unit Value _MUST_ have the following properties: [id](#id), [type](#type), [value](#value), and [unit](#unit).

+A Unit Value _MAY_ have the following properties: [label](#label). +{: .note} + +{% include api/code_header.html %} +```json +{ + "id": "https://example.org/iiif/unit/2", + "type": "UnitValue", + "value": 1.0, + "unit": "m" +} +``` + ## Properties From c1756b263dad492d69ff9db15506bb02f3d87be8 Mon Sep 17 00:00:00 2001 From: Rob Sanderson Date: Thu, 29 May 2025 10:10:30 -0400 Subject: [PATCH 085/130] Hit commit too quickly :) --- source/presentation/4.0/model.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index df8086f87..2b10f7a94 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -937,8 +937,7 @@ Services will also have specific requirements as to additional properties based > `"type": "UnitValue"` -A UnitValue expresses a quantity through a numerical value and associated unit of measurement. The unit _MUST_ be drawn from the - +A UnitValue expresses a quantity through a numerical value and associated unit of measurement. The value of `unit` _MUST_ be drawn from the list of possible units, or a registered extension. __Properties__
A Unit Value _MUST_ have the following properties: [id](#id), [type](#type), [value](#value), and [unit](#unit).

From 86b0492e6c9ec20fd0808b1a55d631bebf7acb51 Mon Sep 17 00:00:00 2001 From: Tom Crane Date: Mon, 2 Jun 2025 09:19:22 +0100 Subject: [PATCH 086/130] Apply suggestions from code review Co-authored-by: Julie Winchester --- source/presentation/4.0/index.md | 2 +- source/presentation/4.0/model.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index bb3c2b938..4c4a65f8d 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -1482,7 +1482,7 @@ In many cases, the dimensions of a Canvas, or the pixel density of a photograph, The `spatialScale` property of a Canvas or Scene provides a corresponding real-world scale for a unit of the Canvas or Scene coordinate system, allowing clients to provide scale information to users, for example by an on-screen virtual ruler. In a 2-up viewer, a client could scale two views to convey the true relative sizes of two objects. -The value of `spatialScale` is a `UnitValue` (ref) that always has the value "m", i.e., metres. If source size metadata is machine readable (or parse-able) in other measurement systems (e.g., feet and inches) then it should be converted to metres for use in `spatialScale`. Publishers may wish to present the original given measure (e.g., from catalogue metadata) in a `metadata` field for context. +The value of `spatialScale` is a `UnitValue` (ref) that has as a value a length unit. This specification defines only one length unit, "m", i.e., metres, though others may be defined externally as an [extension][prezi30-ldce]. If source size metadata is machine readable (or parse-able) in other measurement systems (e.g., feet and inches) then it should be converted to metres for use in `spatialScale`. Publishers may wish to present the original given measure (e.g., from catalogue metadata) in a `metadata` field for context. The Presentation API also offers a corresponding `temporalScale` property for the `duration` dimension of a Container, when 1 second in the Container does not correspond to 1 second of real time. This is useful for speeded-up or slowed-down audio or video. diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index 9a837fc8b..67170c1c0 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -1852,7 +1852,7 @@ The value _MUST_ be an array of JSON objects. Each object _MUST_ be a service re ### spatialScale {: #spatialScale} -A single UnitValue that defines a real-world scale factor for the coordinate units of a Canvas or Scene. For a Canvas, this defines the physical distance between adjacent units horizontally and vertically. A Canvas with a `width` of 5000 and a `spatialScale` with `value` 0.00008 represents a physical space 0.4 metres wide. For a Scene, this defines the physical distance corresponding to the XYZ coordinate units, or in other words, the physical distance length of a unit vector in the 3D coordinate space. The value of `unit` _MUST_ always be `m`, i.e., metres. +A single UnitValue that defines a real-world scale factor for the coordinate units of a Canvas or Scene. For a Canvas, this defines the physical distance between adjacent units horizontally and vertically. A Canvas with a `width` of 5000 and a `spatialScale` with `value` 0.00008 represents a physical space 0.4 metres wide. For a Scene, this defines the physical distance corresponding to the XYZ coordinate units, or in other words, the physical distance length of a unit vector in the 3D coordinate space. The value of `unit` _MUST_ be a length unit. In this specification, the only length unit defined is `m`, i.e., metres. Unless other values are defined externally as an [extension][prezi30-ldce], the value of `unit` _SHOULD_ always be `m`. {% include api/code_header.html %} From 7cb83025c6332655927aa1d1defe3c5c4cd4ce4a Mon Sep 17 00:00:00 2001 From: Tom Crane Date: Mon, 2 Jun 2025 09:20:21 +0100 Subject: [PATCH 087/130] Apply suggestions from code review Co-authored-by: Julie Winchester --- source/presentation/4.0/model.md | 24 +++++++++++------------- 1 file changed, 11 insertions(+), 13 deletions(-) diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index 67170c1c0..9b5ceeb44 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -1859,12 +1859,11 @@ A single UnitValue that defines a real-world scale factor for the coordinate uni ``` json-doc { "type": "Scene", - - "spatialScale": { - "type": "UnitValue", - "value": 22.0, - "unit": "m" - } + "spatialScale": { + "type": "UnitValue", + "value": 22.0, + "unit": "m" + } } ``` @@ -1990,19 +1989,18 @@ The value _MUST_ be a JSON object, which _MUST_ have the `id` and `type` propert ### temporalScale {: #temporalScale} -A single UnitValue that defines a multiplier or scale factor for the `duration` property of a Container, indicating that one second in "Container time" represents some other real world duration. A Canvas with a `duration` of 450 seconds and a `temporalScale` with `value` 1000 represents a real-world duration of 450,000 seconds (5.2 days), for example a time-lapse video of a growing plant. The value of `unit` _MUST_ always be `s`, i.e., seconds. +A single UnitValue that defines a multiplier or scale factor for the `duration` property of a Container, indicating that one second in "Container time" represents some other real world duration. A Canvas with a `duration` of 450 seconds and a `temporalScale` with `value` 1000 represents a real-world duration of 450,000 seconds (5.2 days), for example a time-lapse video of a growing plant. The value of `unit` _MUST_ be a time unit. In this specification, the only time unit defined is `s`, i.e., seconds. Unless other values are defined externally as an [extension][prezi30-ldce], the value of `unit` _SHOULD_ always be `s`. {% include api/code_header.html %} ``` json-doc { "type": "Canvas", - - "temporalScale": { - "type": "UnitValue", - "value": 1000, - "unit": "s" - } + "temporalScale": { + "type": "UnitValue", + "value": 1000, + "unit": "s" + } } ``` From bfbe5a0ee24484d7fa6da9b01eee8a566cea48e0 Mon Sep 17 00:00:00 2001 From: tomcrane Date: Mon, 2 Jun 2025 09:20:51 +0100 Subject: [PATCH 088/130] physical dims --- source/presentation/4.0/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index bb3c2b938..6f01c5478 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -1478,7 +1478,7 @@ See above... ## Conveying Physical Dimensions -In many cases, the dimensions of a Canvas, or the pixel density of a photograph, are not necessarily related to the real-world size of the object they show. A large wall painting and a tiny miniature may both be conveyed by 20 megapixel source images on a 4000 by 3000 unit Canvas. But it can be important to know how big something is or if there is a relationship between pixel density and physical length, especially when comparing objects together. An X-Ray image may have a tight expectation for the physical distance between two adjacent pixels, or a scanned 3D model may be constructed such that each 3D coordinate unit corresponds to one meter of physical distance. +In many cases, the dimensions of a Canvas, or the pixel density of a photograph, are not necessarily related to the real-world size of the object they show. A large wall painting and a tiny miniature may both be conveyed by 20 megapixel source images on a 4000 by 3000 unit Canvas. But it can be important to know how big something is or if there is a relationship between pixel density and physical length, especially when comparing objects together. Each pixel in an image may correspond precisely to a physical area in the real world, or a scanned 3D model may be constructed such that each 3D coordinate unit corresponds to one meter of physical distance. The `spatialScale` property of a Canvas or Scene provides a corresponding real-world scale for a unit of the Canvas or Scene coordinate system, allowing clients to provide scale information to users, for example by an on-screen virtual ruler. In a 2-up viewer, a client could scale two views to convey the true relative sizes of two objects. From 2c0ea1292c0a43a91a1c405d7791dd3cb07a5936 Mon Sep 17 00:00:00 2001 From: tomcrane Date: Mon, 2 Jun 2025 09:24:59 +0100 Subject: [PATCH 089/130] metres --- source/presentation/4.0/index.md | 6 +++--- source/presentation/4.0/model.md | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index fe5202e6f..e6031f60d 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -1478,15 +1478,15 @@ See above... ## Conveying Physical Dimensions -In many cases, the dimensions of a Canvas, or the pixel density of a photograph, are not necessarily related to the real-world size of the object they show. A large wall painting and a tiny miniature may both be conveyed by 20 megapixel source images on a 4000 by 3000 unit Canvas. But it can be important to know how big something is or if there is a relationship between pixel density and physical length, especially when comparing objects together. Each pixel in an image may correspond precisely to a physical area in the real world, or a scanned 3D model may be constructed such that each 3D coordinate unit corresponds to one meter of physical distance. +In many cases, the dimensions of a Canvas, or the pixel density of a photograph, are not necessarily related to a real-world size of the object they show. A large wall painting and a tiny miniature may both be conveyed by 20 megapixel source images on a 4000 by 3000 unit Canvas. But it can be important to know how big something is or if there is a relationship between pixel density and physical length, especially when comparing objects together. Each pixel in an image may correspond precisely to a physical area, allowing measurement of real world distances from the image. A scanned 3D model may be constructed such that each 3D coordinate unit corresponds to one meter of physical distance. The `spatialScale` property of a Canvas or Scene provides a corresponding real-world scale for a unit of the Canvas or Scene coordinate system, allowing clients to provide scale information to users, for example by an on-screen virtual ruler. In a 2-up viewer, a client could scale two views to convey the true relative sizes of two objects. -The value of `spatialScale` is a `UnitValue` (ref) that has as a value a length unit. This specification defines only one length unit, "m", i.e., metres, though others may be defined externally as an [extension][prezi30-ldce]. If source size metadata is machine readable (or parse-able) in other measurement systems (e.g., feet and inches) then it should be converted to metres for use in `spatialScale`. Publishers may wish to present the original given measure (e.g., from catalogue metadata) in a `metadata` field for context. +The value of `spatialScale` is a `UnitValue` (ref) that has as a value a length unit. This specification defines only one length unit, "m", i.e., meters, though others may be defined externally as an [extension][prezi30-ldce]. If source size metadata is machine readable (or parse-able) in other measurement systems (e.g., feet and inches) then it should be converted to meters for use in `spatialScale`. Publishers may wish to present the original given measure (e.g., from catalogue metadata) in a `metadata` field for context. The Presentation API also offers a corresponding `temporalScale` property for the `duration` dimension of a Container, when 1 second in the Container does not correspond to 1 second of real time. This is useful for speeded-up or slowed-down audio or video. -An extreme example of both physical dimension properties together is a Canvas showing an animation of continental drift over the course of Earth history, where the spatialScale could convey that each Canvas unit is several thousand metres, and each second of the Canvas `duration` is several million years. +An extreme example of both physical dimension properties together is a Canvas showing an animation of continental drift over the course of Earth history, where the spatialScale could convey that each Canvas unit is several thousand meters, and each second of the Canvas `duration` is several million years. diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index 9b5ceeb44..af041e126 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -1852,7 +1852,7 @@ The value _MUST_ be an array of JSON objects. Each object _MUST_ be a service re ### spatialScale {: #spatialScale} -A single UnitValue that defines a real-world scale factor for the coordinate units of a Canvas or Scene. For a Canvas, this defines the physical distance between adjacent units horizontally and vertically. A Canvas with a `width` of 5000 and a `spatialScale` with `value` 0.00008 represents a physical space 0.4 metres wide. For a Scene, this defines the physical distance corresponding to the XYZ coordinate units, or in other words, the physical distance length of a unit vector in the 3D coordinate space. The value of `unit` _MUST_ be a length unit. In this specification, the only length unit defined is `m`, i.e., metres. Unless other values are defined externally as an [extension][prezi30-ldce], the value of `unit` _SHOULD_ always be `m`. +A single UnitValue that defines a real-world scale factor for the coordinate units of a Canvas or Scene. For a Canvas, this defines the physical distance between adjacent units horizontally and vertically. A Canvas with a `width` of 5000 and a `spatialScale` with `value` 0.00008 represents a physical space 0.4 meters wide. For a Scene, this defines the physical distance corresponding to the XYZ coordinate units, or in other words, the physical distance length of a unit vector in the 3D coordinate space. The value of `unit` _MUST_ be a length unit. In this specification, the only length unit defined is `m`, i.e., meters. Unless other values are defined externally as an [extension][prezi30-ldce], the value of `unit` _SHOULD_ always be `m`. {% include api/code_header.html %} From 3796dfcadb31e69b60a5c63202a5d9d74375512a Mon Sep 17 00:00:00 2001 From: tomcrane Date: Mon, 2 Jun 2025 09:50:28 +0100 Subject: [PATCH 090/130] clarify scale units --- source/presentation/4.0/model.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index 13fa01084..bf41cdb13 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -276,7 +276,7 @@ A Timeline _MUST_ have the following additional properties: [duration](#duration > `"type": "Canvas"` -A Canvas is a Container that represents a particular rectangular 2 dimensional view of the object and has content resources associated with it or with parts of it. This aspect ratio is defined by the `height` and `width` properties. The values of these properties are not pixels, but arbitrary units into which pixel-based resources can be scaled. A Canvas _MAY_ also have a duration, given in the `duration` property, allowing audio and video to be correctly positioned in time as well as the 2 dimensional space. +A Canvas is a Container that represents a particular rectangular 2 dimensional view of the object and has content resources associated with it or with parts of it. This aspect ratio is defined by the `height` and `width` properties. The values of these properties are not pixels, but arbitrary square units into which pixel-based resources can be scaled. A Canvas _MAY_ also have a duration, given in the `duration` property, allowing audio and video to be correctly positioned in time as well as the 2 dimensional space. __Properties__
A Canvas _MUST_ have the following additional properties: [height](#height), and [width](#width).

@@ -292,7 +292,7 @@ A Scene is a Container that represents an infinitely large three-dimensional spa diagram of Right handed cartesian coordinate system -The axes of the coordinate system are measured in arbitrary units and these units do not necessarily correspond to any physical unit of measurement, unless `spatialScale` is supplied. +The axes of the coordinate system are measured in arbitrary units. All axes use the same unit scaling and do not necessarily correspond to any physical unit of measurement, unless `spatialScale` is supplied. All resources that can be added to a Scene have an implicit (e.g. Lights, Cameras) or explicit (e.g. Models, Scenes), local coordinate space. @@ -2048,7 +2048,7 @@ The value _MUST_ be an array of JSON objects. Each object _MUST_ be a service re ### spatialScale {: #spatialScale} -A single UnitValue that defines a real-world scale factor for the coordinate units of a Canvas or Scene. For a Canvas, this defines the physical distance between adjacent units horizontally and vertically. A Canvas with a `width` of 5000 and a `spatialScale` with `value` 0.00008 represents a physical space 0.4 meters wide. For a Scene, this defines the physical distance corresponding to the XYZ coordinate units, or in other words, the physical distance length of a unit vector in the 3D coordinate space. The value of `unit` _MUST_ be a length unit. In this specification, the only length unit defined is `m`, i.e., meters. Unless other values are defined externally as an [extension][prezi30-ldce], the value of `unit` _SHOULD_ always be `m`. +A single UnitValue that defines a real-world scale factor for the coordinate units of a Canvas or Scene. For a Canvas, this defines the physical distance corresponding to the length of a single Canvas coordinate unit. A Canvas with a `width` of 5000 and a `spatialScale` with `value` 0.00008 represents a physical space 0.4 meters wide. For a Scene, this defines the physical distance corresponding to the XYZ coordinate units, or in other words, the physical distance length of a unit vector in the 3D coordinate space. The value of `unit` _MUST_ be a length unit. In this specification, the only length unit defined is `m`, i.e., meters. Unless other values are defined externally as an [extension][prezi30-ldce], the value of `unit` _SHOULD_ always be `m`. {% include api/code_header.html %} From 6e6dc93e3c39b8193dc7967b0dc4e2cbf8e715ae Mon Sep 17 00:00:00 2001 From: tomcrane Date: Mon, 2 Jun 2025 11:17:59 +0100 Subject: [PATCH 091/130] Leeds tweaks --- source/presentation/4.0/index.md | 391 +++++++++++++---------------- source/presentation/4.0/model.md | 2 +- source/presentation/4.0/scratch.md | 6 + 3 files changed, 181 insertions(+), 218 deletions(-) create mode 100644 source/presentation/4.0/scratch.md diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index e873827dd..647ad7b84 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -35,7 +35,7 @@ hero: image: '' --- -## Status of this Document +# Status of this Document {:.no_toc} __This Version:__ {{ page.major }}.{{ page.minor }}.{{ page.patch }}{% if page.pre != 'final' %}-{{ page.pre }}{% endif %} @@ -51,57 +51,57 @@ __Previous Version:__ [3.0][prezi30] ---- -## Introduction +# Introduction The purpose of the IIIF Presentation API specification is to provide a [model](model) and JSON serialization format of that model. -It provides a document format - the IIIF Manifest - for cultural heritage organizations (and anyone else) to publish standardized, interoperable objects. This allows compatible software such as viewers and annotation tools to load and present complex digital objects on the web. +It provides a document format - the IIIF Manifest - for cultural heritage organizations (and anyone else) to present objects in a standardized, interoperable fashion. This allows compatible software such as viewers and annotation tools to load and present complex digital objects on the web from thousands of different providers. -The specification is solely concerned with presentation - providing enough information to render an object in compatible software, and leaving the meaning of the object to external descriptive metadata standards. +**If you have existing images, audio, video and models on the web, you can easily provide IIIF Manifests for them by publishing the appropriate JSON documents.** -_Presentation, the clue is in the name_ +The IIIF Presentation API is concerned with enabling user experiences - providing enough information to present objects in compatible software, and leaving the meaning of the objects to external descriptive metadata standards. -This specification is presented in two parts. This document acts as an introduction to the specification through a set of typical (but non-exhaustive) use cases. The model [model](model) provides the formal specification of the terms used in this introduction. +This document acts as an introduction to the specification through a set of typical (but non-exhaustive) use cases. The model [model](model) document provides the formal specification of the terms used in this introduction. -### IIIF Use cases +## IIIF Use cases -1. **Artwork** - a IIIF Manifest that represents a painting, comprising a single image and accompanying display information. -2. **Book** - a IIIF Manifest that represents a digitized bound volume made up many separate images in order. The IIIF model provides structural elements to indicate the chapters. The text of the book is made available in machine-readable form as Web Annotations. -3. **45 Single** - a IIIF Manifest that represents the digitized audio from the two sides of a vinyl 7 inch record. -4. **Movie** - a IIIF Manifest that represents the digitized video of a film. A transcript of the audio is provided as Web Annotations, and additional machine-readable files provide subtitles and captions. -5. **Simple 3D Model** - a IIIF Manifest that publishes a single 3D model. -6. **Complex Scene** - a IIIF Manifest that publishes a complex 3D scene comprising multiple models, lights and cameras. -7. **Periodical** - a IIIF Collection that provides multiple IIIF child IIIF Collections and Manifests, representing the publication run of a newspaper over many years. The IIIF model provides structural elements to indicate individual articles and other elements. -8. **Storytelling in 3D** - a IIIF Manifest that defines a sequence of states in a complex scene for the purposes of guiding a user through a particular experience. +1. **Artwork** - a Manifest that represents a painting, comprising a single image and accompanying display information. +2. **Book** - a Manifest that represents a digitized bound volume made up many separate images in order. The IIIF model provides structural elements to indicate the chapters. The text of the book is made available in machine-readable form as Web Annotations. +3. **45 Single** - a Manifest that represents the digitized audio from the two sides of a vinyl 7 inch record. +4. **Movie** - a Manifest that represents the digitized video of a film. A transcript of the audio is provided as Web Annotations, and additional machine-readable files provide subtitles and captions. +5. **Simple 3D Model** - a Manifest that publishes a single 3D model. +6. **Complex Scene** - a Manifest that publishes a complex 3D scene comprising multiple models, lights and cameras. +7. **Periodical** - a IIIF Collection that provides multiple child Collections and Manifests, representing the publication run of a newspaper over many years. The IIIF model provides structural elements to indicate individual articles and other elements. +8. **Storytelling in 3D** - a Manifest that defines a sequence of states in a complex scene for the purposes of guiding a user through a particular experience. 9. **Manuscript** - (integration) -These use case were chosen as a broad sample to introduce IIIF Concepts. Many more use cases are provided as recipes in the [IIIF Cookbook](link). +These use case were chosen as a broad sample to introduce IIIF concepts. Many more use cases are provided as recipes in the [IIIF Cookbook](link). -Consider diagrams +> TODO Consider diagrams -## Foundations +# Foundations -(needs updating) +This section is what you need to know to make sense of the examples that follow it.

Data Model

-### Manifests +## Manifests A Manifest is the primary unit of distribution of IIIF. Each Manifest usually describes how to present an object, such as a book, statue, music album or 3 dimensional scene. It is a JSON document that carries information needed for the client to present content to the user, such as a title and other descriptive information. The scope of what constitutes an object, and thus its Manifest, is up to the publisher of that Manifest. The Manifest contains sufficient information for the client to initialize itself and begin to display something quickly to the user. -The Manifest's `items` property is an ordered list of _Containers_ of _Content Resources_ (images, 3D models, audio, etc). Client software loads the Manifest and presents the Content Resources to the user in that order. +The Manifest's `items` property is an ordered list of _Containers_ of _Content Resources_ (images, 3D models, audio, etc). Client software loads the Manifest and presents each Container's Content Resources. The client software also presents user interface controls to navigate the list of Content Containers. Manifests have descriptive, technical and linking properties. The required properties of Manifests are `id`, `type`, `items` and `label`. Other commonly used properties include `summary`, `metadata`, `rights`, `thumbnail`, `homepage` and `provider`. (👀) [Model Documentation](model/#manifest) -```json +```jsonc { "@context": "http://iiif.io/api/presentation/4/context.json", "id": "https://iiif.io/api/cookbook/recipe/0001-mvm-image/manifest.json", @@ -116,7 +116,8 @@ Manifests have descriptive, technical and linking properties. The required prope ``` -### Containers + +## Containers A Container is a frame of reference that allows the relative positioning of Content Resources, a concept borrowed from standards like PDF and HTML, or applications like Photoshop and PowerPoint, where an initially blank display surface has images, video, text and other content "painted" on to it. The frame is defined by a set of dimensions, with different types of Container having different dimensions. This specification defines three sub-classes of Container: Timeline (which only has a duration), Canvas (which has bounded height and width, and may have a duration), and Scene (which has infinite height, width and depth, and may have a duration). @@ -124,109 +125,33 @@ The required properties of all Containers are `id`, and `type`. Most Containers The defined Container types are: -#### Timeline +### Timeline A Container that represents a bounded temporal range, without any spatial coordinates. It is typically used for audio-only content. Timelines have an additional required property of `duration`, which gives the extent of the Timeline as a floating point number of seconds. - -#### Canvas - -A Container that represents a bounded, two-dimensional space, optionally with a bounded temporal range. Canvases are typically used for Image and Video content. - -Canvases have two additional required properties: `height` and `width`, which give the spatial extent as unitless integers. Canvases may also have the `duration` property in the same manner as Timelines. - - -#### Scene - -A Container that represents a boundless three-dimensional space, optionally with a bounded temporal range. Scenes are typically used for rendering 3D models, and can additionally have Cameras and Lights. - -Scenes may also have the `duration` property in the same manner as Timelines. - -(👀) [Model Documentation](model/#containers) - ```json { - "@context": "http://iiif.io/api/presentation/4/context.json", - "id": "https://iiif.io/api/presentation/examples/manifest-with-containers", - "type": "Manifest", - "label": { - "en": [ "A Manifest with all three types of Container" ] - }, + "id": "https://example.org/iiif/presentation/examples/manifest-with-containers/timeline", + "type": "Timeline", + "duration": 32.76, "items": [ { - "id": "https://iiif.io/api/presentation/examples/manifest-with-containers/timeline", - "type": "Timeline", - "duration": 32.76, - "items": [ - { - "id": "https://iiif.io/api/presentation/examples/manifest-with-containers/page/p1", - "type": "AnnotationPage", - "items": [ - { - "id": "https://iiif.io/api/presentation/examples/manifest-with-containers/annotation/t1", - "type": "Annotation", - "motivation": "painting", - "body": { - "id": "https://iiif.io/api/presentation/example-content-resources/audio/clip.mp3", - "type": "Audio", - "format": "audio/mp3", - "duration": 32.76, - }, - "target": "https://iiif.io/api/presentation/examples/manifest-with-containers/timeline" - } - ] - } - ] - }, - { - "id": "https://iiif.io/api/presentation/examples/manifest-with-containers/canvas", - "type": "Canvas", - "width": 12000, - "height": 9000, - "items": [ - { - "id": "https://iiif.io/api/presentation/examples/manifest-with-containers/page/p2", - "type": "AnnotationPage", - "items": [ - { - "id": "https://iiif.io/api/presentation/examples/manifest-with-containers/annotation/c1", - "type": "Annotation", - "motivation": "painting", - "body": { - "id": "https://iiif.io/api/presentation/example-content-resources/image/painting.jpg", - "type": "Image", - "format": "image/jpeg", - "width": 4000, - "height": 3000 - }, - "target": "https://iiif.io/api/presentation/examples/manifest-with-containers/canvas" - } - ] - } - ] - }, - { - "id": "https://iiif.io/api/presentation/examples/manifest-with-containers/scene", - "type": "Scene", + "id": "https://example.org/iiif/presentation/examples/manifest-with-containers/page/p1", + "type": "AnnotationPage", "items": [ { - "id": "https://iiif.io/api/presentation/examples/manifest-with-containers/page/p3", - "type": "AnnotationPage", - "items": [ - { - "id": "https://iiif.io/api/presentation/examples/manifest-with-containers/annotation/s1", - "type": "Annotation", - "motivation": "painting", - "body": { - "id": "https://iiif.io/api/presentation/example-content-resources/models/astronaut.glb", - "type": "Model", - "format": "model/gltf-binary" - }, - "target": "https://iiif.io/api/presentation/examples/manifest-with-containers/scene" - } - ] + "id": "https://example.org/iiif/presentation/examples/manifest-with-containers/annotation/t1", + "type": "Annotation", + "motivation": [ "painting" ], + "body": { + "id": "https://iiif.io/api/presentation/example-content-resources/audio/clip.mp3", + "type": "Audio", + "format": "audio/mp3", + "duration": 32.76 + }, + "target": "https://example.org/iiif/presentation/examples/manifest-with-containers/timeline" } ] } @@ -234,48 +159,27 @@ Scenes may also have the `duration` property in the same manner as Timelines. } ``` -The above Manifest has three Containers, one of each type. While contrived, it is still valid and the expected user experience would be for a viewer to begin on the Timeline Container, presenting UI for the user to play the audio. The viewer would also present navigation elements to move to the next Container (the Canvas) or otherwise navigate the available Content Containers. Usually, even when a Manifest has a large number of Containers in its `items` property, they are of the same type (e.g., a 100 page book is modelled as a Manifest with 100 Canvases, each bearing an image of one page). But it is not a requirement that all Containers in a Manifest must be of the same type. - -In each of the three Containers, an **Annotation** links the Container to a Content Resource. The Content Resource is _painted_ into the Container by an Annotation whose `target` property is the `id` of the Container. In all three simple cases here the `target` property is the the `id` of the Container with no further qualification. - - - -### Annotations - -IIIF uses the concept of _Annotation_ to link resources together from around the web. This specification uses a World Wide Web Consortium (W3C) standard for this called the [Web Annotation Data Model][org-web-anno]. This is a structured linking mechanism useful for making comments about Content Resources, but IIIF's primary use of it is to associate the images, audio and other Content Resources with their Containers for presentation. - -Different uses of Annotation are distinguished through their `motivation` property. This specification defines a value for `motivation` called `painting` for associating Content Resources with Containers, which this specification calls a Painting Annotation. The verb "paint" is also used to refer to the associating of a Content Resource with a Container by a Painting Annotation. This is from the notion of painting onto a canvas, a metaphor borrowed from art and used for image-based digital applications, and expanded by IIIF into "painting" any Content Resource into a Container of any number of dimensions. - -In the example Manifest above the first Container is a Timeline. One content resource, an MP3 file, is associated with the Timeline via a Painting Annotation for its entire duration. Typically the duration of the Timeline matches the duration of its content. This is the simplest time-based use case. The `target` property of the Painting Annotation is the whole Timeline, because it is simply the `id` of the Timeline without further qualification. In this simple case, playing the Timeline is the same as playing the MP3. - -The second Container is a Canvas, representing a 2D surface. In this case the Canvas represents an artwork, and there is no duration property. The content resource, a JPEG image of the artwork, is associated with the Canvas via a Painting Annotation. The unit integer coordinates of the Canvas (12000 x 9000) are not the same as the pixel dimensions of the JPEG image (4000 x 3000), but they are proportional - the Canvas has a 4:3 landscape aspect ratio, and so does the JPEG image. The `target` property of the Annotation is the Canvas `id`, unqualified by any particular region; this is taken to mean the content (the image) should fill the Canvas completely. As the Canvas and the image are the same aspect ratio, no distortion will occur. This approach allows the current image to be replaced by a higher resolution image in future, on the same Canvas. The Canvas dimensions establish a coordinate system for _painting annotations_ and other kinds of annotation that link content with the Canvas; they are not pixels of images. - -The third Container is a Scene. Unlike a Canvas, it is not a bounded spatial extent, but may be a bounded temporal extent if it has the optional duration property. It still establishes a coordinate space (x, y, z) but doesn't need any spatial properties to do so as it is always the same, infinite unbounded space. The Annotation paints the astronaut model into the Scene. As no further qualification is given, the astronaut model is placed at the (0,0,0) origin of the Scene. Later examples will show how to control the lighting and camera position(s) and properties, but this is not required; a IIIF viewer is expected to supply ambient light and a default camera position in the absence of specific values. - - -The same linking mechanism is also used in IIIF with other motivations for transcriptions, commentary, tags and other content. This provides a single, unified method for aligning content, and provides a standards-based framework for referencing parts of resources. As Annotations can be added later, it promotes a distributed system in which further content such as commentary can be aligned with the objects published on the web. - -The required properties of Annotations are `id`, `type`, `motivation`, and `target`. Most Annotations also have the `body` property. +### Canvas -The relationship between a Container and a painting annotation is not direct. Annotations are grouped within the `items` property of an Annotation Page, and the `items` property of the Container is a list of Annotation Pages. +A Container that represents a bounded, two-dimensional space, optionally with a bounded temporal range. Canvases are typically used for Image and Video content. -(👀) [Model Documentation](model/#annotations) +Canvases have two additional required properties: `height` and `width`, which give the spatial extent as integers. Canvases may also have the `duration` property in the same manner as Timelines. ```json { - "id": "https://iiif.io/api/presentation/examples/manifest-with-containers/canvas", + "id": "https://example.org/iiif/presentation/examples/manifest-with-containers/canvas", "type": "Canvas", "width": 12000, "height": 9000, "items": [ { - "id": "https://iiif.io/api/presentation/examples/manifest-with-containers/page/p2", + "id": "https://example.org/iiif/presentation/examples/manifest-with-containers/page/p2", "type": "AnnotationPage", "items": [ { - "id": "https://iiif.io/api/presentation/examples/manifest-with-containers/annotation/c1", + "id": "https://example.org/iiif/presentation/examples/manifest-with-containers/annotation/c1", "type": "Annotation", - "motivation": "painting", + "motivation": [ "painting" ], "body": { "id": "https://iiif.io/api/presentation/example-content-resources/image/painting.jpg", "type": "Image", @@ -283,7 +187,7 @@ The relationship between a Container and a painting annotation is not direct. An "width": 4000, "height": 3000 }, - "target": "https://iiif.io/api/presentation/examples/manifest-with-containers/canvas" + "target": "https://example.org/iiif/presentation/examples/manifest-with-containers/canvas" } ] } @@ -291,23 +195,76 @@ The relationship between a Container and a painting annotation is not direct. An } ``` -### Content Resources +### Scene -Content Resources are external web resources, including images, video, audio, 3D models, data, web pages or any other format. Typically these are the resources that will be "painted" onto a Container using a Painting Annotation. +A Container that represents a boundless three-dimensional space, optionally with a bounded temporal range. Scenes are typically used for rendering 3D models, and can additionally have Cameras and Lights. -The required properties of Content Resources are `id` and `type`. Other commonly used properties include `format`, and `width`, `height` and `duration` as appropriate to the Content Resource format. +Scenes may also have the `duration` property in the same manner as Timelines. -The Containers example also demonstrates that if you have existing content resources with web URIs - images, audio, video and models - you can quite easily publish IIIF Manifests for them by constructing the appropriate JSON around them and publishing the JSON documents. This requires careful consideration of the URI schemes for `id` properties of Containers and their Manifests to ensure they remain referenceable in the future. The choice of Timeline or Canvas dimensions (duration, width, height) can usually be derived simply from the content; the same duration as the audio or video, and the same unit Canvas dimensions as the image or video pixel dimensions, with the caveat that you should avoid low values for `width` and `height` (ref model). +```json +{ + "id": "https://example.org/iiif/presentation/examples/manifest-with-containers/scene", + "type": "Scene", + "items": [ + { + "id": "https://example.org/iiif/presentation/examples/manifest-with-containers/page/p3", + "type": "AnnotationPage", + "items": [ + { + "id": "https://example.org/iiif/presentation/examples/manifest-with-containers/annotation/s1", + "type": "Annotation", + "motivation": [ "painting" ], + "body": { + "id": "https://iiif.io/api/presentation/example-content-resources/models/astronaut.glb", + "type": "Model", + "format": "model/gltf-binary" + }, + "target": "https://example.org/iiif/presentation/examples/manifest-with-containers/scene" + } + ] + } + ] +} +``` + +[👀 Model Documentation](model/#containers) -#### Containers as Content Resources + +## Annotations + + +IIIF uses the concept of _Annotation_ to link resources together from around the web. This specification uses a World Wide Web Consortium (W3C) standard for this called the [Web Annotation Data Model][org-web-anno]. This is a structured linking mechanism useful for making comments about Content Resources, but IIIF's primary use of it is to associate the images, audio and other Content Resources with their Containers for presentation. + +In each of the three Containers above, an **Annotation** links the Container to a Content Resource. The Content Resource in the `body` property is _painted_ into the Container by an Annotation whose `target` property is the `id` of the Container. In all three simple cases here the `target` property is the `id` of the Container with no further qualification. + +Different uses of Annotation are distinguished through their `motivation` property. This specification defines a value for `motivation` called `painting` for associating Content Resources with Containers, which this specification calls a Painting Annotation. The verb "paint" is also used to refer to the associating of a Content Resource with a Container by a Painting Annotation. This is from the notion of painting onto a canvas, a metaphor borrowed from art and used for image-based digital applications, and expanded by IIIF into "painting" any Content Resource into a Container of any number of dimensions. + +The same linking mechanism is also used in IIIF with other motivations for transcriptions, commentary, tags and other content. This provides a single, unified method for aligning content, and provides a standards-based framework for referencing parts of resources. As Annotations can be added later, it promotes a distributed system in which further content such as commentary can be aligned with the objects published on the web. + +Annotations are grouped within the `items` property of an Annotation Page, and the `items` property of the Container is a list of Annotation Pages. This allows consistent grouping of Annotations when required. + +(👀) [Model Documentation](model/#annotations) + + +## Content Resources + +Content Resources are external web resources, including images, video, audio, 3D models, data, web pages or any other format. Typically these are the resources that will be painted into a Container using a Painting Annotation. + +In addition to the required properties `id` and `type`, other commonly used properties include `format`, and `width`, `height` and `duration` as appropriate to the Content Resource format. + +If you have existing content resources with web URIs - images, audio, video and models - you can publish IIIF Manifests for them by constructing the appropriate JSON around them and publishing the JSON documents. This requires careful consideration of the URI schemes for `id` properties of Containers and their Manifests to ensure they remain referenceable in the future. The choice of Timeline or Canvas dimensions (duration, width, height) can usually be derived simply from the content; the same duration as the audio or video, and the same unit Canvas dimensions as the image or video pixel dimensions, with the caveat that you should avoid low values for `width` and `height` (ref model). + +(👀) [Model Documentation](model/#contentresources) + +### Containers as Content Resources Containers may also be treated as Content Resources and painted into other Containers. This allows rich composition of content, such as painting a Canvas bearing a Video into a Scene, or painting a 3D model along with its associated Lights into an encompassing Scene. -#### Referencing Parts of Resources +### Referencing Parts of Resources A common requirement is to refer to only part of a resource, either a Container or a Content Resource. There are two primary methods for achieving this: adding a fragment to the end of the URI for the resource, or creating a Specific Resource that describes the method for selecting the desired part. -##### Fragments +#### Fragments Parts of resources on the Web are identified using URIs with a fragment component that both describes how to select the part from the resource, and, as a URI, also identifies it. In HTML this is frequently used to refer to part of the web page, called an anchor. The URI with the fragment can be used in place of the URI without the fragment in order to refer to this part. @@ -315,7 +272,7 @@ There are different types of fragment based on the format of the resource. The m ```json { - "id": "https://iiif.io/api/presentation/examples/manifest-with-containers/comments/c1", + "id": "https://example.org/iiif/presentation/examples/manifest-with-containers/comments/c1", "type": "Annotation", "motivation": "commenting", "body": { @@ -324,14 +281,14 @@ There are different types of fragment based on the format of the resource. The m "language": "en", "format": "text/plain" }, - "target": "https://iiif.io/api/presentation/examples/manifest-with-containers/canvas#xywh=6050,3220,925,1250" + "target": "https://example.org/iiif/presentation/examples/manifest-with-containers/canvas#xywh=6050,3220,925,1250" } ``` Here the Canvas `id` from the earlier example is still the `target` of an Annotation, but it has been qualified to a specific region of that Canvas by a Fragment Selector `#xywh=6050,3220,925,1250`. Note that the x, y, w, and h are in the Canvas coordinate space, not the pixel dimensions space. This annotation has no knowledge of or dependency on the particular image we painted onto the Canvas; we could replace that image with one of a different, higher resolution without affecting this annotation or the region of the Canvas it targets. -##### Specific Resource +#### Specific Resource URIs with fragments are insufficient for complex referencing, like circular regions or arbitrary text spans, and do not support other useful features such as describing styling or transformation. The Web Annotation Data Model introduces a class called `SpecificResource` that represents the resource in a specific context or role, which IIIF uses to describe these more complex requirements. The Specific Resource then identifies the part, and the description of how to extract it is given as an instance of a `Selector` class associated with it. @@ -341,7 +298,7 @@ The required properties of Specific Resources are `id`, `type`, and `source`. Ot ```json { - "id": "https://iiif.io/api/presentation/examples/manifest-with-containers/comments/c1", + "id": "https://example.org/iiif/presentation/examples/manifest-with-containers/comments/c1", "type": "Annotation", "motivation": "commenting", "body": { @@ -353,7 +310,7 @@ The required properties of Specific Resources are `id`, `type`, and `source`. Ot "target": { "type": "SpecificResource", "source": { - "id": "https://iiif.io/api/presentation/examples/manifest-with-containers/canvas", + "id": "https://example.org/iiif/presentation/examples/manifest-with-containers/canvas", "type": "Canvas" }, "selector": { @@ -366,9 +323,9 @@ The required properties of Specific Resources are `id`, `type`, and `source`. Ot -## Image Content +# Image Content -### Use Case 1: Artwork +## Use Case 1: Artwork This example is a Manifest with one Canvas, with an image of an artwork "painted" onto the Canvas. It demonstrates the use of the common descriptive properties `label` for the title of the artwork, `metadata` for additional information to display to the user, `summary` for a brief description of the artwork, `rights` to assert a rights statement or license from a controlled vocabulary, `homepage` to link to the artwork's specific web page, `thumbnail` to provide a small image to stand for the Manifest, and `provider` to give information about the publisher of the Manifest. @@ -380,10 +337,10 @@ Manifest -> items -> Canvas -> items -> AnnoPage -> items -> Anno -> body -> Ima label, summary, metadata, rights, provider, homepage, thumbnail ``` -Notice that the painting Annotation is a member of the `items` property of an Annotation Page. While in this case there is only one Annotation Page and one Annotation, the mechanism is needed for consistency when there are multiple Annotation Pages, and it allows for Annotation Pages in general to be separate resources on the web. +Notice that the Painting Annotation is a member of the `items` property of an Annotation Page. While in this case there is only one Annotation Page and one Annotation, the mechanism is needed for consistency when there are multiple Annotation Pages, and it allows for Annotation Pages in general to be separate resources on the web. -### Example 2: Book +## Example 2: Book This example is a Manifest with multiple Canvases, each of which represents a page of a book. It demonstrates the use of the `behavior` property to indicate to a client that the object is _paged_: this helps a client generate the correct user experience. The `viewingDirection` property indicates that the book is read left-to-right. In this case, the property is redundant as `left-to-right` is the default value. The Manifest has a `rendering` property linking to a PDF representation; typically a client would offer this as a download or "view as" option. The `start` property is used to tell a client to initialize the view on a particular Canvas, useful if the digitized work contains a large amount of irrelevant front matter or blank pages. The `requiredStatement` is a message that a client MUST show to the user when presenting the Manifest. @@ -394,9 +351,9 @@ requiredStatement, behavior, viewingDirection, (no Ranges), rendering - PDF vers -## Audio and Video +# Audio and Video -### Example: a 45 single with one Timeline per song/side +## Example: a 45 single with one Timeline per song/side This example is a Manifest with two Timelines, each of which represent a temporal extent during which a song is played. As in most cases, the Timeline `duration` is the same length as that of Content Resource painted into it. This example is a recording digitized from a 45 RPM 7 inch single. It demonstrates the use of `format` for the audio files' content type, `language` (One song is in English and one is in German), `behavior` with value "autoPlay" that tells a client to automatically advance to the second Timeline after playing the first, `annotations` that link to Annotation Pages of annotations with the motivation `supplementing` that provide the lyrics (one example is given afterwards) - and an `accompanyingContainer` that carries a picture of the single's cover that is shown while the songs are playing. @@ -412,7 +369,7 @@ duration, autoPlay, format, annotations (transcript), language, accompanyingCont ... ``` -### Example: a movie with subtitles +## Example: a movie with subtitles This example is a Manifest with one Canvas that represents the temporal extent of the movie (the Canvas `duration`) and its aspect ratio (given by the `width` and `height` of the Canvas). The example demonstrates the use of a `Choice` annotation body to give two alternative versions of the movie, the `timeMode` property ..., and `placeholderContainer` that provides a poster image to show in place of the video file before the user initiates playback. @@ -434,7 +391,7 @@ duration, behavior=autoplay, format, Choice of video 720p, 4K? (forward ref), ti Sometimes, two different formats derived from the same source may have slightly different durations, perhaps a few milliseconds out. What to do... -## 3D +# 3D 3D Content Resources are painted into Scenes. @@ -443,7 +400,7 @@ Scenes have infinite height (y axis), width (x axis) and depth (z axis), where 0 The positive y axis points upwards, the positive x axis points to the right, and the positive z axis points forwards (a [right-handed cartesian coordinate system](https://en.wikipedia.org/wiki/Right-hand_rule)). -### Example: Static 3D Model of a Spacesuit +## Example: Static 3D Model of a Spacesuit This example is a Manifest with a single Scene, with a single model of a space suit painted at the Scene's origin. @@ -472,7 +429,7 @@ backgroundColor: #000 point selector for positioning -### Example: 3D Model of a Chessboard +## Example: 3D Model of a Chessboard Chessboard is a Canvas with image more than one model @@ -488,7 +445,7 @@ interactionMode -### Merge the below into the examples or into model +## Merge the below into the examples or into model This (no units for scale) allows arbitrarily scaled models to be used, including very small or very large, without needing to deal with very small or very large values. If there is a correspondence to a physical scale, then this can be asserted using the physical dimensions pattern(fwd-ref-to-phys-dims). @@ -683,13 +640,13 @@ Todo add example ``` -### Give example of refinedBy ? e.g. WktSelector + Instant +## Give example of refinedBy ? e.g. WktSelector + Instant -### Scene-Specific Resources +## Scene-Specific Resources -#### Camera +### Camera A Camera provides a view of a region of the Scene's space from a particular position within the Scene; the client constructs a viewport into the Scene and uses the view of one or more Cameras to render that region. The size and aspect ratio of the viewport is client and device dependent. @@ -729,7 +686,7 @@ The first Camera defined and not hidden in a Scene is the default Camera used to -#### Light +### Light This specification defines four types of Light: @@ -767,7 +724,7 @@ If there are no Lights present within the Scene, then the viewer MUST add at lea -#### Transforms +### Transforms The Annotation with a Selector on the target can paint a resource at a point other than the origin, however it will be at its initial scale and rotation, which may not be appropriate for the scene that is being constructed. @@ -811,7 +768,7 @@ Transforms are only used in the Presentation API when the SpecificResource is th ``` -#### Relative Rotation +### Relative Rotation It is useful to be able to rotate a light or camera resource such that it is facing another object or point in the Scene, rather than calculating the angles within the Scene's coordinate space. This is accomplished with a property called `lookAt`, valid on DirectionalLight, SpotLight, and all Cameras. The value of the property is either a PointSelector, a WktSelector, the URI of an Annotation which paints something into the current Scene, or a Specific Resource with a selector identifying a point or region in an arbitrary container. @@ -829,7 +786,7 @@ This rotation happens after the resource has been added to the Scene, and thus a ``` -#### Excluding +### Excluding Just as a Scene may contain multiple Annotations with model, light, and camera resources, a single 3D model file may contain a collection of 3D resources, including model geometry, assemblages of lights, and/or multiple cameras, with some of these potentially manipulated by animations. When painting Scenes or models that themselves may contain groups of resources within a single Scene, it may not always be appropriate to include all possible cameras, lights, or other resources, and it may be desirable to opt not to import some of these resources. This is accomplished through the Annotation property `exclude`, which prevents the import of audio, lights, cameras, or animations from a particular Scene or model prior to the Annotation being painted into a Scene. When `exclude` is used, the excluded resource type should not be loaded into the Scene, and it is not possible to reactivate or turn on these excluded resources after loading. @@ -854,7 +811,7 @@ Painting a Scene into another while excluding import of several types of resourc -#### Nesting +### Nesting A Canvas can be painted into a Scene as an Annotation, but the 2D nature of Canvases requires special consideration due to important differences between Canvases and Scenes. A Canvas describes a bounded 2D space with finite `height` and `width` measured in pixels with a pixel origin at the top-left corner of the Canvas, while Scenes describe a boundless 3D space with x, y, and z axes of arbitrary coordinate units and a coordinate origin at the center of the space. It is important to note that in many cases the pixel scale used by a Canvas or a 2D image content resource will not be in proportion to the desired 3D coordinate unit scale in a Scene. @@ -888,20 +845,20 @@ When a Scene is nested into another Scene, the `backgroundColor` of the Scene to -## Annotations +# Annotations -### Comment Annotations +## Comment Annotations -### Choice of Alternative Resources +## Choice of Alternative Resources Example: Multi-spectral Images with Comments -### Embedded Content +## Embedded Content e.g., painting TextualBody on Canvas @@ -912,34 +869,34 @@ It is important to be able to position the textual body of an annotation within -### Non Rectangular Segments +## Non Rectangular Segments SvgSelector - move to SpecificResource too ^^ -### Style +## Style Move to SpecificResource -### Rotation +## Rotation -### Hotspot Linking and Activation +## Hotspot Linking and Activation Move to SpecificResource -### Annotation Page +## Annotation Page "Overlapping elements with a larger z-index cover those with a smaller one." link to https://developer.mozilla.org/en-US/docs/Web/CSS/z-index -### Annotation Collection +## Annotation Collection deal with this: https://github.com/IIIF/api/pull/2304/files#diff-cc70f02818f6bed2b14dfbf8bf3206e0825047951c8e83ad56fc73e489f82ac4R1757 @@ -953,21 +910,21 @@ use totalItems? https://iiif.io/api/discovery/1.0/#totalitems -## Navigation +# Navigation -### Collection +## Collection IIIF Collections are ordered lists of Manifests, Collections, and/or Specific Resources. Collections allow these resources to be grouped in a hierarchical structure for navigation and other purposes. :eyes: -### Range +## Range IIIF Ranges are used to represent structure _WITHIN_ a Manifest beyond the default order of the Containers in the `items` property. Example uses include newspaper sections or articles, chapters within a book for a table of contents, or movements within a piece of music. Ranges can include Containers, parts of Containers via Specific Resources or fragment URIs, or other Ranges, creating a tree structure like a table of contents. The typical intent of adding a Range to the Manifest is to allow the client to display a linear or hierarchical navigation interface to enable the user to quickly move through the object's content. :eyes: -### Example: Periodical +## Example: Periodical This example demonstrates the use of IIIF Collections to group Manifests into a hierarchy. In this case, there is a Collection for a publishing run of the _The Tombstone Epitaph_ from 1880 to 1920. This contains 41 child Collections each representing a year's worth of issues. Each of these year Collections in turn has one Manifest for each daily issue of the newspaper. @@ -1010,7 +967,7 @@ sequence -## Integration +# Integration seeAlso, service(s), extensions mention search, image api, auth @@ -1023,7 +980,7 @@ partOf - -## Content State +# Content State 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: @@ -1137,14 +1094,14 @@ Annotations with the motivation `contentState` are referred to as _content state Content States are used for the following applications: -### Load a particular view of a resource or group of resources +## 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 +## Load a particular view of some resource and modify it 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: @@ -1188,7 +1145,7 @@ TODO: what is the processing algorithm for applying incoming `hidden` ? When a Content State annotation carries a Scene, a view might be initialized from a Content State that introduces an additional Camera that shows the user the point of interest. -### Modify the Container in a particular context +## Modify the Container in a particular context The techniques in the previous example are also used within a published IIIF Manifest 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. The `scope` property indicates to the client that the Content State provides valuable context for displaying some aspect of a Scene or other Container. In the case of a commenting annotation, this means that the Content State should be loaded when the commenting annotation is selected or otherwise highlighted. @@ -1356,19 +1313,19 @@ Use of `scope` is permitted in annotations on any Container type, not just Scene -### The `sequence` behavior +## The `sequence` behavior // Is this right? Language... While all AnnotationPage `items` are inherently ordered, an Annotation Page with the behavior `sequence` is explicitly a narrative, and clients should prevent (dissuade) users from jumping about. The presence of `sequence` affects the way a client should interpret the `reset` property described below. -### Content States on Manifests +## Content States on Manifests When an annotation with the motivation `contentState` is provided via the `annotations` property of a Manifest, rather than contextually via `scope`, it is assumed to be generally available for selection by the user at any time. A client may present such as annotations as a menu of views, allowing arbitrary jumping into any Scene (or Canvas or Timeline) from any other point. // Is there some overlap here with Range? -### Processing Content States in Scopes: reset +## Processing Content States in Scopes: reset When a Content State is applied to a Container such as a Scene, it is assumed to be a "diff" - for example if 3 cameras and 4 lights are already present in the Scene, and a Content State asserts a single new Camera, the default behavior is to add this fourth Camera to the Scene and leave the existing resources as they are. @@ -1446,19 +1403,19 @@ Before applying the content state to the Scene, the client should reset the Scen // I am assuming reset is always true except in `linear-nav` - otherwise it's completely unpredictable!! or is it... arbitrary navigation, state provided by initialization content states, etc... -### Contribute additional information permanently +## Contribute additional information permanently Rerum inbox scenario - should be covered in CS2 protocol -### activating - animation and interactions +## activating - animation and interactions Annotations with the motivation `activating` are referred to as _activating_ annotations. There are two uses of `activating` annotations: -#### Triggering a content state +### Triggering a content state -An activating annotation links a painting annotation to a content state. When a user interacts with the painting annotation - whether through clicking it, tapping it, or other client-specific behaviors - the linked content state should be processed to modify the Scene or other Container, as in the previous examples. The painting annotation is the target of the activating annotation, and the content state is the body value. Only one content state may be specified in the body array, but the body array may include a `TextualBody` to provide a label for the interaction. The pattern is the same as for the `linking` motivation, but rather than the client opening a new browser window on the resource specified in the `body`, it applies the modification provided by the Content State. +An activating annotation links a Painting Annotation to a content state. When a user interacts with the Painting Annotation - whether through clicking it, tapping it, or other client-specific behaviors - the linked content state should be processed to modify the Scene or other Container, as in the previous examples. The Painting Annotation is the target of the activating annotation, and the content state is the body value. Only one content state may be specified in the body array, but the body array may include a `TextualBody` to provide a label for the interaction. The pattern is the same as for the `linking` motivation, but rather than the client opening a new browser window on the resource specified in the `body`, it applies the modification provided by the Content State. The activating annotation is provided in a Container's `annotations` property. In this (contrived for brevity) example, if the user clicks the mandible model, the Scene background changes color: @@ -1530,14 +1487,14 @@ The activating annotation is provided in a Container's `annotations` property. I -#### Triggering a named animation in a model +### 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. This pattern is similar to the above, except that: - There is no Content State in the `body`, but there _MUST_ be a TextualBody to label the interaction. (?? must?) - - The `target` selects a _named animation_ in the model. The `target` MUST be a SpecificResource, where the `source` is the painting annotation that paints the model, and the `selector` is of type `AnimationSelector` with the `value` being a string that corresponds to the animation in the model. + - The `target` selects a _named animation_ in the model. The `target` MUST be a SpecificResource, where the `source` is the Painting Annotation that paints the model, and the `selector` is of type `AnimationSelector` with the `value` being a string that corresponds to the animation in the model. The format of the `value` string is implementation-specific, and will depend on how different 3D formats support addressing of animations within models. The same model can be painted multiple times into the scene, and you might want to activate only one model's animation, thus we need to refer to the annotation that paints the model, not the model directly. @@ -1618,7 +1575,7 @@ if the `target` is an AnimationSelector, then the `body` can ONLY be TextualBody There is a more general rule here! -### reset +## reset See above... @@ -1631,7 +1588,7 @@ See above... -## Conveying Physical Dimensions +# Conveying Physical Dimensions In many cases, the dimensions of a Canvas, or the pixel density of a photograph, are not necessarily related to a real-world size of the object they show. A large wall painting and a tiny miniature may both be conveyed by 20 megapixel source images on a 4000 by 3000 unit Canvas. But it can be important to know how big something is or if there is a relationship between pixel density and physical length, especially when comparing objects together. Each pixel in an image may correspond precisely to a physical area, allowing measurement of real world distances from the image. A scanned 3D model may be constructed such that each 3D coordinate unit corresponds to one meter of physical distance. @@ -1645,26 +1602,26 @@ An extreme example of both physical dimension properties together is a Canvas sh -## Protocol +# Protocol -### HTTP Requests and Responses +## HTTP Requests and Responses -#### URI Recommendations +### URI Recommendations -#### Requests +### Requests -#### Responses +### Responses -#### Authentication +### Authentication -## Accessibility +# Accessibility (new section) @@ -1677,7 +1634,7 @@ An extreme example of both physical dimension properties together is a Canvas sh -## Terminology +# Terminology The principles of [Linked Data][org-linked-data] and the [Architecture of the Web][org-w3c-webarch] are adopted in order to provide a distributed and interoperable framework. The [Shared Canvas data model][shared-canvas] and [JSON-LD][org-w3c-json-ld] are leveraged to create an easy-to-implement, JSON-based format. @@ -1693,12 +1650,12 @@ The key words _MUST_, _MUST NOT_, _REQUIRED_, _SHALL_, _SHALL NOT_, _SHOULD_, _S -## Appendices +# Appendices -### Versioning +## Versioning -### Acknowledgements +## Acknowledgements -### Change Log +## Change Log "Exclude Audio" diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index bf41cdb13..6b89d0bc4 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -1294,7 +1294,7 @@ The URI that identifies the resource. If the resource is only available embedded The value _MUST_ be a string, and the value _MUST_ be an HTTP(S) URI for resources defined in this specification. If the resource is retrievable via HTTP(S), then the URI _MUST_ be the URI at which it is published. External resources, such as profiles, _MAY_ have non-HTTP(S) URIs defined by other communities. -The existence of an HTTP(S) URI in the `id` property does not mean that the URI will always be dereferencable. If the resource with the `id` property is [embedded][prezi30-terminology], it _MAY_ also be dereferenceable. If the resource is referenced (again, see the [terminology section][prezi30-terminology] for an explanation of "referenced"), it _MUST_ be dereferenceable. The [definitions of the Resources][prezi30-resource-structure] give further guidance. +The existence of an HTTP(S) URI in the `id` property does not mean that the URI will always be dereferenceable. If the resource with the `id` property is [embedded][prezi30-terminology], it _MAY_ also be dereferenceable. If the resource is referenced (again, see the [terminology section][prezi30-terminology] for an explanation of "referenced"), it _MUST_ be dereferenceable. The [definitions of the Resources][prezi30-resource-structure] give further guidance. * All resource types _MUST_ have the `id` property.
Clients _MAY_ render `id` on any resource type, and _SHOULD_ render `id` on Collections, Manifests and Canvases. diff --git a/source/presentation/4.0/scratch.md b/source/presentation/4.0/scratch.md new file mode 100644 index 000000000..3142c74e6 --- /dev/null +++ b/source/presentation/4.0/scratch.md @@ -0,0 +1,6 @@ + +In the example Manifest above the first Container is a Timeline. One content resource, an MP3 file, is associated with the Timeline via a Painting Annotation for its entire duration. Typically the duration of the Timeline matches the duration of its content. This is the simplest time-based use case. The `target` property of the Painting Annotation is the whole Timeline, because it is simply the `id` of the Timeline without further qualification. In this simple case, playing the Timeline is the same as playing the MP3. + +The second Container is a Canvas, representing a 2D surface. In this case the Canvas represents an artwork, and there is no duration property. The content resource, a JPEG image of the artwork, is associated with the Canvas via a Painting Annotation. The unit integer coordinates of the Canvas (12000 x 9000) are not the same as the pixel dimensions of the JPEG image (4000 x 3000), but they are proportional - the Canvas has a 4:3 landscape aspect ratio, and so does the JPEG image. The `target` property of the Annotation is the Canvas `id`, unqualified by any particular region; this is taken to mean the content (the image) should fill the Canvas completely. As the Canvas and the image are the same aspect ratio, no distortion will occur. This approach allows the current image to be replaced by a higher resolution image in future, on the same Canvas. The Canvas dimensions establish a coordinate system for _painting annotations_ and other kinds of annotation that link content with the Canvas; they are not pixels of images. + +The third Container is a Scene. Unlike a Canvas, it is not a bounded spatial extent, but may be a bounded temporal extent if it has the optional duration property. It still establishes a coordinate space (x, y, z) but doesn't need any spatial properties to do so as it is always the same, infinite unbounded space. The Annotation paints the astronaut model into the Scene. As no further qualification is given, the astronaut model is placed at the (0,0,0) origin of the Scene. Later examples will show how to control the lighting and camera position(s) and properties, but this is not required; a IIIF viewer is expected to supply ambient light and a default camera position in the absence of specific values. \ No newline at end of file From 7a56441b3e25929f3441bb57eb4241ddee7a6fdc Mon Sep 17 00:00:00 2001 From: Rob Sanderson Date: Mon, 2 Jun 2025 11:18:26 +0100 Subject: [PATCH 092/130] Model --- source/presentation/4.0/model.md | 22 +++++++++++++++++----- 1 file changed, 17 insertions(+), 5 deletions(-) diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index 6b89d0bc4..2a2925390 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -235,7 +235,7 @@ A Manifest is the primary unit of distribution of IIIF and provides a descriptio Manifests _MUST_ be identified by a URI and it _MUST_ be an HTTP(S) URI, given in the `id` property. It _MUST_ be able to be dereferenced to retrieve the JSON description. -The members of a Manifest are listed in the `items` property. The members of Manifests _MUST_ be Containers, defined below, and are embedded within the Manifest. The Manifest _MAY_ have a `structures` property listing one or more [Ranges][#range] which describe additional structure of the content, such as might be rendered as a table of contents. The Manifest _MAY_ have an `annotations` property, which includes Annotation Page resources where the Annotations have the Manifest as their `target`. These Annotations _MUST NOT_ have `painting` as their `motivation`. +The members of a Manifest are listed in the `items` property. The members of Manifests _MUST_ be Containers, defined below, and are embedded within the Manifest. The Containers in a single Manifest _MAY_ be of different classes. The Manifest _MAY_ have a `structures` property listing one or more [Ranges][#range] which describe additional structure of the content, such as might be rendered as a table of contents. The Manifest _MAY_ have an `annotations` property, which includes Annotation Page resources where the Annotations have the Manifest as their `target`. These Annotations _MUST NOT_ have `painting` as their `motivation`. __Properties__
@@ -245,7 +245,7 @@ A Manifest _MAY_ have the following properties: [requiredStatement](#requiredSta {: .note} ### Container Classes -{: #containers} +{: #Containers} A Container is a frame of reference that allows the relative positioning of content. @@ -263,6 +263,7 @@ All Containers _MAY_ have the following properites: [metadata](#metadata), [summ #### Timeline +{: #Timeline} > `"type": "Timeline"` @@ -273,6 +274,7 @@ A Timeline _MUST_ have the following additional properties: [duration](#duration {: .note} #### Canvas +{: #Canvas} > `"type": "Canvas"` @@ -285,6 +287,7 @@ A Canvas _MAY_ have the following additional properties: [duration](#duration). #### Scene +{: #Scene} > `"type": "Scene"` @@ -301,13 +304,13 @@ A Scene _MAY_ have the following additional properties: [duration](#duration). {: .note} - ### Annotation Classes -{: #annotations} +{: #Annotations} The following set of classes are defined by the W3C's [Web Annotation Data Model][org-w3c-webanno] and Vocabulary, and are heavily used within the IIIF Data Model. Any necessary deviations from those specifications are explicitly noted and explained, such as the need for internationalization of labels. #### Annotation +{: #Annotation} > `"type": "Annotation"` @@ -327,6 +330,7 @@ An Annotation _MAY_ have the following properties: [label](#label), [metadata](# #### Annotation Collection +{: #AnnotationCollection} > `"type": "AnnotationCollection"` @@ -344,6 +348,7 @@ An Annotation Collection _MAY_ have the following properties: [requiredStatement #### Annotation Page +{: #AnnotationPage} > `"type": "AnnotationPage"` @@ -359,6 +364,7 @@ An Annotation Page _MAY_ have the following properties: [label](#label), [startI #### Specific Resource +{: #SpecificResource} > `"type": "SpecificResource"` @@ -373,6 +379,7 @@ A Specific Resource _MAY_ have the following properties: [position](#position), {: .note} #### Textual Body +{: #TextualBody} > `"type": "TextualBody"` @@ -387,6 +394,7 @@ A Specific Resource _MAY_ have the following properties: [position](#position), #### Choice +{: #Choice} > `"type": "Choice"` @@ -402,6 +410,7 @@ A Choice _MAY_ have the following properties: [metadata](#metadata), [summary](# ### Content Resources +{: #ContentResources} Content Resources are resources on the Web such as images, audio, video, 3d models, or text which can be associated with a Container via an Annotation, or be used with `thumbnail`, `rendering` or similar properties. @@ -421,11 +430,13 @@ A Content Resource _MAY_ have the following properties: [height](#height), [widt ### Selectors +{: #Selectors} The Web Annotation Data Model defines several Selectors, which describe how to find a specific segment of that resource to be used. As noted, the nature of Selectors are dependent on the type of resources that they select out of, and the methods needed for those descriptions will vary. The Selectors from the Web Annotation Data Model and other sources can be used within the IIIF Data Model. This specification defines additional Selector classes for use. #### Point Selector +{: #PointSelector} > `"type": "PointSelector"` @@ -451,6 +462,7 @@ A Point Selector _MAY_ have the following properties: [x](#x), [y](#y), [z](#z), #### WKT Selector +{: #WktSelector} > `"type": "WktSelector"` @@ -2206,7 +2218,7 @@ A single UnitValue that defines a multiplier or scale factor for the `duration` Clients _MAY_ process `temporalScale` on a Canvas. * A Scene _MAY_ have the `temporalScale` property.
Clients _MAY_ process `temporalScale` on a Scene. - + ### thumbnail {: #thumbnail} From ead08e788ac17f665c2d378577ae902f1a2a9f35 Mon Sep 17 00:00:00 2001 From: Rob Sanderson Date: Mon, 2 Jun 2025 11:20:37 +0100 Subject: [PATCH 093/130] Update model.md --- source/presentation/4.0/model.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index 2a2925390..02e34b4c6 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -483,6 +483,7 @@ A WKT Selector _MUST_ have the following properties: [id](#id), [type](#type), a ``` #### Audio Content Selector +{: #AudioContentSelector} > `"type": "AudioContentSelector"` @@ -501,6 +502,7 @@ An Audio Content Selector _MUST_ have the following properties: [id](#id), and [ #### Visual Content Selector +{: #VisualContentSelector} > `"type": "VisualContentSelector"` From 988de7e0814ebd8c8e9a731039a05e59a0620323 Mon Sep 17 00:00:00 2001 From: tomcrane Date: Mon, 2 Jun 2025 11:26:47 +0100 Subject: [PATCH 094/130] ORCIDs --- source/presentation/4.0/index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index 647ad7b84..527511e93 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -23,13 +23,13 @@ editors: ORCID: https://orcid.org/0000-0003-4441-6852 institution: J. Paul Getty Trust - name: Dawn Childress - ORCID: + ORCID: https://orcid.org/0000-0003-2602-2788 institution: UCLA - name: Julie Winchester - ORCID: + ORCID: https://orcid.org/0000-0001-6578-764X institution: Duke University - name: Jeff Mixter - ORCID: + ORCID: https://orcid.org/0000-0002-8411-2952 institution: OCLC hero: image: '' From 0ce7b72b3c3a1cdc35f15c7e9027337b1304fbb0 Mon Sep 17 00:00:00 2001 From: Rob Sanderson Date: Mon, 2 Jun 2025 13:55:24 +0100 Subject: [PATCH 095/130] Update provides to annotation --- source/presentation/4.0/model.md | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index 02e34b4c6..078e8b00f 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -23,13 +23,13 @@ editors: ORCID: https://orcid.org/0000-0003-4441-6852 institution: Yale University - name: Dawn Childress - ORCID: + ORCID: https://orcid.org/0000-0003-2602-2788 institution: UCLA - name: Julie Winchester - ORCID: + ORCID: https://orcid.org/0000-0001-6578-764X institution: Duke University - name: Jeff Mixter - ORCID: + ORCID: https://orcid.org/0000-0002-8411-2952 institution: OCLC hero: image: '' @@ -1839,17 +1839,14 @@ The value _MUST_ be an array of JSON objects, where each item in the array confo ### provides {: #provides} -A set of features or additional functionality that a linked resource enables relative to the linking or including resource, which is not defined by the `type`, `format` or `profile` of the linked resource. It provides information as to why and how a client might want to interact with the resource, rather than what the resource is. For example, a text file (linked resource) that `provides` a `closedCaptions` for a Video (context resource), or an audio file (linked resource) that `provides` an `audioDescription` of a Canvas (context resource). +A set of features or additional functionality that a linked resource enables relative to the linking or including resource, often for accessibility purposes and which are not defined by the `type`, `format` or `profile` of the linked resource. It provides information as to why and how a client might want to interact with the resource, rather than what the resource is. For example, a text file (linked resource) that `provides` a `closedCaptions` for a Video (context resource), or an audio file (linked resource) that `provides` an `audioDescription` of a Canvas (context resource). The value _MUST_ be an array of strings, each string identifies a particular feature and _MUST_ be taken from the table below or the [provides registry][link]. Note that the majority of the values have been selected from [accessibility feature spec][link] and thus use the original form rather than being consistent with the hyphen-based form of the values of `behavior` and `viewingDirection`. - -* Annotations with the `painting` motivation _SHOULD NOT_ have the `provides` property.
- Clients _SHOULD_ ignore the `provides` property on Annotations with the `painting` motivation. -* Any resource linked to or included in another resource _MAY_ have the `provides` property.
- Clients _SHOULD_ process the `provides` property on these resources. +* Annotations with the `supplementing` motivation _MAY_ have the `provides` property.
+ Clients _SHOULD_ ignore the `provides` property on all other resource. | Value | Description | | ----- | ----------- | From db6d0b81489ee98b9af09ebdef38b0e6acb7846c Mon Sep 17 00:00:00 2001 From: Rob Sanderson Date: Mon, 2 Jun 2025 13:56:26 +0100 Subject: [PATCH 096/130] Remove warning --- source/presentation/4.0/model.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index 078e8b00f..d61d2035d 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -1869,8 +1869,6 @@ Note that the majority of the values have been selected from [accessibility feat { "provides": [ "closedCaption" ] } ``` -!!! warning "This breaks the graph as the file doesn't provide X in all contexts" - ### rendering {: #rendering} From 4d9dbafa56f9774f00e986d9273067124fcd45de Mon Sep 17 00:00:00 2001 From: tomcrane Date: Mon, 2 Jun 2025 13:57:44 +0100 Subject: [PATCH 097/130] Leeds tweaks 2 --- source/presentation/4.0/index.md | 91 ++++++++++++++++-------------- source/presentation/4.0/scratch.md | 5 +- 2 files changed, 52 insertions(+), 44 deletions(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index 527511e93..30be9aba7 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -243,30 +243,26 @@ The same linking mechanism is also used in IIIF with other motivations for trans Annotations are grouped within the `items` property of an Annotation Page, and the `items` property of the Container is a list of Annotation Pages. This allows consistent grouping of Annotations when required. -(👀) [Model Documentation](model/#annotations) +(👀) [Model Documentation](model/#Annotations) ## Content Resources Content Resources are external web resources, including images, video, audio, 3D models, data, web pages or any other format. Typically these are the resources that will be painted into a Container using a Painting Annotation. -In addition to the required properties `id` and `type`, other commonly used properties include `format`, and `width`, `height` and `duration` as appropriate to the Content Resource format. +In addition to the required properties `id` and `type`, other commonly used properties include `format`, and `width`, `height` and `duration` as appropriate to the Content Resource format. The values of these properties are often the source of the equivalent Container properties. -If you have existing content resources with web URIs - images, audio, video and models - you can publish IIIF Manifests for them by constructing the appropriate JSON around them and publishing the JSON documents. This requires careful consideration of the URI schemes for `id` properties of Containers and their Manifests to ensure they remain referenceable in the future. The choice of Timeline or Canvas dimensions (duration, width, height) can usually be derived simply from the content; the same duration as the audio or video, and the same unit Canvas dimensions as the image or video pixel dimensions, with the caveat that you should avoid low values for `width` and `height` (ref model). - -(👀) [Model Documentation](model/#contentresources) +(👀) [Model Documentation](model/#ContentResources) ### Containers as Content Resources -Containers may also be treated as Content Resources and painted into other Containers. This allows rich composition of content, such as painting a Canvas bearing a Video into a Scene, or painting a 3D model along with its associated Lights into an encompassing Scene. +Containers may also be treated as Content Resources and painted into other Containers. This allows composition of content, such as painting a Canvas bearing a Video into a Scene, or painting a 3D model along with its associated Lights into an encompassing Scene. ### Referencing Parts of Resources -A common requirement is to refer to only part of a resource, either a Container or a Content Resource. There are two primary methods for achieving this: adding a fragment to the end of the URI for the resource, or creating a Specific Resource that describes the method for selecting the desired part. - -#### Fragments +A common scenario is to refer to only part of a resource, either a Container or a Content Resource. There are two primary methods for achieving this: adding a fragment to the end of the URI for the resource, or creating a Specific Resource that describes the method for selecting the desired part. -Parts of resources on the Web are identified using URIs with a fragment component that both describes how to select the part from the resource, and, as a URI, also identifies it. In HTML this is frequently used to refer to part of the web page, called an anchor. The URI with the fragment can be used in place of the URI without the fragment in order to refer to this part. +Parts of resources on the Web can be identified using URIs with a fragment component that both describes how to select the part from the resource, and, as a URI, also identifies it. In HTML this is frequently used to refer to part of the web page, called an anchor. The URI with the fragment can be used in place of the URI without the fragment in order to refer to this part. There are different types of fragment based on the format of the resource. The most commonly used type in IIIF is the W3C's Media Fragments specification, as it can define a temporal and 2D spatial region. @@ -274,8 +270,9 @@ There are different types of fragment based on the format of the resource. The m { "id": "https://example.org/iiif/presentation/examples/manifest-with-containers/comments/c1", "type": "Annotation", - "motivation": "commenting", + "motivation": [ "commenting" ], "body": { + "id": "https://example.org/iiif/presentation/examples/manifest-with-containers/bodies/koto-body", "type": "TextualBody", "value": "Koto with a cover being carried", "language": "en", @@ -285,35 +282,40 @@ There are different types of fragment based on the format of the resource. The m } ``` -Here the Canvas `id` from the earlier example is still the `target` of an Annotation, but it has been qualified to a specific region of that Canvas by a Fragment Selector `#xywh=6050,3220,925,1250`. Note that the x, y, w, and h are in the Canvas coordinate space, not the pixel dimensions space. This annotation has no knowledge of or dependency on the particular image we painted onto the Canvas; we could replace that image with one of a different, higher resolution without affecting this annotation or the region of the Canvas it targets. +Here the Canvas `id` from the earlier example is still the `target` of an Annotation, but it has been qualified to a specific region of that Canvas by a URI fragment `#xywh=6050,3220,925,1250`. Note that the x, y, w, and h are in the Canvas coordinate space, not the image pixel dimensions space. This annotation has no knowledge of or dependency on the particular image we painted onto the Canvas; we could replace that image with one of a different, higher resolution without affecting this annotation or the region of the Canvas it targets. -#### Specific Resource +### Specific Resource -URIs with fragments are insufficient for complex referencing, like circular regions or arbitrary text spans, and do not support other useful features such as describing styling or transformation. The Web Annotation Data Model introduces a class called `SpecificResource` that represents the resource in a specific context or role, which IIIF uses to describe these more complex requirements. The Specific Resource then identifies the part, and the description of how to extract it is given as an instance of a `Selector` class associated with it. +URIs with fragments are insufficient for complex referencing, like circular regions or arbitrary text spans, and do not support other useful features such as describing styling or transformation. The Web Annotation Data Model introduces a class called `SpecificResource` that represents the resource in a specific context or role, which IIIF uses to describe these more complex requirements. Several different classes of Selector are used in IIIF, including an alternative implementation of the fragment pattern called `FragmentSelector`. The fragment is given in the `value` property of the `FragmentSelector`, and the resource it should be applied to is given in `source`. The required properties of Specific Resources are `id`, `type`, and `source`. Other commonly used properties include `selector`, `transform`, and `scope`. +The fragment example above can be expressed using a Specific Resource: + ```json { "id": "https://example.org/iiif/presentation/examples/manifest-with-containers/comments/c1", "type": "Annotation", - "motivation": "commenting", + "motivation": [ "commenting" ], "body": { + "id": "https://example.org/iiif/presentation/examples/manifest-with-containers/bodies/koto-body", "type": "TextualBody", "value": "Koto with a cover being carried", "language": "en", "format": "text/plain" }, "target": { + "id": "https://example.org/iiif/presentation/examples/manifest-with-containers/resources/koto-sr", "type": "SpecificResource", "source": { "id": "https://example.org/iiif/presentation/examples/manifest-with-containers/canvas", "type": "Canvas" }, "selector": { + "id": "https://example.org/iiif/presentation/examples/manifest-with-containers/selectors/koto-selector", "type": "FragmentSelector", "value": "xywh=6050,3220,925,1250" } @@ -493,34 +495,37 @@ A content resource may be annotated into a Scene for a period of time by use of ```json { - "id": "https://example.org/iiif/3d/anno1", - "type": "Annotation", - "motivation": ["painting"], - "body": { - "id": "https://example.org/iiif/assets/model1.glb", - "type": "Model" - }, - "target": { - "type": "SpecificResource", - "source": [ - { - "id": "https://example.org/iiif/scene1", - "type": "Scene" - } - ], - "selector": [ - { - "type": "PointSelector", - "x": -1.0, - "y": -1.0, - "z": 3.0, - "refinedBy": { - "type": "FragmentSelector", - "value": "t=45,95" - } - } - ] - } + "id": "https://example.org/iiif/3d/anno1", + "type": "Annotation", + "motivation": ["painting"], + "body": { + "id": "https://example.org/iiif/assets/model1.glb", + "type": "Model" + }, + "target": { + "id": "https://example.org/iiif/selectors/model1-glb-sr", + "type": "SpecificResource", + "source": [ + { + "id": "https://example.org/iiif/scene1", + "type": "Scene" + } + ], + "selector": [ + { + "id": "https://example.org/uuid/9fbd580b-895b-41b9-974a-1553329037f2", + "type": "PointSelector", + "x": -1.0, + "y": -1.0, + "z": 3.0, + "refinedBy": { + "id": "https://example.org/uuid/3d0d097b-2b37-4a15-b6a5-506e417d5115", + "type": "FragmentSelector", + "value": "t=45,95" + } + } + ] + } } ``` diff --git a/source/presentation/4.0/scratch.md b/source/presentation/4.0/scratch.md index 3142c74e6..273543e6d 100644 --- a/source/presentation/4.0/scratch.md +++ b/source/presentation/4.0/scratch.md @@ -3,4 +3,7 @@ In the example Manifest above the first Container is a Timeline. One content res The second Container is a Canvas, representing a 2D surface. In this case the Canvas represents an artwork, and there is no duration property. The content resource, a JPEG image of the artwork, is associated with the Canvas via a Painting Annotation. The unit integer coordinates of the Canvas (12000 x 9000) are not the same as the pixel dimensions of the JPEG image (4000 x 3000), but they are proportional - the Canvas has a 4:3 landscape aspect ratio, and so does the JPEG image. The `target` property of the Annotation is the Canvas `id`, unqualified by any particular region; this is taken to mean the content (the image) should fill the Canvas completely. As the Canvas and the image are the same aspect ratio, no distortion will occur. This approach allows the current image to be replaced by a higher resolution image in future, on the same Canvas. The Canvas dimensions establish a coordinate system for _painting annotations_ and other kinds of annotation that link content with the Canvas; they are not pixels of images. -The third Container is a Scene. Unlike a Canvas, it is not a bounded spatial extent, but may be a bounded temporal extent if it has the optional duration property. It still establishes a coordinate space (x, y, z) but doesn't need any spatial properties to do so as it is always the same, infinite unbounded space. The Annotation paints the astronaut model into the Scene. As no further qualification is given, the astronaut model is placed at the (0,0,0) origin of the Scene. Later examples will show how to control the lighting and camera position(s) and properties, but this is not required; a IIIF viewer is expected to supply ambient light and a default camera position in the absence of specific values. \ No newline at end of file +The third Container is a Scene. Unlike a Canvas, it is not a bounded spatial extent, but may be a bounded temporal extent if it has the optional duration property. It still establishes a coordinate space (x, y, z) but doesn't need any spatial properties to do so as it is always the same, infinite unbounded space. The Annotation paints the astronaut model into the Scene. As no further qualification is given, the astronaut model is placed at the (0,0,0) origin of the Scene. Later examples will show how to control the lighting and camera position(s) and properties, but this is not required; a IIIF viewer is expected to supply ambient light and a default camera position in the absence of specific values. + + +This requires careful consideration of the URI schemes for `id` properties of Containers and their Manifests to ensure they remain referenceable in the future. \ No newline at end of file From 676c2d81df2bc18167045ca1f1fe7de1b640688a Mon Sep 17 00:00:00 2001 From: tomcrane Date: Mon, 2 Jun 2025 14:57:04 +0100 Subject: [PATCH 098/130] key points --- source/presentation/4.0/index.md | 116 +++++++++++++++++++++++++++++-- 1 file changed, 109 insertions(+), 7 deletions(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index 30be9aba7..2220ebe79 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -329,18 +329,120 @@ The fragment example above can be expressed using a Specific Resource: ## Use Case 1: Artwork -This example is a Manifest with one Canvas, with an image of an artwork "painted" onto the Canvas. It demonstrates the use of the common descriptive properties `label` for the title of the artwork, `metadata` for additional information to display to the user, `summary` for a brief description of the artwork, `rights` to assert a rights statement or license from a controlled vocabulary, `homepage` to link to the artwork's specific web page, `thumbnail` to provide a small image to stand for the Manifest, and `provider` to give information about the publisher of the Manifest. +This example is a Manifest with one Canvas, representing a 2D surface. In this case the Canvas represents an artwork, and there is no duration property. The content resource, a JPEG image of the artwork, is associated with the Canvas via a Painting Annotation. The unit integer coordinates of the Canvas (12000 x 9000) are not the same as the pixel dimensions of the JPEG image (4000 x 3000), but they are proportional - the Canvas has a 4:3 landscape aspect ratio, and so does the JPEG image. The `target` property of the Annotation is the Canvas `id`, unqualified by any particular region; this is taken to mean the content (the image) should fill the Canvas completely. As the Canvas and the image are the same aspect ratio, no distortion will occur. This approach allows the current image to be replaced by a higher resolution image in future, on the same Canvas. The Canvas dimensions establish a coordinate system for _painting annotations_ and other kinds of annotation that link content with the Canvas; they are not pixels of images. -``` -Example: a painting {} -Will demonstrate: +It demonstrates the use of the common descriptive properties `label` for the title of the artwork, `metadata` for additional information to display to the user, `summary` for a brief description of the artwork, `rights` to assert a rights statement or license from a controlled vocabulary, `homepage` to link to the artwork's specific web page, `thumbnail` to provide a small image to stand for the Manifest, and `provider` to give information about the publisher of the Manifest. -Manifest -> items -> Canvas -> items -> AnnoPage -> items -> Anno -> body -> Image -label, summary, metadata, rights, provider, homepage, thumbnail +```json +{ + "@context": "http://iiif.io/api/presentation/4/context.json", + "id": "https://iiif.io/api/cookbook/recipe/0001-mvm-image/manifest.json", + "type": "Manifest", + "label": { + "en": [ "Use case 1: Artwork" ] + }, + "metadata": [ + { + "label": { "en": [ "Artist" ] }, + "value": { "en": [ "Anne Artist" ] } + }, + { + "label": { "en": [ "Date" ] }, + "value": { "en": [ "c. 1800" ] } + } + ], + "summary": { "en": [ "A longer piece of text to be shown when the metadata is not." ] }, + "rights": "http://rightsstatements.org/vocab/NoC-NC/1.0/", + "homepage": [ + { + "id": "https://example.org/works/artwork37", + "type": "Text", + "format": "text/html", + "label": { "en": [ "Homepage for artwork37" ] } + } + ], + "thumbnail": [ + { + "id": "https://example.org/works/artwork37/thumbnail.jpg", + "type": "Image", + "format": "image/jpeg", + "width": 100, + "height": 150 + } + ], + "provider": + [ + { + "id": "https://example.org/about", + "type": "Agent", + "label": { "en": [ "Example Organization" ] }, + "homepage": [ + { + "id": "https://example.org/", + "type": "Text", + "label": { "en": [ "Example Organization Homepage" ] }, + "format": "text/html" + } + ], + "logo": [ + { + "id": "https://example.org/images/logo.png", + "type": "Image", + "format": "image/png", + "height": 100, + "width": 120 + } + ] + } + ], + "items": [ + { + "id": "https://example.org/iiif/presentation/examples/manifest-with-containers/canvas", + "type": "Canvas", + "width": 12000, + "height": 9000, + "items": [ + { + "id": "https://example.org/iiif/presentation/examples/manifest-with-containers/page/p2", + "type": "AnnotationPage", + "items": [ + { + "id": "https://example.org/iiif/presentation/examples/manifest-with-containers/annotation/c1", + "type": "Annotation", + "motivation": [ "painting" ], + "body": { + "id": "https://iiif.io/api/presentation/example-content-resources/image/painting.jpg", + "type": "Image", + "format": "image/jpeg", + "width": 4000, + "height": 3000 + }, + "target": "https://example.org/iiif/presentation/examples/manifest-with-containers/canvas" + } + ] + } + ] + } + ] +} ``` -Notice that the Painting Annotation is a member of the `items` property of an Annotation Page. While in this case there is only one Annotation Page and one Annotation, the mechanism is needed for consistency when there are multiple Annotation Pages, and it allows for Annotation Pages in general to be separate resources on the web. +
+ + **Key Points** + + * All IIIF documents begin with the `@context` key, which maps the JSON structure into a linked data representation. The value identifies the version of the specification in use. [👀 Model Documentation](model/#json-ld-contexts-and-extensions) + * Every JSON object that has a `type` property also has an `id` property and vice versa. + * Text elements intended for display to the user are conveyed by _Language Maps_, JSON objects in which the keys are language codes and the values are lists of one or more strings in that language. [👀 Model Documentation](model/#language-of-property-values) + * The Painting Annotation is a member of the `items` property of an Annotation Page. While in this case there is only one Annotation Page and one Annotation, the mechanism is needed for consistency when there are multiple Annotation Pages, and it allows for Annotation Pages in general to be separate resources on the web. + * The `metadata` label and value pairs are for display to the user rather than for machines to interpret. + * The `rights` property is always a single string value which is a URI. +
+{: .note} + + +> List of properties used with links to model for each ## Example 2: Book From ee528a1d87abacbaf8def6ff43d5292e074d38cb Mon Sep 17 00:00:00 2001 From: Rob Sanderson Date: Mon, 2 Jun 2025 14:57:32 +0100 Subject: [PATCH 099/130] Tweaks --- source/presentation/4.0/model.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index d61d2035d..40712425f 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -100,7 +100,7 @@ Any of the properties in the API that can have multiple values _MUST_ always be ### Language of Property Values {: #language-of-property-values} -Language _SHOULD_ be associated with strings that are intended to be displayed to the user for the `label` and `summary` properties, plus the `label` and `value` properties of the `metadata` and `requiredStatement` objects. +Language _SHOULD_ be associated with strings that are intended to be displayed to the user for the `label` and `summary` properties, plus the `label` and `value` properties of the `metadata` and `requiredStatement` objects. This construction is called a Language Map in the [JSON-LD specification](https://www.w3.org/TR/json-ld11/#language-maps). The values of these properties _MUST_ be JSON objects, with the keys being the [BCP 47][org-bcp-47] language code for the language, or if the language is either not known or the string does not have a language, then the key _MUST_ be the string `none`. The locale, script and other subtags _MAY_ be included. Clients _SHOULD_ process subtags when comparing the values with the user's provided preferences, however _MAY_ simply reduce all tags down to just the language, discarding everything after the first hyphen, and display all matching values. The associated values _MUST_ be arrays of strings, where each item is the content in the given language. @@ -2502,8 +2502,10 @@ Additional motivations may be added to the Annotation to further clarify the int ## JSON-LD and Extensions +{: #json-ld-and-extensions} ### JSON-LD Contexts and Extensions +{: #json-ld-contexts-and-extensions} The top level resource in the response _MUST_ have the `@context` property, and it _SHOULD_ appear as the very first key/value pair of the JSON representation. This tells Linked Data processors how to interpret the document. The IIIF Presentation API context, below, _MUST_ occur once per response in the top-most resource, and thus _MUST NOT_ appear within [embedded][prezi30-terminology] resources. For example, when embedding a Canvas within a Manifest, the Canvas will not have the `@context` property. @@ -2531,6 +2533,7 @@ Any additional properties beyond those defined in this specification or the Web The JSON representation _MUST NOT_ include the `@graph` key at the top level. This key might be created when serializing directly from RDF data using the JSON-LD 1.0 compaction algorithm. Instead, JSON-LD framing and/or custom code should be used to ensure the structure of the document is as defined by this specification. ### Term Collisions between Contexts +{: #term-collisions-between-contexts} There are some common terms used in more than one JSON-LD context document. Every attempt has been made to minimize these collisions, but some are inevitable. In order to know which specification is in effect at any given point, the class of the resource that has the property is the primary governing factor. Thus properties on Annotation based resources use the context from the [Web Annotation Data Model][org-w3c-webanno], whereas properties on classes defined by this specification use the IIIF Presentation API context's definition. From dc113d2431c5023eeb28c1f4ae6c26c1cebcbf77 Mon Sep 17 00:00:00 2001 From: Rob Sanderson Date: Mon, 2 Jun 2025 15:01:35 +0100 Subject: [PATCH 100/130] Fix callout? --- source/presentation/4.0/index.md | 107 +++++++++++++++---------------- 1 file changed, 51 insertions(+), 56 deletions(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index 2220ebe79..abd3dba33 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -8,7 +8,7 @@ tags: [specifications, presentation-api] major: 4 minor: 0 patch: 0 -pre: +pre: redirect_from: - /presentation/index.html - /presentation/4/index.html @@ -53,9 +53,9 @@ __Previous Version:__ [3.0][prezi30] # Introduction -The purpose of the IIIF Presentation API specification is to provide a [model](model) and JSON serialization format of that model. +The purpose of the IIIF Presentation API specification is to provide a [model](model) and JSON serialization format of that model. -It provides a document format - the IIIF Manifest - for cultural heritage organizations (and anyone else) to present objects in a standardized, interoperable fashion. This allows compatible software such as viewers and annotation tools to load and present complex digital objects on the web from thousands of different providers. +It provides a document format - the IIIF Manifest - for cultural heritage organizations (and anyone else) to present objects in a standardized, interoperable fashion. This allows compatible software such as viewers and annotation tools to load and present complex digital objects on the web from thousands of different providers. **If you have existing images, audio, video and models on the web, you can easily provide IIIF Manifests for them by publishing the appropriate JSON documents.** @@ -63,15 +63,15 @@ The IIIF Presentation API is concerned with enabling user experiences - providin This document acts as an introduction to the specification through a set of typical (but non-exhaustive) use cases. The model [model](model) document provides the formal specification of the terms used in this introduction. -## IIIF Use cases +## IIIF Use cases -1. **Artwork** - a Manifest that represents a painting, comprising a single image and accompanying display information. +1. **Artwork** - a Manifest that represents a painting, comprising a single image and accompanying display information. 2. **Book** - a Manifest that represents a digitized bound volume made up many separate images in order. The IIIF model provides structural elements to indicate the chapters. The text of the book is made available in machine-readable form as Web Annotations. 3. **45 Single** - a Manifest that represents the digitized audio from the two sides of a vinyl 7 inch record. 4. **Movie** - a Manifest that represents the digitized video of a film. A transcript of the audio is provided as Web Annotations, and additional machine-readable files provide subtitles and captions. 5. **Simple 3D Model** - a Manifest that publishes a single 3D model. 6. **Complex Scene** - a Manifest that publishes a complex 3D scene comprising multiple models, lights and cameras. -7. **Periodical** - a IIIF Collection that provides multiple child Collections and Manifests, representing the publication run of a newspaper over many years. The IIIF model provides structural elements to indicate individual articles and other elements. +7. **Periodical** - a IIIF Collection that provides multiple child Collections and Manifests, representing the publication run of a newspaper over many years. The IIIF model provides structural elements to indicate individual articles and other elements. 8. **Storytelling in 3D** - a Manifest that defines a sequence of states in a complex scene for the purposes of guiding a user through a particular experience. 9. **Manuscript** - (integration) @@ -94,7 +94,7 @@ This section is what you need to know to make sense of the examples that follow A Manifest is the primary unit of distribution of IIIF. Each Manifest usually describes how to present an object, such as a book, statue, music album or 3 dimensional scene. It is a JSON document that carries information needed for the client to present content to the user, such as a title and other descriptive information. The scope of what constitutes an object, and thus its Manifest, is up to the publisher of that Manifest. The Manifest contains sufficient information for the client to initialize itself and begin to display something quickly to the user. -The Manifest's `items` property is an ordered list of _Containers_ of _Content Resources_ (images, 3D models, audio, etc). Client software loads the Manifest and presents each Container's Content Resources. The client software also presents user interface controls to navigate the list of Content Containers. +The Manifest's `items` property is an ordered list of _Containers_ of _Content Resources_ (images, 3D models, audio, etc). Client software loads the Manifest and presents each Container's Content Resources. The client software also presents user interface controls to navigate the list of Content Containers. Manifests have descriptive, technical and linking properties. The required properties of Manifests are `id`, `type`, `items` and `label`. Other commonly used properties include `summary`, `metadata`, `rights`, `thumbnail`, `homepage` and `provider`. @@ -119,11 +119,11 @@ Manifests have descriptive, technical and linking properties. The required prope ## Containers -A Container is a frame of reference that allows the relative positioning of Content Resources, a concept borrowed from standards like PDF and HTML, or applications like Photoshop and PowerPoint, where an initially blank display surface has images, video, text and other content "painted" on to it. The frame is defined by a set of dimensions, with different types of Container having different dimensions. This specification defines three sub-classes of Container: Timeline (which only has a duration), Canvas (which has bounded height and width, and may have a duration), and Scene (which has infinite height, width and depth, and may have a duration). +A Container is a frame of reference that allows the relative positioning of Content Resources, a concept borrowed from standards like PDF and HTML, or applications like Photoshop and PowerPoint, where an initially blank display surface has images, video, text and other content "painted" on to it. The frame is defined by a set of dimensions, with different types of Container having different dimensions. This specification defines three sub-classes of Container: Timeline (which only has a duration), Canvas (which has bounded height and width, and may have a duration), and Scene (which has infinite height, width and depth, and may have a duration). The required properties of all Containers are `id`, and `type`. Most Containers also have the `items` and `label` properties. Further properties are required for the different types of Container. -The defined Container types are: +The defined Container types are: ### Timeline @@ -235,7 +235,7 @@ Scenes may also have the `duration` property in the same manner as Timelines. IIIF uses the concept of _Annotation_ to link resources together from around the web. This specification uses a World Wide Web Consortium (W3C) standard for this called the [Web Annotation Data Model][org-web-anno]. This is a structured linking mechanism useful for making comments about Content Resources, but IIIF's primary use of it is to associate the images, audio and other Content Resources with their Containers for presentation. -In each of the three Containers above, an **Annotation** links the Container to a Content Resource. The Content Resource in the `body` property is _painted_ into the Container by an Annotation whose `target` property is the `id` of the Container. In all three simple cases here the `target` property is the `id` of the Container with no further qualification. +In each of the three Containers above, an **Annotation** links the Container to a Content Resource. The Content Resource in the `body` property is _painted_ into the Container by an Annotation whose `target` property is the `id` of the Container. In all three simple cases here the `target` property is the `id` of the Container with no further qualification. Different uses of Annotation are distinguished through their `motivation` property. This specification defines a value for `motivation` called `painting` for associating Content Resources with Containers, which this specification calls a Painting Annotation. The verb "paint" is also used to refer to the associating of a Content Resource with a Container by a Painting Annotation. This is from the notion of painting onto a canvas, a metaphor borrowed from art and used for image-based digital applications, and expanded by IIIF into "painting" any Content Resource into a Container of any number of dimensions. @@ -250,7 +250,7 @@ Annotations are grouped within the `items` property of an Annotation Page, and t Content Resources are external web resources, including images, video, audio, 3D models, data, web pages or any other format. Typically these are the resources that will be painted into a Container using a Painting Annotation. -In addition to the required properties `id` and `type`, other commonly used properties include `format`, and `width`, `height` and `duration` as appropriate to the Content Resource format. The values of these properties are often the source of the equivalent Container properties. +In addition to the required properties `id` and `type`, other commonly used properties include `format`, and `width`, `height` and `duration` as appropriate to the Content Resource format. The values of these properties are often the source of the equivalent Container properties. (👀) [Model Documentation](model/#ContentResources) @@ -370,7 +370,7 @@ It demonstrates the use of the common descriptive properties `label` for the tit "height": 150 } ], - "provider": + "provider": [ { "id": "https://example.org/about", @@ -427,18 +427,13 @@ It demonstrates the use of the common descriptive properties `label` for the tit } ``` - -
- - **Key Points** - - * All IIIF documents begin with the `@context` key, which maps the JSON structure into a linked data representation. The value identifies the version of the specification in use. [👀 Model Documentation](model/#json-ld-contexts-and-extensions) - * Every JSON object that has a `type` property also has an `id` property and vice versa. - * Text elements intended for display to the user are conveyed by _Language Maps_, JSON objects in which the keys are language codes and the values are lists of one or more strings in that language. [👀 Model Documentation](model/#language-of-property-values) - * The Painting Annotation is a member of the `items` property of an Annotation Page. While in this case there is only one Annotation Page and one Annotation, the mechanism is needed for consistency when there are multiple Annotation Pages, and it allows for Annotation Pages in general to be separate resources on the web. - * The `metadata` label and value pairs are for display to the user rather than for machines to interpret. - * The `rights` property is always a single string value which is a URI. -
+**Key Points** +* All IIIF documents begin with the `@context` key, which maps the JSON structure into a linked data representation. The value identifies the version of the specification in use. [👀 Model Documentation](model/#json-ld-contexts-and-extensions) +* Every JSON object that has a `type` property also has an `id` property and vice versa. +* Text elements intended for display to the user are conveyed by _Language Maps_, JSON objects in which the keys are language codes and the values are lists of one or more strings in that language. [👀 Model Documentation](model/#language-of-property-values) +* The Painting Annotation is a member of the `items` property of an Annotation Page. While in this case there is only one Annotation Page and one Annotation, the mechanism is needed for consistency when there are multiple Annotation Pages, and it allows for Annotation Pages in general to be separate resources on the web. +* The `metadata` label and value pairs are for display to the user rather than for machines to interpret. +* The `rights` property is always a single string value which is a URI. {: .note} @@ -561,7 +556,7 @@ This (no units for scale) allows arbitrarily scaled models to be used, including A Scene or a Canvas may be treated as a content resource, referenced or described within the `body` of an Annotation. As with models and other resources, the Annotation is associated with a Scene into which the Scene or Canvas is to be nested through an Annotation `target`. The content resource Scene will be placed within the `target` Scene by aligning the coordinate origins of the two scenes. Alternately, Scene Annotations may use `PointSelector` to place the origin of the resource Scene at a specified coordinate within the `target` Scene. -As with other containers in IIIF, Annotations are used to target the Scene to place content such as 3d models into the scene. Annotations are also used to add lights and cameras. A Scene can have multiple models, lights, cameras and other resources, allowing them to be grouped together. Scenes and other IIIF containers, such as Canvases, may also be embedded within Scenes, as described below in the nesting section [fwd-ref-to-nesting]. +As with other containers in IIIF, Annotations are used to target the Scene to place content such as 3d models into the scene. Annotations are also used to add lights and cameras. A Scene can have multiple models, lights, cameras and other resources, allowing them to be grouped together. Scenes and other IIIF containers, such as Canvases, may also be embedded within Scenes, as described below in the nesting section [fwd-ref-to-nesting]. ```json { @@ -570,11 +565,11 @@ As with other containers in IIIF, Annotations are used to target the Scene to pl "label": {"en": ["Chessboard"]}, "backgroundColor": "#000000", "items": [ - "Note: Annotations Live Here" + "Note: Annotations Live Here" ] } ``` -As with other resources, it may be appropriate to modify the initial scale, rotation, or translation of a content resource Scene prior to painting it within another Scene. Scenes associated with SpecificResources may be manipulated through the transforms described in Transforms(transforms_section). +As with other resources, it may be appropriate to modify the initial scale, rotation, or translation of a content resource Scene prior to painting it within another Scene. Scenes associated with SpecificResources may be manipulated through the transforms described in Transforms(transforms_section). A simple example painting one Scene into another: @@ -624,7 +619,7 @@ A content resource may be annotated into a Scene for a period of time by use of "id": "https://example.org/uuid/3d0d097b-2b37-4a15-b6a5-506e417d5115", "type": "FragmentSelector", "value": "t=45,95" - } + } } ] } @@ -646,7 +641,7 @@ When using a URL fragment in place of a SpecificResource, the parameter `t` can } ``` -An Annotation may target a specific point in time using a PointSelector's `instant` property. The property's value must be a positive floating point number indicating a value in seconds that falls within the Scene's duration. +An Annotation may target a specific point in time using a PointSelector's `instant` property. The property's value must be a positive floating point number indicating a value in seconds that falls within the Scene's duration. ```json { @@ -708,7 +703,7 @@ Annotations may use a type of Selector called a `PointSelector` to align the Ann Example Annotation that positions a model at a point within a Scene: -```json +```json { "id": "https://example.org/iiif/3d/anno1", "type": "Annotation", @@ -773,7 +768,7 @@ The region of the Scene's space that is observable by the camera is bounded by t The `near` property defines the minimum distance from the camera at which something in the space must exist in order to be viewed by the camera. Anything nearer to the camera than this distance will not be viewed. Conversely, the `far` property defines a maximum distance from the camera at which something in the space must exist in order to be viewed by the camera. Anything further away will not be viewed. -For PerspectiveCameras, the vertical projection angle is specificed using the full angular extent in degrees from the top plane to the bottom plane using the `fieldOfView` property. The `fieldOfView` angle MUST be greater than 0 and less than 180. For OrthographicCameras, the vertical projection is always parallel and thus not defined. +For PerspectiveCameras, the vertical projection angle is specificed using the full angular extent in degrees from the top plane to the bottom plane using the `fieldOfView` property. The `fieldOfView` angle MUST be greater than 0 and less than 180. For OrthographicCameras, the vertical projection is always parallel and thus not defined. If any of these properties are not specified explicitly, they default to the choice of the client implementation. @@ -787,7 +782,7 @@ The first Camera defined and not hidden in a Scene is the default Camera used to "type": "PerspectiveCamera", "near": 1.0, "far": 100.0, - "fieldOfView": 45.0 + "fieldOfView": 45.0 } ``` @@ -806,7 +801,7 @@ This specification defines four types of Light: Lights defined in this specification have a `color` and an `intensity`. The color is given as an RGB value, such as "#FFFFFF" for white. The intensity is the strength or brightness of the light, and described using a `Value` construct. -SpotLight has an additional property of `angle`, specified in degrees, which is the angle from the direction that the Light is facing to the outside extent of the cone. +SpotLight has an additional property of `angle`, specified in degrees, which is the angle from the direction that the Light is facing to the outside extent of the cone. diagram of cone geometry showing how the angle of the cone is defined @@ -895,7 +890,7 @@ This rotation happens after the resource has been added to the Scene, and thus a ### Excluding -Just as a Scene may contain multiple Annotations with model, light, and camera resources, a single 3D model file may contain a collection of 3D resources, including model geometry, assemblages of lights, and/or multiple cameras, with some of these potentially manipulated by animations. When painting Scenes or models that themselves may contain groups of resources within a single Scene, it may not always be appropriate to include all possible cameras, lights, or other resources, and it may be desirable to opt not to import some of these resources. This is accomplished through the Annotation property `exclude`, which prevents the import of audio, lights, cameras, or animations from a particular Scene or model prior to the Annotation being painted into a Scene. When `exclude` is used, the excluded resource type should not be loaded into the Scene, and it is not possible to reactivate or turn on these excluded resources after loading. +Just as a Scene may contain multiple Annotations with model, light, and camera resources, a single 3D model file may contain a collection of 3D resources, including model geometry, assemblages of lights, and/or multiple cameras, with some of these potentially manipulated by animations. When painting Scenes or models that themselves may contain groups of resources within a single Scene, it may not always be appropriate to include all possible cameras, lights, or other resources, and it may be desirable to opt not to import some of these resources. This is accomplished through the Annotation property `exclude`, which prevents the import of audio, lights, cameras, or animations from a particular Scene or model prior to the Annotation being painted into a Scene. When `exclude` is used, the excluded resource type should not be loaded into the Scene, and it is not possible to reactivate or turn on these excluded resources after loading. Painting a Scene into another while excluding import of several types of resources: ```json @@ -920,7 +915,7 @@ Painting a Scene into another while excluding import of several types of resourc ### Nesting -A Canvas can be painted into a Scene as an Annotation, but the 2D nature of Canvases requires special consideration due to important differences between Canvases and Scenes. A Canvas describes a bounded 2D space with finite `height` and `width` measured in pixels with a pixel origin at the top-left corner of the Canvas, while Scenes describe a boundless 3D space with x, y, and z axes of arbitrary coordinate units and a coordinate origin at the center of the space. It is important to note that in many cases the pixel scale used by a Canvas or a 2D image content resource will not be in proportion to the desired 3D coordinate unit scale in a Scene. +A Canvas can be painted into a Scene as an Annotation, but the 2D nature of Canvases requires special consideration due to important differences between Canvases and Scenes. A Canvas describes a bounded 2D space with finite `height` and `width` measured in pixels with a pixel origin at the top-left corner of the Canvas, while Scenes describe a boundless 3D space with x, y, and z axes of arbitrary coordinate units and a coordinate origin at the center of the space. It is important to note that in many cases the pixel scale used by a Canvas or a 2D image content resource will not be in proportion to the desired 3D coordinate unit scale in a Scene. When a Canvas is painted as an Annotation targeting a Scene, the top-left corner of the Canvas (the pixel origin) is aligned with the 3D coordinate origin of the Scene. The top edge of the Canvas is aligned with (e.g., is colinear to) the positive x axis extending from the coordinate origin. The left edge of the Canvas is aligned with (e.g., is colinear to) the negative y axis extending from the coordinate origin. The Canvas is scaled to the Scene such that the pixel dimensions correspond to 3D coordinate units - a Canvas 200 pixels wide and 400 pixels high will extend 200 coordinate units across the x axis and 400 coordinate units across the y axis. Please note: direction terms "top", "bottom", "right", and "left" used in this section refer to the frame of reference of the Canvas itself, not the Scene into which the Canvas is painted. @@ -944,7 +939,7 @@ Example placing top-left at (0, 1, 0); bottom-left at (0, 0, 0); bottom-right at ] ``` -When a Scene is nested into another Scene, the `backgroundColor` of the Scene to be nested should be ignored as it is non-sensible to import. All Annotations painted into the Scene to be nested will be painted into the Scene into which content is being nested, including Light or Camera resources. If the Scene to be nested has one or more Camera Annotations while the Scene into which content is being nested does not, the first Camera Annotation from the nested Scene will become the default Camera for the overall Scene. +When a Scene is nested into another Scene, the `backgroundColor` of the Scene to be nested should be ignored as it is non-sensible to import. All Annotations painted into the Scene to be nested will be painted into the Scene into which content is being nested, including Light or Camera resources. If the Scene to be nested has one or more Camera Annotations while the Scene into which content is being nested does not, the first Camera Annotation from the nested Scene will become the default Camera for the overall Scene. --- @@ -1008,7 +1003,7 @@ link to https://developer.mozilla.org/en-US/docs/Web/CSS/z-index deal with this: https://github.com/IIIF/api/pull/2304/files#diff-cc70f02818f6bed2b14dfbf8bf3206e0825047951c8e83ad56fc73e489f82ac4R1757 -use totalItems? https://iiif.io/api/discovery/1.0/#totalitems +use totalItems? https://iiif.io/api/discovery/1.0/#totalitems @@ -1023,7 +1018,7 @@ use totalItems? https://iiif.io/api/discovery/1.0/#totalitems IIIF Collections are ordered lists of Manifests, Collections, and/or Specific Resources. Collections allow these resources to be grouped in a hierarchical structure for navigation and other purposes. -:eyes: +:eyes: ## Range @@ -1037,7 +1032,7 @@ This example demonstrates the use of IIIF Collections to group Manifests into a Within each Manifest, the `structures` property provides Ranges which are used to identify individual sections of the Newspaper, and individual stories within the sections which may be spread across multiple columns and pages. -Each Manifest has a `navDate` property that could be used to plot the issues on a calendar-style user interface. +Each Manifest has a `navDate` property that could be used to plot the issues on a calendar-style user interface. The top level Collection has a `navPlace` property that could be used on a "Newspapers of America" map to allow users to view newspapers by location. Each story's Range links to an Annotation Collection that provides the text of the story via the `supplementary` property. @@ -1081,7 +1076,7 @@ mention search, image api, auth profile for seeAlso -partOf - +partOf - @@ -1249,12 +1244,12 @@ As well as adding resources not present in the referred-to resource, the Content TODO: what is the processing algorithm for applying incoming `hidden` ? -When a Content State annotation carries a Scene, a view might be initialized from a Content State that introduces an additional Camera that shows the user the point of interest. +When a Content State annotation carries a Scene, a view might be initialized from a Content State that introduces an additional Camera that shows the user the point of interest. ## Modify the Container in a particular context -The techniques in the previous example are also used within a published IIIF Manifest 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. The `scope` property indicates to the client that the Content State provides valuable context for displaying some aspect of a Scene or other Container. In the case of a commenting annotation, this means that the Content State should be loaded when the commenting annotation is selected or otherwise highlighted. +The techniques in the previous example are also used within a published IIIF Manifest 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. The `scope` property indicates to the client that the Content State provides valuable context for displaying some aspect of a Scene or other Container. In the case of a commenting annotation, this means that the Content State should be loaded when the commenting annotation is selected or otherwise highlighted. Consider a Scene with two models, and two `commenting` annotations: @@ -1282,7 +1277,7 @@ Consider a Scene with two models, and two `commenting` annotations: "id": "https://raw.githubusercontent.com/IIIF/3d/main/assets/whale/whale_mandible.glb", "type": "Model" }, - "target": { + "target": { // SpecificResource with PointSelector } }, @@ -1294,7 +1289,7 @@ Consider a Scene with two models, and two `commenting` annotations: "id": "https://raw.githubusercontent.com/IIIF/3d/main/assets/whale/whale_cranium.glb", "type": "Model" }, - "target": { + "target": { // SpecificResource with PointSelector } } @@ -1313,7 +1308,7 @@ Consider a Scene with two models, and two `commenting` annotations: "type": "Annotation", "motivation": ["commenting"], "bodyValue": "Mandibular tooth", - "target": { + "target": { // SpecificResource with PointSelector } }, @@ -1322,7 +1317,7 @@ Consider a Scene with two models, and two `commenting` annotations: "type": "Annotation", "motivation": ["commenting"], "bodyValue": "Right pterygoid hamulus", - "target": { + "target": { // SpecificResource with PointSelector } } @@ -1332,7 +1327,7 @@ Consider a Scene with two models, and two `commenting` annotations: } ``` -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 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. It may be useful to light the Scene differently in different contexts. @@ -1468,10 +1463,10 @@ The client should reset the Container to its original state before applying the ```jsonc [ - { + { "id": "https://.../step-1", "type": "Annotation", - "motivation": ["contentState"] + "motivation": ["contentState"] // if you really want to ensure that any ad-hoc applied content states are wiped out, // then put an explicit reset here. But usually, we can start the nav by applying // the content state in the scope to the Scene without worrying that someone has @@ -1479,8 +1474,8 @@ The client should reset the Container to its original state before applying the }, // .... - - { + + { "id": "https://.../step-20", "type": "Annotation", "motivation": ["contentState"] @@ -1488,7 +1483,7 @@ The client should reset the Container to its original state before applying the }, - { + { // However, this particular step (step 37) needs to reset the Scene to the initial state. "id": "https://.../step-37", "type": "Annotation", @@ -1549,7 +1544,7 @@ The activating annotation is provided in a Container's `annotations` property. I "id": "https://raw.githubusercontent.com/IIIF/3d/main/assets/whale/whale_mandible.glb", "type": "Model" }, - "target": { + "target": { // SpecificResource with PointSelector } } @@ -1630,7 +1625,7 @@ This pattern is similar to the above, except that: "id": "https://raw.githubusercontent.com/IIIF/3d/main/assets/music-box.glb", "type": "Model" }, - "target": { + "target": { // SpecificResource with PointSelector } } @@ -1699,11 +1694,11 @@ See above... In many cases, the dimensions of a Canvas, or the pixel density of a photograph, are not necessarily related to a real-world size of the object they show. A large wall painting and a tiny miniature may both be conveyed by 20 megapixel source images on a 4000 by 3000 unit Canvas. But it can be important to know how big something is or if there is a relationship between pixel density and physical length, especially when comparing objects together. Each pixel in an image may correspond precisely to a physical area, allowing measurement of real world distances from the image. A scanned 3D model may be constructed such that each 3D coordinate unit corresponds to one meter of physical distance. -The `spatialScale` property of a Canvas or Scene provides a corresponding real-world scale for a unit of the Canvas or Scene coordinate system, allowing clients to provide scale information to users, for example by an on-screen virtual ruler. In a 2-up viewer, a client could scale two views to convey the true relative sizes of two objects. +The `spatialScale` property of a Canvas or Scene provides a corresponding real-world scale for a unit of the Canvas or Scene coordinate system, allowing clients to provide scale information to users, for example by an on-screen virtual ruler. In a 2-up viewer, a client could scale two views to convey the true relative sizes of two objects. The value of `spatialScale` is a `UnitValue` (ref) that has as a value a length unit. This specification defines only one length unit, "m", i.e., meters, though others may be defined externally as an [extension][prezi30-ldce]. If source size metadata is machine readable (or parse-able) in other measurement systems (e.g., feet and inches) then it should be converted to meters for use in `spatialScale`. Publishers may wish to present the original given measure (e.g., from catalogue metadata) in a `metadata` field for context. -The Presentation API also offers a corresponding `temporalScale` property for the `duration` dimension of a Container, when 1 second in the Container does not correspond to 1 second of real time. This is useful for speeded-up or slowed-down audio or video. +The Presentation API also offers a corresponding `temporalScale` property for the `duration` dimension of a Container, when 1 second in the Container does not correspond to 1 second of real time. This is useful for speeded-up or slowed-down audio or video. An extreme example of both physical dimension properties together is a Canvas showing an animation of continental drift over the course of Earth history, where the spatialScale could convey that each Canvas unit is several thousand meters, and each second of the Canvas `duration` is several million years. From b0e6762c5fca9ba77368d7fb87502c9265b216a3 Mon Sep 17 00:00:00 2001 From: Rob Sanderson Date: Mon, 2 Jun 2025 15:17:14 +0100 Subject: [PATCH 101/130] push? --- source/presentation/4.0/index.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index abd3dba33..c2aac18de 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -329,9 +329,11 @@ The fragment example above can be expressed using a Specific Resource: ## Use Case 1: Artwork -This example is a Manifest with one Canvas, representing a 2D surface. In this case the Canvas represents an artwork, and there is no duration property. The content resource, a JPEG image of the artwork, is associated with the Canvas via a Painting Annotation. The unit integer coordinates of the Canvas (12000 x 9000) are not the same as the pixel dimensions of the JPEG image (4000 x 3000), but they are proportional - the Canvas has a 4:3 landscape aspect ratio, and so does the JPEG image. The `target` property of the Annotation is the Canvas `id`, unqualified by any particular region; this is taken to mean the content (the image) should fill the Canvas completely. As the Canvas and the image are the same aspect ratio, no distortion will occur. This approach allows the current image to be replaced by a higher resolution image in future, on the same Canvas. The Canvas dimensions establish a coordinate system for _painting annotations_ and other kinds of annotation that link content with the Canvas; they are not pixels of images. +This example is a Manifest with one Canvas, representing an artwork. The content resource, a JPEG image of the artwork, is associated with the Canvas via a Painting Annotation. -It demonstrates the use of the common descriptive properties `label` for the title of the artwork, `metadata` for additional information to display to the user, `summary` for a brief description of the artwork, `rights` to assert a rights statement or license from a controlled vocabulary, `homepage` to link to the artwork's specific web page, `thumbnail` to provide a small image to stand for the Manifest, and `provider` to give information about the publisher of the Manifest. +The unit integer coordinates of the Canvas (12000 x 9000) are not the same as the pixel dimensions of the JPEG image (4000 x 3000), but they are proportional - the Canvas has a 4:3 landscape aspect ratio, and so does the JPEG image.The `target` property of the Annotation is the Canvas `id`, unqualified by any particular region; this is taken to mean the content (the image) should fill the Canvas completely. As the Canvas and the image are the same aspect ratio, no distortion will occur. This approach allows the current image to be replaced by a higher resolution image in future, on the same Canvas. The Canvas dimensions establish a coordinate system for _painting annotations_ and other kinds of annotation that link content with the Canvas; they are not pixels of images. + +The example demonstrates the use of the common descriptive properties `label` for the title of the artwork, `metadata` for additional information to display to the user, `summary` for a brief description of the artwork, `rights` to assert a rights statement or license from a controlled vocabulary, `homepage` to link to the artwork's specific web page, `thumbnail` to provide a small image to stand for the Manifest, and `provider` to give information about the publisher of the Manifest. ```json { @@ -428,6 +430,7 @@ It demonstrates the use of the common descriptive properties `label` for the tit ``` **Key Points** + * All IIIF documents begin with the `@context` key, which maps the JSON structure into a linked data representation. The value identifies the version of the specification in use. [👀 Model Documentation](model/#json-ld-contexts-and-extensions) * Every JSON object that has a `type` property also has an `id` property and vice versa. * Text elements intended for display to the user are conveyed by _Language Maps_, JSON objects in which the keys are language codes and the values are lists of one or more strings in that language. [👀 Model Documentation](model/#language-of-property-values) @@ -436,8 +439,13 @@ It demonstrates the use of the common descriptive properties `label` for the tit * The `rights` property is always a single string value which is a URI. {: .note} +!!! warning TODO: The above should be a green class rgb(244,252,239) to distinguish from properties + +__Definitions__
+Classes: [Manifest](#model/Manifest), ...

+Properties: [id](#model/id), [type](#type), [label](#label), [lookAt](#lookAt), [near](#near), and [far](#far) +{: .note} -> List of properties used with links to model for each ## Example 2: Book From 3a9576de4dd5606bf63aa9297f80dc8ddf08f1b8 Mon Sep 17 00:00:00 2001 From: Rob Sanderson Date: Mon, 2 Jun 2025 15:24:38 +0100 Subject: [PATCH 102/130] css :( --- 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 c2aac18de..303bccee3 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -429,8 +429,9 @@ The example demonstrates the use of the common descriptive properties `label` fo } ``` -**Key Points** +> +**Key Points** * All IIIF documents begin with the `@context` key, which maps the JSON structure into a linked data representation. The value identifies the version of the specification in use. [👀 Model Documentation](model/#json-ld-contexts-and-extensions) * Every JSON object that has a `type` property also has an `id` property and vice versa. * Text elements intended for display to the user are conveyed by _Language Maps_, JSON objects in which the keys are language codes and the values are lists of one or more strings in that language. [👀 Model Documentation](model/#language-of-property-values) From a229838f5df376de0c6d233275dc76f7a943aa84 Mon Sep 17 00:00:00 2001 From: Dawn Childress Date: Tue, 3 Jun 2025 07:03:14 -0700 Subject: [PATCH 103/130] add book use case json --- source/presentation/4.0/index.md | 128 ++++++++++++++++++++++++++++++- 1 file changed, 124 insertions(+), 4 deletions(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index 303bccee3..5f278d4ec 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -448,15 +448,135 @@ Properties: [id](#model/id), [type](#type), [label](#label), [lookAt](#lookAt), {: .note} -## Example 2: Book +## Use Case 2: Book This example is a Manifest with multiple Canvases, each of which represents a page of a book. It demonstrates the use of the `behavior` property to indicate to a client that the object is _paged_: this helps a client generate the correct user experience. The `viewingDirection` property indicates that the book is read left-to-right. In this case, the property is redundant as `left-to-right` is the default value. The Manifest has a `rendering` property linking to a PDF representation; typically a client would offer this as a download or "view as" option. The `start` property is used to tell a client to initialize the view on a particular Canvas, useful if the digitized work contains a large amount of irrelevant front matter or blank pages. The `requiredStatement` is a message that a client MUST show to the user when presenting the Manifest. -``` -Example: a paged thing - a book -requiredStatement, behavior, viewingDirection, (no Ranges), rendering - PDF version, start +```json +{ + "@context": "http://iiif.io/api/presentation/4/context.json", + "id": "https://example.org/iiif/presentation/examples/manifest-with-book.json", + "type": "Manifest", + "label": { "en": [ "Use case 2: Book" ] }, + "behavior": [ "paged" ], + "viewingDirection": "left-to-right", + "rendering": [ + { + "id": "https://example.org/pdfs/book.pdf", + "type": "Text", + "label": { "en": [ "PDF version" ] }, + "format": "application/pdf" + } + ], + "start": { + "id": "https://example.org/iiif/presentation/examples/manifest-with-book/canvas/c2", + "type": "Canvas" + }, + "requiredStatement": { + "label": { "en": [ "Attribution" ] }, + "value": { "en": [ "Provided courtesy of Example Institution" ] } + }, + "items": [ + { + "id": "https://example.org/iiif/presentation/examples/manifest-with-book/canvas/c1", + "type": "Canvas", + "label": { "en": [ "Blank page" ] }, + "height": 4613, + "width": 3204, + "items": [ + { + "id": "https://example.org/iiif/presentation/examples/manifest-with-book/page/p1", + "type": "AnnotationPage", + "items": [ + { + "id": "https://example.org/iiif/presentation/examples/manifest-with-book/annotation/a1", + "type": "Annotation", + "motivation": [ "painting" ], + "body": { + "id": "https://iiif.io/api/presentation/example-content-resources/image/page1.jpg", + "type": "Image", + "format": "image/jpeg", + "height": 4613, + "width": 3204, + }, + "target": "https://example.org/iiif/presentation/examples/manifest-with-book/canvas/c1" + } + ] + } + ] + }, + { + "id": "https://example.org/iiif/presentation/examples/manifest-with-book/canvas/c2", + "type": "Canvas", + "label": { "en": [ "Frontispiece" ] }, + "height": 4613, + "width": 3204, + "items": [ + { + "id": "https://example.org/iiif/presentation/examples/manifest-with-book/page/p2", + "type": "AnnotationPage", + "items": [ + { + "id": "https://example.org/iiif/presentation/examples/manifest-with-book/annotation/a2", + "type": "Annotation", + "motivation": [ "painting" ], + "body": { + "id": "https://iiif.io/api/presentation/example-content-resources/image/page2.jpg", + "type": "Image", + "format": "image/jpeg", + "height": 4613, + "width": 3204, + }, + "target": "https://example.org/iiif/presentation/examples/manifest-with-book/canvas/c2" + } + ] + } + ] + }, + { + "id": "https://example.org/iiif/presentation/examples/manifest-with-book/canvas/c3", + "type": "Canvas", + "label": { "en": [ "Title Page" ] }, + "height": 4613, + "width": 3204, + "items": [ + { + "id": "https://example.org/iiif/presentation/examples/manifest-with-book/page/p3", + "type": "AnnotationPage", + "items": [ + { + "id": "https://example.org/iiif/presentation/examples/manifest-with-book/annotation/a3", + "type": "Annotation", + "motivation": [ "painting" ], + "body": { + "id": "https://iiif.io/api/presentation/example-content-resources/image/page3.jpg", + "type": "Image", + "format": "image/jpeg", + "height": 4613, + "width": 3204, + }, + "target": "https://example.org/iiif/presentation/examples/manifest-with-book/canvas/c3" + } + ] + } + ] + }, + // Additional Canvases... + ] +} ``` +> +**Key Points** +* Recommend using Canvas labels when more than one Canvas... +{: .note} + +!!! warning TODO: The above should be a green class rgb(244,252,239) to distinguish from properties + +__Definitions__
+Classes: [Manifest](#model/Manifest), ...

+Properties: [behavior](#model/behavior), [viewingDirection](#model/viewingDirection), [start](#model/start), [rendering](#model/rendering), [requiredStatement](#model/requiredStatement) +{: .note} # Audio and Video From ef53e08003fd012ea5b5297d76b86c631c56c0f9 Mon Sep 17 00:00:00 2001 From: Rob Sanderson Date: Wed, 4 Jun 2025 13:38:23 +0100 Subject: [PATCH 104/130] anchors --- source/presentation/4.0/model.md | 45 +++++++++++++++++++++----------- 1 file changed, 30 insertions(+), 15 deletions(-) diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index 40712425f..ad8be5db9 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -54,12 +54,14 @@ __Previous Version:__ [3.0][prezi30] # IIIF Presentation API Data Model ## Introduction +{: #introduction} The IIIF Presentation API is backed by a standards-based data model inspired by both earlier tree structured representations of cultural heritage objects, as well as linked data approaches with the same goal. It comprises four main types of resource: Structural (such as Collections, Manifests, and Ranges), Presentational Containers (Canvas, Scene and Timeline), Linking (Annotations), and Content (the images, texts, audio, video and models to be displayed). The model intentionaly does not include any semantic or descriptive relationships or properties such as the author of a book or the place where a statue was sculpted; it is solely for presenting content in a structured fashion to human users. ### Terminology +{: #terminology} This specification uses the following terms: @@ -73,14 +75,17 @@ The key words _MUST_, _MUST NOT_, _REQUIRED_, _SHALL_, _SHALL NOT_, _SHOULD_, _S ## JSON Considerations +{: #json-considerations} This section describes features applicable to all of the Presentation API content. ### Case Sensitivity +{: #case-sensitivity} Keys in JSON objects are [case sensitive][org-w3c-json-ld-case]. The cases of properties and enumerated values in IIIF Presentation API responses _MUST_ match those used in this specification. For example to specify that a resource is a Manifest, the property _MUST_ be given as `type` and not `Type` or `tYpE`, and the value _MUST_ be given as `Manifest` and not `manifest` or `manIfEsT`. ### Properties with Multiple Values +{: #properties-with-multiple-values} Any of the properties in the API that can have multiple values _MUST_ always be given as an array of values, even if there is only a single item in that array. @@ -521,7 +526,7 @@ A Visual Content Selector _MUST_ have the following properties: [id](#id), and [ #### Animation Selector - +{: #AnimationSelector} > `"type": "AnimationSelector"` More interactive content resources, such as 3D models, may have animations or similar features that can be _activated_ by user interaction. For example, a model of a box might have an animation that opens the lid and a second animation that closes the lid. In order to activate those animations, they need to be selectable, and thus the specification defines an Animation Selector. The identity of the activatable aspect is given in the `value` property. @@ -539,7 +544,7 @@ An Animation Selector _MUST_ have the following properties: [id](#id), [type](#t ``` #### IIIF Image API Selector - +{: #ImageApiSelector} > `"type": "ImageApiSelector"` The Image API Selector is used to describe the operations available via the IIIF Image API in order to retrieve a particular image representation. In this case the resource is the abstract image as identified by the [IIIF Image API][image-api] base URI plus identifier, and the retrieval process involves adding the correct parameters after that base URI. @@ -570,7 +575,7 @@ A IIIF Image API Selector _MAY_ have the following properties: [region](#region) ``` ### Range - +{: #Range} > `"type": "Range"` Ranges are used to represent structure within a Manifest beyond the default order of the Containers in the `items` property. @@ -587,10 +592,12 @@ A Range _MAY_ have the following properties: [start](#start), [supplementary](#s ### Scene Components +{: #scene-components} The following classes are only usable within Scenes. #### Cameras +{: #Camera} A Camera provides a view of a region of a Scene's space from a particular position within the Scene; the client constructs a viewport into the Scene and uses the Camera to render that region. The size and aspect ratio of the viewport is client and device dependent. @@ -603,6 +610,7 @@ All Cameras _MAY_ have the following properties: [label](#label), [lookAt](#look ##### Orthographic Camera +{: #OrthographicCamera} > `"type": "OrthographicCamera"` @@ -624,7 +632,7 @@ Orthographic Cameras _SHOULD_ have the following additional properties: [viewHei ##### Perspective Camera - +{: #PerspectiveCamera} > `"type": "PerspectiveCamera"` A Perspective Camera mimics the way the human eye sees, in that objects further from the camera are smaller. @@ -647,6 +655,7 @@ Perspective Cameras _SHOULD_ have the following additional properties: [fieldOfV ``` #### Lights +{: #Light} It is necessary for there to be a Light within a Scene that illuminates the objects. If no Light is provided by the Scene's description, then the client _MUST_ add a Light. @@ -662,7 +671,7 @@ All Lights _MAY_ have the following properties: [label](#label). ##### Ambient Light - +{: #AmbientLight} > `"type": "AmbientLight"` Ambient Light evenly illuminates all objects in the Scene, and does not have a direction or position. It does not have any new properties. The Light itself _MUST_ be added into the scene at a specific position, however this is only such that editing interfaces can render the object to the user. @@ -677,7 +686,7 @@ Ambient Light evenly illuminates all objects in the Scene, and does not have a d ``` ##### Directional Light - +{: #DirectionalLight} > `"type": "DirectionalLight"` Directional Lights emit their light in a specific direction as if infinitely far away, and as such the light does not come from a specific position. The rays produced are all parallel. The Light itself _MUST_ be added into the scene at a specific position, however this is only such that editing interfaces can render the object to the user. @@ -699,7 +708,7 @@ Directional Lights _MAY_ have the following additional properties: [lookAt](#loo ``` ##### Point Light - +{: #PointLight} > `"type": "PointLight"` Point Lights emit in all directions from a single point within the Scene. @@ -715,7 +724,7 @@ Point Lights emit in all directions from a single point within the Scene. ##### Spot Light - +{: #SpotLight} > `"type": "SpotLight"` Spot Light emits a cone of light in a given direction from a single point. The Spot Light's `angle` property defines the radius of the cone. The default angle is client dependent if not specified. @@ -746,6 +755,7 @@ Spot Lights _MAY_ have the following additional properties: [lookAt](#lookAt) ``` #### Audio Emitters +{: #AudioEmitters} Positional audio is supported through the use of Audio Emitter resources annotated into Scenes, in the same way that light is emitted from the various subclasses of Light. @@ -760,7 +770,7 @@ All Audio Emitters _MAY_ have the following properties: [label](#label). {: .note} ##### Ambient Audio - +{: #AmbientAudio} > `"type": "AmbientAudio"` Ambient Audio emits equally throughout the Scene, and does not have a position or direction. The Emitter _MUST_ be annotated somewhere within the Scene so that it can be rendered by editing interfaces, and exists within the Scene's hierarchy. @@ -779,7 +789,7 @@ Ambient Audio emits equally throughout the Scene, and does not have a position o ``` ##### Point Audio - +{: #PointAudio} > `"type": "PointAudio"` Point Audio emits in all directions from a single point in the Scene. @@ -798,6 +808,7 @@ Point Audio emits in all directions from a single point in the Scene. ``` ##### Spot Audio +{: #SpotAudio} > `"type": "SpotAudio"` @@ -831,6 +842,7 @@ Spot Audio Emitters _MAY_ have the following additional properties: [lookAt](#lo ``` #### Transforms +{: #Transforms} An operation to transform a 3D resource. Transforms are specified by the [transform](#transform) property on a Specific Resource. Transforms are carried out on a resource in the implicit or explicit local coordinate space of the resource, and are performed prior to painting that resource into any subsequent coordinate space. @@ -840,7 +852,7 @@ All Transforms _MAY_ have the following properties: [label](#label), [x](#x), [y {: .note} ##### Rotate Transform - +{: #RotateTransform} > `"type": "RotateTransform"` A Rotate Transform rotates the resource around one or more axes. If present, the values of properties `x`, `y`, and `z` _MUST_ be angular values in degrees that specify the extent of rotation around each axis. Positive angular values indicate counter-clockwise rotation around the axis due to coordinate right-handedness. Axis rotation is performed with a pivot point at the origin of the local coordinate space. As an example, for a point at (1, 1, 0) in local coordinate space, rotating 90 degrees around the x axis would transform the point to be at (1, 0, 1). If any property `x`, `y`, or `z` is not specified or is specified to be 0.0, rotation around that axis does not occur. When more than one axis rotation is specified through multiple non-zero values for `x`, `y`, and `z`, rotations comprise a Euler angle with ordering x-y-z, and rotation _MUST_ be carried out first around the x axis, second around the y axis, and third around the z axis. @@ -857,7 +869,7 @@ A Rotate Transform rotates the resource around one or more axes. If present, the ``` ##### Scale Transform - +{: #ScaleTransform} > `"type": "ScaleTransform"` A Scale Transform scales the resource along one or more axes. If present, the values of properties `x`, `y`, and `z` _MUST_ be multiplicative scale factors that specify the extent of scaling along each axis. As an example, for a point at 3.5 along the x axis in local coordinate space, scaling along the x axis by 2.0 would result in the point being at 7.0. If any property `x`, `y`, or `z` is not specified or is specified to be 1.0, scaling does not occur along that axis. Negative scale factor values indicate mirroring as well as scaling along that axis. @@ -874,7 +886,7 @@ A Scale Transform scales the resource along one or more axes. If present, the va ``` ##### Translate Transform - +{: #TranslateTransform} > `"type": "TranslateTransform"` A Translate Transform translates or moves the resource across one or more axes. If present, the values of properties `x`, `y`, and `z` _MUST_ be coordinate unit distances that specify the distance across each axis to translate the resource. As an example, for a point at 1.0 along the x axis, translating across the x axis by 3.0 would result in the point being at 4.0. If any property `x`, `y`, or `z` is not present or is specified to be 0.0, translation does not occur across that axis. @@ -891,9 +903,10 @@ A Translate Transform translates or moves the resource across one or more axes. ``` ### Utility Classes +{: #utility-classes} #### Agent - +{: #Agent} > `"type": "Agent"` An Agent represents a person or organization, typically referenced with the `provider` property. @@ -934,6 +947,7 @@ An Agent _MAY_ have the following properties: [seeAlso](#seeAlso), and [summary] #### Service +{: #Service} > `"type": "Service"` @@ -948,6 +962,7 @@ Services will also have specific requirements as to additional properties based #### Unit Value +{: #UnitValue} > `"type": "UnitValue"` @@ -970,7 +985,7 @@ A Unit Value _MAY_ have the following properties: [label](#label). ## Properties - +{: #properties} ### accompanyingContainer {: #accompanyingContainer} From b7e52d41a570e09d9ab84e5698b615858199345d Mon Sep 17 00:00:00 2001 From: Rob Sanderson Date: Wed, 4 Jun 2025 14:32:44 +0100 Subject: [PATCH 105/130] Add fileSize property on Content Resources with rationale --- source/presentation/4.0/model.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index ad8be5db9..b7806a778 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -430,7 +430,7 @@ Containers _MAY_ be treated as content resources for the purposes of annotating __Properties__
A Content Resource _MUST_ have the following properties: [id](#id), and [type](#type)

A Content Resource _SHOULD_ have the following properties: [label](#label)

-A Content Resource _MAY_ have the following properties: [height](#height), [width](#width), [duration](#duration), [language](#language), [format](#format), [metadata](#metadata), [summary](#summary), [provider](#provider), [thumbnail](#thumbnail), [requiredStatement](#requiredStatement), [rights](#rights), [behavior](#behavior), [profile](#profile), [seeAlso](#seeAlso), [service](#service), [homepage](#homepage), [rendering](#rendering), [canonical](#canonical), [via](#via), and [annotations](#annotations).

+A Content Resource _MAY_ have the following properties: [height](#height), [width](#width), [duration](#duration), [language](#language), [format](#format), [fileSize](#fileSize),[metadata](#metadata), [summary](#summary), [provider](#provider), [thumbnail](#thumbnail), [requiredStatement](#requiredStatement), [rights](#rights), [behavior](#behavior), [profile](#profile), [seeAlso](#seeAlso), [service](#service), [homepage](#homepage), [rendering](#rendering), [canonical](#canonical), [via](#via), and [annotations](#annotations).

{: .note} @@ -1231,6 +1231,19 @@ The value _MUST_ be a floating point number greater than 0 and less than 180, an { "fieldOfView": 50.0 } ``` +### fileSize + +The size of a content resource in bytes. This will allow clients to determine whether the resource should be retrieved in the user's current context. For example, the same 3d Model or AV file might be available in multiple formats, and the client can choose the most appropriate one based on the `fileSize` property. + +The value _MUST_ be a positive integer. + +* Any Content Resource _MAY_ have the `fileSize` property.
+ Clients _SHOULD_ process the `fileSize` property on Resources. + +```json-doc +{ "fileSize": 132465987 } +``` + ### first {: #first} From aee20aa4688448d575e2c5f0fac270e4ae27c8a2 Mon Sep 17 00:00:00 2001 From: Dawn Childress Date: Wed, 4 Jun 2025 14:26:59 -0700 Subject: [PATCH 106/130] add json to use case 3 --- source/presentation/4.0/index.md | 149 +++++++++++++++++++++++++++++-- 1 file changed, 140 insertions(+), 9 deletions(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index 5f278d4ec..15696fa18 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -561,7 +561,7 @@ This example is a Manifest with multiple Canvases, each of which represents a pa } ] }, - // Additional Canvases... + // Additional Canvases ] } ``` @@ -581,21 +581,152 @@ Properties: [behavior](#model/behavior), [viewingDirection](#model/viewingDirect # Audio and Video -## Example: a 45 single with one Timeline per song/side +## Use Case 3: a 45 single with one Timeline per song/side This example is a Manifest with two Timelines, each of which represent a temporal extent during which a song is played. As in most cases, the Timeline `duration` is the same length as that of Content Resource painted into it. This example is a recording digitized from a 45 RPM 7 inch single. It demonstrates the use of `format` for the audio files' content type, `language` (One song is in English and one is in German), `behavior` with value "autoPlay" that tells a client to automatically advance to the second Timeline after playing the first, `annotations` that link to Annotation Pages of annotations with the motivation `supplementing` that provide the lyrics (one example is given afterwards) - and an `accompanyingContainer` that carries a picture of the single's cover that is shown while the songs are playing. -``` -Timeline -duration, autoPlay, format, annotations (transcript), language, accompanyingContainer +```json +{ + "@context": "http://iiif.io/api/presentation/4/context.json", + "id": "https://example.org/iiif/presentation/examples/manifest-with-audio.json", + "type": "Manifest", + "label": { "en": [ "Use case 3: 45 single with 2 tracks" ] }, + "behavior": [ "autoPlay" ], + "accompanyingContainer": { + "id": "https://example.org/iiif/presentation/examples/manifest-with-audio/accompany/c1", + "type": "Canvas", + "label": { "en": [ "Photo of cover sleeve" ] }, + "height": 900, + "width": 900, + "items": [ + { + "id": "https://example.org/iiif/presentation/examples/manifest-with-audio/accompany/c1/page", + "type": "AnnotationPage", + "items": [ + { + "id": "https://example.org/iiif/presentation/examples/manifest-with-audio/accompany/c1/image", + "type": "Annotation", + "motivation": "painting", + "body": { + "id": "https://example.org/presentation/example-content-resources/image/cover.jpg", + "type": "Image", + "format": "image/jpeg", + "height": 900, + "width": 900 + }, + "target": "https://example.org/iiif/presentation/examples/manifest-with-audio/accompany/ac1" + } + ] + } + ] + }, + + "items": [ + { + "id": "https://example.org/iiif/presentation/examples/manifest-with-audio/timeline/t1", + "type": "Timeline", + "label": { "en": [ "Side A: 99 Luftballons" ] }, + "duration": 242.40, + "items": [ + { + "id": "https://example.org/iiif/presentation/examples/manifest-with-audio/track/tr1", + "type": "AnnotationPage", + "items": [ + { + "id": "https://example.org/iiif/presentation/examples/manifest-with-audio/annotation/a1", + "type": "Annotation", + "motivation": [ "painting" ], + "body": { + "id": "https://example.org/presentation/example-content-resources/audio/track1.mp4", + "type": "Sound", + "format": "audio/mp4", + "duration": 242.40, + "language": [ "de" ], + }, + "target": "https://example.org/iiif/presentation/examples/manifest-with-audio/timeline/t1" + } + ] + } + ] + }, + { + "id": "https://example.org/iiif/presentation/examples/manifest-with-audio/timeline/t2", + "type": "Timeline", + "label": { "en": [ "Side B: 99 Red Balloons" ] }, + "duration": 242.40, + "items": [ + { + "id": "https://example.org/iiif/presentation/examples/manifest-with-audio/track/tr2", + "type": "AnnotationPage", + "items": [ + { + "id": "https://example.org/iiif/presentation/examples/manifest-with-audio/annotation/a2", + "type": "Annotation", + "motivation": [ "painting" ], + "body": { + "id": "https://example.org/presentation/example-content-resources/audio/track2.mp4", + "type": "Sound", + "format": "audio/mp4", + "duration": 242.40, + "language": [ "en" ], + }, + "target": "https://example.org/iiif/presentation/examples/manifest-with-audio/timeline/t2" + } + ] + } + ] + } + ], + "annotations": [ + { + "id": "https://example.org/iiif/presentation/examples/external-anno.json", + "type": "AnnotationPage", + } + } ``` +```json +{ + "@context": "http://iiif.io/api/presentation/3/context.json", + "id": "https://example.org/iiif/presentation/examples/external-anno.json", + "type": "AnnotationPage", + "items": [ + { + "id": "https://example.org/iiif/presentation/examples/external-anno/a1", + "type": "Annotation", + "motivation": "supplementing", + "body": { + "id": "https://example.org/presentation/example-content-resources/lyrics1.txt", + "type": "TextualBody", + "language": "de", + "format": "text/plain", + "value": "Hast du etwas Zeit für mich?" + }, + "target": { + "type": "SpecificResource", + "source": "https://example.org/iiif/presentation/examples/manifest-with-audio/timeline/t1", + "selector": { + "type": "PointSelector", + "instant": 3.5 + } + } + ] +} ``` -... - (A single supplementing annotation for a line of the song) t= fragment -... -``` + +> +**Key Points** +* t vs. instant / verbose vs. append to URI??? +{: .note} + +!!! warning TODO: The above should be a green class rgb(244,252,239) to distinguish from properties + +__Definitions__
+Classes: [Manifest](#model/Manifest), ...

+Properties: [duration](#model/duration), [format](#model/format), [language](#model/language), [behavior](#model/behavior), [annotations](#model/annotations), [accompanyingContainer](#model/accompanyingContainer) +{: .note} + ## Example: a movie with subtitles From 459be328f6e49860a8e6ad4dc1a44e19c9536c35 Mon Sep 17 00:00:00 2001 From: Dawn Childress Date: Wed, 4 Jun 2025 14:41:16 -0700 Subject: [PATCH 107/130] use case 3 anno --- source/presentation/4.0/index.md | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index 15696fa18..d1bc41134 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -703,13 +703,7 @@ This example is a Manifest with two Timelines, each of which represent a tempora "format": "text/plain", "value": "Hast du etwas Zeit für mich?" }, - "target": { - "type": "SpecificResource", - "source": "https://example.org/iiif/presentation/examples/manifest-with-audio/timeline/t1", - "selector": { - "type": "PointSelector", - "instant": 3.5 - } + "target": "https://example.org/iiif/presentation/examples/manifest-with-audio/timeline/t1#instant=3.5" } ] } From da9590e676f449585627ca955f0930a3814c8619 Mon Sep 17 00:00:00 2001 From: Dawn Childress Date: Thu, 5 Jun 2025 07:16:08 -0700 Subject: [PATCH 108/130] fix auto-advance in use case 3 --- source/presentation/4.0/index.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index d1bc41134..519c07eaf 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -583,7 +583,7 @@ Properties: [behavior](#model/behavior), [viewingDirection](#model/viewingDirect ## Use Case 3: a 45 single with one Timeline per song/side -This example is a Manifest with two Timelines, each of which represent a temporal extent during which a song is played. As in most cases, the Timeline `duration` is the same length as that of Content Resource painted into it. This example is a recording digitized from a 45 RPM 7 inch single. It demonstrates the use of `format` for the audio files' content type, `language` (One song is in English and one is in German), `behavior` with value "autoPlay" that tells a client to automatically advance to the second Timeline after playing the first, `annotations` that link to Annotation Pages of annotations with the motivation `supplementing` that provide the lyrics (one example is given afterwards) - and an `accompanyingContainer` that carries a picture of the single's cover that is shown while the songs are playing. +This example is a Manifest with two Timelines, each of which represent a temporal extent during which a song is played. As in most cases, the Timeline `duration` is the same length as that of Content Resource painted into it. This example is a recording digitized from a 45 RPM 7 inch single. It demonstrates the use of `format` for the audio files' content type, `language` (One song is in English and one is in German), `behavior` with value "auto-advance" that tells a client to automatically advance to the second Timeline after playing the first, `annotations` that link to Annotation Pages of annotations with the motivation `supplementing` that provide the lyrics (one example is given afterwards) - and an `accompanyingContainer` that carries a picture of the single's cover that is shown while the songs are playing. ```json @@ -592,7 +592,7 @@ This example is a Manifest with two Timelines, each of which represent a tempora "id": "https://example.org/iiif/presentation/examples/manifest-with-audio.json", "type": "Manifest", "label": { "en": [ "Use case 3: 45 single with 2 tracks" ] }, - "behavior": [ "autoPlay" ], + "behavior": [ "auto-advance" ], "accompanyingContainer": { "id": "https://example.org/iiif/presentation/examples/manifest-with-audio/accompany/c1", "type": "Canvas", @@ -627,7 +627,7 @@ This example is a Manifest with two Timelines, each of which represent a tempora "id": "https://example.org/iiif/presentation/examples/manifest-with-audio/timeline/t1", "type": "Timeline", "label": { "en": [ "Side A: 99 Luftballons" ] }, - "duration": 242.40, + "duration": 231, "items": [ { "id": "https://example.org/iiif/presentation/examples/manifest-with-audio/track/tr1", @@ -641,7 +641,7 @@ This example is a Manifest with two Timelines, each of which represent a tempora "id": "https://example.org/presentation/example-content-resources/audio/track1.mp4", "type": "Sound", "format": "audio/mp4", - "duration": 242.40, + "duration": 231, "language": [ "de" ], }, "target": "https://example.org/iiif/presentation/examples/manifest-with-audio/timeline/t1" @@ -654,7 +654,7 @@ This example is a Manifest with two Timelines, each of which represent a tempora "id": "https://example.org/iiif/presentation/examples/manifest-with-audio/timeline/t2", "type": "Timeline", "label": { "en": [ "Side B: 99 Red Balloons" ] }, - "duration": 242.40, + "duration": 230.5, "items": [ { "id": "https://example.org/iiif/presentation/examples/manifest-with-audio/track/tr2", @@ -668,7 +668,7 @@ This example is a Manifest with two Timelines, each of which represent a tempora "id": "https://example.org/presentation/example-content-resources/audio/track2.mp4", "type": "Sound", "format": "audio/mp4", - "duration": 242.40, + "duration": 230.5, "language": [ "en" ], }, "target": "https://example.org/iiif/presentation/examples/manifest-with-audio/timeline/t2" From 4f69435c3b1cb1842ea7bae71444de7240dd02e4 Mon Sep 17 00:00:00 2001 From: Dawn Childress Date: Fri, 6 Jun 2025 00:46:39 -0700 Subject: [PATCH 109/130] example 3 movie json --- source/presentation/4.0/index.md | 123 ++++++++++++++++++++++++++++++- 1 file changed, 120 insertions(+), 3 deletions(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index 519c07eaf..179ef5e57 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -581,7 +581,7 @@ Properties: [behavior](#model/behavior), [viewingDirection](#model/viewingDirect # Audio and Video -## Use Case 3: a 45 single with one Timeline per song/side +## Use Case 3: A 45 single with 2 tracks This example is a Manifest with two Timelines, each of which represent a temporal extent during which a song is played. As in most cases, the Timeline `duration` is the same length as that of Content Resource painted into it. This example is a recording digitized from a 45 RPM 7 inch single. It demonstrates the use of `format` for the audio files' content type, `language` (One song is in English and one is in German), `behavior` with value "auto-advance" that tells a client to automatically advance to the second Timeline after playing the first, `annotations` that link to Annotation Pages of annotations with the motivation `supplementing` that provide the lyrics (one example is given afterwards) - and an `accompanyingContainer` that carries a picture of the single's cover that is shown while the songs are playing. @@ -722,13 +722,119 @@ Properties: [duration](#model/duration), [format](#model/format), [language](#mo {: .note} -## Example: a movie with subtitles +## Use Case 4: Movie with subtitles This example is a Manifest with one Canvas that represents the temporal extent of the movie (the Canvas `duration`) and its aspect ratio (given by the `width` and `height` of the Canvas). The example demonstrates the use of a `Choice` annotation body to give two alternative versions of the movie, the `timeMode` property ..., and `placeholderContainer` that provides a poster image to show in place of the video file before the user initiates playback. +```json +{ + "@context": "http://iiif.io/api/presentation/4/context.json", + "id": "https://example.org/iiif/presentation/examples/manifest-with-movie.json", + "type": "Manifest", + "label": { "en": [ "Use Case 4: Movie with Subtitles" ] }, + "items": [ + { + "id": "https://example.org/iiif/presentation/examples/manifest-with-movie/canvas", + "type": "Canvas", + "height": 360, + "width": 480, + "duration": 3600, + "timeMode": "trim", + "placeholderContainer": { + "id": "https://example.org/iiif/presentation/examples/manifest-with-movie/placeholder", + "type": "Canvas", + "height": 320, + "width": 400, + "items": [ + { + "id": "https://example.org/image/placeholder/annopage", + "type": "AnnotationPage", + "items": [ + { + "id": "https://example.org/iiif/presentation/examples/manifest-with-movie/placeholder/image", + "type": "Annotation", + "motivation": "painting", + "body": { + "id": "https://example.org/image/placeholder.png", + "type": "Image", + "format": "image/png", + "height": 320, + "width": 400, + }, + "target": "https://iiif.io/api/cookbook/recipe/0013-placeholderCanvas/canvas/donizetti/placeholder" + } + ] + } + ] + }, + "items": [ + { + "id": "https://example.org/iiif/presentation/examples/manifest-with-movie/annopage1", + "type": "AnnotationPage", + "items": [ + { + "id": "https://example.org/iiif/presentation/examples/manifest-with-movie/anno1", + "type": "Annotation", + "motivation": "painting", + "body": { + "type": "Choice", + "items": [ + { + "id": "https://example.org/video/movie.mp4", + "type": "Video", + "height": 360, + "width": 480, + "duration": 3599.68, + "format": "video/mp4" + }, + { + "id": "https://example.org/video/movie.flv", + "type": "Video", + "height": 360, + "width": 480, + "duration": 3600.8, + "format": "video/flv" + } + ] + }, + "target": "https://example.org/iiif/presentation/examples/manifest-with-movie/canvas" + } + ] + } + ], + "annotations": [ + { + "id": "https://example.org/iiif/presentation/examples/manifest-with-movie/subtitles", + "type": "AnnotationPage", + "items": [ + { + "id": "https://example.org/iiif/presentation/examples/manifest-with-movie/subtitles/anno", + "type": "Annotation", + "motivation": "supplementing", + "body": { + "id": "https://example.org/text/subtitles.vtt", + "type": "Text", + "format": "text/vtt", + "label": { + "en": [ + "Subtitles in WebVTT format" + ] + }, + "language": "en" + }, + "target": "https://example.org/iiif/presentation/examples/manifest-with-movie/canvas" + } + ] + } + ] + } + ] +} +``` + ``` Canvas -duration, behavior=autoplay, format, Choice of video 720p, 4K? (forward ref), timeMode, placeholderContainer +duration, behavior=auto-advance, format, Choice of video 720p, 4K? (forward ref), timeMode, placeholderContainer ``` { @@ -743,6 +849,17 @@ duration, behavior=autoplay, format, Choice of video 720p, 4K? (forward ref), ti Sometimes, two different formats derived from the same source may have slightly different durations, perhaps a few milliseconds out. What to do... +> +**Key Points** +* +{: .note} + +!!! warning TODO: The above should be a green class rgb(244,252,239) to distinguish from properties + +__Definitions__
+Classes: [Manifest](#model/Manifest), ...

+Properties: [duration](#model/duration), [format](#model/format), [timeMode](#model/timeMode), [behavior](#model/behavior), [placeholderContainer](#model/placeholderContainer) +{: .note} # 3D From cc0aad5152ed9dcbfd8ff19ea77c976592a4ee55 Mon Sep 17 00:00:00 2001 From: Rob Sanderson Date: Fri, 6 Jun 2025 10:26:43 +0100 Subject: [PATCH 110/130] Start to update id, props, fileSize --- source/presentation/4.0/model.md | 70 ++++++++++++++++++++++---------- 1 file changed, 49 insertions(+), 21 deletions(-) diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index b7806a778..2cd75396f 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -378,9 +378,9 @@ A Specific Resource is a resource in the context of an Annotation. They are used A Specific Resource _MUST_ have an HTTP(S) URI given in `id`. This allows for it to be addressed by other parts of the model, such as Content State Annotations. __Properties__
-A Specific Resource _MUST_ have the following properties: [id](#id), [type](#type), [source](#source)

+A Specific Resource _MUST_ have the following properties: [type](#type), [source](#source)

A Specific Resource _SHOULD_ have the following properties: [selector](#selector)

-A Specific Resource _MAY_ have the following properties: [position](#position), [transform](#transform), [scope](#scope), [styleClass](#styleClass), [height](#height), [width](#width), [duration](#duration), [language](#language), [label](#label), [metadata](#metadata), [summary](#summary), [provider](#provider), [thumbnail](#thumbnail), [requiredStatement](#requiredStatement), [rights](#rights), [behavior](#behavior), [seeAlso](#seeAlso), [service](#service), [homepage](#homepage), [rendering](#rendering), [canonical](#canonical), [via](#via), and [annotations](#annotations).

+A Specific Resource _MAY_ have the following properties: [id](#id), [position](#position), [transform](#transform), [scope](#scope), [styleClass](#styleClass), [height](#height), [width](#width), [duration](#duration), [language](#language), [label](#label), [metadata](#metadata), [summary](#summary), [provider](#provider), [thumbnail](#thumbnail), [requiredStatement](#requiredStatement), [rights](#rights), [behavior](#behavior), [seeAlso](#seeAlso), [service](#service), [homepage](#homepage), [rendering](#rendering), [canonical](#canonical), [via](#via), and [annotations](#annotations).

{: .note} #### Textual Body @@ -390,11 +390,10 @@ A Specific Resource _MAY_ have the following properties: [position](#position), A Textual Body is an embedded resource within an Annotation that carries, as the name suggests, a text as the body of the Annotation. It is defined by the Web Annotation Data Model, and this specification defines a new property for `position` that allows it to be positioned within a Container. -A Textual Body _MUST_ have an HTTP(S) URI given in `id`. This allows for it to be addressed by other parts of the model, such as Content State Annotations. __Properties__
-A Textual Body _MUST_ have the following properties: [id](#id), [type](#type), [value](#value)

-A Specific Resource _MAY_ have the following properties: [position](#position), [transform](#transform), [scope](#scope), [styleClass](#styleClass), [height](#height), [width](#width), [duration](#duration), [language](#language), [format](#format), [label](#label), [metadata](#metadata), [summary](#summary), [provider](#provider), [thumbnail](#thumbnail), [requiredStatement](#requiredStatement), [rights](#rights), [behavior](#behavior), [seeAlso](#seeAlso), [service](#service), [homepage](#homepage), [rendering](#rendering), [canonical](#canonical), [via](#via), and [annotations](#annotations).

+A Textual Body _MUST_ have the following properties: [type](#type), [value](#value)

+A Specific Resource _MAY_ have the following properties: [id](#id), [position](#position), [transform](#transform), [scope](#scope), [styleClass](#styleClass), [height](#height), [width](#width), [duration](#duration), [language](#language), [format](#format), [label](#label), [metadata](#metadata), [summary](#summary), [provider](#provider), [thumbnail](#thumbnail), [requiredStatement](#requiredStatement), [rights](#rights), [behavior](#behavior), [seeAlso](#seeAlso), [service](#service), [homepage](#homepage), [rendering](#rendering), [canonical](#canonical), [via](#via), and [annotations](#annotations).

{: .note} @@ -403,14 +402,15 @@ A Specific Resource _MAY_ have the following properties: [position](#position), > `"type": "Choice"` -A Choice is a Web Annotation construction that allows one entry from a list to be selected for processing or display. This specification allows `behavior` and other properties to be added to a Choice to influence how it is processed. +A Choice is a Web Annotation construction that allows one entry from a list to be selected for processing or display. +The client may use any method to determine which item to select, including presenting the Choice to the user for a decision or using the properties of the items to make the decision. In the absence of any information, the client _SHOULD_ select the first item in the array and publishers _SHOULD_ list the items in order of preference. This specification allows `behavior` and other properties to be added to a Choice to influence how it is processed. -A Choice _MUST_ have an HTTP(S) URI given in `id`. It _SHOULD_ have a `label` in order to present the choice to the user, along with its items. This allows for it to be addressed by other parts of the model, such as Content State Annotations. +A Choice _SHOULD_ have a `label` in order to present the choice to the user, along with its items. __Properties__
-A Choice _MUST_ have the following properties: [id](#id), [type](#type), [items](#items)

+A Choice _MUST_ have the following properties: [type](#type), [items](#items)

A Choice _SHOULD_ have the following properties: [label](#label)

-A Choice _MAY_ have the following properties: [metadata](#metadata), [summary](#summary), [provider](#provider), [thumbnail](#thumbnail), [requiredStatement](#requiredStatement), [behavior](#behavior), and [seeAlso](#seeAlso).

+A Choice _MAY_ have the following properties: [id](#id), [metadata](#metadata), [summary](#summary), [provider](#provider), [thumbnail](#thumbnail), [requiredStatement](#requiredStatement), [behavior](#behavior), and [seeAlso](#seeAlso).

{: .note} @@ -450,8 +450,8 @@ There are common use cases in which a point, rather than a range or area, is the If `instant` is not supplied, and the target resource has a `duration`, the selector is interpreted as targeting the entire duration. If `instant` is supplied, but no spatial point, the selector is interpreted as targeting the entire spatial aspect of the resource. __Properties__
-A Point Selector _MUST_ have the following properties: [id](#id), and [type](#type)

-A Point Selector _MAY_ have the following properties: [x](#x), [y](#y), [z](#z), and [instant](#instant).

+A Point Selector _MUST_ have the following properties: [type](#type)

+A Point Selector _MAY_ have the following properties: [id](#id), [x](#x), [y](#y), [z](#z), and [instant](#instant). {: .note} ```json @@ -476,7 +476,8 @@ Well-known text, or WKT, is an ISO standard method for describing 2 and 3 dimens The text representation is given in the `value` property of the selector. __Properties__
-A WKT Selector _MUST_ have the following properties: [id](#id), [type](#type), and [value](#value). +A WKT Selector _MUST_ have the following properties: [type](#type), and [value](#value).

+A WKT Selector _MAY_ have the following properties: [id](#id) {: .note} ```json @@ -495,7 +496,8 @@ A WKT Selector _MUST_ have the following properties: [id](#id), [type](#type), a Video content resources consist of both visual and audio content within the same bit-level representation. There are situations when it is useful to refer to only one aspect of the content – either the visual or the audio, but not both. For example, an Annotation might associate only the visual content of a video that has spoken English in the audio, and an audio file that has the translation of that content in Spanish. The Audio Content Selector selects all of the audio content from an A/V content resource, and may be further refined with subsequent selectors to select a segment of it. __Properties__
-An Audio Content Selector _MUST_ have the following properties: [id](#id), and [type](#type). +An Audio Content Selector _MUST_ have the following properties: [type](#type).

+An Audio Content Selector _MAY_ have the following properties: [id](#id) {: .note} ```json @@ -521,7 +523,8 @@ Similar to Audio Content Selectors, Visual Content Selectors select the visual a ``` __Properties__
-A Visual Content Selector _MUST_ have the following properties: [id](#id), and [type](#type). +A Visual Content Selector _MUST_ have the following properties: [type](#type).

+A Visual Content Selector _MAY_ have the following properties: [id](#id) {: .note} @@ -533,6 +536,7 @@ More interactive content resources, such as 3D models, may have animations or si __Properties__
An Animation Selector _MUST_ have the following properties: [id](#id), [type](#type), and [value](#value). +An Animation Selector _MAY_ have the following properties: [id](#id) {: .note} ```json @@ -1028,6 +1032,7 @@ The value _MUST_ be a floating point number greater than 0 and less than 90, and * A SpotLight _SHOULD_ have the `angle` property.
Clients _SHOULD_ process the `angle` property on SpotLights. +{% include api/code_header.html %} ```json "angle": 15.0 ``` @@ -1078,6 +1083,7 @@ The value _MUST_ be string, which defines an RGB color. It SHOULD be a hex value Clients _SHOULD_ render `backgroundColor` on any resource type. * Other resources _MUST NOT_ have the `backgroundColor` property. +{% include api/code_header.html %} ```json-doc { "backgroundColor": "#FFFFFF" } ``` @@ -1140,6 +1146,11 @@ TODO: Address https://github.com/IIIF/api/issues/2318 { "behavior": [ "auto-advance", "individuals" ] } ``` +### body +{: #body} + + + ### canonical {: #canonical} @@ -1329,17 +1340,20 @@ Please note that this specification has stricter requirements about the JSON pat ] } ``` + ### id {: #id} -The URI that identifies the resource. If the resource is only available embedded within another resource (see the [terminology section][prezi30-terminology] for an explanation of "embedded"), such as a Range within a Manifest, then the URI _MAY_ be the URI of the embedding resource with a unique fragment on the end. This is not true for Canvases, which _MUST_ have their own URI without a fragment. +The URI that identifies the resource. If the resource is only available embedded within another resource (see the [terminology section][prezi30-terminology] for an explanation of "embedded"), such as a Range within a Manifest, then the URI _MAY_ be the URI of the embedding resource with a unique fragment on the end. This is not true for Canvases, which _MUST_ have their own URI without a fragment. -The value _MUST_ be a string, and the value _MUST_ be an HTTP(S) URI for resources defined in this specification. If the resource is retrievable via HTTP(S), then the URI _MUST_ be the URI at which it is published. External resources, such as profiles, _MAY_ have non-HTTP(S) URIs defined by other communities. +The value _MUST_ be a string, and the value _MUST_ be an absolute HTTP(S) URI for resource classes defined or described in this specification. If the resource is retrievable via HTTP(S), then the URI _MUST_ be the URI at which it is published. External resources, such as profiles, _MAY_ have non-HTTP(S) URIs defined by other communities. -The existence of an HTTP(S) URI in the `id` property does not mean that the URI will always be dereferenceable. If the resource with the `id` property is [embedded][prezi30-terminology], it _MAY_ also be dereferenceable. If the resource is referenced (again, see the [terminology section][prezi30-terminology] for an explanation of "referenced"), it _MUST_ be dereferenceable. The [definitions of the Resources][prezi30-resource-structure] give further guidance. +The existence of an HTTP(S) URI in the `id` property does not mean that the URI will always be dereferenceable. If the resource with the `id` property is embedded, it _MAY_ also be dereferenceable. If the resource is referenced, it _MUST_ be dereferenceable. - * All resource types _MUST_ have the `id` property.
+ * Collections, Collection Pages, Manifests, Timelines, Canvases, Scenes, Annotations, Annotation Pages, Annotation Collections, Ranges, Content Resources, and Services _MUST_ have the `id` property.
Clients _MAY_ render `id` on any resource type, and _SHOULD_ render `id` on Collections, Manifests and Canvases. + * All other resources _MAY_ have the `id` property.
+ Clients _MAY_ render `id` on any resource type. {% include api/code_header.html %} ``` json-doc @@ -1349,9 +1363,15 @@ The existence of an HTTP(S) URI in the `id` property does not mean that the URI ### instant {: #instant} -A number (floating point) giving the time of the point in seconds, relative to the duration of the source resource +A floating point number giving the time of the point in seconds from the beginning of the temporal resource. For example, an `instant` value of 4.5 means the exact point 4.5 seconds from the beginning of the resource. -FIXME: fix +* PointSelector _MAY_ have the `instant` property.
+ Clients _SHOULD_ process `instant`. + +{% include api/code_header.html %} +``` json-doc +{ "instant": 4.5 } +``` ### intensity @@ -1549,7 +1569,7 @@ The value _MUST_ be a JSON object, conforming to either a reference to an Annota * A SpotLight or a DirectionalLight _SHOULD_ have the `lookAt` property.
* A SpotSound _SHOULD_ have the `lookAt` property. - +{% include api/code_header.html %} ```json "lookAt": { "type": "PointSelector", @@ -1558,6 +1578,7 @@ The value _MUST_ be a JSON object, conforming to either a reference to an Annota "z": -10 } ``` + ### metadata {: #metadata} @@ -1587,6 +1608,7 @@ Clients _SHOULD_ display the entries in the order provided. Clients _SHOULD_ exp ] } ``` + ### navDate {: #navDate} @@ -1611,6 +1633,7 @@ The value _MUST_ be an [XSD dateTime literal][org-w3c-xsd-datetime]. The value _ ``` json-doc { "navDate": "2010-01-01T00:00:00Z" } ``` + ### navPlace {: #navPlace} @@ -2219,6 +2242,11 @@ The value _MUST_ be a JSON object, which _MUST_ have the `id` and `type` propert { "supplementary": { "id": "https://example.org/iiif/1/annos/1", "type": "AnnotationCollection" } } ``` +### target +{: #target} + +... + ### temporalScale {: #temporalScale} From 135a33c4b78079879f42aaf05ce3069dd666da1e Mon Sep 17 00:00:00 2001 From: tomcrane Date: Fri, 6 Jun 2025 10:31:02 +0100 Subject: [PATCH 111/130] Movie example --- source/presentation/4.0/index.md | 63 ++++++++++++++------------------ 1 file changed, 28 insertions(+), 35 deletions(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index 179ef5e57..883f679c4 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -621,7 +621,6 @@ This example is a Manifest with two Timelines, each of which represent a tempora } ] }, - "items": [ { "id": "https://example.org/iiif/presentation/examples/manifest-with-audio/timeline/t1", @@ -683,9 +682,11 @@ This example is a Manifest with two Timelines, each of which represent a tempora "id": "https://example.org/iiif/presentation/examples/external-anno.json", "type": "AnnotationPage", } - } + ] +} ``` + ```json { "@context": "http://iiif.io/api/presentation/3/context.json", @@ -703,9 +704,10 @@ This example is a Manifest with two Timelines, each of which represent a tempora "format": "text/plain", "value": "Hast du etwas Zeit für mich?" }, - "target": "https://example.org/iiif/presentation/examples/manifest-with-audio/timeline/t1#instant=3.5" + "target": "https://example.org/iiif/presentation/examples/manifest-with-audio/timeline/t1#t=3.5,6.8" } - ] + ], + // (annotations for the rest of the song lines) } ``` @@ -724,7 +726,7 @@ Properties: [duration](#model/duration), [format](#model/format), [language](#mo ## Use Case 4: Movie with subtitles -This example is a Manifest with one Canvas that represents the temporal extent of the movie (the Canvas `duration`) and its aspect ratio (given by the `width` and `height` of the Canvas). The example demonstrates the use of a `Choice` annotation body to give two alternative versions of the movie, the `timeMode` property ..., and `placeholderContainer` that provides a poster image to show in place of the video file before the user initiates playback. +This example is a Manifest with one Canvas that represents the temporal extent of the movie (the Canvas `duration`) and its aspect ratio (given by the `width` and `height` of the Canvas). The example demonstrates the use of a `Choice` annotation body to give two alternative versions of the movie, indicated by their `label` and `fileSize` properties as well as `height` and `width`. Subtitles are provided by an annotation that links to a VTT file. The motivation of this annotation is `supplementing` and the `provides` property of this annotation indicates what accessibility feature it provides, in this case the term `subtitles`. The `timeMode` property in this case is redundant as `trim` is the default value. The Canvas has a `placeholderContainer` that provides a poster image to show in place of the video file before the user initiates playback. ```json { @@ -736,8 +738,8 @@ This example is a Manifest with one Canvas that represents the temporal extent o { "id": "https://example.org/iiif/presentation/examples/manifest-with-movie/canvas", "type": "Canvas", - "height": 360, - "width": 480, + "height": 1080, + "width": 1440, "duration": 3600, "timeMode": "trim", "placeholderContainer": { @@ -780,20 +782,24 @@ This example is a Manifest with one Canvas that represents the temporal extent o "type": "Choice", "items": [ { - "id": "https://example.org/video/movie.mp4", + "id": "https://example.org/video/movie-low.mp4", "type": "Video", + "label": { "en": ["Low resolution (360 MB)" ]}, "height": 360, "width": 480, - "duration": 3599.68, - "format": "video/mp4" + "duration": 3600, + "format": "video/mp4", + "fileSize": 360553219 }, { - "id": "https://example.org/video/movie.flv", + "id": "https://example.org/video/movie-hi.mp4", "type": "Video", - "height": 360, - "width": 480, - "duration": 3600.8, - "format": "video/flv" + "label": { "en": ["High resolution (1.3 GB)" ]}, + "height": 1080, + "width": 1440, + "duration": 3600, + "format": "video/mp4", + "fileSize": 1345876231 } ] }, @@ -815,6 +821,7 @@ This example is a Manifest with one Canvas that represents the temporal extent o "id": "https://example.org/text/subtitles.vtt", "type": "Text", "format": "text/vtt", + "provides": [ "subtitles" ], "label": { "en": [ "Subtitles in WebVTT format" @@ -832,28 +839,13 @@ This example is a Manifest with one Canvas that represents the temporal extent o } ``` -``` -Canvas -duration, behavior=auto-advance, format, Choice of video 720p, 4K? (forward ref), timeMode, placeholderContainer -``` - -{ - Canvas - duration: 3600 - movie.mp4 - duration: 3599.68 - movie.flv - duration: 3600.8 - -} - -Sometimes, two different formats derived from the same source may have slightly different durations, perhaps a few milliseconds out. What to do... - > **Key Points** -* +* The decision about which item in the `Choice` to play by default is client dependent. In the absence of any other decision process the client should play the first item. In this specific example, the user might make the decision after reading the `label`, or the client might make the decision based on the `fileSize` property and an assessment of the user's available bandwidth. However, the client may have no way of determining why the publisher has offered the choices, and should not prevent the user from making the choice. The cookbook demonstrates several uses of `Choice` for common use cases. +* Slop {: .note} + !!! warning TODO: The above should be a green class rgb(244,252,239) to distinguish from properties __Definitions__
@@ -870,7 +862,7 @@ Scenes have infinite height (y axis), width (x axis) and depth (z axis), where 0 The positive y axis points upwards, the positive x axis points to the right, and the positive z axis points forwards (a [right-handed cartesian coordinate system](https://en.wikipedia.org/wiki/Right-hand_rule)). -## Example: Static 3D Model of a Spacesuit +## Use Case 5: Simple 3D Model This example is a Manifest with a single Scene, with a single model of a space suit painted at the Scene's origin. @@ -899,7 +891,8 @@ backgroundColor: #000 point selector for positioning -## Example: 3D Model of a Chessboard +## Use Case 6: Complex Scene + Chessboard is a Canvas with image more than one model From c07e06511e9f5e5d086748aec3a918d53e25f496 Mon Sep 17 00:00:00 2001 From: Dawn Childress Date: Fri, 6 Jun 2025 02:47:39 -0700 Subject: [PATCH 112/130] update use case class and property lists --- source/presentation/4.0/index.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index 883f679c4..64bb264e6 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -443,8 +443,8 @@ The example demonstrates the use of the common descriptive properties `label` fo !!! warning TODO: The above should be a green class rgb(244,252,239) to distinguish from properties __Definitions__
-Classes: [Manifest](#model/Manifest), ...

-Properties: [id](#model/id), [type](#type), [label](#label), [lookAt](#lookAt), [near](#near), and [far](#far) +Classes: [Manifest](#model/Manifest), [Canvas](#model/Canvas), [AnnotationPage](#model/AnnotationPage), [Annotation](#model/Annotation)

+Properties: [id](#model/id), [type](#type), [label](#label), [metadata](#metadata), [summary](#summary), [rights](#rights), [homepage](#homepage), [thumbnail](#thumbnail), and [provider](#provider) {: .note} @@ -574,7 +574,7 @@ This example is a Manifest with multiple Canvases, each of which represents a pa !!! warning TODO: The above should be a green class rgb(244,252,239) to distinguish from properties __Definitions__
-Classes: [Manifest](#model/Manifest), ...

+Classes: [Manifest](#model/Manifest), [Canvas](#model/Canvas)

Properties: [behavior](#model/behavior), [viewingDirection](#model/viewingDirection), [start](#model/start), [rendering](#model/rendering), [requiredStatement](#model/requiredStatement) {: .note} @@ -719,7 +719,7 @@ This example is a Manifest with two Timelines, each of which represent a tempora !!! warning TODO: The above should be a green class rgb(244,252,239) to distinguish from properties __Definitions__
-Classes: [Manifest](#model/Manifest), ...

+Classes: [Manifest](#model/Manifest), [Timeline](#model/Timeline),[TextualBody](#model/TextualBody)

Properties: [duration](#model/duration), [format](#model/format), [language](#model/language), [behavior](#model/behavior), [annotations](#model/annotations), [accompanyingContainer](#model/accompanyingContainer) {: .note} @@ -849,8 +849,8 @@ This example is a Manifest with one Canvas that represents the temporal extent o !!! warning TODO: The above should be a green class rgb(244,252,239) to distinguish from properties __Definitions__
-Classes: [Manifest](#model/Manifest), ...

-Properties: [duration](#model/duration), [format](#model/format), [timeMode](#model/timeMode), [behavior](#model/behavior), [placeholderContainer](#model/placeholderContainer) +Classes: [Manifest](#model/Manifest), [Canvas](#model/Canvas), [Choice](#model/Choice)

+Properties: [fileSize](#model/fileSize), [format](#model/format), [provides](#model/provides), [timeMode](#model/timeMode), [behavior](#model/behavior), [placeholderContainer](#model/placeholderContainer) {: .note} # 3D From b4f9e08c424b22dc216762c823b724e3d56e150d Mon Sep 17 00:00:00 2001 From: tomcrane Date: Fri, 6 Jun 2025 10:54:47 +0100 Subject: [PATCH 113/130] Scene key points --- source/presentation/4.0/index.md | 57 +++++++++++++++++++++++++------- 1 file changed, 45 insertions(+), 12 deletions(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index 883f679c4..7a8e8343e 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -867,21 +867,57 @@ The positive y axis points upwards, the positive x axis points to the right, and This example is a Manifest with a single Scene, with a single model of a space suit painted at the Scene's origin. -The model also has its own local coordinate space, which may be scaled differently from the Scene's coordinate space. -Unlike when you paint a resource into a Canvas where it fills the space, instead targeting the Scene is equivalent to having a point selector that targets the origin. +```jsonc +{ + "@context": "http://iiif.io/api/presentation/4/context.json", + "id": "https://example.org/iiif/3d/model_origin.json", + "type": "Manifest", + "label": { "en": ["Single Model"] }, + "summary": { "en": ["Viewer should render the model at the scene origin, and then viewer should add default lighting and camera"] }, + "items": [ + { + "id": "https://example.org/iiif/scene1/page/p1/1", + "type": "Scene", + "label": { "en": ["A Scene"] }, + "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/astronaut/astronaut.glb", + "type": "Model", + "format": "model/gltf-binary" + }, + "target": "https://example.org/iiif/scene1/page/p1/1" + } + ] + } + ] + } + ] +} +``` +> +**Key Points** +* As this Scene only has one resource in it (the model), the client must provide lighting and a default camera. +* In this simplest use case, the Painting Annotation targets the whole Scene rather than a specific point. The client places the model's origin at the Scene's origin. This is in contrast to the _bounded_ Containers `Canvas` and `Timeline`, where the painted resource fills the Container completely. -```jsonc +* this is equivalent to having a point selector that targets the origin. +* The model also has its own local coordinate space, which may be scaled differently from the Scene's coordinate space. +{: .note} + + +## Use Case 6: Complex Scene -manifest - scene - annotationpage - annotation - model -``` model @@ -891,9 +927,6 @@ backgroundColor: #000 point selector for positioning -## Use Case 6: Complex Scene - - Chessboard is a Canvas with image more than one model transforms for scale and rotation From 5d409c3d454ba4c3ba8e4f2cbe8b9a50a2ef911d Mon Sep 17 00:00:00 2001 From: tomcrane Date: Fri, 6 Jun 2025 11:51:15 +0100 Subject: [PATCH 114/130] use case 5a img --- source/assets/images/p4/use-case-5a.png | Bin 0 -> 38863 bytes source/presentation/4.0/index.md | 136 ++++++++++++++++++++++-- 2 files changed, 130 insertions(+), 6 deletions(-) create mode 100644 source/assets/images/p4/use-case-5a.png diff --git a/source/assets/images/p4/use-case-5a.png b/source/assets/images/p4/use-case-5a.png new file mode 100644 index 0000000000000000000000000000000000000000..e00fd7e91a783ce186372857bde122332266e6aa GIT binary patch literal 38863 zcmXt9WmH>T)5Qw`TC{}X#ob*4MGLgJySqby;sp2N?(Po3io2HJP#lUCC~jYP-u3;s zD=S%9H@S1>%;>LMSy~*f zdXo4M_6ErUqyU10tBXZ{G(v{GM{|_Xa)E<;+xL3G4>^>Y!oj7O%6t{b;{_vB#|wK=wN;|5olfSOCkB}lqHNF?GbC`h`@{`wGSW0GCl1vd+Zx_pjvF%DsXv_IvYngi)w^nk z+J|-@p@(we9~p3Q0rk+O;M93+amNu#g3FK%Nc73N^JPc>U)Z-hg6}RMT}FPs8w>D3 z{3G4w_;h^W-1&3$jQyez0cOlHKLYI|YyD$YpvhM^50gAv4}N-OfV)tAmZ0yA zy6DE9r_wg^#I|R+S$7H4ROpf> z!eA5Tm0S%|GVD zj59+HNC28l50VFq$q}`aApxqmFGKejoeIo5v*dpzNCiUE1%1!d1L-nXJ3i{1tqHZ2 zZ<#JEJ5LplsF6-Z{P&|2H-5jdNpF7_z+r?g?d$;>Mn(ICCJvccOd5Y$G6oMmIaoJG zW8hUC(r6{C;CT(?#>q`*Uh&9c(G}tW?KB0tf>{8wAc5td;R^HuO2qJSMTCREJ)Rn( z6YmfiYFZ8WX*4*Z`V)RGI|C}YE;Wu zQFn9!3?cyIlGyp}Axj#CZN(L)geg)x{e(vp-c0deeKrS4Q?NX2A3NJP-bl0-6+MX&(T#OBN4;1>o z0B_QphK0kKqko6)4|twNDfwaq?e|MZ7>90e{&^$bKT&ule_4$ma&i7I96%H6pYI2? zWEGR50%q;YbrS}s)9tZouz9|3+mb7e3Fw4BlbfaDkK3ge2(N@Vi%enj8W$?dP_r+i zjLov0{9`J^+nroY=u`o+8C^3`aFsi%DqJ;Q4etcc?`ABpBxpn503ssX#OxaI&VpCIFr%Q{0Zaa5UPn(3_w6A zswAp&Wwf?KhD@^n2hqG0Fc_U092jioi7d0{j80yZg-EBYOfWGm?4!o<1vMc(SOt1L zQhvk7AzD$jkbO@OUI=YsIRi7ZjgJ=m4`47fwZm}n#N}TP`&%K8xPph+I@j;<1#e=U zf42n@uY06!hsH?glSfk|Ca`@)n$>nL0#?(wFQX+uLyVFk3{=o8tq7IG{!dP-XerTu zi91Qrk{d?l=qu3HhOv*%D@n+956&|seDB7(^}stvy>E|!CVlHoD0V+`BX>zpCXT|> z*$1PFS3g9jt|BX;8ui`H8Oe1E)()9%U&;>xiG&a0i9*=St-(K}_PUY}EHwUDAS4fLC z!#E^2voa#ovn2Yg6rt`3Z_vv(RR#}&e|XsV!^}06{)!P``{FRNTT&m-P`5g*AtEB590PHg(=K8b z;0*s>`iA7E82(=+_3>0u$2iIW-6FG!ndg>XuGFp<-ajtb!z7X{bfuF6?k>)r;dQFJ5-J?J@iT`HI>hKQ{xBmB+)o@$<8HyTdEP^BoD}4d<3<0>x0_-jziU}kNSOtd0ydoCji_Zr4%tY+4 zQi+y6lTMDBnr`>QoCiUf5B`YB75J~xt*EKErLo^9=kBxp^R>hFk>8`NSLEk^?+M_6 z*IuU#P@IarK5JAX@w1NNOGXh`Tl(mv0qJ*#kJ2lfFVJ7xEv{@0@!jtnD2ZPuTr_lV84hdjZ~fCh58!%E_k#LWO%OPUgF)N|8ao4)r}oD|Wn@0RIyv!sTAZ&Pz$KaxS=Z3e+8v;$ zK?WaWpYsH{{$YVE3Cj}XQ1_EP&hFc>$F-MRJ4Wp!K_}fX#cVq}w)!yA=i-f(xp7WLI@@+$LX2B5 z*vMZJ6=G?kyV0P{EJ;lrv`dg|K`pY>Q$M>tLi?BV{^9nFy z==Gwnqn{|SfENv_r2~X zj?kQyAa}{6%Z}d%&jrMS-!iG{CF2+wr#e%$c~Z9lWkkN+Pu`LwG)m;MxcM&%Jc7ww)=R3Pp7ry4>(`>XxKn!m^r zz)pUc=93+DH16a_9lMpCBiWx^imJ5Ufyw)LJ-7x>A8vfEFH?Kx%f``@2?X#Ybao5- zC-b6_)`2FBF~6?U8fS&F=YIZ|B!n%+wnGPYHLW;~)J0L7dENIquvEArsRBlqe~GRL zE7fBEaby$OleJBCI*hBW%oW#3 z{k9|L)_cM|?vngp^gfRozAeF$)b|eS69!^F|M>XT zPqZ$U{^(sz?Jvp7u9)_?&3>mqS&2W>a}Z4-)6edkAMqQwC`pPxIfb!@kOP!JUxiyb z_vjw|E;84(FEd&G3tI?CPS(PAX_5#{=hS*Z_$K;FRxChvDYmKzz>JmR}TMAMZ(4!sbry6Y@^$ znLO`Ly|udS7(0t3qXH(yLwE1Y0>zdX9+aa#jq_c;vq&Ob*cxnO`oh;Xv0#W{%!{|N{eCXU;u6CI7I zXEzE#=h4bU8XC-uy!1)`#~+I*>Ro@sO_b5JPXq0~{bqgf8lSk$=aGTZF%1Gw@BUe| zU2f;l&1V*-83MK|IV0V(>c{RHoC#GXxb^3@>0dc{=I2JYf-^knS{4==d;`JA`vos)P_Z z{QtK)v2iA0LJ465k-2SZdqC*(9{LYR_4sF3c>;vfyUT8Jk9qN^fL-ugt?sixLn(AK zSg}GGS`585ddQypk8i)FC(`~PtZyQ6auYv_5}6rAFcv3rh$%#PorVPKCXSX1Ec+V4 zLK7n)WhcM&UZ(CzDi|K;+ne;Kx1IjSaEp?R*b0O2OpYIwc!(2ZEVeP)TBJvrh3wy0EdRGgCdcH}O&}t@vR;xiuYFnM zt)gKxqeqkw#c8>S-ige40B(vgil!6eyBikiDXaf_MQGwFm$ia`8TnGH$wPlOl4VEMmSw;;F0t7wMv~OJ7X!&dF6wQ=#gt$g>C3}&Mv+DlLwifz- zO)?DX9wW1l3`5W^8BjIQk(0Nz^G#A&?4dE(tm(?WOuzc8lOJ`ow$(#Aa;p>;SUp#_ zReIKX_UNB3?lgSRsehwr;l?57!S$iX!;Y0U+UlYH)b@WlA`u}(d-9I{B9IOMgYi4! zpUAD7X*@)^&HuY`20f%Psw2l_tgu$Wo)x_7y5AVcM-fHIcD>l9;IgBoXknDr=lymj z%Rt;l0c-g^=N%j6=c*$mg7lA5v|kR-Gx7eTk)H@Y=;0wL4PO|;c9Epx7P;DQ{S_aL z`oM9(`(IWr021xPc8egknAShg47inHm(6MHo zj>=kBPpHwcs`$mU&XYm{z$TwvQy@%a1|LbxP17(@(0+u`#l$Id99&npFtNHz(O!Oo z`u~UQjH56m7nZTOw?QZ&iEucsRRsu*9X}SJ@85ib2L5-){K(#r@_qg%#n^%eJB@v1pedfj zT5nklaaAe0G&T7??n-2%S7)+!oSf5L^a8{mFCZ@P)HxQ^B0X!%*6ACPcE#CPywX^# zZQ6%HPc6XuRW88-*)zTBZ@@R9idR*PKQu7_Pn#&_SP%oqW2C4ntY?TDU1xXlkj}PGz3O+6vwM zLihL;{@bc?<%)Sc@)OPR%C)eSPgF*wXnlgbz^_zyu9rm;;&S)he$xjGTVbBFFumLv zj(%z$@n&m!s9HQjHL)wnxNRmI0fMh?1F z(AUcT*;OZSp4KJX7SlY3{g3S%2&k74x=7@pp}L{@WIW=XvVhWG|zlHXmxs zMuiGfGGGCQa9yhV(ZyOI|L-B4tL5R8m;CH6Lu2Y(Z384A?-u1ql`j-TFC@nGJNigD zH(7$URR__^8}gB|YAe4TSbL}NeidyMl2B+>>;dxVUjg=-?ajQ_Fl0H6wv#bk-zW1o zKEO3(K;w%D+o#9vv^A2taS*no#9hjxv3hAtB4;f2&ny48XQ-xhXY>TuaT7Q1d#a^# zHiy?GV9cIN8*}|a;!He5wy9GjIp^1?0O-db=&EIk8nTUZn%JlcggF|!<4={t{+|_x z{m~2uIEy5ar)iaAuYZKWSgGQ;bjV`y1msAPdHfwWSRf$QCwL`FDS9xyZo?G*>Cm0JCBZs!JXH@d1vN!x=>r$b4$d) zZmLjq$b47(QA2Uct_W)WH3kenCQhX2%g@TE>Wc=!y%mDI+hv-YfroM&Gkc6QthO7$ z)FLx{I)sq?zaWb2xxQDt^>$=7(KdC7dSZr~8ml*A;BnKWl#Se;N`6AY<&L=}P&LUi z3iD7=-gT{Kw#m%+krmmBn!$+y*#(U3@m$B>xLl`Aq<10MI=0pIU#ia}2I}zR(>2wgGarOP2f>3Y z;R4>G^E@TEyWR^zUdN9~`TV2X$8{mOOI!IG9T8&=?J=#`xU}q5hwq74mV18OoHf2r z#sV%ZswTE5WorcD<=4a6N#ZNS6C8Bp(nYXiUwu;q|5un28Z&GmwnQgO^!HgmeV16$g1ro@%B0q79 zAs9vhBcfM$R=zhf(M~zf8d($hnYZCf#9BnlKjWUm)Ybr)#&7eu68qvOKQ$4xm#b?E zj>DlxR*veu$F98@S+iYj#@5qx`nF3_vkg6aeDDY9P+CYT(kL=&>-`v`FYO=i9Cn!y z6!{0gei3v=WzQY96~-5{*lLFhAzd3d9m~A5eODS6}O7Z994Ac z=jyIRs4DvQYE*lz@D5Di;U{@rK#Ta-vBRTi&ZFe>DVg8AyFSl{@zUrhG4kLlH@YMQ z3d=?!BqOnG0-=XR7Hv*uRbX5rk*?QMlkQdfLco!;o`rHOjoT=n#@0x4je87E06s_6 zPeVHAz7^kp!ce^kF*#W!JlnUT*q!cNXBkzco(mf?-t!|hbggId?W$r`o1du6%O zRo9SB!!STql5qhJa(&}+Fn*};mt*tiX(u8!Wy`{Zj;*E^_LjB1(r6`(?ER6#xac+_ zy}#0_jkhs==eXl`OZ}^Rn88jm1@ne51@<9FxF^VN{Dww3R?qUBJy5?VMbM6(|Lf#X>&z_Id{beoVr(wXNqG)GAQU zlT$*xsO-T@r>n~^N@Vr`&wD1A_fjwDD*nD7fRT966S3%n%MV6j(y8SopEZ%L+fD;S zT0^rhH5|@UKnb347@Z8Hqx$0Fn9qA~joOD*g(=?dk8Lrb_kGtLWet9CF=lE---)|( zm!(0c87G+CGkfKdK$1FFJ}kv?2JEJeTg$ErCyv#RHnGINexFUYlW=4pi4|N*M;=AF zMI{c7cz8Lr7eLnwoQ9U*^{TIYc|c55<|@%q>_P0ML*n(Y3?{c<6vHmVW2iOO*vq%7 zT6+4^x%#yJMhvxCwAF2kMmXCknDDaR8%8#Fw_i4Y9JibEwzBy|DFAr1Rq()75%9!< zj=_cVhSMh+vVE{7RFL@5o(8Cq+9EW>-O`aj9&zB|g=z%h-}ihw_;*p`EU&wD`0;0u zX%IyxcpFd4eqaiXP;s@ewC&xRFnVQu(ve*xfekZ{xq0i({ZXoRcg%G=e=nV}^%Ij5 zB?#5BQAd8NNp>zO>qcaFd@kF0a$Xq?n&MTu{OP1%~{f%c#kt;ic&3cl__PD^0%ya-o z7EkjkcK@KM(-LmMf!w)@-qlzVzR}0cZQFHU?C7%hiTPm^Q4%cPSNL2j3Ngo`2q+gq zLpvW33;Xh#T%#yHtGpHIjO>gRQWOBzy8iX=B-=!qSPQCFBZtS5t2^C_TzW3oz!_xM zsptaO&fVo(KQQL_UjT*|@FbP32!!_A2BC#NX7iU6RFN4)qjoh^ORA6fC4S0dlP=QUivSBEsICrgc$#0z7nTeEs-x54kEIg z*t*()bSxM-i`PMCwx`+Al8WCYUiFD9Okz8DYrB)fe!S5X`|KR+ma%}#Yoa};f{Mm~ zdcfprsmR@SanDE(P*4KGiu(Rwqi~fyl%5q!gfdDEc92h>54W%D?M{2S_ z`9)((MIC`&XK<%4N@y%h2eX$>j1Rqvf6aWlDKMLhsIhptSx=tcdiGu>2|ZIO@1#im zqFD5su*YLH0r%ACf8;LiX6+d}=j5YpKyj!d+y;2^t4s~#DLv0jRwaL|b5LFe* zlRa6K(KHF0pK12wBaUnZ$lE;v>Pkd`EK3Pu7=dYQfqaHfl0>QL86P7k@7Lg$*bo9qd2&cGJe)F>Q7Lkx(6PJ}i@jh2qFy;TDF zV^A4kqoo29CZ^K%`zg9eBpX*|m(Svs_(Dz(huI!-Grx{32KIIaeA&omJtSvPWjF3njqr>YZ-rAEB|H2?Iit2QReTjYHhvQ51L704Oqy z3Av_HfT9 z=~i==Jhs|_HgA5E5K0kUaG5NU;m}~8q|w`W$}%b!EfSd=d*7rTcI2|pf3zP2R>do; z&*WdbfZ6bbAUc;RS)o7_v>L(o&gIkd-}WX!B7MB@ z5%OK26mnmnBwq3hhOO?neI_NUgtiLvhpIhIrOkVv_eEn3bTa8?4!lI8u?>JGXuqs{ zwz;AF?lti>3ZB+!KKGZ(&2Rrwi?4c2;E2<%H~NHW|C2p1yV{N3-Ao8g{xn4de@#71 z#xzF78{AF6_xzd53&)$H24&$Iv?u6=Iwkh*+VR&h+^~YhZ5CA8qmuEU+Ke!>MAa1! z#3-iBjkA=^bbl?@!`KbYcXkCKiCFgo90u zozi(P7mRo8=f&!o-0;m79s}bIJ%Wrj+HAO!x4ShHKLi6ZV|t-{GP+ zp1Ho9;p@&W^{u%qApV`ozWvg1dN43AlAXf4E)LT(hNlcJ)m~RsdYk{Wm0PUJ0TC+% z{>jV+8~&hI{hF?CV(d4%ie)}u`Ck0&&*}2Oy!uv0^;l?gtad!Xj_0IfT-`TYY!i$n zHtH#5*j$CE*i=g@yBJAH25YJOI$9l9&k_cD#?VQ+o|gnYAFHK3PtPs*egD!)s>fOI zpB(a>v{?nxeGC)Vp0lgxsz`t|eFhEBW`1n&8Aa)YZ?9EK1l#n}mwUG)>&(i;<$a8z z)QD?y{VA7NFYcg=(~7ASVB}|cgBu9)v#e37pN2Q2Ir|%_@ks7XMBudFPIL>_@O5j9 z-8YMcAp;A{?{0mhzR!PH5p%KSn~-(g>L&Vdcm!(k*y!!{cYB+}==bB=)!wG9)y&u% zN4adaoz5$lmDh*i*NoGszN(yi2P|&v%hPB74n6KIs|c?{O|4);Utv(9(Aac)F85kK z|NJL8khguh(3I6wb391QrCipgI2sDZd|60mnmB-<4%+gWPM_#(lDw6DBhmg@Z}yiu z!^mZ(5bH7Ldv*WllYJ`{ghXfAnGkXeTgR{hVNNhT^Jm)I*56q8%lb|TK-V{)>Lwga zniXEox(V&uBgAF0t(G}74YIwHbNq^!1^3Qh8z;19%7C*Tsp}3CUPE`!xu`ccomFC) zpUfo61^@jdph2;>aK02L9?W=J5sC0gt8eC1n?`}a6C^;KfT_ac&>hyA<~ZP{F_UUt zzgutDv9+hc0WnHG(KvxUNTzTg@Z zn+?NexryTVpd`oAZpum2Y+pFceMsIEX!%c5xFUaAMq`ne#FS2Bk-+fo_T$7M53C>N zFWDp1I=W_?Lk9lc6T$>>)1bsF9o{;}Ti{WP9o0z*6RD12UvhMz&%<{R5T+NRZKD=& zOW%;?4Z9#{gepP!L3*0JmcPQ5YTXJtK}Lum*SwJi7~&&LN&fv&Bsy>7L<<`;aQRYa z=8JZ8dGO+F{ieg&_)@2z5a6OD2i8Zg7Hx)L0q}iYT*cnGh2!nMmwVjr$6q+AyX2h* ziV_&J+}=}T2Pu-Bj5Abm0|R)V$R(Gn$cl?T4_P9Ema|3x|Ad4R((gEBR8@z~(Fu6u zh4s~fCatG2L@=G?^C?n2X_XSSVhTQ}9Mk>tGLh;E%}ac2?}4;pdOZ5HR=jfDTa_a@ z?rUEJYW|KFRB!iFDLJG4-aqkaU^l%<+tj*hNslMGaG5vs;;7o3c8NBel>SB=?feq^ z`b>=A#6X(D!WnDToRzJF&Gk1fr0e`F)-M+$ycevUrJa@MEYh+2RI68g9@uoZ)858i zSIiU|`hWVFVqp26#Gx9f)NC_@LZ4LiJAN-!{0E;#ZqI#>J;>^-?_yxE&KBl*gl@?oURX$87Iw_@CFJDTT8AM58ONHe02}`<^E}wnAm|IZN z#y;Y@-71~a?&$qIPjCG&I<5IOL5@DJ%9_Q_2R8t{Rbxid3ciNq05Aw(m&Qneyu9cN zX1AU?h~k6mT|Rm_){ABJe&ziYwfpTp$6mYk#U(Z`@<_o(!?mJft#^4zbe9!!1jc*T z%x@q1Msechw0O-3Ne`o#Px6UR${4Q@;HQKiRhw!C-u~Oo)U}%VN}~diY`0TOaBKVW z#ODz|^KfxY%K@<>;aez=c4aD0M55P~wx?YOF1*Ows47H9ROZ6$8*ldeZSk0lFRyDo z`g7-Myh@tV16S+;x94OrORb8IS4G#C4|@yN&j%+PrITl#cbhOhSPRVBrZHW5){I&INR){=;(*%t?CNE})s&hh0ZVW4TgC!X9fbhZzrq{X z=j}QOBLA{enTe2N{r=j#`cxr7!mPZnL1+BW=ef3UnxU%z1jEM7*0n5eoIY2br(*F$ z>5W+1Gm$Ox7tUB>YUuiL_dUm*DwpsOm{$awTB)N=xx@-hNEmdaNO#}EeOY_pGkEOZ zzuTe}nX(YM82Xp;U>amgC8qd0xPNc3ZRG>!ElqN}m)h1Ybe_36!N||hJKM_cvs>H4 zATXp8q;@6hss@5fS5XMA_!o=yPtVno@LaR);}L=LT6~a2R+u>6dCJA?p~7>d zOv1F;!Fd;^eS*Bl1ViNcU!P6f9-2PHZ}YJ-z=BxQv7%$eD*YON+|1wBu89=8?T&=~ znx7@)Tgi@~By8ZobNwAZs(EB-C(;y~T^a&5D!`0Md<%Xr-8 z`?6y_h5TyCDH+sQ_gRRj9wf(*iU7NSlUSu~uvy+=TE9hxxyv|^F?q^BV!t-#i>Zy|1uP=fBP;{@-HT)a23;LS_;Vrp{P+Le5!BA9xQEa+y zeT-~oCMxhw319K}i`lqJwC5i+Jj#L+N1NxId^Y5invJ>JbJ{Ia-WS`AP<}On8ES{; zzg^PmPaTQ6kG%#y;=jP>=-=CuKCre>h7y8ZY>)%Q!SH?SJ<%_ekw5v+$GV(cWLe}p zD_1ll(tk#1#S>KXrjrx#E$EqD?EvjwhcEh0bKD&lPz@bySFqP57d1>!r^+XQs8Hw_3@#QWP5Nj@%4ilTwjE z{s8>Gbu4_k^pp4E%W^cH$$5cr6q37xYIzMvHcF{{8Wlb5l*p8MKa_KObIZw{Ii45J z?ng${veEI*U{u!n*v7XChp}lDSqx?N`o0{}7OXSMpR4U*mZ>vsol_S`UHP}DFY#3Q zO;r^&E{&2JZ52;2# z*@tabHhE|P09#+;{P83g1U+9Z$2%8l_tS9^4=iMpEKK$O3F_y+-s{83CN*iRf7*Kf zzE2-&z|m4Pgz@^t_biURza7R~)j%iAn!IU0$rJUoO!+;N=g$7oU1Ul%Y%&%DSV@$Ov^)*kTA=JVS*FM*^>8ahqy=Ad|us zwK*2dM)~5vAU2dTOy!>Ampdamh@toYJOzx?kMFuc9lx?_NB=~LUyg-AtQGL5{TXe{ z_S*}Ug&x9~^{D-&yPmO5(s+OpQ*FH99=9kS`6{9-tcte+0ccHHPV^qk`^Ac@*Zpg; zwU^n_cdHIhR!zrV-)N^qE=*4x8QGqSSU{Gz;{{aZOq>*jnBSe+Jj~*a@aagqAC$bZ zSQuD`LkZ=|wXuzPzo?`50lf{NNjjgUOS>HnXfC)YqxzJ<*!%aGg4dUs&xbEjWylxb zSZq7SX11MF(F@w z&);P~li8l!$vqMXylwqwT?Y9N60tZ!puwkT$e$PBrP67G(D@PP!&k??U zuo@9J&-_rQW}XIVs}o4uy+_L&hE>CFu41#IFwp_uwF4O1T?M z@(FX=WhNXbakSwVT;}&+L;&8$ntwUg+04IM?a@IIl%YRhVn)OoWOtgI6qKd6Z2SO| z0+sNFd-jaMFtq_ZZl5ZNy7+X!l6^baM=a`?co!tSboE;i<|D|UJ@rlP6wKKkUhkV1 zt{fiuG^wf{o= zr`>&PGFa+4L`aqEt?&HG-2AMo7@-A_1y9T6<6!mV%Q7JG+L zn2x<}t)h-%-w)Q=S!(UsAxF5zwO?p%`}{g~lOoCcOrYClsd4^%$I;+K(vY#>vb|!U z!<^x++rRg@S@i++rm}%(9}ZPq5+;-yS>`kp3rG>cET*|lG*NcddUu3!6hO;~bL~wN z-NGH2+EI4__kr+iWyl~9HHJAqhBf|a#sE9nfTmZeO8PwVCE`KkR_1EmWfLa;UDjK? zM2GTyYiM#F1!?)-`UO?6IIaCS`CAqp(04ihcrhgX=F9kzDvuO1#rl^)<7NkYf9C@aJ`CHA=o7tsZy6KC30H6q`Olqji18D$32CniVQH zn#-1lCQ;it3|k+Z#i@$O!z5sc1=R8-*}PP2M&~qu2g%4EfOw>>icm(?2c}L5;;Gi; zR$ye^4wRI7@PCru0#h%)ob!hJopCDu1<}luCS6JUy`8g9*iVP7KNvnCWus%UT4tvR z-*lZ(Ty)UUI+ydatlzAKZ9KLt@?>(Kc%8z{kv(v!#X&zCB4IMnQNOWGkItXA{XlR^~R>xL;i1 zGer;mRH2Vj{VNG`$pdXNt?DeS!TJXkh5LzqaP3c8&t%FXDuTc}$|2O=X>HTf$H5aJ zoGW%}A|E@fKy$*!%`UOT9D4B{heutvZjQG~O%X5I=(sOL*Wct;f0rbh^2tkYAFw{# z^uJtEM6oBej=b^6Kkdlb+gL^3{iaR!H%szn)da#|!fd5E#)K*nC>D=7SN^_$^kt&Fu>qpcne9&&CKg_1$qhS^U>qwG)F}ykx--5e@Xc8AySk**s9agLp-!a> zetE8`c%Wm9UcGq^9sBW(koksTMRjzzRUq3?$LSkPk9b)&P|<&Fj;U&D&Ae}5}! zEQ!N~n82L*c*wHZbLj>j?WsN~g#lFYhwH2!B-I}9YQqP`HQ_T&FN<`RoCn;Sb$!`0 zSe69Z?mF@k>(!HRim{cPtv~t423)buZ3%}z}a%yGNmCNH`_UX1J zdtd4;9sN+x{g&JfU+>-1i06L}R!%hFCr(y-Um*aKya#!JgW3+W$zuRK2$^3q z4!ML`{!%%^JJFF}WY73NExMwCuaRrT>;; zwtaFF-OvS*uq3ZtbkWY-I~=v{cu&teFjB{b`+WLZSdV{OSAl2B<#tyEE)o6S`AifY z5LGunFnL%#&Yu1F{s;a0&VtC#q?whkMCMsGliK#PNx=yL6a0uo*D<*8+e`z#CDPq< zlqc7RldN^FuGvKemoi5CA&HHViMfeD9R%tMGv|zi?J;d^7I;WMO<=6PM%R#Y)={K6 zTXTjO;rtw^?aJmZpZ6?w|N#U71ip>XuO^I z;Fi=~dO^_G+Y-2< z%FmCTMb*sL8GFs4%Uc{zic>V$q3XbVKI7+Mr&*)XT0t=xNh}nqs($sqLnx++Sp{G$ zpb5Bf*o8;GV@Ws`#pLMIAMqbtxUe&+E;#}CU~&NL0EiSP$fghGEWMK$vcvsC5f{L0 zRfMoos!D)7sChmXLN8?l^I*XYxWnkMp$bd@WE4~HJjpcHuf2*m$;DI=y^Nd=%M&G* z{lR|V;7Q_a|DkKwZ8E*$u+&@07iy>*aBzO2jJp1^>=6s~W&yr#q~yoD(3kYig|nJM zIb;Am5*Vt6{4N!%QQI*9+DxU+Z}?skbUm&gBl66Y@`v}_=Znc&Q`wy&^R}cISd|zNwxK$2%dD?RCb6{Oxwf}Oiig8CX{Gc%jMhv z$piopm*?zoH0mobFkk|wA{S;m-SjfdlB`W|trbGwxtk5yi-XET>Pv$Yn`w&bE}b== z_HvXPKMZSAV_yyuvG?Jf7i?_DFzO{va#S!h@y!6Jd{Ajk=?{qI2oNV7oq zes2$iSeR93w5=h5q0K8wTa?9ue$n`zMaW>WiDr!7>jigM!{BGj^8l~LL&dbzC7RYG z0ezurqeZc0W5&Gi?r#<~t@HJEipUP~7?Uk?V@cjxp8|rI@gGI7Deab2prfb05;67w zyAlp17^W^SAB^(B>M3jvr>yA|O%z_GjRQsk!6A5j{{(Xcq+K<@j)B)v+#!58c`r*@ z_cXNHx#V3#n(swAxLSJcRW!yPQANH|Ts+!Ng80A>v&~#hw6K502>^9paQusjoEH6i z^E=14MYs-^R-$?dkLYedl6YF^Vd!43cufP2In$q;13q02SNYT?lZ2X^@bA- z?m41Wf=d#`k>Ohl&G1pGOP$1k$o;aPR>M%Y!(ivUEP2CUeNQ;NAM>f|0)K0-AQ^=* z3EFP-;pCWG2yTP-d#m$ktQZNCDuQej2tz8!Ey?w`{21K`8PPg` zPRyc?^MlXYZ`}=+La}}D#HKP-jTR;b&(d&(s_z8SiG%a(f(q~k7a!}`FqDjB3heYk zj7$sgf`-wknwLu4HrqT!=}~{AZW6jt&raV)`Ico1?&z1*T&en&-3#QpV(~^hXVl_?|#gSPdVj(ED|HY-MH4X z`+1({vh%h-I!VjiJFW9+YMrC`|42H^u&BBy3M<{x-AK1|hjdDJcS^&6q=a;Lm&DNB zNS82lcPk|zUEjs;-~5_q=H7G9-DmH$-enZ-q``%Lt*e`fsI~L$gLfUaa+&!aKeD(M z>8L?>g>^NQMzS|%6-sgvCJr2zyi6Oz4R?nhHvi{?C3WM2>tJ*@Jcl>m+@98=YUh*z z@lV|KQ(D~uk#n0Bwk8il(imS~_!kTJHj=UTM;G;~Vw;W!W^*FOaf!pdx6@K|pivO|;t5Gb z;qTQYQQ}YIg`$T5}`<+J4;*VtET&V=ofgJOgt)y&J5_h;+xPhX*kKk_PX11A9tFFKn$8c zyKqUK2Eh*w3i5nNQR7)&R8?;j(?IB{5!tO9@^HGt+Nl~$h*vRL3msgHb7^<};#ct= z;u^&cU=a8fvN65+)#|+3diV)xODoe z_~jH&W_%DY>Ub{2ur2GD18KHM8*%OS_P#Eek2pG79~lCBf0 zBu&OF2tLLiptSq0Uxa-w&31+|A#q9uqX}T9QZ@kUqEEX`)!M!YxZ;y~r%>ARa!3+7 zi`r3ej=w6hr>24gS<5{wuvC5(V4Yy;1MFfVNK5Ibt=WM} zqCOHk=Gtjy2J||&TwN7RN4E0S!bVZTtmLMeAt@ToAW6lcQ37S!Bx*UiivnJipR2+; zDG%R3I_lI^uT1KgfURKTeN(Z4_RVDaBhxX-6G98p6wo~~{j_2-9UJ!$d% znr^Bi%qsZeO<^8D@foE*hI88Z7H!SDsHx{t_1|OK13aeHhmORWV$jLK(Q2qI$rX!% zQ`Y>KV;y_3r)j*#S@NVyG0p|0$PQS=M1|sQR}|WSFf`{KX=8l&qO%_$xe}P2`r=%J zqt$9_J~s>VHdPIG5Cf#i8}GEeeT~{TIqsm-6Q0>f+07-!E{Y#=Y!xcv4Mm!vwF^?( zS}imar;@6sl~j?jS*zM>U8|C6VMUv$WJK3D96NyadKz-vx!!22_5O^cm>(@PG3)1h zTJl2}EPn^qsn{WISwdb80jw&Jv7qXwNuflrRNo3x%E00qhZ>*u!;b-OY3GXmk8mu$ zZbR1HbET-ad$)#Uher!|2xzF-@5tuu9hDz1E7oT6i-S5=EcmQj9|*(M(L;pE zll?aJBdNu;<;OQqvGm%IC~SwcM+2~uIlaEn@1OgD%Xw_xIB+(Vct$hq{4lJ4Zp?pF zs7OB057GR(+Qo*U{z*8N zHB^7L4yrBU)Y<+``I5OXa>bjiRW}PZX#?Id__A!U%h!mh@W_JA+fNsZkNsAAhJ?^W znRzo5-n^Sr1B<%JAvm}c_J0(7Uu0F7)*@u^w6|lb4F#OD+?Z2VpG6$EuV0+ixDISW zTue_Z?&ppDlW>c$3z29NZ#UzRp@HR&oCD26X8AH6CJk+%QQJ2!No;cbfp32fP74RF z$Y$c*)2hIbhYo5b7YNXBqD{g9`h*<;d>=&z6kR(~14kz(dNWr$K|VekF8i7=qUu zuIl$A>+%-^WUH<{m%st;vkT6fuldYc?oh=(PNvzaNZEMy_k-TRn(^^HlAV$aM0c`3 z%P%K)=2Iuib6ODKMDY3}I`O?_lWRqMx(9ub)5%l%c*cv6GeIVK^yF%i#O8NXe!*kxY(Y1ug(U_}*Jk;;@ z-nsKRjt)($VcNr}djqH;-T*a({vYC&^GU>w{)}+0#*qUr7qgmPV4mUw&_A5YSY` zzm-rVZ}&4I1*cp*wtpmNrqjdKK??6!AF0PWhmf-ewpQKbFN?GyY{X|!cI5A$t`~cf zqy|yEi(vYQhg+IT&Yjbe$F$-Ea~&o0P&eGvrK?FbfNmq1qouiFyLzq16XRzfwQ{7W zuo1nbM6HD0fdSu{e4Q`^ycvQlfkN+-3EOu)u{`_sqzKg|TOULf0)*mH>=4TbXuZYr zKTT79CFEl+xM*Z%&%=U|(s%%yCxVhp2Rj7JgJ2)w%FTnstqhCZnrVk+I!mQ!N9yOr zgDm;&o2eaFQ;8QtZobfr6oP;jU5%sE%Hm8{%Ea%wpaV+c9fZ|3a)hN;`we7@)|b{Q z98McMexzf;Toz6SlopRpjdzK7hg)$&a5J01prm(}B5DF*dz3ss=@12o00|ZaMDP(? z`kIs`iVFB;v?N8lHeCrOJcABoohEx{RN{*~q30WAD^`t{>pKTih8M55ZgTY{P`cv5 zHptIk+ea%Vc%q@yKeBop9@QIq{f|#I$w@oh^KFbWyTAE*qf)IHwz$kie&w)LqBOKkd5A+Dsw55cXCFQhkROpYynHsXyTuoc`lrI-ecycw6hgkK!e9=Sn+t+J^ z85ZLf^Wr`*_gE7ZrX9e7EOYhj80`lUJzU#D=uuwf@V{;`0l(WD;3GBBcfdoZtnMKXxVaXEd=>1!&2pXjG!Q2LgvM@6 zT*Eid-w0F3I{FiDNi;OiO4{{3=I_j1uTNY5P=f!cwLBWrV$msik`PR`*!T@a+%7wW zg2Bf4A}Z37%8)CO0$MgnLSr%nhpTzkP*;VBfC@^>#)y8su2y>LC@+JVF-_&?1Zd#m z@xzm2EE^K|K5xKCOTaA1f<;99>qR%qdjEb@JS^e@$=3;CU_mRxjnxF*KGNB##XwI_C4ko9{Vw|pJpuHdpO zQ31a{*3|mhAr_%uDOAj`y<_Vq+9Jme#p`cAg@xU`i*pW&GBd{yR88yH96u5Oj>ZY2 zXtTW$*t1tZyF9%$b)0))qYz9kFSx1s797|Px85XkR+Lh+-w2zXbt_QixttLcCF#42 zTX1i%umV;Wln3bc*!scHr?D0@+XRHsrPqGJNcKLY5P85@nuDA`uG_khhF<7rPPO_F{>gQx zYutZ9#AnEQfeR4Cz3{~vUGT~e;W0ksp}=6MIvxMO0G>qjCQ(sl*XaaZ=ZhFX4~*ecVQ=q59m>u(@=tDf0*B)5*wBjAGld(qr?d8H31~Cr zTl;x4%^-I!yV10G0awdDCLS`fIR`<4=9lYnd=q73c~iwx6+Di^o9U4=)=$qdbwTYf zWzCa@<*(aM9MJ2RR;rn>*8tfKM5Pfg=^K1(hNSp#=QM%O6F)z5=H7qr&KtJ>*3KSk zp9Yvy0nvYhh`HmX_da)JJaj#v#p(8z-?LO$3;V8! zjD6#luwihb5OwI43bE!>T#~WaN7t?8_<2e;=VqE3l5HE&RibPg`KFsSUMJ18EywD4 z!27C~&KTquK46CImU{ezrz5r>+|j*S+`Vcsc>)a>VPt3QXF)%bOX{-whE|5MA~Hq3 zFpE`^D7)|OR(qn-QFpGKQvEWJE0}c{xw(cfizqdFx&wPZW1m zVE64j1U)DLK3X4`DO&yUBUs?{->+4#k;tEL(bT{|D$ z+@suo3}tC^^>!o-c7IE>`o$>S&7j%`^snvEHk9Gz*n?P3lLdC?3P$g;9hL`t`#H!l zojk;%L<@&?gdHb5XH#t4CUq?udy}*<`uBe{o7O$2ZiQ*LI5w_9!Z#=W(dr3HibvYb zHbTHqGEGNhEM*Mv4}yfmtOexp?qr6gW`sPR@_6z#PFxRLp=GFT6dQrYALlY^FgjpJ zz=z{pL0ySo*0`wYNcz`$X`le~NfCgnODb0@x zMeJVa zQE9dfsrWto7y61+;@1}}v9iHAr;VjNZE^ucuxRTje$#yi(IJgcY}Jqcfg2+?-Fbo^ z0>Tg6RbMVX2zc&_&lLmi;B4tJ13pIjF*(vE(KFyRGW3qj>V?B6UbW6|Ov>q00*8+1 z8%BtPiFsln?W#qwQ!I9c<@edr1~6uu_n&WA&C|YRML3O8`r#JXl7OiSI<|Al&Rl5+-8F-a5LAPJCA6_qYm?6t@)NW%) za|aBVuvzQFYy=Z24#!tFOqbnX&!O-%cVX8j_s)&6zKzcWtK~<#*f(Uthz<9~gV2OM z1NQEyOA#~Kn=WKibb9J>Z3EO30Qn0#9N-Y1R`|A)Mu&#D6UQ4KZps)W=2am7M}770 z(SlYr*oxGL=>gTUah|h9=;EixyBp1AdF0o}lhn*UIpPP`9VZKY3kt?Uh$0-z!PllW ze~gvWjSrv}i%02@TL3vvBrr0Rb3Thn%`Va5lT#WlR&_DOt0j zcHT0)kr0?KFay3udYAD)tLv$BqwmAWdheIkM056bTixrC@H$I_@-Qoy#)j(v;{zRF zL&U}}3{OaQ9Z(u%?sooowYr?VMkqu_1s=zr=A;cj=`bdth7~LQRANKnZRqvy?k&5j zC4%!Tg|bBX-q`AW{sW90JX~UDws9ba11}euFHyPA(Yd=Nepf@U=n9P}Pk=%8;S*4! zSRCQ3fFmJ}S@oKQ2{P1EAd`cdYvKxt=3xiKa<{kyG}VYzv}fE0eTy!Fs-5c=MwgJA zIj2)$JQMhbIzRIq3-i7x%I56iBL@e2C0&^$31Gh}c>le9*5qZzhp+97t&OhyPDp>G zqI@WW{d%=nv|W#_s?OQ9O>tUgl(}TUp&RrSZ1XE;dfaS&YB?{dp^SuUk5%%g^;hmD zy{`ww0KN+XJEQ^8*SR6rG+Rm=FttbjHs#oZwkeBQyO*QbNRmrdz37g!aOy*?s>8GW zJ(8!^@6sCuFpL1ED7_OqJ7J{IuWvy)99Ivy7Aqy)!znM%&b=Z}M7s-Q5+u9|UWarD zCTpOI?dLZ2R?YwIGsPab33pR5_RTO)rcJba|J4}AsiG*!y;<7))Iu$_REUnhcs9&1Dv9dc70o&(u+5umgV4^mU=Gd~Pym zX;0X-k(!lR^jhev@V9*z(o{8BrW8BhMb$v+8+w~xl6LyDtm1Y zyQ3kFA%yMPe@`I+8>)~C0M$S~=$*W@KEXUu)UA9JxrH&^Fd>W_`_l+Nm3#N$NEfy3 z=m5Pc!ar$|uZa?Z2$eZTQ(Pp(@mel}GU7Q+wPcG#m4}vW{)|=kyw1} zhiqsYQxWKweEQxxbw7Lntx0vrIaQzBWK2_%j90+QnbfQpp8u+UxY^|M^go zeW4z@CZjod_lsDsG>F~FpsgD9eo+G7=8t zta|M-#WH9lW;?Xc31u5k$d-OL96(ow%D(Fe;KiOBHj(i57Dor)j@@ARo`^-bI4a1! zY9z%IG!ubY(teWfJfQ3>cwf*y+c=e|5-^{^79o>?D26_1&86R8h$E%nd!0@hK*tiv zrFR3KU)HUcRMB{3MOvvJS6DRbr717!d@`ZDw)=ajatMS^@6Vr`*?gW6cbAX7$4h3Zb8$W z^_oHGMST?FQTwT(oo}5vOwMniQXg+(XIyZDs@fIo=2M`qui@XHc~ONK`NEoD1C-Py zhd}qU8K@!5sK}0>CHVfpi#vI-6+KLR zF6;)8s2$lGe`6M`Pzh`}yM!{p2Hr?n1IH6(C%%AC|H};7TF+jr5mfJWH5N;>@lYRL zuCo)`59zaeA-Fy_PGxPsIJCE%8Hm0MxsC~J>bp8U@P;?giJ5||s{eL5(zR>4v(~?B z!Lq$I3)M*5U8g?lgSF6ru5D7uJCcO^c(Hdne&;VP|6~1~e-Hfi%i?a?1mVl+J3rEz zOGAt4Ms#(MzBrOw6-M_Rtv&D>HT}R_O&pso6Qb(GG_Eb@8j<_-2AD6GrPCilp+NH( zX&_~wa+e`zu;)dt!e!up?4F^O=h!Fpj@aMu%Wh?R@7b$`WDH{6Q$}QR=>8^j*79}f zs-F9XrP*SjVP3*{mq~0za;1ePH=i-nLZA1A=V^-MwYlwNCFHYu(-qco34d0(uM~nT z<^1`FXnppiXVr#m@26U)Ltc@m8^13ui3gGqo_yXcyr>p{#PW2t`ChqMu{ zA^O2V8xM|--r8@6f^B}A!61xE59vn}sBE1tnSIbbfrS&4Gb7v<@cgKih886Ela9G> znR1OXz}@Fv-FbY;)L>rG$q4QsH=izoi7Nz37C$uDSt6~!5L0UcRsThBf`;dL+5Nq& zd8HWM+LoWASjrqJM zNM1`oPRF#m&#R)joR|We4B-h)?^EIua``SGM`1Zw<_>RC1Km-#9hvR>k309~7FHPr^odnLDi(L>03g5bKI`#{m3Fb=g&&FrRI$Kg* zkD)5&iM_?O`JI@Jc8BesR$;$Bs;xdIFZ?Na5bilRy?4Dn`4VGAx;T=P4OvE53_)89 zvAC$%#Co}r_S)|nT6*ZOC*JT+tKiuj49Q&jAXq>97IHVF_j>rs#Qj{h8eN=5z+s5d zi!YOq##XcUy_fAxCFnGt_NauP@%7~xP+KbX;P+RzZMBpxhSzDueK_1Z3LI~%csA`o zd^^#sUR-8=wc2RMt5xWi~hQhRDY_cEO3r8VRF0Ut<-0(Bw2(!oXz{>DR1-8T6+ zpWMyv5pysGbl=)qi{n|VvqT6x;R8#d7|>SzgaWanOtFSAL}^)vyMJj$j5SdNGvC^+ zjPV|oU^h;yGO`}bBhx#Wjf=)}V#RdrC%bKU3j}Jf{2&i3Z0=Z=;%t*qt$_r#``IvS zQffYx&Y}gZO+*OcJ&x|bgt|Q){>X!p%0d1ydCf73fpa5pu0+%Ix0^ z^pzqq@jesyd@fv!&SvC@Ywa>0#BY#ig3}xOBqJ8TyjoK)X_2nZ_`CXOKeKW+Up)Xc zL~?xh{Mic9zAo0bLpe=?$0x=qp*qQkR5#XC>-69*A*(QLOI}nnE>hfJkuBvdrUEBE zTg4o}R=4#xTJviuM(yqL(XZo0@s?2Qv5%Sa7+t?zf`(Jt3a)wQDT#!@a~uywk|2)# z{_P&CNTcrCKBb0ZD@y$~(X9f5u{#N$YOJ^H#RxuzAO7DS8#r04shf6_NrvUX3PffH zkWt?NAFI={^<3tNM{LK&I{vQuRdsZ9eOH2gU=e>=5a9hY@p)${_nG$iVg0konZv@g zZ(lUimzNDHCDUM6E(W|PmERI`TzUw=LAjW_cr%)bFH;JA0OJ?=-jAD(=ny8_a*1)I zvfj{!5&;&|yO@PI-^-Kv59*`3274i3pPC5GaBF&}J;#ZAY*o!)*jAab_AhLK;4Dm- zw~BaM-cX6AnpHXaTR`9hV~7`vjG^lexZF=yHA01A8;4Mb0WV#vMW31i#;E;rz1BD9 zU3>M)(AndPh+FTc=zUsrm>cDF}_a`4F3&cTnrn~cizbH(smNWBVKxv2}DJ-7T6#St8JJJO9nyHo&m z!?5H3lCvxPgXUff^O`7YFgXIYoZK`gmFI~9&A{n#Z7*m@lMlz~E#`b$LX%#AYAG8G zjBLH^>NkVF$v0atCMOK4X1&aG$&}wd_P#G@aS{0Xxh?rP^K-qco9d)BHK%SkGaYf* zaGj-jW&eD}=fdk_Nt3~SEC?>}6Yb2->N!8EJD3gDrd0aGEO&NPKE*5>=HLm?K3fXq zAP2M|gP#Y8N-v5UxF09g&bD$-K_c13j$C;JX17<7{>A*y$IcONH`dfnP8LOpg5Qc^ zw}{645SIQW%v7?iRP&PwToEbKIc-9)n9N}mO z)+DaJ?IkNe*JdHUUNSfG%3C56Vuh$@b@2QzU%oaBE~P{ za9~y03ck8pjz5T7=FPCW)1H|cVV_4EE_{1yE^he~>7-nK^mHBze3YVTz^m0Zfe7xW zuYin1YAjmmDt?*>1|Gq!)3WyRo3=>=b{1X9e65!+wpl0T>^ZKHucuUbe7INM=Ms|M z8nfm+amD5HlZaIOisR_Js&0Rm%X9$9LL5`AXYofwj817YNkH8PU-OgXyc-67y>5lq z{D4F8jPB3y8(#kL;qI0uJzgpa`eBwyOJ>cAECk#Sx*W&3psy+rb{lbr)rP5G*7 z3}pVI6j5RPfTccfd`q2) z-bc)}y_`yf?Ht+J@{yWe2i#>RyPNCqMqp+BD~+<1a(R&mh(0U#hLJtcdHS6@u0O0k z(C}ol3y@ZY6h`9wOk7_1pf!O_Sm+>-R(Ca0L{7kg*})VRXn~t5#kezhcQ&9~tg}51F3eZ`kT`dp10oR~DJyg%G|yAv_o3 zS{KpFm#C>ZznoOGf5R{lk3(8(Wv&w<9_}UQ84q{i+*!tiER-EvM6`QoxTm+q!seno|6Mgs~j>V}M7cd&O#z?2|cxWJ)4xeY|eA zM5Y`vC;>|(mSgApKxXU6+y%DypJ!+h;ie}`9#2BaE$s-2?iF})lJ5X{aWd5DL)_41 z!M{oT!PA33K+eJtk2~;CvaS0&h1_E<(}4~JH0K<<5rP5biY0)xQu@ZGu8Jv1A%-8v ziB%K_OmP6*=Pwqf8J)vPox@k8)6-iUf0-Q1q9=-v%|#z+zu1Jn<&PxcS9;$rPXc^s zizM-uH}D=ac#ZB*VQv-h1pIgLPhlrdsVYS!#fng_DF!|-Pd!F^sbtUYr}xXyt99ak zl<{@*F}Wz1{c&3@`y`KApAS*>eGc1dcLZ7efNO1t``90!YYu9SROL3gU1)m#a5J9s zMA>g8zQ#M^swZE|H)lRcRO55tYHlM{zh>^ZLwv+tY34Y?Z^`|0iLxE4KuTiTcG8~b z8&NG+d{n+bw|$7CbNWQ@hiu7*F2Kdf(cOR1`(f--9{9H>0gh2%DNM`(3bE4FdzC5k zE&eZKKOB#kJ$n`zXhfL}r}&>~1{M_rtJkiu`RuKJ*us{}|CTCZt7)l0`LSK_#AKMe zrn1s^sS23#4=j3O$?jzR9{+?58#n>6KnF$T&*_vf!SRhP!AB0bJXn@IKPih}J?<7D z9GHT}?_4wA0oE4R+IJxUC}9}^*nofrnL=fzrR5IsE2?OXcWAba0H8AhYV4GBR1TmC zY2xjeF|QtJ*)BG%0E|2|CxZgguUvmR7(#%+h(%yZbi`dzqiW9AsT2#~lI&aU ziF7hBq$V!X)2f-ukoB^?TdOa7n6p>VtLD4eLj@rQ)tqVBncs&mN4b81YyiZ=W!)Au zyk8cX*LJSc%u%LD$|462~+iSC!a+gl$3$FtD(K-vT4mS8=4I zH4;0nRV+Ku7y&BQl_Mr3a2rr@k_=+V&fpR_LK!Q zx|nZ7h;p(qWc-79Gp^wyjA#D*NxjxlV)O%3Phor=2k6s?26i41K;Ir;S|WO}Db{)J zxt>$6)pIOfjfxoH*T!l8=_5c8Kw*#~a;&AFPq$oRvxuhRuOL>|yil0rb6 z>Vt{u)88>?R|Bc%73sv555>#g16p!g_VHhE082dnI*fSTr-h-^PM_;JxuWUb+b&wx zEk7NY4nRXl$!(}#2^18-RZ$^c;^U=u2rg7tvL5;>l9RgN6!IX5_vJ6<%HJ7l#hg8$ zTQ{qa36w+5er{**G@dvAN4;giD_OLf+ccFgnO;>|;>hZie1eUji?C5_mRVK=C}qHe z#d)*!38l@qmluc$QKVWU)?GSNpa)DLXEQ#$9)Iu|K5>4}kdU<>U>QdO0nLKjHebV(9Y2 zuE^6Js|G!^doViC*5Suj(&jxKN3x8q)V3&>5i+Y7Flopib^tMyf6xs(@qzAp4tTk# ze*yZDq|1-!Mh{yLKN_{)+6RO+IH-?;IP?*^&a%Os8!*`IQP{W(6rSCTl0dNLbgQcOnA+1OiaNPBCkMP@Yms9py zs9tSP!2;#HDbPcPPZjnI?C00wDe&HrCDU)#3HL{frrT|zKksM3{-o~WTN%`niLZ&uW2-!O)R8^>Pr z5Ny`lVSv}<7n?!7 zjLwtZ&IBn$_SMkb5g=1MTo+}U9Oq{{OarxV~I%9E3 z*Kz5Oxdr&QmQi5%t^+c^;!D3Up zgqyEuKJRo0-p=DO_FhwHES_?#;H}ok0pgMPkex5Gb}Aa&LuLvZX}$&FGy@9<^WO&b zvm7H(X^f_EOnrXETB?#WJcuoC*i|6R14$Be)up9bExmv*0!F{?boi#zhIc~A%bo_y zLwk7MfnIUJI?cLzl+s1G( zIZ7Uj-9=z!OxmnxoAkH;1n*0gPl}CrM>%aQ2`1YT|;BS z_WLpqfhk2BMmKtl{hR(Vxuz2|_e!)Hyi~=ecZCxUKN~mvxV6K8bSlW2*0A2ZK{hYxM7YydG%T}Q z07o)qZyeA_0L^f-o6_5103R9EvzON5$#6C z2q-hDgDUtyfJc*vrn+Kk`Jv<-GRM+P6JP;S<%6C3wvOHm&qOheBiN116(e6p4UAK} zxik*BO1&<(39PRIjuNCs73--5iN#BZ7G+A2%lUg*I!XN{ZhHh;8@0cE zzOOocLRz|PDONLRfB(4Fy*VxN7dPYJ_#c_}opoh==0ZN6z_)Bjw1Zs(;UP}>RxXR` zax0rbhL-56%w&k+T%}DE>ZNiRz0I$CA5w8Rbg8#(ymuYOfBupNb+;4Mu2OYd_r0cZ zM*Uj=@3IWj<(u+6Pl#6BxcgB=Lnywk*C16J+07^vMmJ*0BcFg&;X+DrCTN32QPg_(DIK^TTi6KYca`JiAa`-3VHbsF=`-eL)doFmt6z6Q zIms`tH$g{|A>3wp67+PlF5x#NHSA*Etn7?*v#P5SXu3!i0RF4u$)PC((Gn>~l!eeT;7KY+ji zr9BXTWogGZh)RTCryCGj?!ZA9`m|-!?5l%n_A^bi{7D+&`A;=lSS-gPTNs}g3JDzW z8<&Jg|9xZbb^>5bRZOPg0c}&>*A>Q?~?B;wueD`S9%d-*HWj_1DBv(+oBb3AO8sc&Z z^-158YkTPl8*)tjvb&)w*oj90Yl4q1WkuuIw;l&r@9>2fKG`?W40FBwnK;W@C5caV zwW1jRh5PHzaR>zb1C9BEqDrjr$0?!@w?9M%vG0S)(@x&q?&svx|BJJN7587@DeOK$ z{bqH8;djhx{XF{;cB|Yi`D|qra7W$CNu{*S?ktc#Dd{YeqpK2;iHLxJ6z%8Dvmoes zwR_sJy$Qa1@OOhpn3TpF3ELT&vx=C9BY+v^l=M617`D2hSoaW+lS4O!#XH>fi9PuF zZyyH|cgZ2L8%|gVJ<~Ux(Cjkdq>HjgFVF6~tdGiYMlHy7#B)UGgY#T?5?c&!iF@U~ zvX|ab@4CWoz7r1f`hpj0ROjkq^~NQ@k&I0uy0QJ4Mv^;9JSky*RR4DztNW+iXH0$w z!SfSO-xkOXzk=Kn0{#>+#1YC?!LBm^tXXzXzZZiqzp{-4OhjX+le{jyz2$}K0B3(y z=QNzlmp#Aj&w}C&5L_-6%kStqO0_mI$9hJwtuA5A**I{!AVE6q8I9=gga(`4dQM{XCEw57m%l%(=A%x==i#Z*u7G*g>6C_!eby z{+x}{`{r`b=dkO-MS+7NJAJ#v|1#J4ibE^LfM`?XW#(nD>W|X0n&S3YQ@s6}y5vfj ziA;(`Q>vcICz!Wip6!C$-%(DYIDWwy(K@3QY!hvAMjMq;f?g7Nv}`d)=G<13a`qOx z%wqn(G-CDNSh$iJku>jd0A}oYPYM@H=8raH$kuU{ERYmM` z1)jIO{7A~^=dx9cAo`7mY9$oib1x;l{|ooAvwJur?}LTG`Q({T<7K#O#ixr+b94iW zC~D?lF`(WOyudzz_$5DXD>8MR(*&~@0a)KX;M~8&wrAw`_oM#RU!25}9mvKt-}ClK zuGum^cFnonyWVFiVBJoSAH6y3-qR%Xe?ax#xbWT$<(nPI93k_IIJ^f>hR`^rSS*3~ zSoab!5IhkTVKV2$kqUK(>a8J5w`2Z_~LYCw^hfM`^bnv=7ofppFUex z)ndD_lI=P=lDbDKI8Qin(;lU`Rb%e+GIYy|xc;{S1kaIV;xD`H6fv*nQ=3(9W|tM3 zVC?rih96a|8FeQVGg`Sh-+(mp<`;J_vEj0Y>Mb>2YD40yv z{qnjk00Y-o(F7vmH*y_@U-k7FF5t)y!9A?rhf7}GlN7sF@!*bBt=*?%zBd) zKpcxYBgX^@25=L?f{mY$tth+&tpK+UP}hgEbCyW4^m2$HWM*<7zSEb;7f9u9#D45gZdk+9h0#S*{>O2Ojv>PF~LCkL$2z#j0{%tkfOAR-JJ| z)56#4t+K6#sGgS;UB}skYmOeG@nbaI>;Of1Pl|s$~%85g?$KfR1|!7G`mw)KiJJ1J9PPF z(dX%Rkml~dWzI+Bg1BBBqCrF*{1xIF#+(j&`wcAg;y*eR3IO0!usc7WZ%)5H4>gNK)AUY10^>5 z4MR0ANDX3Pa5cM^{1>2$%jGmBYm}g@Xq7aeF93EU=P^tmoOW~L58kRf?;5wD~v7uU@$kej}+OA~w0@PAFM zS=U?cKDh6fP0xTZT(^8a2ST+Rw=H)t!Yc~@$;Br4<&|G4C5#po?a}F+t3vCxhYnS&dFqq*hFpv zk?8`hqdR=en$M{Km3V@1g>1R0d_@_LkfNXdh`CCNK0;%>-J)JOW!krwfl%D5iFR)^{@6GviG+>+AU`f#%|KtXDIMwC`u@tXE&}C z#v?X`{p|4av$ELQAPIl<+`*qf+@A)^kL2O{ z$EZ~w@kPLnF)^x!ukT;W1^0Ef_3>Q3d?(^3H$o-yo-Ri3e*YdwY*jmRtbP|P;sn`c zh_xF3w?9BvzbsY)Pg()5uIq$0$qv6Eyon6A8%9iH6T2g8PS^d?^21!~@wxme-?5KC zHBSV)4&z>yF~3Z_+*0rvmobX|L{I=iwLE(9JSwI?~L z!X?j)Kv1Yv2oPQ0R9oX+S$TLUo?C0DEGHYkw`+5n;gZ3i`l%J^xn#$sbiOu_{|uf z@4qf+q$J`LqENu$Wf#l(Z@cnLdKN)_@TXyXg6R2=ov$I35$1s z!H2d`+tQE^(EAj^n*2Bt1^|}7>qj#|9AsNmoYsGgZbL@KbCBQsdmHZp@{VX8zsKv} zo$BRC(RkwO;XmC~^lS(uIWn;Hg9i5s!ZSp((Ncw*`Un$x=fA0|eEULrY2DkZp`2Xg zTZN4MLi?Igy)y2+uvy$cQLVwju-mmug{C2 z=;`g+%H&{P?+?U4qF?e?gfnlOD|IWG^OZGuAbsYN@I+ga87w42_#?D}v8=g$vm{>}IeSmzv8V|6YKwQg9JP=>Tt6GA9vL zjfkxPRWhF*DH^>vC;3wQRGWIFj@S(4L&Hl}vq+1@Bb3!Jb*%o+OrU9pZ}tsSPuFf* zyh1%nb>w(-bif)#91(>)NmND*h*T<$&3Rs3PyhFKfWH)7nTgE{3Hg`J3u}Jln+ZM? z!J#XVib8^}<20K*nmM}$5W@WOBtV=1FaiKCiDYa5gbyZGt5P9Tj2)PodCeph(6%nbwlY~V6 zI~5=g&-?Iv#p1w$;Uq*9!v;>S^oh}T&YJ7Z;`y)+ zia%b^^(wYlX`Gw}F6D%2zvKtpkVd*nem&%I-Si9~)rM)@db|P13G97ep7ZcU1+T{Q z<*xniEvq%&``0=Oj~HN$7MY@lzywObA>qKiIwIfz`uD6%nl6uGRzIhnVge9agFWM_ z7VK;u`wp6=>*ctG_$`ayj~sb`kwe{C%pyO8tHa+U^SO0w`VsRfrjfFJ%m9ee5`+-^ zg`d|Tfam;92+Vn^CepJkV}W>qf2E@#48ECuziFU456cBFanEGthJG&g=eBB z)vcBFq)hiplH@QCQW6F3D@3*=Pi8qzr#WIsQK(Q+Dw+23N`$;+K=?+)9z9=roUD#n zhAoC)v$w8jw(!Sm;$J)#UYa~9;hwRiY%mJ8>hd>93VrPk?Brot`to9Zqmap5llYyv zMUNLr1PTN!f#wBkZhdo01#~(9bG~i)l`h<-Df3msC;_7)lO-YHEP)UEiqo4o?aZc6 zytMhRxaK=c=QGL`g;`MvD*`HKVsg87_iElw?FVqlaMRDl?)C zLPE5`U>L3vyx#j}J zaZfU?z>oX7y5YQSh;=xsTJ=NkWyPA%i*-5>c(UK2tE$rzb!BXv_nS{dlhoU`#Z0t` zRt=GUiS~B>6JYFLAu($se{huw>RvtXzeio=qm;_30)-5KN<2xYdG&2moqS?lyz;=$ z#>kjy>@mJ0*Dp5k+I65g>#};#eUtkI*3vItsrNgzP7zyexsBqOY27&-WI1o~CHl6^ z0>naV48OANA)o_m_G<6-^6MikKmlh>0C^RFF%vtk8r?#9dP|09!YA^z=7tjU zC1DL7c~Mz{Q~GTa#NSWHR_kRPg-1Z=!rXhmbw89>E@O?zM^pg3vYBfjBhSz1FD$z{ z@3kJ-Q%PT}v}=6ZMp~H?IUwCl%4LEoFx{CV<2D<6rv!Bm?$|8s+r6dsZG zht!48sz`KWeCR8}gUwd}nM6JS=4mOeheZME0dnR5O_k2zMpz`ZD@4pQlMgx?0hA3x zU0zj!T1UAn)ZU@P^493zasAbLt9g~4voX0Y=Fdp@37*`CjZhFg&nFd?JQ6ISmtV4& zmM5Geyqz%F#LJOz0AUAyXx;5k;@?mbwN%kEo!gV}1PG2_#)o=u-xvvzbRnh;5d@L2 z)W#VGoSO%Zzj+JywQI#k7uA^bYtwTFh#q|(CUO9Hef)Jp`U~gmZLe8>Ncobgl-O?R z=X(OsOeFGjS}^}jJnlV6GyJsi<2N$3#Xf#MI0K-j%6VDXXo8dv}Mb*tFb5MT(@9k-J znN{avj6tGrL6fC`YKYq8BS0`OsK<`8zM|EaE#C%EX)tmt6B*I)c!YV+8SHkR{Q~er zf<$=({R_ytVV9$~OyKRew6up#GCuO-sUgLJYQ_J z&)M^7tBdg8{T--_o+mVWv^&$-zFH3n-*;6FOhG=umkd`^xCywri|nsxS096zZ%8#1 zu9mTI*@LvXSAU{plLU>ehvRLZS${uke$xCA^58(YFBZ1lXlcVyp3|E=<0R+j+d>B| z8FliibD7vFNyS$wwvTVJ@R)Bq2$6BbN{t^T#&^~>oo8jjqCX&8W@fZZAl`oHdD#+u z=65B2UBzN?2#)J~nB@OtV^5a}6V;1VP8C?;1Wv+n)>~FF zjaM%Jz2nGUEz*}&l{bz-70fq7h4k(r=AVNtKdpG_fw+dBqM}DKcXarnuBaXEmFU%I z*Q4m-DgmGGEuAw8LacUZTgbblUASxSp+~gnvgBvk{zHWF?jE%*Uu=S~{pk0KoDufR z!%y|5BFXBI9>0qMqhjGykDiBGOh4U0ih1??ZJlP|=}Au*hM}vTRd2z56gBnfHI$SA zl9lZ34g0L8n6*ZFwY$Z<6sm2UIV6~dv=kVrnQL5#{n44LnTTR(H_{*SBtQ0|LV zL$9{mIYR*ie#g1mq3rEhC2$c0Qd3eYg-|wr-@dEnq&HCk;YwpkMP*P2_@D;zBtc}% z`+c~R;3LE+Q$*>2yrAlTm75pM%I3FG~Djy@F7f$b2 zPj0M5xK+r21@wZ=rY^hOYhzR8JP+>%u0Gy*h!XY5;rNiDPnZAjP`oW`kdb*euG+2KB>0(`OuAn{-($6= z8}{#H(xF)cJmwZW6f-Fh!3dEeSt$^cI`nD!L$}hK*YY~x93%L`J&u*Fl|hwVx&^%O z^0Y!hWO$*f%0#MitAF(5K7H{=Ce`9gI#644fx}+wneF97l2!d6+->*g(4LO&X^-pX z;yfMcE335*NPOWiYw(DfR@*c+GjM<&w7M7P_j2`^Ilgdah7N*Qkz zYK%`~l3EOkFPK{?WMK~C?x=K&u3}!(}C8gMlqUQr`lu;KQS|#u=S_oQAefC7(@Tc4wryXw96g#boXQ=hG1(Q z=_%P$9mcPPyKZsOi8=bU#meH1OBUyHr}!P>7IFd zD7!G8a4n{ME+druWr59SJ@0~1*vMp3kseoG zjH#-jhKTy&&aP0%5q7IK6}%Q+!DH>}iS@|Oq(?b-mqqWa(u2^xi>I0o)g}CUzZ%kn zE*IDlJ@ruAJ|CBiFhmIUIGHjUv@vPF-T=#~I{w&)Fi?jlLS`9ldZp5#bCb>WCD*FO zH~cg@9Zl^O#~TXj?!|m;-=a8Tn%5w?GA8{t%f#d6Dow~lO_a;KwqteAH)EFCEK=lW79;-}ZkyE;)!o`QWT)g?M<9vxypRTu2O3~Z$kt|@XG zd|~RxM}^NpwVIT?rvg6DD^kldSi^_GxnM%dn1)meGy+WOIEgMx7@^n;8e_bo;hhU5 zamc99pGV4R8N!nt6u689X~0}`m~-EnX#?O zk6f2@HGbkg$jx+%C6nIh^#cZ0gZr%_Nm%LNNVL;bQccI!7+)E?@0mVDS1HFK_#$3K z`|7tZE;g3I@)VBUF}k8JY8MQJ)XpQ!PkxNQkT*c>Wq#M5KdK2%j2{n3~(p zM%+x71GT2<)BO{F3P0*Qm?%XuyDlD~wxh6_VBaWIt;kmXIBD7RRxyT+mbHuj0I1fa zdOh7pRmPB)gdaSK&RWvE84z!Vh}4b>TN5hE5u0n+;GJvT$ll`6e5OygC`XINSaH+R z1k%Pa6nloAs#7+;V~y7Wv{&g1w*kMcRJ39XP!7Q`>Ta!;L;!FFeJlAJMU|dyv749{ z+s>5_UkhBzK=sQ^sx)ef;-dm?*gtC6jgTHnoZjd}eL5wBlij8D_B_+Hvc00hop~47 zY4D2gg(>A0$%P-=aJ!}hw;}{m(->|l*B$ndTLx#GtwntB87o@?FKH4n?`_2!RO= zuV*p7`}asU$L0R^x9GDV`1!~D7X@gX7dwg-AHSzQwqk5D8{8MhX=s;=b9mDPUN|o8DEAM8 zHO9z-e@}7hj+$1cpGAXtf4yi&*#9@cfr^e~=;qgJmzwMV6W*6}?uCfN zF?30jv0$_gq94e3VyBxy8;|4N%@Xvlg<`)-rd`h*GvJT zU3i$*?i$1m8y12!G%qRvA-z{em}LH`U!#X}LNt}e8ig|n8d)>ZRJNN3OwA`osUfbt zRyH>6&GxS6C1?CF2$vEBp1Fbev)VSxLv))ZV!xoy)hnRKS`I`Th#yDdNT%Kw{+)3z z^tvkwcQN@_lz`RT1;Qb5o0Mp$X8%_4C>A!+^N2p|ze2Nkk(Tv;H$3a4Gtr3mAc75n R8;OPnY-C|rcl%-d{{bAML#zM* literal 0 HcmV?d00001 diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index 1fc9d5663..7e83b9b3c 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -864,11 +864,9 @@ The positive y axis points upwards, the positive x axis points to the right, and ## Use Case 5: Simple 3D Model - This example is a Manifest with a single Scene, with a single model of a space suit painted at the Scene's origin. - - +> PNG of Scene ```jsonc { @@ -910,12 +908,138 @@ This example is a Manifest with a single Scene, with a single model of a space s **Key Points** * As this Scene only has one resource in it (the model), the client must provide lighting and a default camera. * In this simplest use case, the Painting Annotation targets the whole Scene rather than a specific point. The client places the model's origin at the Scene's origin. This is in contrast to the _bounded_ Containers `Canvas` and `Timeline`, where the painted resource fills the Container completely. +{: .note} + + +## Use Case 5a: Simple 3D Model in Configured Scene + +This example adds a Light and a Camera to the previous example, and places the model at a specific point rather than at the default origin position. The Light is green and has a position, but has its default orientation of looking along the negative-y axis as no rotation has been specified. The Camera has a position and is pointing at the model's origin via the `lookAt` property. The Scene has a background color. + +> PNG of Scene - lurid green light half-illuminating the astronaut. + +Use case 5a + + +```jsonc + { + "@context": "http://iiif.io/api/presentation/4/context.json", + "id": "https://example.org/iiif/3d/model_origin.json", + "type": "Manifest", + "label": { "en": ["Single Model with light and Camera"] }, + "summary": { "en": ["Viewer should render the model at (-1,0,1), add the light, and base the viewport on the provided camera"] }, + "items": [ + { + "id": "https://example.org/iiif/scene1/page/p1/1", + "type": "Scene", + "label": { "en": ["A Scene"] }, + "backgroundColor": "#FF00FE", + "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/astronaut/astronaut.glb", + "type": "Model", + "format": "model/gltf-binary" + }, + "target": { + "type": "SpecificResource", + "source": [ + { + "id": "https://example.org/iiif/scene1/page/p1/1", + "type": "Scene" + } + ], + "selector": [ + { + "type": "PointSelector", + "x": -1.0, + "y": 1.0, + "z": 1.0 + } + ] + } + }, + { + "id": "https://example.org/iiif/3d/anno2", + "type": "Annotation", + "motivation": ["painting"], + "body": { + "id": "https://example.org/iiif/3d/cameras/1", + "type": "PerspectiveCamera", + "label": {"en": ["Perspective Camera 1"]}, + "lookAt": { + "id": "https://example.org/iiif/3d/anno1", + "type": "Annotation" + } + }, + "target": { + "type": "SpecificResource", + "source": [ + { + "id": "https://example.org/iiif/scene1/page/p1/1", + "type": "Scene" + } + ], + "selector": [ + { + "type": "PointSelector", + "x": 0.0, + "y": 6.0, + "z": 10.0 + } + ] + } + }, + { + "id": "https://example.org/iiif/3d/anno2", + "type": "Annotation", + "motivation": ["painting"], + "body": { + "id": "https://example.org/iiif/3d/lights/1", + "type": "SpotLight", + "label": {"en": ["Spot Light 1"]}, + "angle": 90.0, + "color": "#A0FFA0" + }, + "target": { + "type": "SpecificResource", + "source": { + "id": "https://example.org/iiif/scene1/page/p1/1", + "type": "Scene" + }, + "selector": [ + { + "type": "PointSelector", + "x": 0.0, + "y": 3.0, + "z": 1.0 + } + ] + } + } + ] + } + ] + } + ] +} +``` -* this is equivalent to having a point selector that targets the origin. -* The model also has its own local coordinate space, which may be scaled differently from the Scene's coordinate space. +> +**Key Points** +* This example uses some of the Scene-Specific resources introduced in the next section. +* A Point Selector explicitly places the model in the Scene via the Painting Annotation's `target` property. In the previous example, there was an implicit Point Selector placing the model at (0,0,0) because no explicit Point Selector was provided. +* The provided Light should replace any default lighting the client might have. {: .note} + ## Use Case 6: Complex Scene @@ -1479,7 +1603,7 @@ partOf - -# Content State +# Content State and toggles 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: From 795218a4880e4946d5a8e808cb6e0aab09dd8ad5 Mon Sep 17 00:00:00 2001 From: tomcrane Date: Fri, 6 Jun 2025 12:05:31 +0100 Subject: [PATCH 115/130] near far fov --- source/presentation/4.0/index.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index 7e83b9b3c..9db742358 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -913,7 +913,7 @@ This example is a Manifest with a single Scene, with a single model of a space s ## Use Case 5a: Simple 3D Model in Configured Scene -This example adds a Light and a Camera to the previous example, and places the model at a specific point rather than at the default origin position. The Light is green and has a position, but has its default orientation of looking along the negative-y axis as no rotation has been specified. The Camera has a position and is pointing at the model's origin via the `lookAt` property. The Scene has a background color. +This example adds a Light and a Camera to the previous example, and places the model at a specific point rather than at the default origin position. The Light is green and has a position, but has its default orientation of looking along the negative-y axis as no rotation has been specified. The Camera has a position and is pointing at the model's origin via the `lookAt` property. The Camera has a `fieldOfView` of 50. The `near` and `far` properties are included to ensure the model falls within the camera's range (although unnecessary in a simple Scene like this). The Scene has a background color. > PNG of Scene - lurid green light half-illuminating the astronaut. @@ -976,7 +976,10 @@ This example adds a Light and a Camera to the previous example, and places the m "lookAt": { "id": "https://example.org/iiif/3d/anno1", "type": "Annotation" - } + }, + "near": 1, + "far": 100, + "fieldOfView": 50 }, "target": { "type": "SpecificResource", From 8e79314adc78ab8da9546e8a1e0e253bc55c0f84 Mon Sep 17 00:00:00 2001 From: Rob Sanderson Date: Fri, 6 Jun 2025 12:10:49 +0100 Subject: [PATCH 116/130] near, far, angle --- source/presentation/4.0/model.md | 54 +++++++++++++++++--------------- 1 file changed, 29 insertions(+), 25 deletions(-) diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index 2cd75396f..ddc312db9 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -423,6 +423,8 @@ Content Resources _MUST_ have an HTTP(s) given in `id`. It _MUST_ be able to be If the Content Resource is an Image, and a IIIF Image service is available for it, then the `id` property of the Content Resource _MAY_ be a complete URI to any particular representation supported by the Image Service, such as `https://example.org/image1/full/1000,/0/default.jpg`, but _MUST NOT_ be just the URI of the Image Service. The Image _SHOULD_ have the service referenced from it using the `service` property. +If the Content Resource is a 3d Model, then regardless of the file format, it is treated as being within an infinitely large three dimensional space with an origin (0 on all three axes). + If there is a need to distinguish between Content Resources, then the resource _SHOULD_ have the `label` property. Containers _MAY_ be treated as content resources for the purposes of annotating on to other Containers. In this situation, the Container _MAY_ be [embedded][prezi30-terminology] within the Annotation, be a reference within the same Manifest, or require dereferencing to obtain its description. @@ -565,8 +567,8 @@ The Image API Selector has properties following the parameters from the API, and {: .api-table} __Properties__
-A IIIF Image API Selector _MUST_ have the following properties: [id](#id), [type](#type).

-A IIIF Image API Selector _MAY_ have the following properties: [region](#region), [size](#size), [rotation](#rotation), [quality](#quality), [format](#format). +A IIIF Image API Selector _MUST_ have the following properties: [type](#type).

+A IIIF Image API Selector _MAY_ have the following properties: [id](#id), [region](#region), [size](#size), [rotation](#rotation), [quality](#quality), [format](#format). {: .note} ```json @@ -598,7 +600,7 @@ A Range _MAY_ have the following properties: [start](#start), [supplementary](#s ### Scene Components {: #scene-components} -The following classes are only usable within Scenes. +The following classes are typically used within Scenes. They might have utility in other contexts, however those uses have not been defined in this specification. #### Cameras {: #Camera} @@ -608,8 +610,8 @@ A Camera provides a view of a region of a Scene's space from a particular positi If either the position or direction is not specified, then the position defaults to the origin of the Scene, and the direction defaults to pointing along the z axis towards negative infinity. __Properties__
-All Cameras _MUST_ have the following properties: [id](#id), and [type](#type).

-All Cameras _MAY_ have the following properties: [label](#label), [lookAt](#lookAt), [near](#near), and [far](#far) +All Cameras _MUST_ have the following properties: [type](#type).

+All Cameras _MAY_ have the following properties: [id](#id), [label](#label), [lookAt](#lookAt), [near](#near), and [far](#far) {: .note} @@ -668,9 +670,9 @@ This specification does not define other aspects of Lights, such as the rate of The specification defines four types of Light, below. __Properties__
-All Lights _MUST_ have the following properties: [id](#id), and [type](#type).

+All Lights _MUST_ have the following properties: [type](#type).

All Lights _SHOULD_ have the following properties: [color](#color), and [intensity](#intensity).

-All Lights _MAY_ have the following properties: [label](#label). +All Lights _MAY_ have the following properties: [id](#id), and [label](#label). {: .note} @@ -768,9 +770,9 @@ As the audio content must come from an audio resource, the Audio Emitter classes Volume is given relative to the input audio content's volume, and thus a volume of 1.0 is the volume as provided, 0.5 is half the volume, and 2.0 is double the volume. __Properties__
-All Audio Emitters _MUST_ have the following properties: [id](#id), [type](#type) and [source](#source).

+All Audio Emitters _MUST_ have the following properties: [type](#type) and [source](#source).

All Audio Emitters _SHOULD_ have the following properties: [volume](#volume).

-All Audio Emitters _MAY_ have the following properties: [label](#label). +All Audio Emitters _MAY_ have the following properties: [id](#id) and [label](#label). {: .note} ##### Ambient Audio @@ -851,8 +853,8 @@ Spot Audio Emitters _MAY_ have the following additional properties: [lookAt](#lo An operation to transform a 3D resource. Transforms are specified by the [transform](#transform) property on a Specific Resource. Transforms are carried out on a resource in the implicit or explicit local coordinate space of the resource, and are performed prior to painting that resource into any subsequent coordinate space. __Properties__
-All Transforms _MUST_ have the following properties: [id](#id), [type](#type).

-All Transforms _MAY_ have the following properties: [label](#label), [x](#x), [y](#y), and [z](#z). +All Transforms _MUST_ have the following properties: [type](#type).

+All Transforms _MAY_ have the following properties: [id](#id), [label](#label), [x](#x), [y](#y), and [z](#z). {: .note} ##### Rotate Transform @@ -917,9 +919,9 @@ An Agent represents a person or organization, typically referenced with the `pro The Agent is not intended to be used as a primary identifier for the person or organization, nor to provide structured metadata, but instead to ensure that the information to be rendered to the user can be kept together in the situation when there are multiple agents being referenced. __Properties__
-An Agent _MUST_ have the following properties: [id](#id), [type](#type), and [label](#label).

-An Agent _SHOULD_ have the following properties: [homepage](#homepage), and [logo](#logo)

. -An Agent _MAY_ have the following properties: [seeAlso](#seeAlso), and [summary](#summary). +An Agent _MUST_ have the following properties: [type](#type) and [label](#label).

+An Agent _SHOULD_ have the following properties: [homepage](#homepage) and [logo](#logo)

. +An Agent _MAY_ have the following properties: [id](#id), [seeAlso](#seeAlso) and [summary](#summary). {: .note} {% include api/code_header.html %} @@ -973,8 +975,8 @@ Services will also have specific requirements as to additional properties based A UnitValue expresses a quantity through a numerical value and associated unit of measurement. The value of `unit` _MUST_ be drawn from the list of possible units, or a registered extension. __Properties__
-A Unit Value _MUST_ have the following properties: [id](#id), [type](#type), [value](#value), and [unit](#unit).

-A Unit Value _MAY_ have the following properties: [label](#label). +A Unit Value _MUST_ have the following properties: [type](#type), [value](#value), and [unit](#unit).

+A Unit Value _MAY_ have the following properties: [id](#id) and [label](#label). {: .note} {% include api/code_header.html %} @@ -1025,12 +1027,14 @@ The value of `accompanyingContainer` _MUST_ be a JSON object with the `id` and ` ### angle {: #angle} -!!! warning "Need more info" +The `angle` property is used with SpotLights and Spot Audio Emitters to define the radius of the cone of emitted light or sound. Note that the `fieldOfView` property is defined as the entire field of view, not half (as might be inferred from `angle` using radius). The value _MUST_ be a floating point number greater than 0 and less than 90, and is measure in degrees. If this property is not specified, then the default value is client-dependent. * A SpotLight _SHOULD_ have the `angle` property.
Clients _SHOULD_ process the `angle` property on SpotLights. +* A Spot Audio Emitter _SHOULD_ have the `angle` property.
+ Clients _SHOULD_ process the `angle` property on Spot Audio Emitters. {% include api/code_header.html %} ```json @@ -1215,7 +1219,7 @@ _On Annotation, a list of strings drawn from table_ ### far {: #far} -This property gives the distance from the camera after which objects are no longer visible. Objects further from the camera than the `far` distance cannot be seen. +This property gives the distance along the axis of the camera's orientation after which objects are no longer visible. Objects further from the camera than the `far` distance cannot be seen. The value is a non-negative floating point number, in the coordinate space of the Scene in which the Camera is positioned. The value _MUST_ be greater than the value for `near` of the same Camera. If this property is not specified, then the default value is client-dependent. @@ -1229,9 +1233,7 @@ The value is a non-negative floating point number, in the coordinate space of th ### fieldOfView {: #fieldOfView} -The angle which a PerspectiveCamera can "see". - -!!! warning "Need more info" +The vertical projection angle from the top plane to the bottom plane of the camera's field of view, specified in degrees. The value _MUST_ be a floating point number greater than 0 and less than 180, and is measured in degrees. If this property is not specified, then the default value is client-dependent. @@ -1350,6 +1352,8 @@ The value _MUST_ be a string, and the value _MUST_ be an absolute HTTP(S) URI fo The existence of an HTTP(S) URI in the `id` property does not mean that the URI will always be dereferenceable. If the resource with the `id` property is embedded, it _MAY_ also be dereferenceable. If the resource is referenced, it _MUST_ be dereferenceable. +If a publisher wishes for a resource be able to be referenced, such as in an Annotation, then the resource _MUST_ have an `id` property. + * Collections, Collection Pages, Manifests, Timelines, Canvases, Scenes, Annotations, Annotation Pages, Annotation Collections, Ranges, Content Resources, and Services _MUST_ have the `id` property.
Clients _MAY_ render `id` on any resource type, and _SHOULD_ render `id` on Collections, Manifests and Canvases. * All other resources _MAY_ have the `id` property.
@@ -1554,7 +1558,6 @@ The value of this property _MUST_ be an array of JSON objects, each of which _MU ### lookAt {: #lookAt} -_Summary here_ It is useful to be able to rotate a light or camera or audio resource such that it is facing another object or point in the Scene, rather than calculating the angles within the Scene's coordinate space. This is accomplished with a property called `lookAt`, valid on DirectionalLight, SpotLight, and all Cameras. The value of the property is either a PointSelector, a WktSelector, the URI of an Annotation which paints something into the current Scene, or a Specific Resource with a selector identifying a point or region in an arbitrary container. If the value is a PointSelector, then the light or camera resource is rotated around the x and y axes such that it is facing the given point. If the value is a WktSelector, then the resource should be rotated to face the given region. If the value is an Annotation which targets a point via a PointSelector, URI fragment or other mechanism, then the resource should be rotated to face that point. If the value is a Specific Resource, the source container for the Specific Resource must be painted into the current Scene, and the Specific Resource selector should identify a point or region in the source container. In this case, the light or camera resource should be rotated to face the point or region in the source container where the point or region is located within the current Scene's coordinate space. This allows light or camera resources to face a specific 2D point on a Canvas painted into a 3D scene. @@ -1567,7 +1570,7 @@ The value _MUST_ be a JSON object, conforming to either a reference to an Annota * A Camera _MAY_ have the `lookAt` property.
Clients _SHOULD_ process the `lookAt` property on Cameras. * A SpotLight or a DirectionalLight _SHOULD_ have the `lookAt` property.
-* A SpotSound _SHOULD_ have the `lookAt` property. +* A SpotAudio _SHOULD_ have the `lookAt` property. {% include api/code_header.html %} ```json @@ -1682,7 +1685,7 @@ The value of the property _MUST_ be a [GeoJSON Feature Collection] [link] contai ### near {: #near} -This property gives the distance from the camera from which objects are visible. Objects closer to the camera than the `near` distance cannot be seen. +This property gives the distance along the cameria's axis of orientation from which objects are visible. Objects closer to the camera than the `near` distance cannot be seen. The value is a non-negative floating point number, in the coordinate space of the Scene in which the Camera is positioned. The value _MUST_ be less than the value for `far` for the same Camera. If this property is not specified, then the default value is client-dependent. @@ -2110,6 +2113,7 @@ The value _MUST_ be an array of JSON objects. Each object _MUST_ be a service re A single UnitValue that defines a real-world scale factor for the coordinate units of a Canvas or Scene. For a Canvas, this defines the physical distance corresponding to the length of a single Canvas coordinate unit. A Canvas with a `width` of 5000 and a `spatialScale` with `value` 0.00008 represents a physical space 0.4 meters wide. For a Scene, this defines the physical distance corresponding to the XYZ coordinate units, or in other words, the physical distance length of a unit vector in the 3D coordinate space. The value of `unit` _MUST_ be a length unit. In this specification, the only length unit defined is `m`, i.e., meters. Unless other values are defined externally as an [extension][prezi30-ldce], the value of `unit` _SHOULD_ always be `m`. +To assert a `spatialScale` for a Content Resource, the resource _MUST_ first be painted into a Container and the `spatialScale` is asserted on that Container. For example, a 3d model would be painted into a Scene, and then `spatialScale` is asserted on the Scene. {% include api/code_header.html %} ``` json-doc @@ -2128,7 +2132,6 @@ A single UnitValue that defines a real-world scale factor for the coordinate uni * A Scene _MAY_ have the `spatialScale` property.
Clients _SHOULD_ process `spatialScale` on a Scene. - ### start {: #start} @@ -2252,6 +2255,7 @@ The value _MUST_ be a JSON object, which _MUST_ have the `id` and `type` propert A single UnitValue that defines a multiplier or scale factor for the `duration` property of a Container, indicating that one second in "Container time" represents some other real world duration. A Canvas with a `duration` of 450 seconds and a `temporalScale` with `value` 1000 represents a real-world duration of 450,000 seconds (5.2 days), for example a time-lapse video of a growing plant. The value of `unit` _MUST_ be a time unit. In this specification, the only time unit defined is `s`, i.e., seconds. Unless other values are defined externally as an [extension][prezi30-ldce], the value of `unit` _SHOULD_ always be `s`. +To assert a `temporalScale` for a Content Resource, the resource _MUST_ first be painted into a Container with a `duration` and the `temporalScale` is asserted on that Container. For example, an Audio file is painted into a Timeline, and then `temporalScale` is asserted on the Timeline. {% include api/code_header.html %} ``` json-doc From 162ca89672e577a972f0b20ca9d5a6989c7eb31c Mon Sep 17 00:00:00 2001 From: Rob Sanderson Date: Fri, 6 Jun 2025 12:12:59 +0100 Subject: [PATCH 117/130] horizontal angle --- source/presentation/4.0/model.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index ddc312db9..b75f3b859 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -1233,7 +1233,7 @@ The value is a non-negative floating point number, in the coordinate space of th ### fieldOfView {: #fieldOfView} -The vertical projection angle from the top plane to the bottom plane of the camera's field of view, specified in degrees. +The vertical projection angle from the top plane to the bottom plane of the camera's field of view, specified in degrees. The horizontal projection angle is dependent on the aspect ratio of the client's viewport. The value _MUST_ be a floating point number greater than 0 and less than 180, and is measured in degrees. If this property is not specified, then the default value is client-dependent. From 2d809dad9348c5b6a5d13d2185e017c7f7529251 Mon Sep 17 00:00:00 2001 From: Dawn Childress Date: Fri, 6 Jun 2025 04:26:40 -0700 Subject: [PATCH 118/130] use case 5. 5a definitions --- source/presentation/4.0/index.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index 9db742358..112333720 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -1041,7 +1041,10 @@ This example adds a Light and a Camera to the previous example, and places the m * The provided Light should replace any default lighting the client might have. {: .note} - +__Definitions__
+Classes: [Manifest](#model/Manifest), [Scene](#model/Scene), [Model](#model/Model), [SpecificResource](#model/SpecificResource), [PointSelector](#model/PointSelector), [PerspectiveCamera](#model/PerspectiveCamera), [SpotLight](#model/SpotLight)

+Properties: [backgroundColor](#model/backgroundColor), [lookAt](#model/lookAt), [near](#model/near), [far](#model/far), [feildOfView](#model/fieldOfView), [angle](#model/angle), [color](#model/color) +{: .note} ## Use Case 6: Complex Scene From 6aa204854e6bd823b02bf87f0b63c2aebb0e9d04 Mon Sep 17 00:00:00 2001 From: Rob Sanderson Date: Fri, 6 Jun 2025 13:41:44 +0100 Subject: [PATCH 119/130] updates --- source/presentation/4.0/model.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index b75f3b859..893ae6729 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -605,7 +605,7 @@ The following classes are typically used within Scenes. They might have utility #### Cameras {: #Camera} -A Camera provides a view of a region of a Scene's space from a particular position within the Scene; the client constructs a viewport into the Scene and uses the Camera to render that region. The size and aspect ratio of the viewport is client and device dependent. +A Camera provides a view of a region of a Scene's space from a particular position within the Scene; the client constructs a viewport into the Scene and uses the Camera to render that region. The size and aspect ratio of the viewport is client and device dependent. The first Camera defined in a Scene without the `hidden` behavior is the default Camera. If either the position or direction is not specified, then the position defaults to the origin of the Scene, and the direction defaults to pointing along the z axis towards negative infinity. @@ -645,6 +645,8 @@ A Perspective Camera mimics the way the human eye sees, in that objects further The region of the Scene's space that is observable by the camera is bounded by two planes orthogonal to the direction the camera is facing, given in the `near` and `far` properties, and a vertical projection angle that provides the top and bottom planes of the region in the `fieldOfView` property. +drawing of a geometrical frustrum truncated by near and far distances + __Properties__
Perspective Cameras _SHOULD_ have the following additional properties: [fieldOfView](#fieldOfView). {: .note} @@ -663,7 +665,7 @@ Perspective Cameras _SHOULD_ have the following additional properties: [fieldOfV #### Lights {: #Light} -It is necessary for there to be a Light within a Scene that illuminates the objects. If no Light is provided by the Scene's description, then the client _MUST_ add a Light. +It is necessary for there to be a Light within a Scene that illuminates the objects. If no Light is provided by the Scene's description, then the client _MUST_ provide default lighting. This specification does not define other aspects of Lights, such as the rate of decay of the intensity of the light over a distance, the maximum range of the light, or the penumbra of a cone. Implementation of these aspects is client-dependent. @@ -763,7 +765,7 @@ Spot Lights _MAY_ have the following additional properties: [lookAt](#lookAt) #### Audio Emitters {: #AudioEmitters} -Positional audio is supported through the use of Audio Emitter resources annotated into Scenes, in the same way that light is emitted from the various subclasses of Light. +Audio is supported through the use of Audio Emitter resources annotated into Scenes, in the same way that light is emitted from the various subclasses of Light. As the audio content must come from an audio resource, the Audio Emitter classes are subclasses of SpecificResource. Note that the `source` of the Audio could be a Timeline, or could be further constrained with additional specifiers as to start point, end point or other transformations. @@ -850,7 +852,7 @@ Spot Audio Emitters _MAY_ have the following additional properties: [lookAt](#lo #### Transforms {: #Transforms} -An operation to transform a 3D resource. Transforms are specified by the [transform](#transform) property on a Specific Resource. Transforms are carried out on a resource in the implicit or explicit local coordinate space of the resource, and are performed prior to painting that resource into any subsequent coordinate space. +An operation to apply a transformation to a resource. Transforms are specified by the [transform](#transform) property on a Specific Resource. Transforms are carried out on a resource in the implicit or explicit local coordinate space of the resource, and are performed prior to painting that resource into any subsequent coordinate space. __Properties__
All Transforms _MUST_ have the following properties: [type](#type).

From 60f07e5c34694ad862ecf21f976c084f0495b24d Mon Sep 17 00:00:00 2001 From: tomcrane Date: Fri, 6 Jun 2025 13:41:52 +0100 Subject: [PATCH 120/130] latest changes --- source/presentation/4.0/index.md | 81 +++----------------------------- 1 file changed, 7 insertions(+), 74 deletions(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index 9db742358..06ed031c5 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -915,8 +915,6 @@ This example is a Manifest with a single Scene, with a single model of a space s This example adds a Light and a Camera to the previous example, and places the model at a specific point rather than at the default origin position. The Light is green and has a position, but has its default orientation of looking along the negative-y axis as no rotation has been specified. The Camera has a position and is pointing at the model's origin via the `lookAt` property. The Camera has a `fieldOfView` of 50. The `near` and `far` properties are included to ensure the model falls within the camera's range (although unnecessary in a simple Scene like this). The Scene has a background color. -> PNG of Scene - lurid green light half-illuminating the astronaut. - Use case 5a @@ -1046,14 +1044,6 @@ This example adds a Light and a Camera to the previous example, and places the m ## Use Case 6: Complex Scene - -model -light Ambient color -camera (put it in the right place looking -Z) near, far, fieldOfView, lookAt (note that Orthographic w/ viewHeight possible) -backgroundColor: #000 -point selector for positioning - - Chessboard is a Canvas with image more than one model transforms for scale and rotation @@ -1276,82 +1266,25 @@ Todo add example A Camera provides a view of a region of the Scene's space from a particular position within the Scene; the client constructs a viewport into the Scene and uses the view of one or more Cameras to render that region. The size and aspect ratio of the viewport is client and device dependent. -This specification defines two types of Camera: - -| Class | Description | -| ------------------- | ------------ | -| `PerspectiveCamera` | `PerspectiveCamera` mimics the way the human eye sees, in that objects further from the camera are smaller | -| `OrthographicCamera` | `OrthographicCamera` removes visual perspective, resulting in object size remaining constant regardless of its distance from the camera | - -Cameras are positioned within the Scene facing in a specified direction. Both position and direction are defined through the Annotation which adds the Camera to the Scene, described below in the sections on [Painting Annotations][], [Transforms][], and [Relative Rotation][]. - -If either the position or direction is not specified, then the position defaults to the origin, and facing direction defaults to pointing along the z axis towards negative infinity. - - -The region of the Scene's space that is observable by the camera is bounded by two planes orthogonal to the direction the camera is facing, given in the `near` and `far` properties, and a vertical projection angle that provides the top and bottom planes of the region. - -The `near` property defines the minimum distance from the camera at which something in the space must exist in order to be viewed by the camera. Anything nearer to the camera than this distance will not be viewed. Conversely, the `far` property defines a maximum distance from the camera at which something in the space must exist in order to be viewed by the camera. Anything further away will not be viewed. - -For PerspectiveCameras, the vertical projection angle is specificed using the full angular extent in degrees from the top plane to the bottom plane using the `fieldOfView` property. The `fieldOfView` angle MUST be greater than 0 and less than 180. For OrthographicCameras, the vertical projection is always parallel and thus not defined. - -If any of these properties are not specified explicitly, they default to the choice of the client implementation. - -drawing of a geometrical frustrum truncated by near and far distances - -The first Camera defined and not hidden in a Scene is the default Camera used to display Scene contents. If the Scene does not have any Cameras defined within it, then the client MUST provide a default Camera. The type, properties and position of this default camera are client-dependent. - -```json -{ - "id": "https://example.org/iiif/camera/1", - "type": "PerspectiveCamera", - "near": 1.0, - "far": 100.0, - "fieldOfView": 45.0 -} -``` - +There are two types of Camera, `PerspectiveCamera` and `OrthographicCamera`. The first Camera defined and not hidden in a Scene is the default Camera used to display Scene contents. If the Scene does not have any Cameras defined within it, then the client provides a default Camera. The type, properties and position of this default camera are client-dependent. ### Light -This specification defines four types of Light: - -| Class | Description | -| ----- | ------------ | -| `AmbientLight` | AmbientLight evenly illuminates all objects in the scene, and does not have a direction or position. | -| `DirectionalLight` | DirectionalLight emits in a specific direction as if it is infinitely far away and the rays produced from it are all parallel. It does not have a specific position. | -| `PointLight` | PointLight emits from a single point within the scene in all directions. | -| `SpotLight` | SpotLight emits a cone of light from a single point in a given direction. | - -Lights defined in this specification have a `color` and an `intensity`. The color is given as an RGB value, such as "#FFFFFF" for white. The intensity is the strength or brightness of the light, and described using a `Value` construct. - -SpotLight has an additional property of `angle`, specified in degrees, which is the angle from the direction that the Light is facing to the outside extent of the cone. - -diagram of cone geometry showing how the angle of the cone is defined +There are four types of Light: AmbientLight, DirectionalLight, PointLight and SpotLight. They have a `color` and an `intensity`. SpotLight has an additional property of `angle` that determines the spread of its light cone. -Lights that require a position and/or direction have these through the Annotation which associates them with the Scene, described below in the sections on [Painting Annotations][] and [Transforms][]. +If the Scene has no Lights, then the client provides its own lighting as it sees fit. - If a Light does not have an explicit direction, then the default is in the negative y direction (downwards). - If a Light does not have an explicit position in the coordinate space, then the default is at the origin. - -This specification does not define other aspects of Lights, such as the rate of decay of the intensity of the light over a distance, the maximum range of the light, or the penumbra of a cone. Implementation of these aspects is client-dependent. - -If there are no Lights present within the Scene, then the viewer MUST add at least one Light. The types and properties of Lights added in this way are client-dependent. - -```json -{ - "id": "https://example.org/iiif/light/1", - "type": "AmbientLight", - "color": "#FFFFFF", - "intensity": {"type": "Value", "value": 0.6, "unit": "relativeUnit"} -} -``` +### Audio Emitters +There are three types of Audio emitter: AmbientAudio, PointAudio and SpotAudio. They have a `source` (an audio Content Resource) and a `volume`. ### Transforms +A Transform is a property + The Annotation with a Selector on the target can paint a resource at a point other than the origin, however it will be at its initial scale and rotation, which may not be appropriate for the scene that is being constructed. This specification defines a new class of manipulations for SpecificResources called a `Transform`, with three specific sub-classes. Each Transform has three properties, `x`, `y` and `z` which determine how the Transform affects that axis in the local coordinate space. From 3840769f95b099df2614fe93801fb6bb462483f3 Mon Sep 17 00:00:00 2001 From: Rob Sanderson Date: Fri, 6 Jun 2025 15:13:06 +0100 Subject: [PATCH 121/130] exclude --- source/presentation/4.0/model.md | 41 ++++++++++++++++++++++---------- 1 file changed, 28 insertions(+), 13 deletions(-) diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index 893ae6729..c395e79e3 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -852,7 +852,7 @@ Spot Audio Emitters _MAY_ have the following additional properties: [lookAt](#lo #### Transforms {: #Transforms} -An operation to apply a transformation to a resource. Transforms are specified by the [transform](#transform) property on a Specific Resource. Transforms are carried out on a resource in the implicit or explicit local coordinate space of the resource, and are performed prior to painting that resource into any subsequent coordinate space. +An operation to apply a transformation to a resource. Transforms are specified by the [transform](#transform) property on a Specific Resource. In the context of Scenes, transforms are carried out on a resource in the implicit or explicit local coordinate space of the resource, and are performed prior to painting that resource into any subsequent coordinate space. __Properties__
All Transforms _MUST_ have the following properties: [type](#type).

@@ -959,12 +959,27 @@ An Agent _MAY_ have the following properties: [id](#id), [seeAlso](#seeAlso) and > `"type": "Service"` -A Service is a software application outside of the Manifest that a client might interact with to gain additional information or functionality for the resource that is associated with the Service. The IIIF Image API is an example of a Service, as are the Auth API services. Known types of Service are registered in the Service Registry. +A Service is an external software application that a client might interact with to gain additional information or functionality for the resource that is associated with the Service. The IIIF Image API is an example of a Service, as are the Auth API services. Known types of Service are registered in the Service Registry. + +For cross-version consistency, this specification defines the following values for the `type` or `@type` property for backwards compatibility with other IIIF APIs. Future versions of these APIs will define their own types. These `type` values are necessary extensions for compatibility of the older versions. + +| Value | Specification | +| -------------------- | ------------- | +| ImageService1 | [Image API version 1][image11] | +| ImageService2 | [Image API version 2][image21] | +| SearchService1 | [Search API version 1][search1] | +| AutoCompleteService1 | [Search API version 1][search1-autocomplete] | +| AuthCookieService1 | [Authentication API version 1][auth1-cookie-service] | +| AuthTokenService1 | [Authentication API version 1][auth1-token-service] | +| AuthLogoutService1 | [Authentication API version 1][auth1-logout-service] | +{: .api-table #table-service-types} + +Implementations _SHOULD_ be prepared to recognize the `@id` and `@type` property names used by older specifications, as well as `id` and `type`. Note that the `@context` key _SHOULD NOT_ be present within the `service`, but instead included at the beginning of the document. __Properties__
A Service _MUST_ have the following properties: [id](#id), and [type](#type).

A Service _SHOULD_ have the following properties: [label](#label), [profile](#profile).

-A Service _MAY_ have the following properties: [service](#service).

+A Service _MAY_ have the following properties: [service](#service), `@id` and `@type`.

Services will also have specific requirements as to additional properties based on the type of service. {: .note} @@ -1200,19 +1215,19 @@ The value _MUST_ be a positive floating point number. ### exclude {: #exclude} -_Summary here_ - -Just as a Scene may contain multiple Annotations with model, light, and camera resources, a single 3D model file may contain a collection of 3D resources, including model geometry, assemblages of lights, and/or multiple cameras, with some of these potentially manipulated by animations. When painting Scenes or models that themselves may contain groups of resources within a single Scene, it may not always be appropriate to include all possible cameras, lights, or other resources, and it may be desirable to opt not to import some of these resources. This is accomplished through the Annotation property `exclude`, which prevents the import of audio, lights, cameras, or animations from a particular Scene or model prior to the Annotation being painted into a Scene. When `exclude` is used, the excluded resource type should not be loaded into the Scene, and it is not possible to reactivate or turn on these excluded resources after loading. - - -_On Annotation, a list of strings drawn from table_ +Just as a Scene may contain multiple Annotations with model, light, and camera resources, a single 3D model file may contain a collection of 3D resources, including model geometry, assemblages of lights, and/or multiple cameras, with some of these potentially manipulated by animations. When painting Scenes or models that themselves may contain groups of resources within a single Scene, it may not always be appropriate to include all possible cameras, lights, or other resources, and it may be desirable to opt not to import some of these resources. This is accomplished through the Annotation property `exclude`, which prevents the import of audio, lights, cameras, or animations from a particular Scene or model prior to the Annotation being painted into a Scene. When `exclude` is used, the excluded resource type or functionality should not be loaded into the Scene, and it is not possible to reactivate or turn on these excluded resources after loading. | Value | Description | |------------|-------------| -| Audio | | -| Animations | | -| Cameras | | -| Lights | | +| Audio | Exclude all sound from resources, including audio tracks, audio emitters, and audio from video | +| Animations | Exclude all definitions of animations from resources | +| Cameras | Exclude all cameras from resources | +| Lights | Exclude all lights from resources | + +The value of `exclude` is an array of strings, each of which is one of the values listed above. If the `exclude` property is not specified, then no resources are excluded. + +* An Annotation _MAY_ have the `exclude` property. + Clients _SHOULD_ process the `exclude` property. ```json "exclude": [ "Audio", "Lights", "Cameras", "Animations" ] From 2dd441e0e7fb602275b46cd462da120734419350 Mon Sep 17 00:00:00 2001 From: tomcrane Date: Fri, 6 Jun 2025 15:13:29 +0100 Subject: [PATCH 122/130] Nesting section --- source/presentation/4.0/index.md | 154 ++++++++--------------------- source/presentation/4.0/scratch.md | 6 +- 2 files changed, 48 insertions(+), 112 deletions(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index 06ed031c5..308f75b68 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -227,6 +227,8 @@ Scenes may also have the `duration` property in the same manner as Timelines. } ``` +Scenes can have time-based and image content in them as well as 3D content. See model for how to do this. + [👀 Model Documentation](model/#containers) @@ -256,7 +258,7 @@ In addition to the required properties `id` and `type`, other commonly used prop ### Containers as Content Resources -Containers may also be treated as Content Resources and painted into other Containers. This allows composition of content, such as painting a Canvas bearing a Video into a Scene, or painting a 3D model along with its associated Lights into an encompassing Scene. +Containers may also be treated as Content Resources and painted into other Containers. This allows composition of content, such as painting a Canvas bearing a Video into a Scene, or painting a 3D model along with its associated Lights into an encompassing Scene. This capability is described further in [nesting](#nesting). ### Referencing Parts of Resources @@ -324,6 +326,45 @@ The fragment example above can be expressed using a Specific Resource: ``` +## Supporting Resources + +Constructs from the domain of 3D graphics are expressed in IIIF as Resources. They are associated with Scenes via Painting Annotations in the same manner as Content Resources. They aid in or enhance the rendering of Content Resources, especially in Scenes. + +### Cameras + +A Camera provides a view of a region of the Scene's space from a particular position within the Scene; the client constructs a viewport into the Scene and uses the view of one or more Cameras to render that region. The size and aspect ratio of the viewport is client and device dependent. + +There are two types of Camera, `PerspectiveCamera` and `OrthographicCamera`. The first Camera defined and not hidden in a Scene is the default Camera used to display Scene contents. If the Scene does not have any Cameras defined within it, then the client provides a default Camera. The type, properties and position of this default camera are client-dependent. + + +### Lights + +There are four types of Light: AmbientLight, DirectionalLight, PointLight and SpotLight. They have a `color` and an `intensity`. SpotLight has an additional property of `angle` that determines the spread of its light cone. + +If the Scene has no Lights, then the client provides its own lighting as it sees fit. + + +### Audio Emitters + +There are three types of Audio emitter: AmbientAudio, PointAudio and SpotAudio. They have a `source` (an audio Content Resource) and a `volume`. + +### Transforms + +When painting resources into Scenes, it is often necessary to resize, rotate or move them relative to the coordinate space of the Scene. These operations are specified using three Transforms: ScaleTransform, RotateTransform and TranslateTransform. Each Transform has three properties, `x`, `y` and `z` which determine how the Transform affects that axis in the local coordinate space. + +Transforms are added to a SpecificResource using the `transform` property, and there may be more than one applied when adding a model to a Scene. Different orders of the same set of transforms can have different results, so attention must be paid when creating the array and when processing it. + +### Agent + +Any resource can have a `provider` property which a client can display to the user. This typically tells the user who the publisher is and how they might be contacted. The value of this property is an [Agent](model/#agent). + +### Service + +A Service is a software application that a client might interact with to gain additional information or functionality. The IIIF Image API is an example of a Service. + +### Unit Value + +To express a numerical measure in some particular unit, we use a UnitValue resource that has `value` and `unit` properties. For example a Scene coordinate system might be in meters. # Image Content @@ -1260,117 +1301,8 @@ Todo add example -## Scene-Specific Resources - -### Camera - -A Camera provides a view of a region of the Scene's space from a particular position within the Scene; the client constructs a viewport into the Scene and uses the view of one or more Cameras to render that region. The size and aspect ratio of the viewport is client and device dependent. - -There are two types of Camera, `PerspectiveCamera` and `OrthographicCamera`. The first Camera defined and not hidden in a Scene is the default Camera used to display Scene contents. If the Scene does not have any Cameras defined within it, then the client provides a default Camera. The type, properties and position of this default camera are client-dependent. - - -### Light - -There are four types of Light: AmbientLight, DirectionalLight, PointLight and SpotLight. They have a `color` and an `intensity`. SpotLight has an additional property of `angle` that determines the spread of its light cone. - -If the Scene has no Lights, then the client provides its own lighting as it sees fit. - - -### Audio Emitters - -There are three types of Audio emitter: AmbientAudio, PointAudio and SpotAudio. They have a `source` (an audio Content Resource) and a `volume`. - - -### Transforms - -A Transform is a property - -The Annotation with a Selector on the target can paint a resource at a point other than the origin, however it will be at its initial scale and rotation, which may not be appropriate for the scene that is being constructed. - -This specification defines a new class of manipulations for SpecificResources called a `Transform`, with three specific sub-classes. Each Transform has three properties, `x`, `y` and `z` which determine how the Transform affects that axis in the local coordinate space. - - -| Class | Description | -| --------------- | ------------ | -| ScaleTransform | A ScaleTransform applies a multiplier to one or more axes in the local coordinate space. A point that was at 3.5, after applying a ScaleTransform of 2.0 would then be at 7.0. If an axis value is not specified, then it is not changed, resulting in a default of 1.0 | -| RotateTransform | A RotateTransform rotates the local coordinate space around the given axis in a counter-clockwise direction around the axis itself (e.g. around a pivot point of 0 on the axis). A point that was at x=1,y=1 and was rotated 90 degrees around the x axis would be at x=1,y=0,z=1. If an axis value is not specified, then it is not changed, resulting in a default of 0.0 | -| TranslateTransform | A TranslateTransform moves all of the objects in the local coordinate space the given distance along the axis. A point that was at x=1.0, after applying a TranslateTransform of x=1.0 would be at x=2.0. If an axis value is not specified then it is not changed, resulting in a default of 0.0 | - -Transforms are added to a SpecificResource using the `transform` property. The value of the property is an array, which determines the order in which the transforms are to be applied. The resulting state of the first transform is the input state for the second transform, and so on. Different orders of the same set of transforms can have different results, so attention must be paid when creating the array and when processing it. - -The point around which RotateTransform rotates the space is the origin. This "pivot point" cannot be changed directly, but instead a TranslateTransform can be used to move the desired pivot point to the be at the origin, then the RotateTransform applied. - -Transforms are only used in the Presentation API when the SpecificResource is the `body` of the Annotation, and are applied before the resource is painted into the scene at the point given in the `target`. - -```json -{ - "type": "SpecificResource", - "source": { - "id": "https://example.org/iiif/assets/model1.glb", - "type": "Model" - }, - "transform": [ - { - "type": "RotateTransform", - "x": 0.0, - "y": 180.0, - "z": 0.0 - }, - { - "type": "TranslateTransform", - "x": 1.0, - "y": 0.0, - "z": 0.0 - } - ] -} -``` - - -### Relative Rotation - -It is useful to be able to rotate a light or camera resource such that it is facing another object or point in the Scene, rather than calculating the angles within the Scene's coordinate space. This is accomplished with a property called `lookAt`, valid on DirectionalLight, SpotLight, and all Cameras. The value of the property is either a PointSelector, a WktSelector, the URI of an Annotation which paints something into the current Scene, or a Specific Resource with a selector identifying a point or region in an arbitrary container. - -If the value is a PointSelector, then the light or camera resource is rotated around the x and y axes such that it is facing the given point. If the value is a WktSelector, then the resource should be rotated to face the given region. If the value is an Annotation which targets a point via a PointSelector, URI fragment or other mechanism, then the resource should be rotated to face that point. If the value is a Specific Resource, the source container for the Specific Resource must be painted into the current Scene, and the Specific Resource selector should identify a point or region in the source container. In this case, the light or camera resource should be rotated to face the point or region in the source container where the point or region is located within the current Scene's coordinate space. This allows light or camera resources to face a specific 2D point on a Canvas painted into a 3D scene. - -This rotation happens after the resource has been added to the Scene, and thus after any transforms have taken place in the local coordinate space. - -```json -"lookAt": { - "type": "PointSelector", - "x": 3, - "y": 0, - "z": -10 -} -``` - - -### Excluding - -Just as a Scene may contain multiple Annotations with model, light, and camera resources, a single 3D model file may contain a collection of 3D resources, including model geometry, assemblages of lights, and/or multiple cameras, with some of these potentially manipulated by animations. When painting Scenes or models that themselves may contain groups of resources within a single Scene, it may not always be appropriate to include all possible cameras, lights, or other resources, and it may be desirable to opt not to import some of these resources. This is accomplished through the Annotation property `exclude`, which prevents the import of audio, lights, cameras, or animations from a particular Scene or model prior to the Annotation being painted into a Scene. When `exclude` is used, the excluded resource type should not be loaded into the Scene, and it is not possible to reactivate or turn on these excluded resources after loading. - -Painting a Scene into another while excluding import of several types of resources: -```json -{ - "id": "https://example.org/iiif/3d/anno1", - "type": "Annotation", - "motivation": ["painting"], - "exclude": ["Audio", "Lights", "Cameras", "Animations"], - "body": { - "id": "https://example.org/iiif/scene1", - "type": "Scene" - }, - "target": "https://example.org/iiif/scene2" -} -``` - - - - - - -### Nesting +# Nesting (more about Containers as Content Resources) A Canvas can be painted into a Scene as an Annotation, but the 2D nature of Canvases requires special consideration due to important differences between Canvases and Scenes. A Canvas describes a bounded 2D space with finite `height` and `width` measured in pixels with a pixel origin at the top-left corner of the Canvas, while Scenes describe a boundless 3D space with x, y, and z axes of arbitrary coordinate units and a coordinate origin at the center of the space. It is important to note that in many cases the pixel scale used by a Canvas or a 2D image content resource will not be in proportion to the desired 3D coordinate unit scale in a Scene. diff --git a/source/presentation/4.0/scratch.md b/source/presentation/4.0/scratch.md index 273543e6d..8afb569b1 100644 --- a/source/presentation/4.0/scratch.md +++ b/source/presentation/4.0/scratch.md @@ -6,4 +6,8 @@ The second Container is a Canvas, representing a 2D surface. In this case the Ca The third Container is a Scene. Unlike a Canvas, it is not a bounded spatial extent, but may be a bounded temporal extent if it has the optional duration property. It still establishes a coordinate space (x, y, z) but doesn't need any spatial properties to do so as it is always the same, infinite unbounded space. The Annotation paints the astronaut model into the Scene. As no further qualification is given, the astronaut model is placed at the (0,0,0) origin of the Scene. Later examples will show how to control the lighting and camera position(s) and properties, but this is not required; a IIIF viewer is expected to supply ambient light and a default camera position in the absence of specific values. -This requires careful consideration of the URI schemes for `id` properties of Containers and their Manifests to ensure they remain referenceable in the future. \ No newline at end of file +This requires careful consideration of the URI schemes for `id` properties of Containers and their Manifests to ensure they remain referenceable in the future. + + +use this in an example: +The point around which RotateTransform rotates the space is the origin. This "pivot point" cannot be changed directly, but instead a TranslateTransform can be used to move the desired pivot point to the be at the origin, then the RotateTransform applied. From cfb691f0f38b95cbdc52ea0cf7a82ccf187774bc Mon Sep 17 00:00:00 2001 From: Dawn Childress Date: Fri, 6 Jun 2025 07:14:47 -0700 Subject: [PATCH 123/130] periodical example --- source/presentation/4.0/index.md | 168 +++++++++++++++++++++++++++---- 1 file changed, 150 insertions(+), 18 deletions(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index 06ed031c5..858c26f75 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -443,7 +443,7 @@ The example demonstrates the use of the common descriptive properties `label` fo !!! warning TODO: The above should be a green class rgb(244,252,239) to distinguish from properties __Definitions__
-Classes: [Manifest](#model/Manifest), [Canvas](#model/Canvas), [AnnotationPage](#model/AnnotationPage), [Annotation](#model/Annotation)

+Classes: [Manifest](#model/Manifest), [Canvas](#model/Canvas), [AnnotationPage](#model/AnnotationPage), [Annotation](#model/Annotation), [Agent](#model/Agent)

Properties: [id](#model/id), [type](#type), [label](#label), [metadata](#metadata), [summary](#summary), [rights](#rights), [homepage](#homepage), [thumbnail](#thumbnail), and [provider](#provider) {: .note} @@ -1414,7 +1414,7 @@ When a Scene is nested into another Scene, the `backgroundColor` of the Scene to ## Choice of Alternative Resources -Example: Multi-spectral Images with Comments +## Use Case : Multi-spectral Images with Comments ## Embedded Content @@ -1483,38 +1483,170 @@ IIIF Ranges are used to represent structure _WITHIN_ a Manifest beyond the defau :eyes: -## Example: Periodical +## Use Case : Periodical -This example demonstrates the use of IIIF Collections to group Manifests into a hierarchy. In this case, there is a Collection for a publishing run of the _The Tombstone Epitaph_ from 1880 to 1920. This contains 41 child Collections each representing a year's worth of issues. Each of these year Collections in turn has one Manifest for each daily issue of the newspaper. +This example demonstrates the use of IIIF Collections to group Manifests into a hierarchy. In this case, there is a Collection using the `behavior` "multi-part" for a publishing run of the _The Tombstone Epitaph_ from 1880 to 1920. This contains 41 child Collections, also using the "multi-part" behavior, each representing a year's worth of issues. Each of these year Collections in turn has one Manifest for each daily issue of the newspaper. Within each Manifest, the `structures` property provides Ranges which are used to identify individual sections of the Newspaper, and individual stories within the sections which may be spread across multiple columns and pages. -Each Manifest has a `navDate` property that could be used to plot the issues on a calendar-style user interface. The top level Collection has a `navPlace` property that could be used on a "Newspapers of America" map to allow users to view newspapers by location. Each story's Range links to an Annotation Collection that provides the text of the story via the `supplementary` property. +Each Manifest has a `navDate` property that could be used to plot the issues on a calendar-style user interface. + ``` demonstrates navDate, navPlace, structures (Ranges), supplementary, Collections ... ``` +IIIF Collection with `behavior:multi-part` that contains the individual `multi-part` Collections for each year/volume +```json +{ + "@context": "http://iiif.io/api/presentation/4/context.json", + "id": "https://example.org/iiif/periodical/collection.json", + "type": "Collection", + "label": { "en": [ "The Tombstone Epitaph (1880-1920)" ] }, + "behavior": [ "multi-part" ], + "navPlace": { + "id": "https://example.org/iiif/periodical/collection/place/1", + "type": "FeatureCollection", + "features": [ + { + "id": "https://example.org/iiif/periodical/collection/feature/1", + "type": "Feature", + "properties": { + "label": { "en": ["Tombstone, Cochise County, Arizona"] } + }, + "geometry": { + "type": "Point", + "coordinates": [31.715940, −110.064827] + } + } + ] + }, + "items": [ + { + "id": "https://example.org/iiif/periodical/multi-part-collection/v1.json", + "type": "Collection", + "label": { "en": [ "The Tombstone Epitaph, 1880" ] } + }, + { + "id": "https://example.org/iiif/periodical/multi-part-collection/v2.json", + "type": "Collection", + "label": { "en": [ "The Tombstone Epitaph, 1881" ] } + }, + // Additional multi-part collections for each year/volume + ] +} +``` +IIIF Collection with `behavior:multi-part` for the second volume (1881), with individual Manifests for each issue. + +```json +{ + "@context": "http://iiif.io/api/presentation/4/context.json", + "id": "https://example.org/iiif/periodical/multi-part-collection/v1.json", + "type": "Collection", + "label": { "en": [ "The Tombstone Epitaph, 1881" ] }, + "behavior": [ "multi-part" ], + "items": [ + // Previous issues + { + "id": "https://example.org/iiif/periodical/multi-part-collection/issue1.json", + "type": "Manifest", + "label": { "en": [ "October 27, 1881" ] } + }, + // Subsequent issues + ] +} +``` +Manifest for the October 27, 1881 issue, with Ranges for table of contents. ```json -"navPlace": { - "id": "https://iiif.io/api/cookbook/recipe/0318-navPlace-navDate/feature-collection/1", - "type": "FeatureCollection", - "features": [ +{ + "@context": "http://iiif.io/api/presentation/4/context.json", + "id": "https://example.org/iiif/periodical/multi-part-collection/issue1.json", + "type": "Manifest", + "label": { "en": [ "The Tombstone Epitaph, October 27, 1881" ] }, + "behavior": [ "paged" ], + "items": [ { - "id": "https://iiif.io/api/cookbook/recipe/0318-navPlace-navDate/feature/1", - "type": "Feature", - "properties": { - "label": { "en": ["Castel Sant'Angelo, Rome"] } - }, - "geometry": { - "type": "Point", - "coordinates": [12.4663, 41.9031] - } + "id": "https://example.org/iiif/periodical/multi-part-collection/canvas/c1", + "type": "Canvas", + "label": { "en": [ "Page 1" ] }, + "height": 4613, + "width": 3204, + "items": [ + { + "id": "https://example.org/iiif/periodical/multi-part-collection/page/p1", + "type": "AnnotationPage", + "items": [ + { + "id": "https://example.org/iiif/periodical/multi-part-collection/annotation/a1", + "type": "Annotation", + "motivation": [ "painting" ], + "body": { + "id": "https://example.org/image/page1.jpg", + "type": "Image", + "format": "image/jpeg", + "height": 4613, + "width": 3204, + }, + "target": "https://example.org/iiif/periodical/multi-part-collection/canvas/c1" + } + ] + } + ] + }, + { + "id": "https://example.org/iiif/periodical/multi-part-collection/canvas/c2", + "type": "Canvas", + "label": { "en": [ "Page 2" ] }, + "height": 4613, + "width": 3204, + "items": [ + { + "id": "https://example.org/iiif/periodical/multi-part-collection/page/p2", + "type": "AnnotationPage", + "items": [ + { + "id": "https://example.org/iiif/periodical/multi-part-collection/annotation/a2", + "type": "Annotation", + "motivation": [ "painting" ], + "body": { + "id": "https://example.org/image/page2.jpg", + "type": "Image", + "format": "image/jpeg", + "height": 4613, + "width": 3204, + }, + "target": "https://example.org/iiif/periodical/multi-part-collection/canvas/c2" + } + ] + } + ] + }, + // Additional Canvases + ], + "structures": [ + { + "id": "https://example.org/iiif/periodical/multi-part-collection/range/r0", + "type": "Range", + "label": { "en": [ "October 27, 1881" ] }, + "items": [ + { + "id": "https://iiif.io/api/cookbook/recipe/0031-bound-multivolume/range/r1", + "type": "Range", + "label": { "en": [ "Yesterday's Tragedy: Three Men Hurled Into Eternity In the Duration of a Moment" ] }, + "items": [ + { + "id": "https://example.org/iiif/periodical/multi-part-collection/canvas/c1", + "type": "Canvas" + }, + // Additional contents + ] + } + ] } ] } From 0078469a242f6bf45fbde7d500606c719744d773 Mon Sep 17 00:00:00 2001 From: Dawn Childress Date: Fri, 6 Jun 2025 07:24:15 -0700 Subject: [PATCH 124/130] add navDate to periodical use case --- source/presentation/4.0/index.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index 5e2a54113..176961415 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -1433,7 +1433,7 @@ Each Manifest has a `navDate` property that could be used to plot the issues on demonstrates navDate, navPlace, structures (Ranges), supplementary, Collections ... ``` -IIIF Collection with `behavior:multi-part` that contains the individual `multi-part` Collections for each year/volume +IIIF Collection with `behavior` "multi-part" that contains the individual "multi-part" Collections for each year/volume. ```json { @@ -1474,7 +1474,7 @@ IIIF Collection with `behavior:multi-part` that contains the individual `multi-p ] } ``` -IIIF Collection with `behavior:multi-part` for the second volume (1881), with individual Manifests for each issue. +IIIF Collection with `behavior` "multi-part" for the second volume (1881), with individual Manifests for each issue. ```json { @@ -1504,6 +1504,7 @@ Manifest for the October 27, 1881 issue, with Ranges for table of contents. "type": "Manifest", "label": { "en": [ "The Tombstone Epitaph, October 27, 1881" ] }, "behavior": [ "paged" ], + "navDate": "1881-10-27T00:00:00+00:00", "items": [ { "id": "https://example.org/iiif/periodical/multi-part-collection/canvas/c1", @@ -1570,7 +1571,7 @@ Manifest for the October 27, 1881 issue, with Ranges for table of contents. "label": { "en": [ "October 27, 1881" ] }, "items": [ { - "id": "https://iiif.io/api/cookbook/recipe/0031-bound-multivolume/range/r1", + "id": "https://example.org/iiif/periodical/multi-part-collection/range/r1", "type": "Range", "label": { "en": [ "Yesterday's Tragedy: Three Men Hurled Into Eternity In the Duration of a Moment" ] }, "items": [ From a7d7776d3b85cae57f08214663271db10315f2f7 Mon Sep 17 00:00:00 2001 From: Dawn Childress Date: Fri, 6 Jun 2025 07:33:42 -0700 Subject: [PATCH 125/130] add classes and properties to periodical use case --- source/presentation/4.0/index.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index 176961415..092165b2c 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -1428,12 +1428,7 @@ The top level Collection has a `navPlace` property that could be used on a "News Each Manifest has a `navDate` property that could be used to plot the issues on a calendar-style user interface. - -``` -demonstrates navDate, navPlace, structures (Ranges), supplementary, Collections -... -``` -IIIF Collection with `behavior` "multi-part" that contains the individual "multi-part" Collections for each year/volume. +IIIF Collection with `behavior` "multi-part" that contains the individual "multi-part" Collections for each year/volume: ```json { @@ -1587,7 +1582,10 @@ Manifest for the October 27, 1881 issue, with Ranges for table of contents. ] } ``` - +__Definitions__
+Classes: [Collection](#model/Collection), [Range](#model/Range), [AnnotationCollection](#model/AnnotationCollection)

+Properties: [behavior](#model/behavior), [navPlace](#model/navPlace), [navDate](#model/navDate), [structure](#model/structures) +{: .note} thumbnail-nav sequence From 80ddb8475d39cabe7d0f7820eeb380670164540d Mon Sep 17 00:00:00 2001 From: tomcrane Date: Fri, 6 Jun 2025 16:28:20 +0100 Subject: [PATCH 126/130] very WIP toggles --- source/presentation/4.0/index.md | 168 ++++++++++++++++++++++++++++- source/presentation/4.0/scratch.md | 24 +++++ 2 files changed, 191 insertions(+), 1 deletion(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index 095b2bea6..5f53b1289 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -1977,12 +1977,50 @@ The activating annotation is provided in a Container's `annotations` property. I } ``` + + +```json +{ + "items": [ + { + "id": "https://example.org/iiif/3d/anno2", + "type": "Annotation", + "motivation": ["activating"], + "body": [ + { + "type": "TextualBody", + "value": "A label for the activation may be provided as a TextualBody" + } + ], + "target": { + "source": { + "id": "https://example.org/iiif/3d/painting-anno-for-mandible", + "type": "Annotation" + }, + "scope": { + "type": "Annotation", + "motivation": ["contentState"], + "target": { + // A body where the type is a IIIF Resource (eg Scene) is the Content State to apply + "id": "https://example.org/iiif/scene1/scene-with-activation", + "type": "Scene", + "backgroundColor": "#FF99AA" + } + } + } + } + ] +} +``` + // Can you put activating annotations in `manifest.annotations`? They would work there too, you have all the information. ### Triggering a named animation in a model +> toggles: anno supplies the label. This anno's `toggles` property lists id of an activating anno that activates the animation. + 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. This pattern is similar to the above, except that: @@ -2028,7 +2066,133 @@ This pattern is similar to the above, except that: "type": "AnnotationPage", "items": [ { - "id": "https://example.org/iiif/3d/anno2", + "id": "https://example.org/iiif/3d/box-opening-activating-anno", + "type": "Annotation", + "motivation": ["activating"], + "body": [ + { + "type": "TextualBody", + "value": "Click the box to open the lid" + } + ], + "target": [ + { + "type": "SpecificResource", + "source": "https://example.org/iiif/3d/painting-anno-for-music-box", + "selector": [ + { + "type": "AnimationSelector", + "value": "open-the-lid" + } + ] + } + ] + } + ] + } + ] + } + ] + } + ] +} +``` + +> Toggles example + +```json +{ + "id": "https://example.org/iiif/3d/activating-animation.json", + "type": "Manifest", + "label": { "en": ["Music Box with lid that opens as an internal animation"] }, + "items": [ + { + "id": "https://example.org/iiif/scene1/scene-with-activation-animation", + "type": "Scene", + "label": { "en": ["A Scene Containing a Music Box"] }, + "items": [ + { + "id": "https://example.org/iiif/scene-with-activation-animation/page/p1/1", + "type": "AnnotationPage", + "items": [ + { + "id": "https://example.org/iiif/3d/painting-anno-for-music-box", + "type": "Annotation", + "motivation": ["painting"], + "body": { + "id": "https://raw.githubusercontent.com/IIIF/3d/main/assets/music-box.glb", + "type": "Model" + }, + "target": { + // SpecificResource with PointSelector + }, + "toggles": [ + // Clicking the box opens the lid + "https://example.org/iiif/3d/activating-anno-for-music-box" + ] + } + ], + "annotations": [ + { + "id": "https://example.org/iiif/scene1/page/activators", + "type": "AnnotationPage", + "items": [ + { + "id": "https://example.org/iiif/3d/activation-labelling-anno", + "type": "Annotation", + "motivation": ["commenting-maybe"], + "body": [ + { + "type": "TextualBody", + "value": "Click me to open the lid of the box" + } + ], + "toggles": [ + // clicking the 'Click me' opens the lid + "https://example.org/iiif/3d/activating-anno-for-music-box" + ], + "target": [ + "https://example.org/iiif/3d/painting-anno-for-music-box" + ] + }, + { + "id": "https://example.org/iiif/3d/activating-anno-for-music-box", + "type": "Annotation", + "motivation": ["activating"], + "body": [ + { + "type": "TextualBody", + "value": "Click me to open the lid of the box" + } + ], + "target": { + "type": "SpecificResource", + "source": "https://example.org/iiif/3d/painting-anno-for-music-box", + "selector": [ + { + "type": "AnimationSelector", + "value": "open-the-lid" + } + ], + "refinedBy": [ + // fragment time selector + ] + } + } + ] + } + ] + } + + + + + { + "id": "https://example.org/iiif/scene1/page/activators", + "type": "AnnotationPage", + "items": [ + { + "id": "https://example.org/iiif/3d/box-opening-activating-anno", "type": "Annotation", "motivation": ["activating"], "body": [ @@ -2058,6 +2222,8 @@ This pattern is similar to the above, except that: } ] } + + ``` // TODO diff --git a/source/presentation/4.0/scratch.md b/source/presentation/4.0/scratch.md index 8afb569b1..4091dccf7 100644 --- a/source/presentation/4.0/scratch.md +++ b/source/presentation/4.0/scratch.md @@ -11,3 +11,27 @@ This requires careful consideration of the URI schemes for `id` properties of Co use this in an example: The point around which RotateTransform rotates the space is the origin. This "pivot point" cannot be changed directly, but instead a TranslateTransform can be used to move the desired pivot point to the be at the origin, then the RotateTransform applied. + + + + + "body": [ + { + "type": "TextualBody", + "value": "A label for the activation may be provided as a TextualBody" + }, + { + "type": "SpecificResource", + "source": { + "id": "https://example.org/iiif/scene1/scene-with-activation", + "type": "Scene" + }, + "transform": [ + { + "type": "PropertyTransform", + "propertyName": "backgroundColor", + "propertyValue": "#FF99AA" + } + ] + } + ], \ No newline at end of file From c3ced33c67736aa5a8a1c49c5fb79d2d91550040 Mon Sep 17 00:00:00 2001 From: Dawn Childress Date: Fri, 6 Jun 2025 08:28:36 -0700 Subject: [PATCH 127/130] add supplementary to periodical use case --- source/presentation/4.0/index.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index 092165b2c..8e4307011 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -1420,13 +1420,9 @@ IIIF Ranges are used to represent structure _WITHIN_ a Manifest beyond the defau ## Use Case : Periodical -This example demonstrates the use of IIIF Collections to group Manifests into a hierarchy. In this case, there is a Collection using the `behavior` "multi-part" for a publishing run of the _The Tombstone Epitaph_ from 1880 to 1920. This contains 41 child Collections, also using the "multi-part" behavior, each representing a year's worth of issues. Each of these year Collections in turn has one Manifest for each daily issue of the newspaper. +This example demonstrates the use of IIIF Collections to group Manifests into a hierarchy. In this case, there is a Collection for a publishing run of the _The Tombstone Epitaph_ from 1880 to 1920. This contains 41 child Collections each representing a year's worth of issues. The parent Collection and each of its child Collections use the `behavior` "multi-part" to signal that the Collections and their Manifests are part of a logical whole or contguous set. Each of the year Collections has one Manifest for each issue of the newspaper. -Within each Manifest, the `structures` property provides Ranges which are used to identify individual sections of the Newspaper, and individual stories within the sections which may be spread across multiple columns and pages. - -The top level Collection has a `navPlace` property that could be used on a "Newspapers of America" map to allow users to view newspapers by location. Each story's Range links to an Annotation Collection that provides the text of the story via the `supplementary` property. - -Each Manifest has a `navDate` property that could be used to plot the issues on a calendar-style user interface. +The top level Collection has a `navPlace` property that could be used on a "Newspapers of America" map to allow users to view newspapers by location. Each Manifest has a `navDate` property that could be used to plot the issues on a calendar-style user interface. Within each Manifest, the `structures` property provides Ranges which are used to identify individual sections of the Newspaper, and individual stories within the sections, which may be spread across multiple columns and pages. Each story's Range includes the `supplementary` property to link to an Annotation Collection that provides the text of the story. IIIF Collection with `behavior` "multi-part" that contains the individual "multi-part" Collections for each year/volume: @@ -1569,6 +1565,7 @@ Manifest for the October 27, 1881 issue, with Ranges for table of contents. "id": "https://example.org/iiif/periodical/multi-part-collection/range/r1", "type": "Range", "label": { "en": [ "Yesterday's Tragedy: Three Men Hurled Into Eternity In the Duration of a Moment" ] }, + "supplementary": { "id": "https://example.org/iiif/full-text-anno-collection", "type": "AnnotationCollection" }, "items": [ { "id": "https://example.org/iiif/periodical/multi-part-collection/canvas/c1", @@ -1582,6 +1579,12 @@ Manifest for the October 27, 1881 issue, with Ranges for table of contents. ] } ``` + +> +**Key Points** +* +{: .note} + __Definitions__
Classes: [Collection](#model/Collection), [Range](#model/Range), [AnnotationCollection](#model/AnnotationCollection)

Properties: [behavior](#model/behavior), [navPlace](#model/navPlace), [navDate](#model/navDate), [structure](#model/structures) From f317be4927c30b86f42cb078d5e6232f0f252dfb Mon Sep 17 00:00:00 2001 From: Dawn Childress Date: Fri, 6 Jun 2025 08:29:27 -0700 Subject: [PATCH 128/130] add supplementary to periodical use case --- source/presentation/4.0/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index 8e4307011..b5207e4db 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -1587,7 +1587,7 @@ Manifest for the October 27, 1881 issue, with Ranges for table of contents. __Definitions__
Classes: [Collection](#model/Collection), [Range](#model/Range), [AnnotationCollection](#model/AnnotationCollection)

-Properties: [behavior](#model/behavior), [navPlace](#model/navPlace), [navDate](#model/navDate), [structure](#model/structures) +Properties: [behavior](#model/behavior), [navPlace](#model/navPlace), [navDate](#model/navDate), [structure](#model/structures), [supplementary](#model/supplementary) {: .note} thumbnail-nav From 9e260e409247ef252892f66494ad21536e5df8ff Mon Sep 17 00:00:00 2001 From: Dawn Childress Date: Fri, 6 Jun 2025 08:33:24 -0700 Subject: [PATCH 129/130] fix periodical section typo --- source/presentation/4.0/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index 8462ac1bd..65bd92298 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -1420,7 +1420,7 @@ IIIF Ranges are used to represent structure _WITHIN_ a Manifest beyond the defau ## Use Case : Periodical -This example demonstrates the use of IIIF Collections to group Manifests into a hierarchy. In this case, there is a Collection for a publishing run of the _The Tombstone Epitaph_ from 1880 to 1920. This contains 41 child Collections each representing a year's worth of issues. The parent Collection and each of its child Collections use the `behavior` "multi-part" to signal that the Collections and their Manifests are part of a logical whole or contguous set. Each of the year Collections has one Manifest for each issue of the newspaper. +This example demonstrates the use of IIIF Collections to group Manifests into a hierarchy. In this case, there is a Collection for a publishing run of the _The Tombstone Epitaph_ from 1880 to 1920. This contains 41 child Collections each representing a year's worth of issues. The parent Collection and each of its child Collections use the `behavior` "multi-part" to signal that the Collections and their Manifests are part of a logical whole or contiguous set. Each of the year Collections has one Manifest for each issue of the newspaper. The top level Collection has a `navPlace` property that could be used on a "Newspapers of America" map to allow users to view newspapers by location. Each Manifest has a `navDate` property that could be used to plot the issues on a calendar-style user interface. Within each Manifest, the `structures` property provides Ranges which are used to identify individual sections of the Newspaper, and individual stories within the sections, which may be spread across multiple columns and pages. Each story's Range includes the `supplementary` property to link to an Annotation Collection that provides the text of the story. From 8c904407c2d9fdbab0018fd9c47b492e2d2cfc85 Mon Sep 17 00:00:00 2001 From: tomcrane Date: Fri, 6 Jun 2025 16:53:04 +0100 Subject: [PATCH 130/130] interactionMode on Camera (maybe) --- source/presentation/4.0/model.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index c395e79e3..79858e833 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -1427,6 +1427,10 @@ For interaction modes that involve a Camera orbiting around a target point, the The value _MUST_ be an array of strings. +> TODO: Undecided whether this is Camera and/or Container + +* A Camera _MAY_ have the `interactionMode` property.
+ Clients _SHOULD_ process `interactionMode` on a Camera. * A Container _MAY_ have the `interactionMode` property.
Clients _SHOULD_ process `interactionMode` on a Container. * Other types of resource _MUST NOT_ have the `interactionMode` property.