Конвертиране между 3D формати в TypeScript с Aspose.3D FOSS

Node.js разработчиците, работещи с 3D съдържание, често се налага да конвертират между формати: дизайнерски инструмент експортира OBJ, уеб рендерерът изисква GLB, 3D принтерът се нуждае от STL, а производственият процес използва 3MF. Обработването на тези конверсии с единна, последователна API намалява броя на външните инструменти в конвейера и запазва логиката за конверсия в кода на приложението, където може да бъде тествана и версиирана.

Това @aspose/3d Пакетът (v24.12.0, MIT лиценз) предоставя TypeScript‑first API за четене и записване на всички основни 3D формати в Node.js. Това ръководство обхваща най-често срещаните работни процеси за конвертиране.

Инсталация

npm install @aspose/3d

Изисквания: Node.js 18, 20 или 22; TypeScript 5.0 или по-нов. Единствената runtime зависимост е xmldom.

Поддържани формати

Таблицата по-долу изброява форматите, разгледани в това ръководство, и тяхната поддръжка за четене/писане.

OBJ поддържа както импортиране, така и експортиране. Заредете с scene.open() и запазете с scene.save('output.obj'), или конвертирайте към друг поддържан формат като glTF, STL или 3MF.

OBJ към GLB (Уеб доставка)

Конвертирането на OBJ към бинарен glTF (GLB) е най-често срещаният уеб работен процес. GLB е самостоятелен бинарен пакет: текстури, геометрия и метаданни в един файл, което го прави ефективен за HTTP доставка и директно зареждане от Three.js, Babylon.js и 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');

Изходният формат се определя от разширението на файла. Използвайте .glb за бинарен GLB или .gltf за отделния JSON + .bin оформление.

OBJ към STL (Подготовка за 3D печат)

STL е общият език на FDM и SLA 3D печат. Слайсъри като PrusaSlicer, Bambu Studio и Chitubox приемат STL. Конвертирането от OBJ към STL е просто, тъй като и двата формата съхраняват триъгълни мрежи.

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 не съхранява цветове, материали или UV данни. Ако вашият OBJ файл използва групи материали, тази информация се премахва при експорта. За формати за печат, запазващи цветовете, обмислете 3MF вместо това (вижте по-долу).

STL към glTF (Скенер и CAD към уеб)

Скенери с структуриран светлинен метод и параметрични CAD експортери обикновено генерират STL. Конвертирането към glTF прави геометрията достъпна в уеб базирани прегледачи и AR платформи без стъпка за сървърно рендериране.

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

Тъй като STL не съдържа информация за материали или текстури, полученият glTF файл ще съдържа само геометрия. При нужда можете програмено да прикачите материали към възлите на сцената след зареждане.

3MF to glTF (Manufacturing to Visualization)

Форматът за 3D производство (3MF) се използва все по-често в работните потоци за добавъчно производство, тъй като съхранява цвят, материали, дървета на компоненти и метаданни за печат заедно с геометрията. Преобразуването на 3MF към glTF позволява последваща визуализация в уеб инструменти, като същевременно запазва структурата на сцената.

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() запазва йерархията на компонентите в scene.rootNode.childNodes, така че можете да инспектирате или манипулирате отделни части преди запазване.

Шаблон за пакетно преобразуване

При обработка на директория с файлове, обвийте всяка конверсия в try/catch за да един повреден файл не прекъсне цялата партида.

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

Горният шаблон чете всяко поддържано файлово разширение от входна директория, конвертира към GLB и записва всички неуспехи, без да спира цикъла. Върнатият масив от ConversionResult обекти могат да се използват за отчитане или логика за повторен опит.

Заключение

@aspose/3d обхваща пълния спектър от нужди за конверсия на формати в Node.js TypeScript приложение с последователен двустепенен API: scene.open() за зареждане, scene.save() за записване. Ключовото ограничение, което трябва да се помни, е, че класовете за импортиране и експортиране на FBX съществуват, но автоматичното разпознаване на формата все още не е включено, така че FBX файловете не могат да се зареждат чрез scene.open().

За повече подробности относно Scene, Node, и Mesh класове, използвани в тези примери, вижте страниците с референция за класове в тази документация.