From 76b78f051ce1f0cc44b50cb6a23f9aed5f40e82a Mon Sep 17 00:00:00 2001 From: tomcrane Date: Fri, 9 May 2025 16:19:01 +0100 Subject: [PATCH 1/7] temporal and spatial scale in Prez4 model --- source/presentation/4.0/model.md | 50 ++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index 7c953dc18..0279e8efc 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -1849,6 +1849,29 @@ The value _MUST_ be an array of JSON objects. Each object _MUST_ be a service re {: #source} +### spatialScale +{: #spatialScale} + +A single UnitValue that defines a real-world scale factor for the coordinate units of a Canvas or Scene. A Canvas with a `width` of 5000 and a `spatialScale` with `value` 0.00008 represents a physical space 0.4 metres wide. The value of `unit` _MUST_ always be `m`, i.e., metres. + + +{% include api/code_header.html %} +``` json-doc +{ + "type": "Scene", + + "spatialScale": { + "type": "UnitValue", + "value": 22.0, + "unit": "m" + } +} +``` + + * A Canvas _MAY_ have the `spatialScale` property.
+ Clients _SHOULD_ process `spatialScale` on a Canvas. + * A Scene _MAY_ have the `spatialScale` property.
+ Clients _SHOULD_ process `spatialScale` on a Scene. ### start @@ -1964,6 +1987,33 @@ The value _MUST_ be a JSON object, which _MUST_ have the `id` and `type` propert { "supplementary": { "id": "https://example.org/iiif/1/annos/1", "type": "AnnotationCollection" } } ``` +### temporalScale +{: #temporalScale} + +A single UnitValue that defines a multiplier or scale factor for the `duration` property of a Container, indicating that one second in "Container time" represents some other real world duration. A Canvas with a `duration` of 450 seconds and a `temporalScale` with `value` 1000 represents a real-world duration of 450,000 seconds (5.2 days), for example a time-lapse video of a growing plant. The value of `unit` _MUST_ always be `s`, i.e., seconds. + + +{% include api/code_header.html %} +``` json-doc +{ + "type": "Canvas", + + "temporalScale": { + "type": "UnitValue", + "value": 1000, + "unit": "s" + } +} +``` + + * A Timeline _MAY_ have the `temporalScale` property.
+ Clients _MAY_ process `temporalScale` on a Timeline. + * A Canvas _MAY_ have the `temporalScale` property.
+ Clients _MAY_ process `temporalScale` on a Canvas. + * A Scene _MAY_ have the `temporalScale` property.
+ Clients _MAY_ process `temporalScale` on a Scene. + + ### thumbnail {: #thumbnail} From 6eefe1fd4789620cec3710cb2c1e4ee209acaadb Mon Sep 17 00:00:00 2001 From: tomcrane Date: Fri, 9 May 2025 16:38:33 +0100 Subject: [PATCH 2/7] phys dims in index.md --- source/presentation/4.0/index.md | 38 +++++--------------------------- 1 file changed, 5 insertions(+), 33 deletions(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index 1c4f43d0d..632cea93b 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -1478,43 +1478,15 @@ See above... ## Conveying Physical Dimensions -(why is this important!?) +It is often important to know how big something is, especially when comparing objects together. The dimensions of a Canvas, or the pixel density of a photograph, are unrelated to the real-world size of the object they show. A large wall painting and a tiny miniature may both be conveyed by 20 megapixel source images on a 4000 by 3000 unit Canvas. -(move the props to vocab doc) +The `spatialScale` property of a Canvas or Scene provides a corresponding real-world scale for a unit of the Canvas or Scene coordinate system, allowing clients to provide scale information to users, for example by an on-screen virtual ruler. In a 2-up viewer, a client could scale two views to convey the true relative sizes of two objects. +The value of `spatialScale` is a `UnitValue` (ref) that always has the value "m", i.e., metres. If source size metadata is machine readable (or parse-able) in other measurement systems (e.g., feet and inches) then it should be converted to metres for use in `spatialScale`. Publishers may wish to present the original given measure (e.g., from catalogue metadata) in a `metadata` field for context. -Continental drift simulation example - -``` -{ - "type": "Scene", - - "spatialScale": { - "type": "UnitValue", - "value": 22.0, - "unit": "m" - }, - - // this would be rarely used - "temporalScale": { - "type": "UnitValue", - "value": 0.00001, - "unit": "s" - } - -} -``` - -`factor` Required A floating point ratio. -`units` Required A real-world measuring unit. Always seconds for temporalScale. Possible values for spatialScale include: "m", "ft". (is that it?) - -For a Canvas, it's the physical "size" of each cartesian integer unit. -For a Scene, it's the physical size of the unit vector. -For a timeline it's the ratio of time in the recording to time in the real world. - - -(define props in the Vocabulary doc) +The Presentation API also offers a corresponding `temporalScale` property for the `duration` dimension of a Container, when 1 second in the Container does not correspond to 1 second of real time. This is useful for speeded-up or slowed-down audio or video. +An extreme example of both physical dimension properties together is a Canvas showing an animation of continental drift over the course of Earth history, where the spatialScale could convey that each Canvas unit is several thousand metres, and each second of the Canvas `duration` is several million years. From 0bf6b9f76032f9151d193f7918c24c6bb30d6dbd Mon Sep 17 00:00:00 2001 From: Tom Crane Date: Wed, 21 May 2025 13:38:34 +0100 Subject: [PATCH 3/7] Apply suggestions from code review Co-authored-by: Julie Winchester --- source/presentation/4.0/index.md | 2 +- source/presentation/4.0/model.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index 632cea93b..bb3c2b938 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -1478,7 +1478,7 @@ See above... ## Conveying Physical Dimensions -It is often important to know how big something is, especially when comparing objects together. The dimensions of a Canvas, or the pixel density of a photograph, are unrelated to the real-world size of the object they show. A large wall painting and a tiny miniature may both be conveyed by 20 megapixel source images on a 4000 by 3000 unit Canvas. +In many cases, the dimensions of a Canvas, or the pixel density of a photograph, are not necessarily related to the real-world size of the object they show. A large wall painting and a tiny miniature may both be conveyed by 20 megapixel source images on a 4000 by 3000 unit Canvas. But it can be important to know how big something is or if there is a relationship between pixel density and physical length, especially when comparing objects together. An X-Ray image may have a tight expectation for the physical distance between two adjacent pixels, or a scanned 3D model may be constructed such that each 3D coordinate unit corresponds to one meter of physical distance. The `spatialScale` property of a Canvas or Scene provides a corresponding real-world scale for a unit of the Canvas or Scene coordinate system, allowing clients to provide scale information to users, for example by an on-screen virtual ruler. In a 2-up viewer, a client could scale two views to convey the true relative sizes of two objects. diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index 0279e8efc..9a837fc8b 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -1852,7 +1852,7 @@ The value _MUST_ be an array of JSON objects. Each object _MUST_ be a service re ### spatialScale {: #spatialScale} -A single UnitValue that defines a real-world scale factor for the coordinate units of a Canvas or Scene. A Canvas with a `width` of 5000 and a `spatialScale` with `value` 0.00008 represents a physical space 0.4 metres wide. The value of `unit` _MUST_ always be `m`, i.e., metres. +A single UnitValue that defines a real-world scale factor for the coordinate units of a Canvas or Scene. For a Canvas, this defines the physical distance between adjacent units horizontally and vertically. A Canvas with a `width` of 5000 and a `spatialScale` with `value` 0.00008 represents a physical space 0.4 metres wide. For a Scene, this defines the physical distance corresponding to the XYZ coordinate units, or in other words, the physical distance length of a unit vector in the 3D coordinate space. The value of `unit` _MUST_ always be `m`, i.e., metres. {% include api/code_header.html %} From 86b0492e6c9ec20fd0808b1a55d631bebf7acb51 Mon Sep 17 00:00:00 2001 From: Tom Crane Date: Mon, 2 Jun 2025 09:19:22 +0100 Subject: [PATCH 4/7] Apply suggestions from code review Co-authored-by: Julie Winchester --- source/presentation/4.0/index.md | 2 +- source/presentation/4.0/model.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index bb3c2b938..4c4a65f8d 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -1482,7 +1482,7 @@ In many cases, the dimensions of a Canvas, or the pixel density of a photograph, The `spatialScale` property of a Canvas or Scene provides a corresponding real-world scale for a unit of the Canvas or Scene coordinate system, allowing clients to provide scale information to users, for example by an on-screen virtual ruler. In a 2-up viewer, a client could scale two views to convey the true relative sizes of two objects. -The value of `spatialScale` is a `UnitValue` (ref) that always has the value "m", i.e., metres. If source size metadata is machine readable (or parse-able) in other measurement systems (e.g., feet and inches) then it should be converted to metres for use in `spatialScale`. Publishers may wish to present the original given measure (e.g., from catalogue metadata) in a `metadata` field for context. +The value of `spatialScale` is a `UnitValue` (ref) that has as a value a length unit. This specification defines only one length unit, "m", i.e., metres, though others may be defined externally as an [extension][prezi30-ldce]. If source size metadata is machine readable (or parse-able) in other measurement systems (e.g., feet and inches) then it should be converted to metres for use in `spatialScale`. Publishers may wish to present the original given measure (e.g., from catalogue metadata) in a `metadata` field for context. The Presentation API also offers a corresponding `temporalScale` property for the `duration` dimension of a Container, when 1 second in the Container does not correspond to 1 second of real time. This is useful for speeded-up or slowed-down audio or video. diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index 9a837fc8b..67170c1c0 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -1852,7 +1852,7 @@ The value _MUST_ be an array of JSON objects. Each object _MUST_ be a service re ### spatialScale {: #spatialScale} -A single UnitValue that defines a real-world scale factor for the coordinate units of a Canvas or Scene. For a Canvas, this defines the physical distance between adjacent units horizontally and vertically. A Canvas with a `width` of 5000 and a `spatialScale` with `value` 0.00008 represents a physical space 0.4 metres wide. For a Scene, this defines the physical distance corresponding to the XYZ coordinate units, or in other words, the physical distance length of a unit vector in the 3D coordinate space. The value of `unit` _MUST_ always be `m`, i.e., metres. +A single UnitValue that defines a real-world scale factor for the coordinate units of a Canvas or Scene. For a Canvas, this defines the physical distance between adjacent units horizontally and vertically. A Canvas with a `width` of 5000 and a `spatialScale` with `value` 0.00008 represents a physical space 0.4 metres wide. For a Scene, this defines the physical distance corresponding to the XYZ coordinate units, or in other words, the physical distance length of a unit vector in the 3D coordinate space. The value of `unit` _MUST_ be a length unit. In this specification, the only length unit defined is `m`, i.e., metres. Unless other values are defined externally as an [extension][prezi30-ldce], the value of `unit` _SHOULD_ always be `m`. {% include api/code_header.html %} From 7cb83025c6332655927aa1d1defe3c5c4cd4ce4a Mon Sep 17 00:00:00 2001 From: Tom Crane Date: Mon, 2 Jun 2025 09:20:21 +0100 Subject: [PATCH 5/7] Apply suggestions from code review Co-authored-by: Julie Winchester --- source/presentation/4.0/model.md | 24 +++++++++++------------- 1 file changed, 11 insertions(+), 13 deletions(-) diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index 67170c1c0..9b5ceeb44 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -1859,12 +1859,11 @@ A single UnitValue that defines a real-world scale factor for the coordinate uni ``` json-doc { "type": "Scene", - - "spatialScale": { - "type": "UnitValue", - "value": 22.0, - "unit": "m" - } + "spatialScale": { + "type": "UnitValue", + "value": 22.0, + "unit": "m" + } } ``` @@ -1990,19 +1989,18 @@ The value _MUST_ be a JSON object, which _MUST_ have the `id` and `type` propert ### temporalScale {: #temporalScale} -A single UnitValue that defines a multiplier or scale factor for the `duration` property of a Container, indicating that one second in "Container time" represents some other real world duration. A Canvas with a `duration` of 450 seconds and a `temporalScale` with `value` 1000 represents a real-world duration of 450,000 seconds (5.2 days), for example a time-lapse video of a growing plant. The value of `unit` _MUST_ always be `s`, i.e., seconds. +A single UnitValue that defines a multiplier or scale factor for the `duration` property of a Container, indicating that one second in "Container time" represents some other real world duration. A Canvas with a `duration` of 450 seconds and a `temporalScale` with `value` 1000 represents a real-world duration of 450,000 seconds (5.2 days), for example a time-lapse video of a growing plant. The value of `unit` _MUST_ be a time unit. In this specification, the only time unit defined is `s`, i.e., seconds. Unless other values are defined externally as an [extension][prezi30-ldce], the value of `unit` _SHOULD_ always be `s`. {% include api/code_header.html %} ``` json-doc { "type": "Canvas", - - "temporalScale": { - "type": "UnitValue", - "value": 1000, - "unit": "s" - } + "temporalScale": { + "type": "UnitValue", + "value": 1000, + "unit": "s" + } } ``` From bfbe5a0ee24484d7fa6da9b01eee8a566cea48e0 Mon Sep 17 00:00:00 2001 From: tomcrane Date: Mon, 2 Jun 2025 09:20:51 +0100 Subject: [PATCH 6/7] physical dims --- source/presentation/4.0/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index bb3c2b938..6f01c5478 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -1478,7 +1478,7 @@ See above... ## Conveying Physical Dimensions -In many cases, the dimensions of a Canvas, or the pixel density of a photograph, are not necessarily related to the real-world size of the object they show. A large wall painting and a tiny miniature may both be conveyed by 20 megapixel source images on a 4000 by 3000 unit Canvas. But it can be important to know how big something is or if there is a relationship between pixel density and physical length, especially when comparing objects together. An X-Ray image may have a tight expectation for the physical distance between two adjacent pixels, or a scanned 3D model may be constructed such that each 3D coordinate unit corresponds to one meter of physical distance. +In many cases, the dimensions of a Canvas, or the pixel density of a photograph, are not necessarily related to the real-world size of the object they show. A large wall painting and a tiny miniature may both be conveyed by 20 megapixel source images on a 4000 by 3000 unit Canvas. But it can be important to know how big something is or if there is a relationship between pixel density and physical length, especially when comparing objects together. Each pixel in an image may correspond precisely to a physical area in the real world, or a scanned 3D model may be constructed such that each 3D coordinate unit corresponds to one meter of physical distance. The `spatialScale` property of a Canvas or Scene provides a corresponding real-world scale for a unit of the Canvas or Scene coordinate system, allowing clients to provide scale information to users, for example by an on-screen virtual ruler. In a 2-up viewer, a client could scale two views to convey the true relative sizes of two objects. From 2c0ea1292c0a43a91a1c405d7791dd3cb07a5936 Mon Sep 17 00:00:00 2001 From: tomcrane Date: Mon, 2 Jun 2025 09:24:59 +0100 Subject: [PATCH 7/7] metres --- source/presentation/4.0/index.md | 6 +++--- source/presentation/4.0/model.md | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/source/presentation/4.0/index.md b/source/presentation/4.0/index.md index fe5202e6f..e6031f60d 100644 --- a/source/presentation/4.0/index.md +++ b/source/presentation/4.0/index.md @@ -1478,15 +1478,15 @@ See above... ## Conveying Physical Dimensions -In many cases, the dimensions of a Canvas, or the pixel density of a photograph, are not necessarily related to the real-world size of the object they show. A large wall painting and a tiny miniature may both be conveyed by 20 megapixel source images on a 4000 by 3000 unit Canvas. But it can be important to know how big something is or if there is a relationship between pixel density and physical length, especially when comparing objects together. Each pixel in an image may correspond precisely to a physical area in the real world, or a scanned 3D model may be constructed such that each 3D coordinate unit corresponds to one meter of physical distance. +In many cases, the dimensions of a Canvas, or the pixel density of a photograph, are not necessarily related to a real-world size of the object they show. A large wall painting and a tiny miniature may both be conveyed by 20 megapixel source images on a 4000 by 3000 unit Canvas. But it can be important to know how big something is or if there is a relationship between pixel density and physical length, especially when comparing objects together. Each pixel in an image may correspond precisely to a physical area, allowing measurement of real world distances from the image. A scanned 3D model may be constructed such that each 3D coordinate unit corresponds to one meter of physical distance. The `spatialScale` property of a Canvas or Scene provides a corresponding real-world scale for a unit of the Canvas or Scene coordinate system, allowing clients to provide scale information to users, for example by an on-screen virtual ruler. In a 2-up viewer, a client could scale two views to convey the true relative sizes of two objects. -The value of `spatialScale` is a `UnitValue` (ref) that has as a value a length unit. This specification defines only one length unit, "m", i.e., metres, though others may be defined externally as an [extension][prezi30-ldce]. If source size metadata is machine readable (or parse-able) in other measurement systems (e.g., feet and inches) then it should be converted to metres for use in `spatialScale`. Publishers may wish to present the original given measure (e.g., from catalogue metadata) in a `metadata` field for context. +The value of `spatialScale` is a `UnitValue` (ref) that has as a value a length unit. This specification defines only one length unit, "m", i.e., meters, though others may be defined externally as an [extension][prezi30-ldce]. If source size metadata is machine readable (or parse-able) in other measurement systems (e.g., feet and inches) then it should be converted to meters for use in `spatialScale`. Publishers may wish to present the original given measure (e.g., from catalogue metadata) in a `metadata` field for context. The Presentation API also offers a corresponding `temporalScale` property for the `duration` dimension of a Container, when 1 second in the Container does not correspond to 1 second of real time. This is useful for speeded-up or slowed-down audio or video. -An extreme example of both physical dimension properties together is a Canvas showing an animation of continental drift over the course of Earth history, where the spatialScale could convey that each Canvas unit is several thousand metres, and each second of the Canvas `duration` is several million years. +An extreme example of both physical dimension properties together is a Canvas showing an animation of continental drift over the course of Earth history, where the spatialScale could convey that each Canvas unit is several thousand meters, and each second of the Canvas `duration` is several million years. diff --git a/source/presentation/4.0/model.md b/source/presentation/4.0/model.md index 9b5ceeb44..af041e126 100644 --- a/source/presentation/4.0/model.md +++ b/source/presentation/4.0/model.md @@ -1852,7 +1852,7 @@ The value _MUST_ be an array of JSON objects. Each object _MUST_ be a service re ### spatialScale {: #spatialScale} -A single UnitValue that defines a real-world scale factor for the coordinate units of a Canvas or Scene. For a Canvas, this defines the physical distance between adjacent units horizontally and vertically. A Canvas with a `width` of 5000 and a `spatialScale` with `value` 0.00008 represents a physical space 0.4 metres wide. For a Scene, this defines the physical distance corresponding to the XYZ coordinate units, or in other words, the physical distance length of a unit vector in the 3D coordinate space. The value of `unit` _MUST_ be a length unit. In this specification, the only length unit defined is `m`, i.e., metres. Unless other values are defined externally as an [extension][prezi30-ldce], the value of `unit` _SHOULD_ always be `m`. +A single UnitValue that defines a real-world scale factor for the coordinate units of a Canvas or Scene. For a Canvas, this defines the physical distance between adjacent units horizontally and vertically. A Canvas with a `width` of 5000 and a `spatialScale` with `value` 0.00008 represents a physical space 0.4 meters wide. For a Scene, this defines the physical distance corresponding to the XYZ coordinate units, or in other words, the physical distance length of a unit vector in the 3D coordinate space. The value of `unit` _MUST_ be a length unit. In this specification, the only length unit defined is `m`, i.e., meters. Unless other values are defined externally as an [extension][prezi30-ldce], the value of `unit` _SHOULD_ always be `m`. {% include api/code_header.html %}