README.textile

PeasyCam provides a dead-simple mouse-driven camera for Processing. It is created and maintained by Jonathan Feinberg. It is free for all uses, per the Apache 2.0 license.

Download

Processing 1.5.1

You can download a version of Peasycam compatible with Processing 1.5.1 here:
http://static.mrfeinberg.com/peasycam/peasycam_15100.zip

Processing 2 and Later

You can install the latest Peasycam from within Processing via the menus Sketch > Import Library… > Add Library…

Example

PeasyCam camera;

void setup() {
    // PeasyCam constructor:
    // PeasyCam(PApplet parent,
    //          double lookAtX, double lookAtY, double lookAtZ, 
    //          double distance);
    camera = new PeasyCam(this, 0, 0, 0, 50);
}

That’s it. Now a mouse left-drag will rotate the camera around the subject, a right drag will zoom in and out, and a middle-drag will pan. A double-click restores the camera to its original position.

The PeasyCam is positioned on a sphere whose radius is the given distance from the look-at point. Rotations are around axes that pass through the looked-at point.

Constructors

PeasyCam(PApplet parent, double lookAtX, double lookAtY, double lookAtZ, double distance);
PeasyCam(PApplet parent, double distance); // look at 0,0,0

Methods

camera.setActive(boolean active);  // false to make this camera stop responding to mouse

// By default, the camera is in "free rotation" mode, but you can
// constrain it to any axis, around the look-at point:
camera.setYawRotationMode();   // like spinning a globe
camera.setPitchRotationMode(); // like a somersault
camera.setRollRotationMode();  // like a radio knob
camera.setSuppressRollRotationMode();  // Permit pitch/yaw only.

// Then you can set it back to its default mode:
camera.setFreeRotationMode();

// reassign particular drag gestures, or set them to null
camera.setLeftDragHandler(PeasyDragHandler handler);
camera.setCenterDragHandler(PeasyDragHandler handler);
camera.setRightDragHandler(PeasyDragHandler handler);
PeasyDragHandler getPanDragHandler();
PeasyDragHandler getRotateDragHandler();
PeasyDragHandler getZoomDragHandler();

// mouse wheel zooms by default; set null, or make your own
camera.setWheelHandler(PeasyWheelHandler handler);
PeasyWheelHandler getZoomWheelHandler();

// change sensitivity of built-in mouse wheel zoom
camera.setWheelScale(double scale); // 1.0 by default
double getWheelScale();

// make your own!
public interface PeasyDragHandler {
	public void handleDrag(final double dx, final double dy);
}
public interface PeasyWheelHandler {
	public void handleWheel(final int delta);
}

camera.lookAt(double x, double y, double z);
camera.rotateX(double angle);  // rotate around the x-axis passing through the subject
camera.rotateY(double angle);  // rotate around the y-axis passing through the subject
camera.rotateZ(double angle);  // rotate around the z-axis passing through the subject
camera.setDistance(double d);  // distance from looked-at point
camera.pan(double dx, double dy);     // move the looked-at point relative to current orientation

camera.reset();
camera.reset(long animationTimeInMillis);  // reset camera to its starting settings

CameraState state = camera.getState(); // get a serializable settings object for current state
camera.setState(CameraState state);
camera.setState(CameraState state, long animationTimeInMillis); // set the camera to the given saved state

// Utility methods to permit the use of a Heads-Up Display
// Thanks, A.W. Martin
camera.beginHUD();
// now draw things that you want relative to the camera's position and orientation
camera.endHUD(); // always!

PeasyCam is impervious to gimbal lock, and has no known “singularities” or discontinuities in its behavior. It relies on the excellent Apache Commons Math geometry package for its rotations.

Contributors

Thanks: Gennaro Senatore, Michael Kaufmann, Oori Shalev, Jeffrey Gentes, A.W. Martin, Yiannis Chatzikonstantinou, and Donald Ephraim Curtis for bug reports and feature suggestions.