Merge pull request #2347 from IIIF/prezi-4-scale

Prezi 4 scale

Author: azaroth42

source/presentation/4.0/index.md

@@ -1633,43 +1633,15 @@ See above...
 
 ## Conveying Physical Dimensions
 
-(why is this important!?)
+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.
 
-(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 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.
 
-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 meters, and each second of the Canvas `duration` is several million years.
 
 
 

source/presentation/4.0/model.md

@@ -2045,6 +2045,28 @@ 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. 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 %}
+``` json-doc
+{
+  "type": "Scene",
+  "spatialScale": {
+    "type": "UnitValue",
+    "value": 22.0,
+    "unit": "m"
+  }
+}
+```
+
+ * A Canvas _MAY_ have the `spatialScale` property.<br/>
+   Clients _SHOULD_ process `spatialScale` on a Canvas.
+ * A Scene _MAY_ have the `spatialScale` property.<br/>
+   Clients _SHOULD_ process `spatialScale` on a Scene.
 
 
 ### start
@@ -2160,6 +2182,32 @@ 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_ 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"
+  }
+}
+```
+
+ * A Timeline _MAY_ have the `temporalScale` property.<br/>
+   Clients _MAY_ process `temporalScale` on a Timeline.
+ * A Canvas _MAY_ have the `temporalScale` property.<br/>
+   Clients _MAY_ process `temporalScale` on a Canvas.
+ * A Scene _MAY_ have the `temporalScale` property.<br/>
+   Clients _MAY_ process `temporalScale` on a Scene.
+   
+
 ### thumbnail
 {: #thumbnail}