MathBox is a library for rendering presentation-quality math diagrams in a browser using WebGL. Built on top of Three.js and tQuery, it provides a clean API to visualize mathematical relationships and animate them smoothly.
MathBox can be operated manually using a tQuery-like API, or used in presentation mode with the included Director. This lets you to feed in a script of actions and step through them one by one, generating an automatic 'rollback' script to allow you to step backwards.
MathBox was initially created for the conference talk "Making Things with Maths" at Full Frontal 2012 and is still a work in progress. There are a couple of important functionality gaps, such as labelling being limited to axes and inability to re-use styles easily.
I've only tested thoroughly in Google Chrome, but Firefox seems to work well, with Opera at 90% functionality.
- Viewport, axis, vectors with labeling
- Bezier surface (slideshow)
- Complex numbers (slideshow)
- Complex exponentiation 4D -> 3D
- Circle equation (x^2 + y^2 = 1) complex 4D -> 3D
- Circle equation (x^2 + y^2 = 1) complex 4D -> 3D (animated projection)
- Distance from a point to a curve
- Surface/plane intersection
- Procedural landscape (slideshow)
- Rational function on the projective line
- Projective viewport transform
- Warping cartesian into cylindrical coordinates
- Texture mapping a surface
- Cross-eyed 3D
- Orthographic camera
You can try MathBox online right away. Simply open any of the examples above, or use this empty template and open the JavaScript console (Chrome: Ctrl-Alt-J / Cmd-Opt-J). You can interact with MathBox using the mathbox object and any of the methods documented below, for example:
mathbox.grid();mathbox.curve({id: 'my-curve',domain: [-3,3],expression: function(x){returnMath.cos(x);},})mathbox.animate('#my-curve',{color: 0x20c050,},{duration: 1000,});MathBox requires its library of GLSL shaders to be included in the DOM. You can either paste in the included MathBox.glsl.html, or use the included ThreeBox preloader with your favorite onReady mechanism:
DomReady.ready(function(){ThreeBox.preload(['MathBox.glsl.html',],function(){// Do stuff with MathBox here});});Because shaders are loaded separately, MathBox examples will not run over the file:// protocol. You must set up a local or remote webserver, or paste MathBox.glsl.html into your HTML file directly, so you can skip the preloading. This is discouraged, as it will make upgrading harder.
MathBox uses the ThreeBox/tQuery boilerplate. Create a MathBox as follows and call .start() to begin rendering.
varmathbox=mathBox({// ...}).start();// orvarelement=document.getElementById('my-element');varmathbox=mathBox(element,{// ...}).start();(which is equivalent to tQuery.createWorld(options).mathBox(element, options).start()).
Then you call methods on the mathbox object to set up your scene. For example:
mathbox// Cartesian viewport.viewport({type: 'cartesian',range: [[-3,3],[-3,3]],scale: [1,1],})// Apply automatic 300ms fade in/out.transition(300)// Add XYZ axes.axis({id: 'x-axis',axis: 0,color: 0xa0a0a0,ticks: 5,lineWidth: 2,size: .05,labels: true,}).axis({id: 'y-axis',axis: 1,color: 0xa0a0a0,ticks: 5,lineWidth: 2,size: .05,labels: true,zero: false,}).axis({id: 'z-axis',axis: 2,color: 0xa0a0a0,ticks: 5,lineWidth: 2,size: .05,zero: false,labels: true,})// Grid.grid({id: 'my-grid',axis: [0,2],color: 0xc0c0c0,lineWidth: 1,})// Curve, explicit function.curve({id: 'my-curve',domain: [-3,3],expression: function(x){returnMath.cos(x);},line: true,points: true,lineWidth: 2,})// Curve, parametric function.curve({id: 'my-circle',domain: [-3,3],expression: function(x){return[Math.sin(x)*2,Math.cos(x)*2];},line: true,points: true,lineWidth: 2,})All mathbox arguments are optional. The following options are available for configuration in addition to the normal tQuery world options:
{// Whether to allow mouse control of the camera.cameraControls: true,// Override the class to use for mouse controls.controlClass: ThreeBox.OrbitControls,// Whether to show the mouse cursor.// When set to false, the cursor auto-hides after a short delay.cursor: true,// Whether to track resizing of the containing element.elementResize: true,// Enable fullscreen mode with 'f' (browser support is buggy)fullscreen: true,// Render at scaled resolution, e.g. scale 2 is half the width/height.// Fractional values allowed.scale: 1,// Enable screenshot taking with 'p'screenshot: true,// Show FPS stats in the cornerstats: true,}By giving objects an ID, you can manipulate them, using CSS-like selectors, i.e. #id. IDs must not contain spaces or punctuation other than - and _. You can also select all objects of a certain type, e.g. axis, camera, grid or viewport.
// Get all properties of the X axis object.varproperties=mathbox.get('#x-axis');// Make all axes redmathbox.set('axis',{color: 0xff0000});// Make Z axis thicker (1000ms animation)mathbox.animate('#z-axis',{lineWidth: 10},{duration: 1000});// Clone the Z axis and move it to the side (500ms animation, 200ms delay)mathbox.clone('#z-axis',{id: 'copy',mathPosition: [0,1,0]},{duration: 500,delay: 200});You can inspect the scene by calling:
varprimitives=mathbox.select('*');which returns an array of matching elements (*, #id or type).
All MathBox primitives support the following styles, in addition to their specific properties:
{color: 0x123456,// Color in hexopacity: 1,// OpacitylineWidth: 2,// Line width for curves and wireframespointSize: 5,// Point size for point renderingmap: null,// Texture Map (pass in THREE.Texture)mapColor: 0,// Strength of texture map color (0 - 1)mapOpacity: 0,// Strength of texture map mask (0 - 1)mathScale: [1,1,1],// Scale transform in math-spacemathRotation: [0,0,0],// Euler-angle rotation in math-spacemathPosition: [0,0,0],// Position shift in math-spaceworldScale: [1,1,1],// Scale transform in world-spaceworldRotation: [0,0,0],// Euler-angle rotation in world-spaceworldPosition: [0,0,0],// Position shift in world-spacezIndex: 0.0,// Z bias which pushes the object forward (+) or backward (-)}Styles are grouped under a separate style property for each primitive, e.g.
mathbox.get('#x-axis').style.colorNote however that styles are converted into and stored as Three.js objects, such as THREE.Color and THREE.Vector3. You can pass these back into MathBox, in fact, the array-based notation for the styles above is just a convenient shorthand.
However, when using mathbox.set() and mathbox.animate(), you can omit the style key and pass in a flat object mixing both styles and options:
mathbox.set('#x-axis',{color: 0xff0000,arrow: false});mathbox.animate('#y-axis',{opacity: 0.5});Each mathbox scene has an associated viewport. This sets up a specific mathematical coordinate grid. Viewports support morphing between various coordinate grids in a mathematically correct way.
The following viewport types are available:
Cartesian Regular linear XYZ.
.viewport({type: 'cartesian',range: [[-1,1],[-1,1],[-1,1]],// Range in X, Y, Zscale: [1,1,1],// Scale in X, Y, Zrotation: [0,0,0],// Viewport rotation in Euler anglesposition: [0,0,0],// Viewport position in XYZ})Projective Applies a 4x4 homogeneous/projective transform.
.viewport({type: 'projective',range: [[-1,1],[-1,1],[-1,1]],// Range in X, Y, Zscale: [1,1,1],// Scale in X, Y, Zrotation: [0,0,0],// Viewport rotation in Euler anglesposition: [0,0,0],// Viewport position in XYZprojective: [[1,0,0,0],// 4x4 projective transform[0,1,0,0],[0,0,1,0],[0,0,0,1]],})Polar Polar coordinate grid in radians. X is angle, Y is radius, Z is ordinary depth. Also useful for visualizing complex operations in polar representation.
.viewport({type: 'polar',range: [[-π,π],[-1,1],[-1,1]],// Range in X, Y, Z (Angle, Radius, Depth)polar: 1,// Morph between cartesian (0) and polar (1)fold: 1,// Fold the angles by this factorpower: 1,// Apply this power to the radiushelix: 0,// Separate the complex plane into a helix by this amountscale: [1,1,1],// Scale in X, Y, Zrotation: [0,0,0],// Viewport rotation in Euler anglesposition: [0,0,0],// Viewport position in XYZ})Sphere Spherical coordinate grid in radians. X is longitude, Y is latitude, Z is radius.
.viewport({type: 'sphere',range: [[-π,π],[-π/2,π/2],[-1,1]],// Range in X, Y, Z (Longitude, Latitude, Radius)sphere: 1,// Morph between cartesian (0) and spherical (1)scale: [1,1,1],// Scale in X, Y, Zrotation: [0,0,0],// Viewport rotation in Euler anglesposition: [0,0,0],// Viewport position in XYZ})Note that for 2D viewports, you can just pass in 2 elements rather than 3 for each vector.
For 3D graphs, you'll often want to move the camera around. For simplicity, the camera is a simple orbiter that always looks at a particular point in space. It uses spherical coordinates (i.e. latitude/longitude) to position itself around the point of interest.
By default the camera is positioned to face the X/Y plane at a distance of 3.5 units, which gives the default viewport a slight margin.
.camera({orbit: 3.5,// Distance from the centerphi: τ/4,// Longitude angle in XZ, in radians, relative to 0 degrees on the X axistheta: 0,// Latitude angle towards Y, in radians, relative to the XZ plane.lookAt: [0,0,0],// Point of focus in space})You can add the following items into the scene by invoking these methods:
Axis
.axis({axis: 0,// 0 = X, 1 = Y, 2 = Zoffset: [0,0,0],// Shift axis positionn: 2,// Number of points on axis line (set to higher for curved viewports)ticks: 10,// Approximate number of ticks on axis (ticks are spaced at sensible units).tickUnit: 1,// Base unit for ticks. Set to π e.g. to space ticks at multiples of π.tickScale: 10,// Integer denoting the base for recursive division. 2 = binary, 10 = decimalarrow: true,// Whether to include an arrow on the axissize: .07,// Size of the arrow relative to the stage})Bezier Curve
.bezier({n: 64,// Number of pointsdomain: [0,1],// Domain, expressed in interpolation spacedata: null,// Array of control points, each an array of 2 or 3 elementsorder: 3,// Order of bezier curve (1-3)expression: function(x,i){// Live expression for data points.return0;// Return single value or array of 2/3 elements.},points: false,// Whether to draw pointsline: true,// Whether to draw lines})Bezier Surface
.bezierSurface({n: [64,64],// Number of points in each directiondomain: [[0,1],[0,1]],// X/Y Domain in interpolation spacedata: null,// Array of array of control points, each an array of 2 or 3 elementsorder: 3,// (unsupported, must be 3)expression: function(x,y,i,j){// Live expression for data points.return0;// Return single value or array of 2/3 elements.},points: false,// Whether to draw pointsline: false,// Whether to draw wireframe linesmesh: true,// Whether to draw a solid meshdoubleSided: true,// Whether the mesh is double sidedflipSided: false,// Whether to flip a single sided meshshaded: true,// Whether to shade the surface})Curve
.curve({n: 64,// Number of pointsdomain: [0,1],// Input domaindata: null,// Array of data points, each an array of 2 or 3 elementsexpression: function(x,i){// Live expression for data points.return0;// Return single value or array of 2/3 elements.},points: false,// Whether to draw pointsline: true,// Whether to draw lines})Grid
.grid({axis: [0,1],// Primary and secondary grid axis (0 = X, 1 = Y, 2 = Z)offset: [0,0,0],// Shift grid positionshow: [true,true],// Show horizontal and vertical directionn: 2,// Number of points on grid line (set to higher for curved viewports)ticks: [10,10],// Approximate number of ticks on axis (ticks are spaced at sensible units).tickUnit: [1,1],// Base unit for ticks on each axis. Set to π e.g. to space ticks at multiples of π.tickScale: [10,10],// Integer denoting the base for recursive division on each axis. 2 = binary, 10 = decimal})Surface
.surface({n: [64,64],// Number of points in each directiondomain: [[0,1],[0,1]],// X/Y Input domaindata: null,// Array of array of data points, each an array of 2 or 3 elementsexpression: function(x,y,i,j){// Live expression for data points.return0;// Return single value or array of 2/3 elements.},points: false,// Whether to draw pointsline: false,// Whether to draw wireframe linesmesh: true,// Whether to draw a solid meshdoubleSided: true,// Whether the mesh is double sidedflipSided: false,// Whether to flip a single sided meshshaded: true,// Whether to shade the surface})Vector
.vector({n: 1,// Number of vectorsdata: null,// Array of alternating start and end points,// each an array of 2 or 3 elementsexpression: function(i,end){// Live expression for start/end points.return0;// Return single value or array of 2/3 elements.},line: true,// Whether to draw vector linesarrow: true,// Whether to draw arrowheadssize: .07,// Size of the arrowhead relative to the stage})After an initial clone, all submodules will have to be initialized and updated.
$ git submodule update --init --recursiveBuild using
$ ./build.shTo build without minification set SKIP_MINIFY
$ SKIP_MINIFY=true ./build.shOr export it to disable it for the rest of the session
$ export SKIP_MINIFY=trueMathBox created by Steven Wittens - http://acko.net/
Contributors:
- So8res (Nate Soares)
- johan (Johan Sundström)
- waldir (Waldir Pimenta)
- fourplusone (Matthias Bartelmeß)
- hugoferreira (Hugo Ferreira)
- EvgenyAgafonchikov (Evgeny Agafonchikov)