Aspose.3D FOSS
TypeScript
Guide du développeur
Loading Models

Chargement de modèles 3D

@aspose/3d fournit deux méthodes de chargement sur le Scene classe : open() pour le chargement par chemin de fichier et openFromBuffer() pour les données en mémoire. La détection du format est automatique à partir des nombres magiques binaires ou de l’extension du fichier, de sorte que vous avez rarement besoin de spécifier explicitement le format source.

Chargement à partir d’un chemin de fichier

Passez la chaîne de chemin de fichier à scene.open(). La bibliothèque détecte le format à partir de l’extension du fichier et, pour les formats binaires, à partir des octets magiques :

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() remplace tout le contenu de la scène existant. Si vous devez charger plusieurs fichiers, créez des Scene instances.

Chargement d’OBJ avec matériaux

Les fichiers OBJ référencent les matériaux via un fichier annexe .mtl fichier. Le chargement des matériaux est activé par défaut (ObjLoadOptions.enableMaterials = true). Passer ObjLoadOptions pour contrôler cela et d’autres options de chargement :

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

Chargement depuis un tampon

Utiliser openFromBuffer() lorsque les données du fichier sont déjà en mémoire, par exemple à partir d’une récupération HTTP, d’un BLOB de base de données ou d’une extraction d’archive zip. Cela évite d’écrire sur le disque :

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

Pour les formats binaires (GLB, STL binary, 3MF), la bibliothèque lit les octets magiques du tampon pour détecter automatiquement le format, vous pouvez donc passer undefined comme argument d’options :

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

Chargement depuis HTTP (Node.js 18+)

Récupérez un actif distant et chargez‑le sans toucher au système de fichiers :

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

Inspection de la scène chargée

Après le chargement, parcourez le graphe de la scène pour énumérer les nœuds et identifier la géométrie :

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

Lecture des métadonnées de l’actif

Le assetInfo propriété expose les métadonnées au niveau du fichier :

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

Tous les formats ne remplissent pas assetInfo. FBX et COLLADA possèdent des métadonnées riches ; OBJ et STL n’en ont généralement pas.

Référence des options de chargement spécifiques au format

FormatClasse d’optionsChemin d’importationOptions clés
OBJObjLoadOptions@aspose/3d/formats/objenableMaterials, flipCoordinateSystem, scale, normalizeNormal
glTF / GLB(aucun requis)N/ADétecté automatiquement ; aucune classe d’options requise
STLStlLoadOptions@aspose/3d/formats/stl(aucune option configurable dans la version actuelle)
FBXFbxLoadOptions@aspose/3d/formats/fbx(aucune option configurable dans la version actuelle)
COLLADAColladaLoadOptions@aspose/3d/formats/collada(aucune option configurable dans la version actuelle)
3MF(aucun requis)N/ADétecté automatiquement

Erreurs de chargement courantes

SymptômeCauseCorrection
Error: Cannot find module '@aspose/3d/formats/obj'moduleResolution non défini à nodeAjouter "moduleResolution": "node" à tsconfig.json
Liste de nœuds vide après le chargement d’OBJ.mtl sidecar manquant ou enableMaterials non définiDéfinir options.enableMaterials = true et assurez que .mtl se trouve dans le même répertoire
La scène se charge mais rootNode.childNodes est videLe format utilise un seul maillage racine, pas de nœuds enfantsAccès scene.rootNode.entity directement
openFromBuffer lance une exception avec le STL binaireLe tampon a été découpé incorrectement (octets de fin manquants)Utilisez le complet readFileSync() sortie sans découpage
Le tableau des clips d’animation est vide après le chargement du FBXLe fichier FBX utilise des transformations précalculées, pas de clipsL’animation est précalculée image par image ; le tableau de clips sera vide

Voir aussi

 Français