How to Convert 3D Models in TypeScript

Aspose.3D FOSS for TypeScript converts between 3D formats by loading into a neutral Scene representation and saving to the target format. This guide shows the most common conversions.

Step-by-Step Guide

Step 1: Install @aspose/3d

Install the package from the npm registry using the command below:

npm install @aspose/3d

Step 2: Load the Source File

Create a Scene and call scene.open(). Use the format-specific *LoadOptions class for best results.

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

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

Step 3: Save to the Target Format

Call scene.save() with the output path. The output format is detected from the file extension.

// OBJ → glTF binary (GLB)
scene.save('output.glb');

// OBJ → STL
scene.save('output.stl');

// OBJ → COLLADA
scene.save('output.dae');

Note: FBX export requires direct invocation of the FBX exporter class — the .fbx extension has no auto-detection wiring in scene.save(). For reliable format conversion, use OBJ, glTF, STL, 3MF, or COLLADA instead.

Step 4: Common Conversion Examples

OBJ to glTF / GLB

Load an OBJ file with ObjLoadOptions and save to GLB using scene.save():

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

const scene = new Scene();
scene.open('model.obj', new ObjLoadOptions());
scene.save('model.glb');
console.log('Converted OBJ → GLB');

FBX — Direct Class Invocation Required

FBX uses a separate code path. FBX importer/exporter classes exist in the library but require direct invocation rather than the high-level open()/save() API. Passing an .fbx file to scene.open() falls through to the STL parser and produces garbage output. Use COLLADA, OBJ, or glTF as a reliable alternative.

glTF to STL

Open a GLB file with scene.open() and save to STL using scene.save():

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

const scene = new Scene();
scene.open('model.glb');
scene.save('model.stl');
console.log('Converted GLB → STL');

COLLADA to 3MF

Open a COLLADA .dae file with scene.open() and save to 3MF format:

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

const scene = new Scene();
scene.open('model.dae');
scene.save('model.3mf');
console.log('Converted COLLADA → 3MF');

Step 5: Batch Convert Multiple Files

Iterate over all OBJ files in an input directory and call scene.save() for each output path:

import * as fs from 'fs';
import * as path from 'path';
import { Scene } from '@aspose/3d';
import { ObjLoadOptions } from '@aspose/3d/formats/obj';

const inputDir = './input';
const outputDir = './output';

fs.mkdirSync(outputDir, { recursive: true });

const objFiles = fs.readdirSync(inputDir).filter(f => f.endsWith('.obj'));

for (const file of objFiles) {
    const inputPath = path.join(inputDir, file);
    const outputFile = file.replace('.obj', '.glb');
    const outputPath = path.join(outputDir, outputFile);

    const scene = new Scene();
    scene.open(inputPath, new ObjLoadOptions());
    scene.save(outputPath);

    console.log(`Converted ${file} → ${outputFile}`);
}

Supported Conversion Matrix

From \ To	glTF/GLB	OBJ	STL	FBX	3MF	COLLADA
OBJ	✓	✓	✓	✗	✓	✓
glTF/GLB	✓	✓	✓	✗	✓	✓
FBX	✗	✗	✗	✗	✗	✗
STL	✓	✓	✓	✗	✓	✓
3MF	✓	✓	✓	✗	✓	✓
COLLADA	✓	✓	✓	✗	✓	✓

FBX requires direct class invocation and has no auto-detection wiring in open()/save(). All FBX cells above are ✗.

Common Issues and Fixes

Materials are lost after conversion

OBJ materials (usemtl, .mtl file) are loaded when ObjLoadOptions.enableMaterials = true. When saving to glTF, PBR material properties are mapped automatically. Complex materials (procedural, multi-layer) may convert with reduced fidelity.

Mesh appears scaled incorrectly

Different formats use different default units (millimeters for STL, meters for glTF). Use ObjLoadOptions.scale when loading or StlSaveOptions.scale when saving to normalize units.

Coordinate system mismatch (model flipped or rotated)

Some formats use right-hand Y-up, others Z-up. Use ObjLoadOptions.flipCoordinateSystem = true or apply a rotation to the root node after loading.

Frequently Asked Questions

Does conversion preserve animations?

Animation data is preserved when converting between formats that support it (e.g., COLLADA → glTF). STL and OBJ carry no animation data. FBX uses a separate direct-invocation code path, so animation round-trips via the high-level scene.open()/scene.save() API are unavailable.

Is texture data preserved?

Textures referenced by OBJ materials or embedded in glTF are carried through to the scene graph. When saving to GLB (binaryMode = true), the binary buffer is embedded in a single file. For OBJ output, textures are saved as separate files alongside the .obj.

Can I convert many files in parallel?

scene.open() and scene.save() are synchronous. Use Node.js worker_threads for parallel processing.