分步指南

步骤 1：验证安装和版本

确保您使用的是受支持的 Node.js 版本（18、20 或 22），并且已安装该包：

node --version          # Must be v18 or later
npm list @aspose/3d     # Should show the installed version

如果未找到该包，请重新安装：

npm install @aspose/3d

步骤 2：修复模块解析错误

错误：Cannot find module '@aspose/3d/formats/obj'

子路径导入需要 Node.js 12.7+ 的 package exports。在 TypeScript 中，设置正确的模块解析：

// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "moduleResolution": "node16",
    "strict": true
  }
}

对于 ESM 项目，请使用 "module": "ES2022" 和 "moduleResolution": "bundler"。

步骤 3：加载后调试空场景

如果 scene.rootNode.childNodes 在 scene.open() 之后为空：

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

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

console.log(`Child nodes: ${scene.rootNode.childNodes.length}`);

常见原因：

错误的格式选项：对于 OBJ，始终传递 new ObjLoadOptions()。使用通用选项可能会阻止格式检测。
文件路径错误: 如果未找到文件，库会悄悄加载一个空场景：

import * as fs from 'fs';

const filePath = 'model.obj';
if (!fs.existsSync(filePath)) {
    throw new Error(`File not found: ${filePath}`);
}
const scene = new Scene();
scene.open(filePath, new ObjLoadOptions());

OBJ 文件使用非标准换行符：在文本编辑器中打开并确保文件有效。

步骤 4：修复坐标系问题

由于不同格式之间坐标系的差异，模型可能会出现旋转、镜像或缩放不正确的情况。

右手坐标系 vs 左手坐标系，Y-up vs Z-up:

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

const options = new ObjLoadOptions();
options.flipCoordinateSystem = true;  // Swap Y and Z axes

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

比例问题（例如，STL 使用毫米而 glTF 使用米）：

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

const options = new ObjLoadOptions();
options.scale = 0.001;  // Convert millimeters to meters

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

第5步：处理大文件的内存问题

对于大于 100 MB 的文件，请增大 Node.js 堆大小：

node --max-old-space-size=4096 convert.js

或者在 package.json 中设置：

{
  "scripts": {
    "convert": "node --max-old-space-size=4096 dist/convert.js"
  }
}

一次处理一个大文件，而不是并行处理，以避免峰值内存问题。

常见错误参考

错误	可能原因	解决办法
`Cannot find module '@aspose/3d/formats/obj'`	模块解析配置	在 tsconfig 中设置 `moduleResolution: node16`
`scene.rootNode.childNodes` 为空	选项错误或文件未找到	检查文件路径；传递正确的 `*LoadOptions`
几何体出现镜像/翻转	坐标系不匹配	设置 `flipCoordinateSystem = true`
几何体缩放不正确	格式之间的单位差异	在加载选项中设置 `scale`
`ENOMEM` 或进程被终止	大文件内存不足	增加 `--max-old-space-size`
`node.entity` 上的 TypeScript 类型错误	实体类型过宽	使用 `instanceof Mesh` 守卫

常见问题

我该如何报告解析错误？

在 GitHub repository 上打开一个 issue，提供格式名称、最小可复现文件以及准确的错误信息。

为什么有些网格的控制点为零？

某些 OBJ 组仅定义纹理坐标或法线，而没有位置数据。处理前请检查 mesh.controlPoints.length > 0。

库会悄悄地忽略解析错误。我该如何检测它们？

将 scene.open() 包装在 try/catch 块中。如果文件格式错误，库可能会抛出异常或加载部分场景：

try {
    scene.open('model.obj', new ObjLoadOptions());
} catch (err) {
    console.error('Failed to load:', err);
}

如何在 TypeScript 中修复 3D 模型错误