Aspose.3D FOSS
TypeScript
Посібник розробника
Loading Models

Завантаження 3D моделей

@aspose/3d надає два методи завантаження в Scene класі: open() для завантаження за шляхом до файлу та openFromBuffer() для даних у пам’яті. Визначення формату виконується автоматично за бінарними магічними числами або розширенням файлу, тому вам рідко потрібно явно вказувати формат джерела.

Завантаження за шляхом до файлу

Передайте рядок шляху до файлу у scene.open(). Бібліотека визначає формат за розширенням файлу і, для бінарних форматів, за магічними байтами:

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

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

console.log(`Root children: ${scene.rootNode.childNodes.length}`);
console.log(`Animation clips: ${scene.animationClips.length}`);

open() замінює будь-який існуючий вміст сцени. Якщо потрібно завантажити кілька файлів, створіть окремі Scene екземпляри.

Завантаження OBJ з матеріалами

OBJ‑файли посилаються на матеріали через допоміжний .mtl файл. Завантаження матеріалів увімкнено за замовчуванням (ObjLoadOptions.enableMaterials = true). Pass ObjLoadOptions для керування цим та іншими параметрами завантаження:

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

const scene = new Scene();
const options = new ObjLoadOptions();
options.enableMaterials = true;       // load the .mtl sidecar
options.flipCoordinateSystem = false; // keep original Y-up orientation
options.normalizeNormal = true;       // fix degenerate normals
options.scale = 1.0;                  // unit scale multiplier

scene.open('character.obj', options);

// Inspect materials on the first node
const first = scene.rootNode.childNodes[0];
if (first) {
    console.log(`Materials on ${first.name}: ${first.materials.length}`);
}

Завантаження з буфера

Використовуйте openFromBuffer() коли дані файлу вже знаходяться в пам’яті, наприклад, отримані через HTTP‑запит, BLOB у базі даних або витягнуті з zip‑архіву. Це дозволяє уникнути запису на диск:

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

const buffer: Buffer = fs.readFileSync('model.obj');
const scene = new Scene();
const options = new ObjLoadOptions();
options.enableMaterials = true;

scene.openFromBuffer(buffer, options);
console.log(`Loaded ${scene.rootNode.childNodes.length} root nodes`);

Для бінарних форматів (GLB, STL binary, 3MF) бібліотека читає магічні байти з буфера, щоб автоматично визначити формат, тому ви можете передати undefined як аргумент options:

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

const glbBuffer: Buffer = fs.readFileSync('model.glb');
const scene = new Scene();
scene.openFromBuffer(glbBuffer); // format auto-detected from GLB magic bytes

Завантаження через HTTP (Node.js 18+)

Отримайте віддалений ресурс і завантажте його, не торкаючись файлової системи:

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

async function loadFromUrl(url: string): Promise<Scene> {
    const response = await fetch(url);
    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    const arrayBuffer = await response.arrayBuffer();
    const buffer = Buffer.from(arrayBuffer);

    const scene = new Scene();
    scene.openFromBuffer(buffer);
    return scene;
}

const scene = await loadFromUrl('https://example.com/model.glb');
console.log(`Loaded scene: ${scene.rootNode.childNodes.length} root nodes`);

Перевірка завантаженої сцени

Після завантаження пройдіться по графу сцени, щоб перелічити вузли та визначити геометрію:

import { Scene, Mesh, Node } from '@aspose/3d';

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

function inspect(node: Node, depth: number = 0): void {
    const indent = '  '.repeat(depth);
    const entityType = node.entity ? node.entity.constructor.name : '(none)';
    console.log(`${indent}${node.name} [${entityType}]`);

    if (node.entity instanceof Mesh) {
        const mesh = node.entity as Mesh;
        console.log(`${indent}  vertices: ${mesh.controlPoints.length}, polygons: ${mesh.polygonCount}`);
    }

    for (const child of node.childNodes) {
        inspect(child, depth + 1);
    }
}

inspect(scene.rootNode);

Читання метаданих ресурсу

Це assetInfo властивість надає метадані рівня файлу:

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

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

const info = scene.assetInfo;
if (info) {
    console.log(`Creator: ${info.creator}`);
    console.log(`Unit name: ${info.unitName}`);
    console.log(`Unit scale: ${info.unitScaleFactor}`);
}

Не всі формати заповнюються assetInfo. FBX та COLLADA мають багаті метадані; OBJ і STL зазвичай їх не мають.

Довідник параметрів завантаження, специфічних для формату

ФорматКлас OptionsШлях імпортуКлючові параметри
OBJObjLoadOptions@aspose/3d/formats/objenableMaterials, flipCoordinateSystem, scale, normalizeNormal
glTF / GLB(не потрібно)N/AАвтоматично визначено; клас параметрів не потрібен
STLStlLoadOptions@aspose/3d/formats/stl(у поточній версії немає налаштовуваних параметрів)
FBXFbxLoadOptions@aspose/3d/formats/fbx(у поточній версії немає налаштовуваних параметрів)
COLLADAColladaLoadOptions@aspose/3d/formats/collada(немає налаштовуваних параметрів у поточній версії)
3MF(не потрібно)N/AАвтоматично виявлено

Типові помилки завантаження

СимптомПричинаВиправлення
Error: Cannot find module '@aspose/3d/formats/obj'moduleResolution не встановлено в nodeДодати "moduleResolution": "node" до tsconfig.json
Порожній список вузлів після завантаження OBJ.mtl sidecar відсутній або enableMaterials не встановленоВстановити options.enableMaterials = true і переконайтеся .mtl знаходиться в тому ж каталозі
Сцена завантажується, але rootNode.childNodes порожняФормат використовує один кореневий меш, а не дочірні вузлиДоступ scene.rootNode.entity безпосередньо
openFromBuffer викидає з бінарним STLБуфер був розрізаний неправильно (відсутні кінцеві байти)Використовуйте повний readFileSync() вивід без розрізання
Масив анімаційних кліпів порожній після завантаження FBXФайл FBX використовує запечені трансформації, а не кліпиАнімація запікається по кадру; масив кліпів буде порожнім

Див. також

 Українська