How to Work with the 3D Core API in Python

Every class in Aspose.3D for Python — Scene, Node, every Entity subclass, every Material — shares the same two foundations: a Scene/Node graph rooted at the scene’s root node, and a generic property system (find_property() / get_property() / set_property() / remove_property()) inherited from the common A3DObject base. Understanding these two pieces makes every other how-to in this knowledge base easier to follow.

Step-by-Step Guide

Step 1: Install the Package

pip install aspose-3d-foss

python -c "import aspose.threed; print(aspose.threed.__name__)"

Step 2: Import Required Classes

from aspose.threed import Scene
from aspose.threed.entities import Box
from aspose.threed.utilities import Vector3, Vector4

Step 3: Read and Set Scene Metadata

A Scene carries document-level metadata on its asset-info object: title, author, application name, and unit scale, among others.

from aspose.threed import Scene

scene = Scene()
scene.asset_info.title = "Sample Scene"
scene.asset_info.author = "Generated by Aspose.3D"
scene.asset_info.application_name = "my-pipeline"

print(scene.asset_info.title, "by", scene.asset_info.author)

Step 4: Walk the Node Graph

Every scene has exactly one root node. Build or inspect the hierarchy through create_child_node(), each node’s child-node list, and its parent-node reference:

from aspose.threed import Scene
from aspose.threed.entities import Box

scene = Scene()
group = scene.root_node.create_child_node("Group")
box_node = group.create_child_node("Crate", entity=Box(1.0, 1.0, 1.0).to_mesh())

print(box_node.parent_node.name)          # "Group"
print(group.parent_node is scene.root_node)  # True
for child in scene.root_node.child_nodes:
    print(child.name)

Step 5: Use the Generic Property System

find_property(), get_property(), set_property(), and remove_property() are available on Node, every Entity, every Material, and Scene itself — they let you attach arbitrary named data to any object in the graph, beyond its declared properties:

from aspose.threed import Scene

scene = Scene()
node = scene.root_node.create_child_node("Annotated")
node.set_property("part_number", "ACME-42")
node.set_property("qa_passed", True)

existing = node.find_property("part_number")
if existing is not None:
    print(node.get_property(existing))

node.remove_property(existing)

Step 6: Compute a Bounding Box

Concrete entities — Mesh, Box, Sphere, and the other shape classes — expose get_bounding_box() once they have real geometry:

from aspose.threed.entities import Box

box = Box(2.0, 3.0, 4.0)
mesh = box.to_mesh()
bbox = mesh.get_bounding_box()
print(bbox.minimum, bbox.maximum)

Step 7: Work with the Vector and Matrix Types

Vector3, Vector4, Matrix4, and Quaternion are the math primitives used throughout the API — for colours (Vector3), homogeneous control points (Vector4), and transforms (Matrix4/Quaternion via a node’s transform):

from aspose.threed.utilities import Vector3

a = Vector3(1.0, 0.0, 0.0)
b = Vector3(0.0, 1.0, 0.0)
print(a.dot(b))        # 0.0 -- perpendicular
print(a.cross(b))      # Vector3(0, 0, 1)
print(a.length)

Common Issues and Fixes

get_property() raises an error for a property that was never set. Always call find_property() first and check that the result is not empty before passing it to get_property() — find_property() returns the lookup result (or nothing) instead of raising.

Setting a property with set_property() doesn’t seem to persist. Confirm you are calling set_property() on the actual object instance you intend to query later (for example the Node, not a copy of an entity extracted earlier) — the property system stores data per-instance in that object’s own PropertyCollection.

The root node looks empty right after creating a Scene(). This is expected — a freshly constructed scene has a root node with no children until you call create_child_node() or load a file with Scene.open()/Scene.from_file().

Calling get_bounding_box() on a bare, un-built entity returns an unexpected result. Build real geometry first — call to_mesh() on a primitive, or add control points and polygons to a Mesh — before requesting its bounding box.

Frequently Asked Questions

What is the relationship between `Node` and `Entity`?

A Node is a position in the scene graph (it has a transform and child nodes); an Entity (Mesh, Box, Sphere, a Light, a Camera, …) is the geometry or object attached to a node’s entity slot. The same entity instance can in principle be referenced by more than one node, which is why Entity tracks its owning nodes as a list.

Do I need to use the property system, or can I just use regular attributes?

For the properties already declared on a class — colour, translation, or control-point lists, for example — use the regular attribute directly. The find_property() / get_property() / set_property() system is for attaching your own ad-hoc, named data to an object — metadata that has no dedicated attribute.

Is there a base class every object shares?

Yes — A3DObject is the common ancestor providing a name, a property collection, and the four property-system methods. Scene, Node, and every Entity/Material ultimately derive from it (through SceneObject).

Where do `Vector3` and `Vector4` differ?

Vector3 represents a 3-component direction, colour, or position and has vector-math helpers such as dot(), cross(), and normalize(). Vector4 represents a homogeneous 4-component coordinate — it is what a mesh’s control-points list stores, with the fourth component conventionally set to one for a position.