Skip to content

Documentation / @interstellar-tools/maps / gradientAt

Function: gradientAt() ​

ts
function gradientAt(
  grid: GridInterface,
  row: number,
  column: number
): TerrainGradientInterface;

Defined in: terrain/gradient-at.ts:65

Compute the gradient of an elevation grid at a cell, from its 3 × 3 neighbourhood with Horn's method.

∂z∂x=(z13+2z23+z33)−(z11+2z21+z31)8Δx,∂z∂y=(z11+2z12+z13)−(z31+2z32+z33)8Δy

Where:

  • zrc is the height in row r and column c of the neighbourhood, from the north-west: z22 is the cell itself (m)
  • Δx and Δy are the cell size east–west and north–south (m)

Units

  • Inputs: heights and the cell size in m.
  • Output: dzdx and dzdy in m/m: the rise per metre towards the east and towards the north.

Notes

  • Each difference is taken across two cells, weighting the middle row or column twice, which smooths out noise in the heights. It's the method most GIS software uses for slope and aspect.
  • Row 0 is the northern edge of the grid (see GridInterface), so ∂z/∂y is the northern row minus the southern one.
  • On the grid's edge, or next to a missing cell, the neighbourhood is incomplete and both components are NaN.

Parameters ​

ParameterTypeDescription
gridGridInterfaceElevation grid, heights in m.
rownumberRow index, 0 at the north edge (an integer in [0, rows)).
columnnumberColumn index, 0 at the west edge (an integer in [0, columns)).

Returns ​

TerrainGradientInterface

The gradient { dzdx, dzdy } in m/m, NaN where it can't be computed.

Throws ​

If row or column is not an integer inside the grid.

Example ​

ts
// Rising 1 m every 10 m to the east
const grid = createGrid({
  rows: 3,
  columns: 3,
  values: [0, 1, 2, 0, 1, 2, 0, 1, 2],
  cellSize: { x: 10, y: 10 }
});

gradientAt(grid, 1, 1); // { dzdx: 0.1, dzdy: 0 }

See ​