Use ST_ImportObj to import OBJ files - PolarDB

Imports an OBJ file from an Object Storage Service (OSS) bucket or a binary stream into a database.

Syntax

boolean ST_ImportObj(text table_name, text url,     text id, text options DEFAULT '{}');
boolean ST_ImportObj(text table_name, bytea content, text id, text options DEFAULT '{}');

The first overload loads the OBJ file from an OSS path. The second loads it from an in-memory binary stream. Both return true on success and false on failure.

Parameters

Parameter	Type	Description
`table_name`	text	Name of the OBJ primary table and the prefix for its sharded tables.
`url`	text	OSS path to the OBJ file. Format: `OSS://<ak>:<ak_secret>@<endpoint>/<bucket>/<path>.obj`
`content`	bytea	OBJ file content as a binary stream.
`id`	text	Identifier assigned to the imported OBJ record.
`options`	text	JSON string of import options. Defaults to `'{}'`. See Import options.

Import options

Pass options as a JSON string, for example: '{"force_triangulate": false, "schema": "myschema"}'.

Options fall into two groups: storage configuration and import behavior.

Storage configuration

Option	Type	Default	Description
`schema`	String	`public`	Schema of the target tables.
`search_path`	String	Parent directory of the OBJ URL; empty when using binary content	Path used to locate material and texture files.
`obj_id_column`	String	`obj_id`	Name of the data ID field in the primary table.
`obj_data_column`	String	`obj_data`	Name of the data field in the primary table.

Import behavior

Option	Type	Default	Description
`ignore_missing`	Boolean	`true`	When `true`, missing material or texture files are silently skipped. Set to `false` to abort the import if any referenced material or texture file cannot be found.
`force_triangulate`	Boolean	`true`	When `true`, non-triangular faces are automatically converted to triangles. Set to `false` to import non-triangular faces as-is.
`metallic_roughness`	Boolean	`true`	When `true`, materials are parsed as the metallic_roughness PBR type. Set to `false` to parse materials as the specular-glossiness type instead.

Limitations

Only textures of the diffusetexture type are supported. Textures of other types are ignored during import.

Table schemas

ST_ImportObj creates or populates three tables: a primary table, a component table, and a texture table.

Primary table

Field	Type	Description
`id`	serial	Primary key.
`[obj_id_column]`	text	OBJ record identifier. The field name defaults to `obj_id` and can be changed with the `obj_id_column` option.
`[obj_data_column]`	sfmesh	Mesh data. The field name defaults to `obj_data` and can be changed with the `obj_data_column` option.

Component table

Field	Type	Description
`id`	serial	Primary key.
`obj_id`	text	OBJ record identifier. Fixed field name.
`component_id`	text	Sequence number of the component within the original OBJ file.
`name`	text	Component name. Derived from the `g` (group) or `o` (object) directive in the OBJ file. If multiple names exist, the first is used. Defaults to `Mesh_[object sequence number]` when no name is defined.
`tags`	jsonb	Tags associated with the component.
`component`	sfmesh	Component mesh data.

Texture table

Field	Type	Description
`id`	serial	Primary key.
`obj_id`	text	OBJ record identifier. Fixed field name.
`texture_id`	text	Sequence number of the texture within the original OBJ file.
`name`	text	File name of the texture.
`texture`	texture	Texture data.

Examples

Basic import from OSS

SELECT ST_ImportObj('test_obj', 'OSS://<ak>:<ak_secret>@oss-cn-beijing-internal.aliyuncs.com/mybucket/path_to_obj.obj');

---------
t

Disable forced triangulation

By default, non-triangular faces are converted to triangles. To preserve the original face topology:

SELECT ST_ImportObj('test_obj', 'OSS://<ak>:<ak_secret>@oss-cn-beijing-internal.aliyuncs.com/mybucket/path_to_obj.obj', '{"force_triangulate": false}');

Specify a texture search path

When textures are stored in a different OSS directory from the OBJ file, set search_path to point to that directory:

SELECT ST_ImportObj('test_obj', 'OSS://<ak>:<ak_secret>@oss-cn-beijing-internal.aliyuncs.com/mybucket/models/scene.obj', '{"search_path": "OSS://foo/bar"}');

Import with a custom schema and column names

SELECT ST_ImportObj('test_obj', 'OSS://<ak>:<ak_secret>@oss-cn-beijing-internal.aliyuncs.com/mybucket/path_to_obj.obj', '{"schema": "gis", "obj_id_column": "model_id", "obj_data_column": "mesh_data"}');