Aspose.3D FOSS
TypeScript
Guía del desarrollador
Loading Models

Cargando modelos 3D

@aspose/3d proporciona dos métodos de carga en el Scene clase: open() para carga mediante ruta de archivo y openFromBuffer() para datos en memoria. La detección de formato es automática a partir de los números mágicos binarios o la extensión del archivo, por lo que rara vez necesitas especificar el formato de origen explícitamente.

Cargando desde una ruta de archivo

Pasa la cadena de ruta de archivo a scene.open(). La biblioteca detecta el formato a partir de la extensión del archivo y, para formatos binarios, a partir de los bytes mágicos:

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() reemplaza cualquier contenido de escena existente. Si necesitas cargar varios archivos, crea Scene instancias.

Cargando OBJ con materiales

Los archivos OBJ hacen referencia a materiales a través de un archivo sidecar .mtl archivo. La carga de materiales está habilitada por defecto (ObjLoadOptions.enableMaterials = true). Pasar ObjLoadOptions para controlar esto y otras opciones de carga:

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

Cargando desde un búfer

Usar openFromBuffer() cuando los datos del archivo ya están en memoria, por ejemplo a partir de una obtención HTTP, un BLOB de base de datos o una extracción de un archivo zip. Esto evita escribir en 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`);

Para formatos binarios (GLB, STL binary, 3MF), la biblioteca lee los bytes mágicos del búfer para detectar el formato automáticamente, por lo que puedes pasar undefined como argumento de opciones:

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

Cargando desde HTTP (Node.js 18+)

Obtenga un recurso remoto y cárguelo sin tocar el sistema de archivos:

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

Inspeccionando la escena cargada

Después de cargar, recorra el grafo de la escena para enumerar nodos e identificar geometría:

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

Leyendo metadatos del recurso

El assetInfo propiedad expone metadatos a nivel de archivo:

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 todos los formatos poblan assetInfo. FBX y COLLADA tienen metadatos ricos; OBJ y STL típicamente no los tienen.

Referencia de Opciones de Carga Específicas del Formato

FormatoClase de OpcionesRuta de importaciónOpciones clave
OBJObjLoadOptions@aspose/3d/formats/objenableMaterials, flipCoordinateSystem, scale, normalizeNormal
glTF / GLB(ninguno requerido)N/ADetectado automáticamente; no se necesita clase de opciones
STLStlLoadOptions@aspose/3d/formats/stl(no hay opciones configurables en la versión actual)
FBXFbxLoadOptions@aspose/3d/formats/fbx(no hay opciones configurables en la versión actual)
COLLADAColladaLoadOptions@aspose/3d/formats/collada(no hay opciones configurables en la versión actual)
3MF(ninguno requerido)N/ADetectado automáticamente

Errores Comunes de Carga

SíntomaCausaSolución
Error: Cannot find module '@aspose/3d/formats/obj'moduleResolution no está configurado a nodeAgregar "moduleResolution": "node" a tsconfig.json
Lista de nodos vacía después de cargar OBJ.mtl sidecar faltante o enableMaterials no está configuradoEstablecer options.enableMaterials = true y asegúrese .mtl está en el mismo directorio
La escena se carga pero rootNode.childNodes está vacíaEl formato usa una malla raíz única, no nodos hijosAcceso scene.rootNode.entity directamente
openFromBuffer lanza una excepción con STL binarioEl búfer se recortó incorrectamente (faltan bytes finales)Usa el completo readFileSync() salida sin recortar
La matriz de clips de animación está vacía después de cargar el FBXEl archivo FBX utiliza transformaciones baked, no clipsLa animación está baked por fotograma; la matriz de clips estará vacía

Ver también

 Español