@xingwangzhe/tags-cloud: Mesin 3D Tag Cloud Multi-Modal yang Dibangun di Atas Matematika Murni

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

1. Pendahuluan: Membayangkan Ulang 3D Tag Cloud untuk Web Modern

Tag cloud telah menjadi andalan visualisasi web selama lebih dari dua dekade, berevolusi dari daftar kata berbobot sederhana menjadi pengalaman tiga dimensi imersif yang memikat pengguna dan mengubah kumpulan teks biasa menjadi patung ruang interaktif. Salah satu kontribusi paling berpengaruh dalam evolusi ini adalah cong-min/TagCloud, sebuah pustaka JavaScript ringan yang mendemonstrasikan bagaimana bola label teks berputar dapat dicapai dengan overhead minimal dan tanpa ketergantungan eksternal. Dengan 390 stars dan 93 forks di GitHub, TagCloud original menetapkan pola desain yang diadopsi oleh banyak pengembang untuk situs portofolio, showcase skill, dan dashboard visualisasi data. Inovasi intinya terletak pada pembuktian bahwa tag cloud 3D tidak perlu bergantung pada framework WebGL berat atau mesin rendering eksternal; sebaliknya, perhitungan trigonometri sederhana yang dikombinasikan dengan positioning DOM yang cermat dapat menghasilkan hasil visual yang sangat menarik.

Hadirlah @xingwangzhe/tags-cloud — sebuah pembayangan ulang dari konsep tag cloud 3D yang mempertahankan keanggunan matematis pendahulunya sambil secara dramatis memperluas kemampuannya, memodernisasi arsitekturnya, dan mendorong batas-batas dari apa yang dapat dirender oleh tag cloud. Ini bukan sekadar fork atau penambahan fitur; ini mewakili pergeseran arsitektural fundamental dari renderer yang hanya mendukung teks dan berat-DOM menjadi mesin multi-modal yang mampu menampilkan teks, gambar, grafik SVG, HTML arbitrer, elemen video, dan bahkan Web Components lengkap — semuanya berputar bersama dalam ruang tiga dimensi yang presisi secara matematis. Pustaka ini mencapai keserbagunaan ini sambil mempertahankan ukuran yang sangat kecil sekitar 3KB terkompresi gzip, membawa nol ketergantungan runtime, dan dibangun dengan toolchain modern yang terdiri dari Bun sebagai runtime JavaScript, Vite sebagai bundler, dan TypeScript untuk keamanan tipe yang lengkap di seluruh basis kode.

Tagline proyek — “multi-modal 3D tag cloud · pure math engine” — merangkum identitas gandanya. Di satu sisi, ini adalah pustaka komponen UI praktis yang dapat diintegrasikan pengembang ke dalam proyek web apa pun untuk membuat bola tag yang menarik secara visual. Di sisi lain, ini adalah mesin matematis yang menguraikan masalah kompleks rendering tag cloud 3D menjadi tiga operasi geometris murni, deterministik, dan dapat dipisahkan dengan indah: distribusi bola Fibonacci untuk positioning awal, perkalian matriks rotasi untuk transformasi spasial, dan proyeksi perspektif untuk rendering 2D yang sadar kedalaman. Masing-masing operasi ini diimplementasikan dalam modul khususnya sendiri di dalam direktori src/core/, membuat basis kode tidak hanya sangat mudah dipelihara tetapi juga sumber daya edukasi yang sangat baik bagi siapa pun yang ingin memahami matematika di balik grafik komputer 3D tanpa kompleksitas pipa rendering penuh yang mengaburkan.

Bagian-bagian berikut menyediakan pembahasan teknis komprehensif tentang setiap aspek @xingwangzhe/tags-cloud, dari algoritma distribusi bola yang diturunkan dari rasio emas hingga model interaksi arcball yang terinspirasi quaternion, dari arsitektur rendering ganda Canvas/DOM hingga pertimbangan desain responsif yang membuatnya bekerja mulus di perangkat desktop dan mobile. Apakah Anda seorang pengembang yang mengevaluasi pustaka ini untuk proyek Anda berikutnya, programmer grafis yang tertarik dengan teknik 3D ringan, atau ahli matematika yang penasaran tentang aplikasi dunia nyata dari kisi Fibonacci, artikel ini menawarkan penjelasan detail, derivasi matematis, diagram arsitektur, dan contoh kode beranotasi untuk menerangi setiap aspek dari karya rekayasa perangkat lunak yang luar biasa ini.

2. Fondasi Matematis: Tiga Pilar Rendering 3D

Di jantung @xingwangzhe/tags-cloud terdapat tiga operasi matematis yang, ketika digabungkan, mengubah daftar abstrak item konten menjadi bola berputar yang koheren secara visual. Operasi-operasi ini — distribusi, rotasi, dan proyeksi — diimplementasikan dalam tiga modul khusus di bawah src/core/, masing-masing bertanggung jawab atas satu transformasi geometris. Pemisahan tanggung jawab ini bukan sekadar preferensi arsitektural; ini mencerminkan struktur fundamental dari pipa grafik komputer 3D, di mana generasi vertex, transformasi model, dan proyeksi kamera adalah tahapan berbeda yang dapat dioptimalkan, diuji, dan dipahami secara independen.

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 Distribusi Bola Fibonacci: Geometri Emas Penempatan Titik

Langkah pertama dan bisa dibilang paling penting secara estetika dalam membuat tag cloud 3D adalah menentukan di mana setiap tag harus diposisikan pada bola. Pendekatan naif mungkin menempatkan tag pada interval lintang dan bujur yang teratur, tetapi ini pasti menghasilkan pengelompokan di kutub, di mana garis meridian bertemu, dan daerah jarang di dekat ekuator. Algoritma bola Fibonacci memecahkan masalah ini dengan elegan dengan menghasilkan distribusi titik yang sangat seragam di seluruh permukaan bola, tanpa pengelompokan atau celah yang terlihat terlepas dari jumlah titik.

Algoritma ini mengambil namanya dari rasio emas (\varphi = \frac{1 + \sqrt{5}}{2} \approx 1.6180339887), sebuah konstanta matematis yang muncul di seluruh alam dalam struktur mulai dari susunan biji bunga matahari hingga spiral cangkang moluska. Hubungannya dengan bilangan Fibonacci — urutan di mana setiap suku adalah jumlah dari dua suku sebelumnya — adalah bahwa rasio bilangan Fibonacci berurutan konvergen ke rasio emas seiring berjalannya urutan. Dalam konteks distribusi bola, sifat irasional rasio emas memastikan bahwa titik-titik berurutan selalu ditempatkan pada sudut yang tidak pernah berulang, menciptakan pola spiral aperiodik yang mengisi permukaan bola secara merata.

Implementasi spesifik dalam src/core/distribution.ts menggunakan variasi dari kisi Fibonacci yang telah dioptimalkan untuk pemetaan bola. Untuk bola berjari-jari (R) dengan (N) titik yang akan didistribusikan, algoritma menghitung koordinat bola dan kemudian mengonversinya ke koordinat Kartesian ((x, y, z)) untuk setiap titik (i \in {0, 1, 2, \ldots, N-1}). Sudut lintang (\phi) (diukur dari sumbu-z positif, yaitu kutub Utara) dihitung menggunakan fungsi kosinus invers untuk memastikan distribusi seragam di sepanjang sumbu-z:

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

Rumus ini menempatkan titik pertama sedikit di bawah kutub Utara dan titik terakhir sedikit di atas kutub Selatan, dengan offset (+0.5) (tertanam dalam pembilang (2i + 1)) memastikan bahwa tidak ada titik yang pernah mendarat tepat di kutub. Penyesuaian halus ini sangat penting karena mencegah artefak visual berupa tag yang duduk tepat di bagian atas atau bawah bola di mana rotasi hampir tidak terlihat. Fungsi (\arccos) mengubah parameter linear yang terdistribusi seragam menjadi distribusi sudut berbobot kosinus, yang mengkompensasi fakta bahwa bola memiliki luas permukaan lebih sedikit di dekat kutub dan lebih banyak di dekat ekuator.

Sudut bujur (\theta) (diukur dalam bidang-xy dari sumbu-x positif) dihitung menggunakan skala dari (\phi) dengan (\sqrt{N\pi}), yang menciptakan pola spiral yang khas:

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

Faktor (\sqrt{N\pi}) diturunkan dari hubungan antara sudut emas dan total luas permukaan bola. Saat (N) meningkat, penskalaan ini memastikan bahwa spiral melilit bola dengan jumlah yang tepat untuk mempertahankan jarak seragam antara titik-titik yang bertetangga. Hasilnya adalah pola di mana setiap titik berurutan diputar sekitar sudut emas (\approx 137.5°) relatif terhadap pendahulunya jika dilihat sepanjang sumbu-z, mencerminkan spiral phyllotactic yang ditemukan di alam.

Akhirnya, koordinat bola ini dikonversi ke koordinat Kartesian menggunakan transformasi standar:

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

Titik-titik yang dihasilkan memenuhi persamaan bola (x_i^2 + y_i^2 + z_i^2 = R^2) dan didistribusikan dengan keseragaman yang menyaingi metode berbasis optimasi yang jauh lebih mahal secara komputasi. Tampilan berikut merangkum algoritma bola Fibonacci lengkap:

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

Implementasi TypeScript dalam src/core/distribution.ts sangat ringkas, mencerminkan kesederhanaan elegan algoritma:

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

Fungsi ini mengembalikan array objek Vec3 yang berfungsi sebagai posisi awal untuk semua tag di cloud. Algoritma berjalan dalam waktu (\mathcal{O}(N)), membuatnya cocok untuk tag cloud dengan ratusan elemen. Dalam praktiknya, kebanyakan tag cloud berisi antara 20 dan 100 tag, di mana komputasi ini hampir seketika.

2.2 Rotasi 3D: Perkalian Matriks dalam Domain Spasial

Setelah tag diposisikan di permukaan bola, langkah selanjutnya adalah memungkinkan rotasi — baik putaran otomatis berkelanjutan maupun interaksi seret yang digerakkan pengguna. Pustaka mengimplementasikan rotasi menggunakan matriks rotasi sumbu-sejajar gabungan, khususnya rotasi berurutan di sekitar sumbu-Y diikuti oleh sumbu-X. Pendekatan ini efisien secara komputasi, mudah dipahami, dan sepenuhnya memadai untuk kasus penggunaan tag cloud di mana rotasi selalu relatif terhadap bola yang berpusat di titik asal.

Fondasi matematis untuk rotasi ini berasal dari aljabar linear. Matriks rotasi 3D adalah matriks ortogonal (3 \times 3) dengan determinan 1 yang mentransformasikan koordinat suatu titik sambil mempertahankan jaraknya dari titik asal. Untuk rotasi sebesar sudut (\alpha) di sekitar sumbu-Y, matriks rotasi (R_y(\alpha)) adalah:

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

Untuk rotasi sebesar sudut (\beta) di sekitar sumbu-X, matriks rotasi (R_x(\beta)) adalah:

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

Pustaka menerapkan rotasi ini secara berurutan: pertama rotasi sumbu-Y, kemudian rotasi sumbu-X. Untuk titik (P = (x, y, z)), rotasi sumbu-Y menghasilkan titik antara (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{‘}’}$$

Rotasi sumbu-X kemudian diterapkan ke (P’) untuk menghasilkan titik rotasi akhir (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{‘}’}$$

Implementasi dalam src/core/rotation.ts memperluas perkalian matriks ini menjadi operasi aritmetika langsung, menghindari overhead alokasi objek matriks dan perkalian. Untuk satu titik, fungsi rotasi menghitung:

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

Fungsi rotatePoints melakukan transformasi ini secara batch untuk semua tag:

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 Proyeksi Perspektif: Dari Ruang 3D ke Layar 2D

Operasi matematis terakhir mentransformasikan koordinat 3D yang sudah dirotasi menjadi posisi layar 2D. Pustaka menggunakan model proyeksi yang disederhanakan namun sangat efektif yang menghitung faktor skala dan faktor opasitas berdasarkan kedalaman, dengan parameter kedalaman perspektif sama dengan dua kali jari-jari bola:

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

Opasitas (alpha) menggunakan hubungan kuadratik dengan penyesuaian bias:

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

Pipa proyeksi lengkap dirangkum sebagai:

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

Implementasi TypeScript mencerminkan matematika ini dengan presisi:

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. Arsitektur dan Desain Modul

Basis kode ini mencontohkan arsitektur perangkat lunak yang bersih melalui pemisahan yang disengaja antara komputasi matematis, orkestrasi rendering, dan penanganan interaksi pengguna.

3.1 Mesin Matematika Murni: src/core/

3.2 Sistem Rendering Ganda: Canvas + DOM

Salah satu inovasi paling signifikan adalah sistem rendering ganda-nya, menggunakan Canvas 2D API untuk teks dan gambar, dan overlay DOM untuk SVG, HTML, video, dan 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. Karakteristik Performa

4.1 Kompleksitas Komputasi

4.2 Efisiensi Memori

Untuk (N = 100) tag, total status numerik sekitar (100 \times (3 + 5) \times 8 = 6.400) byte — kurang dari 7KB angka floating-point.

4.3 Ukuran Bundle

5. Konten Multi-Modal: Enam Tipe Tag

6. Perbandingan dengan cong-min/TagCloud

7. Panduan Penggunaan Praktis

7.1 Cloud Teks Saja Dasar

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 Cloud Multi-Modal

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 Manajemen Siklus Hidup

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

8. Kesimpulan: Matematika sebagai Mesin Rendering

@xingwangzhe/tags-cloud berdiri sebagai demonstrasi meyakinkan bahwa mesin rendering paling kuat dalam perangkat lunak bukanlah GPU, kompiler shader, atau framework — melainkan matematika. Dengan menguraikan masalah visualisasi tag cloud 3D menjadi tiga operasi matematis murni — distribusi bola Fibonacci, perkalian matriks rotasi, dan proyeksi perspektif — pustaka ini mencapai hasil yang secara visual tidak dapat dibedakan dari alternatif berbasis WebGL sambil tidak memerlukan kompleksitas, ketergantungan perangkat keras, atau bobot bundle mereka.

Kontribusi proyek ini terhadap ekosistem sumber terbuka ada tiga. Secara arsitektural, ini membuktikan bahwa renderer hybrid Canvas/DOM dapat memberikan performa dan keserbagunaan dalam paket 3KB. Secara matematis, ini menyediakan implementasi yang bersih dan terdokumentasi dengan baik dari algoritma grafik 3D fundamental. Secara praktis, ini memberi pengembang komponen siap-pakai untuk membuat tag cloud 3D dengan dukungan media kaya, keamanan tipe TypeScript, dan interaksi siap-mobile — semuanya tanpa menambahkan satu dependensi pun.

Akhir Artikel — Berdasarkan analisis kode sumber @xingwangzhe/tags-cloud v0.9.0