MathViz

• 

  MathViz transforms math and physics questions into interactive visual lessons, narrated explanations, equations, and hands-on practice.

Inspiration

Math and physics are often taught through separate equations, diagrams, and explanations. I wanted to make concepts feel connected: students should be able to see a formula, watch it happen, interact with it, and test their understanding in one place.

What it does

MathViz turns a natural-language math or physics question into an interactive visual lesson. It generates animated SVG scenes, guided explanations, equation-to-visual mappings, browser narration, live follow-up interactions, and separate hands-on practice challenges.

For example, a learner can explore escape velocity, move objects in a practice scene, and see how mass, distance, and velocity relate to the equation.

How I built it

I built MathViz with a React, TypeScript, and Vite frontend plus a FastAPI backend. The app uses OpenAI-compatible model providers to generate structured lesson specifications, then renders them in an interactive SVG-based visual runtime.

Key features include:

• Multi-scene lessons with timed steps and narration
• Draggable interactive visual objects
• Practice scenes generated separately from the lesson
• Equation mapping using KaTeX
• Browser text-to-speech narration
• Learner memory for continuity across interactions
• Saved and encrypted model-provider profiles
• Validation and repair flows for imperfect model JSON

Codex with GPT-5.6 helped me rapidly design, implement, debug, test, and document the product.

Challenges I ran into

The hardest challenge was making AI-generated scenes reliable. Smaller and open-source models can return incomplete JSON, invalid schemas, or visual instructions that cause overlapping objects.

I addressed this with strict schemas, validation, retry and repair flows, safer visual defaults, layout guidance, and a runtime that can still render a useful scene when model output is imperfect. Designing genuinely interactive practice questions—instead of static multiple-choice questions—was another major challenge.

Accomplishments that I'm proud of

I am proud that MathViz is more than an AI chatbot or static animation generator. It creates a complete learning loop:

1. See the concept.
2. Hear the explanation.
3. Connect it to the equation.
4. Manipulate the visual objects.
5. Practice in a new challenge scene.
6. Receive feedback and continue learning.

I am also proud that the project supports OpenAI-compatible providers, so learners and developers are not tied to a single model.

What I learned

I learned that visual learning needs more than attractive graphics. A strong educational experience requires clear scene composition, pacing, narration, meaningful interaction, and feedback that explains why an answer is correct or incorrect.

I also learned how important structured outputs, schema validation, graceful fallbacks, and model-aware prompting are when building agentic interfaces with multiple AI providers.

What's next for MathViz

Next, I want to improve visual layout intelligence, add richer interactive controls, expand adaptive learner memory, and improve accessibility with captions and more voice options.

I also plan to support more advanced visual runtimes for selected topics while keeping SVG as the fast, universal foundation. My goal is for MathViz to become an agentic learning platform where any learner can ask a question and receive a clear, interactive path to understanding.

Built With

• codex
• phet
• python
• react
• vite