How codingmango/learn-vpython works
Project type & purpose (what you’re diagramming)
This repo is not a traditional multi-tier app (no backend/frontend/services). It’s a learning content + executable notebooks project: a curated set of Jupyter Notebooks teaching VPython (3D animations/simulations) plus one standalone Python script (014-thousand-cubes.py).
• Execution environment (user + Jupyter runtime)
• Notebook content (individual lessons)
• VPython rendering stack (Python → VPython → browser/canvas/WebGL)
• Optional: widgets/interactive inputs, and time-based animation loops
File structure analysis (components implied by tree)
Top-level artifacts:
• 001-...ipynb through 013-widgets.ipynb: incremental lessons (basics → animations → physics-ish behaviors → text/labels → widgets)
• README.md: usage instructions and learning goals
Architecturally, each notebook is a self-contained “module” that executes in the same general pipeline:
Jupyter kernel (Python) → VPython library → renders to browser output.
README-derived architecture cues
The README makes clear:
• Runtime: Python 3.7+, Jupyter Notebook/Lab
• Core dependency: vpython
• UI: browser-based notebook rendering; some notebooks use widgets to change parameters live
• Primary behavior: 3D animations/simulations, typically with a time loop (e.g., rate() in VPython), and sometimes non-blocking/dual animation patterns (notebooks 002, 006)
• the interactive feedback loop (user modifies params → kernel updates scene → browser re-renders)
• the animation loop timing control
Learner / Developer (User)
Runs notebooks, edits code, interacts with widgets.
Execution & Orchestration
Jupyter UI (Notebook/Lab in Browser)
Displays notebooks, captures user interactions, shows outputs.
Jupyter Server (local process)
Serves notebook documents, websocket channels, forwards execution requests.
Python Kernel (IPython kernel)
Executes cells, holds runtime state.
Core Library / Rendering
VPython Rendering Layer (Browser-side)
VPython commonly renders via a browser canvas/WebGL pipeline; represent it as:
• Web Canvas / WebGL (or “3D Renderer”)
Interactive Controls (where relevant)
Widget/Input Layer (notebook 013)
Sliders/buttons/etc. that send parameter changes to the kernel.
Content Modules (the repo itself)
• 1: Basics & primitives (001, 012)
• 2: Animation patterns (002, 004, 006)
• 3: Example simulations (003, 005, 010, 011)
• 5: Geometry/orientation (009)
• 6: Widgets (013)
• Standalone script: 014-thousand-cubes.py
External/Stdlib
User → Jupyter UI
• edits notebook cells
• clicks run
• manipulates widgets
Jupyter UI ↔ Jupyter Server
• HTTP/WebSocket communication for execution requests and output streaming
Jupyter Server ↔ Python Kernel
• execution commands
• stdout/stderr/results
• widget comm messages (for interactive controls)
VPython API → Browser Renderer (Canvas/WebGL)
• scene updates are sent/displayed in the notebook output area
Animation loop feedback
• Kernel executes loop (often while True: with rate(fps))
• Each iteration updates VPython objects → triggers re-render
• For “non-blocking/dual animation” notebook: show two object update streams driven by one loop/tick scheduler.
Widgets path (013)
• User changes slider → widget event → kernel callback updates parameters → VPython scene updates.
Time source path (011)
• Kernel calls time → updates clock hands → VPython scene updates.
Architectural patterns used here
• Interactive REPL-style execution: stateful kernel; successive cells mutate the same runtime scene.
• Scene graph / object model: VPython objects (primitives) represent a scene; updates modify properties.
• Render loop / tick-based simulation: animation driven by a timing function (rate() conceptually) rather than multi-threading.
• Event-driven parameter updates: widgets produce events that update simulation parameters.
Relevant technologies/frameworks
• Python 3.7+
• Jupyter Notebook/Lab (browser UI + local server)
• IPython Kernel
• VPython
• Browser rendering (Canvas/WebGL)
• (Optional) ipywidgets-style widget comms (since notebook 013 focuses on widgets)
• Python time module (accurate clock)
Clear labels for each component
Use explicit names like:
• “Jupyter UI (Browser)”
• “Jupyter Server (local)”
• “Python Kernel (IPython)”
• “VPython (Python API)”
• “VPython Renderer (Canvas/WebGL)”
• “Notebook: 003 Bouncing Ball (loop + collision logic)”
• “Notebook: 013 Widgets (event callbacks)”