3D-Formatunterstützung

Aspose.3D FOSS für TypeScript liest und schreibt sieben wichtige 3D-Dateiformate. Die Format‑Erkennung ist beim Laden automatisch: Die Bibliothek prüft binäre Magic Numbers, sodass Sie das Quellformat nicht angeben müssen. Format‑spezifische Optionsklassen werden aus Unterpfaden des @aspose/3d Pakets.

Unterstützte Formate

OBJ (Wavefront)

OBJ unterstützt sowohl den Import als auch den Export in @aspose/3d. Beim Speichern als OBJ wird die Materialbibliothek (.mtl) wird automatisch zusammen mit dem .obj Datei. Verwenden Sie ObjLoadOptions um das Laden von Materialien und das Verhalten des Koordinatensystems zu steuern.

Wichtige Optionen für 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)`);

Um ein OBJ in ein beliebiges schreibbares Format zu konvertieren, lade es und rufe scene.save() mit der Ziel-Formatklasse.

glTF and GLB

glTF 2.0 ist das empfohlene Austauschformat für Web- und Spiel-Engine‑Verwendung. Die Bibliothek verwendet dieselbe GltfFormat Klasse für beide .gltf (JSON + sidecar) und .glb (binary, self-contained) Ausgabe. Umschalten zwischen ihnen mit GltfSaveOptions.binaryMode.

Laden von glTF oder 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

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

Exportieren als binäres 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);

Verwenden binaryMode = true für die Bereitstellung von Produktions-Assets. Ein einzelnes .glb lädt schneller in Browsern und Engines als das geteilte Text‑+‑Binär‑Paar.

STL

STL ist ein trianguliertes Mesh‑Format, das in CAD und 3D‑Druck verwendet wird. Sowohl binäres als auch ASCII‑STL werden für Ein- und Ausgabe unterstützt. StlSaveOptions.binaryMode steuert, ob die Ausgabe binär (kompakt) oder ASCII (menschlich lesbar) ist.

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 speichert nur triangulierte Geometrie und Vertex‑Normalen. Material‑ und UV‑Daten werden in STL nicht erhalten.

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

Warnung: FBX‑Import‑ und Export‑Klassen (FbxImporter, FbxExporter) existieren in der Bibliothek, aber die automatische Erkennung des FBX‑Formats ist nicht angeschlossen in scene.open() oder scene.save(). Aufrufen scene.open('file.fbx') ruft den FBX-Importer nicht auf — die Datei wird an das STL-Fallback weitergeleitet. Aufrufen scene.save('output.fbx', opts) ruft den FBX-Exporter nicht auf. Die obige Formatunterstützungstabelle markiert FBX als No* aus diesem Grund. Verwenden Sie GLB oder COLLADA für voll funktionsfähigen Import und Export über scene.open() / scene.save().

COLLADA (DAE)

COLLADA ist ein XML-basiertes Austauschformat, das von einer breiten Palette von DCC-Tools (Blender, Maya, Cinema 4D) unterstützt wird. Die Bibliothek verwendet die xmldom Abhängigkeit für XML-Parsing; sie wird automatisch mit 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-Dateien können Metadaten zur Einheitsskalierung enthalten (<unit> element). Die Bibliothek führt bei der Ladung automatisch eine Einheitumrechnung durch.

Formatautomatischerkennung

Beim Laden von einem Dateipfad versucht die Bibliothek, das Format anhand von binären Magic Numbers zu erkennen, bevor sie auf die Dateierweiterung zurückgreift. Das bedeutet, Sie können eine GLB-Datei mit dem Namen .bin oder eine STL-Datei namens .model ohne das Format explizit anzugeben.

Beim Laden von einer Buffer mit scene.openFromBuffer(), die Erkennung von Magic Numbers ist der primäre Mechanismus:

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

Formate mit zuverlässigen Magic Numbers: GLB (glTF), STL binär (80-Byte-Header + Dreiecksanzahl), 3MF (ZIP magic PK). OBJ und COLLADA sind textbasiert und werden anhand der Dateierweiterung oder der übergebenen Optionsklasse erkannt.

Tipps

• OBJ unterstützt sowohl Import als auch Export: Beim Speichern als OBJ wird die .mtl Materialdatei automatisch neben der .obj Datei.
• Verwenden Sie GLB für die Webauslieferung: das eigenständige Binärformat vermeidet CORS-Probleme mit .bin Sidecars und lädt schneller in WebGL-Renderern.
• Geben Sie formatbezogene Optionen weiter: generisch scene.open(path) funktioniert für die meisten Formate, aber das Übergeben der Loader-Optionen-Klasse ermöglicht formatbezogenes Verhalten wie das Laden von OBJ-Materialien oder die Normalisierung von STL-Koordinaten.
• xmldom ist für COLLADA erforderlich: es wird automatisch installiert. Fügen Sie es nicht zu peerDependencies oder versuchen Sie, es zu entfernen; der COLLADA-Leser ruft es direkt auf.

Häufige Probleme

Siehe auch

• Funktionen und Merkmale: Szenengraph, Mesh, Materialien, Animation und Mathematik-APIs.
• Szenengraph: Aufbau und Durchlaufen des Knotenbaums.
• Wie man ein 3D-Mesh programmgesteuert erstellt.