Returns an array of geographic grid codes that intersect with a 3D geometry, based on the CGC2000 (China Geodetic Coordinate System 2000) national standard grid hierarchy.
Syntax
geomgrid[] ST_As3DGrid(geometry geom3d, integer precision, bool degenerated default false);
geomgrid[] ST_As3DGrid(meshgeom geom3d, integer precision, bool degenerated default false);
geomgrid[] ST_As3DGrid(sfmesh geom3d, integer precision, bool degenerated default false);
geomgrid[] ST_As3DGrid(vomesh geom3d, integer precision, bool degenerated default false);Parameters
| Parameter | Description |
|---|---|
geom3d | The 3D geometry to encode. Accepts geometry, meshgeom, sfmesh, or vomesh types. |
precision | The grid precision level. Valid values: 1 to 32. Higher values produce finer grid subdivisions. |
degenerated | Specifies whether to include degenerated grid cells. Default: false. |
Description
CGC2000 defines a hierarchical geographic grid that subdivides space by longitude, latitude, and altitude. Each grid cell at a given precision level corresponds to a fixed spatial extent. ST_As3DGrid finds all cells in this hierarchy that intersect the input geometry and returns their codes as a geomgrid[] array.
The input geometry must use SRID 4490 (CGC2000). If your geometry uses a different spatial reference system (SRS), convert its coordinates to CGC2000 before calling this function.
Choose the overload based on your geometry type:
| Input type | When to use |
|---|---|
geometry | Standard OGC geometry objects, such as LINESTRING Z, POINT Z, or POLYGON Z |
meshgeom | Surface or solid mesh geometries created with st_meshgeomfromtext |
sfmesh | Scene-format mesh geometries defined in JSON and created with st_meshfromtext |
vomesh | Volumetric mesh geometries with explicit cell topology created with ST_VOMeshFromText |
The following figures show an example of 3D geographic grids intersecting a geometry.
Examples
Example 1: Encode a 3D line string (geometry type)
Use this overload when your input is a standard OGC geometry with Z coordinates, such as a LINESTRING Z.
SELECT ST_AsText(ST_As3DGrid(
'srid=4490;LINESTRING Z (116 39 2000,116.012 39.009 3000)'::geometry, 10));Result:
{GZ0026204626,GZ0026204662,GZ0026206404,GZ0026206440}Example 2: Encode a solid mesh geometry (meshgeom type)
Use this overload when your input is a surface or solid mesh created with st_meshgeomfromtext. The SOLID=TRUE flag indicates a closed volumetric solid.
SELECT ST_AsText(ST_As3DGrid(st_meshgeomfromtext(
'srid=4490;SOLID=TRUE;MESHGEOM(PATCH(INDEXSURFACE Z (VERTEX(115.966 38.9757000000001 3000,
116 38.9757000000001 3000,116 38.9999999999999 3000,115.966 38.9999999999999 3000,116 38.9999999999999 0,
116 38.9757000000001 0,115.966 38.9757000000001 0,115.966 38.9999999999999 0),
INDEX((0,1,2),(2,3,0),(4,5,6),(6,7,4),(3,7,6),(6,0,3),(0,6,5),(5,1,0),(1,5,4),(4,2,1),(2,4,7),(7,3,2)))))'),10));Result:
{GZ0026204626,GZ0026206404,GZ4026204626,GZ4026206404}Example 3: Encode a scene-format mesh (sfmesh type)
Use this overload when your input is a JSON-format scene mesh created with st_meshfromtext. The matrix field applies a transformation (scale and translation) to the base geometry before encoding.
SELECT ST_AsText(ST_As3DGrid(st_meshfromtext(
'{"version" : 1, "srid" : 4490, "root" : 0,
"meshgeoms" : ["MESHGEOM(PATCH(POLYGON Z ((0 0 0,1 0 0,1 1 0,0 1 0,0 0 0))))"],
"primitives" : [{"meshgeom" : 0}], "nodes" : [{"primitive" : 0,"matrix" : [0.012,0,0,116,0,0.009,0,39,0,0,1000,0,0,0,0,1]}]}'),8,true));Result:
{GZ00262046,GZ00262064,GZ40262046,GZ40262064}Example 4: Encode a volumetric mesh (vomesh type)
Use this overload when your input is a volumetric mesh with explicit cell and face topology created with ST_VOMeshFromText. The LOD parameter specifies the level of detail of the mesh.
SELECT ST_AsText(ST_As3DGrid(ST_VOMeshFromText(
'SRID=4490;LOD=2;VOMESH(VERTEX(COORDS(116.012 39 0,116 39.009 0,115.988 39 0,116 38.991 0,116 39 1000)),
FACE(INDEX((0,1,2,3),(1,0,4),(2,1,4),(3,2,4),(0,3,4))),
CELL(INDEX((0,1,2,3,4)),DIRECTION((0,1,1,1,0))))'),15, true));Result:
{GZ002620462666066,GZ002620466222022,GZ002620640444044,GZ002620644000000,GZ402620462666066,GZ402620466222022,GZ402620640444044,GZ402620644000000}