Repository files navigation

MathBox is a library for rendering presentation-quality math diagrams in abrowser using WebGL. Built on top ofThree.js andShaderGraph it provides a clean API to visualize mathematicalrelationships and animate them declaratively.

For background, see thearticle series onAcko.net.

Presentations:

• The Pixel Factory

Demos:

• Audio Visualizer (code)
• Cylindrical Stream (code)
• Data/Shape Mapping (code)
• LaTeX/HTML/GL Labels (code)
• Quaternion Hypersphere (code)
• Render-to-Texture History (code)
• Vertex Warping (code)
• Volumetric Vectors (code)

And many more athttps://mathbox.org.

You can install MathBox vianpm for use with a bundler likeWebpack, or include a globalMathBox object ontoyour page by including the library via CDN.

• Run the following in your project's directory to install MathBox andThree.js vianpm:

npm install mathbox three

ImportTHREE andMathBox (library and stylesheet), along with a controlsinstance that you'll pass to theMathBox.mathBox constructor:

import"mathbox/mathbox.css"import*asTHREEfrom"three"import{OrbitControls}from"three/examples/jsm/controls/OrbitControls.js"import*asMathBoxfrom"mathbox"

Include the following in your HTML header to load all required libraries andstyles:

<!-- Install your choice of three.js version from CDN: --><scripttype="text/javascript"src="https://cdn.jsdelivr.net/npm/three@0.137.0/build/three.min.js"></script><!-- Load a Controls instance, making sure that the version matches the Three.js version above: --><scripttype="text/javascript"src="https://cdn.jsdelivr.net/npm/three@0.137.0/examples/js/controls/OrbitControls.js"></script><!-- Install the latest MathBox, either mathbox.js or mathbos.min.js --><scripttype="text/javascript"src="https://cdn.jsdelivr.net/npm/mathbox@latest/build/bundle/mathbox.js"></script><!-- Include the MathBox CSS: --><linkrel="stylesheet"href="https://cdn.jsdelivr.net/npm/mathbox@latest/build/mathbox.css"/>

Construct a MathBox instance by passing initialization options to themathBox() constructor:

constoptions={controls:{// Orbit controls, i.e. Euler angles, with gimbal lockklass:THREE.OrbitControls},};constroot=MathBox.mathBox(options);

NoteSeethreestrap for all availableoptions.

To spawn inside a specific element, pass anHTMLElementwith theelement option:

constelement=document.querySelector("#my-thing");constoptions={element:element,controls:{klass:THREE.OrbitControls},};constroot=MathBox.mathBox(options);

On initialization,mathBox returns a MathBox API object, wrapping the MathBox<root/>. Insert new MathBox nodes into the component tree by calling themethod associated with the primitive you'd like to add.

NoteSeethe Primitives doc for a description of allprimitives and their properties.

The following code will set up a 3D Cartesian coordinate system with thespecified range and scale for its x, y and z axes, and then insert anx andy axis into the scene:

constview=root.cartesian({range:[[-2,2],[-1,1],[-1,1],],scale:[2,1,1],}).axis({axis:1,}).axis({axis:2,});

Use your mouse to click and drag the camera's orientation, and zoom in and out:

Each primitive call:

• creates a new element
• inserts it into the tree
• returns a version of the API object with its selection focused on the new element.

Callingprint() on some selection will print a representation to the consoleof the selection and any children. For example,view.print() prints thefollowing:

<cartesianrange={[[-2,2],[-1,1],[-1,1],]}scale={[2,1,1]}><axisaxis={1}/><axisaxis={2}/></cartesian>

Select objects using.select() and a CSS-like selector to get a jQuery-likeselection:

root.select("cartesian > axis");

Next, visit theQuick Start page for a more involved examplethat builds up an animating, interactive mathematical graph with labeled axes.

For help, see the following resources:

• Glossary of terms to help get familiar with MathBox and WebGL.
• MathBox API for typical usage.
• List of Primitives for a full element reference.
• Writing Custom Shaders for info on custom shaders and GPU-side processing.
• Context API for advanced usage.

For more involved questions, or just to say hi, please join us in theMathBoxGoogle Group.

• threestrap - Three.js bootstrapper
• shadergraph - Functional GLSL linker
• MathBox-react - React bindings for MathBox
• MathBox.cljs - ClojureScript bindings for MathBox via MathBox-react

• Math3D online graphing calculator
• KineticGraphs JS Engine (code)
• Textbook: "Interactive Linear Algebra"" (code)
• Many visualizations atSam Zhang's homepage
• Jesse Bettencourt'sTorus Knot Fibration Master's project (code)
• Interactive knot visualizations

And the many demos listed onthisthread of theMathBoxGoogle group.

MIT License.

MathBox and ShaderGraph (c) Steven Wittens 2013-2023.

Libraries and 3rd party shaders (c) their respective authors.