Instalação

Este guia cobre tudo o que você precisa para instalar Aspose.3D FOSS para TypeScript e confirmar que está funcionando corretamente antes de escrever seu primeiro script de processamento 3D.

Pré‑requisitos

Certifique-se de que o seguinte esteja instalado e em seu PATH antes de prosseguir:

Para verificar suas versões:

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

Etapa 1: Criar um Projeto (se necessário)

Se você estiver adicionando Aspose.3D a um projeto TypeScript existente, pule esta etapa e vá diretamente para a Etapa 2.

Para um projeto novo:

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

Etapa 2: Instalar @aspose/3d

npm install @aspose/3d

Isso instala o pacote e sua única dependência transitiva, xmldom, automaticamente. Nenhum pacote de sistema adicional, complementos nativos ou compiladores são necessários. A instalação está completa quando @aspose/3d aparece em seu package.json em dependencies.

Verifique a instalação:

ls node_modules/@aspose/3d

Você deve ver o diretório do pacote com package.json, arquivos de definição de tipos (.d.ts), e JavaScript compilado.

Etapa 3: Configurar o TypeScript

Adicione ou atualize tsconfig.json na raiz do seu projeto com as seguintes configurações. Estas são necessárias para total compatibilidade com as definições de tipo da biblioteca e a saída CommonJS:

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

Configurações principais e por que são importantes:

Etapa 4: Verificar a Instalação

Criar src/verify.ts com o seguinte teste mínimo de importação:

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

Compile e execute:

npx tsc
node dist/verify.js

Saída esperada:

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

O nome do nó raiz é uma string vazia por padrão — scene.rootNode é criado sem argumento de nome.

Se preferir pular a etapa de compilação durante o desenvolvimento, execute diretamente com ts-node:

npx ts-node src/verify.ts

Etapa 5: Início Rápido: Carregar uma Cena e Imprimir Informações do Nó

O script a seguir carrega um arquivo 3D e imprime o nome e o tipo de entidade de cada nó na cena. Ele funciona com qualquer formato suportado: OBJ, glTF, GLB, STL, 3MF, FBX ou 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);

Salve isso como src/quickstart.ts e execute-o:

npx ts-node src/quickstart.ts

Para um arquivo OBJ com uma malha chamada Cube, a saída será assim:

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

O nó raiz tem um nome vazio (impresso como um prefixo em branco). Os nós filhos herdam seus nomes do arquivo carregado.

Observações de Dependência

Aspose.3D FOSS for TypeScript tem exatamente uma dependência em tempo de execução:

Você não precisa instalar xmldom manualmente. Ele aparecerá em seu node_modules após o comando principal de instalação. Não há complementos nativos (.node arquivos) e sem necessidade de bibliotecas do sistema.

Próximos Passos

Agora que a biblioteca está instalada e verificada:

• Leia o Guia do Desenvolvedor para um guia completo de todas as áreas de recursos.
• Veja Recursos e Funcionalidades para detalhes de suporte a formatos, padrões de grafo de cena, APIs de material e animação, e exemplos completos de código TypeScript.