How poloclub/diffusion-explainer works
Project type and purpose
• This is a static, client-side interactive visualization tool (an open-source “Diffusion Explainer” web app).
• Purpose: let users experiment with Stable Diffusion text-to-image transformations in the browser, visualizing intermediate stages (latent vectors, denoising steps, UMAP projections).
File structure
• Top-level:
• index.html + style.css – single-page HTML/CSS UI
• js/ – JavaScript modules (controllers, visualization logic, UI components, data loaders)
• assets/ – static data (images, latent-viz frames, JSON vectors, UMAP coords, noises)
• python/compress.py – build-time script for compressing or generating assets
• No “backend” directory or server code: the app is purely static, served over HTTP.
• The js/ folder shows an MVC-like pattern:
• controller.js orchestrates user interactions
• denoise_*.js, text_*.js handle algorithmic data processing
• prompts.js, description.js, header.js populate UI text and prompts
• assets/umap and assets/json hold precomputed data loaded at runtime; assets/img and assets/latent_viz supply visual frames.
Insights from the README
• Confirms it’s a browser-only tool, no installation, runs via python -m http.server.
• Data is static, loaded via AJAX/fetch.
• Libraries and dependencies: plain JS, no framework dependencies listed (likely vanilla JS or small libs inlined).
a. Main components:
• Static HTTP Server (serves files)
• Browser (client)
– UI Layer (index.html, style.css, DOM)
– JS Controller Layer (js/controller.js + header.js + prompts.js + description.js)
– Data Processing Modules (js/denoise_l2expl.js, js/text_l3expl.js, etc.)
– Visualization Layer (renders images, latent projections, UMAP via Canvas or SVG)
– Asset Loader (fetches JSON, images, UMAP coords)
• Build-Time Pipeline (python/compress.py → generates compressed assets, latent viz frames, JSON)
b. Relationships & interactions:
• Browser ←fetch— HTTP Server serves index.html, JS, CSS, assets
• User actions in UI → Controller → invokes Data Processing → Visualization Layer
• Asset Loader fetches JSON & images on demand → passed to processing modules → displayed
• Build-Time Pipeline is separate: transforms raw data into assets/, not involved at runtime
c. Architectural patterns & design principles:
• Single-Page Application (SPA) pattern – no full page reloads, all logic in JS
• MVC-like separation: UI/view vs controller vs data processing modules
• Precompute-at-build: heavy computation (UMAP, denoise outputs) done ahead of time for fast client interaction
• Modular JS: each feature in its own file, easy to extend (e.g., add new denoising explainer)
d. Key technologies/frameworks:
• Plain HTML/CSS/JavaScript, no heavy frameworks
• JSON assets for data interchange
• Python script (compress.py) for asset generation
• Possibly D3.js or Canvas APIs (if used inside js/visualization modules)