Konwertowanie między formatami 3D w TypeScript przy użyciu Aspose.3D FOSS

Programiści Node.js pracujący z treściami 3D często muszą konwertować między formatami: narzędzie projektowe eksportuje OBJ, renderer internetowy oczekuje GLB, drukarka 3D wymaga STL, a pipeline produkcyjny używa 3MF. Obsługa tych konwersji przy użyciu jednego, spójnego API zmniejsza liczbę zewnętrznych narzędzi w pipeline i utrzymuje logikę konwersji w kodzie aplikacji, gdzie może być testowana i wersjonowana.

Ten @aspose/3d pakiet (v24.12.0, licencja MIT) zapewnia API zorientowane na TypeScript do odczytu i zapisu wszystkich głównych formatów 3D w Node.js. Ten przewodnik przechodzi przez najczęstsze przepływy konwersji.

Instalacja

npm install @aspose/3d

Wymagania: Node.js 18, 20 lub 22; TypeScript 5.0 lub nowszy. Jedyną zależnością w czasie wykonywania jest xmldom.

Obsługiwane formaty

Poniższa tabela wymienia formaty omówione w tym przewodniku oraz ich obsługę odczytu/zapisu.

Uwaga: OBJ jest tylko do importu (canExport: false). Aby przekonwertować zawartość OBJ na inny format, wczytaj go za pomocą scene.open() i zapisz do obsługiwanego formatu eksportu, takiego jak glTF, STL lub 3MF.

OBJ do GLB (dostawa w sieci)

Konwersja OBJ do binarnego glTF (GLB) jest najczęstszym przepływem w sieci. GLB to samodzielny pakiet binarny: tekstury, geometria i metadane w jednym pliku, co czyni go wydajnym przy dostarczaniu przez HTTP i bezpośrednim ładowaniu przez Three.js, Babylon.js oraz 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');

Format wyjściowy jest określany na podstawie rozszerzenia pliku. Użyj .glb do binarnego GLB lub .gltf do oddzielnego JSON + .bin układu.

OBJ do STL: przygotowanie modelu do druku 3D

STL jest lingua franca druku 3D FDM i SLA. Slicery takie jak PrusaSlicer, Bambu Studio i Chitubox akceptują STL. Konwersja z OBJ do STL jest prosta, ponieważ oba formaty przechowują siatki trójkątów.

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 nie przechowuje informacji o kolorze, materiale ani danych UV. Jeśli Twój plik OBJ używa grup materiałów, te informacje są pomijane podczas eksportu. Dla formatów druku zachowujących kolory, rozważ użycie 3MF (zobacz poniżej).

STL do glTF: od skanera lub wyjścia CAD do sieci

Skanery strukturalnego światła i eksportery CAD parametrycznego zazwyczaj generują STL. Konwersja do glTF udostępnia geometrię w przeglądarkach internetowych i platformach AR bez konieczności renderowania po stronie serwera.

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

Ponieważ STL nie zawiera informacji o materiałach ani teksturach, wynikowy plik glTF będzie zawierał wyłącznie geometrię. W razie potrzeby możesz programowo dołączać materiały do węzłów sceny po załadowaniu, jeśli to konieczne.

3MF to glTF (Manufacturing to Visualization)

Format 3D Manufacturing (3MF) jest coraz częściej używany w przepływach pracy druku addytywnego, ponieważ przechowuje kolory, materiały, drzewa komponentów oraz metadane druku razem z geometrią. Konwersja 3MF do glTF umożliwia dalszą wizualizację w narzędziach internetowych, zachowując strukturę sceny.

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() zachowuje hierarchię komponentów w scene.rootNode.childNodes, dzięki czemu możesz przeglądać lub modyfikować poszczególne części przed zapisaniem.

Wzorzec konwersji wsadowej

Podczas przetwarzania katalogu plików, owiń każdą konwersję w try/catch aby pojedynczy uszkodzony plik nie przerywał całej partii.

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

Powyższy wzorzec odczytuje każde obsługiwane rozszerzenie pliku z katalogu wejściowego, konwertuje do GLB i rejestruje wszelkie niepowodzenia bez przerywania pętli. Zwrócona tablica ConversionResult obiektów może być użyta do raportowania lub logiki ponownych prób.

Podsumowanie

@aspose/3d obejmuje pełen zakres potrzeb konwersji formatów w aplikacji Node.js TypeScript z konsekwentnym dwustopniowym API: scene.open() do wczytania, scene.save() do zapisu. Kluczowym ograniczeniem, które należy pamiętać, jest to, że klasy importera i eksportera FBX istnieją, ale automatyczne wykrywanie formatu nie jest jeszcze podłączone, więc pliki FBX nie mogą być wczytywane za pomocą scene.open().

Aby uzyskać więcej szczegółów na temat Scene, Node, oraz Mesh klas używanych w tych przykładach, zobacz strony referencyjne klas w tej dokumentacji.