Aspose.3D FOSS
Python
开发者指南
格式支持

格式支持

Aspose.3D FOSS for Python 可以使用单一的内存场景表示读取和写入七种 3D 格式。该库在加载时将每种格式转换为通用 Scene 对象在加载时，并在保存时将该对象序列化回目标格式。这意味着从 OBJ 加载的场景可以直接保存为 glTF，而无需任何中间转换步骤。.

支持的格式

格式扩展名读取写入选项类备注
Wavefront OBJ.obj是是ObjLoadOptions.mtl 支持材质加载
STL（二进制）.stl是是StlSaveOptions二进制和ASCII读取；保存默认使用二进制
STL (ASCII).stl是是StlSaveOptions往返验证已完成
glTF 2.0.gltf是是GltfSaveOptions完整的场景图、材质和动画均已保留
GLB（二进制 glTF）.glb是是GltfSaveOptions单文件二进制容器
COLLADA.dae是是ColladaLoadOptions / ColladaSaveOptions场景层级和材质
3MF.3mf是是ThreeMfSaveOptions增材制造格式
FBX.fbx部分否N/A分词器正在工作；完整解析器正在进行中（未准备好用于生产)

OBJ 格式

Wavefront OBJ 是最广泛支持的静态网格交换格式。Aspose.3D FOSS 加载几何体（顶点、法线、UV 坐标和多边形面），并可选加载伴随的 .mtl 材质文件。.

ObjLoadOptions

属性类型默认描述
enable_materialsboolTrue解析 .mtl OBJ 头部引用的文件
flip_coordinate_systemboolFalse从 Y-up 右手坐标系转换为 Z-up 右手坐标系
normalize_normalboolTrue将所有导入的表面法线归一化为单位长度
scalefloat1.0对所有顶点位置应用统一的缩放因子

加载 OBJ 文件 

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)}")

保存为 OBJ 

scene.save("output.obj")

OBJ 导出会写入顶点位置和多边形面。如果场景包含 LambertMaterial 或 PhongMaterial 对象时，库会写入一个伴随文件 .mtl 文件会自动生成。.

STL 格式

STL（立体光刻）将三角网格存储为未索引的面列表。读取时支持二进制和 ASCII 两种格式；保存时库默认使用二进制。.

StlSaveOptions

StlSaveOptions 没有强制字段。实例化它以传递给 scene.save():

from aspose.threed.formats import StlSaveOptions

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

往返示例 

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 仅存储三角形几何，仅保留面法线，不包含 UV 坐标、材质或层级结构。如果场景中包含四边形或更高阶多边形，保存时会自动进行三角化。.

glTF / GLB 格式

glTF 2.0 是现代 3D 交换的推荐格式。它保留完整的场景图（节点层次结构、命名节点、变换），材质（LambertMaterial, PhongMaterial → PBR 转换），以及动画剪辑。GLB 是单文件二进制容器变体。.

GltfSaveOptions 

from aspose.threed.formats import GltfSaveOptions

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

材质支持

Aspose.3D FOSS 材质映射到 glTF pbrMetallicRoughness 导出时：:

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")

验证 glTF 输出 

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 格式

COLLADA (.dae) 是一种基于 XML 的格式，支持场景层次结构、材质、多 UV 通道和骨骼动画。Aspose.3D FOSS 能读取和写入完整的节点树和材质定义。.

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 是一个不错的选择。.

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 格式

状态：进行中（尚未准备好用于生产）。.

FBX (.fbx) 在 Aspose.3D FOSS 中的支持目前处于 tokenizer 阶段。二进制 FBX tokenizer 能解析文件结构，但完整的节点、网格和材质解析器存在已知错误且尚未完成。FBX 读取结果应视为实验性。.

在此版本中，请勿在生产流水线中使用 FBX。. 如果您的源数据是 FBX，请先使用 Blender 或 FBX Review 将其转换为 glTF 或 OBJ，然后再使用 Aspose.3D FOSS 加载。.

不支持 FBX 写入。.

格式自动检测

Scene.from_file() 和 scene.open() 使用文件扩展名以及（如果可用）文件头中的魔术字节自动检测格式：:

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")

如果没有扩展名或扩展名不明确，库会回退到检查头部（魔术字节）。不受支持或无法识别的文件会引发一个 IOError 并附带描述性信息。.

技巧与最佳实践

  • 使用 glTF 或 GLB 进行现代流水线。. glTF 保留完整的场景图、材质和动画数据。它是与游戏引擎和网页查看器进行交互的最完整的格式。.
  • 为获得最大兼容性，请使用 OBJ。. 几乎所有 3D 工具都支持 OBJ。它仅限于静态网格，但极其便携。.
  • 打印时请使用 3MF。. 3MF carries colour, orientation hints, and print settings that STL cannot express.
  • 在 FBX 达到生产就绪之前请避免使用。. 请查阅发行说明，了解完整 FBX 解析已完成的版本。.
  • 保存时的扩展名应与格式匹配。. 不要传递 a .gltf 当你想要二进制 GLB 时使用扩展名；使用 .glb 显式地。扩展名决定使用哪个序列化器。.
  • 检查多边形兼容性。. STL 和 3MF 需要三角形。四边形和 N-gon 在保存时会自动进行三角化，但顶点数会增加。如果需要控制三角化，请调用 mesh.triangulate() 保存前。.
 中文