two-rotations.js

Rotate vectors about two axes.

Installation

npm install two-rotations
bower install two-rotations

Motivation

In three dimensions, there are three possible rotations: one about each axis. In many visualizations, a combination of rotations about two of these axes is particularly important. This is because these visualizations allow users to rotate the object about two axes by dragging the mouse.

Vectors

A vector is represented as a flat Javascript array of length 3. To define a vector,

var vector = [x, y, z];

In math lingo, this can be thought of as a column vector with dimensions 3x1.

A point of confusion is that writing the array out like that makes it appear like a 1x3 row vector. The actual relationship may be more clear when the vector is written out like so:

var vector = [
  x,
  y,
  z
];

Usage

// Define a vector
var vector = [1, 0, 0];

// Generate the rotation matrix from a `yaw` and `pitch`.
var rotation = twoRotations.generateMatrix(Math.PI, 30);

// Rotate a point with that matrix
var newVector = twoRotations.rotate(vector, rotation);

API

generateMatrix( yaw, pitch )

Create a rotation matrix from a yaw and pitch. Angles are measured in Radians.

rotate( vector, rotationMatrix )

Accepts a vector as a Javascript matrix of length 3. The rotation matrix should be a matrix output from the generateMatrix method – though any 3-by-3 matrix will work.

Axes

This library is intended to be used with mouse events. As such, the axes are based off of the axes defined by the browser viewport. The axes associated with mouse coordinates are illustrated below.

The axes of this library extend from that definition, adding a z-axis that points outward from the screen, toward you. This is shown in the following diagram.

The above diagram also indicates the direction of rotations.