Поддержка 3D-форматов

Aspose.3D FOSS для TypeScript читает и записывает семь основных 3D форматов файлов. Определение формата происходит автоматически при загрузке: библиотека проверяет бинарные магические числа, поэтому вам не нужно указывать исходный формат. Классы параметров, специфичных для формата, импортируются из подпутей пакета. @aspose/3d пакет.

Поддерживаемые форматы

OBJ (Wavefront)

OBJ поддерживает как импорт, так и экспорт в @aspose/3d. При сохранении в формате OBJ библиотека материалов (.mtl) записывается автоматически рядом с .obj файл. Используйте ObjLoadOptions для управления загрузкой материалов и поведением системы координат.

Ключевые параметры для ObjLoadOptions:

import { Scene } from '@aspose/3d';
import { ObjLoadOptions } from '@aspose/3d/formats/obj';

const scene = new Scene();
const opts = new ObjLoadOptions();
opts.enableMaterials = true;
opts.normalizeNormal = true;

scene.open('model.obj', opts);
console.log(`Loaded ${scene.rootNode.childNodes.length} top-level node(s)`);

Чтобы преобразовать OBJ в любой записываемый формат, загрузите его и вызовите scene.save() с классом целевого формата.

glTF и GLB

glTF 2.0 — рекомендуемый формат обмена для веба и использования в игровых движках. Библиотека использует тот же GltfFormat класс для обоих .gltf (JSON + sidecar) и .glb (binary, self-contained) вывод. Переключайтесь между ними с помощью GltfSaveOptions.binaryMode.

Загрузка glTF или GLB:

import { Scene } from '@aspose/3d';
import { GltfLoadOptions } from '@aspose/3d/formats/gltf';

const scene = new Scene();
scene.open('model.gltf', new GltfLoadOptions());
// or
scene.open('model.glb');  // format detected from magic bytes

Экспортировать как JSON glTF (.gltf + .bin):

import { Scene } from '@aspose/3d';
import { GltfSaveOptions, GltfFormat } from '@aspose/3d/formats/gltf';

const scene = new Scene();
scene.open('input.fbx');

const opts = new GltfSaveOptions();
opts.binaryMode = false;  // produces output.gltf + output.bin
scene.save('output.gltf', GltfFormat.getInstance(), opts);

Экспортировать как бинарный GLB (.glb):

import { Scene } from '@aspose/3d';
import { GltfSaveOptions, GltfFormat } from '@aspose/3d/formats/gltf';

const scene = new Scene();
scene.open('input.obj');

const opts = new GltfSaveOptions();
opts.binaryMode = true;  // single self-contained file
scene.save('output.glb', GltfFormat.getInstance(), opts);

Использовать binaryMode = true для доставки производственных ресурсов. Один .glb загружается быстрее в браузерах и движках, чем split text + binary pair.

STL

STL — это формат триангулированной сетки, используемый в CAD и 3D печати. Поддерживаются как бинарный, так и ASCII STL для ввода и вывода. StlSaveOptions.binaryMode управляет тем, будет ли вывод бинарным (компактным) или ASCII (читаемым человеком).

import { Scene } from '@aspose/3d';
import { StlLoadOptions, StlSaveOptions } from '@aspose/3d/formats/stl';

const scene = new Scene();
scene.open('model.stl', new StlLoadOptions());

// Export as binary STL (default, compact)
const binaryOpts = new StlSaveOptions();
binaryOpts.binaryMode = true;
scene.save('output_binary.stl', binaryOpts);

// Export as ASCII STL (human-readable)
const asciiOpts = new StlSaveOptions();
asciiOpts.binaryMode = false;
scene.save('output_ascii.stl', asciiOpts);

STL сохраняет только триангулированную геометрию и нормали вершин. Данные о материалах и UV не сохраняются в STL.

3MF (3D Manufacturing Format)

3MF is an XML-based format designed for additive manufacturing. It supports color and material metadata alongside geometry. Use it when exchanging files with 3D printing slicers or manufacturing workflows.

import { Scene } from '@aspose/3d';
import { ThreeMfSaveOptions } from '@aspose/3d/formats/3mf';

const scene = new Scene();
scene.open('model.3mf');

// Re-export as 3MF
scene.save('output.3mf', new ThreeMfSaveOptions());

3MF files are ZIP archives internally. The library handles archive creation and extraction automatically.

FBX

Предупреждение: классы импортёра и экспортёра FBX (FbxImporter, FbxExporter) существуют в библиотеке, но автоматическое определение формата FBX является не подключено в scene.open() или scene.save(). Вызов scene.open('file.fbx') не вызовет импортёр FBX — файл будет передан в резервный STL. Вызов scene.save('output.fbx', opts) не вызовет экспортёр FBX. Таблица поддержки форматов выше помечает FBX как No* по этой причине. Используйте GLB или COLLADA для полностью функционального импорта и экспорта через scene.open() / scene.save().

COLLADA (DAE)

COLLADA — это основанный на XML формат обмена, поддерживаемый широким спектром DCC‑инструментов (Blender, Maya, Cinema 4D). Библиотека использует xmldom зависимость для разбора XML; она устанавливается автоматически вместе с npm install @aspose/3d.

import { Scene } from '@aspose/3d';
import { ColladaSaveOptions } from '@aspose/3d/formats/collada';

const scene = new Scene();
scene.open('model.dae');

// Re-export as COLLADA
const saveOpts = new ColladaSaveOptions();
scene.save('output.dae', saveOpts);

Файлы COLLADA могут содержать метаданные масштабирования единиц (<unit> элемент). Библиотека автоматически применяет преобразование единиц при загрузке.

Автоматическое определение формата

При загрузке из пути к файлу библиотека пытается определить формат по бинарным магическим числам, прежде чем использовать расширение файла. Это означает, что вы можете загрузить файл GLB с именем .bin или файл STL с именем .model не указывая формат явно.

При загрузке из Buffer с scene.openFromBuffer(), magic-number detection является основным механизмом:

import { Scene } from '@aspose/3d';
import * as fs from 'fs';

const buffer = fs.readFileSync('model.glb');
const scene = new Scene();
scene.openFromBuffer(buffer);  // format detected from magic bytes: 'glTF'

console.log(`Root has ${scene.rootNode.childNodes.length} child node(s)`);

Форматы с надёжными магическими числами: GLB (glTF), STL binary (80‑байтовый заголовок + количество треугольников), 3MF (ZIP magic PK). OBJ и COLLADA являются текстовыми и определяются по расширению файла или по переданному классу параметров.

Советы

• OBJ поддерживает как импорт, так и экспорт: при сохранении в OBJ, .mtl файл материала записывается автоматически рядом с .obj файл.
• Используйте GLB для веб‑доставки: самодостаточный бинарный формат избегает проблем CORS с .bin sidecars и загружается быстрее в WebGL‑рендерерах.
• Передайте параметры, специфичные для формата: универсальный scene.open(path) работает для большинства форматов, но передача класса параметров загрузчика включает специфическое для формата поведение, такое как загрузка материалов OBJ или нормализация координат STL.
• xmldom требуется для COLLADA: это устанавливается автоматически. Не добавляйте его в peerDependencies или попытайтесь удалить его; читатель COLLADA вызывает его напрямую.

Распространённые проблемы

См. также

• Функции и возможности: граф сцены, меш, материалы, анимация и математические API.
• Граф сцены: построение и обход дерева узлов.
• Как программно построить 3D Mesh