linked-rolls 0.19.1 → 0.20.0

package/lib/readers/stanfordAton.js

@@ -1,6 +1,6 @@
 import { v4 } from "uuid";
 import { AtonParser } from "./AtonParser";
-import { systemOf, translationBetween } from "../TrackerBar";
+import { systemOf } from "../TrackerBar";
 import { welteT100 } from "../systems/welteT100/bar";
 import { inMillimeters, mean, mm, pixelsPerInch, px, subtract, track } from "../Quantity";
 /** Values in these files carry their unit as a suffix, e.g. "37.7646px". */
@@ -110,7 +110,7 @@ const measuredByOf = (rollinfo) => {
         date
     };
 };
-export function readFromStanfordAton(atonString, { trackShift, bar = welteT100, system = bar, scan } = {}) {
+export function readFromStanfordAton(atonString, { trackShift, system = welteT100, scan } = {}) {
     const parser = new AtonParser();
     const json = parser.parse(atonString);
     const holes = json.ROLLINFO.HOLES.HOLE;
@@ -128,11 +128,10 @@ export function readFromStanfordAton(atonString, { trackShift, bar = welteT100,
     };
     const punchDiameter = punchDiameterOf(holes, dpi);
     const chains = chainsAmong([...holes, ...chainedBadHoles(listOf(json.ROLLINFO.BADHOLES?.HOLE), calibration)]);
-    const onBar = translationBetween(system, bar);
     const features = chains
         .flatMap(({ hole, attack, release }) => {
-        const position = onBar(track(+hole.TRACKER_HOLE + shift));
-        if (position === undefined)
+        const position = track(+hole.TRACKER_HOLE + shift);
+        if (!system.meaningOf(position))
             return [];
         const column = readPx(hole.ORIGIN_COL);
         const columnWidth = readPx(hole.WIDTH_COL);

package/lib/reservations.d.ts

@@ -1,5 +1,5 @@
 import { RollCopy } from "./RollCopy";
-export declare const reservationTypes: readonly ['source-not-stated', 'source-undocumented', 'features-interpreted', 'no-physical-evidence', 'measurement-undocumented', 'not-calibrated'];
+export declare const reservationTypes: readonly ['source-not-stated', 'source-undocumented', 'features-interpreted', 'no-physical-evidence', 'measurement-undocumented', 'not-calibrated', 'system-unknown'];
 export type ReservationType = typeof reservationTypes[number];
 /**
  * Something an edition cannot vouch for in one of its copies.

package/lib/reservations.js

@@ -1,12 +1,14 @@
 import { bearsPhysicalEvidence, isMeasured, sourceLabels } from "./FeatureSource";
 import { calibrationOf } from "./RollCopy";
+import { trackerBarOf } from "./systems";
 export const reservationTypes = [
     'source-not-stated',
     'source-undocumented',
     'features-interpreted',
     'no-physical-evidence',
     'measurement-undocumented',
-    'not-calibrated'
+    'not-calibrated',
+    'system-unknown'
 ];
 const sourceStated = copy => copy.readFrom ? undefined : {
     type: 'source-not-stated',
@@ -37,13 +39,33 @@ const calibrated = copy => calibrationOf(copy) ? undefined : {
     type: 'not-calibrated',
     note: 'The copy is not calibrated against the tracker bar, so its track positions rest on the numbering its source used.'
 };
+/**
+ * The bar decides what every track on the copy means, so a copy the
+ * edition cannot place in a system is read by the T-100 for want of
+ * anything better. Between two Welte scales that is a semitone rather
+ * than a visible error, which is why it is said out loud.
+ */
+const systemKnown = copy => {
+    const system = copy.production?.system;
+    if (system === undefined) {
+        return {
+            type: 'system-unknown',
+            note: 'The copy names no reproducing system, so it is read by the T-100 tracker bar.'
+        };
+    }
+    return trackerBarOf(system) ? undefined : {
+        type: 'system-unknown',
+        note: `The copy names ${system.name || 'a reproducing system'}, which the edition has no tracker bar for, so it is read by the T-100's.`
+    };
+};
 const checks = [
     sourceStated,
     sourceDocumented,
     featuresMeasured,
     physicalEvidence,
     measurementDocumented,
-    calibrated
+    calibrated,
+    systemKnown
 ];
 /**
  * What the edition cannot vouch for in a copy, in the order the

package/lib/schema.json

@@ -1802,15 +1802,10 @@
                 "recordingEvent": {
                     "$ref": "#/definitions/RecordingEvent",
                     "description": "[ontology: lrmoo:R19i was realised through]"
-                },
-                "system": {
-                    "$ref": "#/definitions/Concept",
-                    "description": "The reproducing system the roll was cut for. A system the type vocabulary knows carries the IRI of its concept as `id`, from which the export takes the system's own context, so that the expression types are read as that system's. [ontology: crm:P2 has type]"
                 }
             },
             "required": [
                 "catalogueNumber",
-                "system",
                 "recordingEvent"
             ],
             "type": "object"
@@ -2089,6 +2084,10 @@
                     "$ref": "#/definitions/Derivation",
                     "description": "If no derivation is defined, it is assumed that this version represents the mother roll. [ontology: lrmoo:R76 is derivative of]"
                 },
+                "creation": {
+                    "$ref": "#/definitions/VersionCreation",
+                    "description": "The act that made this version, where it is known: who carried it out, when, and by what rule. [ontology: lrmoo:R17i was created by]"
+                },
                 "edits": {
                     "description": "The list of edits that, applied to the base version, produce this version. [ontology: reo:involvedEdit]",
                     "items": {
@@ -2107,6 +2106,10 @@
                     "description": "A short siglum to identify the version, e.g. \"A\", \"B1\", \"B2_rev\", etc. [ontology: reo:siglum]",
                     "type": "string"
                 },
+                "system": {
+                    "$ref": "#/definitions/Concept",
+                    "description": "The reproducing system this version is coded for. One roll was often issued for several of them, and a version is a reading in one system's words: its expression types are that system's vocabulary and its notes sit on that bar's positions. A system the type vocabulary knows carries the IRI of its concept as `id`, from which the export takes the system's own context. [ontology: crm:P2 has type]"
+                },
                 "versionType": {
                     "$ref": "#/definitions/VersionType",
                     "description": "Whether the version served as a master for reproductions or exists on one copy only. [ontology: crm:P2 has type]"
@@ -2127,11 +2130,30 @@
                 "@id",
                 "motivations",
                 "siglum",
+                "system",
                 "@type",
                 "versionType"
             ],
             "type": "object"
         },
+        "VersionCreation": {
+            "description": "How a version was made, where that is known and worth stating.\n\nA roll issued for another system was re-punched by an editor of the publisher's, and that was an editorial act rather than a conversion: Lawson names Kähle as the man who corrected second masters for the green system. The rule he worked by is the procedure named here, and the version's edits carry it out, so the mechanical part of a transfer is stated once instead of being spelled out per note. [ontology: lrmoo:F28 Expression Creation]",
+            "properties": {
+                "actor": {
+                    "$ref": "#/definitions/ActorAssignment",
+                    "description": "Who carried the act out. An `ObjectAssumption`, so an attribution can carry the belief it rests on and the reasons for it. [ontology: crm:P14 carried out by]"
+                },
+                "date": {
+                    "$ref": "#/definitions/DateAssignment",
+                    "description": "When it took place. [ontology: dcterms:date]"
+                },
+                "procedure": {
+                    "$ref": "#/definitions/Concept",
+                    "description": "The rule followed, as a term of the vocabulary: the notes stand at their pitch, the expression is re-spelled in the other system's words. [ontology: crm:P33 used specific technique]"
+                }
+            },
+            "type": "object"
+        },
         "VersionType": {
             "description": "The type of a version. An 'edition' version may serve as the master for several roll copies; a 'unicum' version exists only on one specific copy.",
             "enum": [

package/lib/spec/context.json

@@ -76,6 +76,7 @@
             "@type": "@id"
         },
         "creation": "lrmoo:R17i_was_created_by",
+        "procedure": "crm:P33_used_specific_technique",
         "editors": "crm:P14_carried_out_by",
         "publisher": "crm:P14_carried_out_by",
         "publicationDate": {

package/lib/spec/welte-licensee.context.json

@@ -0,0 +1,10 @@
+{
+    "@context": {
+        "@version": 1.1,
+        "expressionType": {
+            "@id": "http://www.cidoc-crm.org/cidoc-crm/P2_has_type",
+            "@type": "@vocab",
+            "@context": { "@vocab": "https://w3id.org/reo/type/welte-t100/" }
+        }
+    }
+}

package/lib/substitution.d.ts

@@ -0,0 +1,73 @@
+import { CollationTolerance, Locate } from "./Collation";
+import { AnySymbol, Expression } from "./Symbol";
+import { Millimeters, Track } from "./Quantity";
+import { TrackerBar } from "./TrackerBar";
+/**
+ * How a scale spells a command: as a perforation that turns a function
+ * on, one that cancels it, or one that holds it for as long as it lasts.
+ */
+export type Spelling = 'on' | 'off' | 'held';
+/**
+ * A command as what it operates rather than as the word a scale uses
+ * for it, so that two scales can be compared at all.
+ */
+export interface Command {
+    /** The function operated, named the same wherever a scale has it. */
+    operates: string;
+    spelling: Spelling;
+    /**
+     * Whether the half of the keyboard the valve serves is part of the
+     * command. The dynamics are per half; the pedals are not, and the
+     * two Welte scales put them on opposite edges of the paper, so a
+     * rule that compared sides would leave every pedal unpaired.
+     */
+    sided: boolean;
+}
+/** What a command operates, or nothing for a word no scale here knows. */
+export declare const commandOf: (expressionType: string) => Command | undefined;
+/**
+ * A latched function of the older version and the held perforation of
+ * the newer one that stands for it.
+ */
+export interface Substitution {
+    /** The perforation that turned the function on, and the one that cancelled it. */
+    replaced: readonly [Expression, Expression];
+    /**
+     * The perforations that say the same thing in the other scale's
+     * words. Usually one, but a held command is punched as a chain of
+     * round holes with paper bridges rather than as a slot, and a scan
+     * whose analysis reports those singly gives one symbol per punch.
+     */
+    by: readonly Expression[];
+}
+/**
+ * How wide a paper bridge may be for two held perforations to be one
+ * command. The T-98 punches a hold as a chain of round holes on a
+ * 2.66 mm grid with bridges of about a millimetre, so a scan read hole
+ * by hole shows a run where the paper shows one command.
+ */
+export declare const defaultChainGap: import("./Quantity").Quantity<"mm">;
+/**
+ * The position a bar reads its own command for the same function on,
+ * where it has no word for this one.
+ *
+ * A version keeps the perforations it does away with in its deletions,
+ * and those may be a scale the version is not coded for: a green
+ * version deletes the red `SlowCrescendoOn` it inherits. That has no
+ * position on the green bar, so drawing it as a perforation is out of
+ * the question, but an edit still has to be shown somewhere, and the
+ * lane the green scale gives the same function is where it belongs.
+ */
+export declare const positionOfSameFunction: (bar: TrackerBar, symbol: Expression) => Track | undefined;
+/**
+ * Where a held perforation of the newer version stands for a latched
+ * function of the older one: the same function, on the same side where
+ * the side counts, spanning the same stretch of the roll.
+ *
+ * Only unambiguous correspondences are reported. Where two held
+ * perforations answer one latched interval, or one answers two, none of
+ * them is reported and the editor is left to say what happened. Nothing
+ * is invented either: both sides are perforations somebody punched, and
+ * all this asserts is which stands for which.
+ */
+export declare const substitutionsBetween: (own: readonly AnySymbol[], inherited: readonly AnySymbol[], locate: Locate, tolerance?: CollationTolerance, chainGap?: Millimeters) => Substitution[];

package/lib/substitution.js

@@ -0,0 +1,175 @@
+import { defaultCollationTolerance } from "./Collation";
+import { distance, mm, track } from "./Quantity";
+/**
+ * What each Welte command operates.
+ *
+ * This cannot be read off the names. The T-100 latches a function on
+ * with one perforation and cancels it with a second, while the T-98
+ * holds it for as long as one perforation lasts (Hagmann pp. 89 f. and
+ * 100–103; Phillips p. 121), and Welte renamed two of the functions
+ * between the scales: the red `SlowCrescendo` is the green `Crescendo`,
+ * and the red's single `Forzando` valve answers to two green ones that
+ * name the end they pull towards. So the correspondence is stated here
+ * rather than derived, and only two commands that operate one function
+ * can stand for each other.
+ *
+ * The T-100's `MotorOn`/`MotorOff`, `Rewind` and `ElectricCutOff` are
+ * left out on purpose: the green scale has no word for any of them, its
+ * motor switch being an automatic mercury contact (Skala-Rolle 98 §12)
+ * and its rewind riding on the bass sforzando-piano line. A red command
+ * of those kinds has no counterpart and stays a plain deletion.
+ */
+const commands = {
+    MezzoforteOn: { operates: 'mezzoforte', spelling: 'on', sided: true },
+    MezzoforteOff: { operates: 'mezzoforte', spelling: 'off', sided: true },
+    SlowCrescendoOn: { operates: 'crescendo', spelling: 'on', sided: true },
+    SlowCrescendoOff: { operates: 'crescendo', spelling: 'off', sided: true },
+    ForzandoOn: { operates: 'sforzando', spelling: 'on', sided: true },
+    ForzandoOff: { operates: 'sforzando', spelling: 'off', sided: true },
+    SustainPedalOn: { operates: 'sustainPedal', spelling: 'on', sided: false },
+    SustainPedalOff: { operates: 'sustainPedal', spelling: 'off', sided: false },
+    SoftPedalOn: { operates: 'softPedal', spelling: 'on', sided: false },
+    SoftPedalOff: { operates: 'softPedal', spelling: 'off', sided: false },
+    Mezzoforte: { operates: 'mezzoforte', spelling: 'held', sided: true },
+    Crescendo: { operates: 'crescendo', spelling: 'held', sided: true },
+    SforzandoForte: { operates: 'sforzando', spelling: 'held', sided: true },
+    SforzandoPiano: { operates: 'sforzando', spelling: 'held', sided: true },
+    SustainPedal: { operates: 'sustainPedal', spelling: 'held', sided: false },
+    SoftPedal: { operates: 'softPedal', spelling: 'held', sided: false }
+};
+/** What a command operates, or nothing for a word no scale here knows. */
+export const commandOf = (expressionType) => commands[expressionType];
+/**
+ * How wide a paper bridge may be for two held perforations to be one
+ * command. The T-98 punches a hold as a chain of round holes on a
+ * 2.66 mm grid with bridges of about a millimetre, so a scan read hole
+ * by hole shows a run where the paper shows one command.
+ */
+export const defaultChainGap = mm(3);
+const isExpression = (symbol) => symbol.type === 'expression';
+/** The key a command is matched on: the function, and the side where the side counts. */
+const functionKey = (symbol, command) => command.sided ? `${command.operates} ${symbol.scope}` : command.operates;
+/**
+ * The position a bar reads its own command for the same function on,
+ * where it has no word for this one.
+ *
+ * A version keeps the perforations it does away with in its deletions,
+ * and those may be a scale the version is not coded for: a green
+ * version deletes the red `SlowCrescendoOn` it inherits. That has no
+ * position on the green bar, so drawing it as a perforation is out of
+ * the question, but an edit still has to be shown somewhere, and the
+ * lane the green scale gives the same function is where it belongs.
+ */
+export const positionOfSameFunction = (bar, symbol) => {
+    const wanted = commandOf(symbol.expressionType);
+    if (!wanted)
+        return undefined;
+    const positions = Array.from({ length: bar.trackCount }, (_, index) => track(index + 1));
+    return positions.find(position => {
+        const meaning = bar.meaningOf(position);
+        if (meaning?.type !== 'expression')
+            return false;
+        const command = commandOf(meaning.expressionType);
+        return command !== undefined
+            && command.operates === wanted.operates
+            && functionKey(meaning, command) === functionKey(symbol, wanted);
+    });
+};
+/**
+ * The intervals the older version latches: each perforation that turns
+ * a function on, with the one that cancels it next on the same line.
+ */
+const latchedIn = (symbols, locate) => {
+    const byFunction = new Map();
+    symbols.filter(isExpression).forEach(symbol => {
+        const command = commandOf(symbol.expressionType);
+        const at = locate(symbol)?.from;
+        if (!command || command.spelling === 'held' || at === undefined)
+            return;
+        const key = functionKey(symbol, command);
+        const group = byFunction.get(key) ?? [];
+        group.push({ symbol, at, spelling: command.spelling });
+        byFunction.set(key, group);
+    });
+    return [...byFunction.values()].flatMap(group => {
+        const inOrder = [...group].sort((a, b) => a.at - b.at);
+        return inOrder.reduce((state, entry) => {
+            // A second On while the function already stands is
+            // redundant, and the interval began at the first, which
+            // is how a red copy reads that reaches the end of the
+            // roll with two Ons and one Off.
+            if (entry.spelling === 'on') {
+                return state.open ? state : { ...state, open: { on: entry.symbol, from: entry.at } };
+            }
+            return state.open
+                ? {
+                    open: undefined,
+                    closed: [...state.closed, {
+                            on: state.open.on,
+                            off: entry.symbol,
+                            from: state.open.from,
+                            to: entry.at,
+                            key: functionKey(state.open.on, commandOf(state.open.on.expressionType))
+                        }]
+                }
+                : state;
+        }, { closed: [] }).closed;
+    });
+};
+/**
+ * The commands the newer version holds, a chain of punches counting as
+ * the one command the paper shows rather than as a run of them.
+ */
+const heldRunsIn = (symbols, locate, chainGap) => {
+    const byFunction = new Map();
+    symbols.filter(isExpression).forEach(symbol => {
+        const command = commandOf(symbol.expressionType);
+        const place = locate(symbol);
+        if (!command || command.spelling !== 'held' || !place)
+            return;
+        const key = functionKey(symbol, command);
+        const group = byFunction.get(key) ?? [];
+        group.push({ symbol, from: place.from, to: place.to });
+        byFunction.set(key, group);
+    });
+    return [...byFunction.entries()].flatMap(([key, group]) => [...group]
+        .sort((a, b) => a.from - b.from)
+        .reduce((runs, punch) => {
+        const open = runs[runs.length - 1];
+        if (open && punch.from - open.to <= chainGap) {
+            open.of.push(punch.symbol);
+            open.to = punch.to > open.to ? punch.to : open.to;
+            return runs;
+        }
+        return [...runs, { of: [punch.symbol], from: punch.from, to: punch.to, key }];
+    }, []));
+};
+/** The only item of the list, or nothing where there is none or a rival. */
+const theOnly = (items) => items.length === 1 ? items[0] : undefined;
+/**
+ * Where a held perforation of the newer version stands for a latched
+ * function of the older one: the same function, on the same side where
+ * the side counts, spanning the same stretch of the roll.
+ *
+ * Only unambiguous correspondences are reported. Where two held
+ * perforations answer one latched interval, or one answers two, none of
+ * them is reported and the editor is left to say what happened. Nothing
+ * is invented either: both sides are perforations somebody punched, and
+ * all this asserts is which stands for which.
+ */
+export const substitutionsBetween = (own, inherited, locate, tolerance = defaultCollationTolerance, chainGap = defaultChainGap) => {
+    const latched = latchedIn(inherited, locate);
+    const spans = (run, interval) => distance(run.from, interval.from) <= tolerance.toleranceStart
+        && distance(run.to, interval.to) <= tolerance.toleranceEnd;
+    const candidates = heldRunsIn(own, locate, chainGap).flatMap(run => {
+        const answered = latched.filter(interval => interval.key === run.key && spans(run, interval));
+        const only = theOnly(answered);
+        return only ? [{ run, interval: only }] : [];
+    });
+    // A latched interval two runs both answer is ambiguous from its side
+    // as well, so neither of them is reported.
+    const claims = candidates.reduce((counts, { interval }) => counts.set(interval.on.id, (counts.get(interval.on.id) ?? 0) + 1), new Map());
+    return candidates
+        .filter(({ interval }) => claims.get(interval.on.id) === 1)
+        .map(({ run, interval }) => ({ replaced: [interval.on, interval.off], by: run.of }));
+};

package/package.json

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