A p5.js library for programming web-based mathematical figures, animations, and interactives in 2D and 3D. Designed for math learners, math educators, and math creators.
Math concepts are easier to understand when we can see them in motion and interact with them. Today, it’s possible for mathematicians and educators to share what they see in their minds by writing programs with a software library.
Software libraries are more versatile than software applications, and they open more doors, since learning to use them means learning to program. Unfortunately, existing libraries for math graphics are inaccessible to most of the math community, due to their complexity.
To bridge this gap, we propose Mathemagical.js: a software library that makes it easier to program web-based mathematical figures, animations, and interactives in 2D and 3D (like the ones in this demo video). To make it intuitive enough for beginners and flexible enough for experts, we are building on p5.js, which has already managed this feat in the visual arts.
This is an open-source, community-driven project. You can join our mailing list by filling out the Mathemagical.js community form.
We plan to follow the All Contributors specification and will set this up soon; for now, we include a description of early contributions here:
- @GregStanton proposed the library and leads the project.
- @tfadali provides code and regular feedback about design choices.
- @jesi-rgb designed the site for our initial proposal, provided expertise, and named the project.
- Others have provided feedback, made helpful suggestions, and shared our work on social media.
You can start by reading our interface proposal. If you like, you can also try out a prototype of the Mathemagical.js library. Either way, we welcome your feedback!
-
Trying out the library: You can tinker with the examples in the interface proposal, or you can start a new sketch by opening this project in the p5.js Web Editor; any Mathemagical code you type into the editor will automatically work (the index.html file imports the prototype library).
-
Sharing feedback: If you want to start a discussion by asking a question or sharing an idea, that would be super helpful! If you want to start an issue that's likely to result in action items, that would also be great! If you're not sure whether to start a discussion or an issue, flip a coin. We can convert one to the other if needed.
Note: Many features have not been implemented yet, and during this prototype phase, some code may not work as expected.
Here, we outline an initial design of the Mathemagical environment, which supports drawing, animation, and interaction. We focus specifically on what the user will see, and we illustrate each type of feature with a minimal selection of examples. For instance, we show how to draw an arrow as an indication of how other shapes can be drawn. We also include links to demos that you can run in the browser, based on a prototype library.
For the purposes of this proposal, we do assume basic familiarity with computer programming; we need to be confident our design will work at all before we can test whether it will be intuitive to beginners. If you're wondering about the rationale for our design decisions, or other details, you can check out the Mathemagical.js wiki.
Mathemagical extends p5’s graphical environment by introducing custom graph windows. Beyond allowing the user to work within a right-handed coordinate system if desired, this allows the user to
- specify the origin, axis orientations, units of length, and scale (e.g. linear or logarithmic)
- provide custom dimensions for graph windows that occupy only part of the canvas
- create multiple graph windows per canvas (e.g. for side-by-side plots or scenes)
- work within non-Cartesian coordinate systems
Graph windows are created and used like canvas elements and graphics buffers in p5. In particular, p5 functions like stroke() and point() continue to work as usual.
w = createCartesianWindow(...) //similar to c = createCanvas(...) in p5
w = createPolarWindow(...)
w = createCylindricalWindow(...)
w = createSphericalWindow(...)
w.background(...) //draw graph window by coloring its background
w.border(...) //CSS-like window border (e.g. supports rounded corners)
w.stroke(...) //set stroke color
w.rotate(...) //apply a transform
w.mousePressed(...) //respond to an event
w.point(x, y) //draw a point
w.point(v) //here, v is a p5.Vector object
In addition to custom graph windows, Mathemagical provides drawing objects that encompass both primitive shapes and composite shapes:
- Primitive shapes: points, lines, graphs of mathematical functions, etc.
- Composite shapes: axes with tick marks, vector fields, styled data tables, etc.
In general, drawing objects are any objects that can be rendered on the canvas. (Mathemagical's drawing objects are analogous to Manim's "mobjects.")
This object-oriented approach makes it easy to modify individual pieces of complicated objects, all within a single interface that’s consistent with p5’s. Specifically, the user creates an object with a method like w.createAxis(), and then they draw it with a method like w.axis(). (Internally, w.axis() invokes an axis object’s own render method.)
myGrid = w.createGrid(...) //store subdivisions per tick, etc.
w.grid(myGrid) //draw grid determined by w
myAxis = w.createAxis(...) //store arrow type, etc.
myAxis.tick(-PI).stroke(...) //adjust color of the tick at -PI
w.axis(myAxis) //draw axis with tick marks and labels
myPoint = w.createPoint(...) //takes same parameters as p5’s point()
w.point(myPoint) //draw a point; has same effect as w.point(x, y) and w.point(v)
myArrow = w.createArrow(...) //create a Mathemagical arrow
w.arrow(myArrow)
//since p5 already has createVector(),
//Mathemagical provides .vector() in addition to .point() and .arrow()
myVector = w.createVector(...)
myVector.vectorMode(mode) //mode = POINT or ARROW (optional)
w.vector(myVector) //uses ARROW mode by default
myGrid.stroke(...)
myPoint.set(...) //takes same parameters as createPoint(), for updates
myLine.rotate(...)
In addition to drawing objects, Mathemagical provides animator objects:
- fade-in animators
- tracing animators
- rotation animators
- color animators
- homotopy animators (these transform one drawing object into another)
- etc.
In general, animator objects store any time-dependent sequence of changes to the rendering of a drawing object. Each of them may be applied to various kinds of drawing objects. For example, a rotation may be applied to a rectangle, a line, or any other shape.
Just as p5's built-in shapes make it easier to make complex drawings, Mathemagical's built-in animator objects make it easier to make complex animations. They can be customized by adjusting speed and other properties, just as p5 shapes can be customized by adjusting color, position, etc.
myLine = w.createLine(...) //drawing object
myRotationAnimator = w.createRotationAnimator(...) //animator object
myLine.takeUpdate(myRotationAnimator) //take update instructions from myRotationAnimator
w.line(myLine) //draw updated line
myRotationAnimator.speed(...) //set rotation speed
In addition to drawing objects and animator objects, Mathemagical provides controller objects, which leverage web-based interaction events. Like animator objects, there are many possible controller objects:
- rotation controllers
- drag controllers
- zoom controllers
- etc.
In general, controller objects store any interaction-dependent changes to the rendering of a drawing object. Like animator objects, each controller object can be applied to different drawing objects; this makes it easy to create rotatable rectangles or ellipses, draggable points or lines, zoomable or pannable graph windows, and so on.
Another advantage is that the user can create a single controller object that applies multiple event detectors and responders by default (e.g. a drag controller applied to a square will change the cursor when the mouse hovers over it and will also give instructions for changing the square's position when it's dragged). Controller objects also allow the user to customize the response to user interactions.
myPoint = w.createPoint(...) //drawing object
myDragController = w.createDragController(...) //controller object
myPoint.takeInput(myDragController) //take user input from myDragController
w.point(myPoint) //draw point
//can add multiple responders for the same event type, or delete them
//below, a user-defined callback function myMouseOverResponder is added and deleted
myDragController.addEventResponder('mouseover', myMouseOverResponder);
myDragController.deleteEventResponder('mouseover', myMouseOverResponder);
//default responders can be deactivated and reactivated
myDragController.deactivateDefaultResponder('mouseover')
myDragController.reactivateDefaultResponder('mouseover')