linked-rolls 0.13.0 → 0.15.0

package/README.md

@@ -33,6 +33,41 @@ the keeper and the production metadata are nodes with a name and
 authority links, and the roll names its reproducing system. Exports
 are always in the current format.
 
+## Where a copy's features come from
+
+`readFrom` states what a copy's features were read from: the roll
+itself, a `scan` of it, an `analysis` somebody else measured on a
+scan, an `emulation` in which the roll has already been read into
+notes and commands, or a `recording` captured while the copy was
+played. Beside the kind it holds who carried the capture out, on what
+device, when, and a note. What is not known is left out.
+
+This says where the numbers of the edition come from and nothing
+about the state of the paper, which is a condition of the copy. In
+RDF it is `reo:capture`, an activity typed by what it read from; the
+file it produced is `crmdig:L11 had output`, the machine it ran on
+`crmdig:L12 happened on device`.
+
+Nothing records that a copy is doubtful. `reservationsAbout` works
+out from what a copy states what the edition cannot vouch for in it:
+that it names no source, that the making of its source is
+undocumented, that its features are somebody else's reading, that its
+source bears no physical evidence, that no measuring software is
+recorded, that it is not calibrated. A reservation goes away when the
+gap it names is filled.
+
+```ts
+import { reservationsAbout, stateSource } from 'linked-rolls'
+
+const next = produce(edition, stateSource(copyId, {
+    kind: 'emulation',
+    output: 'https://example.org/wm225.mid',
+    note: 'MIDI from a third party; the emulator is not named.'
+}))
+
+reservationsAbout(next.copies[0]).map(reservation => reservation.note)
+```
+
 ## Emulation
 
 `Emulation` turns a version of the edition into MIDI. The core of the

package/lib/FeatureSource.d.ts

@@ -0,0 +1,65 @@
+import { ActorAssignment, DateAssignment } from "./Assumption";
+import { Concept } from "./Agent";
+import { WithNote } from "./utils";
+/**
+ * What a copy's features were read from. The kinds run from the paper
+ * itself to a file in which the roll has already been read into notes
+ * and commands.
+ */
+export declare const sourceKinds: readonly ['roll', 'scan', 'analysis', 'emulation', 'recording'];
+export type SourceKind = typeof sourceKinds[number];
+/** How each kind of source is referred to in prose. */
+export declare const sourceLabels: Record<SourceKind, string>;
+/**
+ * Whether a source of this kind gives positions that were measured.
+ * An emulation and a recording give the reading somebody else made:
+ * the roll has been turned into notes and commands already, and
+ * turning those back into holes reconstructs them.
+ */
+export declare const isMeasured: (kind: SourceKind) => boolean;
+/**
+ * Whether a source of this kind bears witness to the paper. Punch
+ * diameter, hole separation, punching pattern, marks and writings can
+ * be observed on the roll and on an image of it, and on nothing else.
+ */
+export declare const bearsPhysicalEvidence: (kind: SourceKind) => boolean;
+/**
+ * The capture by which a copy's features became data: what they were
+ * read from, who read them, on what device and when. It states where
+ * the numbers of the edition come from and says nothing about the
+ * state of the paper, which is a condition.
+ *
+ * What is not known is left out. A reader is told about the gap by
+ * `reservationsAbout`, which works out what a copy cannot vouch for
+ * from what it states here.
+ * @see crm:E7 Activity
+ */
+export interface FeatureSource extends WithNote {
+    /**
+     * What the features were read from.
+     * @see crm:P2 has type
+     */
+    kind: SourceKind;
+    /**
+     * The file the capture produced, where it has an address.
+     * @see crmdig:L11 had output
+     */
+    output?: string;
+    /**
+     * Who carried out the capture.
+     * @see crm:P14 carried out by
+     */
+    actor?: ActorAssignment;
+    /**
+     * The make and model of the scanner, camera or player the capture
+     * ran on.
+     * @see crmdig:L12 happened on device
+     */
+    device?: Concept;
+    /**
+     * When the capture took place.
+     * @format date
+     * @see dcterms:date
+     */
+    date?: DateAssignment;
+}

package/lib/FeatureSource.js

@@ -0,0 +1,35 @@
+/**
+ * What a copy's features were read from. The kinds run from the paper
+ * itself to a file in which the roll has already been read into notes
+ * and commands.
+ */
+export const sourceKinds = [
+    'roll',
+    'scan',
+    'analysis',
+    'emulation',
+    'recording'
+];
+/** How each kind of source is referred to in prose. */
+export const sourceLabels = {
+    roll: 'the roll itself',
+    scan: 'a scan of the roll',
+    analysis: 'a hole analysis of a scan',
+    emulation: 'an emulated MIDI file',
+    recording: 'a MIDI recording of the copy being played'
+};
+const measured = ['roll', 'scan', 'analysis'];
+const physical = ['roll', 'scan'];
+/**
+ * Whether a source of this kind gives positions that were measured.
+ * An emulation and a recording give the reading somebody else made:
+ * the roll has been turned into notes and commands already, and
+ * turning those back into holes reconstructs them.
+ */
+export const isMeasured = (kind) => measured.includes(kind);
+/**
+ * Whether a source of this kind bears witness to the paper. Punch
+ * diameter, hole separation, punching pattern, marks and writings can
+ * be observed on the roll and on an image of it, and on nothing else.
+ */
+export const bearsPhysicalEvidence = (kind) => physical.includes(kind);

package/lib/RollCopy.d.ts

@@ -6,6 +6,7 @@ import { AnyFeature } from "./Feature";
 import { ActorAssignment, DateAssignment, ObjectAssumption } from "./Assumption";
 import { WithId, WithType } from "./utils";
 import { Agent, Concept } from "./Agent";
+import { FeatureSource } from "./FeatureSource";
 import { Measure, Millimeters, Quantity, Track } from "./Quantity";
 /**
  * This condition state is used to describe the roll's
@@ -282,6 +283,13 @@ export interface RollCopy extends WithType<'RollCopy'>, WithId {
      * @see crm:P138i has representation
      */
     scan?: string;
+    /**
+     * What this copy's features were read from. A copy that states no
+     * source is one whose features reached the edition by a way that
+     * was not written down.
+     * @see reo:capture
+     */
+    readFrom?: FeatureSource;
 }
 /**
  * Reads the features of a copy as the tracker bar would read them.

package/lib/editionOps.d.ts

@@ -5,7 +5,9 @@ import { AnySymbol, PlacementRelation } from "./Symbol";
 import { CollationTolerance } from "./Collation";
 import { Edit } from "./Edit";
 import { RollCopy, ScaleReading, Shift } from "./RollCopy";
+import { FeatureSource } from "./FeatureSource";
 import { AnyArgumentation, Certainty } from "./Assumption";
+import { AnyFeature } from "./Feature";
 /**
  * A change to an edition, written onto an immer draft of it. One
  * operation is one undo step, so an operation that has to read the
@@ -30,6 +32,10 @@ export declare const alignCopy: (copyId: string, shift: Shift, scale: number, re
  * being a fact about the copy.
  */
 export declare const unalignCopy: (copyId: string) => EditionOp;
+/** States what the copy's features were read from, in place of any earlier statement. */
+export declare const stateSource: (copyId: string, source: FeatureSource) => EditionOp;
+/** Takes back the statement, leaving the copy silent about its source again. */
+export declare const clearSource: (copyId: string) => EditionOp;
 /** The symbols of the versions that no other copy carries. */
 export declare const symbolsCarriedOnlyBy: (edition: Edition, copyId: string) => AnySymbol[];
 /** Takes the features off the copy, and out of the versions with what only they carried. */
@@ -39,6 +45,28 @@ export declare const removeFeatures: (copyId: string, featureIds: readonly strin
  * carries, and with every reference the versions made to those symbols.
  */
 export declare const removeCopy: (copyId: string) => EditionOp;
+/** Why several features cannot be replaced by one. */
+export type MergeObstacle = 'fewer-than-two' | 'different-types' | 'different-tracks' | 'differing-conditions' | 'unlike-features';
+/**
+ * What stands in the way of reading the features as one, or nothing
+ * where they may be merged. Features may be merged where they differ
+ * in nothing but their place along the roll, their depiction and the
+ * condition at most one of them states. How far apart they lie is not
+ * asked: whether a gap is a bridge of the perforator, a tear or two
+ * perforations of their own is the editor's reading.
+ */
+export declare const mergeObstacle: (features: readonly AnyFeature[]) => MergeObstacle | undefined;
+/**
+ * Replaces the features of the copy with a single one covering them
+ * all, where a scan has split what the editor reads as one feature.
+ * The merged feature takes the place of the first it replaces and
+ * spans from the first to the last, any gap between them included.
+ * What the replaced features carried is carried by the merged one.
+ *
+ * Throws where the features cannot stand for one; `mergeObstacle`
+ * says beforehand whether they can.
+ */
+export declare const mergeFeatures: (copyId: string, featureIds: readonly string[]) => EditionOp;
 /**
  * Bases the child on the parent. A symbol of the child that collates
  * with one the parent hands down adds its carriers to that symbol; the

package/lib/editionOps.js

@@ -96,6 +96,14 @@ export const unalignCopy = (copyId) => onCopy(copyId, copy => {
     revertShift(copy);
     copy.conditions = without(copy.conditions, isPaperStretch);
 });
+/** States what the copy's features were read from, in place of any earlier statement. */
+export const stateSource = (copyId, source) => onCopy(copyId, copy => {
+    copy.readFrom = source;
+});
+/** Takes back the statement, leaving the copy silent about its source again. */
+export const clearSource = (copyId) => onCopy(copyId, copy => {
+    copy.readFrom = undefined;
+});
 const featureIdsOf = (copy) => new Set(copy.features.map(feature => feature.id));
 /**
  * A symbol every carrier of which lies among the features loses its
@@ -165,6 +173,117 @@ export const removeCopy = (copyId) => onCopy(copyId, (copy, draft) => {
     forgetFeatures(draft, featureIdsOf(copy));
     draft.copies = draft.copies.filter(c => c.id !== copyId);
 });
+const isRecord = (value) => typeof value === 'object' && value !== null;
+/**
+ * Whether two records of the edition state the same, the identity of a
+ * statement left out: two transcriptions reading the same word say the
+ * same, whichever ids they were given.
+ */
+const sayTheSame = (a, b) => {
+    if (a === b)
+        return true;
+    if (!isRecord(a) || !isRecord(b) || Array.isArray(a) !== Array.isArray(b))
+        return false;
+    const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+    keys.delete('id');
+    return [...keys].every(key => sayTheSame(a[key], b[key]));
+};
+/** What a feature states beyond its identity, its place along the roll, its depiction and its condition. */
+const nature = (feature) => {
+    const { id, horizontal, depiction, condition, ...rest } = feature;
+    return rest;
+};
+const conditionsOf = (features) => features.flatMap(feature => feature.condition ? [feature.condition] : []);
+/**
+ * What stands in the way of reading the features as one, or nothing
+ * where they may be merged. Features may be merged where they differ
+ * in nothing but their place along the roll, their depiction and the
+ * condition at most one of them states. How far apart they lie is not
+ * asked: whether a gap is a bridge of the perforator, a tear or two
+ * perforations of their own is the editor's reading.
+ */
+export const mergeObstacle = (features) => {
+    if (features.length < 2)
+        return 'fewer-than-two';
+    const [first, ...rest] = features;
+    if (rest.some(feature => feature.type !== first.type))
+        return 'different-types';
+    if (rest.some(feature => !sayTheSame(feature.vertical, first.vertical)))
+        return 'different-tracks';
+    if (rest.some(feature => !sayTheSame(nature(feature), nature(first))))
+        return 'unlike-features';
+    const conditions = conditionsOf(features);
+    if (conditions.some(condition => !sayTheSame(condition, conditions[0])))
+        return 'differing-conditions';
+    return undefined;
+};
+/** The items with the replacement in the place of the first it stands for, the others dropped. */
+const standingFor = (items, stands, replacement) => {
+    const first = items.findIndex(stands);
+    if (first < 0)
+        return items;
+    return items.flatMap((item, i) => i === first ? [replacement] : stands(item) ? [] : [item]);
+};
+const spanning = (features) => ({
+    unit: 'mm',
+    from: mm(Math.min(...features.map(feature => feature.horizontal.from))),
+    to: mm(Math.max(...features.map(feature => feature.horizontal.to)))
+});
+/**
+ * The feature the merged ones give way to. It spans them all and is in
+ * every other respect the one of them that states a condition, the
+ * others being alike in all but their place. The depiction goes: a
+ * region of the scan showing one part depicts no more than that part.
+ */
+const mergedFrom = (features) => {
+    const stating = features.find(feature => feature.condition) ?? features[0];
+    const merged = { ...stating, id: v4(), horizontal: spanning(features) };
+    delete merged.depiction;
+    return merged;
+};
+/** The symbol carried by the merged feature where it named one of those it replaces, and naming it once. */
+const carriedByMerged = (replaced, mergedId) => (symbol) => {
+    const names = (carrier) => replaced.has(idOf(carrier));
+    const first = symbol.carriers.find(names);
+    if (!first)
+        return symbol;
+    return { ...symbol, carriers: standingFor(symbol.carriers, names, { ...first, id: mergedId }) };
+};
+/** Points the versions at the merged feature wherever they name one it replaces. */
+const carryOver = (draft, replaced, mergedId) => {
+    const recarry = carriedByMerged(replaced, mergedId);
+    const recarrying = (edit) => {
+        const insert = edit.insert && mapped(edit.insert, recarry);
+        return insert === edit.insert ? edit : { ...edit, insert };
+    };
+    const versions = stateOf(draft.versions);
+    draft.versions.forEach((version, i) => {
+        version.edits = mapped(versions[i].edits, recarrying);
+    });
+};
+/**
+ * Replaces the features of the copy with a single one covering them
+ * all, where a scan has split what the editor reads as one feature.
+ * The merged feature takes the place of the first it replaces and
+ * spans from the first to the last, any gap between them included.
+ * What the replaced features carried is carried by the merged one.
+ *
+ * Throws where the features cannot stand for one; `mergeObstacle`
+ * says beforehand whether they can.
+ */
+export const mergeFeatures = (copyId, featureIds) => onCopy(copyId, (copy, draft) => {
+    const replaced = new Set(featureIds);
+    const isReplaced = (feature) => replaced.has(feature.id);
+    const features = stateOf(copy.features);
+    const toMerge = features.filter(isReplaced);
+    const obstacle = mergeObstacle(toMerge);
+    if (obstacle) {
+        throw new Error(`The features of copy ${copyId} cannot be merged: ${obstacle}`);
+    }
+    const merged = mergedFrom(toMerge);
+    copy.features = standingFor(features, isReplaced, merged);
+    carryOver(draft, replaced, merged.id);
+});
 /** The carriers of each collated symbol pass to its counterpart. */
 const handOverCarriers = (view, draft, collations) => collations.forEach(({ symbol, counterpart }) => {
     const path = view.getPath(counterpart.id);

package/lib/index.d.ts

@@ -14,7 +14,9 @@ export * from './systems/welteT100/bar';
 export * from './systems/welteLicensee/bar';
 export * from './systems';
 export * from './ReproducingSystem';
+export * from './FeatureSource';
 export * from './RollCopy';
+export * from './reservations';
 export * from './alignment';
 export * from './Edition';
 export * from './EditionView';
@@ -25,5 +27,6 @@ export * from './constraints';
 export * from './context';
 export * from './asJsonLd';
 export * from './importJsonLd';
+export * from './migrate';
 export { readFromStanfordAton, type StanfordAtonOptions } from './readers/stanfordAton';
 export { readFromSpencerBar, readSpencerAnn, paperSpeedOfSpencerAnn, SPENCER_ROWS_PER_INCH, type SpencerBarOptions } from './readers/spencerBar';

package/lib/index.js

@@ -14,7 +14,9 @@ export * from './systems/welteT100/bar';
 export * from './systems/welteLicensee/bar';
 export * from './systems';
 export * from './ReproducingSystem';
+export * from './FeatureSource';
 export * from './RollCopy';
+export * from './reservations';
 export * from './alignment';
 export * from './Edition';
 export * from './EditionView';
@@ -25,5 +27,6 @@ export * from './constraints';
 export * from './context';
 export * from './asJsonLd';
 export * from './importJsonLd';
+export * from './migrate';
 export { readFromStanfordAton } from './readers/stanfordAton';
 export { readFromSpencerBar, readSpencerAnn, paperSpeedOfSpencerAnn, SPENCER_ROWS_PER_INCH } from './readers/spencerBar';

package/lib/reservations.d.ts

@@ -0,0 +1,23 @@
+import { RollCopy } from "./RollCopy";
+export declare const reservationTypes: readonly ['source-not-stated', 'source-undocumented', 'features-interpreted', 'no-physical-evidence', 'measurement-undocumented', 'not-calibrated'];
+export type ReservationType = typeof reservationTypes[number];
+/**
+ * Something an edition cannot vouch for in one of its copies.
+ *
+ * A reservation is worked out from what the copy states about itself
+ * and is never written into the edition: it says that knowledge of
+ * the copy is incomplete, so filling in what is missing makes it go
+ * away. Nothing here describes the state of the paper, which is a
+ * condition of the copy.
+ */
+export interface Reservation {
+    type: ReservationType;
+    /** What the reservation means for a reader, in one sentence. */
+    note: string;
+}
+/**
+ * What the edition cannot vouch for in a copy, in the order the
+ * checks are listed: where its features came from first, then what
+ * the measurement leaves open.
+ */
+export declare const reservationsAbout: (copy: RollCopy) => Reservation[];

package/lib/reservations.js

@@ -0,0 +1,53 @@
+import { bearsPhysicalEvidence, isMeasured, sourceLabels } from "./FeatureSource";
+import { calibrationOf } from "./RollCopy";
+export const reservationTypes = [
+    'source-not-stated',
+    'source-undocumented',
+    'features-interpreted',
+    'no-physical-evidence',
+    'measurement-undocumented',
+    'not-calibrated'
+];
+const sourceStated = copy => copy.readFrom ? undefined : {
+    type: 'source-not-stated',
+    note: 'The copy does not state what its features were read from.'
+};
+const sourceDocumented = copy => {
+    const source = copy.readFrom;
+    if (!source || source.actor || source.device || source.date)
+        return undefined;
+    return {
+        type: 'source-undocumented',
+        note: `The copy names ${sourceLabels[source.kind]} as its source, but records nobody who made it, no device and no date.`
+    };
+};
+const featuresMeasured = copy => copy.readFrom && !isMeasured(copy.readFrom.kind) ? {
+    type: 'features-interpreted',
+    note: `The features come from ${sourceLabels[copy.readFrom.kind]}, in which the roll has already been read into notes and commands by somebody else.`
+} : undefined;
+const physicalEvidence = copy => copy.readFrom && !bearsPhysicalEvidence(copy.readFrom.kind) ? {
+    type: 'no-physical-evidence',
+    note: 'Punch diameter, hole separation, punching pattern, marks and writings cannot be observed on this source.'
+} : undefined;
+const measurementDocumented = copy => !copy.measurements.measuredBy && copy.readFrom?.kind !== 'roll' ? {
+    type: 'measurement-undocumented',
+    note: 'No measuring software is recorded for this copy.'
+} : undefined;
+const calibrated = copy => calibrationOf(copy) ? undefined : {
+    type: 'not-calibrated',
+    note: 'The copy is not calibrated against the tracker bar, so its track positions rest on the numbering its source used.'
+};
+const checks = [
+    sourceStated,
+    sourceDocumented,
+    featuresMeasured,
+    physicalEvidence,
+    measurementDocumented,
+    calibrated
+];
+/**
+ * What the edition cannot vouch for in a copy, in the order the
+ * checks are listed: where its features came from first, then what
+ * the measurement leaves open.
+ */
+export const reservationsAbout = (copy) => checks.flatMap(check => check(copy) ?? []);

package/lib/schema.json

@@ -543,6 +543,40 @@
             ],
             "type": "string"
         },
+        "FeatureSource": {
+            "description": "The capture by which a copy's features became data: what they were read from, who read them, on what device and when. It states where the numbers of the edition come from and says nothing about the state of the paper, which is a condition.\n\nWhat is not known is left out. A reader is told about the gap by `reservationsAbout`, which works out what a copy cannot vouch for from what it states here. [ontology: crm:E7 Activity]",
+            "properties": {
+                "actor": {
+                    "$ref": "#/definitions/ActorAssignment",
+                    "description": "Who carried out the capture. [ontology: crm:P14 carried out by]"
+                },
+                "date": {
+                    "$ref": "#/definitions/DateAssignment",
+                    "description": "When the capture took place. [ontology: dcterms:date]",
+                    "format": "date"
+                },
+                "device": {
+                    "$ref": "#/definitions/Concept",
+                    "description": "The make and model of the scanner, camera or player the capture ran on. [ontology: crmdig:L12 happened on device]"
+                },
+                "kind": {
+                    "$ref": "#/definitions/SourceKind",
+                    "description": "What the features were read from. [ontology: crm:P2 has type]"
+                },
+                "note": {
+                    "description": "A free-text note providing additional context. [ontology: crm:P3 has note]",
+                    "type": "string"
+                },
+                "output": {
+                    "description": "The file the capture produced, where it has an address. [ontology: crmdig:L11 had output]",
+                    "type": "string"
+                }
+            },
+            "required": [
+                "kind"
+            ],
+            "type": "object"
+        },
         "GluedOn": {
             "description": "A piece of material (paper or tape) glued onto the roll surface. Glued-on features are typically used to cover perforations (for corrections) or to reinforce damaged areas. They may themselves carry other features such as writings or additional holes. [ontology: crm:E22 Human-Made Object]",
             "properties": {
@@ -1816,6 +1850,10 @@
                     "$ref": "#/definitions/ProductionEvent",
                     "description": "The production event that created this roll copy. [ontology: lrmoo:R28i was produced by]"
                 },
+                "readFrom": {
+                    "$ref": "#/definitions/FeatureSource",
+                    "description": "What this copy's features were read from. A copy that states no source is one whose features reached the edition by a way that was not written down. [ontology: reo:capture]"
+                },
                 "scan": {
                     "description": "The scan URL or IIIF URL of the roll. [ontology: crm:P138i has representation]",
                     "type": "string"
@@ -1861,6 +1899,16 @@
             ],
             "type": "object"
         },
+        "SourceKind": {
+            "enum": [
+                "roll",
+                "scan",
+                "analysis",
+                "emulation",
+                "recording"
+            ],
+            "type": "string"
+        },
         "Text": {
             "description": "A textual symbol, e.g. a label or annotation found on the roll. [ontology: crm:E33 Linguistic Object]",
             "properties": {

package/lib/spec/context.json

@@ -165,6 +165,22 @@
             "@id": "crm:P138i_has_representation",
             "@type": "@id"
         },
+        "readFrom": {
+            "@id": "reo:capture",
+            "@context": {
+                "kind": {
+                    "@id": "crm:P2_has_type",
+                    "@type": "@vocab",
+                    "@context": { "@vocab": "https://w3id.org/reo/type/" }
+                },
+                "output": {
+                    "@id": "crmdig:L11_had_output",
+                    "@type": "@id"
+                },
+                "device": "crmdig:L12_happened_on_device",
+                "note": "crm:P3_has_note"
+            }
+        },
         "depiction": {
             "@id": "crm:P138i_has_representation",
             "@type": "@id"

package/package.json

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