Compatibilidad de formatos 3D

Aspose.3D FOSS para TypeScript lee y escribe siete formatos de archivo 3D principales. La detección de formato es automática al cargar: la biblioteca inspecciona los números mágicos binarios, por lo que no es necesario especificar el formato de origen. Las clases de opciones específicas de cada formato se importan desde subrutas del @aspose/3d paquete.

Formatos compatibles

OBJ (Wavefront)

OBJ admite tanto la importación como la exportación en @aspose/3d. Al guardar como OBJ, la biblioteca de materiales (.mtl) se escribe automáticamente junto al .obj archivo. Utilice ObjLoadOptions para controlar la carga de materiales y el comportamiento del sistema de coordenadas.

Opciones clave para 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)`);

Para convertir un OBJ a cualquier formato escribible, cárgalo y llama a scene.save() con la clase del formato de destino.

glTF and GLB

glTF 2.0 es el formato de intercambio recomendado para uso web y en motores de juego. La biblioteca usa el mismo GltfFormat clase para ambos .gltf (JSON + sidecar) y .glb (binario, autónomo) salida. Alterna entre ellos con GltfSaveOptions.binaryMode.

Cargar 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

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

Exportar como GLB binario (.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);

Usar binaryMode = true para la entrega de activos en producción. Un único .glb carga más rápido en navegadores y motores que el par de texto + binario separado.

STL

STL es un formato de malla triangulada usado en CAD e impresión 3D. Tanto STL binario como ASCII son compatibles para entrada y salida. StlSaveOptions.binaryMode controla si la salida es binaria (compacta) o ASCII (legible por humanos).

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 solo almacena geometría triangulada y normales de vértices. Los datos de material y UV no se conservan 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

Advertencia: clases de importador y exportador FBX (FbxImporter, FbxExporter) existen en la biblioteca, pero la detección automática del formato FBX es no está conectada en scene.open() o scene.save(). Llamando scene.open('file.fbx') no invocará el importador FBX — el archivo pasará al fallback STL. Llamando scene.save('output.fbx', opts) no invocará el exportador FBX. La tabla de soporte de formatos anterior marca FBX como No* por esta razón. Use GLB o COLLADA para importación y exportación totalmente funcionales a través de scene.open() / scene.save().

COLLADA (DAE)

COLLADA es un formato de intercambio basado en XML compatible con una amplia gama de herramientas DCC (Blender, Maya, Cinema 4D). La biblioteca usa el xmldom dependencia para el análisis XML; se instala automáticamente con 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);

Los archivos COLLADA pueden contener metadatos de escala de unidades (<unit> elemento). La biblioteca aplica la conversión de unidades automáticamente al cargar.

Detección automática de formato

Al cargar desde una ruta de archivo, la biblioteca intenta la detección de formato a partir de números mágicos binarios antes de recurrir a la extensión del archivo. Esto significa que puedes cargar un archivo GLB llamado .bin o un archivo STL llamado .model sin especificar el formato explícitamente.

Al cargar desde un Buffer con scene.openFromBuffer(), la detección por número mágico es el mecanismo 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)`);

Formatos con números mágicos fiables: GLB (glTF), STL binario (encabezado de 80 bytes + recuento de triángulos), 3MF (ZIP magic PK). OBJ y COLLADA son basados en texto y se detectan a partir de la extensión del archivo o mediante la clase de opciones que pases.

Consejos

• OBJ admite tanto importación como exportación: al guardar como OBJ, el .mtl archivo de material se escribe automáticamente junto al .obj archivo.
• Utilice GLB para la entrega web: el formato binario autocontenido evita problemas de CORS con .bin archivos auxiliares y se carga más rápido en los renderizadores WebGL.
• Pase opciones específicas del formato: genérico scene.open(path) funciona para la mayoría de los formatos, pero pasar la clase de opciones del cargador habilita comportamientos específicos del formato, como la carga de materiales OBJ o la normalización de coordenadas STL.
• xmldom es necesario para COLLADA: se instala automáticamente. No lo añada a peerDependencies o intente eliminarlo; el lector COLLADA lo llama directamente.

Problemas comunes

Ver también

• Características y Funcionalidades: grafo de escena, malla, materiales, animación y APIs de matemáticas.
• Grafo de Escena: construcción y recorrido del árbol de nodos.
• Cómo crear un Mesh 3D programáticamente