3D rotating images

The script

Occasionally, you may want to display images of a product (for example), so that the product appears to rotate in 3D. This allows customers to see the product from all possible angles, and gives a better impression of what it will look like, than is possible with a normal 2D image.

This has been done before using bloated Java applets (which for reasons best known to themselves, can take over a minute to initialise on my computer, hanging everything else while they load), or Flash animations or QuickTime movies, which also take a long time to display, and do not interact well with the page. The plug-ins for these are not always available on all desktop operating systems, and many users do not have them installed, even where they are available. Occasionally, they are also done with animated GIFs, which lose all possible interaction, and do not have high quality images.

This script is designed to replace those. It allows a normal image of a product to be replaced by images that appear to rotate. The images can be rotated or tilted automatically, or manually by the user. Manually, they can be changed using buttons, links, or simply by dragging the image with a mouse. Basic zooming is also possible. All of these features can be seamlessly combined, so the image could begin rotating automatically, then the user could take over and rotate it manually.

Demo

Loading images:

[Blue man sample]

Important: see the notes below about making the effect more fluid/smooth.

Instructions

To download the script(s), see the script license, and check details like browser compatibility, use the links on the navigation panel at the top of this page.

Download the script, then inbetween the <head> tags, put:

<script src="PATH TO SCRIPT/imgrotate.js" type="text/javascript"></script>

Make sure every image that you want to be able to rotate has a unique name attribute. The script has one main class used to initialise the rotating image. It can be called at any time, including before the image has been created on the page. However, since it triggers preloading of all the required images, I recommend you wait until the page has loaded before calling it (such as using an onload function etc.). The class creates a RotatingImage Object - the API is described later:

myref = new RotatingImage(imgPrefix,imgExt,imgName,numRot,numTilt,curRot,curTilt,progressScript,readyScript,useThrow)

imgPrefix: String: The first part of the image file name and path
imgExt: String: The first part of the image file name and path
imgName: String: The name attribute of the image
numRot: Integer: Number of steps to be used in the rotation, e.g. 30
numTilt: Integer: Number of tilt angles you want, e.g. 15
curRot: Integer: The initial rotation step that is being displayed, e.g. 1
curTilt: Integer: The initial tilt angle that is being displayed, e.g. 3
progressScript: Function: a reference to a function that will be called each time an image loads during the preloading stage. Will be passed a single parameter; a number between 0 and 1, representing the image loading progress (can be combined with my progress bar script).
readyScript: Function: a reference to a function that will be called called when all images have been preloaded. No parameters will be passed, but this can be used to hide the progress bar.
useThrow: Boolean: false = show an alert when you make a configuration mistake (to aid debugging), true = throw an error when you make a configuration mistake (will not work in older browsers like Netscape 4, if you care).

How many rotation steps and tilt angles you want is very important, as it determines how fluid the effect is. The more steps and angles you have, the better it looks. The demonstrations on this page are using about the lowest possible number of rotation steps; 6, and as a result they do not look very fluid. You may want to use as many as 30. You can usually get away with many fewer tilt angles, but 6 or more is common (assuming you want more than one). However, the more steps and angles you use, the more images you will need, so the total file size increases dramatically. You will need numRot x numTilt images in total. My demonstrations here use 6 x 3 = 18 images - around 117 KB. For 30 rotation steps, and 15 tilt angles (for a very fluid effect), you would need 450 images (so let's hope you have a good relationship with your camera).

The image file names/paths must be carefully prepared to work with the rotation. The names must match the pattern:

imgPrefix_α_βimgExt

Where α is the rotation step, and β is the tilt angle. You will need combinations of every rotation step and tilt angle that you are using. If you want to use panning, you must make sure that you number the images in the correct direction. Tilt angles assume that 1 is the view from the top (or the highest viewing perspective), and rotation steps assume that progressing from 1 to 2 is motion in a clockwise direction, etc. It is assumed that the rotation steps make a complete circle around the subject.

Individual configuration demonstrations

Auto-rotating image

[Blue man sample]

<p><img src="rotimages/blue_1_1.jpg" name="myimage1" alt="[Blue man sample]"></p>
<script type="text/javascript">
var firstRotate = new RotatingImage('rotimages/blue','.jpg','myimage1',6,1,1,1,null,null,false);
firstRotate.startAutoRot(500,true);
</script>

Auto-tilting image

[Blue man sample]

<p><img src="rotimages/blue_1_1.jpg" name="myimage2" alt="[Blue man sample]"></p>
<script type="text/javascript">
var secondRotate = new RotatingImage('rotimages/blue','.jpg','myimage2',1,3,1,1,null,null,false);
secondRotate.startAutoTilt(3000,true);
</script>

Auto-rotating and auto-tilting image

[Blue man sample]

<p><img src="rotimages/blue_1_1.jpg" name="myimage3" alt="[Blue man sample]"></p>
<script type="text/javascript">
var thirdRotate = new RotatingImage('rotimages/blue','.jpg','myimage3',6,3,1,1,null,null,false);
thirdRotate.startAutoRot(500,true);
thirdRotate.startAutoTilt(3000,true);
</script>

Manual rotating, tilting, and zooming image

[Blue man sample]

<p><img src="rotimages/blue_1_1.jpg" name="myimage4" alt="[Blue man sample]"></p>
<script type="text/javascript">
var forthRotate = new RotatingImage('rotimages/blue','.jpg','myimage4',6,3,1,1,null,null,false);
</script>
<form method="get" action="" onsubmit="return false;">
  <p>
    <input type="button" onclick="forthRotate.rotateUp();" value="&larr;">
    <input type="button" onclick="forthRotate.rotateDown();" value="&rarr;">
    <input type="button" onclick="forthRotate.tiltUp();" value="&uarr;">
    <input type="button" onclick="forthRotate.tiltDown();" value="&darr;">
    <input type="button" onclick="this.form.curpercent.value = forthRotate.zoomImageIn(10,200);" value="+">
    <input type="button" onclick="this.form.curpercent.value = forthRotate.zoomImageOut(10,50);" value="-">
    <input type="text" name="curpercent" disabled readonly size="3" value="100">%
  </p>
</form>

Panning image

[Blue man sample]

Use your mouse to rotate and tilt the image. Important: see the notes above about making the effect more fluid/smooth.

<p><img src="rotimages/blue_1_1.jpg" name="myimage5" alt="[Blue man sample]"></p>
<script type="text/javascript">
var fifthRotate = new RotatingImage('rotimages/blue','.jpg','myimage5',6,3,1,1,null,null,false);
fifthRotate.setPanning(true,true,false,false);
</script>

Note that panning is not as accessible as manual buttons, since it requires the user to use a mouse. It also does not work in some older browsers like Netscape 4, if you care. For the best accessibility, combine panning with manual buttons, to allow the user to choose what they want to use.

Progress bar integration

The demo near the top of this page has a progress bar that appears while the images are loading. This assumes you are using my progress bar script, although you could change the functions to use any script of your choice.

<script src="PATH TO SCRIPT/progressbar.js" type="text/javascript"></script>
...
<div id="proginhere">Loading images: <script type="text/javascript">
  var myProgBar = new progressBar(1,'#000000','#a5f3b1','#043db2',400,20,1);
</script></div>
...
<p><img src="rotimages/blue_1_1.jpg" name="myimage6" alt="[Blue man sample]"></p>
<script type="text/javascript">
function progbarChange(oTo) {
	myProgBar.setBar(oTo);
}
function progbarFinish() {
	var oCont = document.getElementById ? document.getElementById('proginhere') : ( document.all ? document.all['proginhere'] : { style: {} } );
	oCont.style.display = 'none';
}
var sixthRotate = new RotatingImage('rotimages/blue','.jpg','myimage6',6,3,1,1,progbarChange,progbarFinish,false);
</script>

API documentation

See above for how to create a RotatingImage object.

RotatingImageObject.rotateUp( [AllowAutoRotation] )

Increases the rotation step by 1. If the new rotation step is higher than the number of steps, then it is reset to 1 (wrap-around).

AllowAutoRotation: Optional Boolean: true = allow any auto rotation to continue, false (default) = cancel any auto rotation.

RotatingImageObject.rotateDown( [AllowAutoRotation] )

Decreases the rotation step by 1. If the new rotation step is lower than 1, then it is reset to the highest step (wrap-around).

AllowAutoRotation: Optional Boolean: true = allow any auto rotation to continue, false (default) = cancel any auto rotation.

RotatingImageObject.rotateTo( Step[, AllowAutoRotation] )

Rotates the image to the specified step.

Step: Integer: The desired step. Must be a valid step between 1 and the total number of steps (inclusive).
AllowAutoRotation: Optional Boolean: true = allow any auto rotation to continue, false (default) = cancel any auto rotation.

RotatingImageObject.startAutoRot( Interval, Direction )

Automatically rotates the image by changing the rotation step at the specified interval. If the image is already auto rotating, the rotation will be stopped, then started again with the new settings.

Interval: Integer: >= 10. The time to display each step before moving on to the next step.
Direction: Boolean: true = step up, false = step down.

RotatingImageObject.stopAutoRot()

Cancels any auto rotation.

RotatingImageObject.getRotation()

Returns the current rotation step.

RotatingImageObject.getNumRotation()

Returns the total number of rotation steps.

RotatingImageObject.tiltUp( [AllowAutoTilt] )

Increases the tilt angle by 1 (if the images are numbered correctly, this means tilting the object in the image up, and the viewing perspective down). If the tilt angle is already at its maximum setting, nothing happens.

AllowAutoTilt: Optional Boolean: true = allow any auto tilt to continue, false (default) = cancel any auto tilt.

RotatingImageObject.tiltDown( [AllowAutoTilt] )

Decreases the tilt angle by 1. If the tilt angle is already at 1, nothing happens.

AllowAutoTilt: Optional Boolean: true = allow any auto tilt to continue, false (default) = cancel any auto tilt.

RotatingImageObject.tiltTo( TiltAngle[, AllowAutoTilt] )

Tilts the image to the specified tilt angle.

TiltAngle: Integer: The desired angle. Must be a valid angle between 1 and the total number of tilt angles (inclusive).
AllowAutoTilt: Optional Boolean: true = allow any auto tilt to continue, false (default) = cancel any auto tilt.

RotatingImageObject.startAutoTilt( Interval, StartingDirection )

Automatically tilts the image by changing the tilt angle at the specified interval. Once it reaches an end of its travel, the direction is reversed, and it begins to tilt in the other direction. If the image is already auto tilting, the auto tilt will be stopped, then started again with the new settings.

Interval: Integer: >= 10. The time to display each angle before moving on to the next angle.
StartingDirection: Boolean: true = tilt up, false = tilt down. Sets the initial direction of the changing tilt.

RotatingImageObject.stopAutoTilt()

Cancels any auto tilt.

RotatingImageObject.getTilt()

Returns the current tilt angle.

RotatingImageObject.getNumTilt()

Returns the total number of tilt angles.

RotatingImageObject.setPanning( Rotation, Tilt, StopAutoRotation, StopAutoTilt )

Enables or disables drag-panning on the image to rotate and/or tilt the image. Panning left and right will rotateUp and rotateDown respectively. Panning up and down will tiltUp and tiltDown respectively. See the notes above about naming the images correctly. Any auto rotation and auto tilt will be temporarily disabled (but not cancelled) while the user is panning in that direction. If you choose to cancel auto rotation or auto tilt when the user pans, you may want to provide them with a button to re-enable it. Method must not be called until after the image has been created.

Rotation: Boolean: true = allow rotation to be modified by panning, false = do not allow rotation to be modified by panning.
Tilt: Boolean: true = allow tilt to be modified by panning, false = do not allow tilt to be modified by panning.
StopAutoRotation: Boolean: true = cancel any auto rotation when the user pans left/right, false = do not cancel any auto rotation when the user pans left/right.
StopAutoTilt: Boolean: true = cancel any auto tilt when the user pans up/down, false = do not cancel any auto tilt when the user pans up/down.

Note: Panning the full width of the image from side to side will rotate through half of the steps in the rotation. Panning the full height of the image from top to bottom will tilt through all tilt angles. This keeps the image rotation in step with the mouse as much as possible, and gives a natural feeling rotation, giving the impression that you are really grabbing and turning the object in the image.

RotatingImageObject.zoomImageIn( byPercent, maxPercent )

Zooms the image in by the chosen percentage. The image's initial size is taken as 100%. Returns the percentage zoom that is now applied to the image. Method must not be called until after the image has loaded.

byPercent: Number: > 0. The desired zoom increase, relative to the original size.
maxPercent: Number: > 0. The maximum percentage zoom level (e.g. 200). If the desired zoom level is greater than the maximum zoom level, it will be set to the maximum zoom level.

RotatingImageObject.zoomImageOut( byPercent, minPercent )

Zooms the image out by the chosen percentage. The image's initial size is taken as 100%. Returns the percentage zoom that is now applied to the image. Method must not be called until after the image has loaded.

byPercent: Number: > 0. The desired zoom decrease, relative to the original size.
Direction: Number: >= 0. The minimum percentage zoom level (e.g. 50). If the desired zoom level is less than the minimum zoom level, it will be set to the minimum zoom level.

RotatingImageObject.zoomImageTo( toPercent )

Zooms the image out to the chosen percentage. The image's initial size is taken as 100%. Method must not be called until after the image has loaded.

toPercent: Number: > 0. The desired zoom decrease, relative to the original size.

RotatingImageObject.redraw()

Redraws the image with its current tilt and rotation. Called automatically by other methods so you should not need to call this yourself (unless you change something manually without using the API).

3D rotating images

Navigation

Site search

Site navigation

Details and download

The script

Demo

Instructions

Individual configuration demonstrations

Auto-rotating image

Auto-tilting image

Auto-rotating and auto-tilting image

Manual rotating, tilting, and zooming image

Panning image

Progress bar integration

API documentation