linked-rolls 0.21.0 → 0.23.0

package/lib/Quantity.d.ts

@@ -7,8 +7,12 @@
  * The unit names are the ones the records state in their `unit` field.
  */
 declare const unit: unique symbol;
+/**
+ * The units a record may state. A `Measure` is limited to these, since
+ * they are what the `unit` field is allowed to say.
+ */
 export type Unit = 'mm' | 'cm' | 'px' | 'track' | 's' | 'ms' | 'ft/min' | 'm/min' | 'px/in';
-export type Quantity<U extends Unit> = number & {
+export type Quantity<U extends string> = number & {
     readonly [unit]: U;
 };
 /** A place along the roll, or any length on the paper. */
@@ -24,6 +28,8 @@ export type FeetPerMinute = Quantity<'ft/min'>;
 export type MetersPerMinute = Quantity<'m/min'>;
 /** How finely a scan was read: pixels of the image per inch of paper. */
 export type Resolution = Quantity<'px/in'>;
+/** Names a number in a unit. Partially apply it to make a constructor. */
+export declare const quantity: <U extends string>(value: number) => Quantity<U>;
 export declare const mm: (value: number) => Quantity<"mm">;
 export declare const cm: (value: number) => Quantity<"cm">;
 export declare const px: (value: number) => Quantity<"px">;
@@ -50,19 +56,24 @@ export interface Measure<U extends Unit> {
      */
     unit: U;
 }
-export declare const add: <U extends Unit>(a: Quantity<U>, b: Quantity<NoInfer<U>>) => Quantity<U>;
-export declare const subtract: <U extends Unit>(a: Quantity<U>, b: Quantity<NoInfer<U>>) => Quantity<U>;
-export declare const distance: <U extends Unit>(a: Quantity<U>, b: Quantity<NoInfer<U>>) => Quantity<U>;
+export declare const add: <U extends string>(a: Quantity<U>, b: Quantity<NoInfer<U>>) => Quantity<U>;
+export declare const subtract: <U extends string>(a: Quantity<U>, b: Quantity<NoInfer<U>>) => Quantity<U>;
+export declare const distance: <U extends string>(a: Quantity<U>, b: Quantity<NoInfer<U>>) => Quantity<U>;
 /** A quantity times a plain factor, such as a stretch. */
-export declare const scale: <U extends Unit>(a: Quantity<U>, factor: number) => Quantity<U>;
-export declare const sum: <U extends Unit>(values: readonly Quantity<U>[]) => Quantity<U>;
-export declare const mean: <U extends Unit>(values: readonly Quantity<U>[]) => Quantity<U>;
+export declare const scale: <U extends string>(a: Quantity<U>, factor: number) => Quantity<U>;
+export declare const min: <U extends string>(a: Quantity<U>, b: Quantity<NoInfer<U>>) => Quantity<U>;
+export declare const max: <U extends string>(a: Quantity<U>, b: Quantity<NoInfer<U>>) => Quantity<U>;
+/** The value brought inside the bounds, which must not be the wrong way round. */
+export declare const clamp: <U extends string>(value: Quantity<U>, low: Quantity<NoInfer<U>>, high: Quantity<NoInfer<U>>) => Quantity<U>;
+export declare const sum: <U extends string>(values: readonly Quantity<U>[]) => Quantity<U>;
+export declare const mean: <U extends string>(values: readonly Quantity<U>[]) => Quantity<U>;
 /** A place in a scan taken at `dpi` dots per inch, on the paper. */
 export declare const inMillimeters: (place: Pixels, dpi: number) => Millimeters;
 /** A place on the paper, in a scan taken at `dpi` dots per inch. */
 export declare const inPixels: (place: Millimeters, dpi: number) => Pixels;
 export declare const inCentimeters: (length: Millimeters) => Centimeters;
 export declare const inSeconds: (time: Milliseconds) => Seconds;
+export declare const inMilliseconds: (time: Seconds) => Milliseconds;
 /** A speed as a record states it, in feet or metres per minute. */
 export type SpeedMeasure = Measure<'ft/min'> | Measure<'m/min'>;
 /** A speed in metres per minute, whichever unit it was stated in. */

package/lib/Quantity.js

@@ -1,4 +1,5 @@
-const quantity = (value) => value;
+/** Names a number in a unit. Partially apply it to make a constructor. */
+export const quantity = (value) => value;
 export const mm = quantity;
 export const cm = quantity;
 export const px = quantity;
@@ -15,6 +16,12 @@ export const subtract = (a, b) => quantity(a - b);
 export const distance = (a, b) => quantity(Math.abs(a - b));
 /** A quantity times a plain factor, such as a stretch. */
 export const scale = (a, factor) => quantity(a * factor);
+// Math.min and Math.max are declared over plain numbers, so a quantity
+// passed through them comes back without its unit.
+export const min = (a, b) => quantity(Math.min(a, b));
+export const max = (a, b) => quantity(Math.max(a, b));
+/** The value brought inside the bounds, which must not be the wrong way round. */
+export const clamp = (value, low, high) => quantity(Math.min(high, Math.max(low, value)));
 // A list is taken at its element type, so one that mixes units yields a
 // union unit rather than an error; only the binary operations reject a mix.
 export const sum = (values) => quantity(values.reduce((total, value) => total + value, 0));
@@ -25,7 +32,9 @@ export const inMillimeters = (place, dpi) => mm(place / dpi * MM_PER_INCH);
 /** A place on the paper, in a scan taken at `dpi` dots per inch. */
 export const inPixels = (place, dpi) => px(place / MM_PER_INCH * dpi);
 export const inCentimeters = (length) => cm(length / 10);
-export const inSeconds = (time) => seconds(time / 1000);
+const MS_PER_SECOND = 1000;
+export const inSeconds = (time) => seconds(time / MS_PER_SECOND);
+export const inMilliseconds = (time) => milliseconds(time * MS_PER_SECOND);
 const METERS_PER_FOOT = 0.3048;
 /** A speed in metres per minute, whichever unit it was stated in. */
 export const inMetersPerMinute = (speed) => speed.unit === 'm/min' ? speed.value : metersPerMinute(speed.value * METERS_PER_FOOT);

package/lib/RollCopy.d.ts

@@ -332,7 +332,9 @@ export declare const barOf: (copy: Pick<RollCopy, 'production'>) => TrackerBar;
 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.
+ * A non-empty result usually means the scan is calibrated wrongly. A hole
+ * lying across several positions is counted against each one the bar
+ * cannot read, and not at all where it reads them all.
  */
 export declare function unreadTracks(features: AnyFeature[], bar: TrackerBar): Map<Track, number>;
 /**

package/lib/RollCopy.js

@@ -40,30 +40,27 @@ export function asSymbols(features, bar) {
     const end = bar.endsAt(holes);
     return holes
         .filter(feature => end === undefined || feature.horizontal.from <= end.at)
-        .flatMap((feature) => {
-        const meaning = bar.meaningOf(feature.vertical.from);
-        if (!meaning)
-            return [];
-        return [{
-                id: `symbol_${v4()}`,
-                ...meaning,
-                carriers: [assignReference(feature.id)]
-            }];
-    });
+        // An opening across two positions uncovers both bar holes and so
+        // reads as both commands; one on a single position gives the one.
+        .flatMap((feature) => bar.meaningsOf(feature.vertical).map(meaning => ({
+        id: `symbol_${v4()}`,
+        ...meaning,
+        carriers: [assignReference(feature.id)]
+    })));
 }
 /**
  * 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.
+ * A non-empty result usually means the scan is calibrated wrongly. A hole
+ * lying across several positions is counted against each one the bar
+ * cannot read, and not at all where it reads them all.
  */
 export function unreadTracks(features, bar) {
     const counts = new Map();
     features
         .filter(feature => feature.type === 'Hole')
-        .filter(feature => !bar.meaningOf(feature.vertical.from))
-        .forEach(feature => {
-        const position = feature.vertical.from;
-        counts.set(position, (counts.get(position) || 0) + 1);
-    });
+        .flatMap(feature => bar.positionsIn(feature.vertical))
+        .filter(position => !bar.meaningOf(position))
+        .forEach(position => counts.set(position, (counts.get(position) || 0) + 1));
     return counts;
 }
 /**

package/lib/TrackerBar.d.ts

@@ -67,8 +67,20 @@ export interface TrackerBar {
      * the symbols afterwards.
      */
     endsAt(features: readonly PlacedOnBar[]): RollEnd | undefined;
-    /** `undefined` for a position the bar does not read. */
+    /**
+     * `undefined` for a position the bar does not read. A measured place
+     * is snapped to the nearest position: perforations sit on the grid and
+     * measurements of them scatter around it.
+     */
     meaningOf(position: Track): TrackMeaning | undefined;
+    /**
+     * What the bar reads off a feature, which may lie across more than one
+     * position. A perforation lifts every valve whose bar hole it uncovers,
+     * so an opening across two positions reads as two commands; one on a
+     * single position reads as the one `meaningOf` gives, and one on
+     * positions the bar does not read as none at all.
+     */
+    meaningsOf(span: OnBar): readonly TrackMeaning[];
     /**
      * `meaningOf` inverted: the position this bar reads the meaning on,
      * or `undefined` where it does not read it at all. A symbol's track
@@ -76,8 +88,10 @@ export interface TrackerBar {
      * sits on exactly one position of a given bar.
      */
     positionOf(meaning: TrackMeaning): Track | undefined;
-    /** `undefined` for a position the bar does not read. */
+    /** `undefined` for a position the bar does not read; snapped as `meaningOf` is. */
     roleOf(position: Track): TrackRole | undefined;
+    /** The positions a feature lies across, snapped to the grid. */
+    positionsIn(span: OnBar): readonly Track[];
 }
 /**
  * What a position says, as a key. Two bars read the same thing exactly
@@ -118,6 +132,15 @@ export type PlacedOnBar = {
         readonly from: Track;
     };
 };
+/**
+ * Where a feature lies across the bar: one place, or a run of them where
+ * `to` is given. Structural, so a feature's `vertical` passes as it is and
+ * this module need know nothing about features.
+ */
+export type OnBar = {
+    readonly from: Track;
+    readonly to?: Track;
+};
 export interface TrackerBarSpec {
     id: string;
     name: string;

package/lib/TrackerBar.js

@@ -20,24 +20,42 @@ const areasOf = ({ notes, trackCount }) => [
     { role: 'treble-expression', from: track(notes.to + 1), to: track(trackCount) }
 ];
 const scopeOf = (role) => role === 'bass-expression' ? 'bass' : 'treble';
+/**
+ * The bar position a measured place falls on. Places are measured off a
+ * scan and scatter around the grid, while the bar has holes only at whole
+ * positions, so the nearest one is the one uncovered.
+ */
+const snap = (place) => track(Math.round(place));
+/** The positions a span reaches, both ends snapped and the run between them. */
+const positionsBetween = (span) => {
+    const ends = [snap(span.from), snap(span.to ?? span.from)];
+    const [first, last] = [Math.min(...ends), Math.max(...ends)];
+    return Array.from({ length: last - first + 1 }, (_, step) => track(first + step));
+};
 export const describeTrackerBar = (spec) => {
     const areas = areasOf(spec);
-    const roleOf = (position) => areas.find(area => position >= area.from && position <= area.to)?.role;
+    const areaAt = (position) => areas.find(area => position >= area.from && position <= area.to)?.role;
+    const roleOf = (position) => areaAt(snap(position));
     const meaningOf = (position) => {
-        const role = roleOf(position);
+        const place = snap(position);
+        const role = areaAt(place);
         if (!role)
             return undefined;
         if (role === 'note') {
             return {
                 type: 'note',
-                pitch: position - spec.notes.from + spec.notes.lowestPitch
+                pitch: place - spec.notes.from + spec.notes.lowestPitch
             };
         }
-        const expressionType = spec.expressions.get(position);
+        const expressionType = spec.expressions.get(place);
         if (!expressionType)
             return undefined;
         return { type: 'expression', expressionType, scope: scopeOf(role) };
     };
+    const meaningsOf = (span) => positionsBetween(span).flatMap(position => {
+        const meaning = meaningOf(position);
+        return meaning ? [meaning] : [];
+    });
     const positions = new Map(Array.from({ length: spec.trackCount }, (_, i) => track(i + 1))
         .flatMap(position => {
         const meaning = meaningOf(position);
@@ -54,7 +72,7 @@ export const describeTrackerBar = (spec) => {
     const endsAt = (features) => {
         const hold = spec.rewindHold ?? mm(0);
         const candidates = features
-            .filter(feature => feature.vertical.from === rewind)
+            .filter(feature => snap(feature.vertical.from) === rewind)
             .filter(feature => !shared || feature.horizontal.to - feature.horizontal.from >= hold)
             .map(feature => feature.horizontal.from);
         return candidates.length ? { at: mm(Math.min(...candidates)), because: 'rewind' } : undefined;
@@ -70,8 +88,10 @@ export const describeTrackerBar = (spec) => {
         rewindTrack: track(rewind),
         ...(spec.paperSpeed && { paperSpeed: spec.paperSpeed }),
         meaningOf,
+        meaningsOf,
         positionOf: meaning => positions.get(keyOf(meaning)),
-        roleOf
+        roleOf,
+        positionsIn: positionsBetween
     };
 };
 /**

package/lib/alignment.js

@@ -59,8 +59,9 @@ 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 }] : [];
+    return bar.meaningsOf(feature.vertical)
+        .filter(meaning => meaning.type === 'note')
+        .map(meaning => ({ pitch: meaning.pitch, at: feature.horizontal.from }));
 })
     .sort(byPlace);
 const median = (values) => {

package/lib/constraints.js

@@ -79,8 +79,10 @@ const carriersOffTheirMeaning = (view, version, perforations) => {
         const copy = view.copyOf(carrier.id);
         if (!copy)
             return false;
-        const meaning = barOf(copy).meaningOf(carrier.vertical.from);
-        return !meaning || keyOf(meaning) !== keyOf(symbol);
+        // A carrier lying across several positions reads as several commands,
+        // and carries the symbol as long as one of them is the symbol's.
+        return !barOf(copy).meaningsOf(carrier.vertical)
+            .some(meaning => keyOf(meaning) === keyOf(symbol));
     };
     return perforations
         .filter(symbol => view.carriersOf(symbol).some(carrier => misread(carrier, symbol)))

package/package.json

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