From 8ad34bd7ec25fd9d7a561ad300534c141ce4afe4 Mon Sep 17 00:00:00 2001 From: tomcrane Date: Thu, 24 Oct 2024 11:32:06 +0100 Subject: [PATCH 01/21] 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 02/21] 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 03/21] 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 04/21] 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 05/21] 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 06/21] 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 07/21] 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 08/21] 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 09/21] 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 10/21] 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 11/21] 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 12/21] 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 13/21] 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 14/21] 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 15/21] 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 16/21] 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 17/21] 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 18/21] 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 19/21] 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 20/21] 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 21/21] 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