Aspose.3D FOSS
TypeScript
开发者指南
Format Support

3D 格式支持

Aspose.3D FOSS for TypeScript 读取和写入七种主要的 3D 文件格式。加载时会自动检测格式：库会检查二进制魔数，因此无需指定源格式。特定格式的选项类从该包的子路径导入。 @aspose/3d 包。.

支持的格式

格式扩展名读取写入格式类备注
Wavefront OBJ.obj是是ObjFormat读取 .mtl 材料; 写入 .mtl 并排 .obj
glTF 2.0.gltf是是GltfFormatJSON 文本 + .bin sidecar
GLB.glb是是GltfFormat二进制 glTF; 设置 binaryMode = true
STL.stl是是StlFormat二进制和 ASCII 模式
3MF.3mf是是ThreeMfFormat3D Manufacturing Format
FBX.fbx否*否*FbxFormatImporter/exporter 已存在，但格式自动检测未接通；无法通过 scene.open()
COLLADA.dae是是ColladaFormat需要 xmldom （自动安装）

OBJ（Wavefront）

OBJ 在以下方面同时支持导入和导出 @aspose/3d.。保存为 OBJ 时，材质库（.mtl）会自动写入到旁边的 .obj 文件。使用 ObjLoadOptions 来控制材质加载和坐标系行为。.

关键选项 ObjLoadOptions:

选项类型默认值效果
enableMaterialsbooleantrue解析 .mtl 被引用的文件 mtllib
flipCoordinateSystembooleanfalse翻转 Y/Z 轴以匹配右手坐标系
scalenumber1.0在加载时对所有顶点应用统一缩放
normalizeNormalbooleantrue将顶点法线归一化为单位长度
import { Scene } from '@aspose/3d';
import { ObjLoadOptions } from '@aspose/3d/formats/obj';

const scene = new Scene();
const opts = new ObjLoadOptions();
opts.enableMaterials = true;
opts.normalizeNormal = true;

scene.open('model.obj', opts);
console.log(`Loaded ${scene.rootNode.childNodes.length} top-level node(s)`);

要将 OBJ 转换为任何可写入的格式，先加载它并调用 scene.save() 目标格式类。.

glTF 与 GLB

glTF 2.0 是用于网页和游戏引擎的推荐交换格式。库使用相同的 GltfFormat 类来处理两者 .gltf (JSON + sidecar) 和 .glb (binary, self-contained) 输出。使用以下方式在它们之间切换 GltfSaveOptions.binaryMode.

加载 glTF 或 GLB：:

import { Scene } from '@aspose/3d';
import { GltfLoadOptions } from '@aspose/3d/formats/gltf';

const scene = new Scene();
scene.open('model.gltf', new GltfLoadOptions());
// or
scene.open('model.glb');  // format detected from magic bytes

导出为 JSON glTF (.gltf + .bin):

import { Scene } from '@aspose/3d';
import { GltfSaveOptions, GltfFormat } from '@aspose/3d/formats/gltf';

const scene = new Scene();
scene.open('input.fbx');

const opts = new GltfSaveOptions();
opts.binaryMode = false;  // produces output.gltf + output.bin
scene.save('output.gltf', GltfFormat.getInstance(), opts);

导出为二进制 GLB (.glb):

import { Scene } from '@aspose/3d';
import { GltfSaveOptions, GltfFormat } from '@aspose/3d/formats/gltf';

const scene = new Scene();
scene.open('input.obj');

const opts = new GltfSaveOptions();
opts.binaryMode = true;  // single self-contained file
scene.save('output.glb', GltfFormat.getInstance(), opts);

使用 binaryMode = true 用于生产资产交付。单个 .glb 在浏览器和引擎中加载速度比分离的文本 + 二进制对更快。.

STL

STL 是一种在 CAD 和 3D 打印中使用的三角网格格式。二进制和 ASCII STL 都支持输入和输出。. StlSaveOptions.binaryMode 控制输出是二进制（紧凑）还是 ASCII（人类可读）。.

import { Scene } from '@aspose/3d';
import { StlLoadOptions, StlSaveOptions } from '@aspose/3d/formats/stl';

const scene = new Scene();
scene.open('model.stl', new StlLoadOptions());

// Export as binary STL (default, compact)
const binaryOpts = new StlSaveOptions();
binaryOpts.binaryMode = true;
scene.save('output_binary.stl', binaryOpts);

// Export as ASCII STL (human-readable)
const asciiOpts = new StlSaveOptions();
asciiOpts.binaryMode = false;
scene.save('output_ascii.stl', asciiOpts);

STL 仅存储三角形几何体和顶点法线。材质和 UV 数据在 STL 中不会被保留。.

3MF (3D Manufacturing Format)

3MF is an XML-based format designed for additive manufacturing. It supports color and material metadata alongside geometry. Use it when exchanging files with 3D printing slicers or manufacturing workflows.

import { Scene } from '@aspose/3d';
import { ThreeMfSaveOptions } from '@aspose/3d/formats/3mf';

const scene = new Scene();
scene.open('model.3mf');

// Re-export as 3MF
scene.save('output.3mf', new ThreeMfSaveOptions());

3MF files are ZIP archives internally. The library handles archive creation and extraction automatically.

FBX

警告: FBX 导入器和导出器类 (FbxImporter, FbxExporter) 在库中存在，但 FBX 格式自动检测是 未接线 进入 scene.open() 或 scene.save().。调用 scene.open('file.fbx') 将不会调用 FBX 导入器 — 文件将回退到 STL 备用。调用 scene.save('output.fbx', opts) 将不会调用 FBX 导出器。上面的格式支持表将 FBX 标记为 No* 出于此原因。使用 GLB 或 COLLADA 进行完整的导入和导出 scene.open() / scene.save().

COLLADA (DAE)

COLLADA 是一种基于 XML 的交换格式，受到广泛的 DCC 工具（Blender、Maya、Cinema 4D）的支持。该库使用 the xmldom 依赖项进行 XML 解析；它会随 automatically with 自动安装 npm install @aspose/3d.

import { Scene } from '@aspose/3d';
import { ColladaSaveOptions } from '@aspose/3d/formats/collada';

const scene = new Scene();
scene.open('model.dae');

// Re-export as COLLADA
const saveOpts = new ColladaSaveOptions();
scene.save('output.dae', saveOpts);

COLLADA 文件可能包含单位缩放元数据 (<unit> 元素)。库在加载时会自动进行单位转换。.

格式自动检测

当从文件路径加载时，库会先尝试通过二进制魔数进行格式检测，若失败再回退到文件扩展名。这意味着您可以加载名为 GLB 文件的 .bin 或名为 STL 文件的 .model 而无需显式指定格式。.

当从 a Buffer 使用 with scene.openFromBuffer(),，魔数检测是主要机制：:

import { Scene } from '@aspose/3d';
import * as fs from 'fs';

const buffer = fs.readFileSync('model.glb');
const scene = new Scene();
scene.openFromBuffer(buffer);  // format detected from magic bytes: 'glTF'

console.log(`Root has ${scene.rootNode.childNodes.length} child node(s)`);

具有可靠魔数的格式：GLB (glTF), STL 二进制（80 字节头部 + 三角形计数），3MF (ZIP 魔数 PK). OBJ 和 COLLADA 是基于文本的，可通过文件扩展名或您传入的选项类进行检测。.

提示

  • OBJ 支持导入和导出两种操作:：保存为 OBJ 时， .mtl 材质文件会自动与 .obj 文件一起写入。.
  • 使用 GLB 进行网络交付:：这种自包含的二进制格式可避免与 .bin 附属文件的 CORS 问题，并在 WebGL 渲染器中加载更快。.
  • 传递特定格式的选项:：通用 scene.open(path) 适用于大多数格式，但传入加载器选项类可启用特定格式的行为，例如 OBJ 材质加载或 STL 坐标归一化。.
  • xmldom 对 COLLADA 是必需的: 它会自动安装。不要将其添加到 peerDependencies 或尝试删除它；COLLADA 读取器会直接调用它。.

常见问题

症状可能原因解决方案
加载后 OBJ 材质为空enableMaterials 未设置通过 ObjLoadOptions 使用 enableMaterials = true
GLB 生成一个 .bin 伴随文件binaryMode 默认使用 false设置 opts.binaryMode = true 在 GltfSaveOptions
scene.open() 抛出 “unsupported format”文件扩展名未被识别传递匹配 *LoadOptions 类或使用 openFromBuffer()
COLLADA 加载因 XML 错误而失败xmldom 缺失或不匹配运行 npm install @aspose/3d 再次；; xmldom 是直接依赖
STL 法线在 ASCII 导出时丢失ASCII STL 丢失每面法线使用 binaryMode = true 用于保留法线的输出

另见

 中文