Compatibilitat de formats 3D

Aspose.3D FOSS per TypeScript llegeix i escriu set formats de fitxer 3D principals. La detecció del format és automàtica en carregar: la biblioteca inspecciona els números màgics binaris, de manera que no cal especificar el format d’origen. Les classes d’opcions específiques de format s’importen des de subcamins del @aspose/3d paquet.

Formats compatibles

OBJ (Wavefront)

OBJ admet tant la importació com l’exportació a @aspose/3d. En desar com a OBJ, la biblioteca de materials (.mtl) s’escriu automàticament al costat del .obj fitxer. Utilitzeu ObjLoadOptions per controlar la càrrega de materials i el comportament del sistema de coordenades.

Opcions clau per a 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)`);

Per convertir un OBJ a qualsevol format d’escriptura, carrega’l i crida scene.save() amb la classe de format de destinació.

glTF i GLB

glTF 2.0 és el format d’intercanvi recomanat per a l’ús en web i motors de jocs. La biblioteca utilitza el mateix GltfFormat classe per a ambdós .gltf (JSON + sidecar) i .glb (binari, autònom) de sortida. Alterna entre ells amb GltfSaveOptions.binaryMode.

Carrega glTF o 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

Exporta com a 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);

Exporta com a GLB binari (.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);

Utilitza binaryMode = true per a la entrega d’actius en producció. Un únic .glb es carrega més ràpidament en navegadors i motors que la parella de text + binari separats.

STL

STL és un format de malla triangulada utilitzat en CAD i impressió 3D. Tant STL binari com ASCII són compatibles per a l’entrada i la sortida. StlSaveOptions.binaryMode controla si la sortida és binària (compacta) o ASCII (legible per a humans).

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 només emmagatzema geometria triangulada i normals de vèrtex. Les dades de material i UV no es conserven en 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

Advertència: les classes d’importador i exportador FBX (FbxImporter, FbxExporter) existeixen a la biblioteca, però la detecció automàtica del format FBX és no està connectada a scene.open() o scene.save(). Cridant scene.open('file.fbx') no invocarà l’importador FBX — el fitxer passarà al recurs alternatiu STL. Cridant scene.save('output.fbx', opts) no invocarà l’exportador FBX. La taula de suport de formats anterior marca FBX com a No* per aquesta raó. Utilitzeu GLB o COLLADA per a una importació i exportació totalment funcional via scene.open() / scene.save().

COLLADA (DAE)

COLLADA és un format d’intercanvi basat en XML compatible amb una àmplia gamma d’eines DCC (Blender, Maya, Cinema 4D). La biblioteca utilitza el xmldom dependència per a l’anàlisi XML; s’instal·la automàticament amb 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);

Els fitxers COLLADA poden contenir metadades d’escalat d’unitats (<unit> element). La biblioteca aplica la conversió d’unitats automàticament en carregar.

Detecció automàtica de format

En carregar des d’un camí de fitxer, la biblioteca intenta la detecció del format a partir de números màgics binaris abans de recórrer a l’extensió del fitxer. Això vol dir que podeu carregar un fitxer GLB anomenat .bin o un fitxer STL anomenat .model sense especificar el format explícitament.

En carregar des d’un Buffer amb scene.openFromBuffer(), la detecció de magic-number és el mecanisme 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 amb nombres màgics fiables: GLB (glTF), STL binari (capçalera de 80 bytes + recompte de triangles), 3MF (ZIP magic PK). OBJ i COLLADA són basats en text i es detecten a partir de l’extensió del fitxer o per la classe d’opcions que passeu.

Consells

• OBJ admet tant importació com exportació: en desar com a OBJ, el .mtl fitxer de material s’escriu automàticament al costat del .obj fitxer.
• Utilitzeu GLB per a la distribució web: el format binari autònom evita problemes de CORS amb .bin sidecars i es carrega més ràpidament en renderitzadors WebGL.
• Passa opcions específiques del format: genèric scene.open(path) funciona per a la majoria de formats, però passar la classe d’opcions del carregador habilita un comportament específic del format com ara la càrrega de materials OBJ o la normalització de coordenades STL.
• xmldom és necessari per a COLLADA: s’instal·la automàticament. No l’afegeixis a peerDependencies o intentis eliminar-lo; el lector COLLADA l’anomena directament.

Problemes comuns

Vegeu també

• Característiques i funcionalitats: graf de escena, malla, materials, animació i API de matemàtiques.
• Graf de escena: construcció i recorregut de l’arbre de nodes.
• Com crear una 3D Mesh programàticament