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

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

import type { BBox, Face, Point3D } from '.';
/**
 * 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 fromFace(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 fromFacePosLevel(face: Face, pos: bigint, level: number): S2CellId;
/**
 * Create an S2CellID from a lon-lat coordinate
 * @param lon - longitude
 * @param lat - latitude
 * @returns the S2CellID
 */
export declare function fromLonLat(lon: number, lat: number): S2CellId;
/**
 * Create an S2CellID from an XYZ Point
 * @param xyz - 3D input vector
 * @returns the S2CellID
 */
export declare function fromS2Point(xyz: Point3D): S2CellId;
/**
 * Create an S2CellID from an Face-U-V coordinate
 * @param face - the face
 * @param u - u coordinate
 * @param v - v coordinate
 * @returns the S2CellID
 */
export declare function fromUV(face: Face, u: number, v: number): S2CellId;
/**
 * Create an S2CellID from an Face-S-T coordinate
 * @param face - the face
 * @param s - s coordinate
 * @param t - t coordinate
 * @returns the S2CellID
 */
export declare function fromST(face: Face, s: number, t: 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 fromDistance(distance: bigint, level?: bigint): S2CellId;
/**
 * @param id - the S2CellID
 * @returns [face, zoom, i, j]
 */
export declare function toFaceIJ(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 fromIJ(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 toIJ(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 toST(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 toUV(id: S2CellId): [face: Face, u: number, v: number];
/**
 * Convert an S2CellID to an lon-lat coordinate
 * @param id - the S2CellID
 * @returns lon-lat coordinates
 */
export declare function toLonLat(id: S2CellId): [lon: number, lat: number];
/**
 * Convert an S2CellID to an XYZ Point
 * @param id - the S2CellID
 * @returns a 3D vector
 */
export declare function toS2Point(id: S2CellId): Point3D;
/**
 * Given an S2CellID, get the face it's located in
 * @param id - the S2CellID
 * @returns face of the cell
 */
export declare function face(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 isFace(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 pos(id: S2CellId): S2CellId;
/**
 * Given an S2CellID, find the level (zoom) its located in
 * @param id - the S2CellID
 * @returns zoom level
 */
export declare function level(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 distance(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 child(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 children(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 childrenIJ(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 childPosition(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 parent(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 parentLevel(id: S2CellId, level: bigint): S2CellId;
/**
 * Given an S2CellID, get the hilbert range it spans
 * @param id - the S2CellID
 * @returns [min, max]
 */
export declare function range(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 contains(a: S2CellId, b: S2CellId): boolean;
/**
 * @param a - the first S2CellID
 * @param p - the second Point3D
 * @returns true if a contains p
 */
export declare function containsS2Point(a: S2CellId, p: Point3D): 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 intersects(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 next(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 prev(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 isLeaf(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 centerST(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 boundsST(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 sizeST(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 sizeIJ(level: number): number;
/**
 * Given an S2CellID, find the neighboring S2CellIDs
 * @param id - the S2CellID
 * @returns [up, right, down, left]
 */
export declare function neighbors(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 neighborsIJ(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 fromIJSame(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 fromIJWrap(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 vertexNeighbors(id: S2CellId, lev?: number): S2CellId[];
/** The four vertices of the cell. */
export type Vertices = [Point3D, Point3D, Point3D, Point3D];
/**
 * 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 normalized.
 * @param id - the S2CellID
 * @returns the k-th vertex of the cell
 */
export declare function getVertices(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 getVerticesRaw(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 getEdges(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 getEdgesRaw(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 getBoundUV(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 getSizeIJ(id: S2CellId): number;
//# sourceMappingURL=id.d.ts.map