linked-rolls 0.5.0 → 0.6.0

package/README.md

@@ -49,10 +49,13 @@ take-up spool sets the time axis, the Nuancierbälge fill through their
 conduits and are arrested by the Mezzoforte pin, and the two pedals travel
 rather than switch. The constants are those fitted against the hand-drawn
 nuance lines of roll 3309, with the terms that describe the drawing
-apparatus switched off. What the emulator does not determine is how
-bellows travel maps onto MIDI velocity; `WelteT100Options.velocity`
-anchors that map at the open rail, the Mezzoforte pin and the closed rail,
-and its defaults are midi2exp's.
+apparatus switched off. The pedals leave no drawn line, so their constants
+come as two readings, `pedalPresets.damping`, under which every lift the
+rolls punch damps, and `pedalPresets.brushing`, under which the quick runs
+of latch changes brush the strings without damping. What the emulator does
+not determine is how bellows travel maps onto MIDI velocity;
+`WelteT100Options.velocity` anchors that map at the open rail, the
+Mezzoforte pin and the closed rail, and its defaults are midi2exp's.
 
 ```ts
 import { Emulation } from 'linked-rolls'

package/lib/Agent.d.ts

@@ -0,0 +1,59 @@
+import { WithId } from "./utils";
+/**
+ * Something with a name and, where one exists, an authority record.
+ */
+export interface Named {
+    /**
+     * The name, e.g. "Grünfeld, Alfred", "Wien", "M. Welte & Söhne".
+     * @see rdfs:label
+     */
+    name: string;
+    /**
+     * Authority records for the same thing: GND, Wikidata,
+     * geonames or similar.
+     * @see owl:sameAs
+     * @example "https://d-nb.info/gnd/116888652"
+     */
+    sameAs: string[];
+}
+export declare const agentRoles: readonly ["pianist", "editor", "publisher"];
+/**
+ * The role an agent plays in the context of the edition.
+ */
+export type AgentRole = typeof agentRoles[number];
+/**
+ * A person or a group: a pianist, an editor, a publisher,
+ * a manufacturer, a library.
+ * @see crm:E39 Actor
+ */
+export interface Agent extends Named, Partial<WithId> {
+    /**
+     * The role of the agent in the context of the edition.
+     * @see crm:P2 has type
+     */
+    role?: AgentRole;
+}
+/**
+ * An agent that is a person.
+ */
+export type Person = Agent;
+export type WithActor = {
+    /**
+     * The person who carried out this activity.
+     * @see crm:P14 carried out by
+     */
+    actor?: Person;
+};
+/**
+ * A place, e.g. a recording location, publishing location, etc.
+ * @see crm:E53 Place
+ */
+export interface Place extends Named {
+}
+/**
+ * A term from a vocabulary, such as a roll system or a kind of
+ * paper. A term the type vocabulary knows carries its IRI as `id`.
+ * @see crm:E55 Type
+ */
+export interface Concept extends Named, Partial<WithId> {
+}

package/lib/Agent.js

@@ -0,0 +1 @@
+export const agentRoles = ['pianist', 'editor', 'publisher'];

package/lib/Assumption.d.ts

@@ -1,4 +1,5 @@
-import { WithActor, WithNote, WithId } from "./utils";
+import { WithNote, WithId } from "./utils";
+import { Person, WithActor } from "./Agent";
 export declare const certainties: readonly ["true", "likely", "possible", "unlikely", "false"];
 /**
  * Certainty levels for beliefs, ranging from 'true' to 'false'
@@ -120,6 +121,23 @@ export type ReferenceAssumption = Assumption & WithId;
  * may be uncertain.
  */
 export type ObjectAssumption<O extends object> = Assumption & O;
+/**
+ * An actor assignment associates a person with an action.
+ * It is an object assumption so that the attribution can be
+ * annotated with a belief about its certainty.
+ */
+export type ActorAssignment = ObjectAssumption<Person>;
+/**
+ * A date value wrapped as an assumption, so that the date
+ * can be annotated with a belief about its certainty and source.
+ */
+export type DateAssignment = ValueAssumption<Date> & {
+    /**
+     * The datatype of the value. Written on export so that
+     * RDF reads the value as a date rather than a string.
+     */
+    '@type'?: 'xsd:date';
+};
 export declare function valueOf<ValueT>(assumption: ValueAssumption<ValueT>): ValueT;
 export declare function valuesOf<ValueT>(assumptions: ValueAssumption<ValueT>[]): ValueT[];
 export declare function idOf(assumption: ReferenceAssumption): string;

package/lib/Collation.d.ts

@@ -1,3 +1,5 @@
+import { HorizontalSpan } from "./Feature";
+import { AnySymbol } from "./Symbol";
 /**
  * Tolerance used in collation of roll copies.
  * The start and end tolerances define the acceptable
@@ -13,3 +15,20 @@ export interface CollationTolerance {
      */
     toleranceEnd: number;
 }
+export declare const defaultCollationTolerance: CollationTolerance;
+/** Where a symbol lies along the roll, as its carriers put it, or nothing for a symbol without a place. */
+export type Locate = (symbol: AnySymbol) => Readonly<{
+    horizontal: HorizontalSpan;
+}> | undefined;
+/**
+ * Two symbols collate when they are of one kind, say the same thing
+ * (pitch, or expression type and scope), and lie at about the same
+ * place along the roll.
+ */
+export declare const isCollatable: (a: AnySymbol, b: AnySymbol, locate: Locate, tolerance?: CollationTolerance) => boolean;
+export type Collation = {
+    symbol: Readonly<AnySymbol>;
+    counterpart: Readonly<AnySymbol>;
+};
+/** Each of the own symbols with every inherited symbol it collates with. */
+export declare const collationsOf: (own: readonly Readonly<AnySymbol>[], inherited: readonly Readonly<AnySymbol>[], locate: Locate, tolerance?: CollationTolerance) => Collation[];

package/lib/Collation.js

@@ -1 +1,25 @@
-export {};
+export const defaultCollationTolerance = { toleranceStart: 5, toleranceEnd: 5 };
+/**
+ * Two symbols collate when they are of one kind, say the same thing
+ * (pitch, or expression type and scope), and lie at about the same
+ * place along the roll.
+ */
+export const isCollatable = (a, b, locate, tolerance = defaultCollationTolerance) => {
+    if (a.type !== b.type)
+        return false;
+    if (a.type === 'note' && b.type === 'note' && a.pitch !== b.pitch)
+        return false;
+    if (a.type === 'expression' && b.type === 'expression'
+        && (a.expressionType !== b.expressionType || a.scope !== b.scope))
+        return false;
+    const here = locate(a)?.horizontal;
+    const there = locate(b)?.horizontal;
+    if (!here || !there)
+        return false;
+    return Math.abs(here.from - there.from) <= tolerance.toleranceStart
+        && Math.abs(here.to - there.to) <= tolerance.toleranceEnd;
+};
+/** Each of the own symbols with every inherited symbol it collates with. */
+export const collationsOf = (own, inherited, locate, tolerance = defaultCollationTolerance) => own.flatMap(symbol => inherited
+    .filter(candidate => isCollatable(symbol, candidate, locate, tolerance))
+    .map(counterpart => ({ symbol, counterpart })));

package/lib/Edit.d.ts

@@ -1,5 +1,4 @@
-import { Assumption, ObjectAssumption } from "./Assumption";
-import { Person } from "./Edition";
+import { Assumption } from "./Assumption";
 import { AnySymbol } from "./Symbol";
 import { WithId } from "./utils";
 export declare const editTypes: readonly ["short-dynamic-differentation", "additional-accent", "add-redundancy", "remove-redundancy", "replace-with-equivalent", "shift", "correct-error", "shorten", "prolong"];
@@ -9,12 +8,6 @@ export declare const editTypes: readonly ["short-dynamic-differentation", "addit
  * adds an accent, shifts a note, or shortens/prolongs a perforation.
  */
 export type EditType = typeof editTypes[number];
-/**
- * An actor assignment associates a person with an action.
- * It is an object assumption so that the attribution can be
- * annotated with a belief about its certainty.
- */
-export type ActorAssignment = ObjectAssumption<Person>;
 /**
  * A set of edits transforms a version of a roll into another version.
  * Edits insert or delete symbols, or both (= replace).

package/lib/Edition.d.ts

@@ -1,59 +1,9 @@
-import { WithId } from "./utils";
-import { DateAssignment, RollCopy } from "./RollCopy";
+import { RollCopy } from "./RollCopy";
 import { Version } from "./Version";
 import { CollationTolerance } from "./Collation";
-import { ObjectAssumption } from "./Assumption";
-/**
- * Something with a name and, where one exists, an authority record.
- */
-export interface Named {
-    /**
-     * The name, e.g. "Grünfeld, Alfred", "Wien", "M. Welte & Söhne".
-     * @see rdfs:label
-     */
-    name: string;
-    /**
-     * Authority records for the same thing: GND, Wikidata,
-     * geonames or similar.
-     * @see owl:sameAs
-     * @example "https://d-nb.info/gnd/116888652"
-     */
-    sameAs: string[];
-}
-export declare const agentRoles: readonly ["pianist", "editor", "publisher"];
-/**
- * The role an agent plays in the context of the edition.
- */
-export type AgentRole = typeof agentRoles[number];
-/**
- * A person or a group: a pianist, an editor, a publisher,
- * a manufacturer, a library.
- * @see crm:E39 Actor
- */
-export interface Agent extends Named, Partial<WithId> {
-    /**
-     * The role of the agent in the context of the edition.
-     * @see crm:P2 has type
-     */
-    role?: AgentRole;
-}
-/**
- * An agent that is a person.
- */
-export type Person = Agent;
-/**
- * A place, e.g. a recording location, publishing location, etc.
- * @see crm:E53 Place
- */
-export interface Place extends Named {
-}
-/**
- * A term from a vocabulary, such as a roll system or a kind of
- * paper. A term the type vocabulary knows carries its IRI as `id`.
- * @see crm:E55 Type
- */
-export interface Concept extends Named, Partial<WithId> {
-}
+import { DateAssignment, ObjectAssumption } from "./Assumption";
+import { Concept, Person, Place } from "./Agent";
+import { RollTempo } from "./ReproducingSystem";
 /**
  * This type describes the creation of an edition,
  * i.e. the editor, publisher, and publication date.
@@ -147,29 +97,6 @@ export interface Roll {
      */
     recordingEvent: RecordingEvent;
 }
-/**
- * The playback tempo of the roll, specified as a starting
- * and ending speed. The tempo may change over the course
- * of the roll due to acceleration effects.
- * @see crm:E54 Dimension
- */
-export interface RollTempo {
-    /**
-     * The tempo at the beginning of the roll.
-     * @see reo:from
-     */
-    startsWith: number;
-    /**
-     * The tempo at the end of the roll.
-     * @see reo:to
-     */
-    endsWith: number;
-    /**
-     * The unit of the tempo measurement (e.g. 'ft/min', 'm/min').
-     * @see crm:P91 has unit
-     */
-    unit: string;
-}
 /**
  * Describes the specific digital edition of a piano roll.
  * @see lrmoo:F2 Expression

package/lib/Edition.js

@@ -1 +1 @@
-export const agentRoles = ['pianist', 'editor', 'publisher'];
+export {};

package/lib/EditionView.d.ts

@@ -1,4 +1,3 @@
-import { CollationTolerance } from "./Collation";
 import { Edition } from "./Edition";
 import { HorizontalSpan, VerticalSpan, AnyFeature } from "./Feature";
 import { AnySymbol, Expression, Note } from "./Symbol";
@@ -20,11 +19,6 @@ export declare class EditionView {
      * Map from id to paths where it is referenced
      */
     private readonly links;
-    /**
-     * Dimensions cache: one frequent operation is to find the average
-     * dimensions of a symbol based on its carriers. This cache stores
-     * the computed dimensions for reuse.
-     */
     constructor(edition: Edition);
     atPath<T>(path: Path): T | null;
     indexObjects(): void;
@@ -40,7 +34,6 @@ export declare class EditionView {
         vertical: VerticalSpan;
     }> | undefined;
     snapshot(versionId: string): readonly Readonly<AnySymbol>[];
-    isCollatable(symbolA: AnySymbol, symbolB: AnySymbol, tolerance?: CollationTolerance): boolean;
     /**
      * Assigns a generation (depth) to every node.
      */

package/lib/EditionView.js

@@ -14,12 +14,6 @@ const referenceKeys = new Set([
     'motivation'
 ]);
 export class EditionView {
-    /**
-     * Dimensions cache: one frequent operation is to find the average
-     * dimensions of a symbol based on its carriers. This cache stores
-     * the computed dimensions for reuse.
-     */
-    //private readonly dimensionsCache: Map<string, { horizontal: HorizontalSpan, vertical: VerticalSpan }> = new Map()
     constructor(edition) {
         Object.defineProperty(this, "edition", {
             enumerable: true,
@@ -56,18 +50,7 @@ export class EditionView {
         });
         this.edition = edition;
         this.indexObjects();
-        //this.buildDimensionsCache()
     }
-    // private buildDimensionsCache() {
-    //     for (const version of this.edition.versions) {
-    //         for (const symbol of version.edits.flatMap(edit => edit.insert || [])) {
-    //             const dim = this.dimensionOf(symbol)
-    //             if (dim) {
-    //                 this.dimensionsCache.set(symbol.id, dim)
-    //             }
-    //         }
-    //     }
-    // }
     atPath(path) {
         const node = getAt(path, this.edition);
         return node || null;
@@ -163,9 +146,6 @@ export class EditionView {
         return this.get(idOf(v.basedOn));
     }
     dimensionOf(symbol) {
-        // if (this.dimensionsCache.has(symbol.id)) {
-        //     return this.dimensionsCache.get(symbol.id);
-        // }
         const carriers = this.getAll(idsOf(symbol.carriers));
         if (carriers.length === 0) {
             return;
@@ -211,36 +191,6 @@ export class EditionView {
             return (aDimension?.horizontal.from || 0) - (bDimension?.horizontal.from || 0);
         });
     }
-    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 = this.dimensionOf(symbolA);
-        const dimensionB = this.dimensionOf(symbolB);
-        if (!dimensionA || !dimensionB)
-            return false;
-        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;
-    }
     /**
      * Assigns a generation (depth) to every node.
      */

package/lib/Feature.d.ts

@@ -116,6 +116,8 @@ export declare const writingMethods: readonly ["Print", "Handwriting", "Stamp"];
  * printed, handwritten, or stamped.
  */
 export type WritingMethod = typeof writingMethods[number];
+/** The text a writing carries. It names no carriers of its own, the writing being its carrier. */
+export type Transcription = Omit<Text, 'carriers'>;
 /**
  * A piece of writing found on the roll, such as a label,
  * catalogue number, or annotation. Writings have a method
@@ -135,7 +137,7 @@ export interface Writing extends Trace<'Writing'> {
      * can be annotated with a belief about its correctness.
      * @see crm:P128 carries
      */
-    transcription: ObjectAssumption<Omit<Text, 'carriers'>>;
+    transcription: ObjectAssumption<Transcription>;
 }
 /**
  * A visible mark on the roll, such as a pencil mark,

package/lib/ReproducingSystem.d.ts

@@ -1,7 +1,29 @@
-import { RollTempo } from "./Edition";
 import { Hole } from "./Feature";
 import { Expression, Note } from "./Symbol";
 import { TrackerBar } from "./TrackerBar";
+/**
+ * The playback tempo of the roll, specified as a starting
+ * and ending speed. The tempo may change over the course
+ * of the roll due to acceleration effects.
+ * @see crm:E54 Dimension
+ */
+export interface RollTempo {
+    /**
+     * The tempo at the beginning of the roll.
+     * @see reo:from
+     */
+    startsWith: number;
+    /**
+     * The tempo at the end of the roll.
+     * @see reo:to
+     */
+    endsWith: number;
+    /**
+     * The unit of the tempo measurement (e.g. 'ft/min', 'm/min').
+     * @see crm:P91 has unit
+     */
+    unit: string;
+}
 /**
  * A note or expression of a version with the dimensions of its carriers
  * averaged in and the editorial assumptions applied, which is all a

package/lib/RollCopy.d.ts

@@ -3,10 +3,9 @@ import { AnySymbol } from "./Symbol";
 import { TrackerBar } from "./TrackerBar";
 import { TrackCalibration } from "./TrackCalibration";
 import { AnyFeature } from "./Feature";
-import { ObjectAssumption, ValueAssumption } from "./Assumption";
+import { ActorAssignment, DateAssignment, ObjectAssumption } from "./Assumption";
 import { WithId, WithType } from "./utils";
-import { ActorAssignment } from "./Edit";
-import { Agent, Concept } from "./Edition";
+import { Agent, Concept } from "./Agent";
 /**
  * This condition state is used to describe the roll's
  * paper shrinkage or stretching. It might be calculated
@@ -49,23 +48,6 @@ export interface Shift {
      */
     vertical: number;
 }
-export declare const applyShift: (shift: Shift, copy: RollCopy) => void;
-export declare const applyStretch: (paperStretch: ObjectAssumption<PaperStretch>, copy: RollCopy) => void;
-/** Takes the shift off the copy's features again, as far as one was applied. */
-export declare const revertShift: (copy: RollCopy) => void;
-/** Takes the stretch off the copy's features again, as far as one was applied. */
-export declare const revertStretch: (copy: RollCopy) => void;
-/**
- * A date value wrapped as an assumption, so that the date
- * can be annotated with a belief about its certainty and source.
- */
-export type DateAssignment = ValueAssumption<Date> & {
-    /**
-     * The datatype of the value. Written on export so that
-     * RDF reads the value as a date rather than a string.
-     */
-    '@type'?: 'xsd:date';
-};
 /**
  * Describes the production of a roll copy: the manufacturer,
  * the paper used, and the date.
@@ -312,51 +294,3 @@ export declare function unreadTracks(features: AnyFeature[], bar?: TrackerBar):
  * calibration was written down; anything read since carries its own.
  */
 export declare const calibrationOf: (copy: RollCopy) => TrackCalibration | undefined;
-export interface StanfordAtonOptions {
-    /**
-     * Added to the scanning software's hole numbering to reach the
-     * tracker bar. Left out, it is inferred by putting the rewind
-     * perforation on the bar's rewind track.
-     */
-    trackShift?: number;
-    bar?: TrackerBar;
-    /**
-     * Where the scan the analysis was made from can be seen. Stanford's
-     * files name their scan by DRUID, so this is only needed for an
-     * analysis of a scan hosted elsewhere.
-     */
-    scan?: string;
-}
-export declare function readFromStanfordAton(atonString: string, { trackShift, bar, scan }?: StanfordAtonOptions): RollCopy;
-/**
- * How a MIDI key number in one of Spencer Chase's roll files names a
- * tracker bar track.
- *
- * The note block follows the obvious rule, `pitch - 13`, which puts
- * track 11 on MIDI 24 as the T100 compass requires. The bass expression
- * block does not: it reads two tracks high, and subtracting two is what
- * has made these files come out right so far.
- *
- * The boundary between the two rules is unresolved. Taken literally the
- * rules leave tracks 8 and 9 unreachable and jump from track 7 to track 10,
- * which no lateral offset can produce, so at least one of them is
- * approximate. Settling it needs a Spencer file whose expression holes
- * can be checked against the roll, hence the option to override.
- */
-export declare const spencerTrackOf: (pitch: number) => number;
-/**
- * Spencer Chase's rolls seem to be scanned at a roll speed of
- * 83 (=8.3 feet per minute). A scanner feeds the paper at one
- * speed, so time in his files is proportional to place.
- */
-export declare const SPENCER_FEET_PER_MINUTE = 8.3;
-/** Place on the roll in mm after `seconds` at a constant `feetPerMinute`. */
-export declare const atConstantSpeed: (feetPerMinute: number) => (seconds: number) => number;
-export declare function readFromSpencerMIDI(midiBuffer: ArrayBuffer, placeAt?: (seconds: number) => number, trackOf?: (pitch: number) => number): RollCopy;
-/**
- * Moves features across the tracker bar. What the new position means is
- * left to the tracker bar to say, since meaning belongs to the symbols
- * read off a copy rather than to the holes themselves.
- */
-export declare function shiftVertically(features: AnyFeature[], amount: number): void;
-export declare const findCopiesCarrying: (sources: RollCopy[], symbol: AnySymbol) => Set<string>;