Aspose.3D FOSS
TypeScript
开发者指南
场景渲染与导出

场景渲染与导出

@aspose/3d 是一个处理和转换库，它不执行 GPU 渲染或生成图像文件。在该库的上下文中，“渲染”指的是 将场景导出为下游渲染器、游戏引擎或查看器可以使用的格式.

本页涵盖所有导出路径：基于文件的保存、内存缓冲区输出、特定格式选项，以及如何为常见下游目标（Three.js、Babylon.js、模型查看器和游戏引擎）准备场景。.

基础导出

调用 scene.save() 使用文件路径。库会根据文件扩展名推断输出格式：:

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

const scene = new Scene();
scene.open('input.obj');  // use a supported format (OBJ, glTF, GLB, STL, 3MF, COLLADA)

scene.save('output.glb');    // GLB (binary glTF)
scene.save('output.stl');    // STL
scene.save('output.dae');    // COLLADA
scene.save('output.3mf');    // 3MF

导出为 GLB（推荐用于网页和游戏）

GLB（二进制 glTF 2.0）是一个单一的自包含文件，嵌入了所有网格数据、材质和纹理。它是网页查看器（Three.js、Babylon.js、model-viewer）和游戏引擎（Godot、通过导入器的 Unity）的推荐输出格式：:

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

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

const opts = new GltfSaveOptions();
opts.binaryMode = true;    // produce .glb instead of .gltf + .bin

scene.save('output.glb', opts);
console.log('GLB export complete');

设置 binaryMode = true 以生成一个自包含的 GLB 文件。当 false,，输出为一个 .gltf JSON 文件，带有单独的 .bin 缓冲区侧文件。.

导出为 glTF（用于检查的 JSON 格式）

JSON 变体（.gltf + .bin）在开发期间很有用，因为 JSON 是人类可读的：:

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

const scene = new Scene();
scene.open('input.dae');  // COLLADA is fully supported; FBX is not wired into scene.open()

const opts = new GltfSaveOptions();
opts.binaryMode = false;  // JSON + .bin sidecar

scene.save('output.gltf', opts);

导出为 STL（3D 打印工作流）

STL 仅包含几何信息（无材质、无动画）。它是 3D 打印切片软件的标准交换格式：:

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

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

const opts = new StlSaveOptions();
opts.binaryMode = true;   // binary STL is more compact than ASCII

scene.save('output.stl', opts);

设置 binaryMode = false 以生成 ASCII STL，它是文本可读的，但体积更大。.

导出为 FBX（DCC 工具工作流）

注意: FBX 导入器和导出器类存在于库中，但 FBX 格式的自动检测并未接入 scene.open() 或 scene.save().。调用 scene.save('output.fbx', opts) 不会调用 FBX 导出器 — the .fbx 扩展名未被保存调度器识别，调用将回退到 OBJ 输出。请直接使用 FbxExporter 类直接使用，如果您需要 FBX I/O。格式支持表将 FBX 标记为 No* 出于此原因。.

如果您需要导出为 Blender、Maya 或 Unreal Engine 所接受的格式，请改用 GLB 或 COLLADA —— 两者都已完整集成到 scene.save():

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

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

// GLB is fully supported and widely accepted by DCC tools
const opts = new GltfSaveOptions();
opts.binaryMode = true;
scene.save('output.glb', opts);

使用内存导出 saveToBuffer()

对于无服务器函数、HTTP 响应和流式管道，直接导出为 Buffer 而无需写入磁盘：:

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

function convertToGlbBuffer(inputPath: string): Buffer {
    const scene = new Scene();
    scene.open(inputPath);

    const opts = new GltfSaveOptions();
    opts.binaryMode = true;

    return scene.saveToBuffer('glb', opts);
}

// Express.js / HTTP response example
// const glbBuffer = convertToGlbBuffer('model.obj');
// res.setHeader('Content-Type', 'model/gltf-binary');
// res.send(glbBuffer);

saveToBuffer() 将格式字符串作为第一个参数（例如. 'glb', 'stl', 'obj'）以及相同的选项对象 save().

组合 openFromBuffer() 和 saveToBuffer()

一个完全在内存中的转换管道，在任何阶段都不进行磁盘 I/O：:

import { Scene } from '@aspose/3d';
import { ObjLoadOptions } from '@aspose/3d/formats/obj';
import { GltfSaveOptions } from '@aspose/3d/formats/gltf';

function objBufferToGlbBuffer(objData: Buffer): Buffer {
    const scene = new Scene();

    const loadOpts = new ObjLoadOptions();
    loadOpts.enableMaterials = true;
    scene.openFromBuffer(objData, loadOpts);

    const saveOpts = new GltfSaveOptions();
    saveOpts.binaryMode = true;

    return scene.saveToBuffer('glb', saveOpts);
}

为特定渲染器准备场景

Three.js / Babylon.js（Web）

这些渲染器原生加载 GLB 文件。使用 binaryMode = true.。如果纹理是从源 OBJ 引用的，请确保 .mtl 以及图像文件在加载时位于同一目录。.

model-viewer（Web 组件）

接受 .glb 直接。导出设置与 Three.js 相同。.

Godot 引擎

通过 Godot 的导入器导入 GLB（Project → Import）。使用 binaryMode = true. Godot 原生支持来自 glTF 2.0 的 PBR 材质。.

Blender

为了获得最佳导入保真度，请使用 glTF (output.gltf + output.bin)output.glb。Blender 的 glTF 2.0 导入器支持 PBR 材质和动画。注意：FBX 输出 via scene.save() 不受支持 — FBX 格式的自动检测未接入保存调度器。.

3D Printing (Slicers: Cura, PrusaSlicer, Bambu Studio)

导出为 STL 或 3MF。需要保留颜色或材料元数据时使用 3MF。追求最大兼容性时使用 STL。.

导出格式对比

格式扩展名材质动画单文件最佳用途
GLB.glbPBR (glTF 2.0)是是网页、游戏、通用交付
glTF.gltfPBR (glTF 2.0)是否 (+ .bin)开发，检查
STL.stl否否是3D printing, geometry-only
FBX.fbxPhong/PBR否*否*导入器/导出器已存在，但未接入自动检测
COLLADA.dae是是是跨 DCC 交换
3MF.3mf颜色/材质否是现代 3D 打印

常见导出问题

症状原因修复
输出的 GLB 在查看器中以 JSON 打开binaryMode 保持为 false设置 opts.binaryMode = true
输出的 GLB 中缺少纹理binaryMode 未设置设置 opts.binaryMode = true 用于自包含的 GLB
STL 文件在切片软件中没有颜色STL 格式不支持颜色使用 3MF 来存储颜色数据
saveToBuffer 返回空缓冲区格式字符串参数缺失或错误传入格式字符串，例如. 'glb', 'stl',，或 'obj'
FBX 在 Blender 中打开时没有动画源文件（OBJ/STL）没有动画仅当源文件中存在动画时，动画才会保留
输出文件非常大源 OBJ 包含许多重复顶点GLB 二进制输出已去重；请检查源资产质量

另见

 中文