功能与特性

本页涵盖了每个主要功能区域的 Aspose.3D 26.1.0 提供可运行的 C# 示例。.

加载和保存场景

Scene.Open() 加载文件；; Scene.Save() 导出它。格式会根据文件扩展名自动检测：:

using Aspose.ThreeD;

var scene = new Scene();
scene.Open("input.obj");
scene.Save("output.glb");

使用静态工厂 Scene.FromFile() 作为替代方案：:

var scene = Scene.FromFile("input.fbx");
scene.Save("output.stl");

特定格式选项

传递 LoadOptions 或 SaveOptions 子类以实现细粒度控制：:

using Aspose.ThreeD;
using Aspose.ThreeD.Formats;

var scene = new Scene();
scene.Open("model.obj", new ObjLoadOptions { FlipCoordinateSystem = true });
scene.Save("model.fbx");

可用的选项类：:

类	方向	关键属性
`ObjLoadOptions`	导入	`FlipCoordinateSystem`, `EnableMaterials`, `Scale`
`ObjSaveOptions`	导出	`FlipCoordinateSystem`, `EnableMaterials`, `PointCloud`
`FbxLoadOptions`	导入	(默认设置)
`GltfLoadOptions`	导入	(默认设置)
`GltfSaveOptions`	导出	(默认设置)
`StlLoadOptions`	导入	(默认设置)
`StlSaveOptions`	导出	(默认设置)
`ColladaLoadOptions`	导入	`FlipCoordinateSystem`
`ColladaSaveOptions`	导出	`Indented`, `TransformStyle`
`PlyLoadOptions`	导入	(默认设置)

构建场景图

创建节点并附加实体以构建层级结构：:

var scene = new Scene();
var root = scene.RootNode;

var boxNode = root.CreateChildNode("box", new Box(5, 5, 5));
var sphereNode = root.CreateChildNode("sphere", new Sphere(3));

通过以下方式访问子项 node.ChildNodes 并通过…访问附加实体 node.Entity.

网格与原始体

创建一个 Mesh 以编程方式创建，包含控制点和多边形：:

// Mesh.ControlPoints uses Aspose.ThreeD.Utilities.Vector4
// (double-precision, lowercase fields: x, y, z, w)
using Aspose.ThreeD.Utilities;

var mesh = new Mesh("custom");
mesh.ControlPoints.Add(new Vector4(0.0, 0.0, 0.0));   // w defaults to 1.0
mesh.ControlPoints.Add(new Vector4(10.0, 0.0, 0.0));
mesh.ControlPoints.Add(new Vector4(10.0, 10.0, 0.0));
mesh.ControlPoints.Add(new Vector4(0.0, 10.0, 0.0));
mesh.CreatePolygon(0, 1, 2, 3);

内置基元（Box, Sphere, Cylinder) 可以转换为 Mesh:

var box = new Box(10, 10, 10);
Mesh boxMesh = box.ToMesh();

顶点元素

为几何体附加法线、UV 和顶点颜色：:

var normals = new VertexElementNormal(MappingMode.ControlPoint, ReferenceMode.Direct);
mesh.AddElement(normals);

可用的顶点元素类型：: VertexElementNormal, VertexElementUV, VertexElementVertexColor, VertexElementBinormal, VertexElementTangent.

变换

每个 Node 携带一个 Transform 带有 Translation, Rotation,，并且 Scale:

var node = scene.RootNode.CreateChildNode("moved", new Box());
node.Transform.Translation = new FVector3(10, 0, 5);
node.Transform.Scale = new FVector3(2, 2, 2);

通过读取世界空间位置 node.GlobalTransform.Matrix 或 node.EvaluateGlobalTransform().

材质

为节点分配材质以提供着色数据：:

var mat = new PhongMaterial("shiny");
mat.Diffuse = new Vector4(0.8, 0.2, 0.2, 1.0);
mat.Specular = new Vector4(1, 1, 1, 1);
mat.Shininess = 32;

scene.RootNode.CreateChildNode("red_box", new Box(), mat);

材质类型：: LambertMaterial, PhongMaterial, PbrMaterial.

技巧与最佳实践

使用 Scene.FromFile() 用于单行加载，当您不需要自定义时 LoadOptions
将基元转换为 Mesh 使用 ToMesh() 在添加顶点元素之前
使用 GltfSaveOptions 使用一个 .glb 扩展以实现紧凑的二进制输出
检查 node.Entity 用于 null 在转换之前 — 并非每个节点都携带几何体
使用 PolygonModifier.Triangulate() 在导出到仅支持三角形的格式（如 STL）之前，将四边形网格转换

常见问题

问题	原因	修复
`ImportException` 加载时	不受支持或已损坏的文件	确认文件能在 3D 查看器中打开；检查格式是否在支持列表中
OBJ 加载后缺少材质	`.mtl` 未找到文件	放置 `.mtl` 文件放在 `.obj` 或设置 `ObjLoadOptions.EnableMaterials = true`
FBX 导入后比例不匹配	不同的单位系统	使用 `ObjLoadOptions.Scale` 或应用一个 `Transform` 加载后

FAQ

我该如何检测未知文件的格式？?

使用 FileFormat.Detect():

var format = FileFormat.Detect("unknown_file.bin");
Console.WriteLine(format.Extension);

我可以从流而不是文件路径加载吗？?

是。. Scene.Open() 接受一个 Stream:

using var stream = File.OpenRead("model.glb");
scene.Open(stream);

哪些格式同时支持导入和导出？?

OBJ、STL、glTF/GLB、FBX、COLLADA 和 3MF 都支持双向操作。PLY 仅支持导入（PLY 导出器尚未接通）。.

API 参考摘要

类 / 方法	描述
`Scene`	顶层 3D 场景容器
`Scene.Open()`	通过路径或流加载 3D 文件
`Scene.Save()`	将场景导出到文件或流
`Scene.FromFile()`	用于加载并返回的静态工厂 `Scene`
`Node`	场景层次节点，持有实体和变换
`Node.CreateChildNode()`	创建并附加子节点
`Mesh`	具有控制点和面列表的多边形网格
`Mesh.CreatePolygon()`	通过顶点索引定义多边形面
`Box` / `Sphere` / `Cylinder`	内置参数化基元
`Transform`	局部平移、旋转和缩放
`FileFormat`	支持格式的注册表和检测器
`LambertMaterial` / `PhongMaterial` / `PbrMaterial`	用于着色的材质类型