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 ссылаются на материалы через sidecar .mtl файл. Загрузка материалов происходит включено по умолчанию (ObjLoadOptions.enableMaterials = true). Пропустить 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 пустоФормат использует одну корневую mesh, а не дочерние узлыДоступ scene.rootNode.entity непосредственно
openFromBuffer выбрасывает ошибку при работе с бинарным STLБуфер был неправильно нарезан (отсутствуют завершающие байты)Используйте полный readFileSync() вывод без нарезки
Массив анимационных клипов пуст после загрузки FBXFBX‑файл использует запечённые трансформации, а не клипыАнимация запекается по кадру; массив клипов будет пустым

См. также

 Русский