Преобразование между 3D-форматами в TypeScript с помощью Aspose.3D FOSS

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

Эта @aspose/3d пакет (v24.12.0, лицензия MIT) предоставляет API, ориентированное на TypeScript, для чтения и записи всех основных 3D‑форматов в Node.js. Это руководство проходит через наиболее распространённые рабочие процессы конвертации.

Установка

npm install @aspose/3d

Требования: Node.js 18, 20 или 22; TypeScript 5.0 или новее. Единственная зависимость во время выполнения — 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 — 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 Manufacturing (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 классы, используемые в этих примерах, см. страницы справочника классов в этой документации.