Installazione

Questa guida copre tutto ciò di cui hai bisogno per installare Aspose.3D FOSS per TypeScript e confermare che funzioni correttamente prima di scrivere il tuo primo script di elaborazione 3D.

Prerequisiti

Assicurati che i seguenti siano installati e sul tuo PATH prima di procedere:

Per verificare le tue versioni:

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

Passo 1: Crea un progetto (se necessario)

Se stai aggiungendo Aspose.3D a un progetto TypeScript esistente, salta questo passo e vai direttamente al Passo 2.

Per un progetto nuovo:

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

Passo 2: Installa @aspose/3d

npm install @aspose/3d

Questo installa il pacchetto e la sua unica dipendenza transitiva, xmldom, automaticamente. Non sono richiesti pacchetti di sistema aggiuntivi, addon nativi o compilatori. L’installazione è completa quando @aspose/3d compare nel tuo package.json sotto dependencies.

Verifica l’installazione:

ls node_modules/@aspose/3d

Dovresti vedere la directory del pacchetto con package.json, file di definizione dei tipi (.d.ts), e JavaScript compilato.

Passo 3: Configura TypeScript

Aggiungi o aggiorna tsconfig.json nella radice del tuo progetto con le seguenti impostazioni. Queste sono necessarie per la piena compatibilità con le definizioni dei tipi della libreria e l’output CommonJS:

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

Impostazioni chiave e perché sono importanti:

Passo 4: Verifica l’installazione

Crea src/verify.ts con il seguente test di importazione minimale:

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 ed esegui:

npx tsc
node dist/verify.js

Output previsto:

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

Il nome del nodo radice è una stringa vuota per impostazione predefinita — scene.rootNode viene creato senza argomento di nome.

Se preferisci saltare il passaggio di compilazione durante lo sviluppo, esegui direttamente con ts-node:

npx ts-node src/verify.ts

Passo 5: Avvio rapido: carica una scena e stampa le informazioni dei nodi

Lo script seguente carica un file 3D e stampa il nome e il tipo di entità di ogni nodo nella scena. Funziona con qualsiasi formato supportato: 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);

Salva questo come src/quickstart.ts e eseguilo:

npx ts-node src/quickstart.ts

Per un file OBJ con una mesh denominata Cube, l’output avrà l’aspetto seguente:

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

Il nodo radice ha un nome vuoto (stampato come prefisso vuoto). I nodi figli ereditano i loro nomi dal file caricato.

Note sulle dipendenze

Aspose.3D FOSS for TypeScript ha esattamente una dipendenza a runtime:

Non è necessario installare xmldom manualmente. Apparirà nel tuo node_modules dopo il comando di installazione principale. Non ci sono addon nativi (.node file) e non sono richieste librerie di sistema.

Passi successivi

Ora che la libreria è installata e verificata:

• Leggi il Guida per sviluppatori per una panoramica completa di tutte le aree funzionali.
• Vedi Caratteristiche e funzionalità per i dettagli del supporto dei formati, i pattern del grafo di scena, le API di materiali e animazione, e esempi di codice TypeScript completi.