3D Interactive Product Viewer Based On Sprite Sheet – animate-sprite

Preview:

Description:

animate-sprite is a 3D interactive image viewer that allows your customers to view important detail and aspect of your product image.

Based on Sprite Sheet image that consists of frames (single image) from all angles of your product.

More Features:

• Interactive with drag, mouse hover, and touch events.
• Autoplay and infinite loop.
• Responsive design and mobile friendly.

How to use it:

1. Install & download the package with NPM.

# NPM
$ npm @its2easy/animate-sprite --save

2. Import the animate-sprite into your document.

<script src="/path/to/build/animate-sprite.min.js"></script>

3. Create a sequence of image spritesheets for your product.

4. Create a placeholder for the image viewer.

<div id="sprite-example" class="sprite sprite-example"></div>

5. Insert your product image as the background to the image viewer.

.sprite{
  background-image: url("product.jpg");
}

6. Initialize the image viewer and pass the required parameters:

• width: width of the image viewer
• height: height of the image viewer
• frames: total number of frames (single image).

var element = document.getElementById('sprite-example');
var sprite = AnimateSprite(element,
    {
      width: 600, /* required */
      height: 450, /* required */
      frames: 36, /* required */
    }
);

7. Play the image viewer on page load.

sprite.play();

8. All default options.

var sprite = animateSprite.init(element,
    {
      width: 100,
      height: 100,
      frames: 24,
      cols: false,
      loop: false,
      autoplay: false,
      frameTime: false, // time between frames
      duration: false,
      fps: 24,
      reverse: false, // reverse direction
      inversion: false,
      dragModifier: 1,
      draggable: false,
      touchScrollMode: "pageScrollTimer",
      pageScrollTimerDelay: 1500,
      onAnimationEnd: function(AnimateSprite){},
      onFrameChange: function(AnimateSprite){},
    }
);

9. Or pass the options via HTML data-OPTION attributes:

<div id="sprite-example" 
     class="sprite sprite-example"
     data-width="600"
     data-heigth="450"
     data-frames="36">
</div>

10. Available API methods to control the image viewer programmatically.

// init
sprite.init(element, options);
// play
sprite.play();
// pause
sprite.pause();
// stop
sprite.stop();
// toggle
sprite.toggle();
// go to the next frame
sprite.next();
// back to the previous frame
sprite.prev();
// if current frame is 30 of 100, it will play from 30 to 85, 
// if current frame is 95, it will play from 95 to 85
sprite.playTo(85);
sprite.playTo(98, {
  shortestPath: true
});
// starts animation in the current direction with the specified number of frames in queue
sprite.playFrames(200);
// change the direction of the animation
sprite.setReverse(true);
// calculate new sprite and frame dimensions
sprite.updateSizes();
// reset
sprite.reset();
// destroy
sprite.destroy();
// set a frame without animation
sprite.setFrame(frameIndex);
// reverse the animation
sprite.setReverse(true/false);
// return the current reverse value
sprite.getReverse();
// update an option
sprite.setOption(option, value);
// get the current frame index
sprite.getCurrentFrame();
// check if is animating
sprite.isAnimating();

11. Event handlers.

element.addEventListener('sprite:drag-start', function () {
  // Fires when user starts dragging
  // event.detail.frame
})
element.addEventListener('sprite:drag-change', function () {
  // Fires on every frame change while dragging
  // event.detail.frame
})
element.addEventListener('sprite:drag-end', function () {
  // Fires when user stops dragging
  // event.detail.frame
})
element.addEventListener('sprite:animation-end', function () {
  // Fires after the animation ends
})

Changelog:

v2.3.1 (08/22/2022)

• add direction to drag-end event, typos

v2.2.1 (03/30/2022)

• new shortestPath option for playTo()

v2.2.0 (01/19/2022)

• new onAnimationEnd and onFrameChange callbacks
• new sprite:animation-end event
• new dragModifier option
• more validations
• fix wrong animation duration
• inversion is now only used while dragging and doesn’t affect animation
• proper handling of empty animation in playTo and playFrames
• fix animation stop after dragging and loop: false
• umd version filename is now build/animate-sprite.umd.min.js

v2.1.0 (01/10/2022)

• add types, fix documentation

v2.0.1 (01/06/2022)

• fix package.json main key

v2.0.0 (01/06/2022)

• plugin import changed
• new initialization with constructor instead of init method
• inline options format has changed from data-width to data-sprite-width
• new options inversion, touchScrollMode and pageScrollTimerDelay
• new methods playTo, playFrames, getOption, updateSizes and getReverse (alias to getOption(“reverse”))
• all options are now allowed in setOption
• all options are now allowed as inline options
• sprite:last-frame and sprite:first-frame events have been removed
• supported browsers have changed (Safari 13.1+, iOS Safari 13.4+)

v1.2.0 (11/04/2021)

• drag/swipe events

v1.1.2 (07/16/2020)

• fix animation stop after resize