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 jednej, spójnej 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 TypeScript-first API 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.

OBJ obsługuje zarówno import, jak i eksport. Ładuj za pomocą scene.open() i zapisz za pomocą scene.save('output.obj'), lub konwertuj do dowolnego innego obsługiwanego formatu, 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 dostawie 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 do druku 3D)

STL jest lingua franca druku 3D metodą 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ż zamiast tego 3MF (patrz niżej).

STL do glTF (skaner i 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 materiale ani teksturze, wynikowy plik glTF będzie zawierał wyłącznie geometrię. W razie potrzeby możesz programowo dołączyć materiały do węzłów sceny po załadowaniu.

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 wydruku 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, więc możesz przeglądać lub modyfikować poszczególne części przed zapisaniem.

Wzorzec konwersji wsadowej

Podczas przetwarzania katalogu plików, otocz każdą konwersję w a 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 zatrzymywania pętli. Zwrócona tablica ConversionResult obiektów, które można wykorzystać 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 załadowania, 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, i Mesh klas używanych w tych przykładach, zobacz strony referencyjne klas w tej dokumentacji.