Skip to content

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:

Installation ​

  • Node.js version 22.12.0 or higher
  • ES modules; require() needs Node 22.12 or later
npm
shell
npm i --save @interstellar-tools/maps

Imaging ​

FunctionDescription
groundSampleDistanceCompute the ground sample distance: how much ground one pixel covers, looking straight down.
illuminationAnglesCompute the illumination angles at a point on a surface: incidence, emission and phase.
instantaneousFieldOfViewCompute the instantaneous field of view of one detector pixel: the angle it sees.
lambertReflectanceCompute the relative brightness of a Lambertian surface: one that scatters light equally in all directions.
lommelSeeligerReflectanceCompute the relative brightness of a Lommel–Seeliger surface: a dark, dusty one, like the Moon or an asteroid.
swathWidthCompute the swath width: the strip of ground a camera covers across its track, looking straight down.

Landing sites ​

NameDescription
SafeLandingOptionsInterfaceThe lander, for safeLandingGrid.
isStableLandingCheck whether a lander stays upright on a slope: whether its total tilt stays below its tip-over angle.
safeLandingGridMap where a lander can touch down safely on an elevation grid: where it stays upright on the slope and the ground is smooth enough.
tipOverAngleCompute the tip-over angle of a lander: the tilt at which its centre of mass passes over the edge of its footprint.

Projections ​

NameDescription
AzimuthalOptionsInterfaceWhere an azimuthal map is centred, for lambertAzimuthalEqualArea, stereographic and orthographic.
EquirectangularOptionsInterfaceOptions for equirectangular and inverseEquirectangular.
GeographicCoordinatesInterfaceA point on a sphere: latitude and longitude.
ProjectedPointInterfaceA point on a map, in metres from the projection's origin: x east, y north.
ProjectionOptionsInterfaceWhere a map is centred east–west, for the projections.
equirectangularProject a point on a sphere with the equirectangular projection: the simple cylindrical map, with latitude and longitude spaced evenly.
inverseEquirectangularFind the point on a sphere for a point on an equirectangular map: the inverse of equirectangular.
inverseLambertAzimuthalEqualAreaFind the point on a sphere for a point on a Lambert azimuthal equal-area map: the inverse of lambertAzimuthalEqualArea.
inverseMercatorFind the point on a sphere for a point on a Mercator map: the inverse of mercator.
inverseMollweideFind the point on a sphere for a point on a Mollweide map: the inverse of mollweide.
inverseOrthographicFind the point on a sphere for a point on an orthographic map: the inverse of orthographic.
inverseSinusoidalFind the point on a sphere for a point on a sinusoidal map: the inverse of sinusoidal.
inverseStereographicFind the point on a sphere for a point on a stereographic map: the inverse of stereographic.
lambertAzimuthalEqualAreaProject 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.
mercatorProject a point on a sphere with the Mercator projection: the conformal cylindrical map, which keeps angles and shapes locally true.
mollweideProject 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.
orthographicProject a point on a sphere with the orthographic projection: the globe as it looks from infinitely far away, above the map's centre.
sinusoidalProject a point on a sphere with the sinusoidal projection: an equal-area map, with every parallel at its true length.
stereographicProject a point on a sphere with the stereographic projection: a conformal map centred on any point, the usual choice for polar maps.

Terrain ​

NameDescription
GridInterfaceA raster grid of values over a map, such as a digital elevation model (DEM): rows × columns cells of equal size, stored row by row.
TerrainCurvatureInterfaceHow the terrain bends at a cell, along the slope and across it.
TerrainGradientInterfaceThe rate at which the terrain rises, east and north, at a cell.
TopographicWetnessIndexOptionsInterfaceOptions for topographicWetnessIndex.
ElevationGridInterfaceA digital elevation model: a GridInterface of heights in m.
aspectAtCompute the aspect of an elevation grid at a cell: the direction the terrain faces.
aspectGridCompute the aspect of every cell of an elevation grid, as a new grid in radians clockwise from north.
createGridCreate a raster grid, such as an elevation model, checking that its parts fit together.
curvatureAtCompute the profile and planform curvature of an elevation grid at a cell: how the terrain bends along the steepest slope and across it.
curvatureGridCompute the profile and planform curvature of every cell of an elevation grid, as two new grids in 1/m.
flowAccumulationCompute the flow accumulation of every cell of an elevation grid: the area that drains through it, its own included.
flowDirectionsCompute the D8 flow direction of every cell of an elevation grid: which of its eight neighbours water would run to.
gradientAtCompute the gradient of an elevation grid at a cell, from its 3 × 3 neighbourhood with Horn's method.
gridValueAtRead the value of one cell of a grid.
hillshadeAtCompute the hillshade of a patch of terrain: how brightly the Sun lights it, from its slope and aspect.
hillshadeGridCompute the hillshade of every cell of an elevation grid, as a new grid of brightness in [0, 1].
slopeAtCompute the slope of an elevation grid at a cell: how steep the terrain is.
slopeGridCompute the slope of every cell of an elevation grid, as a new grid in radians.
terrainRoughnessIndexAtCompute the Terrain Roughness Index of an elevation grid at a cell: the root-mean-square height difference between the cell and its eight neighbours.
terrainRoughnessIndexGridCompute the Terrain Roughness Index of every cell of an elevation grid, as a new grid in metres.
topographicWetnessIndexCompute 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 ​

NameDescription
TileBoundsInterfaceThe edges of a web map tile: the latitudes of its north and south edges and the longitudes of its west and east edges.
TileInterfaceA web map tile, in the scheme web maps use ("slippy maps", XYZ): at zoom z the spherical Web Mercator map is cut into 2z×2z square tiles.
fromQuadkeyFind the web map tile named by a quadkey: the inverse of quadkey.
quadkeyFind 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.
tileAtFind 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.
tileBoundsFind 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.