Convertint entre formats 3D a TypeScript amb Aspose.3D FOSS

Els desenvolupadors de Node.js que treballen amb contingut 3D sovint necessiten convertir entre formats: una eina de disseny exporta OBJ, un renderitzador web espera GLB, una impressora 3D requereix STL i una cadena de fabricació utilitza 3MF. Gestionar aquestes conversions amb una API única i coherent redueix el nombre d’eines externes en una cadena i manté la lògica de conversió dins del codi de l’aplicació, on pot ser provada i versionada.

El @aspose/3d El paquet (v24.12.0, llicència MIT) ofereix una API centrada en TypeScript per llegir i escriure tots els principals formats 3D a Node.js. Aquesta guia recorre els fluxos de treball de conversió més comuns.

Instal·lació

npm install @aspose/3d

Requisits: Node.js 18, 20 o 22; TypeScript 5.0 o posterior. L’única dependència d’execució és xmldom.

Formats compatibles

La taula següent enumera els formats coberts en aquesta guia i el seu suport de lectura/escriptura.

Nota: OBJ és només d’importació (canExport: false). Per convertir el contingut OBJ a un altre format, carregueu-lo amb scene.open() i deseu-lo a un format d’exportació compatible com glTF, STL o 3MF.

OBJ a GLB (Entrega web)

Convertir OBJ a glTF binari (GLB) és el flux de treball web més comú. GLB és un paquet binari autònom: textures, geometria i metadades en un únic fitxer, cosa que el fa eficient per a la entrega HTTP i la càrrega directa per Three.js, Babylon.js i model-viewer.

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

function convertObjToGlb(inputPath: string, outputPath: string): void {
  const scene = new Scene();
  scene.open(inputPath);
  scene.save(outputPath);  // extension '.glb' selects binary GLB format
  console.log(`Converted ${inputPath} -> ${outputPath}`);
}

convertObjToGlb('model.obj', 'model.glb');

El format de sortida s’infereix a partir de l’extensió del fitxer. Utilitzeu .glb per a GLB binari o .gltf per al JSON separat + .bin disposició.

OBJ a STL: Preparar un model per a impressió 3D

STL és la llengua franca de la impressió 3D FDM i SLA. Talladors com PrusaSlicer, Bambu Studio i Chitubox accepten STL. Convertir d’OBJ a STL és senzill perquè ambdós formats emmagatzemen malles de triangles.

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

function convertObjToStl(inputPath: string, outputPath: string): void {
  const scene = new Scene();
  scene.open(inputPath);
  scene.save(outputPath);  // extension '.stl' selects STL format
  console.log(`STL written to ${outputPath}`);
}

convertObjToStl('part.obj', 'part.stl');

STL no emmagatzema color, material ni dades UV. Si el vostre fitxer OBJ utilitza grups de material, aquesta informació es perd durant l’exportació. Per a formats d’impressió que conserven el color, considereu 3MF en el seu lloc (vegeu a continuació).

STL a glTF: Des de l’escàner o sortida CAD al web

Els escàners de llum estructurada i els exportadors CAD paramètrics solen generar STL. Convertir a glTF fa que la geometria sigui accessible en visualitzadors web i plataformes AR sense necessitat d’un pas de renderització al servidor.

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

function convertStlToGltf(inputPath: string, outputPath: string): void {
  const scene = new Scene();
  scene.open(inputPath);
  // extension '.gltf' saves as JSON + .bin sidecar
  scene.save(outputPath);
  console.log(`glTF written to ${outputPath}`);
}

convertStlToGltf('scan_output.stl', 'scan_output.gltf');

Com que STL no conté informació de material ni de textura, el fitxer glTF resultant només contindrà geometria. Podeu adjuntar materials de manera programàtica als nodes de l’escena després de carregar-lo, si cal.

3MF to glTF (Manufacturing to Visualization)

El Format de Fabricació 3D (3MF) s’utilitza cada vegada més en fluxos de treball d’impressió additiva perquè emmagatzema color, materials, arbres de components i metadades d’impressió juntament amb la geometria. Convertir 3MF a glTF permet la visualització posterior en eines web mantenint l’estructura de l’escena.

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

function convert3mfToGlb(inputPath: string, outputPath: string): void {
  const scene = new Scene();
  scene.open(inputPath);
  scene.save(outputPath);  // extension '.glb' selects binary GLB format
  console.log(`3MF -> GLB: ${outputPath}`);
}

convert3mfToGlb('assembly.3mf', 'assembly.glb');

3MF files often contain multi-component assemblies. The scene graph produced by scene.open() preserva la jerarquia de components a scene.rootNode.childNodes, de manera que podeu inspeccionar o manipular les parts individuals abans de desar.

Patró de conversió per lots

Quan es processa un directori de fitxers, embolica cada conversió en un try/catch de manera que un únic fitxer corrupte no interrompi tot el lot.

import { Scene } from '@aspose/3d';
import { readdirSync } from 'fs';
import { join, basename, extname } from 'path';

interface ConversionResult {
  input: string;
  output: string;
  success: boolean;
  error?: string;
}

function batchConvertToGlb(
  inputDir: string,
  outputDir: string,
  extensions: string[] = ['.obj', '.stl', '.3mf', '.dae']  // .fbx excluded: format auto-detection not wired
): ConversionResult[] {
  const results: ConversionResult[] = [];

  const files = readdirSync(inputDir).filter((f) =>
    extensions.includes(extname(f).toLowerCase())
  );

  for (const file of files) {
    const inputPath = join(inputDir, file);
    const outputPath = join(outputDir, basename(file, extname(file)) + '.glb');

    try {
      const scene = new Scene();
      scene.open(inputPath);
      scene.save(outputPath);  // extension '.glb' infers GLB format
      results.push({ input: inputPath, output: outputPath, success: true });
    } catch (err) {
      const message = err instanceof Error ? err.message : String(err);
      results.push({ input: inputPath, output: outputPath, success: false, error: message });
      console.error(`Failed to convert ${file}: ${message}`);
    }
  }

  const succeeded = results.filter((r) => r.success).length;
  console.log(`Batch complete: ${succeeded}/${results.length} files converted.`);
  return results;
}

// Usage
batchConvertToGlb('./input', './output');

El patró anterior llegeix cada extensió de fitxer compatible d’un directori d’entrada, converteix a GLB i registra qualsevol error sense aturar el bucle. La matriu retornada de ConversionResult objectes es poden utilitzar per a informes o lògica de reintents.

Conclusió

@aspose/3d cobreix tot l’abast de les necessitats de conversió de formats en una aplicació Node.js TypeScript amb una API de dos passos consistent: scene.open() per carregar, scene.save() per escriure. La restricció clau a recordar és que les classes d’importador i exportador FBX existeixen però la detecció automàtica de formats encara no està implementada, de manera que els fitxers FBX no es poden carregar a través de scene.open().

Per a més detalls sobre el Scene, Node, i Mesh classes utilitzades en aquests exemples, consulteu les pàgines de referència de classes en aquesta documentació.