Installation

Esta guía cubre todo lo que necesitas para instalar Aspose.3D FOSS para TypeScript y confirmar que funciona correctamente antes de escribir tu primer script de procesamiento 3D.

Requisitos previos

Asegúrese de que lo siguiente esté instalado y en su PATH antes de continuar:

Para comprobar tus versiones:

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

Paso 1: Crear un proyecto (si es necesario)

Si estás añadiendo Aspose.3D a un proyecto TypeScript existente, omite este paso y ve directamente al Paso 2.

Para un proyecto nuevo:

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

Paso 2: Instalar @aspose/3d

npm install @aspose/3d

Esto instala el paquete y su única dependencia transitiva, xmldom, automáticamente. No se requieren paquetes del sistema adicionales, complementos nativos ni compiladores. La instalación se completa cuando @aspose/3d aparece en su package.json en dependencies.

Verifica la instalación:

ls node_modules/@aspose/3d

Deberías ver el directorio del paquete con package.json, archivos de definición de tipos (.d.ts), y JavaScript compilado.

Paso 3: Configurar TypeScript

Añade o actualiza tsconfig.json en la raíz de tu proyecto con la siguiente configuración. Estos son necesarios para una compatibilidad total con las definiciones de tipos de la biblioteca y la salida CommonJS:

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

Configuraciones clave y por qué son importantes:

Paso 4: Verificar la instalación

Crear src/verify.ts con la siguiente prueba mínima de importación:

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

Compila y ejecuta:

npx tsc
node dist/verify.js

Expected output:

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

El nombre del nodo raíz es una cadena vacía por defecto — scene.rootNode se crea sin argumento de nombre.

Si prefieres omitir el paso de compilación durante el desarrollo, ejecuta directamente con ts-node:

npx ts-node src/verify.ts

Paso 5: Inicio rápido: cargar una escena e imprimir información de los nodos

El siguiente script carga un archivo 3D e imprime el nombre y el tipo de entidad de cada nodo en la escena. Funciona con cualquier formato compatible: OBJ, glTF, GLB, STL, 3MF, FBX o 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);

Guárdalo como src/quickstart.ts y ejecútalo:

npx ts-node src/quickstart.ts

Para un archivo OBJ con una malla llamada Cube, la salida se verá así:

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

El nodo raíz tiene un nombre vacío (impreso como un prefijo en blanco). Los nodos hijos heredan sus nombres del archivo cargado.

Notas de dependencias

Aspose.3D FOSS for TypeScript tiene exactamente una dependencia en tiempo de ejecución:

No necesitas instalar xmldom manualmente. Aparecerá en tu node_modules después del comando principal de instalación. No hay complementos nativos (.node archivos) y sin bibliotecas del sistema requeridas.

Próximos pasos

Ahora que la biblioteca está instalada y verificada:

• Lea el Guía del desarrollador para un recorrido completo de todas las áreas de funciones.
• Vea Características y funcionalidades para detalles de soporte de formatos, patrones de grafo de escena, APIs de material y animación, y ejemplos completos de código TypeScript.