@math.gl/projection 0.0.0-stage → 5.0.0-alpha.12

package/dist/experimental/projection-pipeline.js

@@ -0,0 +1,746 @@
+import { CORE_PARAMETERS, normalizeCRS } from "./crs/normalize.js";
+import { unsupportedStage } from "./crs/types.js";
+import { applyDatumGrids, createHelmert, geocentricToGeodeticInPlace, geodeticToGeocentricInPlace } from "./datum.js";
+import { projectionOperation } from "./mutable-projection.js";
+import { ProjectionScratch } from "./projection-scratch.js";
+import { createNumericFlat } from "./numeric-flat.js";
+import { validateScalarOutput, writeScalarOutput } from "./scalar-output.js";
+import { createHelmertFlat } from "./helmert-flat.js";
+import { createExactHelmert } from "./exact-helmert.js";
+import { createKinematicHelmert } from "./kinematic-helmert.js";
+import { getLoadedProjection, preloadProjection } from "./projection-descriptor.js";
+import { compileVerticalGrid } from "./vertical-datum.js";
+const EMPTY_STACK = new Float64Array(0);
+// Typed-array buffers are ordinary or shared. The intrinsic getter checks the
+// backing-store brand across realms and cannot be fooled by Symbol.toStringTag.
+const ordinaryByteLength = Object.getOwnPropertyDescriptor(ArrayBuffer.prototype, 'byteLength').get;
+function sharedBuffer(buffer) {
+    try {
+        ordinaryByteLength.call(buffer);
+        return false;
+    }
+    catch {
+        return true;
+    }
+}
+function compileFlat(pairs) {
+    if (pairs.length === 1 && pairs[0].forwardFlat)
+        return pairs[0].forwardFlat;
+    // Pure axis measurements were inconsistent; retain general dispatch for that subset.
+    return pairs.every(pair => pair.forwardNumeric) &&
+        pairs.some(pair => pair.forwardNumeric[0] !== 2)
+        ? createNumericFlat(pairs.map(pair => pair.forwardNumeric))
+        : undefined;
+}
+const factors = {
+    deg: Math.PI / 180,
+    rad: 1,
+    m: 1,
+    ft: 0.3048,
+    'us-ft': 1200 / 3937
+};
+const geometryKeys = ['ellps', 'a', 'b', 'rf', 'f', 'R'];
+const angular = (unit) => unit === 'deg' || unit === 'rad';
+const own = (value, name) => Object.prototype.hasOwnProperty.call(value, name);
+function keys(value, allowed) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('Expected operation object');
+    for (const name of Object.keys(value))
+        if (!allowed.includes(name))
+            unsupportedStage('Unsupported pipeline parameter: ' + name);
+}
+function definition(name, parameters = {}) {
+    if (!/^[a-z][a-z0-9_]*$/i.test(name))
+        throw new Error('Invalid projection name');
+    return ('+proj=' +
+        name +
+        Object.entries(parameters)
+            .map(([key, value]) => {
+            if (!/^[a-z][a-z0-9_]*$/i.test(key) ||
+                (value !== undefined &&
+                    (typeof value !== 'string' ||
+                        !value ||
+                        /[\s=]/.test(value) ||
+                        /\+/.test(value.slice(1).replace(/[eE]\+/g, '')))))
+                throw new Error('Invalid pipeline projection parameter: ' + key);
+            return ' +' + key + (value === undefined ? '' : '=' + value);
+        })
+            .join(''));
+}
+function finite(point) {
+    if (!Number.isFinite(point.x) || !Number.isFinite(point.y) || !Number.isFinite(point.z))
+        throw new Error('Pipeline coordinate must be finite');
+}
+function triple(values) {
+    if (!Array.isArray(values) || values.length !== 3 || !values.every(Number.isFinite))
+        throw new Error('Expected three finite Helmert parameters');
+}
+/** Explicit forward/reverse operations; no CRS/epoch inference or string pipeline parser.
+ * General execution reuses guarded scratch; specialized flat stages use numeric
+ * locals and never allocate coordinate arrays inside the flat loop. M and additional ordinates are preserved, never interpreted.
+ */
+export class ProjectionPipeline {
+    constructor(options) {
+        this.forwardFactories = [];
+        this.inverseFactories = [];
+        this.stackSize = 0;
+        this.coordinateScratch = new ProjectionScratch();
+        this.required = [];
+        this.requiresZ = false;
+        this.requiresEpoch = false;
+        keys(options, ['input', 'steps', 'projections', 'datumGrids', 'verticalGrids']);
+        keys(options.input, ['space', 'units']);
+        const { space, units } = options.input;
+        if (!['geographic', 'projected', 'geocentric'].includes(space) ||
+            !Array.isArray(units) ||
+            units.length !== 3 ||
+            units.some(unit => !own(factors, unit)) ||
+            angular(units[2]) ||
+            (space === 'geographic'
+                ? !angular(units[0]) || !angular(units[1])
+                : angular(units[0]) || angular(units[1])))
+            throw new Error('Invalid pipeline input space/units');
+        if (!Array.isArray(options.steps) || options.steps.length === 0)
+            throw new Error('Pipeline requires at least one step');
+        this.requiresZ = space === 'geocentric';
+        this.input = Object.freeze({
+            space,
+            units: Object.freeze([...units])
+        });
+        const state = { space, units: [...units], stacks: [[], [], []] };
+        const projections = [...(options.projections || [])];
+        this.deferred = projections.some(projection => !('create' in projection));
+        // Each direction has its own validated metadata and stack layout. Share equation
+        // implementations by step so custom plugin factories still run once per step.
+        const caches = options.steps.map(() => ({}));
+        for (const [index, step] of options.steps.entries()) {
+            for (const name of ['inverse', 'omitForward', 'omitInverse'])
+                if (step?.[name] !== undefined && typeof step[name] !== 'boolean')
+                    throw new Error('Invalid pipeline ' + name + ' flag');
+            if (step?.omitForward && step.omitInverse)
+                throw new Error('A pipeline step cannot omit both directions');
+            if (!step?.omitForward)
+                this.forwardFactories.push(this.prepare(step, state, { ...options, projections }, caches[index]));
+        }
+        this.balanced(state);
+        this.output = Object.freeze({
+            space: state.space,
+            units: Object.freeze([...state.units])
+        });
+        const reverse = { space: state.space, units: [...state.units], stacks: [[], [], []] };
+        for (let index = options.steps.length - 1; index >= 0; index--) {
+            const step = options.steps[index];
+            if (!step.omitInverse)
+                this.inverseFactories.push(this.prepare({ ...step, inverse: !step.inverse }, reverse, { ...options, projections }, caches[index]));
+        }
+        this.balanced(reverse);
+        if (reverse.space !== space || reverse.units.some((unit, index) => unit !== units[index]))
+            throw new Error('Inverse pipeline output does not match declared input space/units');
+        if (this.required.every(projection => getLoadedProjection(projection)))
+            this.compile();
+        this.project = this.project.bind(this);
+        this.unproject = this.unproject.bind(this);
+        this.projectSync = this.projectSync.bind(this);
+        this.unprojectSync = this.unprojectSync.bind(this);
+        this.projectTo = this.projectTo.bind(this);
+        this.unprojectTo = this.unprojectTo.bind(this);
+        this.projectToSync = this.projectToSync.bind(this);
+        this.unprojectToSync = this.unprojectToSync.bind(this);
+        this.projectFlat = this.projectFlat.bind(this);
+        this.unprojectFlat = this.unprojectFlat.bind(this);
+        this.projectFlatSync = this.projectFlatSync.bind(this);
+        this.unprojectFlatSync = this.unprojectFlatSync.bind(this);
+    }
+    /** Load only implementations named by pipeline steps; failures can be retried. */
+    preload() {
+        if (this.compiled)
+            return Promise.resolve(this);
+        this.pending || (this.pending = Promise.all(this.required.map(preloadProjection))
+            .then(() => {
+            this.compile();
+            return this;
+        })
+            .catch(error => {
+            this.pending = undefined;
+            throw error;
+        }));
+        return this.pending;
+    }
+    project(coordinate, epoch) {
+        return (this.deferred
+            ? this.preload().then(() => this.projectSync(coordinate, epoch))
+            : this.projectSync(coordinate, epoch));
+    }
+    unproject(coordinate, epoch) {
+        return (this.deferred
+            ? this.preload().then(() => this.unprojectSync(coordinate, epoch))
+            : this.unprojectSync(coordinate, epoch));
+    }
+    /** Reuse a scalar output; the epoch remains separate from all coordinate ordinates. */
+    projectTo(coordinate, output, epoch) {
+        return (this.deferred
+            ? this.scalarToLoaded(coordinate, output, false, epoch)
+            : this.projectToSync(coordinate, output, epoch));
+    }
+    unprojectTo(coordinate, output, epoch) {
+        return (this.deferred
+            ? this.scalarToLoaded(coordinate, output, true, epoch)
+            : this.unprojectToSync(coordinate, output, epoch));
+    }
+    projectToSync(coordinate, output, epoch) {
+        validateScalarOutput(coordinate, output, coordinate.length);
+        return this.scalar(coordinate, false, epoch, output);
+    }
+    unprojectToSync(coordinate, output, epoch) {
+        validateScalarOutput(coordinate, output, coordinate.length);
+        return this.scalar(coordinate, true, epoch, output);
+    }
+    scalarToLoaded(coordinate, output, inverse, epoch) {
+        validateScalarOutput(coordinate, output, coordinate.length);
+        const input = coordinate.slice();
+        return this.preload().then(() => inverse
+            ? this.unprojectToSync(input, output, epoch)
+            : this.projectToSync(input, output, epoch));
+    }
+    projectFlat(coordinates, dimension = 2, epochs) {
+        return (this.deferred
+            ? this.preload().then(() => this.projectFlatSync(coordinates, dimension, epochs))
+            : this.projectFlatSync(coordinates, dimension, epochs));
+    }
+    unprojectFlat(coordinates, dimension = 2, epochs) {
+        return (this.deferred
+            ? this.preload().then(() => this.unprojectFlatSync(coordinates, dimension, epochs))
+            : this.unprojectFlatSync(coordinates, dimension, epochs));
+    }
+    projectSync(coordinate, epoch) {
+        return this.scalar(coordinate, false, epoch);
+    }
+    unprojectSync(coordinate, epoch) {
+        return this.scalar(coordinate, true, epoch);
+    }
+    projectFlatSync(coordinates, dimension = 2, epochs) {
+        return this.flat(coordinates, dimension, false, epochs);
+    }
+    unprojectFlatSync(coordinates, dimension = 2, epochs) {
+        return this.flat(coordinates, dimension, true, epochs);
+    }
+    compile() {
+        if (this.compiled)
+            return;
+        for (const registration of this.required)
+            if (!getLoadedProjection(registration))
+                unsupportedStage('Pipeline projection requires preload(): ' + registration.name);
+        const forward = this.forwardFactories.map(factory => factory()), inverse = this.inverseFactories.map(factory => factory());
+        this.compiled = {
+            forward: forward.map(pair => pair.forward),
+            inverse: inverse.map(pair => pair.forward),
+            forwardFlat: compileFlat(forward),
+            inverseFlat: compileFlat(inverse)
+        };
+    }
+    operations(inverse) {
+        this.compile();
+        return inverse ? this.compiled.inverse : this.compiled.forward;
+    }
+    scalar(coordinate, inverse, epoch, output) {
+        this.coordinateEpoch(epoch);
+        if (coordinate.length < (this.requiresZ ? 3 : 2))
+            throw new Error('Pipeline requires ' + (this.requiresZ ? 'XYZ' : 'XY') + ' coordinates');
+        const operations = this.operations(inverse);
+        const point = this.coordinateScratch.acquire();
+        try {
+            point.x = coordinate[0];
+            point.y = coordinate[1];
+            point.z = coordinate.length >= 3 ? coordinate[2] : 0;
+            let stack = EMPTY_STACK;
+            if (this.stackSize) {
+                if (point === this.coordinateScratch.point) {
+                    this.coordinateStack || (this.coordinateStack = new Float64Array(this.stackSize));
+                    stack = this.coordinateStack;
+                }
+                else {
+                    stack = new Float64Array(this.stackSize);
+                }
+            }
+            this.run(point, operations, stack, epoch);
+            if (output)
+                return writeScalarOutput(coordinate, output, point, coordinate.length);
+            const result = [...coordinate];
+            result[0] = point.x;
+            result[1] = point.y;
+            if (coordinate.length >= 3)
+                result[2] = point.z;
+            return result;
+        }
+        finally {
+            this.coordinateScratch.release(point);
+        }
+    }
+    flat(coordinates, dimension, inverse, epochs) {
+        if (!(coordinates instanceof Float32Array || coordinates instanceof Float64Array) ||
+            !Number.isSafeInteger(dimension) ||
+            dimension < (this.requiresZ ? 3 : 2) ||
+            coordinates.length % dimension)
+            throw new Error('Pipeline requires Float32Array/Float64Array and a valid XY/XYZ stride');
+        if (epochs === undefined)
+            this.coordinateEpoch(undefined);
+        else if (typeof epochs === 'number')
+            this.coordinateEpoch(epochs);
+        else {
+            if (!(epochs instanceof Float32Array || epochs instanceof Float64Array) ||
+                epochs.length !== coordinates.length / dimension)
+                throw new Error('Epoch buffer requires one Float32/Float64 value per coordinate record');
+            if (epochs.byteOffset < coordinates.byteOffset + coordinates.byteLength &&
+                coordinates.byteOffset < epochs.byteOffset + epochs.byteLength &&
+                (epochs.buffer === coordinates.buffer ||
+                    (sharedBuffer(epochs.buffer) && sharedBuffer(coordinates.buffer))))
+                throw new Error('Epoch and coordinate buffers must not overlap or alias shared storage');
+        }
+        const operations = this.operations(inverse);
+        const specialized = inverse ? this.compiled.inverseFlat : this.compiled.forwardFlat;
+        if (specialized) {
+            specialized(coordinates, dimension, epochs);
+            return coordinates;
+        }
+        const point = this.coordinateScratch.acquire();
+        try {
+            const float32 = coordinates instanceof Float32Array;
+            let stack = EMPTY_STACK;
+            if (this.stackSize) {
+                if (point === this.coordinateScratch.point) {
+                    this.coordinateStack || (this.coordinateStack = new Float64Array(this.stackSize));
+                    stack = this.coordinateStack;
+                }
+                else
+                    stack = new Float64Array(this.stackSize);
+            }
+            const epochBuffer = typeof epochs === 'number' ? undefined : epochs;
+            let epoch = typeof epochs === 'number' ? epochs : undefined;
+            for (let i = 0; i < coordinates.length; i += dimension) {
+                point.x = coordinates[i];
+                point.y = coordinates[i + 1];
+                point.z = dimension >= 3 ? coordinates[i + 2] : 0;
+                if (epochBuffer) {
+                    epoch = epochBuffer[i / dimension];
+                    this.coordinateEpoch(epoch);
+                }
+                this.run(point, operations, stack, epoch);
+                if (float32 &&
+                    Math.max(Math.abs(point.x), Math.abs(point.y), Math.abs(point.z)) > 3.4028234663852886e38)
+                    throw new Error('Pipeline output exceeds Float32 range');
+                coordinates[i] = point.x;
+                coordinates[i + 1] = point.y;
+                if (dimension >= 3)
+                    coordinates[i + 2] = point.z;
+            }
+            return coordinates;
+        }
+        finally {
+            this.coordinateScratch.release(point);
+        }
+    }
+    coordinateEpoch(epoch) {
+        if (epoch === undefined) {
+            if (this.requiresEpoch)
+                throw new Error('Pipeline requires an explicit coordinate epoch');
+        }
+        else if (typeof epoch !== 'number' || !Number.isFinite(epoch))
+            throw new Error('Coordinate epoch must be a finite decimal year');
+    }
+    run(point, operations, stack, epoch) {
+        finite(point);
+        for (const operation of operations) {
+            operation(point, stack, epoch);
+            finite(point);
+        }
+    }
+    balanced(state) {
+        if (state.stacks.some(stack => stack.length))
+            throw new Error('Pipeline stack has unbalanced push/pop operations');
+    }
+    prepare(step, state, options, cache) {
+        const allowed = {
+            unitconvert: ['xy', 'z'],
+            axisswap: ['order'],
+            projection: ['name', 'parameters', 'output'],
+            cart: ['ellipsoid'],
+            helmert: [
+                'translation',
+                'rotation',
+                'scalePPM',
+                'convention',
+                'exact',
+                'referenceEpoch',
+                'rates'
+            ],
+            deformation: ['model', 'sourceEpoch', 'targetEpoch'],
+            push: ['components'],
+            pop: ['components'],
+            hgridshift: ['grids'],
+            vgridshift: ['grids', 'multiplier']
+        };
+        if (!step || !own(allowed, step.type))
+            unsupportedStage('Unsupported pipeline operation: ' + step?.type);
+        keys(step, ['type', 'inverse', 'omitForward', 'omitInverse', ...allowed[step.type]]);
+        if (step.inverse !== undefined && typeof step.inverse !== 'boolean')
+            throw new Error('Invalid pipeline inverse flag');
+        const inverse = Boolean(step.inverse);
+        const orient = (pair) => inverse
+            ? {
+                forward: pair.inverse,
+                inverse: pair.forward,
+                forwardNumeric: pair.inverseNumeric,
+                inverseNumeric: pair.forwardNumeric,
+                forwardFlat: pair.inverseFlat,
+                inverseFlat: pair.forwardFlat
+            }
+            : pair;
+        const pair = (forward, backward, forwardNumeric, inverseNumeric, forwardFlat, inverseFlat) => () => {
+            cache.pair || (cache.pair = {
+                forward,
+                inverse: backward,
+                forwardNumeric,
+                inverseNumeric,
+                forwardFlat,
+                inverseFlat
+            });
+            return orient(cache.pair);
+        };
+        const requireState = (space, expected) => {
+            if (state.space !== space || expected.some((unit, index) => state.units[index] !== unit))
+                throw new Error('Pipeline step ' + step.type + ' requires ' + space + ' ' + expected.join('/'));
+        };
+        switch (step.type) {
+            case 'unitconvert': {
+                if (!step.xy && !step.z)
+                    throw new Error('Empty unit conversion');
+                const scale = [1, 1, 1];
+                for (const [conversion, indices] of [
+                    [step.xy, [0, 1]],
+                    [step.z, [2]]
+                ]) {
+                    if (!conversion)
+                        continue;
+                    keys(conversion, ['from', 'to']);
+                    const { from, to } = conversion;
+                    if (!own(factors, from) || !own(factors, to) || angular(from) !== angular(to))
+                        throw new Error('Incompatible pipeline units');
+                    for (const index of indices) {
+                        if (state.units[index] !== (inverse ? to : from))
+                            throw new Error('Pipeline unit mismatch');
+                        state.units[index] = inverse ? from : to;
+                        scale[index] = factors[from] / factors[to];
+                    }
+                }
+                this.requiresZ || (this.requiresZ = Boolean(step.z));
+                const [xScale, yScale, zScale] = scale;
+                return pair(p => {
+                    p.x *= xScale;
+                    p.y *= yScale;
+                    p.z *= zScale;
+                }, p => {
+                    p.x /= xScale;
+                    p.y /= yScale;
+                    p.z /= zScale;
+                }, [0, xScale, yScale, zScale], [1, xScale, yScale, zScale]);
+            }
+            case 'axisswap': {
+                const order = [...step.order];
+                if (![2, 3].includes(order.length) ||
+                    order.some(index => !Number.isInteger(index) || Math.abs(index) < 1 || Math.abs(index) > order.length) ||
+                    new Set(order.map(Math.abs)).size !== order.length)
+                    throw new Error('Axis order must be a signed permutation');
+                if (order.length === 2)
+                    order.push(3);
+                this.requiresZ || (this.requiresZ = step.order.length === 3);
+                const reverse = [0, 0, 0];
+                order.forEach((index, target) => {
+                    reverse[Math.abs(index) - 1] = Math.sign(index) * (target + 1);
+                });
+                const selected = inverse ? reverse : order;
+                state.units = selected.map(index => state.units[Math.abs(index) - 1]);
+                const operation = (indices) => {
+                    const [a, b, c] = indices.map(Math.abs);
+                    const [sx, sy, sz] = indices.map(Math.sign);
+                    return p => {
+                        const { x, y, z } = p;
+                        p.x = sx * (a === 1 ? x : a === 2 ? y : z);
+                        p.y = sy * (b === 1 ? x : b === 2 ? y : z);
+                        p.z = sz * (c === 1 ? x : c === 2 ? y : z);
+                    };
+                };
+                return pair(operation(order), operation(reverse), [2, order[0], order[1], order[2]], [2, reverse[0], reverse[1], reverse[2]]);
+            }
+            case 'projection': {
+                const output = step.output === undefined ? { space: 'projected', unit: 'm' } : { ...step.output };
+                keys(output, ['space', 'unit']);
+                if (output.space === 'geographic'
+                    ? !['rad', 'deg'].includes(output.unit)
+                    : output.space !== 'projected' || output.unit !== 'm')
+                    throw new Error('Invalid projection output space/unit contract');
+                requireState(inverse ? output.space : 'geographic', inverse ? [output.unit, output.unit] : ['rad', 'rad']);
+                state.space = inverse ? 'geographic' : output.space;
+                state.units[0] = state.units[1] = inverse ? 'rad' : output.unit;
+                const key = (name) => name.toLowerCase().replace(/[\s_-]/g, '');
+                if (typeof step.name !== 'string')
+                    throw new Error('Invalid projection name');
+                const registration = options.projections?.find(p => [p.name, ...(p.aliases || [])].some(name => key(name) === key(step.name)));
+                if (!registration)
+                    unsupportedStage('Pipeline projection is not registered: ' + step.name);
+                if (!this.required.includes(registration))
+                    this.required.push(registration);
+                const parameters = { ...step.parameters };
+                for (const name of Object.keys(parameters))
+                    if (CORE_PARAMETERS.includes(name) && !geometryKeys.includes(name) && name !== 'over')
+                        unsupportedStage('Unsupported pipeline parameter: ' + name);
+                const oblique = key(registration.name) === 'obtran';
+                const geographicChild = ['longlat', 'latlong', 'latlon', 'lonlat', 'identity'].includes(key(parameters['o_proj'] || ''));
+                if (oblique && (!step.output || !parameters['o_proj']))
+                    unsupportedStage('Oblique helper pipelines require an explicit output-unit contract and o_proj');
+                if ((oblique && geographicChild) !== (output.space === 'geographic'))
+                    throw new Error('Projection output contract does not match its algorithm');
+                const scale = geographicChild && output.unit === 'rad' ? Math.PI / 180 : 1;
+                const normalized = normalizeCRS(definition(registration.name, parameters));
+                if (normalized.kind !== 'projected')
+                    unsupportedStage('Use a cart step for geocentric conversion');
+                return () => {
+                    if (cache.pair)
+                        return orient(cache.pair);
+                    const plugin = getLoadedProjection(registration);
+                    if (!plugin)
+                        unsupportedStage('Pipeline projection requires preload(): ' + registration.name);
+                    if ((key(plugin.name) === 'obtran') !== oblique)
+                        unsupportedStage('Pipeline projection requires a matching projected-metre output contract: ' +
+                            plugin.name);
+                    if ([
+                        'geocent',
+                        'geocentric',
+                        'identity',
+                        'longlat',
+                        'latlong',
+                        'latlon',
+                        'lonlat'
+                    ].includes(key(plugin.name)))
+                        unsupportedStage('Pipeline projection requires a projected-metre output contract: ' + plugin.name);
+                    keys(parameters, [...geometryKeys, 'over', ...plugin.parameters]);
+                    for (const [name, value] of Object.entries(parameters)) {
+                        const flag = name === 'over' || plugin.flags?.includes(name);
+                        if (flag && value !== undefined)
+                            throw new Error('Expected a flag without a value: ' + name);
+                        if (!flag && value === undefined)
+                            throw new Error('Pipeline parameter requires a value: ' + name);
+                    }
+                    const implementation = plugin.create({
+                        parameters: { ...normalized.parameters, proj: plugin.name },
+                        semiMajorAxis: normalized.ellipsoid.semiMajorAxis,
+                        semiMinorAxis: normalized.ellipsoid.semiMinorAxis,
+                        eccentricitySquared: normalized.ellipsoid.eccentricitySquared
+                    });
+                    const forward = projectionOperation(implementation, false), backward = projectionOperation(implementation, true);
+                    cache.pair = oblique
+                        ? {
+                            forward: p => {
+                                if (Math.abs(p.y) > Math.PI / 2)
+                                    throw new Error('Invalid geographic latitude');
+                                forward(p);
+                                p.x *= scale;
+                                p.y *= scale;
+                            },
+                            inverse: p => {
+                                if (geographicChild && Math.abs(p.y) > (output.unit === 'deg' ? 90 : Math.PI / 2))
+                                    throw new Error('Invalid rotated geographic latitude');
+                                p.x /= scale;
+                                p.y /= scale;
+                                backward(p);
+                            }
+                        }
+                        : { forward, inverse: backward };
+                    return orient(cache.pair);
+                };
+            }
+            case 'cart': {
+                requireState(inverse ? 'geocentric' : 'geographic', inverse ? ['m', 'm', 'm'] : ['rad', 'rad', 'm']);
+                state.space = inverse ? 'geographic' : 'geocentric';
+                state.units = inverse ? ['rad', 'rad', 'm'] : ['m', 'm', 'm'];
+                this.requiresZ = true;
+                keys(step.ellipsoid || {}, geometryKeys);
+                const ellipsoid = normalizeCRS(definition('longlat', step.ellipsoid)).ellipsoid;
+                return pair(p => geodeticToGeocentricInPlace(p, ellipsoid), p => geocentricToGeodeticInPlace(p, ellipsoid));
+            }
+            case 'helmert': {
+                requireState('geocentric', ['m', 'm', 'm']);
+                this.requiresZ = true;
+                triple(step.translation);
+                if (step.rotation)
+                    triple(step.rotation);
+                if ((step.rotation || step.rates?.rotation) && !step.convention)
+                    throw new Error('Helmert rotation requires a convention');
+                if (step.convention !== undefined &&
+                    !['position_vector', 'coordinate_frame'].includes(step.convention))
+                    throw new Error('Invalid Helmert convention');
+                const scale = step.scalePPM ?? 0;
+                if (!Number.isFinite(scale) || scale <= -1e6)
+                    throw new Error('Helmert requires positive finite scale');
+                if (step.exact !== undefined && typeof step.exact !== 'boolean')
+                    throw new Error('Invalid exact Helmert flag');
+                if (step.rates !== undefined) {
+                    keys(step.rates, ['translation', 'rotation', 'scalePPM']);
+                    if (step.rates.translation === undefined &&
+                        step.rates.rotation === undefined &&
+                        step.rates.scalePPM === undefined)
+                        throw new Error('Helmert rates require at least one parameter');
+                    if (step.rates.translation !== undefined)
+                        triple(step.rates.translation);
+                    if (step.rates.rotation !== undefined)
+                        triple(step.rates.rotation);
+                    if (step.rates.scalePPM !== undefined && !Number.isFinite(step.rates.scalePPM))
+                        throw new Error('Helmert scale rate must be finite');
+                    if (typeof step.referenceEpoch !== 'number' || !Number.isFinite(step.referenceEpoch))
+                        throw new Error('Helmert rates require a finite referenceEpoch');
+                    this.requiresEpoch = true;
+                    const operation = createKinematicHelmert(step.translation, step.rotation || [0, 0, 0], scale, step.rates, step.referenceEpoch, step.convention === 'coordinate_frame', Boolean(step.exact));
+                    return pair((p, _stack, epoch) => operation.forward(p, epoch), (p, _stack, epoch) => operation.inverse(p, epoch), undefined, undefined, operation.forwardFlat, operation.inverseFlat);
+                }
+                if (step.referenceEpoch !== undefined)
+                    throw new Error('Helmert referenceEpoch requires rates');
+                if (step.exact) {
+                    const exact = createExactHelmert(step.translation, step.rotation || [0, 0, 0], scale, step.convention === 'coordinate_frame');
+                    return pair(exact.forward, exact.inverse, undefined, undefined, createHelmertFlat(exact.coefficients, false, true), createHelmertFlat(exact.coefficients, true, true));
+                }
+                const sign = step.convention === 'coordinate_frame' ? -1 : 1;
+                const values = [
+                    ...step.translation,
+                    ...(step.rotation || [0, 0, 0]).map(value => sign * value),
+                    scale
+                ];
+                const radians = Math.PI / (180 * 3600);
+                const coefficients = [
+                    (values[3] || 0) * radians,
+                    (values[4] || 0) * radians,
+                    (values[5] || 0) * radians,
+                    0,
+                    0,
+                    0,
+                    0,
+                    0,
+                    0,
+                    values[0],
+                    values[1],
+                    values[2],
+                    1 + (values[6] || 0) / 1e6
+                ];
+                return pair(createHelmert(values, false), createHelmert(values, true), undefined, undefined, createHelmertFlat(coefficients, false, false), createHelmertFlat(coefficients, true, false));
+            }
+            case 'deformation': {
+                requireState('geocentric', ['m', 'm', 'm']);
+                this.requiresZ = true;
+                const source = step.sourceEpoch, target = step.targetEpoch;
+                if ((source !== 'coordinate' && (typeof source !== 'number' || !Number.isFinite(source))) ||
+                    typeof target !== 'number' ||
+                    !Number.isFinite(target))
+                    throw new Error('Explicit finite deformation source/target epochs required');
+                if (!step.model ||
+                    typeof step.model.forward !== 'function' ||
+                    typeof step.model.inverse !== 'function')
+                    throw new Error('Prepared deformation model required');
+                this.requiresEpoch || (this.requiresEpoch = source === 'coordinate');
+                const forward = step.model.forward.bind(step.model), backward = step.model.inverse.bind(step.model);
+                return pair((p, _stack, epoch) => forward(p, source === 'coordinate' ? epoch : source, target), (p, _stack, epoch) => backward(p, source === 'coordinate' ? epoch : source, target));
+            }
+            case 'push':
+            case 'pop': {
+                if (!Array.isArray(step.components) ||
+                    !step.components.length ||
+                    step.components.some(component => !Number.isInteger(component) || component < 1 || component > 3) ||
+                    new Set(step.components).size !== step.components.length)
+                    throw new Error('Stack components must be distinct ordinates 1, 2 or 3');
+                const components = [...step.components];
+                this.requiresZ || (this.requiresZ = components.includes(3));
+                const pushing = (step.type === 'push') !== inverse;
+                const entries = components.map(component => {
+                    const index = component - 1;
+                    if (pushing) {
+                        const entry = { unit: state.units[index], space: state.space, slot: this.stackSize++ };
+                        state.stacks[index].push(entry);
+                        return entry;
+                    }
+                    const entry = state.stacks[index].pop();
+                    if (!entry)
+                        throw new Error('Pipeline stack underflow for ordinate ' + component);
+                    return entry;
+                });
+                if (!pushing) {
+                    const horizontal = components
+                        .map((component, index) => ({ component, entry: entries[index] }))
+                        .filter(({ component }) => component < 3);
+                    const space = horizontal[0]?.entry.space || state.space;
+                    if (horizontal.some(({ entry }) => entry.space !== space) ||
+                        (horizontal.length === 1 && space !== state.space))
+                        throw new Error('Stack restore would mix horizontal coordinate spaces');
+                    state.space = space;
+                    components.forEach((component, index) => {
+                        state.units[component - 1] = entries[index].unit;
+                    });
+                }
+                const save = (p, stack) => {
+                    for (let index = 0; index < components.length; index++)
+                        stack[entries[index].slot] =
+                            components[index] === 1 ? p.x : components[index] === 2 ? p.y : p.z;
+                };
+                const restore = (p, stack) => {
+                    for (let index = 0; index < components.length; index++) {
+                        const value = stack[entries[index].slot];
+                        if (components[index] === 1)
+                            p.x = value;
+                        else if (components[index] === 2)
+                            p.y = value;
+                        else
+                            p.z = value;
+                    }
+                };
+                // Unlike equations, stack slots are direction-local and must not use the
+                // shared pair cache. Their matching push is known at construction.
+                return () => pushing ? { forward: save, inverse: restore } : { forward: restore, inverse: save };
+            }
+            case 'hgridshift': {
+                requireState('geographic', ['rad', 'rad']);
+                if (typeof step.grids !== 'string')
+                    throw new Error('Horizontal grid names required');
+                const crs = normalizeCRS(definition('longlat', { nadgrids: step.grids }));
+                // Normalization collapses sole null/@null lists to no datum-grid metadata.
+                if (!crs.datum.grids)
+                    return pair(() => { }, () => { });
+                const grids = crs.datum.grids.map(reference => {
+                    const grid = own(options.datumGrids || {}, reference.name)
+                        ? options.datumGrids[reference.name]
+                        : undefined;
+                    if (reference.name !== 'null' && !grid && !reference.optional)
+                        unsupportedStage('Required datum grid is not registered: ' + reference.name);
+                    if (grid && typeof grid.shift !== 'function')
+                        throw new Error('Invalid datum grid: ' + reference.name);
+                    return { ...reference, grid };
+                });
+                const datum = { ...crs.datum, grids };
+                return pair(p => applyDatumGrids(p, datum, false), p => applyDatumGrids(p, datum, true));
+            }
+            case 'vgridshift': {
+                requireState('geographic', ['rad', 'rad', 'm']);
+                this.requiresZ = true;
+                if (typeof step.grids !== 'string')
+                    throw new Error('Vertical grid names required');
+                const offset = compileVerticalGrid(step.grids, options.verticalGrids);
+                const multiplier = step.multiplier ?? -1;
+                if (!Number.isFinite(multiplier))
+                    throw new Error('Vertical grid multiplier must be finite');
+                return pair(p => {
+                    p.z += multiplier * offset(p.x, p.y);
+                }, p => {
+                    p.z -= multiplier * offset(p.x, p.y);
+                });
+            }
+            default:
+                throw new Error('Unsupported pipeline step');
+        }
+    }
+}
+//# sourceMappingURL=projection-pipeline.js.map