jdf / peasycam

Dead-simple mouse-driven camera for Processing
http://MrFeinberg.com/peasycam/
Apache License 2.0
116 stars 35 forks source link

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

h3. Download

h4. 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":http://static.mrfeinberg.com/peasycam/peasycam_15100.zip

h4. Processing 2 and Later

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

h3. 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.

h3. Constructors

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

h3. 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":http://commons.apache.org/math/ "geometry package":http://commons.apache.org/math/userguide/geometry.html for its rotations.

h3. Contributors

Thanks: "Gennaro Senatore":http://wiki.uelceca.net/msc0809/published/gennaro+senatore, "Michael Kaufmann":http://www.michael-kaufmann.ch/, "Oori Shalev":http://ooish.com/, Jeffrey Gentes, "A.W. Martin":http://imaginationfeed.com, "Yiannis Chatzikonstantinou":http://prototy.blogspot.com/, and "Donald Ephraim Curtis":http://milkbox.net/ for bug reports and feature suggestions.