Installation

Ce guide couvre tout ce dont vous avez besoin pour installer Aspose.3D FOSS pour TypeScript et confirmer qu’il fonctionne correctement avant d’écrire votre premier script de traitement 3D.

Prérequis

Assurez-vous que les éléments suivants sont installés et sur votre PATH avant de continuer :

Pour vérifier vos versions :

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

Étape 1 : Créer un projet (si nécessaire)

Si vous ajoutez Aspose.3D à un projet TypeScript existant, passez cette étape et allez directement à l’étape 2.

Pour un nouveau projet :

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

Étape 2 : Installer @aspose/3d

npm install @aspose/3d

Cela installe le paquet et sa seule dépendance transitive, xmldom, automatiquement. Aucun paquet système supplémentaire, module natif ou compilateur n’est requis. L’installation est terminée lorsque @aspose/3d apparaît dans votre package.json sous dependencies.

Vérifiez l’installation :

ls node_modules/@aspose/3d

Vous devriez voir le répertoire du paquet avec package.json, des fichiers de définition de type (.d.ts), et du JavaScript compilé.

Étape 3 : Configurer TypeScript

Ajoutez ou mettez à jour tsconfig.json dans la racine de votre projet avec les paramètres suivants. Ceux-ci sont nécessaires pour une compatibilité totale avec les définitions de type de la bibliothèque et la sortie CommonJS :

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

Paramètres clés et pourquoi ils sont importants :

Étape 4 : Vérifier l’installation

Créer src/verify.ts avec le test d’importation minimal suivant :

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

Compilez et exécutez :

npx tsc
node dist/verify.js

Expected output:

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

Le nom du nœud racine est une chaîne vide par défaut — scene.rootNode est créé sans argument de nom.

Si vous préférez sauter l’étape de compilation pendant le développement, exécutez directement avec ts-node:

npx ts-node src/verify.ts

Étape 5 : Démarrage rapide : charger une scène et afficher les informations des nœuds

Le script suivant charge un fichier 3D et affiche le nom ainsi que le type d’entité de chaque nœud de la scène. Il fonctionne avec n’importe quel format pris en charge : 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);

Enregistrez ceci sous src/quickstart.ts et exécutez‑le :

npx ts-node src/quickstart.ts

Pour un fichier OBJ contenant un seul maillage nommé Cube, la sortie ressemblera à :

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

Le nœud racine a un nom vide (affiché comme un préfixe vide). Les nœuds enfants héritent de leurs noms du fichier chargé.

Notes sur les dépendances

Aspose.3D FOSS for TypeScript a exactement une dépendance d’exécution :

Vous n’avez pas besoin d’installer xmldom manuellement. Il apparaîtra dans votre node_modules après la commande d’installation principale. Il n’existe aucun module natif (.node fichiers) et aucune bibliothèque système requise.

Étapes suivantes

Maintenant que la bibliothèque est installée et vérifiée :

• Lisez le Guide du développeur pour un guide complet de toutes les zones de fonctionnalités.
• Voir Fonctionnalités et Capacités pour les détails de prise en charge des formats, les modèles de graphe de scène, les API de matériaux et d’animation, ainsi que des exemples de code TypeScript complets.