lenticular.js - tilt-controlled images

Introduction

Remember those cards from the bottom of the Cracker Jack box – the ones that changed images as they were tilted? Well, lenticular.js brings that interaction to the iPhone. It can be used for fancy-pants product views or just to slather some whimsy onto a boring.jpg. Check out the examples on your iPhone.

Built by your pal Tom Giannattasio (@attasi).

Quick Start

Create a sequence of images

Save each frame of the sequence with a standardized name and be sure to include the frame number. For example: sasquatch-1.jpg, sasquatch-2.jpg, sasquatch-3.jpg and so on.

Headache prevention: don't add leading zeros in the frame numbers.

Setup the lenticular element

Create an empty element for the lenticulars to be added into. Be sure to set a width and height; the images in the lenticular will scale to fit within the dimensions provided.

Initialize the lenticular

The Lenticular.Image constructor requires two important arguments. The first is the target element in which to load the image sequence. The second is an object with the lenticular's settings.

The settings object has numerous properties, but only two are required: images and frames. The images property is a string specifying the image path format. Lenticular.js looks for a double hash ## and will insert the appropriate frame number when loading images. The frames property sets the number of frames to be loaded.

// create a lenticular with 16 frames
var myLenticular = new Lenticular.Image($('.lenticular')[0], {
  images: 'images/lenticular-##.jpg',
  frames: 16
});

Library Reference

Lenticular.Image( element, settings ) constructor

Creates a new Image object.

element:object

The DOM element into which the images will be loaded. A load event is dispatched from this element when all frames have been loaded.

settings:object

Requires two properties: images and frames. Other settings are optional.

axis:string: The logical axis – x, y or z – upon which tilt values will be based. Lenticular.js will automatically adjust to follow the logical axis in both landscape and portrait mode.
frames:int: The number of frames in the image sequence.
images:string: The image path format to use when loading images. A double hash ## should be used to denote where the frame number is to be inserted. For example: lenticular-##.jpg would load images lenticular-1.jpg, lenticular-2.jpg, lenticular-3.jpg and so on.
isActive:boolean: If set to false, frames will not automatically update based on tilt. Defaults to true.
maxTilt:float: The maximum number of degrees the lenticular can be tilted. Defaults to 10.
minTilt:float: The minimum number of degrees the lenticular can be tilted. Defaults to -10.
useTilt:boolean: Specifies whether or not to automatically show frames based on the device's tilt. Defaults to true

activate() method

Tells lenticular to listen for tilt and update frames accordingly.

deactivate() method

Stops listening for tilt. Frame updates on deactivated lenticulars must be done using the showFrame method.

destroy() method

Removes the image from the global Lenticular object. This is useful in optimizing performance.

showFrame( index ) method

Manually shows a frame. This is most useful when useTilt = false;.

Support

Lenticular.js has been tested on solely on the iPhone. Extended support is in the works.