linked-rolls 0.0.1 → 0.1.0

package/lib/TrackCalibration.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Relates a scan to the tracker bar it was read with.
+ *
+ * Scanning 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.
+ *
+ *     column      = offset + scannerTrack * separation
+ *     trackerBar  = scannerTrack + shift
+ */
+export interface TrackCalibration {
+    unit: 'px';
+    /** Image column of the scanning software's track 0. */
+    offset: number;
+    /** Distance between the centres of adjacent tracks. */
+    separation: number;
+    /** Added to the scanning software's numbering to reach the tracker bar. */
+    shift: number;
+}
+/** Image column at the centre of a tracker bar track. */
+export declare const columnOf: (track: number, calibration: TrackCalibration) => number;
+/** Tracker bar track covering an image column, unrounded. */
+export declare const trackAt: (column: number, calibration: TrackCalibration) => number;
+/**
+ * The columns covered by a run of tracks, from the outer edge of the
+ * first to the outer edge of the last.
+ */
+export declare const columnsOf: (from: number, to: number, calibration: TrackCalibration) => {
+    from: number;
+    to: number;
+    width: number;
+};

package/lib/TrackCalibration.js

@@ -0,0 +1,14 @@
+/** Image column at the centre of a tracker bar track. */
+export const columnOf = (track, calibration) => calibration.offset + (track - calibration.shift) * calibration.separation;
+/** Tracker bar track covering an image column, unrounded. */
+export const trackAt = (column, calibration) => (column - calibration.offset) / calibration.separation + calibration.shift;
+/**
+ * The columns covered by a run of tracks, from the outer edge of the
+ * first to the outer edge of the last.
+ */
+export const columnsOf = (from, to, calibration) => {
+    const [lower, upper] = from <= to ? [from, to] : [to, from];
+    const start = columnOf(lower, calibration) - calibration.separation / 2;
+    const end = columnOf(upper, calibration) + calibration.separation / 2;
+    return { from: start, to: end, width: end - start };
+};

package/lib/TrackerBar.d.ts

@@ -1,8 +1,55 @@
 import { Expression, Note } from "./Symbol";
-export declare abstract class TrackerBar {
-    abstract meaningOf(track: number): Partial<Note> | Partial<Expression>;
+/**
+ * What a tracker bar position does: sound a note, or operate one of
+ * the expression valves on the bass or the treble side.
+ */
+export type TrackRole = 'bass-expression' | 'note' | 'treble-expression';
+/**
+ * A contiguous block of tracker bar positions serving one role.
+ * Both bounds are inclusive.
+ */
+export interface TrackArea {
+    readonly role: TrackRole;
+    readonly from: number;
+    readonly to: number;
 }
-export declare class WelteT100 {
-    meaningOf(track: number): Pick<Note, 'type' | 'pitch'> | Pick<Expression, 'type' | 'expressionType' | 'scope'>;
-    width: number;
+export type NoteMeaning = Pick<Note, 'type' | 'pitch'>;
+export type ExpressionMeaning = Pick<Expression, 'type' | 'expressionType' | 'scope'>;
+export type TrackMeaning = NoteMeaning | ExpressionMeaning;
+/**
+ * Describes a tracker bar. Track numbers are 1-based and count from
+ * the bass edge of the roll, which is the numbering used throughout
+ * the edition: a feature's `vertical.from` is a track in this sense.
+ *
+ * This is the only place where track numbers are given a meaning.
+ * Anything that needs to know where the note block ends, which side
+ * an expression belongs to, or how a track maps to a pitch, should
+ * ask the tracker bar rather than repeat the boundaries.
+ */
+export interface TrackerBar {
+    readonly name: string;
+    /** Width of the roll the bar reads, in mm. */
+    readonly width: number;
+    /** Number of positions on the bar. Tracks run from 1 to this. */
+    readonly trackCount: number;
+    /** The blocks of positions, from the bass edge upwards. */
+    readonly areas: readonly TrackArea[];
+    /**
+     * The position carrying the rewind perforation, which runs at
+     * the very end of a roll and is the usual landmark for calibrating
+     * a scan against the bar.
+     */
+    readonly rewindTrack: number;
+    /** `undefined` for a position the bar does not read. */
+    meaningOf(track: number): TrackMeaning | undefined;
+    /** `undefined` for a position the bar does not read. */
+    roleOf(track: number): TrackRole | undefined;
 }
+/**
+ * Welte-Mignon T-100 ("red Welte"), cf. Hagmann, pp. 75 and 178.
+ *
+ * The note block spans 80 positions from C1 to g⁴, i.e. MIDI 24 to 103.
+ * The expression valves are duplicated, bass below the note block and
+ * treble above it, in mirrored order.
+ */
+export declare const welteT100: TrackerBar;

package/lib/TrackerBar.js

@@ -1,53 +1,74 @@
-export class TrackerBar {
-}
-export class WelteT100 {
-    constructor() {
-        Object.defineProperty(this, "width", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: 328
-        }); // in mm, cf. Hagmann, p. 75
-    }
-    meaningOf(track) {
-        if (track <= 0 || track > 100) {
-            throw new Error('Track out of range');
-        }
-        // Cf. Hagmann, p. 178
-        const expressionMap = new Map([
-            [1, 'MezzoforteOff'],
-            [2, 'MezzoforteOn'],
-            [3, 'SlowCrescendoOff'],
-            [4, 'SlowCrescendoOn'],
-            [5, 'ForzandoOff'],
-            [6, 'ForzandoOn'],
-            [7, 'SoftPedalOff'],
-            [8, 'SoftPedalOn'],
-            [9, 'MotorOff'],
-            [10, 'MotorOn'],
-            [91, 'Rewind'],
-            [92, 'ElectricCutOff'],
-            [93, 'SustainPedalOn'],
-            [94, 'SustainPedalOff'],
-            [95, 'ForzandoOn'],
-            [96, 'ForzandoOff'],
-            [97, 'SlowCrescendoOn'],
-            [98, 'SlowCrescendoOff'],
-            [99, 'MezzoforteOn'],
-            [100, 'MezzoforteOff']
-        ]);
-        if (track <= 10 || track >= 91) {
-            const scope = track <= 10 ? 'bass' : 'treble';
+const areasOf = ({ notes, trackCount }) => [
+    { role: 'bass-expression', from: 1, to: notes.from - 1 },
+    { role: 'note', from: notes.from, to: notes.to },
+    { role: 'treble-expression', from: notes.to + 1, to: trackCount }
+];
+const scopeOf = (role) => role === 'bass-expression' ? 'bass' : 'treble';
+const describe = (spec) => {
+    const areas = areasOf(spec);
+    const roleOf = (track) => areas.find(area => track >= area.from && track <= area.to)?.role;
+    const meaningOf = (track) => {
+        const role = roleOf(track);
+        if (!role)
+            return undefined;
+        if (role === 'note') {
             return {
-                expressionType: expressionMap.get(track),
-                scope,
-                type: 'expression'
+                type: 'note',
+                pitch: track - spec.notes.from + spec.notes.lowestPitch
             };
         }
-        // C1-G4 = track 11-90 = 24-103 in MIDI keys
-        return {
-            pitch: track + 13,
-            type: 'note',
-        };
+        const expressionType = spec.expressions.get(track);
+        if (!expressionType)
+            return undefined;
+        return { type: 'expression', expressionType, scope: scopeOf(role) };
+    };
+    const rewindTrack = [...spec.expressions]
+        .find(([, type]) => type === 'Rewind')?.[0];
+    if (rewindTrack === undefined) {
+        throw new Error(`${spec.name} declares no rewind track`);
     }
-}
+    return {
+        name: spec.name,
+        width: spec.width,
+        trackCount: spec.trackCount,
+        areas,
+        rewindTrack,
+        meaningOf,
+        roleOf
+    };
+};
+/**
+ * Welte-Mignon T-100 ("red Welte"), cf. Hagmann, pp. 75 and 178.
+ *
+ * The note block spans 80 positions from C1 to g⁴, i.e. MIDI 24 to 103.
+ * The expression valves are duplicated, bass below the note block and
+ * treble above it, in mirrored order.
+ */
+export const welteT100 = describe({
+    name: 'Welte-Mignon T100',
+    width: 328,
+    trackCount: 100,
+    notes: { from: 11, to: 90, lowestPitch: 24 },
+    expressions: new Map([
+        [1, 'MezzoforteOff'],
+        [2, 'MezzoforteOn'],
+        [3, 'SlowCrescendoOff'],
+        [4, 'SlowCrescendoOn'],
+        [5, 'ForzandoOff'],
+        [6, 'ForzandoOn'],
+        [7, 'SoftPedalOff'],
+        [8, 'SoftPedalOn'],
+        [9, 'MotorOff'],
+        [10, 'MotorOn'],
+        [91, 'Rewind'],
+        [92, 'ElectricCutOff'],
+        [93, 'SustainPedalOn'],
+        [94, 'SustainPedalOff'],
+        [95, 'ForzandoOn'],
+        [96, 'ForzandoOff'],
+        [97, 'SlowCrescendoOn'],
+        [98, 'SlowCrescendoOff'],
+        [99, 'MezzoforteOn'],
+        [100, 'MezzoforteOff']
+    ])
+});

package/lib/Version.d.ts

@@ -1,42 +1,41 @@
-import { ActorAssignment, Edit } from "./Edit";
-import { EditorialAssumption, Motivation } from "./EditorialAssumption";
-import { AnySymbol } from "./Symbol";
-import { CollationTolerance } from "./Collation";
-export type Derivation = EditorialAssumption<'derivation', Version>;
-export declare const versionTypes: readonly ["edition", "authorised-revision", "unauthorised-revision", "gloss"];
+import { Edit } from "./Edit";
+import { ReferenceAssumption } from "./Assumption";
+import { WithId, WithNote, WithType } from "./utils";
+export declare const versionTypes: readonly ["edition", "unicum"];
+/**
+ * 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.
+ */
 export type VersionType = typeof versionTypes[number];
 /**
- * Version + Version Creation
+ * A motivation provides a reason or rationale for an editorial change.
+ * Motivations are defined at the version level and referenced by edits.
+ * @see crm:E73 Information Object
+ */
+export type Motivation = WithType<'motivation'> & WithId & WithNote;
+/**
+ * A version is defined by the sum of edits applied
+ * to the version it is based on. For simple identification,
+ * a siglum is given to each version.
  */
 export interface Version {
     id: string;
+    /**
+     * A short siglum to identify the version, e.g. "A", "B1", "B2_rev", etc.
+     */
     siglum: string;
-    actor?: ActorAssignment;
-    basedOn?: Derivation;
+    /**
+     * If no derivation is defined, it is assumed that this version represents the mother roll.
+     */
+    basedOn?: ReferenceAssumption;
+    /**
+     * The list of edits that, applied to the base version, produce this version.
+     */
     edits: Edit[];
-    motivations: Motivation<string>[];
+    /**
+     * A collection of motivations used in this version's edits.
+     */
+    motivations: Motivation[];
     type: VersionType;
 }
-export declare const traverseVersions: (version: Version, callback: (version: Version) => void) => void;
-export declare const getSnapshot: (version: Version) => AnySymbol[];
-/**
- * Walks through the versions. If it finds a symbol that is still
- * part of the tradition (i.e. it is included in the current snapshot)
- * and is equivalent with the given symbol, it will add the feature
- * carrying the symbol to the collated symbol. Otherwise, the
- * given symbol will be added to the current version's insertions.
- *
- * All symbols of the tradition that are not included in the given
- * symbols are considered to be deleted.
- *
- * @param creation
- * @param symbols
- * @returns
- */
-export declare function fillEdits(currentVersion: Version, symbols: AnySymbol[], tolerance?: CollationTolerance): void;
-/**
- * Assigns a generation (depth) to every node.
- */
-export declare function assignGenerations(versions: Version[]): Array<Version & {
-    generation: number;
-}>;

package/lib/Version.js

@@ -1,217 +1,11 @@
-import { v4 } from "uuid";
-import { flat } from "./EditorialAssumption";
-import { dimensionOf } from "./Symbol";
 export const versionTypes = [
     /**
-     * The roll is in a state where it is used as
+     * The roll is in a state where it is (possibly) used as
      * the master roll for several new reproductions.
      */
     'edition',
     /**
-     * This denotes a version which is specific to (early)
-     * Welte-Mignon piano rolls, where rolls inteded to
-     * be pulished are revised by a controller first. These
-     * rolls typically carry a "controlliert" stamp. The
-     * revision is done on the same date as the perforation
-     * and the date is written on the roll towards its end.
+     * A version that exists only on one specific copy of a roll.
      */
-    'authorised-revision',
-    /**
-     * Unauthorised revisions are those, which cannot be linked
-     * to a specific controller and are likely done by
-     * a later, anonymous hand.
-     */
-    'unauthorised-revision',
-    /**
-     * In the case of Welte Mignon rolls, glosses are
-     * typically comments about the roll's condition, added
-     * e.g. by the collector.
-     */
-    'gloss'
+    'unicum'
 ];
-export const traverseVersions = (version, callback) => {
-    callback(version);
-    if (version.basedOn) {
-        traverseVersions(flat(version.basedOn), callback);
-    }
-};
-export const getSnapshot = (version) => {
-    const snapshot = [];
-    const toDelete = [];
-    traverseVersions(version, s => {
-        snapshot.push(...s.edits.flatMap(edit => edit.insert || []));
-        // as we travel further up, remove symbols that are 
-        // deleted in the versions further down
-        const deleted = [];
-        for (const toRemove of toDelete) {
-            const index = snapshot.findIndex(s => s === toRemove);
-            if (index !== -1) {
-                snapshot.splice(index, 1);
-                deleted.push(toRemove);
-            }
-        }
-        for (const del of deleted) {
-            toDelete.splice(toDelete.indexOf(del), 1);
-        }
-        // collect symbols that are deleted in the current version
-        toDelete.push(...s.edits.flatMap(edit => edit.delete || []));
-    });
-    return snapshot.sort((a, b) => {
-        const aDimension = dimensionOf(a);
-        const bDimension = dimensionOf(b);
-        return aDimension.horizontal.from - bDimension.horizontal.from;
-    });
-};
-const isCollatable = (symbolA, symbolB, tolerance = {
-    toleranceEnd: 5,
-    toleranceStart: 5
-}) => {
-    // two symbols are collatible if they share the same 
-    // symbol characteristics (pitch, expression type etc.)
-    // and occur in the same horizontal position.
-    if (symbolA.type === 'note' && symbolB.type === 'note') {
-        if (symbolA.pitch !== symbolB.pitch)
-            return false;
-    }
-    else if (symbolA.type === 'expression' && symbolB.type === 'expression') {
-        if (symbolA.expressionType !== symbolB.expressionType)
-            return false;
-        if (symbolA.scope !== symbolB.scope)
-            return false;
-    }
-    const dimensionA = dimensionOf(symbolA);
-    const dimensionB = dimensionOf(symbolB);
-    const distanceStart = Math.abs(dimensionA.horizontal.from - dimensionB.horizontal.from);
-    const distanceEnd = Math.abs(dimensionA.horizontal.to - dimensionB.horizontal.to);
-    if (distanceStart > tolerance.toleranceStart
-        || distanceEnd > tolerance.toleranceEnd) {
-        // the symbols are too far apart to be collated
-        return false;
-    }
-    return true;
-};
-const overlaps = (a, b) => {
-    const overlapsDimension = (a, b) => (a.from ?? 0) < (b.to ?? Infinity) && (b.from ?? 0) < (a.to ?? Infinity);
-    return overlapsDimension(a.horizontal, b.horizontal) && overlapsDimension(a.vertical, b.vertical);
-};
-/**
- * Walks through the versions. If it finds a symbol that is still
- * part of the tradition (i.e. it is included in the current snapshot)
- * and is equivalent with the given symbol, it will add the feature
- * carrying the symbol to the collated symbol. Otherwise, the
- * given symbol will be added to the current version's insertions.
- *
- * All symbols of the tradition that are not included in the given
- * symbols are considered to be deleted.
- *
- * @param creation
- * @param symbols
- * @returns
- */
-export function fillEdits(currentVersion, symbols, tolerance = {
-    toleranceEnd: 5,
-    toleranceStart: 5
-}) {
-    const snapshot = getSnapshot(currentVersion);
-    const treatedSymbols = [];
-    // can it be collated with any of the symbols of 
-    // included in the current snapshot?
-    const insertions = [...symbols];
-    for (const symbol of symbols) {
-        snapshot
-            .filter(toCompare => isCollatable(symbol, toCompare, tolerance))
-            .forEach(corresp => {
-            corresp.carriers.push(...symbol.carriers);
-            insertions.splice(insertions.indexOf(symbol), 1);
-            treatedSymbols.push(corresp);
-        });
-    }
-    // special treatment for covers
-    const covers = insertions.filter(symbol => symbol.type === 'cover');
-    for (const cover of covers) {
-        // find perforations in the snapshot that 
-        // overlap with the cover
-        snapshot
-            .filter(symbol => symbol.type === 'note' || symbol.type === 'expression')
-            .map(dimensionOf)
-            .filter(dimension => overlaps(dimension, dimensionOf(cover)))
-            .forEach(dimension => {
-            const coverDimension = dimensionOf(cover);
-            // check if the cover partially covers the beginning
-            if (dimension.horizontal.from >= coverDimension.horizontal.from &&
-                dimension.horizontal.from <= coverDimension.horizontal.to) {
-                // the note starts where the cover ends
-                dimension.horizontal.from = coverDimension.horizontal.to;
-            }
-            // check if the cover partially covers the ending
-            if (dimension.horizontal.to >= coverDimension.horizontal.from &&
-                dimension.horizontal.to <= coverDimension.horizontal.to) {
-                // the note ends where the cover starts
-                dimension.horizontal.to = coverDimension.horizontal.from;
-            }
-        });
-        insertions.splice(insertions.indexOf(cover), 1);
-    }
-    currentVersion.edits.push(...insertions.map((symbol) => {
-        return {
-            insert: [symbol],
-            delete: [],
-            id: v4(),
-        };
-    }));
-    const deletions = snapshot.filter(sym => {
-        return !treatedSymbols.includes(sym);
-    });
-    for (const symbol of deletions) {
-        currentVersion.edits.push({
-            insert: [],
-            delete: [symbol],
-            id: v4(),
-        });
-    }
-}
-/**
- * Assigns a generation (depth) to every node.
- */
-export function assignGenerations(versions) {
-    const byId = new Map();
-    for (const n of versions)
-        byId.set(n.id, n);
-    const memo = new Map(); // id -> generation
-    const inStack = new Set(); // for cycle detection
-    const computeGen = (id) => {
-        if (memo.has(id))
-            return memo.get(id);
-        if (inStack.has(id)) {
-            throw new Error(`Cycle detected involving node '${id}'. Check parentId links.`);
-        }
-        const node = byId.get(id);
-        if (!node) {
-            // If you ever call computeGen on a missing id, treat as root.
-            memo.set(id, 0);
-            return 0;
-        }
-        inStack.add(id);
-        let gen;
-        const p = node.basedOn?.assigned.id;
-        if (p === undefined) {
-            gen = 0; // root
-        }
-        else if (!byId.has(p)) {
-            // Orphaned parent reference — treat boundary as root
-            gen = 0;
-        }
-        else {
-            gen = 1 + computeGen(p);
-        }
-        inStack.delete(id);
-        memo.set(id, gen);
-        return gen;
-    };
-    // Compute for all nodes (order doesn’t matter)
-    const withGen = versions.map(n => ({
-        ...n,
-        generation: computeGen(n.id),
-    }));
-    return withGen;
-}

package/lib/alignFeatures.d.ts

@@ -1,4 +1,5 @@
-import { RollFeature } from "./Feature";
+import { AnyFeature } from "./Feature";
+import { TrackerBar } from "./TrackerBar";
 type AlignmentResult = {
     shift: number;
     stretch: number;
@@ -7,5 +8,5 @@ type AlignmentResult = {
  * 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) * stretch.
  */
-export declare function alignFeatures(rollA: RollFeature[], rollB: RollFeature[]): AlignmentResult;
+export declare function alignFeatures(rollA: AnyFeature[], rollB: AnyFeature[], bar?: TrackerBar): AlignmentResult;
 export {};

package/lib/alignFeatures.js

@@ -1,6 +1,6 @@
-import { WelteT100 } from "./TrackerBar";
-const isNote = (feature) => {
-    return new WelteT100().meaningOf(feature.vertical.from).type === 'note';
+import { welteT100 } from "./TrackerBar";
+const isNoteOn = (bar) => (feature) => {
+    return feature.type === 'Hole' && bar.meaningOf(feature.vertical.from)?.type === 'note';
 };
 /**
  * Fit a line: position = alpha * index + beta via least squares.
@@ -33,8 +33,9 @@ function selectEnds(arr, count) {
  * 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) * stretch.
  */
-export function alignFeatures(rollA, rollB) {
+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)

package/lib/asJsonLd.d.ts

@@ -1,3 +1,3 @@
 import { Edition } from "./Edition";
-export declare const referenceTypes: string[];
+export declare const exportDate: (date: Date) => string;
 export declare const asJsonLd: (edition: Edition) => any;

package/lib/asJsonLd.js

@@ -1,13 +1,8 @@
-import { exportDate } from "./importJsonLd";
-// for these keys, references by id will be inserted
-// rather than the object itself.
-export const referenceTypes = [
-    'premises',
-    'delete',
-    'comprehends'
-];
-const asIDArray = (arr) => {
-    return arr.map(e => e.id);
+export const exportDate = (date) => {
+    const year = date.getFullYear();
+    const month = String(date.getMonth() + 1).padStart(2, "0");
+    const day = String(date.getDate()).padStart(2, "0");
+    return `${year}-${month}-${day}`;
 };
 const asJsonLdEntity = (obj) => {
     if (obj instanceof Date) {
@@ -21,19 +16,6 @@ const asJsonLdEntity = (obj) => {
         if (typeof value === 'function' || typeof value === 'undefined') {
             // ignore
         }
-        else if (referenceTypes.includes(key)) {
-            if (!Array.isArray(value)) {
-                console.error(`Expected array for key ${key}, got ${value}`);
-            }
-            else {
-                result[key] = asIDArray(value);
-            }
-        }
-        else if (key === 'assigned'
-            && (result['@type'] === 'derivation'
-                || result['@type'] === 'carrierAssignment')) {
-            result['assigned'] = value.id;
-        }
         else if (key === 'type') {
             result['@type'] = value;
         }
@@ -53,7 +35,8 @@ const asJsonLdEntity = (obj) => {
     return result;
 };
 export const asJsonLd = (edition) => {
-    const result = {
+    const { base, copies, ...rest } = asJsonLdEntity(edition);
+    return {
         '@context': [
             'https://linked-rolls.org/rollo/1.0/edition.jsonld',
             {
@@ -61,7 +44,11 @@ export const asJsonLd = (edition) => {
             }
         ],
         '@type': "Edition",
-        ...asJsonLdEntity(edition)
+        '@id': edition.base,
+        ...rest,
+        copies: copies?.map(copy => ({
+            ...copy,
+            '@id': `copy/${copy['@id']}`
+        }))
     };
-    return result;
 };

package/lib/importJsonLd.d.ts

@@ -1,4 +1,3 @@
 import { Edition } from "./Edition";
-export declare const exportDate: (date: Date) => string;
 export declare const importDate: (str: string) => Date;
 export declare const importJsonLd: (json: any) => Edition;