Documentation / @interstellar-tools/maps
@interstellar-tools/maps
Map projections, web map tiles, terrain from elevation grids, imaging geometry and landing site analysis, for Earth and any other planet or moon.
NOTE
0.x: the API can still change. This package is new and versioned 0.x until its API settles; a minor release may change it. Geodesy on body shapes (ellipsoids, distances, geodetic coordinates, the horizon) lives in @interstellar-tools/equations, which this package builds on.
What's planned
The Maps and topography milestone tracks the work:
- map projections: Mercator and equirectangular, sinusoidal and Mollweide, and azimuthal projections
- web map tiles and quadkeys
- terrain from elevation grids: slope, aspect, hillshade, roughness
- imaging geometry: ground sample distance, field of view and illumination angles
- landing site analysis: whether a lander tips over on a slope
Documentation
The full documentation lives at phun-ky.net/interstellar-tools:
- Getting started: installation, unit conventions and recommended practices
- API reference for
@interstellar-tools/maps: every export, with formulas, parameters and examples
Installation
- Node.js version 22.12.0 or higher
- ES modules;
require()needs Node 22.12 or later
shell
npm i --save @interstellar-tools/mapsImaging
| Function | Description |
|---|---|
| groundSampleDistance | Compute the ground sample distance: how much ground one pixel covers, looking straight down. |
| illuminationAngles | Compute the illumination angles at a point on a surface: incidence, emission and phase. |
| instantaneousFieldOfView | Compute the instantaneous field of view of one detector pixel: the angle it sees. |
| lambertReflectance | Compute the relative brightness of a Lambertian surface: one that scatters light equally in all directions. |
| lommelSeeligerReflectance | Compute the relative brightness of a Lommel–Seeliger surface: a dark, dusty one, like the Moon or an asteroid. |
| swathWidth | Compute the swath width: the strip of ground a camera covers across its track, looking straight down. |
Landing sites
| Name | Description |
|---|---|
| SafeLandingOptionsInterface | The lander, for safeLandingGrid. |
| isStableLanding | Check whether a lander stays upright on a slope: whether its total tilt stays below its tip-over angle. |
| safeLandingGrid | Map where a lander can touch down safely on an elevation grid: where it stays upright on the slope and the ground is smooth enough. |
| tipOverAngle | Compute the tip-over angle of a lander: the tilt at which its centre of mass passes over the edge of its footprint. |
Projections
| Name | Description |
|---|---|
| AzimuthalOptionsInterface | Where an azimuthal map is centred, for lambertAzimuthalEqualArea, stereographic and orthographic. |
| EquirectangularOptionsInterface | Options for equirectangular and inverseEquirectangular. |
| GeographicCoordinatesInterface | A point on a sphere: latitude and longitude. |
| ProjectedPointInterface | A point on a map, in metres from the projection's origin: x east, y north. |
| ProjectionOptionsInterface | Where a map is centred east–west, for the projections. |
| equirectangular | Project a point on a sphere with the equirectangular projection: the simple cylindrical map, with latitude and longitude spaced evenly. |
| inverseEquirectangular | Find the point on a sphere for a point on an equirectangular map: the inverse of equirectangular. |
| inverseLambertAzimuthalEqualArea | Find the point on a sphere for a point on a Lambert azimuthal equal-area map: the inverse of lambertAzimuthalEqualArea. |
| inverseMercator | Find the point on a sphere for a point on a Mercator map: the inverse of mercator. |
| inverseMollweide | Find the point on a sphere for a point on a Mollweide map: the inverse of mollweide. |
| inverseOrthographic | Find the point on a sphere for a point on an orthographic map: the inverse of orthographic. |
| inverseSinusoidal | Find the point on a sphere for a point on a sinusoidal map: the inverse of sinusoidal. |
| inverseStereographic | Find the point on a sphere for a point on a stereographic map: the inverse of stereographic. |
| lambertAzimuthalEqualArea | Project a point on a sphere with the Lambert azimuthal equal-area projection: an equal-area map centred on any point, with true directions from the centre. |
| mercator | Project a point on a sphere with the Mercator projection: the conformal cylindrical map, which keeps angles and shapes locally true. |
| mollweide | Project a point on a sphere with the Mollweide projection: an equal-area map of the whole sphere inside an ellipse twice as wide as tall. |
| orthographic | Project a point on a sphere with the orthographic projection: the globe as it looks from infinitely far away, above the map's centre. |
| sinusoidal | Project a point on a sphere with the sinusoidal projection: an equal-area map, with every parallel at its true length. |
| stereographic | Project a point on a sphere with the stereographic projection: a conformal map centred on any point, the usual choice for polar maps. |
Terrain
| Name | Description |
|---|---|
| GridInterface | A raster grid of values over a map, such as a digital elevation model (DEM): rows × columns cells of equal size, stored row by row. |
| TerrainCurvatureInterface | How the terrain bends at a cell, along the slope and across it. |
| TerrainGradientInterface | The rate at which the terrain rises, east and north, at a cell. |
| TopographicWetnessIndexOptionsInterface | Options for topographicWetnessIndex. |
| ElevationGridInterface | A digital elevation model: a GridInterface of heights in m. |
| aspectAt | Compute the aspect of an elevation grid at a cell: the direction the terrain faces. |
| aspectGrid | Compute the aspect of every cell of an elevation grid, as a new grid in radians clockwise from north. |
| createGrid | Create a raster grid, such as an elevation model, checking that its parts fit together. |
| curvatureAt | Compute the profile and planform curvature of an elevation grid at a cell: how the terrain bends along the steepest slope and across it. |
| curvatureGrid | Compute the profile and planform curvature of every cell of an elevation grid, as two new grids in 1/m. |
| flowAccumulation | Compute the flow accumulation of every cell of an elevation grid: the area that drains through it, its own included. |
| flowDirections | Compute the D8 flow direction of every cell of an elevation grid: which of its eight neighbours water would run to. |
| gradientAt | Compute the gradient of an elevation grid at a cell, from its 3 × 3 neighbourhood with Horn's method. |
| gridValueAt | Read the value of one cell of a grid. |
| hillshadeAt | Compute the hillshade of a patch of terrain: how brightly the Sun lights it, from its slope and aspect. |
| hillshadeGrid | Compute the hillshade of every cell of an elevation grid, as a new grid of brightness in [0, 1]. |
| slopeAt | Compute the slope of an elevation grid at a cell: how steep the terrain is. |
| slopeGrid | Compute the slope of every cell of an elevation grid, as a new grid in radians. |
| terrainRoughnessIndexAt | Compute the Terrain Roughness Index of an elevation grid at a cell: the root-mean-square height difference between the cell and its eight neighbours. |
| terrainRoughnessIndexGrid | Compute the Terrain Roughness Index of every cell of an elevation grid, as a new grid in metres. |
| topographicWetnessIndex | Compute the Topographic Wetness Index of every cell of an elevation grid: where water would collect, from how much ground drains through a cell and how slowly it drains away. |
Tiles
| Name | Description |
|---|---|
| TileBoundsInterface | The edges of a web map tile: the latitudes of its north and south edges and the longitudes of its west and east edges. |
| TileInterface | A web map tile, in the scheme web maps use ("slippy maps", XYZ): at zoom z the spherical Web Mercator map is cut into |
| fromQuadkey | Find the web map tile named by a quadkey: the inverse of quadkey. |
| quadkey | Find the quadkey of a web map tile: one base-4 digit per zoom level, naming which quarter of its parent the tile is, from zoom 1 down. |
| tileAt | Find the web map tile that holds a point, at a zoom level: the tile scheme web maps use ("slippy maps", XYZ) on the spherical Web Mercator map. |
| tileBounds | Find the edges of a web map tile: the latitudes of its north and south edges and the longitudes of its west and east edges. The inverse of tileAt. |