{
"markdown": "# TorchViz-3D\n\n**An interactive browser-based environment for exploring neural network architectures in 3D and learning the mathematics and AI concepts behind them.**\n\n[](https://react.dev/)\n[](https://www.typescriptlang.org/)\n[](https://vite.dev/)\n[](https://tailwindcss.com/)\n[](https://threejs.org/)\n[](https://pyodide.org/)\n\nNo backend. No model upload. No heavy server runtime. TorchViz-3D interprets PyTorch-style `nn.Module` code in-browser using Pyodide and a shape-oriented `torchstub`, traces the network into an intermediate graph, and renders it as an interactive 3D scene alongside a rich, interactive Learning Lab.\n\n
\n \n
\n\n\n## Overview\n\nTorchViz-3D brings together two integrated capabilities accessible from the unified landing hub:\n\n1. **TorchViz Workspace** — A browser-native 3D modeling and inspection environment for PyTorch neural network architectures.\n2. **Learning Lab** — An interactive, domain-driven learning environment covering core mathematics, machine learning foundations, computer vision, and AI engineering.\n\n
\n \n
\n\n\n## Features\n\n### TorchViz Workspace\n\n- **Edit PyTorch-style models** directly in an integrated Monaco code editor.\n- **Trace architectures in-browser** using Pyodide (WASM) and `torchstub` without running a Python backend or uploading code.\n- **Visualize in interactive 3D** with Three.js and React Three Fiber, showing tensor spatial dimensions, channel depths, skip/residual connections, and hierarchical container grouping.\n- **Inspect layer structures** with parameter breakdowns, node selection sync with editor code, and terminal build logs.\n- **Inline shape validation** highlights mismatched layers directly on the canvas and in the terminal.\n- **Built-in architecture templates** include LeNet-5, Mini-ResNet, Mini-ViT, AlexNet, VGG-16, MobileNetV2, and UNet.\n- **Export diagrams** as publication-ready vector SVG or screen PNG.\n\n### Learning Lab\n\n- **Curriculum organized by AI domain**, materialized from typed, React-free Tables of Contents (TOC).\n- **Rich authored MDX lessons** featuring live KaTeX mathematical formatting and interactive visualizations.\n- **Interactive mathematical visualizers** (Cartesian vectors, matrix operations, systems of linear equations, eigenspaces, PCA, and SVD) powered by Mafs.\n- **Capability-gated lazy loading**: Reference citation tools (`Cite`, `PaperSummary`) and domain adapters load on demand without bloating the initial bundle.\n- **Structured assessments & search**: In-lesson quizzes, interactive shape exercises, and fast per-domain search.\n\n
\n \n
\n\n
\n \n
\n\n\n## How It Works\n\n### Workspace Architecture\n\n```mermaid\nflowchart LR\n A[\"PyTorch nn.Module (Monaco Editor)\"] --> B[\"WorkerService (requestId guard)\"]\n B --> C[\"Pyodide Web Worker + torchstub\"]\n C --> D[\"IRGraph JSON (nodes, edges, shapes)\"]\n D --> E[\"Layout Engine (3D positions + routes)\"]\n E --> F[\"Canvas3D (React Three Fiber)\"]\n E --> G[\"SVG / PNG Export\"]\n```\n\nThe core technique is **`torchstub`** (`src/lib/python_sources.ts`), a lightweight Python module that intercepts PyTorch `torch.nn` layer calls to perform shape inference and parameter counting without tensor arithmetic. This produces a clean Intermediate Representation (`IRGraph`) that the layout engine turns into a 3D isometric scene.\n\n### Learning Lab Pipeline\n\n```text\nTyped Domain TOCs\n → React-Free Catalog (materializeCatalog)\n → Route Resolution & Selectors\n → Locale-Authored MDX\n → Capability-Gated Domain & Reference Renderers\n```\n\nContent navigation is decoupled from UI rendering. Navigation metadata lives in typed TOCs, authored content lives in locale-specific MDX files, and domain-specific visual components are loaded dynamically only when requested.\n\n\n## Quick Start\n\n### Requirements\n\n- **Node.js**: LTS version (Node 20+ recommended).\n- **Browser**: Modern desktop browser supporting WebGL and WebAssembly (screen width ≥ 1024px recommended for the 3D workspace).\n\n### Installation & Run\n\n```bash\ngit clone https://github.com/duongtruongbinh/TorchViz-3D.git\ncd TorchViz-3D\nnpm install\nnpm run dev\n```\n\nOpen `http://localhost:3000` in your browser. From the landing page, choose **Workspace** to design 3D models or **Learning Lab** to explore the interactive curriculum.\n\n\n## Development Commands\n\n| Command | Purpose |\n| :--- | :--- |\n| `npm run dev` | Start Vite development server (`http://localhost:3000`) |\n| `npm run typecheck` | Run TypeScript type checks (`tsc --noEmit`) |\n| `npm test` | Run the Node test suite (`src/**/*.test.ts`) |\n| `npm run build` | Build production bundle in `dist/` |\n| `npm run verify` | Full verification pipeline (`typecheck` + `test` + `build`) |\n| `npm run preview` | Preview production build locally |\n\n\n## Tech Stack\n\n- **Framework & Language**: React 19 · TypeScript 6 · Vite 8 · Tailwind CSS 4\n- **3D & Graphics**: Three.js · React Three Fiber · Drei · Lucide Icons\n- **In-Browser Execution**: Pyodide (Python on WebAssembly) · `torchstub` shape tracer\n- **Editor & Content**: Monaco Editor · MDX · KaTeX · Mafs · Shiki · Floating UI\n- **State Management**: Zustand · React Router\n\n\n## Project Structure\n\n```text\nsrc/\n├── components/\n│ ├── landing/ # Landing entry surface and flow visualizer\n│ ├── workspace/ # 3D workspace, Monaco editor pane, and inspector\n│ ├── canvas/ # Three.js / React Three Fiber 3D scene\n│ ├── exercises/ # Shape/conv/value exercise engines shared with Learning Lab\n│ ├── mnist-demo/ # Forward-pass MNIST animation demo\n│ ├── operation-effects/ # Operation visual effect primitives for the canvas\n│ └── learning/ # Learning Lab shell, MDX registry, and domain adapters\n├── content/learning/ # Typed domain TOCs and locale-authored MDX lessons\n├── core/learning/ # React-free catalog contracts, materialization, and selectors\n├── lib/ # Layout engine, IR types, torchstub Python source, SVG export, and route helpers\n├── store/ # Zustand stores for workspace state and preferences\n├── templates/ # Built-in PyTorch architecture templates\n└── workers/ # Pyodide Web Worker host\n\ndocs/ # Architecture specifications, torchstub guide, and workflow plans\nwiki/ # OKF knowledge bundle (concepts, subsystem guides, gotchas)\nscripts/ # MDX validators, search generators, and build projections\n```\n\n\n## Documentation\n\n- [Architecture Guide](docs/ARCHITECTURE.md) — Detailed data flow, IR contract, layout algorithms, and renderer notes.\n- [Extending torchstub](docs/TORCHSTUB.md) — How to add shape inference for new PyTorch operations.\n- [Learning Lab Architecture](wiki/concepts/learning-lab.md) — UI ownership layers, component reuse rules, and MDX authoring contract.\n- [Knowledge Bundle](wiki/index.md) — Subsystem documentation, guides, and gotchas.\n- [Workflow Guide](docs/WORKFLOW.md) — Mandatory task workflow and stored plan rules.\n- [Contributing](CONTRIBUTING.md) — Development setup and contribution guidelines.\n\n\n## Scope & Notes\n\n- **Shape-Oriented Tracing:** TorchViz-3D computes layer output dimensions and parameter counts for architectural visualization; it does not execute full tensor mathematical backends.\n- **Workspace Layout:** The 3D modeling workspace is designed for desktop viewports (≥ 1024px).\n- **Curriculum Coverage:** Learning Lab organizes curriculum across multiple AI domains; authored lesson depth varies by domain with explicit placeholder indicators for unpublished topics.\n",
"bytes": 8732,
"sha": "8567d5ad545f1f940d428ee96216532a5bdf839512f6f564a13abec6a3b86caf",
"repo_slug": "duongtruongbinh/torchviz-3d",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/okf_duongtruongbinh_torchviz_3d_wiki_index_m_b2fe9686/readme"
}
![\"TorchViz-3D](\"docs/assets/torchviz-workspace.png\")
\n![\"TorchViz-3D](\"docs/assets/torchviz-landing.png\")
\n![\"TorchViz-3D](\"docs/assets/learning-lab-catalog.png\")
\n![\"Learning](\"docs/assets/learning-lab-continual-learning.png\")
\n