linked-rolls 0.12.0 → 0.13.0

package/lib/alignment.d.ts

@@ -9,14 +9,27 @@ 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;
-type AlignmentResult = {
+/**
+ * How a copy's places are carried onto another copy's:
+ * `x_other = (x + shift) · scale`.
+ */
+export interface AlignmentResult {
     /** Applied before the scale. */
     shift: Millimeters;
     scale: number;
-};
+    /** The notes of the copy that found their counterpart on the other. */
+    matched: number;
+    /** How far the counterparts still lie apart, as a root mean square in the other copy's millimetres. */
+    residual: Millimeters;
+}
 /**
- * Align two rolls by computing independent linear fits of each roll's note-onset positions
- * using only the first and last segments, then deriving a transform x2 = (x1 + shift) * scale.
+ * Finds the shift and scale that carry the places of `rollA` onto those
+ * of `rollB`, reading both through the bar. Runs of pitches that occur
+ * once on each roll anchor a first line; then every note is paired with
+ * its nearest counterpart of the same pitch and the line refitted, the
+ * window closing each time. A copy cut for another paper speed, a scan
+ * with a calibration pattern, and holes the other copy lacks are all
+ * within reach of that. Nothing is found where the rolls share no run of
+ * pitches, as between two different pieces.
  */
-export declare function alignFeatures(rollA: AnyFeature[], rollB: AnyFeature[], bar?: TrackerBar): AlignmentResult;
-export {};
+export declare function alignFeatures(rollA: readonly AnyFeature[], rollB: readonly AnyFeature[], bar?: TrackerBar): AlignmentResult | undefined;

package/lib/alignment.js

@@ -53,57 +53,125 @@ export const revertScale = (copy) => {
     copy.ops = copy.ops.filter(op => op !== 'stretched');
     delete copy.measurements.scale;
 };
-const isNoteOn = (bar) => (feature) => {
-    return feature.type === 'Hole' && bar.meaningOf(feature.vertical.from)?.type === 'note';
+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
+    .flatMap((feature) => {
+    if (feature.type !== 'Hole')
+        return [];
+    const meaning = bar.meaningOf(feature.vertical.from);
+    return meaning?.type === 'note' ? [{ pitch: meaning.pitch, at: feature.horizontal.from }] : [];
+})
+    .sort(byPlace);
+const median = (values) => {
+    const sorted = [...values].sort((x, y) => x - y);
+    return sorted[Math.floor(sorted.length / 2)] ?? 0;
 };
+/** The slope of the line through two matches, or nothing where they share a place on the copy. */
+const slopeBetween = (m, n) => n.a === m.a ? [] : [(n.b - m.b) / (n.a - m.a)];
+/** Matches beyond this are thinned before the slopes are taken, whose number grows with the square. */
+const SLOPE_SAMPLE = 1500;
 /**
- * Fit a line: position = alpha * index + beta via least squares.
+ * The line of the median slope and the median intercept, after Theil
+ * and Sen. A minority of matches at odds with the rest, as from a
+ * passage the copy retimes or from an anchor set by chance, leaves it
+ * unmoved, where a least-squares line would tilt towards them.
  */
-function fitIndexToPosition(indices, positions) {
-    const n = indices.length;
-    const meanIdx = indices.reduce((s, i) => s + i, 0) / n;
-    const meanPos = positions.reduce((s, p) => s + p, 0) / n;
-    let num = 0;
-    let den = 0;
-    for (let i = 0; i < n; i++) {
-        const d = indices[i] - meanIdx;
-        num += d * (positions[i] - meanPos);
-        den += d * d;
+const robustLine = (matches) => {
+    const step = Math.max(1, Math.ceil(matches.length / SLOPE_SAMPLE));
+    const sample = matches.filter((_, i) => i % step === 0);
+    const slopes = sample.flatMap((m, i) => sample.slice(i + 1).flatMap(n => slopeBetween(m, n)));
+    if (slopes.length === 0)
+        return undefined;
+    const slope = median(slopes);
+    return { slope, intercept: median(matches.map(m => m.b - slope * m.a)) };
+};
+const placed = (line, a) => line.slope * a + line.intercept;
+const residualOf = (line, match) => match.b - placed(line, match.a);
+/** Pitches in a row that pin down a place on a roll, provided the row occurs once. */
+const ANCHOR_LENGTH = 6;
+/** Every run of `length` pitches, keyed by the run, with the onsets it starts at. */
+const runsOf = (onsets, length) => {
+    const runs = new Map();
+    onsets.slice(0, Math.max(0, onsets.length - length + 1)).forEach((start, i) => {
+        const key = onsets.slice(i, i + length).map(onset => onset.pitch).join(',');
+        runs.set(key, [...(runs.get(key) ?? []), start]);
+    });
+    return runs;
+};
+/** The places a run of pitches found once on each roll ties together. */
+const anchors = (a, b) => {
+    const runsB = runsOf(b, ANCHOR_LENGTH);
+    return [...runsOf(a, ANCHOR_LENGTH)]
+        .flatMap(([key, starts]) => {
+        const others = runsB.get(key);
+        return starts.length === 1 && others?.length === 1
+            ? [{ a: starts[0].at, b: others[0].at }]
+            : [];
+    });
+};
+/** Takes the candidates nearest first, each onset going into one pair only. */
+const pairedNearestFirst = (candidates) => {
+    const taken = new Set();
+    const matches = [];
+    for (const candidate of [...candidates].sort((x, y) => x.distance - y.distance)) {
+        if (taken.has(candidate.a) || taken.has(candidate.b))
+            continue;
+        taken.add(candidate.a);
+        taken.add(candidate.b);
+        matches.push({ a: candidate.a.at, b: candidate.b.at });
     }
-    const alpha = den === 0 ? 1 : num / den;
-    const beta = meanPos - alpha * meanIdx;
-    return { alpha, beta };
-}
+    return matches;
+};
+/** Each onset of A paired with the nearest onset of B of its pitch within the window around where the line puts it. */
+const nearestMatches = (a, b, line, window) => {
+    const bByPitch = new Map();
+    b.forEach(onset => bByPitch.set(onset.pitch, [...(bByPitch.get(onset.pitch) ?? []), onset]));
+    const candidates = a.flatMap(onset => {
+        const expected = placed(line, onset.at);
+        return (bByPitch.get(onset.pitch) ?? [])
+            .map(other => ({ distance: Math.abs(other.at - expected), a: onset, b: other }))
+            .filter(candidate => candidate.distance <= window);
+    });
+    return pairedNearestFirst(candidates);
+};
 /**
- * Selects the first and last N elements of an array (or fewer if length is smaller).
+ * Windows, in the other roll's millimetres, narrowed as the line settles.
+ * The first is wide enough to catch what a line extrapolated from the
+ * anchors misses at the ends of a long roll; the last is narrow enough
+ * to leave out a passage the copy retimed.
  */
-function selectEnds(arr, count) {
-    const n = arr.length;
-    if (count * 2 >= n)
-        return arr.slice();
-    return arr.slice(0, count).concat(arr.slice(n - count, n));
-}
+const WINDOWS = [mm(40), mm(15), mm(6)];
+const settled = (a, b) => (fit, window) => {
+    const matches = nearestMatches(a, b, fit.line, window);
+    return { line: robustLine(matches) ?? fit.line, matches };
+};
+const resultOf = ({ line, matches }) => {
+    if (matches.length < 2 || line.slope <= 0)
+        return undefined;
+    const squares = matches.reduce((total, m) => total + residualOf(line, m) ** 2, 0);
+    return {
+        shift: mm(line.intercept / line.slope),
+        scale: line.slope,
+        matched: matches.length,
+        residual: mm(Math.sqrt(squares / matches.length))
+    };
+};
 /**
- * Align two rolls by computing independent linear fits of each roll's note-onset positions
- * using only the first and last segments, then deriving a transform x2 = (x1 + shift) * scale.
+ * Finds the shift and scale that carry the places of `rollA` onto those
+ * of `rollB`, reading both through the bar. Runs of pitches that occur
+ * once on each roll anchor a first line; then every note is paired with
+ * its nearest counterpart of the same pitch and the line refitted, the
+ * window closing each time. A copy cut for another paper speed, a scan
+ * with a calibration pattern, and holes the other copy lacks are all
+ * within reach of that. Nothing is found where the rolls share no run of
+ * pitches, as between two different pieces.
  */
 export function alignFeatures(rollA, rollB, bar = welteT100) {
-    // 1. Extract note-onset positions
-    const isNote = isNoteOn(bar);
-    const allXA = rollA.filter(isNote).map(f => f.horizontal.from);
-    const allXB = rollB.filter(isNote).map(f => f.horizontal.from);
-    // 2. Determine segment size (e.g. 10% of notes, min 5)
-    const segCount = Math.max(5, Math.floor(allXA.length * 0.1));
-    // 3. Select only first and last segments
-    const XA = selectEnds(allXA, segCount);
-    const idxA = XA.map((_, i) => i);
-    const XB = selectEnds(allXB, segCount);
-    const idxB = XB.map((_, i) => i);
-    // 4. Fit index->position for each roll on selected ends
-    const { alpha: alphaA, beta: betaA } = fitIndexToPosition(idxA, XA);
-    const { alpha: alphaB, beta: betaB } = fitIndexToPosition(idxB, XB);
-    // 5. Derive scale and shift such that x2 = (x1 + shift) * scale
-    const scale = alphaB / alphaA;
-    const shift = mm(betaB / scale - betaA);
-    return { scale, shift };
+    const a = noteOnsets(rollA, bar);
+    const b = noteOnsets(rollB, bar);
+    const coarse = robustLine(anchors(a, b));
+    if (!coarse)
+        return undefined;
+    return resultOf(WINDOWS.reduce(settled(a, b), { line: coarse, matches: [] }));
 }

package/package.json

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