@geolibre/core 3.6.0 → 3.7.0

package/dist/ellipsoids-BdHOMRmm.d.mts

@@ -0,0 +1,448 @@
+/**
+ * The value values for the "type" property of GeoJSON Objects.
+ * https://tools.ietf.org/html/rfc7946#section-1.4
+ */
+type GeoJsonTypes = GeoJSON["type"];
+/**
+ * Bounding box
+ * https://tools.ietf.org/html/rfc7946#section-5
+ */
+type BBox = [number, number, number, number] | [number, number, number, number, number, number];
+/**
+ * A Position is an array of coordinates.
+ * https://tools.ietf.org/html/rfc7946#section-3.1.1
+ * Array should contain between two and three elements.
+ * The previous GeoJSON specification allowed more elements (e.g., which could be used to represent M values),
+ * but the current specification only allows X, Y, and (optionally) Z to be defined.
+ *
+ * Note: the type will not be narrowed down to `[number, number] | [number, number, number]` due to
+ * marginal benefits and the large impact of breaking change.
+ *
+ * See previous discussions on the type narrowing:
+ * - {@link https://github.com/DefinitelyTyped/DefinitelyTyped/pull/21590|Nov 2017}
+ * - {@link https://github.com/DefinitelyTyped/DefinitelyTyped/discussions/67773|Dec 2023}
+ * - {@link https://github.com/DefinitelyTyped/DefinitelyTyped/discussions/71441| Dec 2024}
+ *
+ * One can use a
+ * {@link https://www.typescriptlang.org/docs/handbook/2/narrowing.html#using-type-predicates|user-defined type guard that returns a type predicate}
+ * to determine if a position is a 2D or 3D position.
+ *
+ * @example
+ * import type { Position } from 'geojson';
+ *
+ * type StrictPosition = [x: number, y: number] | [x: number, y: number, z: number]
+ *
+ * function isStrictPosition(position: Position): position is StrictPosition {
+ *   return position.length === 2 || position.length === 3
+ * };
+ *
+ * let position: Position = [-116.91, 45.54];
+ *
+ * let x: number;
+ * let y: number;
+ * let z: number | undefined;
+ *
+ * if (isStrictPosition(position)) {
+ *   // `tsc` would throw an error if we tried to destructure a fourth parameter
+ * 	 [x, y, z] = position;
+ * } else {
+ * 	 throw new TypeError("Position is not a 2D or 3D point");
+ * }
+ */
+type Position = number[];
+/**
+ * The base GeoJSON object.
+ * https://tools.ietf.org/html/rfc7946#section-3
+ * The GeoJSON specification also allows foreign members
+ * (https://tools.ietf.org/html/rfc7946#section-6.1)
+ * Developers should use "&" type in TypeScript or extend the interface
+ * to add these foreign members.
+ */
+interface GeoJsonObject {
+  // Don't include foreign members directly into this type def.
+  // in order to preserve type safety.
+  // [key: string]: any;
+  /**
+   * Specifies the type of GeoJSON object.
+   */
+  type: GeoJsonTypes;
+  /**
+   * Bounding box of the coordinate range of the object's Geometries, Features, or Feature Collections.
+   * The value of the bbox member is an array of length 2*n where n is the number of dimensions
+   * represented in the contained geometries, with all axes of the most southwesterly point
+   * followed by all axes of the more northeasterly point.
+   * The axes order of a bbox follows the axes order of geometries.
+   * https://tools.ietf.org/html/rfc7946#section-5
+   */
+  bbox?: BBox | undefined;
+}
+/**
+ * Union of GeoJSON objects.
+ */
+type GeoJSON<G extends Geometry | null = Geometry, P = GeoJsonProperties> = G | Feature<G, P> | FeatureCollection<G, P>;
+/**
+ * Geometry object.
+ * https://tools.ietf.org/html/rfc7946#section-3
+ */
+type Geometry = Point | MultiPoint | LineString | MultiLineString | Polygon | MultiPolygon | GeometryCollection;
+/**
+ * Point geometry object.
+ * https://tools.ietf.org/html/rfc7946#section-3.1.2
+ */
+interface Point extends GeoJsonObject {
+  type: "Point";
+  coordinates: Position;
+}
+/**
+ * MultiPoint geometry object.
+ *  https://tools.ietf.org/html/rfc7946#section-3.1.3
+ */
+interface MultiPoint extends GeoJsonObject {
+  type: "MultiPoint";
+  coordinates: Position[];
+}
+/**
+ * LineString geometry object.
+ * https://tools.ietf.org/html/rfc7946#section-3.1.4
+ */
+interface LineString extends GeoJsonObject {
+  type: "LineString";
+  coordinates: Position[];
+}
+/**
+ * MultiLineString geometry object.
+ * https://tools.ietf.org/html/rfc7946#section-3.1.5
+ */
+interface MultiLineString extends GeoJsonObject {
+  type: "MultiLineString";
+  coordinates: Position[][];
+}
+/**
+ * Polygon geometry object.
+ * https://tools.ietf.org/html/rfc7946#section-3.1.6
+ */
+interface Polygon extends GeoJsonObject {
+  type: "Polygon";
+  coordinates: Position[][];
+}
+/**
+ * MultiPolygon geometry object.
+ * https://tools.ietf.org/html/rfc7946#section-3.1.7
+ */
+interface MultiPolygon extends GeoJsonObject {
+  type: "MultiPolygon";
+  coordinates: Position[][][];
+}
+/**
+ * Geometry Collection
+ * https://tools.ietf.org/html/rfc7946#section-3.1.8
+ */
+interface GeometryCollection<G extends Geometry = Geometry> extends GeoJsonObject {
+  type: "GeometryCollection";
+  geometries: G[];
+}
+type GeoJsonProperties = {
+  [name: string]: any;
+} | null;
+/**
+ * A feature object which contains a geometry and associated properties.
+ * https://tools.ietf.org/html/rfc7946#section-3.2
+ */
+interface Feature<G extends Geometry | null = Geometry, P = GeoJsonProperties> extends GeoJsonObject {
+  type: "Feature";
+  /**
+   * The feature's geometry
+   */
+  geometry: G;
+  /**
+   * A value that uniquely identifies this feature in a
+   * https://tools.ietf.org/html/rfc7946#section-3.2.
+   */
+  id?: string | number | undefined;
+  /**
+   * Properties associated with this feature.
+   */
+  properties: P;
+}
+/**
+ * A collection of feature objects.
+ *  https://tools.ietf.org/html/rfc7946#section-3.3
+ */
+interface FeatureCollection<G extends Geometry | null = Geometry, P = GeoJsonProperties> extends GeoJsonObject {
+  type: "FeatureCollection";
+  features: Array<Feature<G, P>>;
+}
+/**
+ * Celestial-body ellipsoids and the planetary basemaps that pair with them.
+ *
+ * GeoLibre is Earth-centric by construction: the default map is Web Mercator
+ * and all vector data is kept as lon/lat GeoJSON. This module does *not*
+ * change that (a map drawn in a body's own polar or simple-cylindrical CRS is
+ * `map-crs.ts`). What it adds is a per-project notion of *which body* the
+ * coordinates describe, so that:
+ *
+ *   - distance / area / scale measurements use that body's radius instead of a
+ *     hardcoded Earth radius, and
+ *   - Moon / Mars basemaps (published in a Web-Mercator tiling scheme) can be
+ *     selected like any other basemap.
+ *
+ * The active ellipsoid is a lightweight module-level singleton kept in sync with
+ * the project's map preferences (see the store's `setPreferences`). Measurement
+ * helpers read it lazily at call time, so callers in other packages don't need
+ * the value threaded through their signatures — a deliberate prototype-friendly
+ * shortcut over a full CRS/context refactor.
+ */
+/** A biaxial (rotational) ellipsoid describing a celestial body. */
+interface Ellipsoid {
+  /** Stable id persisted in the project (`map.ellipsoidId`). */
+  id: string;
+  /** Human-readable name shown in the UI. */
+  name: string;
+  /** Equatorial (semi-major) radius in metres — the "web mercator" radius. */
+  semiMajorAxisMeters: number;
+  /**
+   * Inverse flattening `1/f`. `0` denotes a perfect sphere (Moon), in which case
+   * the polar radius equals {@link semiMajorAxisMeters}.
+   */
+  inverseFlattening: number;
+}
+/**
+ * Built-in ellipsoids. Earth is WGS 84; every other body uses IAU-adopted
+ * figures. Only Earth and Mars are appreciably oblate; the rest are modelled as
+ * spheres (`inverseFlattening: 0`), which is how the IAU/USGS simple-cylindrical
+ * products treat them and is well within the accuracy MapLibre's unit-sphere
+ * rendering can represent anyway.
+ */
+declare const ELLIPSOIDS: readonly [{
+  readonly id: "earth";
+  readonly name: "Earth (WGS 84)";
+  readonly semiMajorAxisMeters: 6378137;
+  readonly inverseFlattening: 298.257223563;
+}, {
+  readonly id: "moon";
+  readonly name: "Moon";
+  readonly semiMajorAxisMeters: 1737400;
+  readonly inverseFlattening: 0;
+}, {
+  readonly id: "mars";
+  readonly name: "Mars (IAU 2000)";
+  readonly semiMajorAxisMeters: 3396190;
+  readonly inverseFlattening: 169.894447;
+}, {
+  readonly id: "mercury";
+  readonly name: "Mercury";
+  readonly semiMajorAxisMeters: 2439400;
+  readonly inverseFlattening: 0;
+}, {
+  readonly id: "venus";
+  readonly name: "Venus";
+  readonly semiMajorAxisMeters: 6051800;
+  readonly inverseFlattening: 0;
+}, {
+  readonly id: "io";
+  readonly name: "Io";
+  readonly semiMajorAxisMeters: 1821600;
+  readonly inverseFlattening: 0;
+}, {
+  readonly id: "europa";
+  readonly name: "Europa";
+  readonly semiMajorAxisMeters: 1560800;
+  readonly inverseFlattening: 0;
+}, {
+  readonly id: "ganymede";
+  readonly name: "Ganymede";
+  readonly semiMajorAxisMeters: 2631200;
+  readonly inverseFlattening: 0;
+}, {
+  readonly id: "callisto";
+  readonly name: "Callisto";
+  readonly semiMajorAxisMeters: 2410300;
+  readonly inverseFlattening: 0;
+}, {
+  readonly id: "titan";
+  readonly name: "Titan";
+  readonly semiMajorAxisMeters: 2574730;
+  readonly inverseFlattening: 0;
+}, {
+  readonly id: "pluto";
+  readonly name: "Pluto";
+  readonly semiMajorAxisMeters: 1188300;
+  readonly inverseFlattening: 0;
+}, {
+  readonly id: "charon";
+  readonly name: "Charon";
+  readonly semiMajorAxisMeters: 606000;
+  readonly inverseFlattening: 0;
+}];
+type EllipsoidId = (typeof ELLIPSOIDS)[number]["id"];
+declare const DEFAULT_ELLIPSOID_ID: EllipsoidId;
+/** Look an ellipsoid up by id, falling back to Earth for unknown ids. */
+declare function getEllipsoid(id: string | undefined): Ellipsoid;
+/**
+ * Mean radius `R = (2a + b) / 3` in metres, where `b` is the polar radius
+ * derived from the inverse flattening. This is the radius used for spherical
+ * (haversine) distance and area math.
+ */
+declare function meanRadiusMeters(ellipsoid: Ellipsoid): number;
+/** Earth's mean radius in metres — the radius Turf.js and MapLibre bake in. */
+declare const EARTH_MEAN_RADIUS_METERS: number;
+/**
+ * Point the measurement helpers at a body. Unknown ids fall back to Earth so a
+ * malformed project can never break measurements. Safe to call on every
+ * preferences change; it is a cheap assignment.
+ */
+declare function setActiveEllipsoidId(id: string | undefined): void;
+declare function getActiveEllipsoid(): Ellipsoid;
+/** Mean radius (metres) of the active body — for haversine distance/area. */
+declare function getActiveMeanRadiusMeters(): number;
+/** Semi-major axis (metres) of the active body — for its Web-Mercator scale. */
+declare function getActiveSemiMajorAxisMeters(): number;
+/**
+ * The active body's mean radius as a fraction of Earth's — `R_body / R_earth`,
+ * and exactly `1` on Earth.
+ *
+ * Everything GeoLibre measures ultimately comes from lon/lat *angles*, and the
+ * only thing that turns an angle into a ground distance is the radius it is
+ * multiplied by. Turf.js hardcodes Earth's, with no per-call override (that is
+ * the "Turf is Earth-locked" half of GeoLibre#1128), so rather than patch or
+ * replace Turf we post-scale what it returns and pre-scale what we hand it. The
+ * result is exact for a sphere, which is how every non-Earth body GeoLibre
+ * offers is modelled anyway, and within Mars' 0.6% flattening at worst.
+ *
+ * Suggested by @thareUSGS (USGS Astrogeology) on GeoLibre#1128 as the practical
+ * workaround planetary web maps have long used on Earth-locked engines.
+ */
+declare function getActiveBodyRadiusRatio(): number;
+/**
+ * Convert a length Turf.js measured on Earth into the active body's true ground
+ * length. A no-op on Earth.
+ *
+ * Use on anything Turf *returns* — a distance, a length, a perimeter.
+ *
+ * The correction is a dimensionless ratio, so it is unit-agnostic: pass the
+ * length in whatever unit Turf gave it back (metres, kilometres, miles) and the
+ * result is in that same unit. There is no hidden unit conversion here.
+ */
+declare function earthLengthToBody(length: number): number;
+/**
+ * Convert a true ground length on the active body into the Earth-equivalent
+ * length to hand Turf.js. A no-op on Earth.
+ *
+ * Use on anything passed *into* Turf as a distance — a buffer width, a circle
+ * or sector radius, a search threshold — so the resulting geometry spans that
+ * distance on this body rather than on Earth.
+ *
+ * Unit-agnostic like {@link earthLengthToBody}: pass the length in whatever
+ * unit you are about to hand Turf alongside it, and the result is in that unit.
+ */
+declare function bodyLengthToEarth(length: number): number;
+/**
+ * Convert an area Turf.js measured on Earth into the active body's true ground
+ * area. A no-op on Earth.
+ *
+ * Areas scale with the *square* of the radius ratio, so this is not the same
+ * correction as {@link earthLengthToBody}. Unit-agnostic in the same way, for
+ * whatever squared unit the area is expressed in.
+ */
+declare function earthAreaToBody(area: number): number;
+/**
+ * A raster basemap for a celestial body — the Moon and Mars mosaics, plus the
+ * Earth satellite imagery the planet switcher pairs with Earth. The tiles are
+ * XYZ (or TMS, see {@link scheme}) images in that body's Web-Mercator scheme, so
+ * MapLibre renders them directly. The `styleUrl` is a `geolibre://basemap/<id>`
+ * sentinel; the map controller expands it into a raster style at apply time (it
+ * is not a fetchable URL).
+ */
+interface PlanetaryBasemap {
+  id: string;
+  name: string;
+  /** Sentinel stored as the basemap style URL. */
+  styleUrl: string;
+  /** XYZ (or TMS, see {@link scheme}) tile template. */
+  tileUrl: string;
+  /**
+   * Tile row ordering. OpenPlanetaryMap's single-layer raster mosaics (the S3
+   * datasets) are published as **TMS** (tile origin bottom-left, Y flipped),
+   * whereas the CARTO `opmbuilder` named maps are standard **XYZ**. Omit for
+   * XYZ; MapLibre defaults to `"xyz"` when `scheme` is absent.
+   */
+  scheme?: "tms";
+  /** Max native zoom of the source (MapLibre overzooms beyond this). */
+  maxZoom: number;
+  /** Attribution shown on the map. */
+  attribution: string;
+  /** The body this basemap depicts, so selecting it can set the ellipsoid. */
+  ellipsoidId: EllipsoidId;
+}
+declare const PLANETARY_BASEMAP_SENTINEL_PREFIX = "geolibre://basemap/";
+declare const PLANETARY_BASEMAPS: readonly PlanetaryBasemap[];
+/**
+ * The section a planetary basemap is grouped under in the New Project and
+ * Change Basemap pickers. The Moon and Mars keep dedicated sections (they are
+ * the most-used bodies and each has several mosaics); every other body is
+ * collapsed into a single "other" section so the picker isn't a wall of
+ * one-item headings.
+ */
+type PlanetaryBasemapSectionId = "moon" | "mars" | "other";
+/** A picker section paired with the planetary basemaps it lists. */
+interface PlanetaryBasemapGroup {
+  id: PlanetaryBasemapSectionId;
+  basemaps: readonly PlanetaryBasemap[];
+}
+/**
+ * {@link PLANETARY_BASEMAPS} grouped for the pickers: one section each for the
+ * Moon and Mars, then a single "Other celestial bodies" section for the rest,
+ * in {@link PLANETARY_BASEMAPS} order (grouped by body). Empty sections are
+ * dropped.
+ */
+declare const PLANETARY_BASEMAP_GROUPS: readonly PlanetaryBasemapGroup[];
+/** Resolve a `geolibre://basemap/<id>` sentinel to its planetary basemap. */
+declare function getPlanetaryBasemapByStyleUrl(styleUrl: string | undefined): PlanetaryBasemap | undefined;
+/** Look a planetary basemap up by its stable id. */
+declare function getPlanetaryBasemapById(id: string): PlanetaryBasemap | undefined;
+/**
+ * The celestial bodies offered by the Layers-panel planet switcher, in menu
+ * order (like Google Earth's planet dropdown). Each body is paired with the
+ * basemap the switcher applies for it — USGS satellite imagery for Earth, the
+ * OpenPlanetaryMap Hillshaded Albedo mosaic for the Moon, and the OpenPlanetaryMap
+ * Viking mosaic for Mars.
+ */
+declare const PLANET_SWITCHER_OPTIONS: readonly [{
+  readonly ellipsoidId: "earth";
+  readonly basemapId: "earth-usgs-imagery";
+}, {
+  readonly ellipsoidId: "moon";
+  readonly basemapId: "moon-hillshaded-albedo";
+}, {
+  readonly ellipsoidId: "mars";
+  readonly basemapId: "mars-viking-mdim21";
+}, {
+  readonly ellipsoidId: "callisto";
+  readonly basemapId: "callisto-galileo-voyager";
+}, {
+  readonly ellipsoidId: "charon";
+  readonly basemapId: "charon-mosaic";
+}, {
+  readonly ellipsoidId: "europa";
+  readonly basemapId: "europa-galileo-voyager";
+}, {
+  readonly ellipsoidId: "ganymede";
+  readonly basemapId: "ganymede-galileo-voyager";
+}, {
+  readonly ellipsoidId: "io";
+  readonly basemapId: "io-galileo-color";
+}, {
+  readonly ellipsoidId: "mercury";
+  readonly basemapId: "mercury-messenger-color";
+}, {
+  readonly ellipsoidId: "pluto";
+  readonly basemapId: "pluto-mosaic";
+}, {
+  readonly ellipsoidId: "titan";
+  readonly basemapId: "titan-cassini";
+}, {
+  readonly ellipsoidId: "venus";
+  readonly basemapId: "venus-magellan-color";
+}];
+export { LineString as A, meanRadiusMeters as C, GeoJSON as D, FeatureCollection as E, Position as F, MultiPolygon as M, Point as N, GeoJsonProperties as O, Polygon as P, getPlanetaryBasemapByStyleUrl as S, Feature as T, getActiveEllipsoid as _, EllipsoidId as a, getEllipsoid as b, PLANETARY_BASEMAP_SENTINEL_PREFIX as c, PlanetaryBasemapGroup as d, PlanetaryBasemapSectionId as f, getActiveBodyRadiusRatio as g, earthLengthToBody as h, Ellipsoid as i, MultiLineString as j, Geometry as k, PLANET_SWITCHER_OPTIONS as l, earthAreaToBody as m, EARTH_MEAN_RADIUS_METERS as n, PLANETARY_BASEMAPS as o, bodyLengthToEarth as p, ELLIPSOIDS as r, PLANETARY_BASEMAP_GROUPS as s, DEFAULT_ELLIPSOID_ID as t, PlanetaryBasemap as u, getActiveMeanRadiusMeters as v, setActiveEllipsoidId as w, getPlanetaryBasemapById as x, getActiveSemiMajorAxisMeters as y };
+//# sourceMappingURL=ellipsoids-BdHOMRmm.d.mts.map

package/dist/ellipsoids-BdHOMRmm.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ellipsoids-BdHOMRmm.d.mts","names":[],"sources":["../../../node_modules/@types/geojson/index.d.ts","../src/ellipsoids.ts"],"ignoreList":[0],"mappings":";;;;KAeY,eAAe;;;;;KAMf;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KA2CA;;;;;;;;;UAUK;;;;;;;EAOb,MAAM;;;;;;;;;EASN,OAAO;;;;;KAMC,QAAQ,UAAU,kBAAkB,UAAU,IAAI,qBACxD,IACA,QAAQ,GAAG,KACX,kBAAkB,GAAG;;;;;KAMf,WAAW,QAAQ,aAAa,aAAa,kBAAkB,UAAU,eAAe;;;;;UAOnF,cAAc;EAC3B;EACA,aAAa;;;;;;UAOA,mBAAmB;EAChC;EACA,aAAa;;;;;;UAOA,mBAAmB;EAChC;EACA,aAAa;;;;;;UAOA,wBAAwB;EACrC;EACA,aAAa;;;;;;UAOA,gBAAgB;EAC7B;EACA,aAAa;;;;;;UAOA,qBAAqB;EAClC;EACA,aAAa;;;;;;UAOA,mBAAmB,UAAU,WAAW,kBAAkB;EACvE;EACA,YAAY;;KAGJ;GAAuB;;;;;;UAMlB,QAAQ,UAAU,kBAAkB,UAAU,IAAI,2BAA2B;EAC1F;;;;EAIA,UAAU;;;;;EAKV;;;;EAIA,YAAY;;;;;;UAOC,kBAAkB,UAAU,kBAAkB,UAAU,IAAI,2BAA2B;EACpG;EACA,UAAU,MAAM,QAAQ,GAAG;;;;;;;;;;;;;;;;;;;;;;;UClLd;;EAEf;;EAEA;;EAEA;;;;;EAKA;;;;;;;;;cAUW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KA2ED,sBAAsB;cAErB,sBAAsB;;iBAGnB,aAAa,yBAAyB;;;;;;iBAWtC,iBAAiB,WAAW;;cAS/B;;;;;;iBAWG,qBAAqB;iBAIrB,sBAAsB;;iBAKtB;;iBAKA;;;;;;;;;;;;;;;;iBAqBA;;;;;;;;;;;iBAcA,kBAAkB;;;;;;;;;;;;iBAelB,kBAAkB;;;;;;;;;iBAYlB,gBAAgB;;;;;;;;;UAef;EACf;EACA;;EAEA;;EAEA;;;;;;;EAOA;;EAEA;;EAEA;;EAEA,aAAa;;cAGF;cA0CA,6BAA6B;;;;;;;;KAwO9B;;UAGK;EACf,IAAI;EACJ,mBAAmB;;;;;;;;cAcR,mCAAmC;;iBAyChC,8BACd,+BACC;;iBAUa,wBAAwB,aAAa;;;;;;;;cAWxC"}