Class HexGrid

The H3 hexagonal hierarchical index laid over a world.

Planets use their own directions: a planet-centred point maps to latitude asin(y / |p|) and longitude atan2(x, z), the same convention as World.frameAt. A resolution's metric size scales with the radius: edge(res) = H3 edge(res) × radius / 6 371 007 m. On a 120 km planet, resolution 8 (531 m on Earth) is 10 m across; resolution 3 (69 km on Earth) is 1.3 km.
Flat worlds map local metres onto an Earth-sized globe near the equator (equirectangular around PLANE_ANCHOR): latitude = −z / R⊕, longitude = anchor + x / R⊕. Cell sizes then match H3's published resolutions in metres (res 8 ≈ 531 m edge, 0.74 km²). Within ±2000 km of the origin cells are within 5 % of their nominal size; beyond that they stretch east–west by 1 / cos(latitude).

Local positions are [x, z] in a LocalFrame (x east, z south): the world itself on flat worlds, a tangent plane (gnomonic projection) on planets.

Example

const grid = new HexGrid(world)
const res = grid.resolutionFor(400)          // the resolution whose edge is nearest 400 m
const cell = grid.cellAtLocal(120, -40, res)
grid.centerLocal(cell)                       // [x, z] of the cell centre
grid.boundaryLocal(cell)                     // hexagon corners, [x, z][]

Index

Constructors

constructor

new HexGrid(world: World, frame?: LocalFrame): HexGrid
Lays the index over world.
Parameters
- world: World
- Optionalframe: LocalFrame
  Local frame for …Local positions (default: world.frame, followed across world changes).
Returns HexGrid
- Defined in city/src/hex.ts:47

Properties

`Readonly`world

world: World

The world the index is laid over.

Accessors

frame

get frame(): LocalFrame
Frame that local [x, z] positions are in.

Returns LocalFrame
- Defined in city/src/hex.ts:53

scale

get scale(): number
Metres per radian of H3 latitude/longitude: the planet radius, or H3's Earth radius on flat worlds.

Returns number
- Defined in city/src/hex.ts:63

sizeFactor

get sizeFactor(): number
Linear size of this world's cells relative to H3's published Earth sizes (1 on flat worlds).

Returns number
- Defined in city/src/hex.ts:68

sphere

get sphere(): boolean
True on planets.

Returns boolean
- Defined in city/src/hex.ts:58

Methods

area

area(cell: string): number
Area of a cell on this world, m².
Parameters
- cell: string
Returns number
- Defined in city/src/hex.ts:162

boundaryLocal

boundaryLocal(cell: string): [number, number][]
Corners of a cell (6, or 5 for pentagons, plus extra points where it crosses an icosahedron edge) as local [x, z], counter-clockwise seen from above.
Parameters
- cell: string
Returns [number, number][]
- Defined in city/src/hex.ts:157

cellAt

cellAt(px: number, py: number, pz: number, res: number): string
Cell containing a base-surface world position.
Parameters
- px: number
- py: number
- pz: number
- res: number
Returns string
- Defined in city/src/hex.ts:134

cellAtLocal

cellAtLocal(x: number, z: number, res: number): string
Cell containing local [x, z].
Parameters
- x: number
- z: number
- res: number
Returns string
- Defined in city/src/hex.ts:140

center

center(cell: string, out?: Vec3): Vec3
Base-surface world position of a cell's centre.
Parameters
- cell: string
- out: Vec3 = ...
Returns Vec3
- Defined in city/src/hex.ts:146

centerLocal

centerLocal(cell: string, out?: [number, number]): [number, number]
Local [x, z] of a cell's centre.
Parameters
- cell: string
- out: [number, number] = ...
Returns [number, number]
- Defined in city/src/hex.ts:152

children

children(cell: string, res: number): string[]
The descendants of cell at a finer resolution (7 per level; 6 under pentagons).
Parameters
- cell: string
- res: number
Returns string[]
- Defined in city/src/hex.ts:184

disk

disk(cell: string, k: number): string[]
Every cell within k steps of cell (its k-ring disk, cell included).
Parameters
- cell: string
- k: number
Returns string[]
- Defined in city/src/hex.ts:174

edgeLength

edgeLength(res: number): number
Average hexagon edge length at res on this world, metres.
Parameters
- res: number
Returns number
- Defined in city/src/hex.ts:73

fromLatLng

fromLatLng(lat: number, lng: number, out?: Vec3): Vec3
Base-surface world position of a latitude/longitude in degrees (on the sphere, or [x, 0, z]).
Parameters
- lat: number
- lng: number
- out: Vec3 = ...
Returns Vec3
- Defined in city/src/hex.ts:97

fromLocal

fromLocal(x: number, z: number, out?: Vec3): Vec3
Base-surface world position under local [x, z] (on the sphere, or [x, 0, z]).
Parameters
- x: number
- z: number
- out: Vec3 = ...
Returns Vec3
- Defined in city/src/hex.ts:125

parent

parent(cell: string, res: number): string
The ancestor of cell at a coarser resolution.
Parameters
- cell: string
- res: number
Returns string
- Defined in city/src/hex.ts:179

resolution

resolution(cell: string): number
Resolution of a cell.
Parameters
- cell: string
Returns number
- Defined in city/src/hex.ts:189

resolutionFor

resolutionFor(metres: number): number
The resolution (0…15) whose average edge length is closest (in ratio) to metres on this world.
Parameters
- metres: number
Returns number
- Defined in city/src/hex.ts:78

toLatLng

toLatLng(px: number, py: number, pz: number): [number, number]
[latitude, longitude] in degrees of a base-surface world position (planet-centred, or [x, ·, z]).
Parameters
- px: number
- py: number
- pz: number
Returns [number, number]
- Defined in city/src/hex.ts:88

toLocal

toLocal(p: Vec3, out?: [number, number]): [number, number]
Local [x, z] of a base-surface world position (NaN on the far side of a planet).
Parameters
- p: Vec3
- out: [number, number] = ...
Returns [number, number]
- Defined in city/src/hex.ts:110

Class HexGrid

Example

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Parameters

Returns HexGrid

Properties

Readonlyworld

Accessors

frame

Returns LocalFrame

scale

Returns number

sizeFactor

Returns number

sphere

Returns boolean

Methods

area

Parameters

Returns number

boundaryLocal

Parameters

Returns [number, number][]

cellAt

Parameters

Returns string

cellAtLocal

Parameters

Returns string

center

Parameters

Returns Vec3

centerLocal

Parameters

Returns [number, number]

children

Parameters

Returns string[]

disk

Parameters

Returns string[]

edgeLength

Parameters

Returns number

fromLatLng

Parameters

Returns Vec3

fromLocal

Parameters

Returns Vec3

parent

Parameters

Returns string

resolution

Parameters

Returns number

resolutionFor

Parameters

Returns number

toLatLng

Parameters

Returns [number, number]

toLocal

Parameters

Returns [number, number]

Settings

On This Page

`Readonly`world