import { FeatureOrPatch } from "../model/Feature.js";
import { Alignment, RollCopy } from "../model/RollCopy.js";
import { TrackerBar } from "../systems/TrackerBar.js";
import { Millimeters } from "../model/Quantity.js";
/**
 * A place on the copy's own paper, on the edition's axis.
 * @category Collation and alignment
 */
export declare const toAxis: (alignment: Alignment | undefined) => (place: Millimeters) => Millimeters;
/**
 * A place on the edition's axis, on the copy's own paper.
 * @category Collation and alignment
 */
export declare const fromAxis: (alignment: Alignment | undefined) => (place: Millimeters) => Millimeters;
/**
 * Carries the copy's features and tears from its own places onto the
 * axis, and records how, in place of any alignment it had: that one is
 * taken off first.
 */
export declare const applyAlignment: (alignment: Alignment, copy: RollCopy) => void;
/** Takes the copy's features and tears back to its own places, as far as it was aligned. */
export declare const revertAlignment: (copy: RollCopy) => void;
/**
 * The copy with its features and tears at its own places, as a document
 * holds them, and its alignment kept to say how they go onto the axis.
 * The copy given is left as it is. A copy that is not aligned is the
 * very same copy.
 */
export declare const atOwnPlaces: (copy: RollCopy) => RollCopy;
/**
 * Puts the features and tears of a copy read from a document, which
 * holds them at the copy's own places, onto the axis. The copy given is
 * changed.
 */
export declare const putOnAxis: (copy: RollCopy) => void;
/**
 * The copy's features at its own places, as it was read, whatever alignment it has.
 * @category Collation and alignment
 */
export declare const ownFeaturesOf: (copy: RollCopy) => FeatureOrPatch[];
/**
 * Takes the extension a pneumatic reader adds off the ends of the
 * copy's chains of holes, and records how much was taken.
 *
 * Such a reader reports how long a valve stayed open, and a valve is
 * held on past the perforation that opened it, so its chains run longer
 * than the punched ones while their onsets agree. Left in, the
 * difference is not a difference between copies at all: a collation
 * comparing this copy's chain ends against a scanned copy's compares a
 * pneumatic on-time with a punched slot, and reads the one as a
 * lengthening of the other.
 *
 * The extension is a property of the reader rather than of the roll,
 * and on the material measured so far it is a constant: it does not
 * grow with the length of the perforation, there is no shortest
 * on-time the valve cannot fall below, and it does not run along the
 * roll with the paper speed as far as one roll can show. What it does
 * vary with is the port that read it, by about half a millimetre either
 * way and without any gradient across the bar, which is measured but
 * too coarse to model from one roll.
 *
 * Only chains of holes are touched. What a writing or a mark spans is no valve.
 */
/**
 * The chains the extension cannot be taken off, being no longer than it
 * is: the reader reported them open for less time than it holds a valve
 * on beyond the perforation, so the constant over-corrects them and
 * would leave them ending before they begin.
 *
 * They are where the constant shows its limit rather than where the
 * copy is wrong, the extension varying by about half a millimetre with
 * the port. What to do with them is an editorial question — a condition
 * on the feature, a reading of the chain, a smaller extension — and
 * `shortenChains` throws rather than answer it.
 * @category Sources
 */
export declare const tooShortToShorten: (extension: Millimeters, copy: RollCopy, leaving?: ReadonlySet<string>) => Readonly<FeatureOrPatch>[];
/**
 * Takes the extension off, leaving the named chains as the reader gave
 * them. Naming a chain is an editorial act and not a repair: it says
 * this one is where the constant stops applying, and the edition is
 * what has to say why. The copy records which were left, so that
 * putting the extension back does not lengthen a chain nothing was
 * taken from.
 *
 * Throws where a chain that was not named is no longer than the
 * extension, `tooShortToShorten` saying beforehand which those are.
 */
export declare const shortenChains: (extension: Millimeters, copy: RollCopy, leaving?: ReadonlySet<string>) => void;
/** Puts the reader's extension back on the chains it was taken off, as far as one was taken off. */
export declare const revertShortening: (copy: RollCopy) => void;
/**
 * The method `alignFeatures` follows, as an alignment records it. Its
 * revision changes when the method does and at no other release, so
 * that an alignment found by an earlier method can be told from one
 * that would be found again as it stands.
 * @category Collation and alignment
 */
export declare const ALIGNMENT_METHOD: {
    readonly software: 'linked-rolls alignFeatures';
    readonly version: '1';
};
/**
 * How a copy's places are carried onto another copy's:
 * `x_other = (x + shift) · scale`.
 * @category Collation and alignment
 */
export interface AlignmentResult {
    /** Applied before the scale. */
    shift: Millimeters;
    scale: number;
    /** The notes of the copy that found their counterpart on the other. */
    matched: number;
    /** How far the counterparts still lie apart, as a root mean square in the other copy's millimetres. */
    residual: Millimeters;
    /**
     * The standard error of the scale, as for a line of least squares
     * through the matches: the residual over the spread of the matched
     * notes along the copy, and over the root of their number. The
     * robust line is fitted otherwise, but on Welte 225 this comes
     * within a few per cent of what resampling the matches gives.
     */
    scaleError: number;
}
/**
 * Finds the shift and scale that carry the places of `rollA` onto those
 * of `rollB`, reading each through its own bar. Runs of pitches that
 * occur once on each roll anchor a first line; then every note is paired
 * with its nearest counterpart of the same pitch and the line refitted,
 * the window closing each time. A copy cut for another paper speed, a
 * scan with a calibration pattern, and holes the other copy lacks are
 * all within reach of that. Nothing is found where the rolls share no
 * run of pitches, as between two different pieces.
 *
 * Two bars are what lets a copy cut for one system be aligned against a
 * copy cut for another, a T-98 against a T-100: the bars put the note
 * positions on different tracks, but they agree on the pitch each track
 * sounds, and it is the pitches that are matched. Where a copy's holes
 * have already been put onto the edition's bar, that bar reads it.
 * @category Collation and alignment
 */
export declare function alignFeatures(rollA: readonly FeatureOrPatch[], rollB: readonly FeatureOrPatch[], barA?: TrackerBar, barB?: TrackerBar): AlignmentResult | undefined;