linked-rolls 0.46.0 → 0.47.0

package/README.md

@@ -143,17 +143,50 @@ and the onset alone 39, so neither test is idle, but a difference at the
 end is as often a punch measured badly as a punch genuinely prolonged,
 and the two are not worth confusing.
 
+## What a reader adds to a hole
+
+A copy read pneumatically rather than scanned reports how long a valve
+stayed open, and a valve is held on past the perforation that opened it,
+so its holes run longer than the punched slots while their onsets agree.
+Left in, that is not a difference between copies: a collation comparing
+such a copy's hole ends against a scanned copy's compares an on-time
+with a slot, and reads the one as a lengthening of the other.
+
+`shortenHoles` takes the extension off and records it on the copy,
+`revertShortening` puts it back, and `readFromPhillipsEroll` will take
+it off at import. Only holes are touched, what a writing spans being no
+valve. The figure is measured against the other copies rather than
+derived from the bar, since Phillips gives only the difference between
+two bars and not the absolute.
+
+On welte225.org that figure is about 1.6 mm, and its shape is simple. It
+does not grow with the length of the perforation: the ratio of the read
+length to the true one falls from 1.34 on the shortest punches to 1.01
+on the longest, which is what a constant added to everything does. There
+is no shortest on-time the valve cannot fall below. It shows no run
+along the roll, though one roll's span of paper speed is too narrow to
+tell a constant in millimetres from a constant in time. What it does
+vary with is the port that read it, by about half a millimetre either
+way and with no gradient across the bar, which is measured but too
+coarse to model from a single roll.
+
 ## Collating a derivation a second time
 
 A collated symbol is one symbol carrying every copy that reads it, so a
 collation cannot simply be run again: there is no second symbol left to
-match. `separateReadings` is the inverse. It takes one copy's carriers
-back off the symbols it shares, gives them to new symbols of the
+match. `separateReadings` is the inverse. It takes the carriers of one
+side back off the symbols it shares, gives them to new symbols of the
 version's own, and states the exchange, leaving the edition in the state
 a collation would have produced had nothing joined. `connectVersions` at
 a new tolerance then re-collates, joining again whatever the new window
 admits.
 
+It takes a side and not a copy, the same side `sidesOf` names and a
+window is measured over. Naming one copy of a side that has several does
+not separate that side: the rest of it stays behind on the other side's
+symbol, and a collation then compares one copy against that mixture
+rather than the two texts against each other.
+
 Nothing an editor established is lost by that. `connectVersions`
 rewrites only what a collation wrote (`isCollationsOwn`): a bare
 insertion or deletion, or an equivalence between two systems' spellings.

package/lib/RollCopy.d.ts

@@ -201,7 +201,7 @@ export interface RollCopy extends WithType<'RollCopy'>, WithId {
      * (e.g. 'shifted', 'stretched') to normalize measurements
      * for comparison with other copies. Not exported to RDF.
      */
-    ops: Array<'shifted' | 'stretched'>;
+    ops: Array<'shifted' | 'stretched' | 'shortened'>;
     /**
      * Physical measurements of this roll copy, including
      * dimensions, punch diameter, hole separation, margins,
@@ -258,6 +258,17 @@ export interface RollCopy extends WithType<'RollCopy'>, WithId {
          * Not exported to RDF.
          */
         scale: number;
+        /**
+         * How much longer this copy's reading of a hole ran than the
+         * perforation that caused it, where that was taken off the ends
+         * again. A pneumatic reader reports how long a valve stayed
+         * open, which exceeds the perforation that opened it, so its
+         * holes are overlong by a constant while its onsets agree.
+         * Nothing for a copy read by other means, whose holes are the
+         * punched slots themselves.
+         * Not exported to RDF.
+         */
+        readerExtension: Millimeters;
         /**
          * The resolution this copy's scan was read at, along the roll.
          * It is what the measurements given in pixels are to be read

package/lib/alignment.d.ts

@@ -9,6 +9,32 @@ export declare const applyScale: (factor: number, copy: RollCopy) => void;
 export declare const revertShift: (copy: RollCopy) => void;
 /** Takes the scale off the copy's features again, as far as one was applied. */
 export declare const revertScale: (copy: RollCopy) => void;
+/**
+ * Takes the extension a pneumatic reader adds off the ends of the
+ * copy's holes, and records how much was taken.
+ *
+ * Such a reader reports how long a valve stayed open, and a valve is
+ * held on past the perforation that opened it, so its holes run longer
+ * than the punched slots while their onsets agree. Left in, the
+ * difference is not a difference between copies at all: a collation
+ * comparing this copy's hole ends against a scanned copy's compares a
+ * pneumatic on-time with a punched slot, and reads the one as a
+ * lengthening of the other.
+ *
+ * The extension is a property of the reader rather than of the roll,
+ * and on the material measured so far it is a constant: it does not
+ * grow with the length of the perforation, there is no shortest
+ * on-time the valve cannot fall below, and it does not run along the
+ * roll with the paper speed as far as one roll can show. What it does
+ * vary with is the port that read it, by about half a millimetre either
+ * way and without any gradient across the bar, which is measured but
+ * too coarse to model from one roll.
+ *
+ * Only holes are touched. What a writing or a mark spans is no valve.
+ */
+export declare const shortenHoles: (extension: Millimeters, copy: RollCopy) => void;
+/** Puts the reader's extension back on the copy's holes, as far as one was taken off. */
+export declare const revertShortening: (copy: RollCopy) => void;
 /**
  * How a copy's places are carried onto another copy's:
  * `x_other = (x + shift) · scale`.

package/lib/alignment.js

@@ -1,6 +1,6 @@
 import { featuresOf } from "./RollCopy.js";
 import { welteT100 } from "./systems/welteT100/bar.js";
-import { add, mm, scale } from "./Quantity.js";
+import { add, mm, scale, subtract } from "./Quantity.js";
 /** Moves both ends of a span, the far end only where the span has one. */
 const move = (span, by) => {
     span.from = add(span.from, by);
@@ -54,6 +54,46 @@ export const revertScale = (copy) => {
     copy.ops = copy.ops.filter(op => op !== 'stretched');
     delete copy.measurements.scale;
 };
+const holesOf = (copy) => featuresOf(copy).filter(feature => feature.type === 'Hole');
+/**
+ * Takes the extension a pneumatic reader adds off the ends of the
+ * copy's holes, and records how much was taken.
+ *
+ * Such a reader reports how long a valve stayed open, and a valve is
+ * held on past the perforation that opened it, so its holes run longer
+ * than the punched slots while their onsets agree. Left in, the
+ * difference is not a difference between copies at all: a collation
+ * comparing this copy's hole ends against a scanned copy's compares a
+ * pneumatic on-time with a punched slot, and reads the one as a
+ * lengthening of the other.
+ *
+ * The extension is a property of the reader rather than of the roll,
+ * and on the material measured so far it is a constant: it does not
+ * grow with the length of the perforation, there is no shortest
+ * on-time the valve cannot fall below, and it does not run along the
+ * roll with the paper speed as far as one roll can show. What it does
+ * vary with is the port that read it, by about half a millimetre either
+ * way and without any gradient across the bar, which is measured but
+ * too coarse to model from one roll.
+ *
+ * Only holes are touched. What a writing or a mark spans is no valve.
+ */
+export const shortenHoles = (extension, copy) => {
+    if (copy.ops.includes('shortened'))
+        return;
+    holesOf(copy).forEach(hole => { hole.horizontal.to = subtract(hole.horizontal.to, extension); });
+    copy.ops = [...copy.ops, 'shortened'];
+    copy.measurements.readerExtension = extension;
+};
+/** Puts the reader's extension back on the copy's holes, as far as one was taken off. */
+export const revertShortening = (copy) => {
+    const extension = copy.measurements.readerExtension;
+    if (!copy.ops.includes('shortened') || extension === undefined)
+        return;
+    holesOf(copy).forEach(hole => { hole.horizontal.to = add(hole.horizontal.to, extension); });
+    copy.ops = copy.ops.filter(op => op !== 'shortened');
+    delete copy.measurements.readerExtension;
+};
 const byPlace = (x, y) => x.at - y.at || x.pitch - y.pitch;
 /** The notes the bar reads off the features, in the order they pass it. */
 const noteOnsets = (features, bar) => features

package/lib/editionOps.d.ts

@@ -8,6 +8,7 @@ import { GeneralRollCondition, ModificationPurpose, RollCopy, ScaleReading, Shif
 import { FeatureSource } from "./FeatureSource.js";
 import { AnyArgumentation, Belief, Certainty, ObjectAssumption } from "./Assumption.js";
 import { FeatureConditionAssignment, FeatureOrPatch, NestedFeature } from "./Feature.js";
+import { Millimeters } from "./Quantity.js";
 /**
  * A change to an edition, written onto an immer draft of it. One
  * operation is one undo step, so an operation that has to read the
@@ -40,6 +41,14 @@ export declare const alignCopy: (copyId: string, shift: Shift, scale: number, re
  * being a fact about the copy.
  */
 export declare const unalignCopy: (copyId: string) => EditionOp;
+/**
+ * Takes the extension a pneumatic reader adds off the ends of the
+ * copy's holes, and records how much was taken, so that its lengths
+ * can be compared with a scanned copy's at all.
+ */
+export declare const shortenCopy: (copyId: string, extension: Millimeters) => EditionOp;
+/** Puts the reader's extension back on the copy's holes. */
+export declare const unshortenCopy: (copyId: string) => EditionOp;
 /** States what the copy's features were read from, in place of any earlier statement. */
 export declare const stateSource: (copyId: string, source: FeatureSource) => EditionOp;
 /** Takes back the statement, leaving the copy silent about its source again. */
@@ -180,9 +189,9 @@ export declare const connectVersions: (view: EditionView, childId: string, paren
  */
 export declare const collateSymbols: (view: EditionView, versionId: string, symbolIds: readonly string[], tolerance?: CollationTolerance) => EditionOp;
 /**
- * Takes the copy's reading of a symbol back out of the symbol it was
- * collated into: the copy's carriers pass to a new symbol of the
- * version's own, the other copies keep the symbol they had, and the
+ * Takes the named copies' reading of a symbol back out of the symbol it
+ * was collated into: their carriers pass to a new symbol of the
+ * version's own, the remaining copies keep the symbol they had, and the
  * version states the exchange.
  *
  * This is the inverse of the hand-over a collation makes, and it is
@@ -191,12 +200,19 @@ export declare const collateSymbols: (view: EditionView, versionId: string, symb
  * takes the two readings apart again, and without that a tolerance
  * arrived at after the fact could never be applied.
  *
- * Symbols the copy alone carries are already the version's own and are
- * passed over, so a reading somebody has separated by hand keeps its
- * identifier and the edit that speaks for it. Named symbols narrow the
- * act to those; naming none separates the copy's whole reading.
+ * The copies named are one **side** of the derivation, the same side a
+ * window is measured over, and `sidesOf` is what says which they are.
+ * Naming one copy of a side that has several does not separate that
+ * side: what stays behind is the rest of it, mixed with the other
+ * side's copies, and a collation then compares one copy against that
+ * mixture rather than the two texts against each other.
+ *
+ * Symbols the named copies alone carry are already the version's own
+ * and are passed over, so a reading somebody has separated by hand
+ * keeps its identifier and the edit that speaks for it. Named symbols
+ * narrow the act to those; naming none separates the whole reading.
  */
-export declare const separateReadings: (view: EditionView, versionId: string, copyId: string, symbolIds?: readonly string[]) => EditionOp;
+export declare const separateReadings: (view: EditionView, versionId: string, copies: ReadonlySet<string>, symbolIds?: readonly string[]) => EditionOp;
 /**
  * Makes the version stand on its own: what it inherited becomes its
  * own insertions, and its derivations go, the hypotheses among them,

package/lib/editionOps.js

@@ -8,7 +8,7 @@ import { asSymbols, barOf, featuresByAct, featuresOf, isPaperStretch, statesNoth
 import { systemOf } from "./TrackerBar.js";
 import { substitutionsBetween } from "./substitution.js";
 import { trackerBarOf } from "./systems/index.js";
-import { applyShift, applyScale, revertShift, revertScale } from "./alignment.js";
+import { applyShift, applyScale, revertShift, revertScale, revertShortening, shortenHoles } from "./alignment.js";
 import { assignReference, idOf } from "./Assumption.js";
 import { conditions as conditionsAllowed, featuresBorneBy, isGluedOn, withBorneFeatures } from "./Feature.js";
 import { distance, mm, subtract } from "./Quantity.js";
@@ -125,6 +125,14 @@ export const unalignCopy = (copyId) => onCopy(copyId, copy => {
     revertShift(copy);
     copy.conditions = without(copy.conditions, isPaperStretch);
 });
+/**
+ * Takes the extension a pneumatic reader adds off the ends of the
+ * copy's holes, and records how much was taken, so that its lengths
+ * can be compared with a scanned copy's at all.
+ */
+export const shortenCopy = (copyId, extension) => onCopy(copyId, copy => shortenHoles(extension, copy));
+/** Puts the reader's extension back on the copy's holes. */
+export const unshortenCopy = (copyId) => onCopy(copyId, copy => revertShortening(copy));
 /** States what the copy's features were read from, in place of any earlier statement. */
 export const stateSource = (copyId, source) => onCopy(copyId, copy => {
     copy.readFrom = source;
@@ -778,16 +786,29 @@ const readingOf = (symbol, carriers) => {
     }
 };
 /** The symbol where the copy and at least one other carry it, with the carriers of each side. */
-const sharedWith = (view, symbol, copyId) => {
-    const onCopy = (carrier) => view.copyOf(idOf(carrier))?.id === copyId;
-    const mine = symbol.carriers.filter(onCopy);
-    const theirs = symbol.carriers.filter(carrier => !onCopy(carrier));
+/**
+ * The symbol where the named copies and at least one other carry it,
+ * with the carriers of each side.
+ *
+ * A symbol the named copies alone carry has no other side to be
+ * separated from and is passed over. That covers the insertions, and it
+ * covers a symbol an ancestor holds on one branch's witness alone,
+ * where the two versions do not disagree and there is nothing to take
+ * apart.
+ */
+const sharedWith = (view, symbol, copies) => {
+    const onNamedCopy = (carrier) => {
+        const copy = view.copyOf(idOf(carrier));
+        return copy !== undefined && copies.has(copy.id);
+    };
+    const mine = symbol.carriers.filter(onNamedCopy);
+    const theirs = symbol.carriers.filter(carrier => !onNamedCopy(carrier));
     return mine.length > 0 && theirs.length > 0 ? [{ symbol, mine, theirs }] : [];
 };
 /**
- * Takes the copy's reading of a symbol back out of the symbol it was
- * collated into: the copy's carriers pass to a new symbol of the
- * version's own, the other copies keep the symbol they had, and the
+ * Takes the named copies' reading of a symbol back out of the symbol it
+ * was collated into: their carriers pass to a new symbol of the
+ * version's own, the remaining copies keep the symbol they had, and the
  * version states the exchange.
  *
  * This is the inverse of the hand-over a collation makes, and it is
@@ -796,19 +817,26 @@ const sharedWith = (view, symbol, copyId) => {
  * takes the two readings apart again, and without that a tolerance
  * arrived at after the fact could never be applied.
  *
- * Symbols the copy alone carries are already the version's own and are
- * passed over, so a reading somebody has separated by hand keeps its
- * identifier and the edit that speaks for it. Named symbols narrow the
- * act to those; naming none separates the copy's whole reading.
+ * The copies named are one **side** of the derivation, the same side a
+ * window is measured over, and `sidesOf` is what says which they are.
+ * Naming one copy of a side that has several does not separate that
+ * side: what stays behind is the rest of it, mixed with the other
+ * side's copies, and a collation then compares one copy against that
+ * mixture rather than the two texts against each other.
+ *
+ * Symbols the named copies alone carry are already the version's own
+ * and are passed over, so a reading somebody has separated by hand
+ * keeps its identifier and the edit that speaks for it. Named symbols
+ * narrow the act to those; naming none separates the whole reading.
  */
-export const separateReadings = (view, versionId, copyId, symbolIds) => {
+export const separateReadings = (view, versionId, copies, symbolIds) => {
     const version = view.get(versionId);
     if (!version)
         return noChange;
     const chosen = symbolIds && new Set(symbolIds);
     const shared = view.snapshot(versionId)
         .filter(symbol => chosen === undefined || chosen.has(symbol.id))
-        .flatMap(symbol => sharedWith(view, symbol, copyId));
+        .flatMap(symbol => sharedWith(view, symbol, copies));
     if (shared.length === 0)
         return noChange;
     const inserted = new Set(insertedBy(version).map(symbol => symbol.id));

package/lib/readers/phillipsEroll.d.ts

@@ -20,16 +20,21 @@ import { Millimeters, Seconds } from "../Quantity.js";
  * perforation, the height of the tracker bar hole and the paper speed
  * (p. 180).
  *
- * That extension is not subtracted. Doing so would need the absolute
- * hole height of the Welte bar, where he gives only the 0.5 mm by which
- * it exceeds the Licensee's. So the end of a hole on this copy is a
- * pneumatic on-time where the end of a scanned copy's hole is a punched
- * slot, and the two are not the same quantity. It shows in a collation:
- * across welte225.org his notes run about 1.8 mm longer than the other
- * copies read them, while the onsets agree. Until it is corrected, a
- * comparison of hole ends against this copy measures the reader as much
- * as the roll, and `offsetEnd` on the derivation absorbs the systematic
- * part of it.
+ * Left in, that extension is not a difference between copies at all:
+ * the end of a hole here is a pneumatic on-time where the end of a
+ * scanned copy's hole is a punched slot, so a collation comparing the
+ * two reads the one as a lengthening of the other. `extension` takes it
+ * off at the end of every hole, and the copy records what was taken.
+ *
+ * How much to take off is measured rather than derived, since he gives
+ * only the 0.5 mm by which the Welte bar's holes exceed the Licensee's
+ * and not the absolute. Across welte225.org it comes to about 1.6 mm,
+ * and the shape of it is simple: a constant, not growing with the
+ * length of the perforation, with no shortest on-time the valve cannot
+ * fall below, and with no run along the roll that one roll's span of
+ * paper speed could show. The port that read it matters by about half a
+ * millimetre either way, without any gradient across the bar, which is
+ * measured but too coarse to model from one roll.
  */
 /**
  * He numbers his files by two rules at once, which his free samples
@@ -64,12 +69,25 @@ export interface PhillipsErollOptions {
      * account for it.
      */
     placeAt?: (elapsed: Seconds) => Millimeters;
+    /**
+     * How much longer a valve is held on than the perforation that
+     * opened it, taken off the end of every hole so that these lengths
+     * can be compared with a scanned copy's. Nothing leaves the holes
+     * as the reader reported them, which is what every copy read before
+     * this option existed states.
+     *
+     * The copy records what was taken, and `revertShortening` puts it
+     * back, so a figure revised later needs no second import. On
+     * welte225.org the extension measures about 1.6 mm, with no
+     * dependence on how long the perforation is.
+     */
+    extension?: Millimeters;
 }
 /**
  * Reads one of his e-roll files as a copy of the roll, in millimetres
  * of paper, on the bar it was cut for and in that bar's numbering. A
  * position the bar does not read is left out, as the bar would leave it.
  */
-export declare function readFromPhillipsEroll(buffer: ArrayBuffer, { system, controlOffset, placeAt }?: PhillipsErollOptions): RollCopy;
+export declare function readFromPhillipsEroll(buffer: ArrayBuffer, { system, controlOffset, placeAt, extension }?: PhillipsErollOptions): RollCopy;
 /** The bars his files are known to be numbered by. */
 export declare const phillipsSystems: readonly TrackerBar[];

package/lib/readers/phillipsEroll.js

@@ -2,6 +2,7 @@ import { read } from "midifile-ts";
 import { v4 } from "uuid";
 import { assignObject } from "../Assumption.js";
 import { systemOf } from "../TrackerBar.js";
+import { shortenHoles } from "../alignment.js";
 import { welteT100 } from "../systems/welteT100/bar.js";
 import { welteLicensee } from "../systems/welteLicensee/bar.js";
 import { inMetersPerMinute, mm, seconds, track } from "../Quantity.js";
@@ -24,16 +25,21 @@ import { inMetersPerMinute, mm, seconds, track } from "../Quantity.js";
  * perforation, the height of the tracker bar hole and the paper speed
  * (p. 180).
  *
- * That extension is not subtracted. Doing so would need the absolute
- * hole height of the Welte bar, where he gives only the 0.5 mm by which
- * it exceeds the Licensee's. So the end of a hole on this copy is a
- * pneumatic on-time where the end of a scanned copy's hole is a punched
- * slot, and the two are not the same quantity. It shows in a collation:
- * across welte225.org his notes run about 1.8 mm longer than the other
- * copies read them, while the onsets agree. Until it is corrected, a
- * comparison of hole ends against this copy measures the reader as much
- * as the roll, and `offsetEnd` on the derivation absorbs the systematic
- * part of it.
+ * Left in, that extension is not a difference between copies at all:
+ * the end of a hole here is a pneumatic on-time where the end of a
+ * scanned copy's hole is a punched slot, so a collation comparing the
+ * two reads the one as a lengthening of the other. `extension` takes it
+ * off at the end of every hole, and the copy records what was taken.
+ *
+ * How much to take off is measured rather than derived, since he gives
+ * only the 0.5 mm by which the Welte bar's holes exceed the Licensee's
+ * and not the absolute. Across welte225.org it comes to about 1.6 mm,
+ * and the shape of it is simple: a constant, not growing with the
+ * length of the perforation, with no shortest on-time the valve cannot
+ * fall below, and with no run along the roll that one roll's span of
+ * paper speed could show. The port that read it matters by about half a
+ * millimetre either way, without any gradient across the bar, which is
+ * measured but too coarse to model from one roll.
  */
 /**
  * He numbers his files by two rules at once, which his free samples
@@ -134,7 +140,7 @@ const positionsByPitch = (bar) => new Map(Array.from({ length: bar.trackCount },
  * of paper, on the bar it was cut for and in that bar's numbering. A
  * position the bar does not read is left out, as the bar would leave it.
  */
-export function readFromPhillipsEroll(buffer, { system = welteT100, controlOffset, placeAt } = {}) {
+export function readFromPhillipsEroll(buffer, { system = welteT100, controlOffset, placeAt, extension } = {}) {
     const file = read(new Uint8Array(buffer));
     const timed = onOneClock(file.tracks);
     const elapsedAt = clockOf(temposIn(timed), file.header.ticksPerBeat);
@@ -157,7 +163,7 @@ export function readFromPhillipsEroll(buffer, { system = welteT100, controlOffse
                 }
             }];
     });
-    return {
+    const copy = {
         type: 'RollCopy',
         id: v4(),
         ops: [],
@@ -171,6 +177,9 @@ export function readFromPhillipsEroll(buffer, { system = welteT100, controlOffse
             note: 'Read on Phillips’s pneumatic roll reader. The places are elapsed time put back onto the paper, and a hole runs as long as its switch stayed open, which is longer than the perforation.'
         }
     };
+    if (extension !== undefined)
+        shortenHoles(extension, copy);
+    return copy;
 }
 /** The bars his files are known to be numbered by. */
 export const phillipsSystems = [welteT100, welteLicensee];

package/lib/schema.json

@@ -2828,6 +2828,10 @@
                             "description": "The average diameter of punched holes.",
                             "ontology": "reo:punchDiameter"
                         },
+                        "readerExtension": {
+                            "$ref": "#/definitions/Millimeters",
+                            "description": "How much longer this copy's reading of a hole ran than the perforation that caused it, where that was taken off the ends again. A pneumatic reader reports how long a valve stayed open, which exceeds the perforation that opened it, so its holes are overlong by a constant while its onsets agree. Nothing for a copy read by other means, whose holes are the punched slots themselves. Not exported to RDF."
+                        },
                         "scale": {
                             "description": "The factor this copy's features were scaled by to align them with the others. What it is put down to is stated apart: a paper-stretch condition, or the speed the copy was cut for. Not exported to RDF.",
                             "type": "number"
@@ -2861,7 +2865,8 @@
                     "items": {
                         "enum": [
                             "shifted",
-                            "stretched"
+                            "stretched",
+                            "shortened"
                         ],
                         "type": "string"
                     },

package/lib/spec/context.json

@@ -151,6 +151,7 @@
             "@context": {
                 "shift": null,
                 "scale": null,
+                "readerExtension": null,
                 "trackCalibration": null,
                 "margins": null,
                 "dimensions": "reo:dimensions",

package/package.json

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