3D-formaatondersteuning

Aspose.3D FOSS voor TypeScript leest en schrijft zeven belangrijke 3D-bestandsformaten. Formaatdetectie is automatisch bij het laden: de bibliotheek inspecteert binaire magic numbers, zodat je het bronformaat niet hoeft op te geven. Formaat‑specifieke optieklassen worden geïmporteerd vanuit sub‑paden van de @aspose/3d package.

Ondersteunde formaten

OBJ (Wavefront)

OBJ ondersteunt zowel import als export in @aspose/3d. Bij het opslaan als OBJ, de material library (.mtl) wordt automatisch naast de .obj bestand. Gebruik ObjLoadOptions om het laden van materiaal en het gedrag van het coördinatensysteem te regelen.

Belangrijke opties voor ObjLoadOptions:

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

Om een OBJ naar een schrijfbaar formaat te converteren, laad het en roep aan scene.save() met de doelformaatklasse.

glTF en GLB

glTF 2.0 is het aanbevolen uitwisselingsformaat voor web- en game‑enginegebruik. De bibliotheek gebruikt dezelfde GltfFormat klasse voor zowel .gltf (JSON + sidecar) en .glb (binaire, zelfstandige) output. Schakel tussen hen met GltfSaveOptions.binaryMode.

Laad glTF of 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

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

Exporteren als binaire 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);

Gebruik binaryMode = true voor productie‑assetlevering. Een enkele .glb laadt sneller in browsers en engines dan het gesplitste tekst + binaire paar.

STL

STL is een getrianguleerd mesh-formaat dat wordt gebruikt in CAD en 3D-printen. Zowel binaire als ASCII STL worden ondersteund voor invoer en uitvoer. StlSaveOptions.binaryMode bepaalt of de uitvoer binair (compact) of ASCII (menselijk leesbaar) is.

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 slaat alleen getrianguleerde geometrie en vertex‑normals op. Materiaal‑ en UV‑gegevens worden niet bewaard in 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

Waarschuwing: FBX-import- en exportklassen (FbxImporter, FbxExporter) bestaan in de bibliotheek, maar automatische detectie van het FBX-formaat is niet gekoppeld naar scene.open() of scene.save(). Het aanroepen van scene.open('file.fbx') zal de FBX-importeur niet activeren — het bestand zal doorgaan naar de STL-terugval. scene.save('output.fbx', opts) zal de FBX-exporteur niet activeren. De formatondersteuningstabel hierboven markeert FBX als No* om deze reden. Gebruik GLB of COLLADA voor volledig functionele import en export via scene.open() / scene.save().

COLLADA (DAE)

COLLADA is een XML-gebaseerd uitwisselingsformaat dat wordt ondersteund door een breed scala aan DCC-tools (Blender, Maya, Cinema 4D). De bibliotheek gebruikt de xmldom afhankelijkheid voor XML-parsing; deze wordt automatisch geïnstalleerd met 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-bestanden kunnen eenheids-schaalmetadata bevatten (<unit> element). De bibliotheek past eenheidsconversie automatisch toe bij het laden.

Automatische formaterkenning

Bij het laden vanaf een bestandspad probeert de bibliotheek de indetectie van het formaat op basis van binaire magic numbers, voordat hij terugvalt op de bestandsextensie. Dit betekent dat je een GLB‑bestand kunt laden met de naam .bin of een STL‑bestand met de naam .model zonder het formaat expliciet op te geven.

Bij het laden vanaf een Buffer met scene.openFromBuffer(), magic-number detectie is het primaire mechanisme:

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

Formaten met betrouwbare magic numbers: GLB (glTF), STL binair (80-byte header + driehoektelling), 3MF (ZIP magic PK). OBJ en COLLADA zijn tekstgebaseerd en worden gedetecteerd op basis van bestandsextensie of via de options class die je doorgeeft.

Tips

• OBJ ondersteunt zowel import als export: bij het opslaan als OBJ, de .mtl material file wordt automatisch geschreven naast het .obj bestand.
• Gebruik GLB voor weblevering: het zelfcontainende binaire formaat voorkomt CORS-problemen met .bin sidecars en laadt sneller in WebGL-renderers.
• Geef format-specifieke opties door: generiek scene.open(path) werkt voor de meeste formaten, maar het doorgeven van de loader options class maakt format-specifiek gedrag mogelijk, zoals OBJ-materialen laden of STL-coördinaatnormalisatie.
• xmldom is vereist voor COLLADA: het wordt automatisch geïnstalleerd. Voeg het niet toe aan peerDependencies of probeer het te verwijderen; de COLLADA-lezer roept het direct aan.

Veelvoorkomende problemen

Zie ook

• Kenmerken en functionaliteiten: scene graph, mesh, materialen, animatie en wiskunde-API’s.
• Scenegraph: het bouwen en doorlopen van de knooppuntboom.
• Hoe je een 3D-mesh programmeermatig bouwt.