linked-rolls 0.8.0 → 0.9.0

package/lib/schema.json

@@ -194,15 +194,15 @@
             "type": "string"
         },
         "CollationTolerance": {
-            "description": "Tolerance used in collation of roll copies. The start and end tolerances define the acceptable deviation (in mm) when aligning features across copies.",
+            "description": "Tolerance used in collation of roll copies: the acceptable deviation at either end when aligning features across copies.",
             "properties": {
                 "toleranceEnd": {
-                    "description": "Tolerance at the end position of a feature (in mm).",
-                    "type": "number"
+                    "$ref": "#/definitions/Millimeters",
+                    "description": "Tolerance at the end position of a feature."
                 },
                 "toleranceStart": {
-                    "description": "Tolerance at the start position of a feature (in mm).",
-                    "type": "number"
+                    "$ref": "#/definitions/Millimeters",
+                    "description": "Tolerance at the start position of a feature."
                 }
             },
             "required": [
@@ -648,12 +648,12 @@
             "description": "Describes the horizontal extent of a feature on the roll, measured in millimeters from the beginning of the roll. The `from` value is the start position and `to` is the end position. [ontology: crm:E54 Dimension]",
             "properties": {
                 "from": {
-                    "description": "The start position of the feature in millimeters from the beginning of the roll. [ontology: reo:from]",
-                    "type": "number"
+                    "$ref": "#/definitions/Millimeters",
+                    "description": "The start position of the feature in millimeters from the beginning of the roll. [ontology: reo:from]"
                 },
                 "to": {
-                    "description": "The end position of the feature in millimeters from the beginning of the roll. [ontology: reo:to]",
-                    "type": "number"
+                    "$ref": "#/definitions/Millimeters",
+                    "description": "The end position of the feature in millimeters from the beginning of the roll. [ontology: reo:to]"
                 },
                 "unit": {
                     "const": "mm",
@@ -699,6 +699,48 @@
             ],
             "type": "object"
         },
+        "Margins<\"mm\">": {
+            "description": "The margins on the treble and bass sides of the roll, in the unit the scan was measured in.",
+            "properties": {
+                "bass": {
+                    "$ref": "#/definitions/Quantity%3C%22mm%22%3E"
+                },
+                "treble": {
+                    "$ref": "#/definitions/Quantity%3C%22mm%22%3E"
+                },
+                "unit": {
+                    "const": "mm",
+                    "type": "string"
+                }
+            },
+            "required": [
+                "treble",
+                "bass",
+                "unit"
+            ],
+            "type": "object"
+        },
+        "Margins<\"px\">": {
+            "description": "The margins on the treble and bass sides of the roll, in the unit the scan was measured in.",
+            "properties": {
+                "bass": {
+                    "$ref": "#/definitions/Quantity%3C%22px%22%3E"
+                },
+                "treble": {
+                    "$ref": "#/definitions/Quantity%3C%22px%22%3E"
+                },
+                "unit": {
+                    "const": "px",
+                    "type": "string"
+                }
+            },
+            "required": [
+                "treble",
+                "bass",
+                "unit"
+            ],
+            "type": "object"
+        },
         "Mark": {
             "description": "A visible mark on the roll, such as a pencil mark, ink mark, or other non-textual annotation. [ontology: crm:E25 Human-Made Feature]",
             "properties": {
@@ -768,6 +810,48 @@
             ],
             "type": "object"
         },
+        "Measure<\"mm\">": {
+            "description": "A value together with the unit it was measured in, as a record states it. [ontology: crm:E54 Dimension]",
+            "properties": {
+                "unit": {
+                    "const": "mm",
+                    "description": "The unit of measurement. [ontology: crm:P91 has unit]",
+                    "type": "string"
+                },
+                "value": {
+                    "$ref": "#/definitions/Quantity%3C%22mm%22%3E",
+                    "description": "The measured value. [ontology: crm:P90 has value]"
+                }
+            },
+            "required": [
+                "value",
+                "unit"
+            ],
+            "type": "object"
+        },
+        "Measure<\"px\">": {
+            "description": "A value together with the unit it was measured in, as a record states it. [ontology: crm:E54 Dimension]",
+            "properties": {
+                "unit": {
+                    "const": "px",
+                    "description": "The unit of measurement. [ontology: crm:P91 has unit]",
+                    "type": "string"
+                },
+                "value": {
+                    "$ref": "#/definitions/Quantity%3C%22px%22%3E",
+                    "description": "The measured value. [ontology: crm:P90 has value]"
+                }
+            },
+            "required": [
+                "value",
+                "unit"
+            ],
+            "type": "object"
+        },
+        "Millimeters": {
+            "$ref": "#/definitions/Quantity%3C%22mm%22%3E",
+            "description": "A place along the roll, or any length on the paper."
+        },
         "Modification": {
             "anyOf": [
                 {
@@ -1208,45 +1292,91 @@
             "type": "object"
         },
         "ObjectAssumption<RollTempo>": {
-            "description": "An object assumption wraps a complex object with an optional annotation. Used for structured values (e.g. persons, conditions) whose properties may be uncertain.",
-            "properties": {
-                "@annotation": {
-                    "description": "An optional annotation expressing a belief about this assumption. Uses the JSON-LD-star `@annotation` mechanism to attach epistemic metadata (certainty and reasons) to any triple.",
+            "anyOf": [
+                {
                     "properties": {
-                        "belief": {
-                            "$ref": "#/definitions/Belief",
-                            "description": "The belief held about the annotated statement. [ontology: crminf:J4i is subject of]"
+                        "@annotation": {
+                            "description": "An optional annotation expressing a belief about this assumption. Uses the JSON-LD-star `@annotation` mechanism to attach epistemic metadata (certainty and reasons) to any triple.",
+                            "properties": {
+                                "belief": {
+                                    "$ref": "#/definitions/Belief",
+                                    "description": "The belief held about the annotated statement. [ontology: crminf:J4i is subject of]"
+                                },
+                                "@id": {
+                                    "description": "A unique identifier for this object.",
+                                    "type": "string"
+                                }
+                            },
+                            "required": [
+                                "belief",
+                                "@id"
+                            ],
+                            "type": "object"
                         },
-                        "@id": {
-                            "description": "A unique identifier for this object.",
+                        "endsWith": {
+                            "$ref": "#/definitions/Quantity%3C%22ft%2Fmin%22%3E",
+                            "description": "The tempo at the end of the roll. [ontology: reo:to]"
+                        },
+                        "startsWith": {
+                            "$ref": "#/definitions/Quantity%3C%22ft%2Fmin%22%3E",
+                            "description": "The tempo at the beginning of the roll. [ontology: reo:from]"
+                        },
+                        "unit": {
+                            "const": "ft/min",
+                            "description": "The unit of the tempo measurement. [ontology: crm:P91 has unit]",
                             "type": "string"
                         }
                     },
                     "required": [
-                        "belief",
-                        "@id"
+                        "endsWith",
+                        "startsWith",
+                        "unit"
                     ],
                     "type": "object"
                 },
-                "endsWith": {
-                    "description": "The tempo at the end of the roll. [ontology: reo:to]",
-                    "type": "number"
-                },
-                "startsWith": {
-                    "description": "The tempo at the beginning of the roll. [ontology: reo:from]",
-                    "type": "number"
-                },
-                "unit": {
-                    "description": "The unit of the tempo measurement (e.g. 'ft/min', 'm/min'). [ontology: crm:P91 has unit]",
-                    "type": "string"
+                {
+                    "properties": {
+                        "@annotation": {
+                            "description": "An optional annotation expressing a belief about this assumption. Uses the JSON-LD-star `@annotation` mechanism to attach epistemic metadata (certainty and reasons) to any triple.",
+                            "properties": {
+                                "belief": {
+                                    "$ref": "#/definitions/Belief",
+                                    "description": "The belief held about the annotated statement. [ontology: crminf:J4i is subject of]"
+                                },
+                                "@id": {
+                                    "description": "A unique identifier for this object.",
+                                    "type": "string"
+                                }
+                            },
+                            "required": [
+                                "belief",
+                                "@id"
+                            ],
+                            "type": "object"
+                        },
+                        "endsWith": {
+                            "$ref": "#/definitions/Quantity%3C%22m%2Fmin%22%3E",
+                            "description": "The tempo at the end of the roll. [ontology: reo:to]"
+                        },
+                        "startsWith": {
+                            "$ref": "#/definitions/Quantity%3C%22m%2Fmin%22%3E",
+                            "description": "The tempo at the beginning of the roll. [ontology: reo:from]"
+                        },
+                        "unit": {
+                            "const": "m/min",
+                            "description": "The unit of the tempo measurement. [ontology: crm:P91 has unit]",
+                            "type": "string"
+                        }
+                    },
+                    "required": [
+                        "endsWith",
+                        "startsWith",
+                        "unit"
+                    ],
+                    "type": "object"
                 }
-            },
-            "required": [
-                "endsWith",
-                "startsWith",
-                "unit"
             ],
-            "type": "object"
+            "description": "An object assumption wraps a complex object with an optional annotation. Used for structured values (e.g. persons, conditions) whose properties may be uncertain."
         },
         "ObjectAssumption<Transcription>": {
             "description": "An object assumption wraps a complex object with an optional annotation. Used for structured values (e.g. persons, conditions) whose properties may be uncertain.",
@@ -1305,6 +1435,10 @@
             "$ref": "#/definitions/Agent",
             "description": "An agent that is a person."
         },
+        "Pixels": {
+            "$ref": "#/definitions/Quantity%3C%22px%22%3E",
+            "description": "A place in a scan. Comparable within one scan only, since the resolution is the scan's."
+        },
         "Place": {
             "description": "A place, e.g. a recording location, publishing location, etc. [ontology: crm:E53 Place]",
             "properties": {
@@ -1347,6 +1481,21 @@
             },
             "type": "object"
         },
+        "Quantity<\"ft/min\">": {
+            "type": "number"
+        },
+        "Quantity<\"m/min\">": {
+            "type": "number"
+        },
+        "Quantity<\"mm\">": {
+            "type": "number"
+        },
+        "Quantity<\"px\">": {
+            "type": "number"
+        },
+        "Quantity<\"track\">": {
+            "type": "number"
+        },
         "RecordingEvent": {
             "description": "Describes the event of recording and documents the persons involved in the process (e.g. pianist), the place, and the date of the recording. [ontology: lrmoo:F28 Expression Creation]",
             "properties": {
@@ -1477,16 +1626,17 @@
                             "description": "The physical dimensions of the roll. [ontology: reo:dimensions]",
                             "properties": {
                                 "height": {
-                                    "description": "The total height (length) of the roll in the given unit. [ontology: reo:height]",
-                                    "type": "number"
+                                    "$ref": "#/definitions/Millimeters",
+                                    "description": "The total height (length) of the roll. [ontology: reo:height]"
                                 },
                                 "unit": {
-                                    "description": "The unit of measurement (e.g. 'mm'). [ontology: crm:P91 has unit]",
+                                    "const": "mm",
+                                    "description": "The unit of measurement. [ontology: crm:P91 has unit]",
                                     "type": "string"
                                 },
                                 "width": {
-                                    "description": "The width of the roll in the given unit. [ontology: reo:width]",
-                                    "type": "number"
+                                    "$ref": "#/definitions/Millimeters",
+                                    "description": "The width of the roll. [ontology: reo:width]"
                                 }
                             },
                             "required": [
@@ -1497,45 +1647,26 @@
                             "type": "object"
                         },
                         "holeSeparation": {
-                            "description": "The distance between adjacent tracker bar holes. [ontology: reo:holeSeparation]",
-                            "properties": {
-                                "unit": {
-                                    "description": "The unit of measurement (e.g. 'px', 'mm'). [ontology: crm:P91 has unit]",
-                                    "type": "string"
+                            "anyOf": [
+                                {
+                                    "$ref": "#/definitions/Measure%3C%22px%22%3E"
                                 },
-                                "value": {
-                                    "description": "The measured hole separation value. [ontology: crm:P90 has value]",
-                                    "type": "number"
+                                {
+                                    "$ref": "#/definitions/Measure%3C%22mm%22%3E"
                                 }
-                            },
-                            "required": [
-                                "value",
-                                "unit"
                             ],
-                            "type": "object"
+                            "description": "The distance between adjacent tracker bar holes, in the unit the scan was measured in. [ontology: reo:holeSeparation]"
                         },
                         "margins": {
-                            "description": "The margins on the treble and bass sides of the roll. Not exported to RDF.",
-                            "properties": {
-                                "bass": {
-                                    "description": "The margin on the bass side.",
-                                    "type": "number"
+                            "anyOf": [
+                                {
+                                    "$ref": "#/definitions/Margins%3C%22px%22%3E"
                                 },
-                                "treble": {
-                                    "description": "The margin on the treble side.",
-                                    "type": "number"
-                                },
-                                "unit": {
-                                    "description": "The unit of measurement (e.g. 'px', 'mm').",
-                                    "type": "string"
+                                {
+                                    "$ref": "#/definitions/Margins%3C%22mm%22%3E"
                                 }
-                            },
-                            "required": [
-                                "treble",
-                                "bass",
-                                "unit"
                             ],
-                            "type": "object"
+                            "description": "The margins on the treble and bass sides of the roll. Not exported to RDF."
                         },
                         "measuredBy": {
                             "description": "Information about the software used to take the measurements. [ontology: crmdig:L23 used software or firmware]",
@@ -1562,22 +1693,8 @@
                             "type": "object"
                         },
                         "punchDiameter": {
-                            "description": "The average diameter of punched holes. [ontology: reo:punchDiameter]",
-                            "properties": {
-                                "unit": {
-                                    "description": "The unit of measurement (e.g. 'mm'). [ontology: crm:P91 has unit]",
-                                    "type": "string"
-                                },
-                                "value": {
-                                    "description": "The measured punch diameter value. [ontology: crm:P90 has value]",
-                                    "type": "number"
-                                }
-                            },
-                            "required": [
-                                "value",
-                                "unit"
-                            ],
-                            "type": "object"
+                            "$ref": "#/definitions/Measure%3C%22mm%22%3E",
+                            "description": "The average diameter of punched holes. [ontology: reo:punchDiameter]"
                         },
                         "shift": {
                             "$ref": "#/definitions/Shift",
@@ -1643,12 +1760,12 @@
             "description": "A shift correction applied to a roll copy to align it with other copies. The shift is defined as horizontal (along the roll length, in mm) and vertical (across tracks).",
             "properties": {
                 "horizontal": {
-                    "description": "Horizontal shift in millimeters (along the roll length).",
-                    "type": "number"
+                    "$ref": "#/definitions/Millimeters",
+                    "description": "Along the roll."
                 },
                 "vertical": {
-                    "description": "Vertical shift in track numbers (across the tracker bar).",
-                    "type": "number"
+                    "$ref": "#/definitions/Track",
+                    "description": "Across the tracker bar."
                 }
             },
             "required": [
@@ -1690,20 +1807,24 @@
             ],
             "type": "object"
         },
+        "Track": {
+            "$ref": "#/definitions/Quantity%3C%22track%22%3E",
+            "description": "A position across the roll, numbered as the tracker bar does."
+        },
         "TrackCalibration": {
             "description": "Relates a scan to the tracker bar it was read with.\n\nScanning software numbers the hole columns it finds by their position in the image, so its numbering is offset by however far the roll lay from the edge of the scanner bed. Calibrating means finding that offset, usually from a landmark such as the rewind perforation.\n\n    column      = offset + scannerTrack * separation     trackerBar  = scannerTrack + shift",
             "properties": {
                 "offset": {
-                    "description": "Image column of the scanning software's track 0.",
-                    "type": "number"
+                    "$ref": "#/definitions/Pixels",
+                    "description": "Image column of the scanning software's track 0."
                 },
                 "separation": {
-                    "description": "Distance between the centres of adjacent tracks.",
-                    "type": "number"
+                    "$ref": "#/definitions/Pixels",
+                    "description": "Distance between the centres of adjacent tracks."
                 },
                 "shift": {
-                    "description": "Added to the scanning software's numbering to reach the tracker bar.",
-                    "type": "number"
+                    "$ref": "#/definitions/Track",
+                    "description": "Added to the scanning software's numbering to reach the tracker bar."
                 },
                 "unit": {
                     "const": "px",
@@ -1780,12 +1901,12 @@
             "description": "Describes the vertical extent of a feature on the roll, measured in track numbers. Track numbers correspond to positions on the tracker bar. [ontology: crm:E54 Dimension]",
             "properties": {
                 "from": {
-                    "description": "The start track number of the feature. [ontology: reo:from]",
-                    "type": "number"
+                    "$ref": "#/definitions/Track",
+                    "description": "The start track number of the feature. [ontology: reo:from]"
                 },
                 "to": {
-                    "description": "The end track number, if the feature spans multiple tracks. If omitted, the feature occupies a single track. [ontology: reo:to]",
-                    "type": "number"
+                    "$ref": "#/definitions/Track",
+                    "description": "The end track number, if the feature spans multiple tracks. If omitted, the feature occupies a single track. [ontology: reo:to]"
                 },
                 "unit": {
                     "const": "track",

package/lib/systems/welteT100/bar.js

@@ -1,4 +1,5 @@
 import { describeTrackerBar } from "../../TrackerBar";
+import { mm } from "../../Quantity";
 /**
  * The commands of the Welte-Mignon T-100, as its tracker bar reads them.
  */
@@ -28,7 +29,7 @@ export const welteT100ExpressionTypes = [
 export const welteT100 = describeTrackerBar({
     id: 'welte-t100',
     name: 'Welte-Mignon T100',
-    width: 328,
+    width: mm(328),
     trackCount: 100,
     notes: { from: 11, to: 90, lowestPitch: 24 },
     expressions: new Map([

package/lib/systems/welteT100/system.d.ts

@@ -1,5 +1,6 @@
 import { Half, Instrument, Parameters, PedalMode, RollNumber, Spool } from "welte-t100-emulator";
 import { ReproducingSystem } from "../../ReproducingSystem";
+import { Millimeters, Seconds, Track } from "../../Quantity";
 /**
  * MIDI velocity at the open rail of the Nuancierbalg, at the Mezzoforte pin,
  * and at the closed rail, joined linearly in between. Nothing in the
@@ -59,21 +60,21 @@ export type WelteT100Options = {
      * understands.
      */
     pedalMode: PedalMode;
-    /** Diameter of the tracker-bar bore, in mm. */
-    trackerBore: number;
-    /** Punch diameter in mm, for an edition whose copies record none. */
-    punchDiameter: number;
+    /** Diameter of the tracker-bar bore. */
+    trackerBore: Millimeters;
+    /** Punch diameter for an edition whose copies record none. */
+    punchDiameter: Millimeters;
     /**
      * The track at which the keyboard is divided, so that notes from
      * here upwards follow the treble expression and the ones below it
      * the bass. Which side an expression perforation itself belongs to
      * is not decided here but read off the tracker bar.
      */
-    division: number;
+    division: Track;
 };
 export declare const defaultWelteT100Options: WelteT100Options;
-/** When the spool brings a place on the roll, in mm, to the tracker bar. */
-export declare const secondsAt: (spool: Spool, mm: number) => number;
+/** When the spool brings a place on the roll to the tracker bar. */
+export declare const secondsAt: (spool: Spool, place: Millimeters) => Seconds;
 /**
  * The red Welte, as welte-t100-emulator models it: the take-up spool sets
  * the time axis, the Nuancierbälge fill through their conduits and are

package/lib/systems/welteT100/system.js

@@ -1,5 +1,6 @@
 import { aperturePorts, CONSENSUS, DEFAULT_PUNCH_MM, geometryInMm, Grid, levelChanges, mezzoforteTravel, paperSeconds, pedalBrushing, pedalDefaults, pneumaticModel, PRESETS, ROWS_PER_MM, runPedals, TRACKER_BORE_MM, travelBetweenRails, WELTE_SPOOL, } from "welte-t100-emulator";
 import { welteT100 } from "./bar";
+import { add, inCentimeters, mm, seconds, track } from "../../Quantity";
 /**
  * The instruments the emulator was fitted as: the consensus over the six
  * rolls with drawn nuance lines, and the setting that drew each of them,
@@ -35,9 +36,9 @@ export const defaultWelteT100Options = {
     pedals: pedalPresets.damping,
     velocity: { piano: 35, mezzoforte: 60, forte: 90 },
     pedalMode: 'continuous',
-    trackerBore: TRACKER_BORE_MM,
-    punchDiameter: DEFAULT_PUNCH_MM,
-    division: 54
+    trackerBore: mm(TRACKER_BORE_MM),
+    punchDiameter: mm(DEFAULT_PUNCH_MM),
+    division: track(54)
 };
 /** What each expression code operates, in the emulator's terms. */
 const CODES = {
@@ -59,7 +60,7 @@ const CODES = {
 const isWelteT100ExpressionType = (type) => Object.hasOwn(CODES, type);
 const codeOf = (expressionType) => isWelteT100ExpressionType(expressionType) ? CODES[expressionType] : undefined;
 /** Paper the grid runs on past the last hole, so that a final pedal release completes. */
-const RUN_OUT_MM = 100;
+const RUN_OUT = mm(100);
 /**
  * Which stack of valves an expression perforation belongs to. The symbol
  * usually says so, having been read off the tracker bar already; where it
@@ -74,9 +75,11 @@ const scopeOf = (event) => {
 };
 const isNote = (event) => event.type === 'note';
 const isExpression = (event) => event.type === 'expression';
-const rowOf = (mm) => mm * ROWS_PER_MM;
-/** When the spool brings a place on the roll, in mm, to the tracker bar. */
-export const secondsAt = (spool, mm) => paperSeconds(spool, mm / 10);
+/** The row of the scan the constants were fitted on that a place on the roll falls in. */
+const rowOf = (place) => place * ROWS_PER_MM;
+const placeOfRow = (row) => mm(row / ROWS_PER_MM);
+/** When the spool brings a place on the roll to the tracker bar. */
+export const secondsAt = (spool, place) => seconds(paperSeconds(spool, inCentimeters(place)));
 const halfOf = (note, division) => note.vertical.from >= division ? 'treble' : 'bass';
 const readingOf = (event) => {
     const code = codeOf(event.expressionType);
@@ -108,10 +111,10 @@ const velocityOf = (travel, hook, map) => {
  * emulator expects.
  */
 const gridOver = (events, spool) => {
-    const lastMm = events.reduce((furthest, event) => Math.max(furthest, event.horizontal.to), 0);
-    const length = Math.ceil(rowOf(lastMm + RUN_OUT_MM)) + 1;
-    const seconds = Float64Array.from({ length }, (_, row) => secondsAt(spool, row / ROWS_PER_MM));
-    return new Grid(0, seconds);
+    const last = mm(events.reduce((furthest, event) => Math.max(furthest, event.horizontal.to), 0));
+    const length = Math.ceil(rowOf(add(last, RUN_OUT))) + 1;
+    const times = Float64Array.from({ length }, (_, row) => secondsAt(spool, placeOfRow(row)));
+    return new Grid(0, times);
 };
 const nuanceCurves = (grid, ports, samples, options) => {
     const curveOf = (half) => {
@@ -162,7 +165,7 @@ const performPedal = (type, curve, grid, readings, mode) => {
         type,
         performs: causeOf(grid.rowAt(change.index)),
         value: change.value,
-        at: curve.seconds[change.index]
+        at: seconds(curve.seconds[change.index])
     }));
 };
 /**
@@ -179,7 +182,7 @@ const perform = (events, options, roll) => {
     const geometry = geometryInMm(roll.punchDiameter ?? options.punchDiameter, options.trackerBore);
     const ports = aperturePorts(grid, readings.map(reading => reading.punch), geometry);
     const samples = {
-        place: Float64Array.from(grid.seconds, (_, row) => row / ROWS_PER_MM),
+        place: Float64Array.from(grid.seconds, (_, row) => placeOfRow(row)),
         seconds: grid.seconds
     };
     const nuance = nuanceCurves(grid, ports, samples, options);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "linked-rolls",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Digital editions of piano rolls: import, collation, editorial assumptions, JSON-LD export, and emulation through a reproducing system",
   "license": "MIT",
   "repository": {