linked-rolls 0.0.1 → 0.1.0

package/lib/RollCopy.d.ts

@@ -1,62 +1,241 @@
 import { ConditionState } from "./ConditionState";
 import { AnySymbol } from "./Symbol";
-import { EditorialAssumption } from "./EditorialAssumption";
-import { PlaceTimeConversion } from "./PlaceTimeConversion";
-import { RollFeature } from "./Feature";
+import { TrackerBar } from "./TrackerBar";
+import { TrackCalibration } from "./TrackCalibration";
+import { AnyFeature } from "./Feature";
+import { ObjectAssumption, ValueAssumption } from "./Assumption";
+import { WithId, WithType } from "./utils";
+import { ActorAssignment } from "./Edit";
 /**
- * This condition state is used to describe to roll's
+ * This condition state is used to describe the roll's
  * paper shrinkage or stretching. It might be calculated
  * on the basis of comparing the vertical or horizontal
  * extent with other witnesses of the same roll.
  */
 export interface PaperStretch extends ConditionState<'paper-stretch'> {
+    /**
+     * The stretch factor, e.g. 1.02 means the paper has
+     * stretched by 2% compared to its original dimensions.
+     */
     factor: number;
 }
+/**
+ * A general condition description for a roll copy, e.g.
+ * overall wear, discoloration, or other observations.
+ * @see crm:E3 Condition State
+ */
 export interface GeneralRollCondition extends ConditionState<'general'> {
 }
-export type RollConditionAssignment = EditorialAssumption<'conditionAssignment', GeneralRollCondition | PaperStretch>;
+/**
+ * An assignment of a condition (general or paper-stretch)
+ * to a roll copy, annotatable with a belief about its certainty.
+ */
+export type RollConditionAssignment = ObjectAssumption<GeneralRollCondition | PaperStretch>;
+export declare const rollConditions: readonly ["general", "paper-stretch"];
+/**
+ * A shift correction applied to a roll copy to align it
+ * with other copies. The shift is defined as horizontal
+ * (along the roll length, in mm) and vertical (across tracks).
+ */
 export interface Shift {
+    /**
+     * Horizontal shift in millimeters (along the roll length).
+     */
     horizontal: number;
+    /**
+     * Vertical shift in track numbers (across the tracker bar).
+     */
     vertical: number;
 }
-export type DateAssignment = EditorialAssumption<'dateAssignment', Date>;
+export declare const applyShift: (shift: Shift, copy: RollCopy) => void;
+export declare const applyStretch: (paperStretch: ObjectAssumption<PaperStretch>, 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>;
+/**
+ * Describes the production of a roll copy, including the
+ * manufacturing company, the roll system, and the paper used.
+ * @see lrm:F33 Reproduction Event
+ */
 export interface ProductionEvent {
+    /**
+     * The company that produced the roll copy
+     * (e.g. "M. Welte & Söhne").
+     * @see crm:P14 carried out by
+     */
     company: string;
+    /**
+     * The roll system used for production
+     * (e.g. "Welte-Mignon T100", "Welte-Mignon T98").
+     */
     system: string;
+    /**
+     * The paper type used for the roll copy.
+     * @see P126:employed
+     */
     paper: string;
-    date: DateAssignment;
+    /**
+     * The date of production, if known.
+     * @see crm:P4 has time-span
+     */
+    date?: DateAssignment;
 }
-export declare class RollCopy {
-    type: 'RollCopy';
-    id: string;
+/**
+ * This type denotes identifiable activities that modified
+ * the roll copy after its production, e.g. annotations, repairs,
+ * etc.
+ * @see crm:E79 Part Addition, crm:E80 Part Removal
+ */
+export type Modification = Partial<{
+    actor: ActorAssignment;
+    date: DateAssignment;
+}> & ({
+    type: 'Addition';
+    /**
+     * @see crm:P111 added
+     */
+    added: string[];
+    /**
+     * @see crm:P21 had general purpose
+     */
+    purpose: 'musical-improvement' | 'technical-improvement' | 'repair' | 'labeling' | 'control' | 'dating' | 'glossing';
+} | {
+    type: 'Removal';
+    /**
+     * @see crm:P113 removed
+     */
+    removed: string[];
+    /**
+     * Usually, roll features are being added.
+     * Sometimes however, we may see traces of features
+     * that have been removed, e.g. through bright spots on
+     * the roll.
+     */
+    purpose: 'delabeling';
+});
+/**
+ * A physical copy of a roll, held at a specific location.
+ * Each roll copy has its own set of features, measurements,
+ * conditions, and modifications. Multiple copies of the same
+ * roll may exist across different archives or collections.
+ * @see crm:E22 Human-Made Object
+ */
+export interface RollCopy extends WithType<'RollCopy'>, WithId {
+    /**
+     * A list of operations that have been applied to this copy's features
+     * (e.g. 'shifted', 'stretched') to normalize measurements
+     * for comparison with other copies.
+     */
+    ops: Array<'shifted' | 'stretched'>;
+    /**
+     * Physical measurements of this roll copy, including
+     * dimensions, punch diameter, hole separation, margins,
+     * shift corrections, and information about the measuring software.
+     */
     measurements: Partial<{
+        /**
+         * The physical dimensions of the roll.
+         */
         dimensions: {
+            /**
+             * The width of the roll in the given unit.
+             */
             width: number;
+            /**
+             * The total height (length) of the roll in the given unit.
+             */
             height: number;
+            /**
+             * The unit of measurement (e.g. 'mm').
+             */
             unit: string;
         };
+        /**
+         * The average diameter of punched holes.
+         */
         punchDiameter: {
+            /**
+             * The measured punch diameter value.
+             */
             value: number;
+            /**
+             * The unit of measurement (e.g. 'mm').
+             */
             unit: string;
         };
+        /**
+         * The distance between adjacent tracker bar holes.
+         */
         holeSeparation: {
+            /**
+             * The measured hole separation value.
+             */
             value: number;
+            /**
+             * The unit of measurement (e.g. 'px', 'mm').
+             */
             unit: string;
         };
+        /**
+         * The margins on the treble and bass sides of the roll.
+         */
         margins: {
+            /**
+             * The margin on the treble side.
+             */
             treble: number;
+            /**
+             * The margin on the bass side.
+             */
             bass: number;
+            /**
+             * The unit of measurement (e.g. 'px', 'mm').
+             */
             unit: string;
         };
         shift: Shift;
+        /**
+         * Relates this copy's scan to the tracker bar: how the scanning
+         * software's hole numbering was shifted onto the bar, and where
+         * the track grid sits in the image.
+         */
+        trackCalibration: TrackCalibration;
+        /**
+         * Information about the software used to take the measurements.
+         */
         measuredBy: {
+            /**
+             * The name of the measurement software.
+             */
             software: string;
+            /**
+             * The version of the measurement software.
+             */
             version: string;
+            /**
+             * The date on which the measurements were taken.
+             * @format date
+             */
             date: Date;
         };
     }>;
-    productionEvent?: ProductionEvent;
+    /**
+     * The production event that created this roll copy.
+     * @see lrm:R28i was produced by
+     */
+    production?: ProductionEvent;
+    /**
+     * Condition assessments of this roll copy (e.g. paper stretch,
+     * general wear). Each condition is an assumption annotatable
+     * with a belief.
+     */
     conditions: RollConditionAssignment[];
+    /**
+     * The current physical location or archive where this copy is held.
+     * @see crm:P55 has current location
+     */
     location: string;
     /**
      * Provides a reconstructed version of the roll,
@@ -64,22 +243,78 @@ export declare class RollCopy {
      * taken into account. This property will not be
      * exported in the final JSON.
      */
-    features: RollFeature[];
+    features: AnyFeature[];
+    /**
+     * @see crm:P31 was modified by
+     */
+    modifications: Modification[];
+    /**
+     * The scan URL or IIIF URL of the roll.
+     * @see crm:P138i has representation
+     */
     scan?: string;
-    insertFeature(feature: RollFeature): void;
-    setShift(shift: Shift): void;
-    setStretch(stretch: EditorialAssumption<'conditionAssignment', PaperStretch>): void;
-    shallowClone(): RollCopy;
 }
-export declare function asSymbols(features: RollFeature[]): AnySymbol[];
-export declare function readFromStanfordAton(atonString: string, adjustByRewind?: boolean, shift?: number): RollCopy;
 /**
- * Spencer Chase's rolls seem to be scanned at a roll speed of
- * 83 (=8.3 feet per minute).
+ * Reads the features of a copy as the tracker bar would read them.
+ * Holes on a position the bar does not read carry no symbol and are
+ * dropped, which is what happens physically as well.
+ */
+export declare function asSymbols(features: AnyFeature[], bar?: TrackerBar): AnySymbol[];
+/**
+ * The tracks a copy carries holes on that the tracker bar does not read.
+ * A non-empty result usually means the scan is calibrated wrongly.
+ */
+export declare function unreadTracks(features: AnyFeature[], bar?: TrackerBar): Map<number, number>;
+/**
+ * Falls back to the way the scan geometry was reconstructed before the
+ * calibration was recorded: the bass hard margin stood in for the phase
+ * of the tracker grid, with a constant making up most of the difference.
  *
- * @param midiBuffer
- * @param conversion
+ * The constant of one and a half tracks is the one the facsimile tiles
+ * were laid out with, and on the rolls measured so far it comes within
+ * about a quarter of a track. It is kept for copies imported before the
+ * 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;
+}
+export declare function readFromStanfordAton(atonString: string, { trackShift, bar }?: 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 readFromSpencerMIDI(midiBuffer: ArrayBuffer, conversion?: PlaceTimeConversion): RollCopy;
-export declare function shiftVertically(features: RollFeature[], amount: number): void;
+export declare function shiftVertically(features: AnyFeature[], amount: number): void;
 export declare const findCopiesCarrying: (sources: RollCopy[], symbol: AnySymbol) => Set<string>;