Fork me on GitHub

Toxiclibs.js

an open-source library for computational design in javascript.

Toxiclibs was originally written by Karsten Schmidt for Java and Processing and is being ported to javascript by Kyle Phillips.

Toxiclibs.js works great with Canvas, SVG or any DOM element. Examples below pair with such fine libraries as: Processing.js, Three.js, or Raphael.js for SVG.

  • 2D/3D geometry
  • Mesh generation
  • Interpolation / Mapping
  • Wave Generators
  • 2D physics simulation
  • Color theory sorting and conversion

Getting Started with Toxiclibs.js

Toxiclibs.js can be used in the following ways:

  • include toxiclibs.js in your page and access with a global toxi object.
  • AMD modules for loaders such as RequireJS
  • Node.js package, available through NPM

Using the files from build/ :

<script type="text/javascript" src="js/toxiclibs.min.js"></script>
<script type="text/javascript">
  var myVector = new toxi.geom.Vec2D( 2, 3 ).scaleSelf(0.5);
  var myColor = toxi.color.TColor.newRGB(128/255,64/255,32/255);
</script>

To use with RequireJS, use the contents of lib/:

require([
  'toxi/geom/Vec2D',
  'toxi/color/TColor'
],function( Vec2D, TColor ){
  var myVector = new Vec2D( 2, 3 ).scaleSelf(0.5);
  var myColor = TColor.newRGB(128/255,64/255,32/255);
});

To use with Node.js:

npm install toxiclibsjs
var toxi = require('toxiclibsjs'),
myVector = new toxi.geom.Vec2D(0.5,0.5),
myColor = toxi.color.TColor.newRGB(128/255,64/255,32/255);

Toxiclibs.js follows the original package structure

The top-level of toxi contains the following objects:

  • color - the color utils package
  • geom - the geometry package
  • internals - functionality used within the library
  • math - the math utils package
  • physics2d - the Verlet Physics 2D package
  • processing - the processing package, eases use with Processing.js
  • THREE - features to ease use with Three.js
  • util - the util package

For comprehensive documentation, read the original javadocs.

Create custom builds easily

If you are working with the build/ files you may wish to create a custom build that only includes the modules you are using in order to reduce file size. If you are using the files as AMD modules there is no need for this.

To generate a custom build, space-delimit the modules you want:

./bin/toxiclibsjs --include "toxi/geom/Vec2D toxi/physics2d" --minify --out "./build/toxiclibsjs-custom.min.js"

There are several areas where toxiclibs.js stands apart to remain more idiomatic and helpful in the javascript environment. For a complete description of the conveniences added to toxiclibs.js, read the sugar file in the repository. Some examples of these differences are:

  • loose-typed for working more naturally with javascript objects, no instanceof tests are ever used
  • toxi.THREE.ToxiclibsSupport for easing work with Three.js
  • toxi.color.TColor additions for complete interoperability with CSS and X11 color names.
  • toxi.geom.mesh.OBJWriter's getOutput() for getting OBJ contents back as a string (helpful in js environments that don't have file system access).

Arrays / Collections

The Java version frequently uses Collections, Iterators, and java-specific for-loops[2]. In toxiclibs.js you will see a standard JavaScript usage of arrays. Below is an example of accessing the faces from a TriangleMesh:

var len = mesh.faces.length, i = 0;
for(i = 0; i < len; i++){
  doSomething( mesh.faces[i] );
}

This section will occassionally be expanded on. If you have a suggestion, or have a question on how something works, feel free to leave an issue and I am quick to respond.

Many of the constructors and other functions have additional support for option objects. For example:

//any object with an `x` and `y` will work
var vec = new toxi.geom.Vec2D({ x: 0.5, y: 0.25 });
var map = new toxi.math.ScaleMap({
  input: { min: 0, max: 100 },
  output: { min: -1, max: 1}
});
var mesh = sphere.toMesh({
  mesh: new toxi.geom.mesh.TriangleMesh('sphere'),
  resolution: 20
});