@xingwangzhe/tags-cloud: мультимодальный 3D-движок облака тегов

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

1. Переосмысление 3D-облака тегов

Облако тегов остается основой веб-визуализации более 20 лет. Среди наиболее влиятельных вкладов — cong-min/TagCloud, легковесная JavaScript-библиотека.

@xingwangzhe/tags-cloud — полное переосмысление концепции, сохраняющее математическую элегантность предшественника, но кардинально расширяющее возможности. Это не форк, а фундаментальный архитектурный сдвиг от текстового DOM-рендерера к мультимодальному движку, способному отображать текст, изображения, SVG, произвольный HTML, видео и Web Components.

Проект занимает ~3KB gzipped с нулевыми зависимостями и построен на Bun + Vite + TypeScript.

2. Математический фундамент: три столпа

2.1 Распределение Фибоначчи

Золотое сечение φ = (1 + √5)/2 ≈ 1.618. Алгоритм Fibonacci sphere равномерно распределяет N точек по сфере:

φ_i = arccos(-1 + (2i+1)/N)
θ_i = √(N·π) · φ_i
P_i = (R·sin(φ_i)·cos(θ_i), R·sin(φ_i)·sin(θ_i), R·cos(φ_i))

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

2.2 Матрицы поворота

Последовательный поворот вокруг оси Y (α), затем X (β). Библиотека разворачивает умножение матриц в прямые арифметические операции.

2.3 Перспективная проекция

per = 2·depth / (2·depth + z)
scale = per
alpha = clamp(per² - 0.25, 0, 1)

3. Архитектура

Модуль	Функция	Вход → Выход
distribution.ts	fibonacciSphere(n, R)	N, R → Vec3[]
rotation.ts	rotatePoints(points, a, b)	Vec3[], a, b → Vec3[]
projection.ts	project(points, depth)	Vec3[], d → ProjectedTag[]

Двойная система рендеринга: Canvas 2D для текста и изображений, DOM-оверлей для SVG, HTML, видео и Web Components.

4. Производительность

Операция	Сложность
Поворот	O(N) — 8 mul + 4 add на точку
Проекция	O(N) — 1 div + 2 mul + 1 add
Z-сортировка	O(N log N)
Canvas рендер	O(N) — fillText / drawImage

Размер: ESM ~12 KB, Gzip ~3 KB, Brotli ~2.5 KB.

5. Шесть типов тегов

Тип	Рендерер	Пример
Text	Canvas	Навыки, ключевые слова
Image	Canvas	Логотипы, аватарки
SVG	DOM	Векторные иконки
HTML	DOM	Rich-форматированный текст
Video	DOM	Демо-клипы
Element	DOM	Web Components

6. Сравнение с cong-min/TagCloud

Аспект	cong-min/TagCloud	@xingwangzhe/tags-cloud
Язык	JavaScript (ES5)	TypeScript
Размер	~6KB min	~3KB gzipped
Типы тегов	Только текст	Текст, Изображение, SVG, HTML, Видео, Элемент
Рендерер	Только DOM	Canvas 2D + DOM
Взаимодействие	Базовый drag	Arcball + инерция

7. Пример использования

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

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

// Управление жизненным циклом
cloud.setTags(["New", "Tags"]);
cloud.pause();
cloud.resume();
cloud.destroy();

@xingwangzhe/tags-cloud: мультимодальный 3D-движок облака тегов на чистой математике