@xingwangzhe/tags-cloud: 純粋数学で作られたマルチモーダル3Dタグクラウドエンジン

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

1. はじめに: モダンWebのための3Dタグクラウドの再発明

タグクラウドは20年以上にわたりWeb視覚表現の定番であり続けてきた。シンプルな重み付き単語リストから、ユーザーを引き込み、ありふれたテキストの集合をインタラクティブな立体的彫刻へと変える没入型の3D体験へと進化してきた。この進化に最も影響を与えた貢献のひとつが cong-min/TagCloud だ。この軽量JavaScriptライブラリは、最小限のオーバーヘッドで外部依存ゼロのまま、回転するテキストラベルの球体を実現できることを示した。GitHubで 390スター・93フォーク を獲得したオリジナルのTagCloudは、ポートフォリオサイト、スキルショーケース、データ可視化ダッシュボードなど、数え切れないほどの開発者に採用されるデザインパターンを確立した。その核となる革新は、3Dタグクラウドが重量級のWebGLフレームワークや外部レンダリングエンジンに依存する必要はなく、シンプルな三角関数の計算と注意深いDOM配置で驚くほど魅力的な視覚結果を生み出せることを証明した点にある。

そこに登場したのが @xingwangzhe/tags-cloud だ。先駆者の数学的なエレガンスを継承しつつ、機能を劇的に拡張し、アーキテクチャをモダナイズし、タグクラウドがレンダリングできる表現の限界を押し広げる、3Dタグクラウド概念のゼロからの再発明である。これは単なるフォークや機能追加ではない。テキスト専用・DOM主体のレンダラーから、テキスト、画像、SVGグラフィクス、任意のHTML、動画要素、さらにはWeb Componentsまでもが数学的に正確な3D空間で一緒に回転するマルチモーダルエンジンへの、根本的なアーキテクチャシフトを意味する。このライブラリはこの汎用性を達成しながら、gzip圧縮で約3KBという驚異的なコンパクトサイズを維持し、ランタイム依存ゼロを実現し、Bun（JavaScriptランタイム）、Vite（バンドラ）、TypeScript（コードベース全体の完全な型安全性）という最新のツールチェーンで構築されている。

プロジェクトのタグライン — “multi-modal 3D tag cloud · pure math engine” — はその二面性を凝縮している。一方では、開発者がどんなWebプロジェクトにもドロップインして視覚的に印象的なタグ球体を作成できる実用的なUIコンポーネントライブラリである。他方では、3Dタグクラウドレンダリングという複雑な問題を、Fibonacci球面分布（初期位置決め）、回転行列乗算（空間変換）、透視投影（深度を考慮した2Dレンダリング）という3つの純粋で決定論的で美しく分離可能な幾何演算に分解する数学エンジンである。各演算は src/core/ ディレクトリ内の専用モジュールに実装されており、コードベースは高いメンテナンス性を持つだけでなく、完全なレンダリングパイプラインの複雑さに隠されることなく3Dコンピュータグラフィクスの背後にある数学を理解したい人にとって優れた教育リソースにもなっている。

以降のセクションでは、黄金比由来の球面分布アルゴリズムからクォータニオンに着想を得たアークボール操作モデル、デュアルCanvas/DOMレンダリングアーキテクチャからデスクトップとモバイルでシームレスに動作するレスポンシブデザインまで、@xingwangzhe/tags-cloud のあらゆる側面を包括的に掘り下げる。このライブラリを次のプロジェクトで評価しようとしている開発者にも、軽量3Dテクニックに興味のあるグラフィクスプログラマにも、Fibonacci格子の実世界応用に好奇心を持つ数学者にも、この記事は詳細な説明、数学的導出、アーキテクチャ図、注釈付きコード例を通じて、この注目すべきソフトウェア工学のあらゆる側面を照らし出す。

2. 数学的基盤: 3Dレンダリングの3つの柱

@xingwangzhe/tags-cloud の中核には、コンテンツ項目の抽象的なリストを視覚的に一貫性のある回転する球体へと変換する、3つの数学的操作からなる三連構造がある。分布→回転→投影というこれらの操作は src/core/ 下の3つの専用モジュールに実装されており、各々が単一の幾何変換を担当する。この関心の分離は単なるアーキテクチャ上の好みではない。頂点生成、モデル変換、カメラ投影が個別に最適化・テスト・理解可能な独立したステージであるという、3Dコンピュータグラフィクスパイプラインの基本構造を反映している。

flowchart LR
    subgraph Input["📥 Input Layer"]
        TAGS["TagItem[]
(text | image | SVG | HTML | video | element)"]
        OPTS["TagCloudOptions
(radius, spin, colors, callbacks)"]
    end

    subgraph CoreEngine["⚙️ Pure Math Engine (src/core/)"]
        direction TB
        DIST["🔵 distribution.ts
Fibonacci Sphere
N points → 3D coordinates"]
        ROT["🟢 rotation.ts
Rotation Matrices
3D points → rotated 3D points"]
        PROJ["🔴 projection.ts
Perspective Projection
rotated 3D → 2D + depth"]
    end

    subgraph RenderLayer["🎨 Render Layer"]
        direction TB
        CANVAS["Canvas 2D API
(text + images)"]
        DOM["DOM Overlay
(SVG + HTML + video + elements)"]
    end

    subgraph Interaction["👤 Interaction Layer"]
        MOUSE["Mouse / Touch Drag"]
        INERTIA["Inertia Decay
(0.96/frame)"]
    end

    TAGS --> DIST
    OPTS --> DIST
    DIST -->|"Vec3[]"| ROT
    ROT -->|"Rotated Vec3[]"| PROJ
    PROJ -->|"ProjectedTag[]
(x, y, z, scale, alpha)"| CANVAS
    PROJ --> DOM
    MOUSE --> INERTIA
    INERTIA -->|"rotation angles"| 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 Fibonacci球面分布: 点配置の黄金幾何

3Dタグクラウド作成における最初の、そしておそらく視覚的に最も重要なステップは、各タグを球面上のどこに配置するかを決めることだ。単純なアプローチでは緯度・経度を一定間隔で配置するが、これでは経線が収束する極付近でのクラスタリングと赤道付近での疎な領域が避けられない。Fibonacci球面アルゴリズムはこの問題をエレガントに解決し、点の数に関係なく球面全体にわたって顕著に均一な分布を生成する。視認できるクラスタリングやギャップがない。

このアルゴリズムの名前の由来は黄金比 (\varphi = \frac{1 + \sqrt{5}}{2} \approx 1.6180339887) である。これはひまわりの種の配列からオウムガイの螺旋まで、自然界のいたるところに現れる数学定数だ。Fibonacci数列との関連は、数列が進むにつれて連続するFibonacci数の比が黄金比に収束することにある。球面分布の文脈では、黄金比の無理数性によって連続する点が決して繰り返されない角度に配置され、球面を均等に埋める非周期螺旋パターンが生まれる。

src/core/distribution.ts の具体的な実装では、球面マッピング用に最適化されたFibonacci格子のバリエーションを使用している。半径 (R) の球面に (N) 個の点を分布させる場合、アルゴリズムは各点 (i \in {0, 1, 2, \ldots, N-1}) について球面座標を計算し、それをデカルト座標 ((x, y, z)) に変換する。緯度角 (\phi)（正のz軸、すなわち北極からの角度）は逆余弦関数を用いて計算され、z軸に沿った一様分布を保証する:

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

この式は最初の点を北極のすぐ下、最後の点を南極のすぐ上に配置し、(+0.5) のオフセット（(2i + 1) 分子に埋め込まれている）によってどの点も極に正確に着地しないようにしている。この微調整は極に直接タグが置かれて回転がほとんど知覚できなくなるという視覚的アーチファクトを防ぐために極めて重要だ。(\arccos) 関数は一様分布する線形パラメータを余弦重み付きの角度分布に変換し、極付近では表面積が小さく赤道付近では大きいという球の性質を補償する。

経度角 (\theta)（xy平面で正のx軸からの角度）は (\phi) に (\sqrt{N\pi}) を乗じて計算され、特徴的な螺旋パターンを生み出す:

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

(\sqrt{N\pi}) の因子は黄金角と球の総表面積の関係から導出される。(N) が増加するにつれて、このスケーリングは近隣の点間の均一な間隔を維持するために螺旋が球の周りを適切な回数巻き付くことを保証する。結果として、各連続する点はz軸方向から見ると先行点に対して約黄金角 (\approx 137.5°) だけ回転したパターンとなり、自然界の葉序螺旋を反映する。

最後に、これらの球面座標は標準変換を用いてデカルト座標に変換される:

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

得られる点は球面方程式 (x_i^2 + y_i^2 + z_i^2 = R^2) を満たし、計算コストの高い最適化ベースの手法に匹敵する均一性で分布する。以下の表示は完全な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{‘}’}{‘}’}$$

src/core/distribution.ts のTypeScript実装は驚くほど簡潔で、アルゴリズムのエレガントな単純さを反映している:

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

この関数はクラウド内のすべてのタグの初期位置となる Vec3 オブジェクトの配列を返す。アルゴリズムは (\mathcal{O}(N)) 時間で実行されるため、数百要素のタグクラウドにも適している。実際には、ほとんどのタグクラウドは20〜100個のタグを含み、この計算は事実上瞬時に行われる。

2.2 3D回転: 空間領域での行列乗算

タグが球面上に配置されたら、次のステップは回転を可能にすることだ — 連続的な自動スピンとユーザー操作によるドラッグの両方だ。このライブラリは複合軸合わせ回転行列、具体的にはY軸回転→X軸回転の順次回転を実装している。このアプローチは計算効率が高く、理解しやすく、回転が常に原点中心の球体に対するものであるタグクラウドのユースケースには完全に十分である。

これらの回転の数学的基盤は線形代数にある。3D回転行列は、点の座標を変換しながら原点からの距離を保持する、行列式が1の (3 \times 3) 直交行列である。角度 (\alpha) によるY軸回りの回転行列 (R_y(\alpha)) は:

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

角度 (\beta) によるX軸回りの回転行列 (R_x(\beta)) は:

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

ライブラリはこれらの回転を順次適用する: 最初にY軸回転、次にX軸回転。点 (P = (x, y, z)) について、Y軸回転は中間点 (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{‘}’}$$

次にX軸回転が (P’) に適用され、最終的な回転点 (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{‘}’}$$

src/core/rotation.ts の実装はこれらの行列乗算を直接算術演算に展開し、行列オブジェクトのアロケーションと乗算のオーバーヘッドを回避している。1点に対する回転関数は次のように計算する:

$$\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{‘}’}{‘}’}$$

rotatePoints 関数はこの変換をすべてのタグに対して一括実行する:

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 透視投影: 3D空間から2Dスクリーンへ

最後の数学的操作は、回転した3D座標を2Dスクリーン位置に変換する。ライブラリはシンプルかつ非常に効果的な投影モデルを使用し、深度に基づいてスケール係数と不透明度係数を計算する。透視深度パラメータは球半径の2倍に等しい:

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

不透明度（alpha）係数はバイアス調整を伴う二次関係を使用する:

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

完全な投影パイプラインは次のように要約される:

$$\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{‘}’}{‘}’}$$

TypeScriptの実装はこの数学を正確に反映している:

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. アーキテクチャとモジュール設計

コードベースは、数学的計算、レンダリングオーケストレーション、ユーザー操作処理の意図的な分離を通じて、クリーンなソフトウェアアーキテクチャを体現している。

3.1 純粋数学エンジン: src/core/

3.2 デュアルレンダリングシステム: Canvas + DOM

最も重要な革新のひとつがデュアルレンダリングシステムであり、Canvas 2D APIをテキストと画像に、DOMオーバーレイをSVG、HTML、動画、Web Componentsに使用する。

flowchart TB
    subgraph "Tag Types & Renderers"
        direction LR
        TEXT["📄 Text Tag"]
        IMG["🖼️ Image Tag"]
        SVG_TAG["🎨 SVG Tag"]
        HTML_TAG["🌐 HTML Tag"]
        VIDEO["🎬 Video Tag"]
        ELEMENT["🔧 Element Tag"]
    end

    subgraph "Renderer Selection"
        CANVAS["Canvas 2D API
✅ Text
✅ Images"]
        DOM["DOM Overlay
✅ SVG
✅ HTML
✅ Video
✅ 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. パフォーマンス特性

4.1 計算量

4.2 メモリ効率

(N = 100) タグの場合、総数値状態は約 (100 \times (3 + 5) \times 8 = 6,400) バイト — 7KB未満の浮動小数点数である。

4.3 バンドルサイズ

5. マルチモーダルコンテンツ: 6つのタグタイプ

6. cong-min/TagCloud との比較

7. 実践的な使い方

7.1 テキストのみの基本クラウド

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 マルチモーダルクラウド

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("Clicked:", item); },
});

7.3 ライフサイクル管理

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

8. 結論: レンダリングエンジンとしての数学

@xingwangzhe/tags-cloud は、ソフトウェアにおける最も強力なレンダリングエンジンがGPUでもシェーダコンパイラでもフレームワークでもなく、数学であるという説得力のある実証である。3Dタグクラウド可視化の問題を3つの純粋な数学的操作 — Fibonacci球面分布、回転行列乗算、透視投影 — に分解することで、このライブラリはWebGLベースの代替手法と視覚的に区別がつかない結果を、それらの複雑さ、ハードウェア依存性、バンドルサイズを一切必要とせずに達成している。

このプロジェクトのオープンソースエコシステムへの貢献は3つある。アーキテクチャ的には、ハイブリッドCanvas/DOMレンダラーが3KBのパッケージでパフォーマンスと汎用性の両方を提供できることを証明した。数学的には、基本的な3Dグラフィクスアルゴリズムのクリーンで十分にドキュメント化された実装を提供している。実用的には、リッチメディア対応、TypeScriptの安全性、モバイル対応のインタラクションを備えた3Dタグクラウド作成用のドロップインコンポーネントを、単一の依存関係も追加せずに開発者に提供している。

End of Article — Based on source code analysis of @xingwangzhe/tags-cloud v0.9.0