@xingwangzhe/tags-cloud : Le moteur de nuage de tags 3D multimodal basé sur les mathématiques pures

GitHub : xingwangzhe/tags-cloud · Demo : tagscloud.needhelp.icu · npm : @xingwangzhe/tags-cloud · License : MIT · Version : v0.9.0

1. Introduction : Repenser le nuage de tags 3D pour le web moderne

Le nuage de tags est un pilier de la visualisation web depuis plus de deux décennies, passant de simples listes de mots pondérées à des expériences tridimensionnelles immersives qui captivent les utilisateurs et transforment des collections de textes banales en sculptures spatiales interactives. Parmi les contributions les plus influentes de cette évolution figure cong-min/TagCloud, une bibliothèque JavaScript légère qui a démontré comment une sphère d’étiquettes textuelles en rotation pouvait être réalisée avec un minimum de frais généraux et zéro dépendance externe. Avec 390 étoiles et 93 forks sur GitHub, le TagCloud original a établi un modèle de conception que d’innombrables développeurs ont adopté pour les sites portfolio, les vitrines de compétences et les tableaux de bord de visualisation de données. Son innovation principale résidait dans la preuve que les nuages de tags 3D n’ont pas besoin de s’appuyer sur des frameworks WebGL lourds ou des moteurs de rendu externes ; au lieu de cela, des calculs trigonométriques simples combinés à un positionnement DOM minutieux pouvaient produire des résultats visuels étonnamment convaincants.

Voici @xingwangzhe/tags-cloud — une réinvention complète du concept de nuage de tags 3D qui préserve l’élégance mathématique de son prédécesseur tout en élargissant considérablement ses capacités, en modernisant son architecture et en repoussant les limites de ce qu’un nuage de tags peut afficher. Ce n’est pas simplement un fork ou un ajout de fonctionnalités ; cela représente un changement architectural fondamental, passant d’un moteur de rendu textuel et lourd en DOM à un moteur multimodal capable d’afficher du texte, des images, des graphiques SVG, du HTML arbitraire, des éléments vidéo et même des Web Components complets — le tout tournant ensemble dans un espace tridimensionnel mathématiquement précis. La bibliothèque atteint cette polyvalence tout en maintenant une empreinte extrêmement compacte d’environ 3KB gzippé, sans aucune dépendance d’exécution, et construite avec une chaîne d’outils moderne comprenant Bun comme environnement d’exécution JavaScript, Vite comme bundler, et TypeScript pour une sécurité de type totale dans l’ensemble du code.

Le slogan du projet — « nuage de tags 3D multimodal · moteur mathématique pur » — résume sa double identité. D’une part, c’est une bibliothèque de composants d’interface pratique que les développeurs peuvent intégrer dans n’importe quel projet web pour créer des sphères de tags visuellement frappantes. D’autre part, c’est un moteur mathématique qui décompose le problème complexe du rendu de nuage de tags 3D en trois opérations géométriques pures, déterministes et magnifiquement séparables : la distribution de la sphère de Fibonacci pour le positionnement initial, la multiplication de matrices de rotation pour la transformation spatiale, et la projection perspective pour le rendu 2D conscient de la profondeur. Chacune de ces opérations est implémentée dans son propre module dédié dans le répertoire src/core/, rendant le code non seulement hautement maintenable mais aussi une excellente ressource pédagogique pour quiconque cherche à comprendre les mathématiques derrière l’infographie 3D sans la complexité obscurcissante d’un pipeline de rendu complet.

Les sections suivantes offrent une analyse technique complète de chaque aspect de @xingwangzhe/tags-cloud, depuis l’algorithme de distribution de sphère basé sur le nombre d’or jusqu’au modèle d’interaction arcball inspiré des quaternions, en passant par l’architecture de rendu double Canvas/DOM et les considérations de conception responsive qui le rendent parfaitement fonctionnel sur ordinateur et mobile. Que vous soyez un développeur évaluant cette bibliothèque pour votre prochain projet, un programmeur graphique intéressé par les techniques 3D légères, ou un mathématicien curieux des applications réelles du réseau de Fibonacci, cet article propose des explications détaillées, des dérivations mathématiques, des diagrammes d’architecture et des exemples de code annotés pour éclairer chaque facette de cette remarquable pièce de génie logiciel.

2. Les fondations mathématiques : Trois piliers du rendu 3D

Au cœur de @xingwangzhe/tags-cloud se trouve un trio d’opérations mathématiques qui, composées ensemble, transforment une liste abstraite d’éléments de contenu en une sphère rotative visuellement cohérente. Ces opérations — distribution, rotation et projection — sont implémentées dans trois modules dédiés sous src/core/, chacun responsable d’une seule transformation géométrique. Cette séparation des préoccupations n’est pas simplement un choix architectural ; elle reflète la structure fondamentale des pipelines d’infographie 3D, où la génération de sommets, la transformation de modèle et la projection de caméra sont des étapes distinctes qui peuvent être indépendamment optimisées, testées et comprises.

flowchart LR
    subgraph Input["📥 Couche d'entrée"]
        TAGS["TagItem[]
(text | image | SVG | HTML | video | element)"]
        OPTS["TagCloudOptions
(radius, spin, colors, callbacks)"]
    end

    subgraph CoreEngine["⚙️ Moteur mathématique pur (src/core/)"]
        direction TB
        DIST["🔵 distribution.ts
Sphère de Fibonacci
N points → coordonnées 3D"]
        ROT["🟢 rotation.ts
Matrices de rotation
points 3D → points 3D rotés"]
        PROJ["🔴 projection.ts
Projection perspective
3D roté → 2D + profondeur"]
    end

    subgraph RenderLayer["🎨 Couche de rendu"]
        direction TB
        CANVAS["Canvas 2D API
(texte + images)"]
        DOM["DOM Overlay
(SVG + HTML + vidéo + éléments)"]
    end

    subgraph Interaction["👤 Couche d'interaction"]
        MOUSE["Glisser souris / tactile"]
        INERTIA["Amortissement d'inertie
(0.96/image)"]
    end

    TAGS --> DIST
    OPTS --> DIST
    DIST -->|"Vec3[]"| ROT
    ROT -->|"Vec3[] rotés"| PROJ
    PROJ -->|"ProjectedTag[]
(x, y, z, scale, alpha)"| CANVAS
    PROJ --> DOM
    MOUSE --> INERTIA
    INERTIA -->|"angles de rotation"| ROT

    style CoreEngine fill:#1a1a2e,stroke:#16213e
    style Input fill:#0f3460,stroke:#16213e
    style RenderLayer fill:#533483,stroke:#16213e
    style Interaction fill:#e94560,stroke:#16213e,color:#fff

2.1 Distribution de la sphère de Fibonacci : La géométrie dorée du placement des points

La première étape, et sans doute la plus critique sur le plan esthétique, dans la création d’un nuage de tags 3D consiste à déterminer où chaque tag doit être positionné sur la sphère. Une approche naïve placerait les tags à intervalles réguliers de latitude et longitude, mais cela conduit inévitablement à un regroupement aux pôles, où les lignes de méridien convergent, et à des régions clairsemées près de l’équateur. L’algorithme de la sphère de Fibonacci résout ce problème élégamment en produisant une distribution de points remarquablement uniforme sur toute la surface de la sphère, sans regroupement ni espace visible quel que soit le nombre de points.

Cet algorithme tire son nom du nombre d’or (\varphi = \frac{1 + \sqrt{5}}{2} \approx 1.6180339887), une constante mathématique qui apparaît dans la nature dans des structures allant des arrangements de graines de tournesol aux spirales de coquilles de nautiles. Le lien avec les nombres de Fibonacci — la séquence où chaque terme est la somme des deux précédents — est que le rapport des nombres de Fibonacci consécutifs converge vers le nombre d’or à mesure que la séquence progresse. Dans le contexte de la distribution sur une sphère, l’irrationalité du nombre d’or garantit que les points successifs sont toujours placés à des angles qui ne se répètent jamais, créant un motif spiral apériodique qui remplit uniformément la surface de la sphère.

L’implémentation spécifique dans src/core/distribution.ts utilise une variante du réseau de Fibonacci optimisée pour le mapping sphérique. Pour une sphère de rayon (R) avec (N) points à distribuer, l’algorithme calcule les coordonnées sphériques puis les convertit en coordonnées cartésiennes ((x, y, z)) pour chaque point (i \in {0, 1, 2, \ldots, N-1}). L’angle de latitude (\phi) (mesuré à partir de l’axe z positif, c’est-à-dire le pôle Nord) est calculé en utilisant la fonction arc cosinus pour garantir une distribution uniforme le long de l’axe z :

$$\phi_i = \arccos\left(-1 + \frac{‘{’}2i + 1{‘}’}{‘{’}N{‘}’}\right)$$

Cette formule place le premier point légèrement en dessous du pôle Nord et le dernier point légèrement au-dessus du pôle Sud, avec le décalage (+0.5) (intégré dans le numérateur (2i + 1)) garantissant qu’aucun point n’atterrit jamais exactement sur un pôle. Cet ajustement subtil est crucial car il empêche l’artefact visuel d’un tag situé directement en haut ou en bas de la sphère où la rotation serait à peine perceptible. La fonction (\arccos) transforme un paramètre linéaire uniformément distribué en une distribution angulaire pondérée par le cosinus, ce qui compense le fait que les sphères ont moins de surface près des pôles et plus près de l’équateur.

L’angle de longitude (\theta) (mesuré dans le plan xy à partir de l’axe x positif) est calculé en utilisant une mise à l’échelle de (\phi) par (\sqrt{N\pi}), ce qui crée le motif spiral caractéristique :

$$\theta_i = \sqrt{‘{’}N\pi{‘}’} \cdot \phi_i$$

Le facteur (\sqrt{N\pi}) est dérivé de la relation entre l’angle d’or et la surface totale de la sphère. À mesure que (N) augmente, cette mise à l’échelle garantit que la spirale s’enroule autour de la sphère le nombre de fois approprié pour maintenir un espacement uniforme entre les points voisins. Le résultat est un motif où chaque point successif est tourné d’environ l’angle d’or (\approx 137,5°) par rapport à son prédécesseur lorsqu’on le regarde le long de l’axe z, reflétant les spirales phyllotaxiques trouvées dans la nature.

Enfin, ces coordonnées sphériques sont converties en coordonnées cartésiennes en utilisant la transformation standard :

$$x_i = R \cdot \cos(\theta_i) \cdot \sin(\phi_i)$$

$$y_i = R \cdot \sin(\theta_i) \cdot \sin(\phi_i)$$

$$z_i = R \cdot \cos(\phi_i)$$

Les points résultants satisfont l’équation de la sphère (x_i^2 + y_i^2 + z_i^2 = R^2) et sont distribués avec une uniformité qui rivalise avec des méthodes basées sur l’optimisation beaucoup plus coûteuses en calcul. L’affichage suivant résume l’algorithme complet de la sphère de Fibonacci :

$$\boxed{‘{’}\text{‘{’}FibonacciSphere{‘}’}(N, R) : \quad \forall i \in [0, N-1] : \begin{‘{’}cases{‘}’} \phi_i = \arccos\left(-1 + \frac{‘{’}2i+1{‘}’}{‘{’}N{‘}’}\right) \ \theta_i = \sqrt{‘{’}N\pi{‘}’} \cdot \phi_i \ P_i = (R\sin\phi_i\cos\theta_i, ; R\sin\phi_i\sin\theta_i, ; R\cos\phi_i) \end{‘{’}cases{‘}’}{‘}’}$$

L’implémentation TypeScript dans src/core/distribution.ts est remarquablement concise, reflétant la simplicité élégante de l’algorithme :

export interface Vec3 { x: number; y: number; z: number; }

export function fibonacciSphere(n: number, R: number): Vec3[] {
  const points: Vec3[] = [];
  for (let i = 0; i < n; i++) {
    const phi = Math.acos(-1 + (2 * i + 1) / n);
    const theta = Math.sqrt(n * Math.PI) * phi;
    points.push({
      x: R * Math.cos(theta) * Math.sin(phi),
      y: R * Math.sin(theta) * Math.sin(phi),
      z: R * Math.cos(phi),
    });
  }
  return points;
}

Cette fonction retourne un tableau d’objets Vec3 qui servent de positions initiales pour tous les tags du nuage. L’algorithme s’exécute en temps (\mathcal{O}(N)), ce qui le rend adapté aux nuages de tags avec des centaines d’éléments. En pratique, la plupart des nuages de tags contiennent entre 20 et 100 tags, pour lesquels ce calcul est pratiquement instantané.

2.2 Rotation 3D : Multiplication matricielle dans le domaine spatial

Une fois les tags positionnés sur la surface de la sphère, l’étape suivante consiste à permettre la rotation — à la fois la rotation automatique continue et l’interaction de glissement initiée par l’utilisateur. La bibliothèque implémente la rotation en utilisant des matrices de rotation composites alignées sur les axes, spécifiquement des rotations séquentielles autour de l’axe Y suivies de l’axe X. Cette approche est efficace en calcul, facile à comprendre et tout à fait suffisante pour le cas d’usage du nuage de tags où les rotations sont toujours relatives à une sphère centrée à l’origine.

Le fondement mathématique de ces rotations provient de l’algèbre linéaire. Une matrice de rotation 3D est une matrice orthogonale (3 \times 3) avec un déterminant de 1 qui transforme les coordonnées d’un point tout en préservant sa distance à l’origine. Pour une rotation d’un angle (\alpha) autour de l’axe Y, la matrice de rotation (R_y(\alpha)) est :

$$R_y(\alpha) = \begin{‘{’}pmatrix{‘}’} \cos\alpha & 0 & \sin\alpha \ 0 & 1 & 0 \ -\sin\alpha & 0 & \cos\alpha \end{‘{’}pmatrix{‘}’}$$

Pour une rotation d’un angle (\beta) autour de l’axe X, la matrice de rotation (R_x(\beta)) est :

$$R_x(\beta) = \begin{‘{’}pmatrix{‘}’} 1 & 0 & 0 \ 0 & \cos\beta & -\sin\beta \ 0 & \sin\beta & \cos\beta \end{‘{’}pmatrix{‘}’}$$

La bibliothèque applique ces rotations séquentiellement : d’abord la rotation autour de l’axe Y, puis la rotation autour de l’axe X. Pour un point (P = (x, y, z)), la rotation autour de l’axe Y produit un point intermédiaire (P’) :

$$\begin{‘{’}pmatrix{‘}’} x' \ y' \ z' \end{‘{’}pmatrix{‘}’} = R_y(\alpha) \begin{‘{’}pmatrix{‘}’} x \ y \ z \end{‘{’}pmatrix{‘}’} = \begin{‘{’}pmatrix{‘}’} x\cos\alpha + z\sin\alpha \ y \ -x\sin\alpha + z\cos\alpha \end{‘{’}pmatrix{‘}’}$$

La rotation autour de l’axe X est ensuite appliquée à (P’) pour produire le point roté final (P’’) :

$$\begin{‘{’}pmatrix{‘}’} x'' \ y'' \ z'' \end{‘{’}pmatrix{‘}’} = R_x(\beta) \begin{‘{’}pmatrix{‘}’} x' \ y' \ z' \end{‘{’}pmatrix{‘}’} = \begin{‘{’}pmatrix{‘}’} x' \ y'\cos\beta - z'\sin\beta \ y'\sin\beta + z'\cos\beta \end{‘{’}pmatrix{‘}’}$$

L’implémentation dans src/core/rotation.ts développe ces multiplications matricielles en opérations arithmétiques directes, évitant les frais généraux d’allocation d’objets matriciels et de multiplication. Pour un seul point, la fonction de rotation calcule :

$$\boxed{‘{’}\begin{‘{’}aligned{‘}’} y_1 &= y \cdot \cos\alpha + z \cdot (-\sin\alpha) \ z_1 &= y \cdot \sin\alpha + z \cdot \cos\alpha \ x_2 &= x \cdot \cos\beta + z_1 \cdot \sin\beta \ z_2 &= z_1 \cdot \cos\beta - x \cdot \sin\beta \ P'' &= (x_2, ; y_1, ; z_2) \end{‘{’}aligned{‘}’}{‘}’}$$

La fonction rotatePoints effectue cette transformation en lot pour tous les tags :

export function rotatePoints(points: Vec3[], a: number, b: number): Vec3[] {
  const sinA = Math.sin(a), cosA = Math.cos(a);
  const sinB = Math.sin(b), cosB = Math.cos(b);
  return points.map((p) => {
    const y1 = p.y * cosA + p.z * -sinA;
    const z1 = p.y * sinA + p.z * cosA;
    const x2 = p.x * cosB + z1 * sinB;
    return { x: x2, y: y1, z: z1 * cosB - p.x * sinB };
  });
}

2.3 Projection perspective : De l’espace 3D à l’écran 2D

La dernière opération mathématique transforme les coordonnées 3D rotées en positions 2D sur l’écran. La bibliothèque utilise un modèle de projection simplifié mais très efficace qui calcule un facteur d’échelle et un facteur d’opacité basés sur la profondeur, avec un paramètre de profondeur de perspective égal à deux fois le rayon de la sphère :

$$\text{‘{’}per{‘}’} = \frac{‘{’}2 \cdot \text{‘{’}depth{‘}’}{‘}’}{‘{’}2 \cdot \text{‘{’}depth{‘}’} + z{‘}’} = \frac{‘{’}4R{‘}’}{‘{’}4R + z{‘}’}$$

Le facteur d’opacité (alpha) utilise une relation quadratique avec un ajustement de biais :

$$\text{‘{’}alpha{‘}’} = \text{‘{’}clamp{‘}’}\left(\text{‘{’}per{‘}’}^2 - 0.25, ; 0, ; 1\right)$$

Le pipeline de projection complet se résume ainsi :

$$\boxed{‘{’}\begin{‘{’}aligned{‘}’} \text{‘{’}per{‘}’}_i &= \frac{‘{’}2 \cdot \text{‘{’}depth{‘}’}{‘}’}{‘{’}2 \cdot \text{‘{’}depth{‘}’} + z_i{‘}’} \ \text{‘{’}scale{‘}’}_i &= \text{‘{’}per{‘}’}_i \ \text{‘{’}alpha{‘}’}_i &= \min\left(1, ; \max\left(0, ; \text{‘{’}per{‘}’}_i^2 - 0.25\right)\right) \ P_i^{‘{’}\text{‘{’}2D{‘}’}{‘}’} &= \left(x_i \cdot \text{‘{’}scale{‘}’}_i, ; y_i \cdot \text{‘{’}scale{‘}’}_i, ; \text{‘{’}scale{‘}’}_i, ; \text{‘{’}alpha{‘}’}_i\right) \end{‘{’}aligned{‘}’}{‘}’}$$

L’implémentation TypeScript reflète précisément ces mathématiques :

export function project(
  points: { x: number; y: number; z: number }[],
  depth: number,
): ProjectedTag[] {
  const d2 = 2 * depth;
  return points.map((p) => {
    const per = d2 / (d2 + p.z);
    const alpha = Math.min(1, Math.max(0, per * per - 0.25));
    return { x: p.x, y: p.y, z: p.z, scale: per, alpha };
  });
}

3. Architecture et conception des modules

Le code illustre une architecture logicielle propre grâce à une séparation délibérée entre le calcul mathématique, l’orchestration du rendu et la gestion des interactions utilisateur.

3.1 Le moteur mathématique pur : src/core/

3.2 Le système de rendu double : Canvas + DOM

L’une des innovations les plus significatives est son système de rendu double, utilisant l’API Canvas 2D pour le texte et les images, et une superposition DOM pour le SVG, le HTML, la vidéo et les Web Components.

flowchart TB
    subgraph "Types de tags et moteurs de rendu"
        direction LR
        TEXT["📄 Tag texte"]
        IMG["🖼️ Tag image"]
        SVG_TAG["🎨 Tag SVG"]
        HTML_TAG["🌐 Tag HTML"]
        VIDEO["🎬 Tag vidéo"]
        ELEMENT["🔧 Tag élément"]
    end

    subgraph "Sélection du moteur de rendu"
        CANVAS["Canvas 2D API
✅ Texte
✅ Images"]
        DOM["DOM Overlay
✅ SVG
✅ HTML
✅ Vidéo
✅ Web Components"]
    end

    TEXT --> CANVAS
    IMG --> CANVAS
    SVG_TAG --> DOM
    HTML_TAG --> DOM
    VIDEO --> DOM
    ELEMENT --> DOM

    style CANVAS fill:#0f3460,stroke:#e94560,color:#fff
    style DOM fill:#533483,stroke:#e94560,color:#fff

4. Caractéristiques de performance

4.1 Complexité algorithmique

4.2 Efficacité mémoire

Pour (N = 100) tags, l’état numérique total est d’environ (100 \times (3 + 5) \times 8 = 6,400) octets — moins de 7 Ko de nombres à virgule flottante.

4.3 Taille du bundle

5. Contenu multimodal : Six types de tags

6. Comparaison avec cong-min/TagCloud

7. Guide d’utilisation pratique

7.1 Nuage textuel basique

import { TagCloud } from "@xingwangzhe/tags-cloud";

const container = document.getElementById("cloud")!;
new TagCloud(container, {
  tags: ["TypeScript", "React", "Vue", "Svelte", "Node.js", "Bun", "Rust"],
  radius: 250,
  spinY: 0.12,
  color: "#e0e0e0",
  fontSize: 16,
});

7.2 Nuage multimodal

new TagCloud(container, {
  tags: [
    "TypeScript",
    { type: "image", src: "/avatar.webp", width: 40, height: 40 },
    { type: "svg", content: `<svg viewBox="0 0 24 24"><circle cx="12" cy="12" r="10"/></svg>`, width: 48, height: 48 },
    { type: "video", src: "/demo.mp4", width: 120, height: 68 },
  ],
  radius: 300,
  spinY: 0.15,
  onTagClick(item) { console.log("Cliqué:", item); },
});

7.3 Gestion du cycle de vie

const cloud = new TagCloud(container, { tags, spinY: 0.2 });
cloud.setTags(["Nouveau", "Jeu", "De", "Tags"]);
cloud.pause();
cloud.resume();
cloud.destroy();

8. Conclusion : Les mathématiques comme moteur de rendu

@xingwangzhe/tags-cloud est une démonstration convaincante que le moteur de rendu le plus puissant en logiciel n’est pas un GPU, un compilateur de shaders ou un framework — ce sont les mathématiques. En décomposant le problème de la visualisation de nuage de tags 3D en trois opérations mathématiques pures — distribution de la sphère de Fibonacci, multiplication de matrices de rotation et projection perspective — la bibliothèque atteint des résultats visuellement indistinguables des alternatives basées sur WebGL tout en ne nécessitant aucune de leur complexité, dépendances matérielles ou poids de bundle.

Les contributions du projet à l’écosystème open source sont triples. Sur le plan architectural, il prouve qu’un moteur de rendu hybride Canvas/DOM peut offrir à la fois performance et polyvalence dans un package de 3 Ko. Sur le plan mathématique, il fournit des implémentations propres et bien documentées d’algorithmes fondamentaux d’infographie 3D. Sur le plan pratique, il donne aux développeurs un composant prêt à l’emploi pour créer des nuages de tags 3D avec support multimédia riche, sécurité TypeScript et interaction prête pour le mobile — le tout sans ajouter une seule dépendance.

Fin de l’article — Basé sur l’analyse du code source de @xingwangzhe/tags-cloud v0.9.0