Import glTF files using ST_ImportGLTF - PolarDB

Imports a GL Transmission Format (glTF) file of the sfmesh type into a database.

Syntax

-- Import from object storage
boolean ST_ImportGLTF(text table_name, text url, text id, text options default '{}');

-- Import from binary content
boolean ST_ImportGLTF(text table_name, bytea content, text id, text options default '{}');

Parameters

Parameter	Type	Required	Description
`table_name`	text	Yes	The name of the glTF primary table. Also used as the prefix for any sharded tables generated during import.
`url`	text	Yes (Syntax 1)	The path to the glTF file in an object storage service such as an Object Storage Service (OSS) bucket. For path format details, see Object storage paths.
`content`	bytea	Yes (Syntax 2)	The binary content of the glTF file. Use this parameter instead of `url` to import directly from memory.
`id`	text	Yes	A unique identifier for the glTF file being imported. When importing multiple models into the same table, each model must have a distinct ID.
`options`	text	No	A JSON string of import options. Defaults to `'{}'`. See Options for details.

Options

All fields are optional. Pass them as a JSON string.

Field	Type	Default	Description
`schema`	String	`public`	The schema of the target table.
`flip_y_z`	Boolean	`true`	Specifies whether to swap values on the y-axis and z-axis. glTF uses a y-up coordinate system by default, while GanosBase uses z-up. Set this to `false` only if your data is already in z-up orientation.
`split_meshgeom`	Boolean	`false`	Specifies whether to split geometry data into a separate table named `[table_name]_meshgeom`. Enable this when individual records contain large numbers of complex geometries to prevent records from becoming too large. The primary table references the geometry table after the split.
`split_texture`	Boolean	`false`	Specifies whether to split embedded image textures into a separate table named `[table_name]_texture`. Enable this for data with many embedded textures, such as oblique photographs. The primary table references the texture table after the split. Has no effect when textures are stored as URLs or when the glTF file contains no embedded image textures.
`sfmesh_column`	String	`gltf_data`	The name of the sfmesh data column in the primary table.
`gltf_id_column`	String	`gltf_id`	The name of the ID column in the primary table.

Limitations

The following limitations apply. Imports that do not meet these requirements fail.

Only sfmesh data is imported. Camera, skeleton, and animation data is ignored.
Only meshes generated with the triangulation method are supported.
Draco-compressed data is not supported.
Only the fully embedded mode is supported. Binary plug-ins and texture plug-ins are not supported.

Generated tables

A successful import creates the following tables in the database.

Primary table

Field	Type	Description
`id`	serial	Auto-generated unique ID. Primary key.
`[gltf_id_column]`	text	The glTF file ID. Configurable via `gltf_id_column`; defaults to `gltf_id`.
`[sfmesh_column]`	sfmesh	The 3D mesh data. Configurable via `sfmesh_column`; defaults to `gltf_data`.

Only the [gltf_id_column] and [sfmesh_column] fields are writable. All other fields in the primary table are populated automatically.

Texture table (`[table_name]_texture`)

Created only when split_texture is true and the glTF file contains embedded image textures.

Field	Type	Description
`id`	serial	Auto-generated unique ID. Primary key.
`gltf_id`	text	The glTF file ID. Must be set to `gltf_id`.
`texture_id`	text	The index of the texture in the original glTF file.
`texture`	texture	The texture data.

Geometry table (`[table_name]_meshgeom`)

Created only when split_meshgeom is true and the glTF file contains geometry data.

Field	Type	Description
`id`	serial	Auto-generated unique ID. Primary key.
`gltf_id`	text	The glTF file ID. Must be set to `gltf_id`.
`meshgeom_id`	text	The index of the mesh in the original glTF file.
`meshgeom`	meshgeom	The geometry data.

Geometry tables and texture tables can be split simultaneously without interfering with each other. If you import multiple models into the same table, use a different id for each model. Duplicate IDs produce duplicate geometry records.

Examples

Import a glTF file from OSS

SELECT ST_ImportGLTF(
  'test_gltf',
  'OSS://<ak>:<ak_secret>@oss-cn-beijing-internal.aliyuncs.com/mybucket/path_to_gltf.gltf',
  'my_gltf'
);

Returns t on success.

Import with texture and geometry splitting

For oblique photographs or models with many textures and complex geometries, split the data into separate tables to keep individual records from growing too large.

SELECT ST_ImportGLTF(
  'building_model',
  'OSS://<ak>:<ak_secret>@oss-cn-beijing-internal.aliyuncs.com/mybucket/building.gltf',
  'building_001',
  '{"split_texture": true, "split_meshgeom": true, "flip_y_z": false}'
);

This creates three tables: building_model (primary), building_model_texture, and building_model_meshgeom.