How to Fix 3D Model Errors in TypeScript

This guide covers the most common errors when using @aspose/3d for TypeScript and Node.js, with practical fixes for each.

Step-by-Step Guide

Step 1: Verify Installation and Versions

Ensure you are on a supported Node.js version (16, 18, 20, or 22) and the package is installed:

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

If the package is not found, reinstall:

npm install @aspose/3d

Step 2: Fix Module Resolution Errors

Error: Cannot find module '@aspose/3d/formats/obj'

Sub-path imports require Node.js 12.7+ package exports. In TypeScript, set the correct module resolution:

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

For ESM projects, use "module": "ES2022" and "moduleResolution": "bundler".

Step 3: Debug an Empty Scene After Loading

If scene.rootNode.childNodes is empty after 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}`);

Common causes:

Wrong format options: for OBJ, always pass new ObjLoadOptions(). Using generic options can prevent format detection.
File path is wrong: the library silently loads an empty scene if the file is not found:

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 file uses non-standard line endings: open in a text editor and ensure the file is valid.

Step 4: Fix Coordinate System Issues

Models may appear rotated, mirrored, or scaled incorrectly due to coordinate system differences between formats.

Right-hand vs left-hand, 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);

Scale issues (e.g., STL in millimeters vs glTF in meters):

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

Step 5: Handle Memory Issues with Large Files

For files larger than 100 MB, increase the Node.js heap size:

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

Or set it in package.json:

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

Process large files one at a time rather than in parallel to avoid peak memory issues.

Common Error Reference

Error	Likely Cause	Fix
`Cannot find module '@aspose/3d/formats/obj'`	Module resolution config	Set `moduleResolution: node16` in tsconfig
`scene.rootNode.childNodes` is empty	Wrong options or file not found	Check file path; pass correct `*LoadOptions`
Geometry appears mirrored/flipped	Coordinate system mismatch	Set `flipCoordinateSystem = true`
Geometry appears scaled incorrectly	Unit difference between formats	Set `scale` in load options
`ENOMEM` or process killed	Insufficient memory for large file	Increase `--max-old-space-size`
TypeScript type error on `node.entity`	Broad entity type	Use `instanceof Mesh` guard

Frequently Asked Questions

How do I report a parsing bug?

Open an issue on the GitHub repository with the format name, a minimal reproducible file, and the exact error message.

Why do some meshes have zero control points?

Some OBJ groups define only texture coordinates or normals without position data. Check mesh.controlPoints.length > 0 before processing.

The library silently ignores parse errors. How do I detect them?

Wrap scene.open() in a try/catch block. If the file is malformed, the library may throw an exception or load a partial scene:

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