Prise en charge des formats 3D

Aspose.3D FOSS pour TypeScript lit et écrit sept principaux formats de fichiers 3D. La détection du format est automatique lors du chargement : la bibliothèque inspecte les nombres magiques binaires, vous n’avez donc pas besoin de spécifier le format source. Les classes d’options spécifiques à chaque format sont importées depuis des sous‑chemins du @aspose/3d package.

Formats pris en charge

OBJ (Wavefront)

OBJ prend en charge à la fois l’importation et l’exportation en @aspose/3d. Lors de l’enregistrement au format OBJ, la bibliothèque de matériaux (.mtl) est écrite automatiquement à côté du .obj fichier. Utilisez ObjLoadOptions pour contrôler le chargement des matériaux et le comportement du système de coordonnées.

Options clés pour ObjLoadOptions:

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

const scene = new Scene();
const opts = new ObjLoadOptions();
opts.enableMaterials = true;
opts.normalizeNormal = true;

scene.open('model.obj', opts);
console.log(`Loaded ${scene.rootNode.childNodes.length} top-level node(s)`);

Pour convertir un OBJ en n’importe quel format inscriptible, chargez-le et appelez scene.save() avec la classe du format cible.

glTF and GLB

glTF 2.0 est le format d’échange recommandé pour une utilisation sur le web et dans les moteurs de jeu. La bibliothèque utilise le même GltfFormat classe pour les deux .gltf (JSON + sidecar) et .glb (binaire, autonome) sortie. Basculez entre les deux avec GltfSaveOptions.binaryMode.

Charger glTF ou GLB :

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

const scene = new Scene();
scene.open('model.gltf', new GltfLoadOptions());
// or
scene.open('model.glb');  // format detected from magic bytes

Exporter au format JSON glTF (.gltf + .bin):

import { Scene } from '@aspose/3d';
import { GltfSaveOptions, GltfFormat } from '@aspose/3d/formats/gltf';

const scene = new Scene();
scene.open('input.fbx');

const opts = new GltfSaveOptions();
opts.binaryMode = false;  // produces output.gltf + output.bin
scene.save('output.gltf', GltfFormat.getInstance(), opts);

Exporter au format binaire GLB (.glb):

import { Scene } from '@aspose/3d';
import { GltfSaveOptions, GltfFormat } from '@aspose/3d/formats/gltf';

const scene = new Scene();
scene.open('input.obj');

const opts = new GltfSaveOptions();
opts.binaryMode = true;  // single self-contained file
scene.save('output.glb', GltfFormat.getInstance(), opts);

Utiliser binaryMode = true pour la livraison d’actifs en production. Un seul .glb se charge plus rapidement dans les navigateurs et les moteurs que la paire texte + binaire séparée.

STL

STL est un format de maillage triangulé utilisé en CAO et en impression 3D. Les deux formats STL binaire et ASCII sont pris en charge pour l’entrée et la sortie. StlSaveOptions.binaryMode contrôle si la sortie est binaire (compacte) ou ASCII (lisible par l’homme).

import { Scene } from '@aspose/3d';
import { StlLoadOptions, StlSaveOptions } from '@aspose/3d/formats/stl';

const scene = new Scene();
scene.open('model.stl', new StlLoadOptions());

// Export as binary STL (default, compact)
const binaryOpts = new StlSaveOptions();
binaryOpts.binaryMode = true;
scene.save('output_binary.stl', binaryOpts);

// Export as ASCII STL (human-readable)
const asciiOpts = new StlSaveOptions();
asciiOpts.binaryMode = false;
scene.save('output_ascii.stl', asciiOpts);

STL ne stocke que la géométrie triangulée et les normales de sommet. Les données de matériau et d’UV ne sont pas conservées dans le STL.

3MF (3D Manufacturing Format)

3MF is an XML-based format designed for additive manufacturing. It supports color and material metadata alongside geometry. Use it when exchanging files with 3D printing slicers or manufacturing workflows.

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

const scene = new Scene();
scene.open('model.3mf');

// Re-export as 3MF
scene.save('output.3mf', new ThreeMfSaveOptions());

3MF files are ZIP archives internally. The library handles archive creation and extraction automatically.

FBX

Avertissement: les classes d’importation et d’exportation FBX (FbxImporter, FbxExporter) existent dans la bibliothèque, mais la détection automatique du format FBX est non câblée dans scene.open() ou scene.save(). Appeler scene.open('file.fbx') ne déclenchera pas l’importateur FBX — le fichier sera transmis au secours STL. Appeler scene.save('output.fbx', opts) ne déclenchera pas l’exportateur FBX. Le tableau de prise en charge des formats ci‑dessus indique FBX comme No* pour cette raison. Utilisez GLB ou COLLADA pour une importation et exportation pleinement fonctionnelles via scene.open() / scene.save().

COLLADA (DAE)

COLLADA est un format d’échange basé sur XML pris en charge par un large éventail d’outils DCC (Blender, Maya, Cinema 4D). La bibliothèque utilise le xmldom dépendance pour l’analyse XML ; elle est installée automatiquement avec npm install @aspose/3d.

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

const scene = new Scene();
scene.open('model.dae');

// Re-export as COLLADA
const saveOpts = new ColladaSaveOptions();
scene.save('output.dae', saveOpts);

Les fichiers COLLADA peuvent contenir des métadonnées d’échelle d’unité (<unit> élément). La bibliothèque applique automatiquement la conversion d’unités lors du chargement.

Détection automatique du format

Lors du chargement depuis un chemin de fichier, la bibliothèque tente la détection du format à partir des nombres magiques binaires avant de revenir à l’extension du fichier. Cela signifie que vous pouvez charger un fichier GLB nommé .bin ou un fichier STL nommé .model sans spécifier le format explicitement.

Lors du chargement depuis un Buffer avec scene.openFromBuffer(), la détection par numéro magique est le mécanisme principal :

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

const buffer = fs.readFileSync('model.glb');
const scene = new Scene();
scene.openFromBuffer(buffer);  // format detected from magic bytes: 'glTF'

console.log(`Root has ${scene.rootNode.childNodes.length} child node(s)`);

Formats avec des numéros magiques fiables : GLB (glTF), STL binaire (en-tête de 80 octets + nombre de triangles), 3MF (ZIP magic PK). OBJ et COLLADA sont basés sur du texte et sont détectés à partir de l’extension de fichier ou par la classe d’options que vous passez.

Conseils

• OBJ prend en charge à la fois l’importation et l’exportation: lors de l’enregistrement au format OBJ, le .mtl fichier matériel est écrit automatiquement à côté du .obj fichier.
• Utilisez GLB pour la diffusion sur le web: le format binaire autonome évite les problèmes CORS avec .bin les sidecars et se charge plus rapidement dans les rendus WebGL.
• Passez des options spécifiques au format: générique scene.open(path) fonctionne pour la plupart des formats, mais passer la classe d’options du chargeur active un comportement spécifique au format tel que le chargement de matériaux OBJ ou la normalisation des coordonnées STL.
• xmldom est requis pour COLLADA: il est installé automatiquement. Ne l’ajoutez pas à peerDependencies ou essayez de le supprimer ; le lecteur COLLADA l’appelle directement.

Problèmes courants

Voir aussi

• Fonctionnalités et fonctions: graphe de scène, maillage, matériaux, animation et API mathématiques.
• Graphe de scène: construction et traversée de l’arbre de nœuds.
• Comment créer un maillage 3D de manière programmatique