Aspose.3D FOSS
TypeScript
Guida per sviluppatori
Loading Models

Caricamento di modelli 3D

@aspose/3d fornisce due metodi di caricamento sulla Scene classe: open() per il caricamento da percorso file e openFromBuffer() per dati in memoria. Il rilevamento del formato è automatico tramite i numeri magici binari o l’estensione del file, quindi raramente è necessario specificare esplicitamente il formato di origine.

Caricamento da un percorso file

Passa la stringa del percorso file a scene.open(). La libreria rileva il formato dall’estensione del file e, per i formati binari, dai byte magici:

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

const scene = new Scene();
scene.open('model.fbx');

console.log(`Root children: ${scene.rootNode.childNodes.length}`);
console.log(`Animation clips: ${scene.animationClips.length}`);

open() sostituisce qualsiasi contenuto della scena esistente. Se devi caricare più file, crea separati Scene istanze.

Caricamento OBJ con materiali

I file OBJ fanno riferimento ai materiali tramite un file sidecar .mtl file. Il caricamento dei materiali è abilitato per impostazione predefinita (ObjLoadOptions.enableMaterials = true). Passa ObjLoadOptions per controllare questa e altre opzioni di caricamento:

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

const scene = new Scene();
const options = new ObjLoadOptions();
options.enableMaterials = true;       // load the .mtl sidecar
options.flipCoordinateSystem = false; // keep original Y-up orientation
options.normalizeNormal = true;       // fix degenerate normals
options.scale = 1.0;                  // unit scale multiplier

scene.open('character.obj', options);

// Inspect materials on the first node
const first = scene.rootNode.childNodes[0];
if (first) {
    console.log(`Materials on ${first.name}: ${first.materials.length}`);
}

Caricamento da un buffer

Usa openFromBuffer() quando i dati del file sono già in memoria, ad esempio da un fetch HTTP, un BLOB di database o l’estrazione di un archivio zip. Questo evita di scrivere su disco:

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

const buffer: Buffer = fs.readFileSync('model.obj');
const scene = new Scene();
const options = new ObjLoadOptions();
options.enableMaterials = true;

scene.openFromBuffer(buffer, options);
console.log(`Loaded ${scene.rootNode.childNodes.length} root nodes`);

Per i formati binari (GLB, STL binary, 3MF), la libreria legge i byte magici dal buffer per rilevare automaticamente il formato, così puoi passare undefined come argomento delle opzioni:

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

const glbBuffer: Buffer = fs.readFileSync('model.glb');
const scene = new Scene();
scene.openFromBuffer(glbBuffer); // format auto-detected from GLB magic bytes

Caricamento da HTTP (Node.js 18+)

Recupera una risorsa remota e caricala senza toccare il file system:

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

async function loadFromUrl(url: string): Promise<Scene> {
    const response = await fetch(url);
    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    const arrayBuffer = await response.arrayBuffer();
    const buffer = Buffer.from(arrayBuffer);

    const scene = new Scene();
    scene.openFromBuffer(buffer);
    return scene;
}

const scene = await loadFromUrl('https://example.com/model.glb');
console.log(`Loaded scene: ${scene.rootNode.childNodes.length} root nodes`);

Ispezione della scena caricata

Dopo il caricamento, percorri il grafo della scena per elencare i nodi e identificare la geometria:

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

const scene = new Scene();
scene.open('model.fbx');

function inspect(node: Node, depth: number = 0): void {
    const indent = '  '.repeat(depth);
    const entityType = node.entity ? node.entity.constructor.name : '(none)';
    console.log(`${indent}${node.name} [${entityType}]`);

    if (node.entity instanceof Mesh) {
        const mesh = node.entity as Mesh;
        console.log(`${indent}  vertices: ${mesh.controlPoints.length}, polygons: ${mesh.polygonCount}`);
    }

    for (const child of node.childNodes) {
        inspect(child, depth + 1);
    }
}

inspect(scene.rootNode);

Lettura dei metadati della risorsa

Il assetInfo la proprietà espone i metadati a livello di file:

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

const scene = new Scene();
scene.open('model.fbx');

const info = scene.assetInfo;
if (info) {
    console.log(`Creator: ${info.creator}`);
    console.log(`Unit name: ${info.unitName}`);
    console.log(`Unit scale: ${info.unitScaleFactor}`);
}

Non tutti i formati popolano assetInfo. FBX e COLLADA hanno metadati ricchi; OBJ e STL tipicamente non li hanno.

Riferimento alle opzioni di caricamento specifiche per formato

FormatoClasse OpzioniPercorso di ImportazioneOpzioni Chiave
OBJObjLoadOptions@aspose/3d/formats/objenableMaterials, flipCoordinateSystem, scale, normalizeNormal
glTF / GLB(nessuno richiesto)N/ARilevato automaticamente; nessuna classe opzioni necessaria
STLStlLoadOptions@aspose/3d/formats/stl(nessuna opzione configurabile nella versione corrente)
FBXFbxLoadOptions@aspose/3d/formats/fbx(nessuna opzione configurabile nella versione corrente)
COLLADAColladaLoadOptions@aspose/3d/formats/collada(nessuna opzione configurabile nella versione corrente)
3MF(nessuno richiesto)N/ARilevato automaticamente

Errori di caricamento comuni

SintomoCausaCorrezione
Error: Cannot find module '@aspose/3d/formats/obj'moduleResolution non impostato a nodeAggiungi "moduleResolution": "node" a tsconfig.json
Elenco nodi vuoto dopo il caricamento di OBJ.mtl sidecar mancante o enableMaterials non impostatoImposta options.enableMaterials = true e assicurati .mtl è nella stessa directory
La scena si carica ma rootNode.childNodes è vuotaIl formato utilizza una singola mesh radice, non nodi figlioAccedi scene.rootNode.entity direttamente
openFromBuffer genera un’eccezione con STL binarioIl buffer è stato tagliato in modo errato (byte finali mancanti)Usa il readFileSync() output senza taglio
L’array dei clip di animazione è vuoto dopo il caricamento FBXIl file FBX utilizza trasformazioni baked, non clipL’animazione è pre‑elaborata per fotogramma; l’array dei clip sarà vuoto

Vedi anche

 Italiano