@sakuzu/maplibre-gl-draw 1.0.0

package/dist/geometry/distance.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Geodesic distance and bearing
+ *
+ * The haversine family under a spherical approximation. This is the body of the
+ * geodesic computation shared by circle rendering, buffer generation and measurement.
+ */
+import type { Coordinate } from './types.js';
+/**
+ * Returns the great-circle distance between two positions in meters.
+ *
+ * The haversine formula on a sphere of radius {@link EARTH_RADIUS_METERS}; the error
+ * against the ellipsoid is up to about 0.5%. Crossing the ±180 degree meridian is taken
+ * the short way round. Non-finite coordinates give NaN.
+ *
+ * @param coord1 A position `[lng, lat]` in degrees
+ * @param coord2 A position `[lng, lat]` in degrees
+ * @returns The distance in meters. 0 for identical positions
+ *
+ * @example
+ * ```ts
+ * import { haversineDistanceMeters } from '@sakuzu/maplibre-gl-draw/geometry';
+ *
+ * // Tokyo Station to Osaka Station
+ * haversineDistanceMeters([139.767, 35.681], [135.495, 34.702]); // about 403,139 m
+ * ```
+ */
+export declare function haversineDistanceMeters(coord1: Coordinate, coord2: Coordinate): number;
+/**
+ * Returns the initial bearing of the great circle from one position to another.
+ *
+ * The same spherical approximation as {@link haversineDistanceMeters}. The bearing along a
+ * great circle changes on the way, so this is the direction at the start only.
+ *
+ * @param from The start `[lng, lat]` in degrees
+ * @param to The end `[lng, lat]` in degrees
+ * @returns The bearing in degrees, clockwise with north as 0, in the range [0, 360). 0 when
+ *   the two positions are identical
+ *
+ * @example
+ * ```ts
+ * import { initialBearingDegrees } from '@sakuzu/maplibre-gl-draw/geometry';
+ *
+ * initialBearingDegrees([0, 0], [1, 0]); // 90 (due east)
+ * initialBearingDegrees([0, 0], [0, 1]); // 0 (due north)
+ * ```
+ */
+export declare function initialBearingDegrees(from: Coordinate, to: Coordinate): number;
+/**
+ * Returns the position reached from an origin along a great circle, given a distance and
+ * an initial bearing (the direct problem on the sphere).
+ *
+ * The inverse of {@link haversineDistanceMeters} and {@link initialBearingDegrees} under the
+ * same spherical approximation: the haversine distance from the origin to the result is
+ * `distanceMeters` and the initial bearing is `bearingDegrees`, up to floating-point
+ * rounding, at any latitude and distance.
+ *
+ * The longitude of the result continues from the origin (origin longitude + a change within
+ * ±180 degrees) and is not wrapped into [-180, 180], so a circle drawn near the antimeridian
+ * stays one continuous ring. A great circle through a pole comes back on the far meridian
+ * (origin longitude ± 180 degrees).
+ *
+ * Circles ({@link generateCirclePolygon}) and buffers ({@link buffer}) place their vertices
+ * with it. No input is rejected; non-finite arguments give non-finite coordinates.
+ *
+ * @param origin The start `[lng, lat]` in degrees
+ * @param distanceMeters The distance along the great circle in meters. A negative value
+ *   goes the opposite way
+ * @param bearingDegrees The initial bearing in degrees, clockwise with north as 0
+ * @returns The position reached, `[lng, lat]` in degrees
+ *
+ * @example
+ * ```ts
+ * import { destinationPoint } from '@sakuzu/maplibre-gl-draw/geometry';
+ *
+ * // 1 km due east of Tokyo Station
+ * destinationPoint([139.767, 35.681], 1000, 90); // [139.77807..., 35.68099...]
+ * ```
+ */
+export declare function destinationPoint(origin: Coordinate, distanceMeters: number, bearingDegrees: number): Coordinate;

package/dist/geometry/distance.js

@@ -0,0 +1,111 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+import { EARTH_RADIUS_METERS, toDegrees, toRadians } from './units.js';
+/**
+ * Returns the great-circle distance between two positions in meters.
+ *
+ * The haversine formula on a sphere of radius {@link EARTH_RADIUS_METERS}; the error
+ * against the ellipsoid is up to about 0.5%. Crossing the ±180 degree meridian is taken
+ * the short way round. Non-finite coordinates give NaN.
+ *
+ * @param coord1 A position `[lng, lat]` in degrees
+ * @param coord2 A position `[lng, lat]` in degrees
+ * @returns The distance in meters. 0 for identical positions
+ *
+ * @example
+ * ```ts
+ * import { haversineDistanceMeters } from '@sakuzu/maplibre-gl-draw/geometry';
+ *
+ * // Tokyo Station to Osaka Station
+ * haversineDistanceMeters([139.767, 35.681], [135.495, 34.702]); // about 403,139 m
+ * ```
+ */
+export function haversineDistanceMeters(coord1, coord2) {
+    const R = EARTH_RADIUS_METERS;
+    const [lng1, lat1] = coord1;
+    const [lng2, lat2] = coord2;
+    const dLat = toRadians(lat2 - lat1);
+    const dLng = toRadians(lng2 - lng1);
+    const a = Math.sin(dLat / 2) * Math.sin(dLat / 2) +
+        Math.cos(toRadians(lat1)) * Math.cos(toRadians(lat2)) * Math.sin(dLng / 2) * Math.sin(dLng / 2);
+    const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
+    return R * c;
+}
+/**
+ * Returns the initial bearing of the great circle from one position to another.
+ *
+ * The same spherical approximation as {@link haversineDistanceMeters}. The bearing along a
+ * great circle changes on the way, so this is the direction at the start only.
+ *
+ * @param from The start `[lng, lat]` in degrees
+ * @param to The end `[lng, lat]` in degrees
+ * @returns The bearing in degrees, clockwise with north as 0, in the range [0, 360). 0 when
+ *   the two positions are identical
+ *
+ * @example
+ * ```ts
+ * import { initialBearingDegrees } from '@sakuzu/maplibre-gl-draw/geometry';
+ *
+ * initialBearingDegrees([0, 0], [1, 0]); // 90 (due east)
+ * initialBearingDegrees([0, 0], [0, 1]); // 0 (due north)
+ * ```
+ */
+export function initialBearingDegrees(from, to) {
+    const [lng1, lat1] = from;
+    const [lng2, lat2] = to;
+    const phi1 = toRadians(lat1);
+    const phi2 = toRadians(lat2);
+    const dLambda = toRadians(lng2 - lng1);
+    const y = Math.sin(dLambda) * Math.cos(phi2);
+    const x = Math.cos(phi1) * Math.sin(phi2) - Math.sin(phi1) * Math.cos(phi2) * Math.cos(dLambda);
+    if (y === 0 && x === 0) {
+        return 0;
+    }
+    const bearing = toDegrees(Math.atan2(y, x));
+    return (bearing + 360) % 360;
+}
+/**
+ * Returns the position reached from an origin along a great circle, given a distance and
+ * an initial bearing (the direct problem on the sphere).
+ *
+ * The inverse of {@link haversineDistanceMeters} and {@link initialBearingDegrees} under the
+ * same spherical approximation: the haversine distance from the origin to the result is
+ * `distanceMeters` and the initial bearing is `bearingDegrees`, up to floating-point
+ * rounding, at any latitude and distance.
+ *
+ * The longitude of the result continues from the origin (origin longitude + a change within
+ * ±180 degrees) and is not wrapped into [-180, 180], so a circle drawn near the antimeridian
+ * stays one continuous ring. A great circle through a pole comes back on the far meridian
+ * (origin longitude ± 180 degrees).
+ *
+ * Circles ({@link generateCirclePolygon}) and buffers ({@link buffer}) place their vertices
+ * with it. No input is rejected; non-finite arguments give non-finite coordinates.
+ *
+ * @param origin The start `[lng, lat]` in degrees
+ * @param distanceMeters The distance along the great circle in meters. A negative value
+ *   goes the opposite way
+ * @param bearingDegrees The initial bearing in degrees, clockwise with north as 0
+ * @returns The position reached, `[lng, lat]` in degrees
+ *
+ * @example
+ * ```ts
+ * import { destinationPoint } from '@sakuzu/maplibre-gl-draw/geometry';
+ *
+ * // 1 km due east of Tokyo Station
+ * destinationPoint([139.767, 35.681], 1000, 90); // [139.77807..., 35.68099...]
+ * ```
+ */
+export function destinationPoint(origin, distanceMeters, bearingDegrees) {
+    const [lng, lat] = origin;
+    const delta = distanceMeters / EARTH_RADIUS_METERS;
+    const theta = toRadians(bearingDegrees);
+    const phi1 = toRadians(lat);
+    const sinPhi1 = Math.sin(phi1);
+    const cosPhi1 = Math.cos(phi1);
+    const sinDelta = Math.sin(delta);
+    const cosDelta = Math.cos(delta);
+    const sinPhi2 = Math.min(1, Math.max(-1, sinPhi1 * cosDelta + cosPhi1 * sinDelta * Math.cos(theta)));
+    const phi2 = Math.asin(sinPhi2);
+    const dLambda = Math.atan2(Math.sin(theta) * sinDelta * cosPhi1, cosDelta - sinPhi1 * sinPhi2);
+    return [lng + toDegrees(dLambda), toDegrees(phi2)];
+}

package/dist/geometry/errors.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The error of the geometry module
+ *
+ * The boolean operations run on polygon-clipping, which reports a failure by throwing an
+ * Error whose message is its own internal wording (a sweep-line event, a segment id). Such
+ * a failure leaves the module as a GeometryError instead: the reason is a stable code the
+ * caller can branch on, and the original error is kept as `cause` for diagnosis.
+ */
+/**
+ * Why a geometry operation failed
+ *
+ * - `invalid-input`: the input is not a polygon the operation can take (a degenerate
+ *   segment, a malformed ring)
+ * - `unclosed-ring`: the output ring could not be closed, typically because edges nearly
+ *   coincide within floating-point precision (still failing after the retry on the grid)
+ * - `too-complex`: the operation gave up on an input too large or tangled for it
+ * - `internal`: any other failure inside the boolean operation engine
+ */
+export type GeometryErrorCode = 'invalid-input' | 'unclosed-ring' | 'too-complex' | 'internal';
+/**
+ * The boolean operation that failed.
+ *
+ * It can differ from the function called: {@link normalizeArea} and {@link unionAll} run
+ * `union`, and {@link buffer} runs `union` and `difference`.
+ */
+export type GeometryOperation = 'union' | 'difference' | 'intersection';
+/**
+ * The error a geometry operation throws when the boolean operation engine cannot compute a
+ * result.
+ *
+ * Every function that runs a boolean operation can throw it: the boolean operations,
+ * {@link splitArea}, {@link buffer}, the polygon predicates and {@link sphericalArea}. A
+ * failure is first retried once with the coordinates rounded to a 1e-9 degree grid (about
+ * 0.1 mm); this error is thrown only when the retry fails too. Branch on `code`, which is
+ * stable across versions of the engine; the message is `<operation>: <reason>` in English
+ * and is meant for logs.
+ *
+ * @example
+ * ```ts
+ * import type { PolygonCoordinates } from '@sakuzu/maplibre-gl-draw/geometry';
+ * import { GeometryError, union } from '@sakuzu/maplibre-gl-draw/geometry';
+ *
+ * function tryMerge(a: PolygonCoordinates, b: PolygonCoordinates) {
+ *   try {
+ *     return union(a, b);
+ *   } catch (error) {
+ *     if (error instanceof GeometryError && error.code === 'unclosed-ring') {
+ *       // Keep the inputs as they are and tell the user the merge failed
+ *       return null;
+ *     }
+ *     throw error;
+ *   }
+ * }
+ * ```
+ */
+export declare class GeometryError extends Error {
+    /** Why the operation failed */
+    readonly code: GeometryErrorCode;
+    /** The boolean operation that failed */
+    readonly operation: GeometryOperation;
+    /** The error thrown by the boolean operation engine, kept for diagnosis */
+    readonly cause: unknown;
+    /**
+     * Creates the error. The library creates it; a caller only needs to catch it.
+     *
+     * @param code Why the operation failed
+     * @param operation The boolean operation that failed
+     * @param message The message, `<operation>: <reason>`
+     * @param options The original error as `cause`
+     */
+    constructor(code: GeometryErrorCode, operation: GeometryOperation, message: string, options?: {
+        cause?: unknown;
+    });
+}

package/dist/geometry/errors.js

@@ -0,0 +1,104 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * The error a geometry operation throws when the boolean operation engine cannot compute a
+ * result.
+ *
+ * Every function that runs a boolean operation can throw it: the boolean operations,
+ * {@link splitArea}, {@link buffer}, the polygon predicates and {@link sphericalArea}. A
+ * failure is first retried once with the coordinates rounded to a 1e-9 degree grid (about
+ * 0.1 mm); this error is thrown only when the retry fails too. Branch on `code`, which is
+ * stable across versions of the engine; the message is `<operation>: <reason>` in English
+ * and is meant for logs.
+ *
+ * @example
+ * ```ts
+ * import type { PolygonCoordinates } from '@sakuzu/maplibre-gl-draw/geometry';
+ * import { GeometryError, union } from '@sakuzu/maplibre-gl-draw/geometry';
+ *
+ * function tryMerge(a: PolygonCoordinates, b: PolygonCoordinates) {
+ *   try {
+ *     return union(a, b);
+ *   } catch (error) {
+ *     if (error instanceof GeometryError && error.code === 'unclosed-ring') {
+ *       // Keep the inputs as they are and tell the user the merge failed
+ *       return null;
+ *     }
+ *     throw error;
+ *   }
+ * }
+ * ```
+ */
+export class GeometryError extends Error {
+    /**
+     * Creates the error. The library creates it; a caller only needs to catch it.
+     *
+     * @param code Why the operation failed
+     * @param operation The boolean operation that failed
+     * @param message The message, `<operation>: <reason>`
+     * @param options The original error as `cause`
+     */
+    constructor(code, operation, message, options) {
+        super(message);
+        /** Why the operation failed */
+        Object.defineProperty(this, "code", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** The boolean operation that failed */
+        Object.defineProperty(this, "operation", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** The error thrown by the boolean operation engine, kept for diagnosis */
+        Object.defineProperty(this, "cause", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.name = 'GeometryError';
+        this.code = code;
+        this.operation = operation;
+        this.cause = options?.cause;
+    }
+}
+/**
+ * Classifies an error thrown by polygon-clipping by its message
+ *
+ * The messages are those of polygon-clipping 0.15; one that is not recognized is `internal`.
+ */
+function classify(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (message.startsWith('Input geometry is not a valid') ||
+        message.startsWith('Tried to create degenerate segment')) {
+        return 'invalid-input';
+    }
+    if (message.startsWith('Unable to complete output ring')) {
+        return 'unclosed-ring';
+    }
+    if (message.startsWith('Infinite loop')) {
+        return 'too-complex';
+    }
+    return 'internal';
+}
+/** The message of each reason */
+const MESSAGES = {
+    'invalid-input': 'the input is not a valid polygon',
+    'unclosed-ring': 'the output ring could not be closed',
+    'too-complex': 'the input is too complex',
+    internal: 'the boolean operation failed',
+};
+/**
+ * Wraps an error thrown by polygon-clipping into a GeometryError
+ *
+ * @internal
+ */
+export function toGeometryError(error, operation) {
+    const code = classify(error);
+    return new GeometryError(code, operation, `${operation}: ${MESSAGES[code]}`, { cause: error });
+}

package/dist/geometry/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Geometry module
+ *
+ * A collection of pure functions independent of the rendering and editing machinery.
+ * It does not depend on maplibre, the DOM, wasm, the Store or events, and its only
+ * runtime dependency is polygon-clipping. The same input produces the same output
+ * regardless of the environment, and determinism is guaranteed by the version of the
+ * package.
+ *
+ * As a limitation, crossing the ±180 degree meridian and the vicinity of the poles are
+ * out of scope.
+ */
+export { getPointAtAngle } from './angle.js';
+export { bboxContains, bboxIntersects, boundingBox, coordinatesBBox } from './bbox.js';
+export { clip, difference, differenceAll, intersection, intersectionAll, normalizeArea, union, unionAll, } from './boolean.js';
+export type { BufferOptions } from './buffer.js';
+export { buffer, DEFAULT_BUFFER_SEGMENTS } from './buffer.js';
+export { generateCirclePolygon } from './circle.js';
+export { closeRing, flattenAreaCoordinates, isMultiPolygonCoordinates, isRingClosed, toMultiPolygonCoordinates, } from './coords.js';
+export { destinationPoint, haversineDistanceMeters, initialBearingDegrees } from './distance.js';
+export type { GeometryErrorCode, GeometryOperation } from './errors.js';
+export { GeometryError } from './errors.js';
+export { centroid, geodesicLength, pointOnSurface, sphericalArea } from './measure.js';
+export { contains, intersects, pointInPolygon, within } from './predicates.js';
+export { isRingClockwise, normalizeMultiPolygonOrientation, normalizePolygonOrientation, normalizeRingOrientation, signedRingArea, simplify, } from './simplify.js';
+export { segmentIntersection, splitArea } from './split.js';
+export type { AreaCoordinates, BBox, Coordinate, GeometryInput, LineStringGeometry, MultiLineStringGeometry, MultiPointGeometry, MultiPolygonCoordinates, MultiPolygonGeometry, PointGeometry, PolygonCoordinates, PolygonGeometry, Ring, } from './types.js';
+export { EARTH_RADIUS_METERS, toDegrees, toRadians } from './units.js';

package/dist/geometry/index.js

@@ -0,0 +1,38 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Geometry module
+ *
+ * A collection of pure functions independent of the rendering and editing machinery.
+ * It does not depend on maplibre, the DOM, wasm, the Store or events, and its only
+ * runtime dependency is polygon-clipping. The same input produces the same output
+ * regardless of the environment, and determinism is guaranteed by the version of the
+ * package.
+ *
+ * As a limitation, crossing the ±180 degree meridian and the vicinity of the poles are
+ * out of scope.
+ */
+// Coordinate generation from a bearing
+export { getPointAtAngle } from './angle.js';
+// Bounding box
+export { bboxContains, bboxIntersects, boundingBox, coordinatesBBox } from './bbox.js';
+// Boolean operations
+export { clip, difference, differenceAll, intersection, intersectionAll, normalizeArea, union, unionAll, } from './boolean.js';
+export { buffer, DEFAULT_BUFFER_SEGMENTS } from './buffer.js';
+// Geodesic circle
+export { generateCirclePolygon } from './circle.js';
+// Discrimination and normalization of coordinate shapes
+export { closeRing, flattenAreaCoordinates, isMultiPolygonCoordinates, isRingClosed, toMultiPolygonCoordinates, } from './coords.js';
+// Geodesic distance and bearing
+export { destinationPoint, haversineDistanceMeters, initialBearingDegrees } from './distance.js';
+export { GeometryError } from './errors.js';
+// Measurement
+export { centroid, geodesicLength, pointOnSurface, sphericalArea } from './measure.js';
+// Predicates
+export { contains, intersects, pointInPolygon, within } from './predicates.js';
+// Shaping
+export { isRingClockwise, normalizeMultiPolygonOrientation, normalizePolygonOrientation, normalizeRingOrientation, signedRingArea, simplify, } from './simplify.js';
+// Splitting by a line
+export { segmentIntersection, splitArea } from './split.js';
+// Unit conversion and geodetic constants
+export { EARTH_RADIUS_METERS, toDegrees, toRadians } from './units.js';

package/dist/geometry/measure.d.ts

@@ -0,0 +1,81 @@
+import type { AreaCoordinates, Coordinate } from './types.js';
+/**
+ * Returns the geodesic length of a path in meters.
+ *
+ * The sum of the {@link haversineDistanceMeters} of each section. For the perimeter of a
+ * polygon pass its closed ring.
+ *
+ * @param path The vertices `[lng, lat]` in degrees
+ * @returns The length in meters. 0 for fewer than 2 positions. NaN when a position is not
+ *   finite
+ *
+ * @example
+ * ```ts
+ * import { geodesicLength } from '@sakuzu/maplibre-gl-draw/geometry';
+ *
+ * geodesicLength([[0, 0], [1, 0], [1, 1]]); // about 222,390 m
+ * ```
+ */
+export declare function geodesicLength(path: Coordinate[]): number;
+/**
+ * Returns the area of a polygon on the sphere in square meters.
+ *
+ * The input is normalized with {@link normalizeArea} first, so self-intersections are
+ * resolved, a hole outside its outer ring is dropped, a hole larger than its outer ring
+ * empties the part, and rings that cannot bound an area are dropped. The holes of the
+ * normalized form lie inside their outer ring, so subtracting them never makes the result
+ * negative. For a MultiPolygon the sum of each part is returned. Ring orientation does not
+ * matter. The area is based on the spherical excess on a sphere of radius
+ * {@link EARTH_RADIUS_METERS}.
+ *
+ * @param polygon Polygon or MultiPolygon coordinates in degrees
+ * @returns The area in square meters. 0 when nothing with an area remains
+ * @throws {@link GeometryError} when the boolean operation engine fails even after the
+ *   retry on the 1e-9 degree grid
+ *
+ * @example
+ * ```ts
+ * import { sphericalArea } from '@sakuzu/maplibre-gl-draw/geometry';
+ *
+ * // A 1 x 1 degree square on the equator
+ * sphericalArea([[[0, 0], [1, 0], [1, 1], [0, 1], [0, 0]]]); // about 1.236e10 m²
+ * ```
+ */
+export declare function sphericalArea(polygon: AreaCoordinates): number;
+/**
+ * Returns the area-weighted centroid of a polygon.
+ *
+ * The area of the holes is subtracted, and the parts of a MultiPolygon are combined with
+ * their areas as the weights. The computation is on the lng/lat plane, an approximation
+ * meant for shapes of the scale of an edit. The centroid of a concave shape can fall
+ * outside it; use {@link pointOnSurface} for a point that is always inside.
+ *
+ * @param polygon Polygon or MultiPolygon coordinates in degrees
+ * @returns The centroid `[lng, lat]` in degrees. The mean of all the vertices when the area
+ *   is 0. `null` when there is not a single position
+ */
+export declare function centroid(polygon: AreaCoordinates): Coordinate | null;
+/**
+ * Returns a representative point that lies inside a polygon, such as a label anchor.
+ *
+ * If the {@link centroid} is inside the polygon, it is returned. If it is outside (a
+ * concave shape, or a centroid in a hole), a horizontal scanline is drawn at the latitude of
+ * the centroid and the midpoint of the longest interior section is returned. For a
+ * degenerate shape the scanline does not cross, the center of the bounding box is returned.
+ *
+ * @param polygon Polygon or MultiPolygon coordinates in degrees
+ * @returns The point `[lng, lat]` in degrees. `null` when there is not a single position
+ *
+ * @example
+ * ```ts
+ * import { centroid, pointOnSurface } from '@sakuzu/maplibre-gl-draw/geometry';
+ *
+ * // A U shape: the centroid falls in the gap between the arms
+ * const u: [number, number][][] = [
+ *   [[0, 0], [3, 0], [3, 3], [2, 3], [2, 1], [1, 1], [1, 3], [0, 3], [0, 0]],
+ * ];
+ * centroid(u); // [1.5, 1.357...] (outside)
+ * pointOnSurface(u); // [0.5, 1.357...] (inside the left arm)
+ * ```
+ */
+export declare function pointOnSurface(polygon: AreaCoordinates): Coordinate | null;