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-foss

The 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

FormatExtensionReadWrite
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.


Getting Started