Установка

Это руководство охватывает всё, что вам нужно для установки Aspose.3D FOSS для TypeScript и подтверждения его корректной работы перед тем, как вы напишете свой первый скрипт 3D‑обработки.

Требования

Убедитесь, что следующее установлено и находится на вашем PATH перед продолжением:

Чтобы проверить версии:

node --version   # v18.x.x or later
npm --version    # 7.x or later
npx tsc --version  # Version 5.x.x

Шаг 1: Создать проект (при необходимости)

Если вы добавляете Aspose.3D в существующий проект TypeScript, пропустите этот шаг и переходите сразу к Шагу 2.

Для нового проекта:

mkdir my-3d-project && cd my-3d-project
npm init -y
npm install -D typescript ts-node @types/node

Шаг 2: Установить @aspose/3d

npm install @aspose/3d

Это устанавливает пакет и его единственную транзитивную зависимость, xmldom, автоматически. Не требуются дополнительные системные пакеты, нативные аддоны или компиляторы. Установка считается завершённой, когда @aspose/3d появляется в вашем package.json в разделе dependencies.

Проверьте установку:

ls node_modules/@aspose/3d

Вы должны увидеть каталог пакета с package.json, файлами определений типов (.d.ts), и скомпилированным JavaScript.

Шаг 3: Настроить TypeScript

Добавьте или обновите tsconfig.json в корне вашего проекта со следующими настройками. Они необходимы для полной совместимости с определениями типов библиотеки и выводом CommonJS:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "moduleResolution": "node",
    "esModuleInterop": true,
    "strict": true,
    "outDir": "dist",
    "rootDir": "src"
  },
  "include": ["src/**/*.ts"],
  "exclude": ["node_modules", "dist"]
}

Ключевые настройки и почему они важны:

Шаг 4: Проверка установки

Создать src/verify.ts со следующим минимальным тестом импорта:

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

const scene = new Scene();
console.log('Aspose.3D FOSS for TypeScript is installed correctly.');
console.log('rootNode name:', scene.rootNode.name);

Скомпилируйте и запустите:

npx tsc
node dist/verify.js

Ожидаемый вывод:

Aspose.3D FOSS for TypeScript is installed correctly.
rootNode name:

Имя корневого узла по умолчанию — пустая строка — scene.rootNode создаётся без аргумента имени.

Если вы предпочитаете пропустить шаг компиляции во время разработки, запускайте напрямую с ts-node:

npx ts-node src/verify.ts

Шаг 5: Быстрый старт: загрузка сцены и вывод информации об узлах

Следующий скрипт загружает 3D‑файл и выводит имя и тип сущности каждого узла в сцене. Он работает с любым поддерживаемым форматом: OBJ, glTF, GLB, STL, 3MF, FBX или COLLADA.

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

function printNode(node: Node, depth: number = 0): void {
  const indent = '  '.repeat(depth);
  const entityType = node.entity ? node.entity.constructor.name : '(no entity)';
  console.log(`${indent}${node.name} [${entityType}]`);
  for (const child of node.childNodes) {
    printNode(child, depth + 1);
  }
}

const scene = new Scene();

// Replace 'model.obj' with any supported 3D file path.
// Format is detected automatically from binary magic numbers.
scene.open('model.obj');

console.log('Scene loaded. Node hierarchy:');
printNode(scene.rootNode);

Сохраните это как src/quickstart.ts и запустите его:

npx ts-node src/quickstart.ts

Для OBJ‑файла с одной сеткой под названием Cube, вывод будет выглядеть так:

Scene loaded. Node hierarchy:
 [(no entity)]
  Cube [Mesh]

У корневого узла пустое имя (выводится как пустой префикс). Дочерние узлы наследуют свои имена из загруженного файла.

Заметки о зависимостях

Aspose.3D FOSS for TypeScript имеет ровно одну runtime‑зависимость:

Вам не нужно устанавливать xmldom вручную. Он появится в вашем node_modules после основной команды установки. Нет нативных аддонов (.node файлы) и системные библиотеки не требуются.

Следующие шаги

Теперь, когда библиотека установлена и проверена:

• Прочитайте Руководство разработчика для полного обзора всех областей функций.
• См. Функции и возможности для получения подробностей о поддержке форматов, шаблонах графа сцены, API материалов и анимации, а также полных примеров кода на TypeScript.