Skip to content

Commit 3d5ef53

Browse files
programmersd21programmersd21
committed
feat(ai): introduce AI-powered explanation system and structural node support
- Implement `ExplainPanel` and `scene_explainer` to generate AI-driven summaries for animations, selected nodes, and project history. - Add "Learning Mode" and "Teacher Mode" settings for automated educational feedback and structured lesson notes. - Overhaul `AINodeIntegrator` to support `PLAY` and `WAIT` structural nodes, improving Manim-to-node graph conversion. - Enhance `VideoOutputPanel` with play/pause controls, improved slider synchronization, and state management. - Expand `SnippetLibrary` with templates for Axes, MathTex transforms, NumberPlanes, and Parametric curves. - Expose new `explain.*` commands via the Manim Command Protocol (MCP). - Update README and documentation to reflect the new learning-first architecture. **Key Changes:** - **AI Explanations:** Integrated system for explaining "why" and "how" animations work in the UI and MCP. - **Structural Nodes:** Node graph now explicitly represents `play()` and `wait()` calls for precise animation timing. - **Learning & Teacher Modes:** New settings triggers proactive AI assistance during content creation. - **UI/UX Refinement:** Improved video preview and added a "🧠 Explain" button to the toolbar. - **Code-to-Node Improvements:** Enhanced Python code parsing and mapping to visual nodes, including `.animate` chains and variable references.
1 parent d10d154 commit 3d5ef53

20 files changed

Lines changed: 4357 additions & 402 deletions

‎README.md‎

Lines changed: 79 additions & 150 deletions
Original file line numberDiff line numberDiff line change
@@ -1,143 +1,110 @@
1-
# 🌿 EfficientManim — The Ultimate Node-Based Manim IDE
1+
# EfficientManim
22

3-
![Icon](icon/icon.ico)
4-
5-
**🌈 Create mathematical animations visually with the power of Python, AI, and Production-Grade Type Safety.**
3+
EfficientManim is a node-based visual IDE for building mathematical animations. It combines a drag-and-drop scene graph with AI-assisted tooling, a structured history system, and a learning-first explanation engine.
64

75
---
86

9-
## 🚀 Key Features
10-
11-
### 📄 Convert Slides into Animated Math Videos
12-
- What it does: Upload one or multiple PDFs and the AI turns each slide into animated Manim scenes and a ready-to-edit node graph.
13-
- Who it's for: Students, teachers, and YouTube educators who need clear animated explanations quickly.
14-
- Why it's powerful: It converts static slides into structured animations automatically, saving hours of manual scene building.
15-
- How it works: PDFs are parsed into slide structure, sent to the AI for an animation plan, then converted into Manim code and nodes.
16-
17-
### 🎬 Node-Based Visual Workflow
18-
- **Visual Editor:** Drag-and-drop Mobjects and Animations with intuitive wiring
19-
- **Infinite Canvas:** Pan and zoom freely to manage large node graphs
20-
- **Live Preview:** Real-time static previews of individual nodes
21-
- **Smart Connections:** Automatic wire validation and scene synchronization
22-
23-
### 🤖 AI Features
24-
- **Prompt-to-Manim Code:** Describe animations in plain English and get runnable Manim code
25-
- **PDF Slide Animation:** Attach PDFs in the AI tab and generate animated scenes automatically
26-
- **AI Voiceover Studio:** TTS generation with multi-voice support and duration syncing
7+
## What You Can Do
8+
- Build Manim scenes visually with nodes, wiring, and live previews.
9+
- Generate animations from natural-language prompts or PDF slides.
10+
- Produce AI voiceovers synced to animation timing.
11+
- Inspect and control everything through MCP commands.
2712

28-
### 🎯 Tooltips
13+
---
2914

30-
* Every button, panel, and action now includes a clear tooltip
31-
* Instantly understand what anything does without searching the documentation
32-
* Faster navigation, fewer mistakes, and a smoother workflow
33-
* The interface becomes self-explanatory, even for first-time users
15+
## 🧠 Explain This Animation
16+
**What it does**
17+
- Converts the current animation into a clear, student-friendly explanation.
18+
- Works for full scenes, selected nodes, or single animations.
3419

35-
This makes the app easier to learn, faster to use, and far more intuitive overall.
20+
**How it helps**
21+
- Students get intuitive explanations and step-by-step reasoning.
22+
- Teachers can reuse explanations as lesson scripts.
23+
- Beginners learn the “why” behind each visual move.
3624

37-
### 🎬 Multiple Scenes
38-
- Manage multiple scenes per project in the **Scenes** tab
39-
- Create, rename, delete, and switch between scenes — each with its own node graph
40-
- Scene state auto-saved and restored when switching
25+
**Explain Panel workflow**
26+
- Open the panel with the **🧠 Explain** button in the main toolbar.
27+
- Choose **Simple** or **Detailed** mode.
28+
- Regenerate or copy the explanation instantly.
4129

42-
### 📦 VGroup Utility
43-
- Select Mobject nodes → click **Create VGroup** in the **VGroups** tab
44-
- VGroup code automatically generated: `group_1 = VGroup(circle_1, square_1)`
45-
- Groups shown in expandable tree view
30+
**Simple vs Detailed**
31+
- **Simple**: short, intuition-first summaries.
32+
- **Detailed**: full step breakdown with conceptual reasoning.
4633

47-
### 🐙 GitHub Snippet Loader
48-
- Clone any GitHub repository into `~/.efficientmanim/snippets/`
49-
- Browse `.py` files; double-click to load into AI panel as snippet
50-
- All cloned repos automatically repopulated on startup
34+
---
5135

52-
### ⭐ Recents Panel
53-
- Top-5 most-used Mobjects + top-5 most-used Animations tracked per session
54-
- Persisted to `~/.efficientmanim/usage.json`
55-
- Double-click to instantly add to canvas
36+
## 🎓 Learning Mode
37+
**What it is**
38+
Learning Mode automatically generates micro-explanations while students build animations.
5639

57-
### ⌨️ Editable Keybindings
58-
- **Help → Edit Keybindings…** opens the keybindings editor
59-
- Double-click any shortcut to change it
60-
- Duplicate detection; changes persisted to QSettings
40+
**When it triggers**
41+
- Adding axes, graphs, or equations
42+
- Creating transformations
43+
- Adding tangent/slope/area visuals
44+
- Major structural changes
45+
- Checkpoints or large batch additions
6146

62-
### 📁 Editable Project Name
63-
- Project name textbox in the top-right corner of the window
64-
- Rename your `.efp` file without leaving the editor
47+
**Why it’s useful**
48+
It turns the editor into a live tutor, explaining what just changed and why it matters.
6549

66-
### 📦 Portable Project Format (.efp)
67-
- Bundled images, sounds, and videos included
68-
- ZIP-based, cross-platform, easy to share
50+
**Default state**
51+
Learning Mode is **OFF** by default to avoid interruptions.
6952

70-
### 🌓 Dark / Light Themes
71-
- Full dark mode with no white bleed-through
72-
- Switch via the theme button in the corner or Settings
73-
- QSS-based styling with ColorToken system
53+
**How to enable**
54+
Settings → **Learning Mode** → Enable Learning Mode.
7455

75-
### 🎨 Manim Class Browser
76-
- 60+ Manim classes in 8 categories (Geometry, Text, Graphs, 3D, Animations, etc.)
77-
- Search bar filters in real-time
78-
- Double-click or drag to add node to canvas
56+
---
7957

80-
### 🎬 Professional Video Rendering
81-
- Full scene export to MP4/WebM
82-
- Up to 4K resolution, 15–60 FPS, quality presets
58+
## 👩🏫 Teacher Mode
59+
**What it does**
60+
Teacher Mode generates structured lesson notes from the current scene.
8361

62+
**What you get**
63+
- Concept explanation
64+
- Visual explanation tied to the animation
65+
- Step-by-step teaching script
66+
- Student-friendly notes
67+
- Key takeaways
8468

85-
### 🧭 Advanced MCP + History Control
86-
- All actions—including node edits, wires, VGroups, scenes, project I/O, rendering, assets, AI workflows, themes, keybindings, and TTS—are now available via `docs/mcp_commands.md` with consistent structured JSON responses.
87-
- The rewritten `HistoryManager` captures grouped atomic operations (AI merges/imports, property edits, motion, wiring) and exposes per-node undo/redo stacks plus project/scene/node checkpoints (`docs/history_system.md`).
88-
- Use the new `history.*` MCP commands (`undo_project`, `redo_node`, `restore_checkpoint`, `timeline`, `replay`, etc.) to inspect diffs, summaries, and timeline metadata before issuing state changes.
69+
**Export options**
70+
- Markdown (`.md`)
71+
- Plain text (`.txt`)
72+
- Copy to clipboard
8973

90-
### 📚 Documentation Links
91-
- `docs/history_system.md` walks through the new history data model, checkpoint APIs, signals, and how to hook future actions into undo/redo.
92-
- `docs/mcp_commands.md` is the canonical MCP API reference listing every command, payload, metadata, and sample usage for AI agents.
74+
**How to enable**
75+
Settings → **Teacher Mode** → Enable Teacher Mode.
9376

9477
---
9578

96-
## 🏗️ Architectural Details
79+
## 🕰 History-Powered Explanations
80+
EfficientManim can explain how a scene evolved over time:
81+
- Explain any checkpoint state
82+
- Explain what changed between two checkpoints
83+
- Explain undo/redo actions in student language
9784

98-
For a detailed breakdown of the project structure, design decisions, and internal architecture, see:
99-
[docs/README.md](docs/README.md)
85+
These explanations are powered by the same analysis engine as the Explain Panel.
10086

10187
---
10288

103-
## 🏠 Start
89+
## 🤖 MCP Command Support
90+
The explanation system is fully scriptable:
91+
- Trigger explanations programmatically (`explain.scene`, `explain.selected_nodes`)
92+
- Control Learning Mode and Teacher Mode via MCP
93+
- Generate lesson notes through `teacher_mode.generate_lesson`
10494

105-
Run `python main.py` to open home screen and open the editor directly.
95+
See `docs/mcp_commands.md` for detailed request/response examples.
10696

10797
---
10898

109-
## ⌨️ Keyboard Shortcuts
110-
111-
| Action | Shortcut |
112-
|--------|----------|
113-
| New Project | `Ctrl+N` |
114-
| Open Project | `Ctrl+O` |
115-
| Save Project | `Ctrl+S` |
116-
| Save As | `Ctrl+Shift+S` |
117-
| Exit | `Ctrl+Q` |
118-
| Undo | `Ctrl+Z` |
119-
| Redo | `Ctrl+Y` |
120-
| Delete Selected | `Del` |
121-
| Fit View | `Ctrl+0` |
122-
| Auto-Layout | `Ctrl+L` |
123-
| Export Code | `Ctrl+E` |
124-
| Copy Code | `Ctrl+Shift+C` |
125-
| Toggle Theme | `Ctrl+T` |
126-
| Edit Keybindings | `Ctrl+,` |
127-
128-
All shortcuts are editable via **Help → Edit Keybindings…**
99+
## Getting Started
100+
Run the app:
101+
```bash
102+
python main.py
103+
```
129104

130105
---
131106

132-
## 🛠️ Prerequisites
133-
134-
1. **Python 3.10+**
135-
2. **FFmpeg** — for video rendering (must be in PATH)
136-
3. **Git** — optional, for GitHub Snippet Loader
137-
4. **LaTeX** — optional, for local LaTeX rendering
138-
139-
## 📦 Installation
140-
107+
## Installation
141108
```bash
142109
git clone https://github.com/pro-grammer-SD/EfficientManim.git
143110
cd EfficientManim
@@ -152,50 +119,12 @@ pip install manim PySide6 google-genai pydub requests numpy pdfplumber regex
152119

153120
---
154121

155-
## 📸 Gallery
156-
157-
### Overview & Setup
158-
159-
![Starting up](gallery/1.png)
160-
Launch the application and initialize the workspace.
161-
162-
![Blank node canvas](gallery/2.png)
163-
Start with a clean node canvas, ready for composition and design.
164-
165-
![Recents Menu](gallery/3.png)
166-
Quickly access recently opened projects and elements from the Recents panel.
167-
168-
---
169-
170-
### Customization & Rendering
171-
172-
![Tinkering with Nodes](gallery/4.png)
173-
Manipulate nodes interactively to refine workflows and structures.
174-
175-
![Searching for elements](gallery/5.png)
176-
Use the search tool to locate elements and components efficiently.
177-
178-
![GitHub snippets panel](gallery/6.png)
179-
Access GitHub snippets directly for rapid code reuse and integration.
122+
## Documentation
123+
- `docs/explain_system.md` — Explain system architecture and extension guide
124+
- `docs/history_system.md` — History model + history-powered explanations
125+
- `docs/mcp_commands.md` — MCP command reference (including Explain, Learning, Teacher)
180126

181127
---
182128

183-
### Features in Action
184-
185-
![Selecting a GitHub snippet](gallery/7.png)
186-
Select a snippet from GitHub to integrate seamlessly into your project.
187-
188-
![Loading the snippet](gallery/8.png)
189-
Load and insert external code dynamically into the workspace.
190-
191-
![Quickly previewing with the handy Preview tab](gallery/9.png)
192-
Preview your work instantly for faster iteration and verification.
193-
194-
![Rendered snippet output](gallery/10.png)
195-
View the resulting output, demonstrating final rendering in the node canvas.
196-
197-
---
198-
199-
Made with lots of ❤️💚💙 by Soumalya a.k.a. @pro-grammer-SD
200-
201-
Discussions: https://www.reddit.com/r/manim/comments/1qck0ji/i_built_a_nodebased_manim_ide_with_ai_assistance/
129+
## License
130+
MIT (see `LICENSE`).

‎core/config.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99
from PySide6.QtCore import QObject, QSettings, QStandardPaths, Signal
1010

1111
APP_NAME = "EfficientManim"
12-
APP_VERSION = "2.2.0"
12+
APP_VERSION = "2.3.0"
1313
PROJECT_EXT = ".efp" # EfficientManim Project (Zip)
1414
LIGHT_MODE = True
1515

‎core/history_manager.py‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -149,6 +149,7 @@ class HistoryManager(QObject):
149149
state_changed = Signal(bool, bool)
150150
snapshot_applied = Signal(object)
151151
diff_available = Signal(object)
152+
checkpoint_created = Signal(object)
152153

153154
def __init__(
154155
self,
@@ -598,6 +599,10 @@ def create_checkpoint(
598599
metadata=meta,
599600
)
600601
self._checkpoints[name] = cp
602+
try:
603+
self.checkpoint_created.emit(cp)
604+
except Exception:
605+
pass
601606
return cp
602607

603608
def restore_checkpoint(self, name: str) -> Optional[dict]:

0 commit comments

Comments
 (0)