SpritSpin


SpriteSpin is a jQuery plugin that turns image frames into animations. It requires an array of images or a stiched sprite sheet and plays them frame by frame like a flip book. The aim of this plugin is to provide a 360 degree view of any kind of product.

The plugin is built with extensibility in mind and allows web developers to customize the behavior and presentation of the animations.

Requirements

SpriteSpin depends on the jQuery-1.4.2 framework and later. Although the basic usability is straight forward a bit of javascript knowledge is required.

Buzzwords

  • 360 Views
  • Panorama Views
  • Touch Support
  • Extensible
  • Api
  • No flash

Browsers

  • IE 6 and greater
  • Opera
  • Firefox
  • Safari
  • Chrome

Mobile

  • iPhone
  • iPad
  • Android
  • WP7 no touch support

Download


view source on github
view annoted source code
download zip

If you are looking for the old version, you can download it here

Buy me a beer, if you like this plugin

License

Code licensed under the MIT license

Getting Started


Basic Setup

Reference jQuery and SpriteSpin scripts

<script src='jquery-1.4.2.js' type='text/javascript' />
<script src='spritespin.js' type='text/javascrip' />

Create a container for SpriteSpin

<div id='mySpriteSpin'/>

Initialize the plugin

<script type='text/javascript'>
  $("#mySpriteSpin").spritespin({
    // path to the source images.
    source: [
      "path/to/frame_001.jpg",
      "path/to/frame_002.jpg",
      "path/to/frame_003.jpg",
      "path/to/frame_004.jpg",
      "path/to/frame_005.jpg",
      "path/to/frame_006.jpg",
      "path/to/frame_007.jpg",
      "path/to/frame_008.jpg",
      "path/to/frame_009.jpg",
      "path/to/frame_010.jpg",
    ],
    width   : 480,  // width in pixels of the window/frame
    height  : 327,  // height in pixels of the window/frame
  });
</script>

Sprite Sheets

A sprite sheet contains all the image frames within a single image. The frames must be continuously aligned from left to right in one or multiple rows. The sprite sheet initialization requires two additional parameters. The total number of used frames and the number of frames in one row.

<script type='text/javascript'>
  $("#mySpriteSpin").spritespin({
    source  : "sprites/bike6x6_big.jpg", // path to sprite sheet
    width   : 480,  // width in pixels of the window/frame
    height  : 327,  // height in pixels of the window/frame
    frames  : 34,   // total number of frames
    framesX : 6     // number of frames in one row inside the spritesheet
  });
</script>

framesX may be omitted and spritespin will try to calculate that number based on the width of the source sheet and the given width. However, this does only work if the frames are tightly packed inside the sheet.

In this example the frames are tightly packed in a 6x6 grid, but the sheet is missing two frames at the end. Thus the frames option is initialized with 34 and not 36.

Panorama View

The panorama view shows a wide shot image that is then scrolled vertically. To create a panorama view, the module option must be set to panorama. The width option specifies the width of the display container, not the width of a frame as seen above.

$("#mySpriteSpin").spritespin({
  source : "sprites/panorama/panorama.jpg",
  width  : 205,        // width in pixels of the window
  height : 140,        // height in pixels of the window
  module : "panorama"  // rendering implementation to use
});

3D View

You can add several lanes of 360 shots into sprite spin to mimic a 3D like experience.

$('.spritespin').spritespin({
  // fill source array using a helper function
  source: SpriteSpin.sourceArray('images/3d/sample-{lane}-{frame}.jpg', {
    lane: [0,11],
    frame: [0,23],
    digits: 2
  }),
  width: 400,
  height: 225,
  frames: 24,
  lanes: 12,
  sense: 1,
  senseLane: -2,
  renderer: 'canvas'
});

Options


There are many options that can be used to initialize the plugin. Most of them are described below. However, it is recommended to take a look at the examples where the options are described with more detail.

source : string or array
    Sprite source or array of file sources.

width : number
    Display width

height : number
    Display height

framesX : number
    Number of frames in a row in sprite sheet

frames : number
    Total number of frames inside the spritesheet or the source array for a single 360 animation.

lanes : number
    number of 360 animations. Used for 3D like effect.

module : string
    The display module to use. Default is "360"

behavior : string
    The input behavior. Default is "drag"

renderer : string
    The render method to use. Default is "canvas". May be one of [image|canvas|background]

lane : number
    Index of the current animation.

frame : number
    The index of the current frame to show (inside current lane).

frameTime : number
    Time between updates during animation. Initial is 40 which is 25 frames per second

animate : bool
    Starts the animation on startup or reload

reverse : bool
    If true animation is played backward

loop : bool
    If true animation is looped

stopFrame : number
    Stops the animation at this frame if loop is disabled

wrap : bool
    Same as "loop" but for user input

wrapLane : bool
    Same as "loop" but for user input

sense : number
    Mouse sensitivity for frames

senseLane : number
    Mouse sensitivity for lanes

orientation : string
    Preferred interaction axis

onInit : function
    Occurs when plugin has been initialized, but before loading the source files

onProgress : function
    Occurs when any source file has been loaded

onLoad : function
    Occurs when all source files have been loaded

onFrame : function
    Occurs when the frame number has been updated (e.g. during animation)

onDraw : function
    Occurs when all update is complete and frame can be drawn

To update some options on a running instance of the plugin, just reinitialize the plugin with the new options object.

// change the source file on an already initialized plugin
$("#mySpriteSpin").spritespin({
  source      : "sprites/other_spritesheet.jpg",
});

API Object


SpriteSpin offers an API object with functions that simplify certain tasks.

var api = $("#mySpriteSpin").spritespin({
  // initialization options
}).spritespin("api");

For the available API methods take a look at the annotated source code.

Data Object


You can access the data object that represents the state of the SpriteSpin instance and manipulate it directly.

var data = $("#mySpriteSpin").spritespin({
  // initialization options
}).data("spritespin");

Most of the initialization parameters are available in the data object. However, changing some of them may break the instance. For example you can not change the source images or the size properties directly. Those options need a special processing by the plugin before they can be actively used.

Examples


How to add a slider

How to show details for specific frames

How to use the API object

Comments