Конвертиране между 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 е само за импортиране (canExport: false). За да конвертирате съдържанието на OBJ в друг формат, заредете го с scene.open() и запазете в поддържан експортен формат като 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 Manufacturing Format (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 класовете, използвани в тези примери, вижте страниците с референции за класове в тази документация.