@thi.ng/morton/zcurve.d.ts

Z-order curve / Morton encoding, decoding & range extraction for arbitrary dimensions

import type { NumericArray, Range1_32, Range1_64, RangeValueMap } from "@thi.ng/api";
export type Range2_64 = Exclude<Range1_64, 1>;
/**
 * Z-Curve encoder/decoder and optimized bbox range extraction for
 * arbitrary dimensions (>= 2). Supports max. 32bit per-component value
 * range and resulting Morton codes encoded as `BigInt`.
 */
export declare class ZCurve<T extends Range2_64> {
    /**
     * Encodes a single nD point component as partial Z index.
     *
     * @param x - component value
     * @param bits - bits per component
     * @param dims - number of dimensions
     * @param offset - bit offset (for curr dimension)
     * @param out - existing partial Z result
     */
    static encodeComponent(x: number, bits: number, dims: number, offset: number, out?: bigint): bigint;
    /**
     * Decodes a single nD component from given Z index.
     *
     * @param z - Z index
     * @param bits - bits per component
     * @param dims - number of dimensions
     * @param offset - bit offset (for curr dimension)
     */
    static decodeComponent(z: bigint, bits: number, dims: number, offset: number): number;
    dim: T;
    bits: number;
    order: ArrayLike<number>;
    masks: bigint[];
    wipeMasks: bigint[];
    /**
     * @param dim - dimensions
     * @param bits - number of bits per component
     * @param order - component ordering
     */
    constructor(dim: T, bits: Range1_32, order?: ArrayLike<RangeValueMap[T]>);
    /**
     * Encodes given nD point as Z index.
     *
     * @param p - point to encode
     */
    encode(p: ArrayLike<number>): bigint;
    /**
     * Decodes given Z index into point coordinates.
     *
     * @param z - Z index
     * @param out - optional result array
     */
    decode(z: bigint, out?: NumericArray): NumericArray;
    /**
     * Decomposes given Z index into individual bit patterns, one per
     * dimension.
     *
     * @remarks
     *
     *
     * @param z -
     * @param out -
     */
    split(z: bigint, out?: bigint[]): bigint[];
    merge(zparts: bigint[]): bigint;
    /**
     * Yields iterator of Z-curve indices in given nD bounding box.
     *
     * @remarks
     * Uses {@link ZCurve.pointInBox} and {@link ZCurve.bigMin} to efficiently
     * skip Z index sub-ranges outside the box.
     *
     * References:
     * - https://en.wikipedia.org/wiki/Z-order_curve#Use_with_one-dimensional_data_structures_for_range_searching
     * - https://aws.amazon.com/blogs/database/z-order-indexing-for-multifaceted-queries-in-amazon-dynamodb-part-1/
     * - https://aws.amazon.com/blogs/database/z-order-indexing-for-multifaceted-queries-in-amazon-dynamodb-part-2/
     *
     * @param rmin - bbox min point
     * @param rmax - bbox max point
     */
    range(rmin: ArrayLike<number>, rmax: ArrayLike<number>): Generator<bigint, void, unknown>;
    /**
     * Computes the next valid Z index in bbox defined by `zmin` / `zmax` and
     * greater than `zcurr`. Returns -1 if no further indices are in the box.
     *
     * @remarks
     * Partially based on:
     * https://github.com/statgen/LDServer/blob/develop/core/src/Morton.cpp#L38
     *
     * @param zcurr -
     * @param zmin -
     * @param zmax -
     */
    bigMin(zcurr: bigint, zmin: bigint, zmax: bigint): bigint;
    pointInBox(p: ArrayLike<number>, rmin: ArrayLike<number>, rmax: ArrayLike<number>): boolean;
    protected initMasks(): void;
    protected loadBits(mask: number, bitPos: number, z: bigint): bigint;
}
export declare class ZCurve2 extends ZCurve<2> {
    constructor(bits: Range1_32, order?: ArrayLike<RangeValueMap[2]>);
    encode(p: ArrayLike<number>): bigint;
    decode(z: bigint, out?: NumericArray): NumericArray;
    pointInBox(p: ArrayLike<number>, rmin: ArrayLike<number>, rmax: ArrayLike<number>): boolean;
}
export declare class ZCurve3 extends ZCurve<3> {
    constructor(bits: Range1_32, order?: ArrayLike<RangeValueMap[3]>);
    encode(p: ArrayLike<number>): bigint;
    decode(z: bigint, out?: NumericArray): NumericArray;
    pointInBox(p: ArrayLike<number>, rmin: ArrayLike<number>, rmax: ArrayLike<number>): boolean;
}
//# sourceMappingURL=zcurve.d.ts.map