PolarDB:ST_3DGridPath - PolarDB

Calculates the shortest path between two 3D points within a specified bounding volume, returning the path as a sequence of geometry grids.

Syntax

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

Parameters

Parameter	Description
`start`	The start point. Must be a 3D point (`geometry`). Inexact z-axis values are accepted — the algorithm automatically finds the nearest valid z-axis position.
`end`	The end point. Must be a 3D point (`geometry`). Inexact z-axis values are accepted — the algorithm automatically finds the nearest valid z-axis position.
`range`	The bounding volume for path planning, specified as a `box3d`. Configure this parameter based on your digital surface model (DSM) data.
`barriers`	A `gridcost[]` array that combines the traversal costs of all grids containing barriers. To build this array, call ST_CostUnion.
`params`	(Optional) A JSON string that configures the pathfinding algorithm. Defaults to `''`. Unset fields fall back to their defaults.

params fields

Field	Description	Default
`algorithm`	The pathfinding algorithm. Valid values: `dij` (Dijkstra's algorithm), `astar` (A* algorithm), `nb_astar` (bidirectional A* algorithm).	`astar`
`movement`	The movement mode. Valid values: `cross` (horizontally and vertically adjacent grids only), `octothorpe` (adjacent and diagonal grids), `strict_octothorpe` (moves to diagonal grids when adjacent grids are passable).	`cross`
`distance`	The distance estimation method. Valid values: `euclidean` (Euclidean distance), `manhattan` (Manhattan distance), `chebyshev` (Chebyshev distance).	`manhattan`

Example `params` value:

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

If params is left blank or a field is omitted, the system uses the default value for that field.

Return value

Returns a geomgrid[] array of geometry grids arranged in path order from start to end.

Description

ST_3DGridPath finds the lowest-cost path through a 3D grid system between two points. The path is constrained to the bounding volume defined by range and respects grid traversal costs defined in barriers.

Key behaviors:

Approximate z-axis input: Both start and end accept 3D points with inexact z-axis values. The algorithm snaps each point to the nearest valid z-axis position within the grid.
DSM-based range: The range parameter defines the path planning volume. Set it based on your digital surface model (DSM) data.
Cost-aware routing: The barriers parameter aggregates traversal costs across all barrier grids. Call ST_CostUnion to compute this value.
Default algorithm: When params is omitted, the function uses the A* algorithm (astar), cross movement (cross), and Manhattan distance (manhattan).

3D grid system

Examples

Example 1: Default algorithm settings

This example calculates a path using default algorithm settings (A*, cross movement, Manhattan distance).

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)
    ])
  )
);

Result:

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

Example 2: Custom algorithm settings

This example uses A* with strict octothorpe movement and Euclidean distance estimation, which allows diagonal movement only through passable adjacent grids.

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"}'
);

Result:

{GZ0000000006,GZ0000000060,GZ0000000066,GZ0000000600,GZ0000000606,GZ0000000660,
GZ0000000666,GZ0000006000,GZ0000006040,GZ0000006044,GZ0000006420}