WebGLSpins.js

Rendering Spins using WebGL and JavaScript.

Installation

Just download the minified JavaScript file or clone this repository:

git clone https://github.com/FlorianRhiem/WebGLSpins.js.git

WebGLSpins.js has no dependencies to other JavaScript files, but it requires browser support of WebGL 1.0 and the ANGLE_instanced_arrays and OES_element_index_uint extensions.

Usage Examples

A static, minimal example showing a single spin arrow:

<canvas id="webgl-canvas" width="800" height="800"></canvas>
<script src="webglspins.js"></script>
<script type='text/javascript'>
  var webglspins = new WebGLSpins(document.getElementById('webgl-canvas'));
  webglspins.updateSpins(1, [0, 0, 0], [1, 0, 0]);
</script>

For a more complex examples showing the different colormaps and animated spins, see this demo.

Documentation

To render spins on a canvas element, first create a WebGLSpins object:

var webglspins = WebGLSpins(<HTMLCanvasElement> canvas, <options> options?);

Arrow renderer options:

Surface renderer options:

Sphere renderer options:

To change these options later on, use:

webglspins.updateOptions(<options> options);

Use the following function to set the spin positions and directions:

webglspins.updateSpins(<Number> n, <Array> spinPositions, <Array> spinDirections);

If you use a cartesian grid, you can generate the surfaceIndices for the surface render mode using:

WebGLSpins.generateCartesianSurfaceIndices(<Number> nx, <Number> ny);

Renderers

By default, spins are rendered as arrows using the full size of the canvas. However, WebGLSpins.js allows you to use multiple renderers, even at the same time. By setting the renderers option, you can specify an array of renders and (optionally) their viewports, e.g.:

webglspins.updateOptions({
  renderers: [
    WebGLSpins.renderers.ARROWS,
    [WebGLSpins.renderers.SPHERE, [0.0, 0.0, 0.2, 0.2]
  ]
});

Arrows

Spins are rendered as arrows. This renderer is available as WebGLSpins.renderModes.ARROWS.

Surface

Spins are rendered as surface. To define the surface, WebGLSpins needs to know which points should be connected as triangles. To do this, set the surfaceIndices option to an array of indices into the spin position array. For example, if you only have three spins and want to render them as a triangle, use:

webglspins.updateOptions({
  surfaceIndices: [0, 1, 2]
});

This renderer is available as WebGLSpins.renderModes.SURFACE.

Sphere

Spins are rendered as points on a sphere, with their position on the sphere defined by the spin direction. Camera zoom and translation are disabled in this renderer. This renderer is available as WebGLSpins.renderModes.SPHERE.

Coordinate System

Spins are not rendered. Instead, a coordinate system is rendered as lines, using the current colormap to color the axes. Camera zoom and translation are disabled in this renderer. This renderer is available as WebGLSpins.renderModes.COORDINATESYSTEM.

Colormap implementations

There are three colormaps already available, basically as templates for your own: red, redblue and hue. These can be accessed as attributes of WebGLSpins.colormapImplementations.

Colormap 'red'

vec3 colormap(vec3 direction) {
  return vec3(1.0, 0.0, 0.0);
}

Colormap 'redblue'

A transition from red for positive z to blue for negative z direction.

vec3 colormap(vec3 direction) {
  vec3 color_down = vec3(0.0, 0.0, 1.0);
  vec3 color_up = vec3(1.0, 0.0, 0.0);
  return mix(color_down, color_up, direction.z*0.5+0.5);
}

Colormap 'hue'

The angle between z and y is mapped to a hue value between 0 and 1, with a positive z direction resulting in red.

float atan2(float y, float x) {
  return x == 0.0 ? sign(y)*3.14159/2.0 : atan(y, x);
}
vec3 hsv2rgb(vec3 c) {
  vec4 K = vec4(1.0, 2.0 / 3.0, 1.0 / 3.0, 3.0);
  vec3 p = abs(fract(c.xxx + K.xyz) * 6.0 - K.www);
  return c.z * mix(K.xxx, clamp(p - K.xxx, 0.0, 1.0), c.y);
}
vec3 colormap(vec3 direction) {
  vec2 xy = normalize(direction.yz);
  float hue = atan2(xy.x, xy.y) / 3.14159 / 2.0;
  return hsv2rgb(vec3(hue, 1.0, 1.0));
}