Object model

Choose APIs based on whether the data must be saved and undone.

Project objects

A project contains versioned nodes. Nodes form a hierarchy and can have transforms, visibility, and representations. A representation gives a node its visible geometry.

The current representation types include block models, point clouds, meshes, and polylines. Large datasets use model handles rather than storing every element directly on the node.

Use std.object for project data. Operations create and update these objects. Undo can remove a newly created node or restore a previous value.

Temporary scene content

Use std.scene for transient shapes and interactions. Cubes, spheres, arrows, and capsules can serve as annotations or manipulation controls.

These shapes have integer IDs. They are not versioned project nodes. They are not saved or restored by project undo.

Use project objects for user-authored content that must survive a restart.

Attach a mesh to a node

This native Python example loads a glTF file on the engine’s machine and adds a versioned node:

import spatialengine
from spatialengine.types.std.object.representation import RepresentationObject

with spatialengine.connect() as client:
    mesh = client.std.object.representation.load_mesh_from_gltf(path="model.glb")
    representation = RepresentationObject.Mesh(mesh)
    with spatialengine.Transaction(client) as txn:
        node = txn.submit(client.std.object.unsafe.create_id_node, name="Model")
        txn.submit(
            client.std.object.upsert_representation,
            node=node,
            new_representation=representation,
        )
        txn.commit()
    client.std.project.wait_for_scene_sync()

The unsafe namespace exposes low-level object operations. Its name refers to object-model invariants; this is a normal SDK call.

Loaders differ by target. A native path is not a browser file upload.

Synchronization

An operation’s completion and the rendered scene’s update are separate. Use std.project.wait_for_scene_sync before a scene read that depends on a project operation.

See the Studio Representation Zoo and CAD API samples for complete applications.

Architecture Statements