Конвертація між 3D-форматами в TypeScript за допомогою Aspose.3D FOSS

Розробникам Node.js, які працюють з 3D‑контентом, часто потрібно конвертувати між форматами: інструмент дизайну експортує OBJ, веб‑рендерер очікує GLB, 3D‑принтер вимагає STL, а виробничий конвеєр використовує 3MF. Обробка цих конвертацій за допомогою єдиного, послідовного API зменшує кількість зовнішніх інструментів у конвеєрі та зберігає логіку конвертації всередині коду застосунку, де її можна тестувати та версіонувати.

The @aspose/3d пакет (v24.12.0, MIT license) надає TypeScript-first API для читання та запису всіх основних 3D форматів у Node.js. Цей посібник проходить через найпоширеніші робочі процеси конвертації.

Встановлення

npm install @aspose/3d

Вимоги: Node.js 18, 20 або 22; TypeScript 5.0 або новіший. Єдина залежність під час виконання — 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 — це lingua franca 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 класи, використані в цих прикладах, дивіться сторінки довідки класів у цій документації.