gis-tools-ts/dist/geometry/id.d.ts

A collection of geospatial tools primarily designed for WGS84, Web Mercator, and S2.

import type { LonLat } from './ll/index.js';
import type { BBox, Face, MValue, Properties, VectorPoint } from './index.js';
/**
 * An S2CellId is a 64-bit unsigned integer that uniquely identifies a
 * cell in the S2 cell decomposition.  It has the following format:
 *
 *   id = [face][face_pos]
 *
 *   face:     a 3-bit number (range 0..5) encoding the cube face.
 *
 *   face_pos: a 61-bit number encoding the position of the center of this
 *             cell along the Hilbert curve over this face (see the Wiki
 *             pages for details).
 *
 * Sequentially increasing cell ids follow a continuous space-filling curve
 * over the entire sphere.  They have the following properties:
 *
 *  - The id of a cell at level k consists of a 3-bit face number followed
 *    by k bit pairs that recursively select one of the four children of
 *    each cell.  The next bit is always 1, and all other bits are 0.
 *    Therefore, the level of a cell is determined by the position of its
 *    lowest-numbered bit that is turned on (for a cell at level k, this
 *    position is 2 * (kMaxLevel - k).)
 *
 *  - The id of a parent cell is at the midpoint of the range of ids spanned
 *    by its children (or by its descendants at any level).
 *
 * Leaf cells are often used to represent points on the unit sphere, and
 * this class provides methods for converting directly between these two
 * representations.  For cells that represent 2D regions rather than
 * discrete point, it is better to use the S2Cell class.
 *
 * This class is intended to be copied by value as desired.  It uses
 * the default copy constructor and assignment operator.
 */
export type S2CellId = bigint;
export declare const K_FACE_BITS = 3;
export declare const FACE_BITS = 3n;
export declare const K_NUM_FACES = 6;
export declare const NUM_FACES = 6n;
export declare const K_MAX_LEVEL = 30;
export declare const MAX_LEVEL = 30n;
export declare const POS_BITS = 61n;
export declare const K_WRAP_OFFSET = 13835058055282163712n;
export declare const K_MAX_SIZE = 1073741824;
/**
 * Create a default S2CellID given a face on the sphere [0-6)
 * @param face - the face
 * @returns the S2CellID
 */
export declare function idFromFace(face: Face): S2CellId;
/**
 * Return a cell given its face (range 0..5), Hilbert curve position within
 * that face (an unsigned integer with S2CellId::kPosBits bits), and level
 * (range 0..kMaxLevel).  The given position will be modified to correspond
 * to the Hilbert curve position at the center of the returned cell. This
 * is a static function rather than a constructor in order to indicate what
 * the arguments represent.
 * @param face - the face
 * @param pos - the Hilbert curve position
 * @param level - the level
 * @returns the S2CellID
 */
export declare function idFromFacePosLevel(face: Face, pos: bigint, level: number): S2CellId;
/**
 * Create an S2CellID from a lon-lat coordinate
 * @param ll - lon-lat vector point in degrees
 * @returns the S2CellID
 */
export declare function idFromLonLat(ll: LonLat): S2CellId;
/**
 * Create an S2CellID from an XYZ Point
 * @param xyz - 3D input vector
 * @param level - zoom level
 * @returns the S2CellID
 */
export declare function idFromS2Point(xyz: VectorPoint, level?: number): S2CellId;
/**
 * Create an S2CellID from an Face-U-V coordinate
 * @param face - the face
 * @param u - u coordinate
 * @param v - v coordinate
 * @param level - zoom level
 * @param uvToST - function to convert U-V to S-T [Default is UVtoST (quadraticUVtoST)]
 * @returns the S2CellID
 */
export declare function idFromUV(face: Face, u: number, v: number, level?: number, uvToST?: (u: number) => number): S2CellId;
/**
 * Create an S2CellID from an Face-S-T coordinate.
 * @param face - the face
 * @param s - s coordinate
 * @param t - t coordinate
 * @param level - zoom level
 * @returns the S2CellID
 */
export declare function idFromST(face: Face, s: number, t: number, level?: number): S2CellId;
/**
 * Create an S2CellID given a distance and level (zoom). Default level is 30n
 * @param distance - distance
 * @param level - level
 * @returns the S2CellID
 */
export declare function idFromDistance(distance: bigint, level?: bigint): S2CellId;
/**
 * @param id - the S2CellID
 * @returns [face, zoom, i, j]
 */
export declare function idToFaceIJ(id: S2CellId): [face: Face, zoom: number, i: number, j: number];
/**
 * Create an S2CellID from an Face-I-J coordinate and map it to a zoom if desired.
 * @param face - the face
 * @param i - i coordinate
 * @param j - j coordinate
 * @param level - zoom level
 * @returns the S2CellID
 */
export declare function idFromIJ(face: Face, i: number, j: number, level?: number): S2CellId;
/**
 * Convert an S2CellID to a Face-I-J coordinate and provide its orientation.
 * If a level is provided, the I-J coordinates will be shifted to that level.
 * @param id - the S2CellID
 * @param level - zoom level
 * @returns face-i-j with orientation
 */
export declare function idToIJ(id: S2CellId, level?: number): [face: Face, i: number, j: number, orientation: number];
/**
 * Convert an S2CellID to an Face-S-T coordinate
 * @param id - the S2CellID
 * @returns face-s-t coordinate associated with the S2CellID
 */
export declare function idToST(id: S2CellId): [face: Face, s: number, t: number];
/**
 * Convert an S2CellID to an Face-U-V coordinate
 * @param id - the S2CellID
 * @returns face-u-v coordinate associated with the S2CellID
 */
export declare function idToUV(id: S2CellId): [face: Face, u: number, v: number];
/**
 * Convert an S2CellID to an lon-lat coordinate
 * @param id - the S2CellID
 * @param m - M-Value
 * @returns lon-lat coordinates
 */
export declare function idToLonLat<M extends MValue = Properties>(id: S2CellId, m?: M): LonLat<M>;
/**
 * Convert an S2CellID to an XYZ Point
 * @param id - the S2CellID
 * @param m - M-Value
 * @returns a 3D vector
 */
export declare function idToS2Point<M extends MValue = Properties>(id: S2CellId, m?: M): VectorPoint<M>;
/**
 * Given an S2CellID, get the face it's located in
 * @param id - the S2CellID
 * @returns face of the cell
 */
export declare function idFace(id: S2CellId): Face;
/**
 * Given an S2CellID, check if it is a Face Cell.
 * @param id - the S2CellID
 * @returns true if the cell is a face (lowest zoom level)
 */
export declare function idIsFace(id: S2CellId): boolean;
/**
 * Given an S2CellID, find the quad tree position [0-4) it's located in
 * @param id - the S2CellID
 * @returns quad tree position
 */
export declare function idPos(id: S2CellId): S2CellId;
/**
 * Given an S2CellID, find the level (zoom) its located in
 * @param id - the S2CellID
 * @returns zoom level
 */
export declare function idLevel(id: S2CellId): number;
/**
 * Given an S2CellID, get the distance it spans (or length it covers)
 * @param id - the S2CellID
 * @param lev - optional zoom level
 * @returns distance
 */
export declare function idDistance(id: S2CellId, lev?: number): bigint;
/**
 * Given an S2CellID, get the quad child tile of your choice [0, 4)
 *
 * @param id - the S2CellID
 * @param pos - quad position 0, 1, 2, or 3
 * @returns the child tile at that position
 */
export declare function idChild(id: S2CellId, pos: 0n | 1n | 2n | 3n): S2CellId;
/**
 * Given an S2CellID, get all the quad children tiles
 * @param id - the S2CellID
 * @param orientation - orientation of the child (0 or 1)
 * @returns the child tile at that position
 */
export declare function idChildren(id: S2CellId, orientation?: number): [S2CellId, S2CellId, S2CellId, S2CellId];
/**
 * Given a Face-level-i-j coordinate, get all its quad children tiles
 * @param face - the Face
 * @param level - zoom level
 * @param i - i coordinate
 * @param j - j coordinate
 * @returns the child tile at that position
 */
export declare function idChildrenIJ(face: Face, level: number, i: number, j: number): [blID: S2CellId, brID: S2CellId, tlID: S2CellId, trID: S2CellId];
/**
 * Given an S2CellID, get the quad position relative to its parent
 * @param id - the S2CellID
 * @param level - zoom level
 * @returns the child tile at that position
 */
export declare function idChildPosition(id: S2CellId, level: number): number;
/**
 * Given an S2CellID, get the parent quad tile
 * @param id - the S2CellID
 * @param level - zoom level
 * @returns the parent of the input S2CellID
 */
export declare function idParent(id: S2CellId, level?: number): S2CellId;
/**
 * given an id and level, return the id of the parent level
 * @param id - the S2CellID
 * @param level - zoom level
 * @returns - the parent of the input S2CellID
 */
export declare function idParentLevel(id: S2CellId, level: bigint): S2CellId;
/**
 * Given an S2CellID, get the hilbert range it spans
 * @param id - the S2CellID
 * @returns [min, max]
 */
export declare function idRange(id: S2CellId): [min: S2CellId, max: S2CellId];
/**
 * Check if the first S2CellID contains the second.
 * @param a - the first S2CellID
 * @param b - the second S2CellID
 * @returns true if a contains b
 */
export declare function idContains(a: S2CellId, b: S2CellId): boolean;
/**
 * @param a - the first S2CellID
 * @param p - the second VectorPoint
 * @returns true if a contains p
 */
export declare function idContainsS2Point(a: S2CellId, p: VectorPoint): boolean;
/**
 * Check if an S2CellID intersects another. This includes edges touching.
 * @param a - the first S2CellID
 * @param b - the second S2CellID
 * @returns true if a intersects b
 */
export declare function idIntersects(a: S2CellId, b: S2CellId): boolean;
/**
 * Get the next S2CellID in the hilbert space
 * @param id - input S2CellID
 * @returns the next S2CellID in the hilbert space
 */
export declare function idNext(id: S2CellId): S2CellId;
/**
 * Get the previous S2CellID in the hilbert space
 * @param id - input S2CellID
 * @returns the previous S2CellID in the hilbert space
 */
export declare function idPrev(id: S2CellId): S2CellId;
/**
 * Check if the S2CellID is a leaf value. This means it's the smallest possible cell
 * @param id - input S2CellID
 * @returns true if the S2CellID is a leaf
 */
export declare function idIsLeaf(id: S2CellId): boolean;
/**
 * Given an S2CellID and level (zoom), get the center point of that cell in S-T space
 * @param id - the S2CellID
 * @returns [face, s, t]
 */
export declare function idCenterST(id: S2CellId): [face: Face, s: number, t: number];
/**
 * Given an S2CellID and level (zoom), get the S-T bounding range of that cell
 * @param id - the S2CellID
 * @param lev - zoom level
 * @returns [sMin, tMin, sMax, tMax]
 */
export declare function idBoundsST(id: S2CellId, lev?: number): BBox;
/**
 * Return the range maximum of a level (zoom) in S-T space
 * @param level - zoom level
 * @returns sMax or tMax
 */
export declare function idSizeST(level: number): number;
/**
 * Return the range maximum of a level (zoom) in I-J space
 * @param level - zoom level
 * @returns iMax or jMax
 */
export declare function idSizeIJ(level: number): number;
/**
 * Given an S2CellID, find the neighboring S2CellIDs
 * @param id - the S2CellID
 * @returns [up, right, down, left]
 */
export declare function idNeighbors(id: S2CellId): [S2CellId, S2CellId, S2CellId, S2CellId];
/**
 * Given a Face-I-J and a desired level (zoom), find the neighboring S2CellIDs
 * @param face - the Face
 * @param i - the I coordinate
 * @param j - the J coordinate
 * @param level - the zoom level (desired)
 * @returns neighbors: [down, right, up, left]
 */
export declare function idNeighborsIJ(face: Face, i: number, j: number, level: number): [S2CellId, S2CellId, S2CellId, S2CellId];
/**
 * Build an S2CellID given a Face-I-J, but ensure the face is the same if desired
 * @param face - the Face
 * @param i - the I coordinate
 * @param j - the J coordinate
 * @param sameFace - if the face should be the same
 * @returns the S2CellID
 */
export declare function idFromIJSame(face: Face, i: number, j: number, sameFace: boolean): S2CellId;
/**
 * Build an S2CellID given a Face-I-J, but ensure it's a legal value, otherwise wrap before creation
 * @param face - the Face
 * @param i - the I coordinate
 * @param j - the J coordinate
 * @returns the S2CellID
 */
export declare function idFromIJWrap(face: Face, i: number, j: number): S2CellId;
/**
 * Given an S2CellID, find it's nearest neighbors associated with it
 * @param id - the S2CellID
 * @param lev - the zoom level (if not provided, defaults to current level of id)
 * @returns neighbors
 */
export declare function idVertexNeighbors(id: S2CellId, lev?: number): S2CellId[];
/** The four vertices of the cell. */
export type Vertices = [VectorPoint, VectorPoint, VectorPoint, VectorPoint];
/**
 * Returns the four vertices of the cell.  Vertices are returned
 * in CCW order (lower left, lower right, upper right, upper left in the UV
 * plane).  The points returned by getVertices are pointNd.
 * @param id - the S2CellID
 * @returns the k-th vertex of the cell
 */
export declare function idGetVertices(id: S2CellId): Vertices;
/**
 * Returns the k-th vertex of the cell (k = 0,1,2,3).  Vertices are returned
 * in CCW order (lower left, lower right, upper right, upper left in the UV
 * plane).  The points returned by getVerticesRaw are not normalized.
 * @param id - the S2CellID
 * @returns the k-th vertex of the cell
 */
export declare function idGetVerticesRaw(id: S2CellId): Vertices;
/**
 * Returns the inward-facing normal of the great circle passing through the
 * edge from vertex k to vertex k+1 (mod 4). The normals returned by
 * getEdges will be unit length.
 * @param id - the S2CellID
 * @returns the 4 edges of the cell normalized
 */
export declare function idGetEdges(id: S2CellId): Vertices;
/**
 * Returns the inward-facing normal of the great circle passing through the
 * edge from vertex k to vertex k+1 (mod 4). The normals returned by
 * getEdgesRaw are not necessarily unit length.
 * @param id - the S2CellID
 * @returns the 4 edges of the cell
 */
export declare function idGetEdgesRaw(id: S2CellId): Vertices;
/**
 * Return the bounds of this cell in (u,v)-space.
 * @param id - the S2CellID
 * @returns the bounds [uLow, uHigh, vLow, vHigh]
 */
export declare function idGetBoundUV(id: S2CellId): BBox;
/**
 * Return the edge length of this cell in (i,j)-space.
 * @param id - the S2CellID
 * @returns the edge length
 */
export declare function idGetSizeIJ(id: S2CellId): number;
/**
 * @param a - the first cell
 * @param b - the second cell
 * @returns -1 | 0 | 1
 */
export declare function compareIDs(a: S2CellId, b: S2CellId): -1 | 0 | 1;
/**
 * Check if the tile is not a real world tile that fits inside a WM quad tree
 * Out of bounds tiles exist if the map has `duplicateHorizontally` set to true.
 * This is useful for filling in the canvas on the x axis instead of leaving it blank.
 * @param id - a tile ID
 * @returns - true if the id is out of bounds for WM
 */
export declare function isOutOfBoundsWM(id: bigint): boolean;
//# sourceMappingURL=id.d.ts.map