Introduction
Aspose.3D FOSS for Python represents a 3D scene as a graph of Node objects rooted
at Scene.root_node. Each node can hold an Entity — typically a Mesh, but also a
Camera or Light — and child nodes attach underneath it, forming a tree that mirrors
how 3D authoring tools organize a scene.
This post covers the building blocks for working with that graph: walking an existing
hierarchy, generating primitive geometries like boxes and spheres, constructing
arbitrary meshes from raw vertex data, and attaching materials. The library is
published on PyPI as pip install aspose-3d-foss, carries an MIT
license, and has zero external dependencies. Every class below is imported from the
aspose.threed package, for example from aspose.threed import Scene and
from aspose.threed.entities import Node, Mesh, Box.
Key Features
Scene Graph Traversal
A Scene loaded from a file already has its node hierarchy populated. Node.child_nodes
returns the list of a node’s direct children, and Node.entity exposes whatever Entity
(if any) is attached to that node, so a recursive walk can inspect every node’s name and
depth without knowing the file format in advance:
from aspose.threed import Scene
scene = Scene()
scene.open("model.gltf")
def walk(node, depth=0):
print(" " * depth + (node.name or "(unnamed)"))
for child in node.child_nodes:
walk(child, depth + 1)
walk(scene.root_node)
Primitive Geometries
aspose.threed.entities includes ready-made primitive shapes — Box, Sphere,
Cylinder, and Pyramid among them — that expose shape-specific properties
(Box.length/width/height, for instance) and convert to a renderable Mesh via
to_mesh(). Node.create_child_node() can attach the resulting mesh and a material to
a new node in a single call:
from aspose.threed import Scene
from aspose.threed.entities import Box
from aspose.threed.shading import LambertMaterial
from aspose.threed.utilities import Vector3
scene = Scene()
box = Box(length=2.0, width=1.0, height=1.0)
material = LambertMaterial()
material.diffuse_color = Vector3(0.2, 0.6, 0.9)
scene.root_node.create_child_node("Crate", entity=box.to_mesh(), material=material)
scene.save("crate.gltf")
Custom Mesh Construction
Beyond the built-in primitives, Mesh can be built directly from vertex data.
Mesh.control_points holds the vertex positions as Vector4 values, and
Mesh.create_polygon() defines a face by the indices of the control points that form
it. The example below builds a single triangle, assigns a PbrMaterial, exports it to
an in-memory glTF stream, and reads the material back out of the resulting JSON:
import io
import json
from aspose.threed import Scene, FileFormat
from aspose.threed.entities import Mesh
from aspose.threed.utilities import Vector3, Vector4
from aspose.threed.formats.gltf import GltfSaveOptions
from aspose.threed.shading import PbrMaterial
scene = Scene()
mesh = Mesh("TestMesh")
mesh.control_points.add(Vector4(0.0, 0.0, 0.0, 1.0))
mesh.control_points.add(Vector4(1.0, 0.0, 0.0, 1.0))
mesh.control_points.add(Vector4(0.0, 1.0, 0.0, 1.0))
mesh.create_polygon(0, 1, 2)
albedo = Vector3(0.8, 0.2, 0.3)
material = PbrMaterial("RedMaterial", albedo)
material.metallic_factor = 0.5
material.roughness_factor = 0.7
node = scene.root_node.create_child_node("TestNode")
node.entity = mesh
node.material = material
stream = io.BytesIO()
# Pass the detected FileFormat into the constructor explicitly: unlike
# StlFormat, GltfFormat.create_save_options() does not set file_format on the
# options it returns, and a bare stream (no filename) gives scene.save()
# nothing else to detect the format from.
options = GltfSaveOptions(FileFormat.get_format_by_extension(".gltf"))
options.binary_mode = False
scene.save(stream, options)
stream.seek(0)
gltf_data = json.loads(stream.read().decode("utf-8"))
print(gltf_data["materials"][0]["pbrMetallicRoughness"])
Materials: Lambert, Phong, and PBR
A node’s visual appearance comes from a Material assigned through
Node.material or passed to create_child_node(). LambertMaterial and
PhongMaterial cover classic diffuse/specular shading (diffuse_color,
specular_color, shininess), while PbrMaterial models physically based shading
with albedo, metallic_factor, and roughness_factor:
from aspose.threed import Scene
from aspose.threed.entities import Sphere
from aspose.threed.shading import PbrMaterial
from aspose.threed.utilities import Vector3
scene = Scene()
sphere = Sphere()
material = PbrMaterial(albedo=Vector3(0.8, 0.1, 0.1))
material.metallic_factor = 0.9
material.roughness_factor = 0.2
scene.root_node.create_child_node("Ball", entity=sphere.to_mesh(), material=material)
scene.save("ball.stl")
Quick Start
Install the package:
pip install aspose-3d-fossThe example below generates a Cylinder primitive, positions it with a Node
transform, and saves the result as an OBJ file:
from aspose.threed import Scene
from aspose.threed.entities import Cylinder
from aspose.threed.utilities import Vector3
scene = Scene()
cylinder = Cylinder()
node = scene.root_node.create_child_node("Post", entity=cylinder.to_mesh())
node.transform.translation = Vector3(0.0, 1.0, 0.0)
node.transform.scaling = Vector3(0.5, 2.0, 0.5)
scene.save("post.obj")
Supported Formats
| Format | Extension | Read | Write |
|---|---|---|---|
| OBJ | .obj | ✓ | ✓ |
| STL | .stl | ✓ | ✓ |
| glTF / GLB | .gltf, .glb | ✓ | ✓ |
| Microsoft 3MF | .3mf | ✓ | ✓ |
| FBX | .fbx | ✓ | — |
FBX files can be opened and read, but FbxExporter does not implement saving —
use OBJ, STL, glTF, or 3MF when writing output.
Open Source & Licensing
Aspose.3D FOSS for Python is distributed under the MIT license and has no external runtime dependencies. The source is available at github.com/aspose-3d-foss/Aspose.3D-FOSS-for-Python and the package is published on PyPI as aspose-3d-foss. It can be used freely in commercial and open-source projects alike.