Aspose.3D FOSS
TypeScript
Guia del desenvolupador
Loading Models

Carregant models 3D

@aspose/3d proporciona dos mètodes de càrrega a la Scene classe: open() per a la càrrega per ruta de fitxer i openFromBuffer() per a dades en memòria. La detecció del format és automàtica a partir dels números màgics binaris o de l’extensió del fitxer, de manera que rarament cal especificar explícitament el format d’origen.

Càrrega des d’un camí de fitxer

Passa la cadena de ruta del fitxer a scene.open(). La biblioteca detecta el format a partir de l’extensió del fitxer i, per a formats binaris, a partir dels bytes màgics:

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() substitueix qualsevol contingut d’escena existent. Si necessites carregar diversos fitxers, crea Scene instàncies.

Càrrega d’OBJ amb materials

Els fitxers OBJ fan referència a materials a través d’un fitxer sidecar .mtl fitxer. La càrrega de materials és activada per defecte (ObjLoadOptions.enableMaterials = true). Passa ObjLoadOptions per controlar això i altres opcions de càrrega:

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

Càrrega des d’un buffer

Utilitza openFromBuffer() quan les dades del fitxer ja són a la memòria, per exemple d’una recuperació HTTP, d’un BLOB de base de dades o d’una extracció d’un arxiu zip. Això evita escriure al disc:

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 a formats binaris (GLB, STL binary, 3MF), la biblioteca llegeix els bytes màgics del buffer per detectar el format automàticament, de manera que pots passar undefined com a argument d’opcions:

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

Càrrega des d’HTTP (Node.js 18+)

Obté un recurs remot i carrega’l sense tocar el sistema de fitxers:

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

Inspecció de l’escena carregada

Després de carregar, recorre el gràfic d’escena per enumerar nodes i identificar 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);

Lectura de metadades del recurs

El assetInfo propietat exposa metadades a nivell de fitxer:

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

No tots els formats omplen assetInfo. FBX i COLLADA tenen metadades riques; OBJ i STL típicament no en tenen.

Referència d’opcions de càrrega específiques del format

FormatClasse d’opcionsCamí d’importacióOpcions clau
OBJObjLoadOptions@aspose/3d/formats/objenableMaterials, flipCoordinateSystem, scale, normalizeNormal
glTF / GLB(cap requerit)N/ADetectat automàticament; no cal classe d’opcions
STLStlLoadOptions@aspose/3d/formats/stl(no hi ha opcions configurables a la versió actual)
FBXFbxLoadOptions@aspose/3d/formats/fbx(no hi ha opcions configurables a la versió actual)
COLLADAColladaLoadOptions@aspose/3d/formats/collada(no hi ha opcions configurables a la versió actual)
3MF(cap requerit)N/ADetectat automàticament

Errors de càrrega comuns

SímptomaCausaSolució
Error: Cannot find module '@aspose/3d/formats/obj'moduleResolution no establert a nodeAfegir "moduleResolution": "node" a tsconfig.json
Llista de nodes buida després de carregar OBJ.mtl sidecar absent o enableMaterials no establertEstablir options.enableMaterials = true i assegura .mtl és al mateix directori
L’escena es carrega però rootNode.childNodes està buidaEl format utilitza una única malla arrel, no nodes fillsAccés scene.rootNode.entity directament
openFromBuffer llança amb STL binariEl buffer es va tallar incorrectament (faltaven bytes finals)Utilitza el complet readFileSync() sortida sense tallar
La matriu de clips d’animació està buida després de carregar l’FBXEl fitxer FBX utilitza transformacions precomputades, no clipsL’animació està precomputada per fotograma; la matriu de clips estarà buida

Vegeu també

 Català