ST_3DGridPath function to calculate a path in a 3D grid - PolarDB

ST_3DGridPath finds the least-cost path between two 3D points across a grid space.

Syntax

geomgrid[] ST_3DGridPath(geometry start, geometry end, box3d range, gridcost[] barriers, params text default '');

Parameters

Parameter	Type	Description
`start`	`geometry`	The start point (3D point).
`end`	`geometry`	The end point (3D point).
`range`	`box3d`	The bounding box that defines the path planning area.
`barriers`	`gridcost[]`	The traversal cost of all barrier grids. Call ST_CostUnion to combine multiple cost sets into a single `gridcost[]` value.
`params`	`text`	A JSON string of algorithm options. Defaults to `''` (applies all default values).

params options

Field	Values	Default	Description
`algorithm`	`dij`, `astar`, `nb_astar`	`astar`	The pathfinding algorithm. `dij` uses Dijkstra's algorithm. `astar` uses A. `nb_astar` uses bidirectional A.
`movement`	`cross`, `octothorpe`, `strict_octothorpe`	`cross`	The movement mode. `cross` moves only to adjacent grids. `octothorpe` moves to adjacent and diagonal grids. `strict_octothorpe` moves to diagonal grids only when adjacent grids are passable.
`distance`	`euclidean`, `manhattan`, `chebyshev`	`manhattan`	The distance estimation method used by the heuristic. `manhattan` is efficient for grid-aligned movement. `euclidean` is more accurate for diagonal paths. `chebyshev` treats diagonal and straight movement as equal cost.

Example `params` value:

{"algorithm":"astar","movement":"strict_octothorpe"}

Omitted fields use their default values. Passing an empty string or omitting params entirely applies all defaults (astar, cross, manhattan).

Description

ST_3DGridPath computes a grid-based path using the specified algorithm and returns the traversed grids in path order.

The start and end parameters accept 3D points. If the z-axis values are imprecise, the algorithm automatically snaps them to appropriate z-axis positions within the grid.
The range parameter defines the planning boundary. Configure it based on your digital surface model (DSM) data.
The barriers parameter encodes the traversal cost of obstacle grids. Call ST_CostUnion to combine multiple cost sets into a single gridcost[] value.

Return value

An array of geomgrid values arranged in sequence from start to end.

Examples

Example 1: Default algorithm settings

This example uses all default settings (astar, cross, manhattan). With 4-directional movement only, the path traverses more grid cells to reach the destination.

select st_astext(ST_3DGridPath(st_geomfromewkt('srid=4490;POINT Z (1 1 1)'), st_geomfromewkt('srid=4490;POINT Z (5 6 3)'),
'BOX3D(0 0 0,10 10 10)'::box3d, st_costunion(array[st_setcost(array[st_gridfromtext('GZ0000000001')],1), st_setcost(array[st_gridfromtext('GZ0000000000')],5)])));

Output:

{GZ0000000006,GZ0000000042,GZ0000000046,GZ0000000064,GZ0000000420,GZ0000000422,
GZ0000000426,GZ0000000604,GZ0000000640,GZ0000000644,GZ0000004200,GZ0000004240,
GZ0000004244,GZ0000004600,GZ0000004602,GZ0000004620,GZ0000004622,GZ0000006400,
GZ0000006420}

Example 2: Diagonal movement with Euclidean distance

This example enables diagonal movement (strict_octothorpe) and Euclidean distance estimation. The path takes more direct diagonal steps, resulting in fewer total grid cells (11 instead of 19).

select ST_3DGridPath(st_geomfromewkt('srid=4490;POINT Z (1 1 1)'), st_geomfromewkt('srid=4490;POINT Z (5 6 3)'),
'BOX3D(0 0 0,10 10 10)'::box3d, st_costunion(array[st_setcost(array[st_gridfromtext('GZ0000000001')],1), st_setcost(array[st_gridfromtext('GZ0000000000')],5)]), '{"algorithm":"astar","movement":"strict_octothorpe","distance":"euclidean"}');