Aspose.3D FOSS
TypeScript
Guia do Desenvolvedor
Loading Models

Carregando Modelos 3D

@aspose/3d fornece dois métodos de carregamento na Scene classe: open() para carregamento por caminho de arquivo e openFromBuffer() para dados em memória. A detecção de formato é automática a partir de números mágicos binários ou da extensão do arquivo, portanto você raramente precisa especificar o formato de origem explicitamente.

Carregando a partir de um caminho de arquivo

Passe a string do caminho do arquivo para scene.open(). A biblioteca detecta o formato a partir da extensão do arquivo e, para formatos binários, a partir dos 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() substitui qualquer conteúdo de cena existente. Se precisar carregar vários arquivos, crie Scene instâncias.

Carregando OBJ com materiais

Arquivos OBJ referenciam materiais por meio de um sidecar .mtl arquivo. O carregamento de material está ativado por padrão (ObjLoadOptions.enableMaterials = true). Passar ObjLoadOptions para controlar isto e outras opções de carregamento:

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

Carregando a partir de um buffer

Usar openFromBuffer() quando os dados do arquivo já estão na memória, por exemplo de uma requisição HTTP, um BLOB de banco de dados ou a extração de um arquivo zip. Isso evita gravação em 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 binários (GLB, STL binário, 3MF), a biblioteca lê os bytes mágicos do buffer para detectar o formato automaticamente, portanto você pode passar undefined como argumento de opções:

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

Carregando a partir de HTTP (Node.js 18+)

Busque um recurso remoto e carregue-o sem tocar no sistema de arquivos:

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

Inspecionando a cena carregada

Após o carregamento, percorra o grafo da cena para enumerar nós e 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);

Lendo metadados do recurso

O assetInfo propriedade expõe metadados ao nível do arquivo:

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

Nem todos os formatos preenchem assetInfo. FBX e COLLADA possuem metadados ricos; OBJ e STL tipicamente não os possuem.

Referência de Opções de Carregamento Específicas de Formato

FormatoClasse de OpçõesCaminho de ImportaçãoOpções de Chave
OBJObjLoadOptions@aspose/3d/formats/objenableMaterials, flipCoordinateSystem, scale, normalizeNormal
glTF / GLB(nenhum necessário)N/ADetectado automaticamente; nenhuma classe de opções necessária
STLStlLoadOptions@aspose/3d/formats/stl(nenhuma opção configurável na versão atual)
FBXFbxLoadOptions@aspose/3d/formats/fbx(nenhuma opção configurável na versão atual)
COLLADAColladaLoadOptions@aspose/3d/formats/collada(nenhuma opção configurável na versão atual)
3MF(nenhum necessário)N/ADetectado automaticamente

Erros Comuns de Carregamento

SintomaCausaCorreção
Error: Cannot find module '@aspose/3d/formats/obj'moduleResolution não definido como nodeAdicionar "moduleResolution": "node" para tsconfig.json
Lista de nós vazia após carregar OBJ.mtl sidecar ausente ou enableMaterials não definidoDefinir options.enableMaterials = true e garantir .mtl está no mesmo diretório
A cena carrega, mas rootNode.childNodes está vaziaO formato usa uma única malha raiz, não nós filhosAcessar scene.rootNode.entity diretamente
openFromBuffer gera exceção com STL binárioO buffer foi fatiado incorretamente (bytes finais ausentes)Use o completo readFileSync() resultado sem fatiamento
O array de clipes de animação está vazio após o carregamento do FBXO arquivo FBX usa transformações baked, não clipesA animação é baked por quadro; o array de clipes ficará vazio

Veja Também

 Português