WKT and EWKT representation for geometric structures - PolarDB

GanosBase surface models can be represented in Well-Known Text (WKT) format — a text-based format that is human-readable and straightforward to construct.

Geometric structures

Beyond the basic types in the Open Geospatial Consortium (OGC) Simple Feature model, GanosBase supports five additional geometric structures for surface mesh modeling. All five can be expressed in WKT format. For details on the data models, see Data models in surface mesh models.

The following table summarizes the five structures and the dimensions each supports:

Structure	WKT keyword	Supported dimensions
IndexSurface	`INDEXSURFACE`	(default), Z, M
TriangleStrip	`TRIANGLESTRIP`	(default), Z, M, ZM
TriangleFan	`TRIANGLEFAN`	(default), Z, M, ZM
MeshGeom	`MESHGEOM`	(default), Z, M
SFmesh	— (JSON format)	—

IndexSurface

An IndexSurface represents a 3D surface defined by an explicit vertex list and a face index list. Each face references vertices by their zero-based index, allowing vertices to be shared across multiple faces.

Construct an IndexSurface using the INDEXSURFACE keyword with two sub-keywords:

VERTEX — the list of vertex coordinates. Separate coordinates within a vertex with spaces, and separate vertices with commas.
INDEX — the list of face definitions. Enclose each face's vertex indices in parentheses and separate indices with commas.

Format:

INDEXSURFACE(
    VERTEX(x1 y1 z1,
        x2 y2 z2,
        ...
    ),
    INDEX(
        (i1,i2,i3,...),
        (j1,j2,j3,...),
        ...
    )
)

Example:

INDEXSURFACE(
    VERTEX(201755.424609375 241700.688720703 7025.00027160645,201755.424609375 241700.688720703 6774.9998336792,202255.431298828 241700.688720703 6774.9998336792,202255.431298828 241700.688720703 7025.00027160645,202255.431298828 243149.418896484 6774.9998336792,201755.424609375 243149.418896484 6774.9998336792,201755.424609375 243149.418896484 7025.00027160645,202255.431298828 243149.418896484 7025.00027160645),
    INDEX((0,1,2),(2,3,0),(4,5,6),(6,7,4),(2,1,5),(5,4,2),(3,2,7),(4,7,2),(0,3,7),(7,6,0),(1,0,5),(6,5,0))
)

IndexSurface also supports Z and M dimensional information:

INDEXSURFACE Z(
    VERTEX(201755.424609375 241700.688720703 7025.00027160645,201755.424609375 241700.688720703 6774.9998336792, 202255.431298828 241700.688720703 6774.9998336792,202255.431298828 241700.688720703 7025.00027160645,202255.431298828 243149.418896484 6774.9998336792,201755.424609375 243149.418896484 6774.9998336792,201755.424609375 243149.418896484 7025.00027160645,202255.431298828 243149.418896484 7025.00027160645),
    INDEX((0,1,2),(2,3,0),(4,5,6),(6,7,4),(2,1,5),(5,4,2),(3,2,7),(4,7,2),(0,3,7),(7,6,0),(1,0,5),(6,5,0)))

INDEXSURFACE M(
    VERTEX(201755.424609375 241700.688720703 7025.00027160645,201755.424609375 241700.688720703 6774.9998336792, 202255.431298828 241700.688720703 6774.9998336792,202255.431298828 241700.688720703 7025.00027160645,202255.431298828 243149.418896484 6774.9998336792,201755.424609375 243149.418896484 6774.9998336792,201755.424609375 243149.418896484 7025.00027160645,202255.431298828 243149.418896484 7025.00027160645),
    INDEX((0,1,2),(2,3,0),(4,5,6),(6,7,4),(2,1,5),(5,4,2),(3,2,7),(4,7,2),(0,3,7),(7,6,0),(1,0,5),(6,5,0)))

TriangleStrip

A TriangleStrip is a connected sequence of triangles where each new triangle shares an edge with the previous one. It efficiently represents ribbon-like or strip surfaces without repeating shared vertices.

Construct a TriangleStrip by listing all coordinate strings after the TRIANGLESTRIP keyword.

Example:

TRIANGLESTRIP(0 0 1 1,0 10 2 2,10 10 3 3,10 0 4 4)

TriangleStrip also supports Z, M, and ZM dimensional information:

TRIANGLESTRIP Z(0 0 1,0 10 2,10 10 3,10 0 4)
TRIANGLESTRIP M(0 0 1,0 10 2,10 10 3,10 0 4)
TRIANGLESTRIP ZM(0 0 1 1,0 10 2 2,10 10 3 3,10 0 4 4)

TriangleFan

A TriangleFan is a set of triangles that all share a common center vertex, fanning out from that point. It suits cone-like or dome-shaped surfaces.

Construct a TriangleFan by listing all coordinate strings after the TRIANGLEFAN keyword.

Example:

TRIANGLEFAN(0 0 1 1,0 10 2 2,10 10 3 3,10 0 4 4)

TriangleFan also supports Z, M, and ZM dimensional information:

TRIANGLEFAN Z(0 0 1,0 10 2,10 10 3,10 0 4)
TRIANGLEFAN M(0 0 1,0 10 2,10 10 3,10 0 4)
TRIANGLEFAN ZM(0 0 1 1,0 10 2 2,10 10 3 3,10 0 4 4)

MeshGeom

A MeshGeom is a composite surface geometry that combines geometric patches with optional rendering attributes — normal vectors and texture coordinates. It is the primary structure for representing richly annotated 3D meshes in GanosBase.

Construct a MeshGeom using the MESHGEOM keyword with the following sub-keywords:

PATCH

PATCH defines the geometric content of the mesh. It can contain one or more sub-objects separated by commas. The supported geometry types within PATCH are:

Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon, IndexSurface, TriangleStrip, and TriangleFan.

Examples:

PATCH(POINT(0 0 1))
PATCH(
    POINT(0 0 1),
    TRIANGLESTRIP(0 0 1,0 10 2,10 10 3,10 0 4)
    )

NORMAL

NORMAL defines the normal vectors for the mesh, expressed as 3D point coordinates. Separate coordinate strings with commas and enclose each sub-object in parentheses. The number of normal vector points must match the number of vertices in the corresponding PATCH sub-object.

Examples:

NORMAL(
    (0 0 0, 1 1 1,2 2 2, 3 3 3)
    )

NORMAL(
    (0 0 0, 1 1 1,2 2 2, 3 3 3),
    (1 2 1, 3 3 4)
    )

TEXCOORD

TEXCOORD defines the texture coordinates for the mesh, expressed as 2D point coordinates. Separate coordinate strings with commas and enclose each sub-object in parentheses. The number of texture coordinate points must match the number of vertices in the corresponding PATCH sub-object.

Examples:

TEXCOORD(
    (0 0, 1 1, 2 2, 3 3)
)

TEXCOORD(
    (0 0, 1 1, 2 2, 3 3),
    (1 1, 0 0, 2 2, 3 3)
)

Examples

The following examples show how a MeshGeom is expressed in WKT.

Two PATCH sub-objects with an IndexSurface:

MESHGEOM(
    PATCH(
        POINT(0 0 1),
        INDEXSURFACE(VERTEX(0 0 1,0 10 2,10 10 3,10 0 4), INDEX((0,1,2),(1,2,3)))
    )
)

A TriangleStrip patch with NORMAL and TEXCOORD attributes:

MESHGEOM(
    PATCH(
        TRIANGLESTRIP(0 0 1,0 10 2,10 10 3,10 0 4)
    ),
    NORMAL(
        (0 0 0, 1 1 1,2 2 2, 3 3 3)
    ),
    TEXCOORD(
        (0 0, 1 1, 2 2, 3 3)
    )
)

MeshGeom also supports Z and M dimensional information. All patches within a single MeshGeom must use the same dimensions.

MESHGEOM(
    PATCH(
        POINT M(0 0 1),
        INDEXSURFACE M(
            VERTEX(0 0 1,0 10 2,10 10 3,10 0 4),
            INDEX((0,1,2),(1,2,3))
        )
    )
)

Reference an object

A MeshGeom can reference another MeshGeom stored in a database table instead of embedding coordinates inline. Use the schema, table, column, and key keywords. table, column, and key are mandatory; schema is optional. Enclose each value in @ symbols.

Format:

MESHGEOM(
    schema(@schema_name@),
    table(@table_name@),
    column(@column_name@),
    key(@where_clause@)
)

Example:

MESHGEOM(
    schema(@public@),
    table(@mytable@),
    column(@mycolumn@),
    key(@id=1@)
)

SFmesh

An SFmesh is a scene-graph structure that organizes multiple MeshGeom objects, materials, and textures into a hierarchical node tree. Unlike the other geometry types, SFmesh uses JSON as its WKT representation.

An SFmesh JSON object contains the following fields:

Field	Type	Description
`version`	integer	SFmesh version. Valid value: `1`.
`srid`	integer	Spatial reference system identifier (SRID).
`lod`	integer	Level of Detail (LOD).
`root`	integer	Root node ID. Default value: `0`.
`meshgeoms`	array	Referenced MeshGeom objects. Each entry uses MeshGeom WKT format and can be an external reference.
`meshes`	array	Referenced SFmesh objects. Each entry uses SFmesh WKT format and can be an external reference.
`textures`	array	Texture objects used in the mesh.
`materials`	array	Material objects that define surface properties of the mesh.
`primitives`	array	Primitive elements, each of type `meshgeom` or `mesh`. A `meshgeom` primitive can include material information via the `material` keyword.
`nodes`	array	Hierarchical structure of mesh components.

Each node in nodes can have the following attributes:

Attribute	Description
`primitive`	Primitive information for this node.
`children`	Array of child node IDs.
`id`	Node ID within this structure.
`matrix`	4x4 transformation matrix in the following layout: `[a, b, c, xoff, d, e, f, yoff, g, h, i, zoff, 0, 0, 0, 1]`.

Example

{
  "version": 1,
  "root": 0,
  "meshgeoms": ["MESHGEOM(PATCH(TRIANGLESTRIP(0 0,0 10,10 10,10 0)))"],
  "meshes": [
    "MESH(schema(@public@), table(@t_mesh@), column(@the_mesh@), key(@num=1@))"
  ],
  "primitives": [
    {
      "mesh": 0
    },
    {
      "meshgeom": 0
    }
  ],
  "nodes": [
    {
      "children": [1, 2],
      "id": 100
    },
    {
      "primitive": 0
    },
    {
      "primitive": 1,
      "matrix": [2, 0, 0, 1, 0, 2, 0, 3, 0, 0, 2, 4, 0, 0, 0, 1],
      "id": 10
    }
  ],
  "materials": [
    {
      "type": "db",
      "attributes": {
        "schema": "public",
        "table": "t_material",
        "column": "the_material",
        "key": "num=1"
      }
    }
  ],
  "textures": [
    {
      "compressionType": "None",
      "format": "JPEG",
      "wrap": "Wrap",
      "type": "Url",
      "depth": 3,
      "width": 256,
      "height": 256,
      "size": 15,
      "data": "http://aaa.png"
    }
  ]
}

Reference an object

An SFmesh can reference another SFmesh stored in a database table. Use the MESH keyword with schema, table, column, and key. table, column, and key are mandatory; schema is optional. Enclose each value in @ symbols.

Format:

MESH(
    schema(@schema_name@),
    table(@table_name@),
    column(@column_name@),
    key(@where_clause@)
)

Example:

MESH(
    schema(@public@),
    table(@mytable@),
    column(@mycolumn@),
    key(@id=1@)
)

EWKT

Standard WKT does not carry spatial reference system information or specify whether a 3D geometry is filled. Extended Well-Known Text (EWKT) addresses both limitations by prepending metadata fields before the geometry. Fields are separated by semicolons (;).

Two optional fields can appear before the geometry:

SRID — the spatial reference system identifier (SRID). For supported values, see Spatial reference systems.
SOLID — specifies whether the geometry is filled. Valid values: true or false (default).

Examples:

SRID=4326;MESHGEOM(PATCH(INDEXSURFACE M(VERTEX(0 0 1,0 10 2,10 10 3,10 04), INDEX((0,1,2),(1,2,3)))))

SRID=4326;SOLID=true;MESHGEOM(PATCH(INDEXSURFACE M(VERTEX(0 0 1,0 10 2,1010 3,10 0 4), INDEX((0,1,2),(1,2,3)))))