Format Support

This guide covers each 3D format that Aspose.3D FOSS for Python supports, with loading and saving examples and key options for each. The library translates each format into a common Scene object on load and serialises that object back to the target format on save, so a scene loaded from OBJ can be saved directly to glTF.

Supported Formats

OBJ Format

Wavefront OBJ is the most widely supported interchange format for static meshes. Aspose.3D FOSS loads geometry (vertices, normals, UV coordinates, and polygonal faces) and optionally the companion .mtl material file.

ObjLoadOptions

Loading an OBJ file

Pass ObjLoadOptions to scene.open() to control material loading, coordinate orientation, and vertex scale:

from aspose.threed import Scene
from aspose.threed.formats import ObjLoadOptions

options = ObjLoadOptions()
options.enable_materials = True
options.flip_coordinate_system = False
options.scale = 1.0

scene = Scene()
scene.open("model.obj", options)

print(f"Top-level nodes: {len(scene.root_node.child_nodes)}")

Saving to OBJ

Call scene.save() with a .obj extension to write the scene as a Wavefront OBJ file:

scene.save("output.obj")

OBJ export writes vertex positions and polygon faces. If the scene contains LambertMaterial or PhongMaterial objects, the library writes a companion .mtl file automatically.

STL Format

STL (STereoLithography) stores triangle meshes as an unindexed list of facets. Both binary and ASCII variants are supported for reading; the library defaults to ASCII on save (binary_mode=False). Set binary_mode=True in StlSaveOptions for binary output.

StlSaveOptions

StlSaveOptions has no mandatory fields. Instantiate it to pass to scene.save():

from aspose.threed.formats import StlSaveOptions

opts = StlSaveOptions()
scene.save("output.stl", opts)

Round-trip example

Load an STL file with Scene.from_file() and inspect vertex counts before saving back to STL:

from aspose.threed import Scene

##Load
scene = Scene.from_file("model.stl")

##Inspect
for node in scene.root_node.child_nodes:
    if node.entity:
        print(f"{node.name}: {len(node.entity.control_points)} vertices")

##Save
scene.save("roundtrip.stl")

STL stores only triangle geometry, with no normals beyond the facet normal, no UV coordinates, no materials, and no hierarchy. If your scene contains quads or higher-order polygons, they are triangulated automatically on save.

glTF / GLB Format

glTF 2.0 is the recommended format for modern 3D exchange. It preserves the full scene graph (node hierarchy, named nodes, transforms), materials (LambertMaterial, PhongMaterial → PBR conversion), and animation clips. GLB is the single-file binary container variant.

GltfSaveOptions

Instantiate GltfSaveOptions and pass it to scene.save() to write glTF output; use .glb for the self-contained binary container:

from aspose.threed.formats import GltfSaveOptions

opts = GltfSaveOptions()
scene.save("output.gltf", opts)   # JSON + external .bin
scene.save("output.glb",  opts)   # Self-contained binary

Material support

Aspose.3D FOSS materials are mapped to glTF pbrMetallicRoughness on export:

from aspose.threed import Scene
from aspose.threed.shading import PhongMaterial
from aspose.threed.utilities import Vector3

scene = Scene()
node = scene.root_node.create_child_node("object")

mat = PhongMaterial()
mat.diffuse_color  = Vector3(0.8, 0.2, 0.2)   # red
mat.specular_color = Vector3(1.0, 1.0, 1.0)
mat.shininess = 50.0
node.material = mat

scene.save("colored.gltf")

Verifying glTF output

After saving, open the JSON file and inspect the asset version, node count, and mesh count:

import json

with open("output.gltf") as f:
    data = json.load(f)

print(f"Asset version : {data['asset']['version']}")
print(f"Nodes         : {len(data.get('nodes', []))}")
print(f"Meshes        : {len(data.get('meshes', []))}")

COLLADA Format

COLLADA (.dae) is an XML-based format that supports scene hierarchies, materials, multiple UV channels, and skeletal animation. Aspose.3D FOSS reads and writes the full node tree and material definitions.

from aspose.threed import Scene

##Load a COLLADA file
scene = Scene.from_file("model.dae")

##Inspect top-level nodes
for node in scene.root_node.child_nodes:
    print(f"  {node.name}")

##Save back to COLLADA
scene.save("output.dae")

COLLADA is a good choice when you need to round-trip hierarchies with named nodes and materials without any data loss.

3MF Format

3MF (3D Manufacturing Format) targets additive manufacturing (3D printing) workflows. It stores triangle geometry, colour, and print-specific metadata in a ZIP-based container.

from aspose.threed import Scene
from aspose.threed.formats import ThreeMfSaveOptions

scene = Scene.from_file("part.stl")   # Load from STL
opts  = ThreeMfSaveOptions()
scene.save("part.3mf", opts)          # Write as 3MF

3MF is the recommended export format when targeting slicer software (Cura, PrusaSlicer, Bambu Studio, etc.).

FBX Format

Status: experimental in this release.

Aspose.3D FOSS reads ASCII FBX files at the tokenizer level. The binary FBX tokenizer can parse the file structure, but the full parser for nodes, meshes, and materials has known bugs. FBX read results should be treated as experimental and verified before use.

If your source data is in FBX, convert to glTF or OBJ first using a 3D editor before loading with Aspose.3D FOSS. FBX write is unavailable in this release.

Format Auto-Detection

Scene.from_file() and scene.open() detect the format from the file extension and, where available, the binary file header:

from aspose.threed import Scene

##The library detects each format without being told explicitly
scene_obj  = Scene.from_file("model.obj")
scene_glb  = Scene.from_file("model.glb")
scene_stl  = Scene.from_file("model.stl")
scene_dae  = Scene.from_file("model.dae")
scene_3mf  = Scene.from_file("model.3mf")

If the extension is absent or ambiguous, the library falls back to header inspection (magic bytes). Unsupported or unrecognised files raise an IOError with a descriptive message.

Tips and Best Practices

• Use glTF or GLB for modern pipelines. glTF preserves the full scene graph, materials, and animation data. It is the most complete format for interchange with game engines and web viewers.
• Use OBJ for maximum compatibility. OBJ is supported by virtually every 3D tool. It is limited to static meshes but is extremely portable.
• Use 3MF for printing. 3MF carries colour, orientation hints, and print-specific metadata that the STL format lacks.
• Treat FBX as experimental. Check the release notes for the version in which full FBX parsing is complete.
• Match save extension to format. Do not pass a .gltf extension when you want binary GLB; use .glb explicitly. The extension determines which serialiser is used.
• Check polygon compatibility. STL and 3MF require triangles. Quads and N-gons are triangulated automatically; call mesh.triangulate() before saving to control the triangulation explicitly.

See Also

• Aspose.3D — Enterprise Documentation
• Aspose.3D for Python — Enterprise Documentation