This library handles the mouse and touch controls for a 3D or 2D viewer window in a webpage. Here is a live demo:
⇓ Download Zip (7 KB) (Open Source - MIT License)
Project Files:Overview
Graphical viewers usually need to provide a standard interface for manipulating the viewed object. Typically, a mouse should allow the user to click and drag, and scroll to zoom. A touch screen should allow the user to move around, and pinch to zoom. In 3D, rotation is also necessary. The IceView library provides a transparent interface for HTML elements to implement these controls.
User manipulations are converted to mathematical coordinates, which are provided to the application through the IceView object. The viewer state is automatically updated when the user interacts with it, and an event function is called to allow the application to redraw the viewer element.
2D Controls:
| Action | Mouse | Touch |
| Pan | Left Button | One Finger |
| Zoom | Scroll Wheel, or Alt + Left Button | Pinch with Two Fingers |
3D Controls:
| Action | Mouse | Touch |
| Rotate | Left Button | One Finger |
| Pan | Shift + Left Button | Two Fingers |
| Zoom | Scroll Wheel, or Alt + Left Button | Pinch with Two Fingers |
Usage
Simply create an IceView object associated with your viewer element, elem. Then, draw your viewer scene based on the transformation provided by the properties of the IceView object.
2D Example:
var view = new IceView(elem);
function refresh_my_scene() {
// Replace these example transform functions with the correct ones for your API.
resetTransform();
translate(view.pos.x, view.pos.y);
scale(view.scale);
draw_my_scene();
}
view.onchange = refresh_my_scene;
You can view a live 2D example in the Mandelbrot Viewer.
3D Example:
var view = new IceView3d(elem);
function refresh_my_scene() {
// Replace these example transform functions with the correct ones for your API.
resetTransform();
rotateZ(view.rot.z);
rotateY(view.rot.y);
rotateX(view.rot.x);
translate(view.pos.x, view.pos.y, view.pos.z);
draw_my_scene();
}
view.onchange = refresh_my_scene;
You can view a live 3D example in the Mandelbulb Viewer.
Callbacks
view.onchange = function() { }
Called whenever the viewer transformation changes due to user action. You may want to use it to redraw your viewer, unless it is already redrawn at regular intervals.
view.ondown = function(x, y, touchnum) { }
Called whenever a mouse button or finger is pressed over the viewer. It provides the (x,y) coordinates of the event, along with the current number of fingers touching the screen. This will be 0 if a mouse was used.
view.onwheel = function(x, y) { }
Called when the user scrolls the mouse wheel. It provides the (x,y) coordinates of the cursor at the time the event occurred.
view.onup = function() { }
Called when the user releases a mouse button or a finger.
Properties
view.pos.x, view.pos.y, view.pos.z
The vector to translate the object being viewed.
view.scale
The scale factor of the object being viewed. For example, 2 means twice as big. (Only in 2D mode.)
view.rot.z, view.rot.y, view.rot.x
The amount in degrees to rotate the object being viewed, around each axis. These must be applied in the order z, y, x. (Only in 3D mode.)
Settings
view.trackball = {true, false} // false by default
When trackball mode is disabled, rotation is fixed with the Z axis pointing vertically. When trackball mode is enabled, the rotation is free about all axes. (Only in 3D mode.)
view.speed.pan = Positive Number // 1.0 by default
This factor changes the magnitude of the user's panning action. Be careful in 2D mode! Anything different will break the 1-to-1 feeling of moving a flat object, and will feel slippery instead. In 3D mode, this factor also affects the Alt+Left zoom speed.
view.speed.wheel = Positive Number // 1.0 by default
This factor changes the magnitude of the user's mouse wheel action. Keep in mind that mice have a wide range of sensitivity levels, so a smaller value is generally better.
view.speed.rotate = Positive Number // 1.0 by default
This factor changes the magnitude of the user's 3D rotation action. (Only in 3D mode.)
view.speed.scale = Positive Number // 1.0 by default
This factor changes the magnitude of the user's 2D zoom action. As with the pan speed, any value other than 1 will break the correct scale given the distance travelled by the fingers in a pinch gesture. However, the mathematically correct scale is sometime a bit extreme, and it helps improve the user experience to decrease this factor. (Only in 2D mode.)