Supporto Formati 3D

Aspose.3D FOSS per TypeScript legge e scrive sette principali formati di file 3D. Il rilevamento del formato è automatico durante il caricamento: la libreria esamina i numeri magici binari, quindi non è necessario specificare il formato di origine. Le classi di opzioni specifiche per formato sono importate dai sotto‑percorsi del @aspose/3d pacchetto.

Formati supportati

OBJ (Wavefront)

OBJ supporta sia l’importazione che l’esportazione in @aspose/3d. Quando si salva come OBJ, la libreria dei materiali (.mtl) viene scritto automaticamente accanto al .obj file. Usa ObjLoadOptions per controllare il caricamento dei materiali e il comportamento del sistema di coordinate.

Opzioni chiave per 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)`);

Per convertire un OBJ in qualsiasi formato scrivibile, caricalo e chiama scene.save() con la classe del formato di destinazione.

glTF e GLB

glTF 2.0 è il formato di interscambio consigliato per l’uso sul web e nei motori di gioco. La libreria utilizza lo stesso GltfFormat classe per entrambi .gltf (JSON + sidecar) e .glb (binario, autonomo) output. Passa da uno all’altro con GltfSaveOptions.binaryMode.

Carica glTF o 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

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

Esporta come GLB binario (.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);

Usa binaryMode = true per la consegna di asset in produzione. Un unico .glb carica più velocemente nei browser e nei motori rispetto alla coppia testo + binario separati.

STL

STL è un formato di mesh triangolata utilizzato in CAD e stampa 3D. Sia STL binario che ASCII sono supportati per l’input e l’output. StlSaveOptions.binaryMode controlla se l’output è binario (compatto) o ASCII (leggibile dall’uomo).

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 memorizza solo la geometria triangolata e le normali dei vertici. I dati di materiale e UV non vengono conservati 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

Avviso: le classi importatore ed esportatore FBX (FbxImporter, FbxExporter) esistono nella libreria, ma il rilevamento automatico del formato FBX è non collegato in scene.open() o scene.save(). Chiamare scene.open('file.fbx') non invocherà l’importatore FBX — il file ricadrà nel fallback STL. Chiamare scene.save('output.fbx', opts) non invocherà l’esportatore FBX. La tabella di supporto dei formati sopra indica FBX come No* per questo motivo. Usa GLB o COLLADA per importazione ed esportazione pienamente funzionali tramite scene.open() / scene.save().

COLLADA (DAE)

COLLADA è un formato di interscambio basato su XML supportato da un’ampia gamma di strumenti DCC (Blender, Maya, Cinema 4D). La libreria utilizza il xmldom dipendenza per l’analisi XML; viene installata automaticamente con 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);

I file COLLADA possono contenere metadati di scala delle unità (<unit> elemento). La libreria applica automaticamente la conversione delle unità durante il caricamento.

Rilevamento Automatico del Formato

Quando si carica da un percorso file, la libreria tenta il rilevamento del formato dai numeri magici binari prima di ricorrere all’estensione del file. Questo significa che è possibile caricare un file GLB chiamato .bin o un file STL chiamato .model senza specificare esplicitamente il formato.

Quando si carica da un Buffer con scene.openFromBuffer(), il rilevamento del magic-number è il meccanismo principale:

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

Formati con magic number affidabili: GLB (glTF), STL binario (intestazione di 80 byte + conteggio dei triangoli), 3MF (ZIP magic PK). OBJ e COLLADA sono basati su testo e vengono rilevati dall’estensione del file o dalla classe delle opzioni che passi.

Suggerimenti

• OBJ supporta sia l’importazione che l’esportazione: quando si salva come OBJ, il .mtl file materiale viene scritto automaticamente accanto al .obj file.
• Usa GLB per la consegna web: il formato binario autonomo evita problemi CORS con .bin i file sidecar e si carica più velocemente nei renderer WebGL.
• Passa opzioni specifiche per il formato: generico scene.open(path) funziona per la maggior parte dei formati, ma passare la classe delle opzioni del loader abilita comportamenti specifici del formato come il caricamento dei materiali OBJ o la normalizzazione delle coordinate STL.
• xmldom è necessario per COLLADA: viene installato automaticamente. Non aggiungerlo a peerDependencies o provare a rimuoverlo; il lettore COLLADA lo chiama direttamente.

Problemi comuni

Vedi anche

• Caratteristiche e funzionalità: grafico della scena, mesh, materiali, animazione e API matematiche.
• Grafico della scena: costruzione e attraversamento dell’albero dei nodi.
• Come costruire una mesh 3D programmaticamente