Підтримка 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);

Експортувати як binary 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 завантажується швидше в браузерах та рушіях, ніж розділена пара text + binary.

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 є основним механізмом:

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

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

Поради

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

Поширені проблеми

Див. також

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