Aspose.3D FOSS
TypeScript
Guia de Desenvolvedores
Loading Models

Carregamento de modelos 3D

Este guia abrange os dois métodos de carregamento no sistema de carga. Scene classe: open() para carregamento de trilhos de ficheiros e openFromBuffer() A detecção de formato é automática a partir de números mágicos binários ou extensão de arquivo, então você raramente precisa especificar o formato fonte explicitamente.

Carregamento a partir de um caminho de arquivo

Passe a sequência de caminho do arquivo para: scene.open().A biblioteca detecta o formato a partir da extensão de arquivo e, para formatos binários, 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}`);

Passagem . new FbxLoadOptions() como segundo argumento para a open() quando carregam arquivos FBX; o FBx requer opções explícitas em vez de detecção por bytes mágicos.

open() Se você precisa carregar vários arquivos, crie separado Scene casos.

Carregamento de materiais no OBJ

OBJ arquivos de referência materiais através de um sidecar .mtl Arquivo. Carregamento de material é habilitado por padrão (ObjLoadOptions.enableMaterials = true) Passagem ObjLoadOptions para controlar esta e outras opções de tempo 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}`);
}

Carregamento a partir de um buffer

Utilização: openFromBuffer() quando os dados do arquivo já estão na memória, por exemplo de uma busca HTTP, um BLOB de banco de dados ou uma extração de arquivos zip. Isto evita a escrita no 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, de modo que você pode passar undefined como argumento das 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

Carregamento a partir do HTTP (Node.js 18+)

Arranja um recurso remoto e carrega-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`);

Inspecção da cena cheia de pessoas

Após o carregamento, percorra a cena para enumerar os nós e identificar geometria:

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

const scene = new Scene();
scene.open('model.fbx'); // ASCII FBX only; see FBX limitation note above

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

Leitura de metadados dos ativos

Acesso ao assetInfo Propriedade para ler metadados a nível de ficheiro, tais como criador, nome da unidade e fator de escala unitária:

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

const scene = new Scene();
scene.open('model.fbx'); // ASCII FBX only

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

Suporte de formato para: assetInfo FBX e COLLADA têm metadados ricos; OBJ e STL normalmente não.

Referência de opções de carregamento específicas do formato

Formatos de imagemClasse de opçõesCaminho de importaçãoOpções fundamentais
OBJObjLoadOptions@aspose/3d/formats/objenableMaterials, flipCoordinateSystem, scale, normalizeNormal
GTF(não obrigatório)N/AAuto-detectado; cobre tanto o JSON glTF como o binário GLB
STLStlLoadOptions@aspose/3d/formats/stl(não há opções configuráveis na versão atual)
FBXFbxLoadOptions@aspose/3d/formats/fbxApenas ASCII FBX; não é suportado o FBx binário. Não detectado automaticamente passa FbxLoadOptions explicitamente.
COLLADAColladaLoadOptions@aspose/3d/formats/collada(não há opções configuráveis na versão atual)
3MF(não obrigatório)N/AAuto-detectado

A detecção de formato usa a extensão do arquivo ou bytes mágicos binários; passe opções específicas para o formato apenas quando você precisar de um comportamento não padrão.

Erros de carregamento comuns

Sintoma:Causa da morteCorreção
Erro de importação ao solicitar @aspose/3d/formats/* SubmódulosmoduleResolution Desaparecido node valor deAdicionar "moduleResolution": "node" a) para o tsconfig.json
Lista de nós vazia após o carregamento do arquivo OBJ.mtl Carro lateral ausente ou enableMaterials deficientesSet (s) options.enableMaterials = true e assegurar a .mtl está no mesmo diretório.
A cena está cheia, mas… rootNode.childNodes está vazio.Formatar usa uma única malha de raiz, não nós filhosAcessos scene.rootNode.entity direta
openFromBuffer lançamentos com STL binário.O buffer foi cortado incorretamente (absença de bytes)Use o total . readFileSync() produção sem corte em fatias
Array de clipes de animação está vazio após o carregamento do FBXO arquivo FBX usa transformações em panelas, não clips.Animação é assada por quadro; o conjunto de clipes ficará vazio
Arquivo FBX não carrega ou produz cena vaziaApenas o ASCII FBX é legível; formato binário produz uma cena vazia.Converter para ASCII FBX usando as configurações de exportação do seu editor 3D

Ver também:

 Português