@sakuzu/maplibre-gl-draw 1.0.0

package/dist/shared/math/rotation.js

@@ -0,0 +1,186 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+import { getMetersPerPixel, toDegrees, toRadians } from './distance.js';
+/**
+ * WGS84 ellipsoid parameters
+ */
+const WGS84_SEMI_MAJOR_AXIS = 6378137.0; // Equatorial radius (meters)
+const WGS84_ECCENTRICITY_SQUARED = 6.69437999014e-3; // Square of the first eccentricity
+/**
+ * Converts a WGS84 coordinate into an ECEF coordinate (accounting for the ellipsoid)
+ *
+ * @param coord WGS84 coordinate [lng, lat]
+ * @returns ECEF coordinate {x, y, z} (in meters)
+ */
+export function wgs84ToECEF(coord) {
+    const lat = toRadians(coord[1]);
+    const lng = toRadians(coord[0]);
+    // Prime vertical radius of curvature
+    const N = WGS84_SEMI_MAJOR_AXIS / Math.sqrt(1 - WGS84_ECCENTRICITY_SQUARED * Math.sin(lat) ** 2);
+    return {
+        x: N * Math.cos(lat) * Math.cos(lng),
+        y: N * Math.cos(lat) * Math.sin(lng),
+        z: N * (1 - WGS84_ECCENTRICITY_SQUARED) * Math.sin(lat),
+    };
+}
+/**
+ * Converts an ECEF coordinate into a WGS84 coordinate (iterative computation by Bowring's
+ * method)
+ *
+ * @param x ECEF X coordinate (meters)
+ * @param y ECEF Y coordinate (meters)
+ * @param z ECEF Z coordinate (meters)
+ * @returns WGS84 coordinate [lng, lat]
+ */
+export function ecefToWGS84(x, y, z) {
+    // The longitude can be computed directly
+    const lng = Math.atan2(y, x);
+    // Iterative computation of the latitude (Bowring's method)
+    const p = Math.sqrt(x * x + y * y);
+    const e2 = WGS84_ECCENTRICITY_SQUARED;
+    const a = WGS84_SEMI_MAJOR_AXIS;
+    // Initial value
+    let lat = Math.atan2(z, p * (1 - e2));
+    // Iterative computation (usually converges in 2-3 rounds)
+    for (let i = 0; i < 5; i++) {
+        const sinLat = Math.sin(lat);
+        const N = a / Math.sqrt(1 - e2 * sinLat * sinLat);
+        const newLat = Math.atan2(z + e2 * N * sinLat, p);
+        if (Math.abs(newLat - lat) < 1e-12) {
+            break;
+        }
+        lat = newLat;
+    }
+    return [toDegrees(lng), toDegrees(lat)];
+}
+/**
+ * Rotates a single coordinate about the center point as the axis (ECEF coordinate system,
+ * Rodrigues' formula)
+ *
+ * @param coord The coordinate to rotate [lng, lat]
+ * @param center Center point of the rotation [lng, lat]
+ * @param angleDegrees Rotation angle (degrees, counter-clockwise)
+ * @returns The coordinate after rotation [lng, lat]
+ */
+export function rotateCoordinateOnSphere(coord, center, angleDegrees) {
+    const angleRad = toRadians(angleDegrees);
+    // Rotation axis: the normal vector from the center point to the center of the Earth
+    // (ECEF coordinate system)
+    const centerLatRad = toRadians(center[1]);
+    const centerLngRad = toRadians(center[0]);
+    const axisX = Math.cos(centerLatRad) * Math.cos(centerLngRad);
+    const axisY = Math.cos(centerLatRad) * Math.sin(centerLngRad);
+    const axisZ = Math.sin(centerLatRad);
+    // Convert the WGS84 coordinate into ECEF (3D Cartesian coordinates)
+    const latRad = toRadians(coord[1]);
+    const lngRad = toRadians(coord[0]);
+    const vx = Math.cos(latRad) * Math.cos(lngRad);
+    const vy = Math.cos(latRad) * Math.sin(lngRad);
+    const vz = Math.sin(latRad);
+    // Rodrigues' rotation formula
+    // v_rotated = v*cos(θ) + (k×v)*sin(θ) + k*(k·v)*(1-cos(θ))
+    // Cross product k×v
+    const crossX = axisY * vz - axisZ * vy;
+    const crossY = axisZ * vx - axisX * vz;
+    const crossZ = axisX * vy - axisY * vx;
+    // Dot product k·v
+    const dotProduct = axisX * vx + axisY * vy + axisZ * vz;
+    // Apply the rotation
+    const cosAngle = Math.cos(angleRad);
+    const sinAngle = Math.sin(angleRad);
+    const oneMinusCos = 1 - cosAngle;
+    const rotatedX = vx * cosAngle + crossX * sinAngle + axisX * dotProduct * oneMinusCos;
+    const rotatedY = vy * cosAngle + crossY * sinAngle + axisY * dotProduct * oneMinusCos;
+    const rotatedZ = vz * cosAngle + crossZ * sinAngle + axisZ * dotProduct * oneMinusCos;
+    // Inverse conversion from ECEF into a WGS84 coordinate (unit sphere approximation)
+    const newLat = toDegrees(Math.asin(rotatedZ));
+    const newLng = toDegrees(Math.atan2(rotatedY, rotatedX));
+    return [newLng, newLat];
+}
+/**
+ * Rotates multiple coordinates about the center point as the axis (ECEF coordinate system,
+ * Rodrigues' formula)
+ *
+ * @param coords Array of coordinates to rotate
+ * @param center Center point of the rotation [lng, lat]
+ * @param angleDegrees Rotation angle (degrees, counter-clockwise)
+ * @returns Array of coordinates after rotation
+ */
+export function rotateCoordinatesOnSphere(coords, center, angleDegrees) {
+    return coords.map((coord) => rotateCoordinateOnSphere(coord, center, angleDegrees));
+}
+/**
+ * Kilometers per degree of latitude
+ */
+const KILOMETERS_PER_DEGREE_LATITUDE = 111.32;
+/**
+ * Converts kilometers into degrees (with a latitude correction)
+ *
+ * @param km Distance (kilometers)
+ * @param latitude Reference latitude
+ * @returns Degrees
+ */
+export function kmToDegrees(km, latitude) {
+    // Distance of 1 degree of latitude
+    const latDegrees = km / KILOMETERS_PER_DEGREE_LATITUDE;
+    // The distance of 1 degree of longitude varies with the latitude
+    const lngDegrees = km / (KILOMETERS_PER_DEGREE_LATITUDE * Math.cos(toRadians(latitude)));
+    // Use the larger one to be safe
+    return Math.max(latDegrees, lngDegrees);
+}
+/**
+ * Converts pixels into degrees (with a latitude correction)
+ *
+ * @param pixels Number of pixels
+ * @param latitude Reference latitude
+ * @param zoom Zoom level
+ * @param tileSize Tile size (default 512)
+ * @returns Degrees
+ */
+export function pixelsToDegrees(pixels, latitude, zoom, tileSize = 512) {
+    // Meters per pixel
+    const metersPerPixel = getMetersPerPixel(latitude, zoom, tileSize);
+    // Convert meters into kilometers
+    const km = (pixels * metersPerPixel) / 1000;
+    // Convert kilometers into degrees (it differs between longitude and latitude)
+    const latDegrees = km / KILOMETERS_PER_DEGREE_LATITUDE;
+    const lngDegrees = km / (KILOMETERS_PER_DEGREE_LATITUDE * Math.cos(toRadians(latitude)));
+    return { lngDegrees, latDegrees };
+}
+/**
+ * Computes the vertices of a quad with a rotation applied (uses spherical rotation)
+ *
+ * @param centerLng Center longitude
+ * @param centerLat Center latitude
+ * @param halfWidthDeg Half width (degrees) - in the longitude direction
+ * @param halfHeightDeg Half height (degrees) - in the latitude direction
+ * @param rotationDeg Rotation angle (degrees, counter-clockwise)
+ * @returns The 4 vertices of the quad [topLeft, topRight, bottomLeft, bottomRight]
+ */
+export function computeRotatedQuadCorners(centerLng, centerLat, halfWidthDeg, halfHeightDeg, rotationDeg) {
+    const center = [centerLng, centerLat];
+    // Local coordinates before rotation (positions relative to the center, in degrees)
+    // Geographic coordinate system: north is positive (up), south is negative (down)
+    const corners = [
+        [centerLng - halfWidthDeg, centerLat + halfHeightDeg], // top-left (northwest)
+        [centerLng + halfWidthDeg, centerLat + halfHeightDeg], // top-right (northeast)
+        [centerLng - halfWidthDeg, centerLat - halfHeightDeg], // bottom-left (southwest)
+        [centerLng + halfWidthDeg, centerLat - halfHeightDeg], // bottom-right (southeast)
+    ];
+    if (rotationDeg === 0) {
+        return {
+            topLeft: corners[0],
+            topRight: corners[1],
+            bottomLeft: corners[2],
+            bottomRight: corners[3],
+        };
+    }
+    // Apply the spherical rotation
+    const rotatedCorners = rotateCoordinatesOnSphere(corners, center, rotationDeg);
+    return {
+        topLeft: rotatedCorners[0],
+        topRight: rotatedCorners[1],
+        bottomLeft: rotatedCorners[2],
+        bottomRight: rotatedCorners[3],
+    };
+}

package/dist/shared/math/segment-grid.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Segment grid index
+ *
+ * A static uniform grid index over a coordinate array (one polyline, or one ring).
+ * On geometries with a hundred thousand vertices it reduces hit testing, which would
+ * otherwise scan every segment (O(N)), to computing only the candidate segments in the
+ * cells that overlap the tolerance box.
+ *
+ * This module is for internal use within the package and is not exposed in the public API.
+ * Hit testing (dispatcher/hit-test/segment-grid.ts measures distances through it) and the
+ * bbox-limited enumeration of the snapping providers and the tracing both use it, so it sits
+ * in shared/.
+ *
+ * Assumption: coordinate arrays are never rewritten in place (updating coordinates in the
+ * Store follows the immutable update convention of replacing the array with a new one,
+ * both in the memory implementation of core and in external store implementations).
+ * Therefore the index stays valid as long as the array reference is the same, and when the
+ * coordinates change the key of the WeakMap changes, so the index is naturally rebuilt and
+ * the old index is reclaimed by the GC.
+ * For that reason there is no invalidation logic.
+ */
+import type { BoundingBox, Coordinate } from '../types/model.js';
+/**
+ * Vertex count threshold above which the index is built
+ *
+ * Below it a full scan is faster (the cost of building the index outweighs the gain).
+ */
+export declare const SEGMENT_INDEX_THRESHOLD = 1024;
+/**
+ * Segment grid index
+ */
+export interface SegmentGrid {
+    /** The bbox covered by the index */
+    readonly minX: number;
+    readonly minY: number;
+    readonly maxX: number;
+    readonly maxY: number;
+    /** Column count and row count */
+    readonly cols: number;
+    readonly rows: number;
+    /** Cell width and height (at least CELL_EPS) */
+    readonly cellW: number;
+    readonly cellH: number;
+    /** The segment start indices of each cell. An empty cell is undefined */
+    readonly cells: (number[] | undefined)[];
+    /** Segment count (= coords.length - 1, never negative) */
+    readonly segmentCount: number;
+    /** Visit stamps (they avoid computing the same segment twice within one query) */
+    readonly visited: Uint32Array;
+    /** Generation counter of the visit stamps */
+    generation: number;
+}
+/**
+ * Builds the segment grid index
+ */
+export declare function buildSegmentGrid(coords: Coordinate[]): SegmentGrid;
+/**
+ * Gets the index for a coordinate array (building and caching it when there is none)
+ */
+export declare function getSegmentGrid(coords: Coordinate[]): SegmentGrid;
+/**
+ * Enumerates, through the index, the indices of the segments that touch a bbox
+ *
+ * Nothing is missed (every segment whose segment bbox overlaps the query bbox is always
+ * included). Since the cells are held as boxes it may return more than necessary, so the
+ * strict test is left to the caller. The return value is sorted in ascending order to make
+ * the enumeration order deterministic.
+ */
+export declare function querySegmentIndicesInBBox(grid: SegmentGrid, bbox: BoundingBox): number[];

package/dist/shared/math/segment-grid.js

@@ -0,0 +1,159 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Vertex count threshold above which the index is built
+ *
+ * Below it a full scan is faster (the cost of building the index outweighs the gain).
+ */
+export const SEGMENT_INDEX_THRESHOLD = 1024;
+/** Lower bound of the cell width and height (guards against division by zero when the
+ * bbox is degenerate) */
+const CELL_EPS = 1e-12;
+/** Module-level index cache (the key is the reference of the coordinate array) */
+const gridCache = new WeakMap();
+/**
+ * Builds the segment grid index
+ */
+export function buildSegmentGrid(coords) {
+    const segmentCount = Math.max(coords.length - 1, 0);
+    let minX = Number.POSITIVE_INFINITY;
+    let minY = Number.POSITIVE_INFINITY;
+    let maxX = Number.NEGATIVE_INFINITY;
+    let maxY = Number.NEGATIVE_INFINITY;
+    // Put only the vertices that make up a segment into the bbox (a trailing isolated point
+    // is ignored)
+    const vertexCount = segmentCount === 0 ? 0 : segmentCount + 1;
+    for (let i = 0; i < vertexCount; i++) {
+        const [x, y] = coords[i];
+        if (x < minX)
+            minX = x;
+        if (y < minY)
+            minY = y;
+        if (x > maxX)
+            maxX = x;
+        if (y > maxY)
+            maxY = y;
+    }
+    const cols = segmentCount === 0 ? 1 : Math.ceil(Math.sqrt(segmentCount));
+    const rows = cols;
+    const cellW = Math.max((maxX - minX) / cols, CELL_EPS);
+    const cellH = Math.max((maxY - minY) / rows, CELL_EPS);
+    const grid = {
+        minX,
+        minY,
+        maxX,
+        maxY,
+        cols,
+        rows,
+        cellW,
+        cellH,
+        cells: new Array(cols * rows),
+        segmentCount,
+        visited: new Uint32Array(segmentCount),
+        generation: 0,
+    };
+    // Register each segment in every cell its bbox overlaps
+    for (let i = 0; i < segmentCount; i++) {
+        const [ax, ay] = coords[i];
+        const [bx, by] = coords[i + 1];
+        const col0 = cellIndex(Math.min(ax, bx) - grid.minX, grid.cellW, cols);
+        const col1 = cellIndex(Math.max(ax, bx) - grid.minX, grid.cellW, cols);
+        const row0 = cellIndex(Math.min(ay, by) - grid.minY, grid.cellH, rows);
+        const row1 = cellIndex(Math.max(ay, by) - grid.minY, grid.cellH, rows);
+        for (let row = row0; row <= row1; row++) {
+            const rowOffset = row * cols;
+            for (let col = col0; col <= col1; col++) {
+                const cell = grid.cells[rowOffset + col];
+                if (cell) {
+                    cell.push(i);
+                }
+                else {
+                    grid.cells[rowOffset + col] = [i];
+                }
+            }
+        }
+    }
+    return grid;
+}
+/**
+ * Gets the index for a coordinate array (building and caching it when there is none)
+ */
+export function getSegmentGrid(coords) {
+    const cached = gridCache.get(coords);
+    if (cached)
+        return cached;
+    const grid = buildSegmentGrid(coords);
+    gridCache.set(coords, grid);
+    return grid;
+}
+/**
+ * Enumerates, through the index, the indices of the segments that touch a bbox
+ *
+ * Nothing is missed (every segment whose segment bbox overlaps the query bbox is always
+ * included). Since the cells are held as boxes it may return more than necessary, so the
+ * strict test is left to the caller. The return value is sorted in ascending order to make
+ * the enumeration order deterministic.
+ */
+export function querySegmentIndicesInBBox(grid, bbox) {
+    if (grid.segmentCount === 0)
+        return [];
+    // If the query box does not intersect the bbox of the index, there is no candidate
+    if (bbox.maxX < grid.minX ||
+        bbox.minX > grid.maxX ||
+        bbox.maxY < grid.minY ||
+        bbox.minY > grid.maxY) {
+        return [];
+    }
+    const col0 = cellIndex(bbox.minX - grid.minX, grid.cellW, grid.cols);
+    const col1 = cellIndex(bbox.maxX - grid.minX, grid.cellW, grid.cols);
+    const row0 = cellIndex(bbox.minY - grid.minY, grid.cellH, grid.rows);
+    const row1 = cellIndex(bbox.maxY - grid.minY, grid.cellH, grid.rows);
+    const stamp = nextGeneration(grid);
+    const indices = [];
+    for (let row = row0; row <= row1; row++) {
+        const rowOffset = row * grid.cols;
+        for (let col = col0; col <= col1; col++) {
+            const cell = grid.cells[rowOffset + col];
+            if (!cell)
+                continue;
+            for (const i of cell) {
+                // A segment is registered in several cells, so pick it up only once per query
+                if (grid.visited[i] === stamp)
+                    continue;
+                grid.visited[i] = stamp;
+                indices.push(i);
+            }
+        }
+    }
+    indices.sort((a, b) => a - b);
+    return indices;
+}
+/**
+ * Finds the cell index from a coordinate offset (clamping it into range)
+ *
+ * @internal
+ */
+export function cellIndex(offset, cellSize, count) {
+    const index = Math.floor(offset / cellSize);
+    if (index < 0)
+        return 0;
+    if (index >= count)
+        return count - 1;
+    return index;
+}
+/**
+ * Advances the generation of the visit stamps
+ *
+ * When the upper limit of the Uint32Array is reached, the stamps are cleared all at once
+ * and the counter wraps back around.
+ *
+ * @internal
+ */
+export function nextGeneration(grid) {
+    if (grid.generation >= 0xffffffff) {
+        grid.visited.fill(0);
+        grid.generation = 0;
+    }
+    grid.generation += 1;
+    return grid.generation;
+}

package/dist/shared/math/transform.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Coordinate transformation utilities
+ *
+ * Converts between geographic coordinates and screen coordinates in both directions.
+ */
+import type { Map as MapLibreMap } from 'maplibre-gl';
+import type { Coordinate } from '../types/model.js';
+/**
+ * Clamps a latitude into the valid range
+ *
+ * MapLibre's project() throws an error when the latitude is outside the range -90 to 90, and
+ * the latitude can fall outside that range, for example when a large image is placed at a low
+ * zoom level.
+ *
+ * @param latitude - The latitude to clamp (degrees)
+ * @returns The latitude clamped into the range -89.9 to 89.9
+ */
+export declare function clampLatitude(latitude: number): number;
+/**
+ * Clamps the latitude of a coordinate into the valid range
+ *
+ * @param coord - The coordinate to clamp [lng, lat]
+ * @returns The coordinate with its latitude clamped
+ */
+export declare function clampCoordinate(coord: Coordinate): Coordinate;
+/**
+ * Mercator coordinate (in the range 0-1)
+ */
+export type MercatorCoord = [number, number];
+/**
+ * Converts a longitude/latitude into a Mercator coordinate (in the range 0-1)
+ *
+ * @param coord Longitude/latitude coordinate [lng, lat]
+ * @returns Mercator coordinate [x, y] (in the range 0-1)
+ */
+export declare function lngLatToMercator(coord: Coordinate): MercatorCoord;
+/**
+ * A point on the screen in CSS pixels, from the top-left corner of the map
+ */
+export interface ScreenPoint {
+    /** The distance from the left edge */
+    x: number;
+    /** The distance from the top edge */
+    y: number;
+}
+/**
+ * A geographic position as an object, in degrees
+ */
+export interface LngLat {
+    /** The longitude */
+    lng: number;
+    /** The latitude */
+    lat: number;
+}
+/**
+ * Coordinate transformation interface
+ *
+ * Wraps MapLibre's map.project() / map.unproject() and supports both the Mercator projection
+ * and the globe projection.
+ */
+export interface CoordinateTransform {
+    /** Converts a geographic coordinate into a screen coordinate */
+    project(lngLat: Coordinate): ScreenPoint;
+    /** Converts a screen coordinate into a geographic coordinate */
+    unproject(point: ScreenPoint): LngLat;
+}
+/**
+ * Injection point for the terrain-aware anchor projection
+ *
+ * When terrain is enabled, this is the only path that maps a UI anchor (longitude/latitude +
+ * ground elevation) into screen coordinates. So that the rendering side (the vertex shader)
+ * and the hit-testing side (this transformation) are structurally guaranteed to go through the
+ * same elevation, the same matrices and the same branches, the implementation is owned by the
+ * view layer (`view/terrain/anchor.ts`) and injected here. shared cannot depend on view, so
+ * the direction is reversed into "shared opens a socket and view plugs into it".
+ *
+ * When project returns null (terrain is disabled, or the frame state is not yet established),
+ * it falls back to MapLibre's project. The path taken when there is no terrain is exactly the
+ * same as before the injection existed (which guarantees zero regression).
+ */
+export interface AnchorProjector {
+    /**
+     * Maps longitude/latitude + ground elevation into a screen coordinate (CSS pixels). null
+     * when it cannot be used.
+     */
+    project(lng: number, lat: number): ScreenPoint | null;
+}
+/**
+ * Injects an anchor projection (the view layer calls this per map; null removes it)
+ */
+export declare function setAnchorProjector(map: MapLibreMap, projector: AnchorProjector | null): void;
+/**
+ * Gets the anchor projection that is currently injected
+ */
+export declare function getAnchorProjector(map: MapLibreMap): AnchorProjector | null;
+/**
+ * Creates a CoordinateTransform from a MapLibre map
+ *
+ * When terrain is enabled, project goes through the anchor projection (elevation included, one
+ * matrix pass). With terrain enabled, MapLibre's map.project internally raycasts against the
+ * terrain mesh, which measured at roughly 307μs per point (roughly 1μs without terrain). Hit
+ * testing calls project for every vertex, so editing would not hold up as is.
+ *
+ * unproject is called for only a single screen point (roughly 43μs), so MapLibre's is used as
+ * is. That is also because it has to solve the intersection with the terrain mesh by
+ * raycasting, which cannot be obtained from matrices alone.
+ *
+ * @param map MapLibre map instance
+ * @returns A CoordinateTransform instance
+ */
+export declare function createCoordinateTransform(map: MapLibreMap): CoordinateTransform;
+/**
+ * Applies a margin in pixels to a bounding box
+ *
+ * When zoom is passed, the expansion is done on the map plane. When it is not passed, the
+ * expansion round-trips through screen coordinates. It must not round-trip when there is
+ * terrain: with terrain enabled, project projects a point at the height of the ground surface
+ * and unproject casts a ray from the screen onto the ground surface and comes back, so the
+ * round trip is no longer the identity mapping. With a tilted view, the returned values drift
+ * by kilometers, and the box appears far away from the feature, with a different shape too.
+ *
+ * @param coords Coordinates of the 4 corners of the bounding box
+ *   [topLeft, topRight, bottomRight, bottomLeft]
+ * @param margin Margin size (pixels)
+ * @param transform Coordinate transformation interface
+ * @param zoom Current zoom (when passed, the expansion is done on the map plane; required when
+ *   there is terrain)
+ * @returns Coordinates of the 4 corners after the margin is applied
+ */
+export declare function applyMarginToBoundingBox(coords: {
+    topLeft: Coordinate;
+    topRight: Coordinate;
+    bottomRight: Coordinate;
+    bottomLeft: Coordinate;
+}, margin: number, transform: CoordinateTransform, zoom?: number): {
+    topLeft: Coordinate;
+    topRight: Coordinate;
+    bottomRight: Coordinate;
+    bottomLeft: Coordinate;
+};