SFMESH structure and syntax reference - PolarDB

SFMESH is a JSON-based format for well-known texts (WKTs) that stores 3D mesh geometry and node hierarchy data in PolarDB for PostgreSQL (GanosBase).

Top-level fields

An SFMESH JSON object contains the following top-level fields: version, srid, lod, root, meshgeoms, meshes, textures, materials, primitives, and nodes.

Field	Type	Description	Default
`version`	integer	The SFMESH format version. Must be set to `1`.	—
`srid`	integer	The spatial reference identifier (SRID).	—
`lod`	number	The level of detail (LOD).	—
`root`	integer	The root node ID of the node tree.	`0`
`meshgeoms`	array	Inline mesh geometry objects defined using MESHGEOM WKT syntax. Can be referenced objects.	—
`meshes`	array	External mesh references pointing to sfmesh objects stored in a database table. Can be referenced objects.	—
`textures`	array	Texture objects.	—
`materials`	array	Material objects.	—
`primitives`	array	All primitives. Each primitive is either a `meshgeom` type or a `mesh` type.	—
`nodes`	array	Nodes that define the tree structure for geometry organization.	—

Primitives

Primitives are of two types: meshgeom and mesh. Primitives of the meshgeom type can carry material information, associated via the material keyword.

Example:

"primitives": [
    { "mesh": 0 },
    { "meshgeom": 0 }
]

Nodes

Each node in the nodes array defines part of the tree structure used to organize geometry. A node can include the following attributes:

Attribute	Description
`primitive`	Index into the `primitives` array, associating this node with a geometry primitive.
`children`	Array of child node indices.
`matrix`	A 4x4 transformation matrix stored as a 16-element array in row-major order.
`id`	An identifier associated with this node.

Transformation matrix

The matrix field is a 4x4 affine transformation matrix, stored as a flat 16-element array in row-major order:

/ a  b  c  xoff \
| d  e  f  yoff |
| g  h  i  zoff |
\ 0  0  0     1 /

The array elements map to the matrix in left-to-right, top-to-bottom (row-major) order: [a, b, c, xoff, d, e, f, yoff, g, h, i, zoff, 0, 0, 0, 1].

Example:

{
    "primitive": 1,
    "matrix": [2, 0, 0, 1,
               0, 2, 0, 3,
               0, 0, 2, 4,
               0, 0, 0, 1],
    "id": 10
}

Inline geometry (meshgeoms)

The meshgeoms field holds inline mesh geometries defined using MESHGEOM WKT syntax.

Syntax:

MESHGEOM(PATCH(TRIANGLESTRIP(<coordinates>)))

Example:

"meshgeoms": [
    "MESHGEOM(PATCH(TRIANGLESTRIP(0 0,0 10,10 10,10 0)))"
]

External mesh references (meshes)

The meshes field holds references to sfmesh objects stored in a database table. Each reference uses the MESH keyword with the following parameters:

Parameter	Required	Description
`schema`	No	Database schema name.
`table`	Yes	Database table name.
`column`	Yes	Column name storing the mesh data.
`key`	Yes	WHERE clause condition identifying the row.

Each parameter value is enclosed by at signs (@). For example, key(@num=1@) corresponds to the WHERE clause num=1.

Syntax:

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

Example:

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

Texture objects

Each object in the textures array describes a texture resource:

Field	Description
`compressionType`	Compression type, e.g., `None`.
`format`	Image format, e.g., `JPEG`.
`wrap`	Texture wrap mode, e.g., `Wrap`.
`type`	Source type, e.g., `Url`.
`depth`	Color depth.
`width`	Image width in pixels.
`height`	Image height in pixels.
`size`	File size.
`data`	Texture data or URL.

Material objects

Each object in the materials array describes how surface appearance is defined:

Field	Description
`type`	Material source type. Use `db` to reference material data from a database table.
`attributes`	An object with `schema`, `table`, `column`, and `key` fields, following the same conventions as the MESH reference format.

Complete 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"
        }
    ]
}