Sirv Spin documentation

This documentation explains how to embed 360 spins in your websites/apps.

Sirv rapidly generates 360° and 3D spins. You can embed in websites, apps and social media. Some samples are shared in your account. New users can create an account.

Create a spin

Sirv automatically detects spins by searching for images that appear to be in a sequence. It recognizes many different sequences, such as:

  • adidas-zx-flux-01.jpg
  • adidas-zx-flux-02.jpg
  • adidas-zx-flux-03.jpg
  • etc.

3D spins (also known as multi-row or multi-axis spins) have multiple rows and columns, allowing images to be rotated up/down/left/right. Sirv recognizes these spins by scanning for two separate sets of digits in the file name. The first set of digits should refer to the row, the second to the column.

The file names below would generate a spin of 4 rows and 8 columns (32 images in total):

bag-01-01.jpgbag-01-02.jpgbag-01-03.jpgbag-01-04.jpgbag-01-05.jpgbag-01-06.jpgbag-01-07.jpgbag-01-08.jpg
bag-02-01.jpgbag-02-02.jpgbag-02-03.jpgbag-02-04.jpgbag-02-05.jpgbag-02-06.jpgbag-02-07.jpgbag-02-08.jpg
bag-03-01.jpgbag-03-02.jpgbag-03-03.jpgbag-03-04.jpgbag-03-05.jpgbag-03-06.jpgbag-03-07.jpgbag-03-08.jpg
bag-04-01.jpgbag-04-02.jpgbag-04-03.jpgbag-04-04.jpgbag-04-05.jpgbag-04-06.jpgbag-04-07.jpgbag-04-08.jpg

Spins are typically photographed using between 24 and 36 images but any number of images from 2 to 1000 can be used. Keep in mind that the more images, the longer the spin will take to load.

Sirv automatically creates a .spin file and provides you with code to embed the 360 spin into your page. The .spin file contains the location of all the images in the spin, plus any custom settings you have chosen. Each .spin file is only 1-2kb in file size. They count towards your Sirv storage allowance and do not duplicate your images.

You can safely delete .spin files that you don’t require. If you delete a .spin file by mistake, you can retrieve it from Trash or trigger the creation of a new file by reuploading an image or changing the name of one of the images and then changing it back again.

Spins will be automatically generated when:

  • The image names contain a sequence of ascending numerals.
  • Between 8 and 1000 images make up the sequence.
  • Numerals do not exceed the value 1024.

Spins can also be created manually, from 2 or more images, regardless of their file name.

To manually create a spin:

  1. Upload the images to your Sirv account.
  2. Select all the images to show in your spin.
  3. Click the “Create spin” button.

Embed a 360 spin

Click on any spin in your Sirv account to a preview of the spin. Underneath is the code to embed the spin in your page.

The JavaScript code should be pasted before the of your HTML page (or anywhere else on your page):

<script src="https://scripts.sirv.com/sirv.js"></script>

The spin code should be pasted where you want the spin to appear:

<div class="Sirv" data-src="https://sirv.sirv.com/Examples/drill/drill.spin"></div>

Go ahead and paste that code above into your page and you’ll see the spinning power drill.

Iframe

Alternatively, spins can be embedded with an iframe, instead of the standard Sirv div and script code described above.

Advantages of iframe:

  • Can often be embedded in your page when other embed methods cannot.

Disadvantages of iframe:

  • Full-screen does not work on all browsers.
  • Scrollbars might be unnecessarily added to your page.

The disadvantages mean that iframes are not recommended unless there is no other option. For example, some CMS or website control panels restrict you from adding any < script > code to your page, so iframe is the solution. Facebook also restricts < script > tags in Facebook pages, so iframe is necessary. (While Facebook pages require iframe, Facebook posts have an diferent method – see below).

To embed an iframe, copy the code from the iframe option of your spin:

Embed 360 spin with iframe

Copy the code below to paste this demo into your page:

<iframe src="https://sirv.sirv.com/Examples/drill/drill.spin" height="300" frameborder="0" allowfullscreen></iframe>

Spin options

ParameterDefaultOptionsDescription
spindragdrag / hoverMethod for spinning the image.
autospinonceonce / twice / infinite / offAutomatically spin the image.
autospinSpeed3600numericThe time (ms) taken to complete 1 rotation.
autospinStartloadload / hover / click / or combination e.g. load,hoverStart autospin on page load, click or hover.
autospinStopclickclick / hover / neverStop autospin on click, hover or never.
autospinDirectionclockwiseclockwise / anticlockwise / alternate-clockwise / alternate-anticlockwiseDirection of spin.
fullscreentruetrue / falseEnable full-screen spin if large images exist.
zoom2.50-10Zoom level on click (0 = disabled)
magnifytruetrue / falseEnable magnifier if large images exist.
magnifierShapeinnerinner / circle / squareShape of magnifying glass.
magnifierWidth80%% of small image width or fixed size in pxWidth of magnifying glass (if circle or square).
initializeOnloadload / hover / clickWhen to download the images.
speed500-100Speed of spin while dragging (100 = fast).
startColumnautonumeric or autoStart spin with image in src or specify another column.
startRowautonumeric or autoStart spin with image in src or specify another row.
reverseRotationfalsetrue / falseReverse rotation on X-axis.
reverseColumnfalsetrue / falseReverse rotation on X-axis.
reverseRowfalsetrue / falseReverse rotation on Y-axis.
swapRowsColumnsfalsetrue / falseDisplay a vertical spin.
columnIncrement1numericLoad only every second (2) or third (3) column so that spins load faster.
rowIncrement1numericLoad only every second (2) or third (3) row so that spins load faster.
loopColumntruetrue / falseContinue spin after the last image on X-axis.
loopRowfalsetrue / falseContinue spin after the last image on Y-axis.
rightClickfalsetrue / falseShow right-click menu on the image.
smoothingtruetrue / falseSmoothly stop the image spinning.
mousewheelStep3numericNumber of frames to spin on mousewheel.
loadingTextLoading…textText shown while loading.
fullscreenLoadingTextLoading large spin…textText shown while full-screen images loading.
hinttruetrue / falseHide the message & arrows for spinning the image.
hintTextDrag to spintextText shown once images have loaded.
mobileHintTextSwipe to spintextText shown on mobile devices once images have loaded.

How to apply spin options

Choose how you want to apply your options:

  • Profile – save a whole set of options in a profile and apply that to as many spins as you wish.
  • Spin file – edit the options of a spin file. Only that .spin will be edited.
  • URL – attach options to the end of the spin URL. Quick and easy.
  • JavaScript – add a script in your page. This can be useful for gaining advanced programmatic control over the spin.

Spin images

Your spins will be created with 3 sizes of image:

  • Main images – shown within your page
  • Zoom images – shown on click
  • Full-screen images – shown when entering full-screen mode

The dimensions of the images are determined like so:

  • Main images – automatically fits the width or height of the containing element of your page (div/table/spans etc.).
  • Zoom images – automatically created at 2.5 times larger than the main images.
  • Full-screen images – automatically fits the users screen dimensions e.g. a 1366 x 768px display will be served an image to fit inside, either 1366px width or 768px height.

You can change the zoom dimensions by changing the zoom option. Click the example below to zoom in at 4 times magnification:

If you wish to specify your desired zoom magnification in pixels, this can be done like so:

  1. Set the “zoom” option to “1” in the spin options.
  2. Set your desired zoom size under Spin options -> Images -> Zoom image -> Scale.

Zoom is automatically enabled if your original images are at least 20% bigger than the main image. If the original images you uploaded are smaller than this, no zoom or full-screen options will be available.

You can make Sirv scale your images beyond their original dimensions by changing the scale.option to fit, fill or ignore. The maximum size you can scale up to is 10,000px. Scaling images up results in loss of clarity, so the ideal solution is to upload higher resolution images.

Image size

You are recommended to upload your highest resolution images to Sirv (4000px width or larger if you have them). This will allow you to display the sharpest possible images. Modern displays are gaining higher and higher definition, so by uploading your largest images, you are protecting yourself for the future. Consider that some displays already go beyond 5000px:

MacBook Pro (3rd generation) 13″2560×1600 pixels
MacBook Pro (3rd generation) 15″2880×1800 pixels
iMac (Intel-based) Slim Unibody iMac 27″5120×2880 pixels

Not only do high resolution images give beautiful clarity zooms, they will give you greater creative options such as cropping into images in artistic ways.

We recommend minimum, upload 1400px images to enjoy an adequate zoom.

Full-screen button

Sirv displays a button in the top right corner of the 360 spin. The default buttons are:

Full-screen buttons

You can remove the button by setting the Fullscreen option to disabled in either the spin settings or a profile:

You can change the buttons to a different design by adding the following CSS to your page:

<style>
  .sirv-spin-button.fullscreen {
    background-image: url(spin/graphics/buttons06.png);
  }
  .sirv-spin-button.fullscreen-exit {
    background-image: url(spin/graphics/buttons06.png);
  }
</style>

To use your own custom-designed buttons, save your buttons with any name and upload them to any directory of your Sirv account. They should use the same dimensions as the default buttons. For example:

Full-screen buttons

Full-screen background

The enlarged full-screen spin has a white background by default.

The background color can be changed via the CSS style sirv-spin-fullscreen. To change it to black, add the following CSS code to your HTML page:

<style>
  .sirv-spin-fullscreen {
    background: #000;
  };
</style>

Loading bar

A loading bar shows the image download progress.

The position, animation and design of the loading bar can be customized by changing these styles:

.sirv-spin-loading {}
.sirv-spin-progress-bar {}
.sirv-spin-progress-bar-state {}
.sirv-spin-progress-text {}
.sirv-spin-fullscreen .sirv-spin-loading-box {}
.sirv-spin-fullscreen .sirv-spin-progress-bar {}
.sirv-spin-fullscreen .sirv-spin-progress-bar-state {}
.sirv-spin-fullscreen .sirv-spin-progress-text {}

Mousewheel

Spins can rotated with the mousewheel. By default, each click of the mousewheel rotates the spin by 3 frames. This can be changed to any other amount.

To disable mousewheel spin, set mousewheelStep to 0. Here’s a spin with mousewheel disabled:

Show/hide a spin

Your 360 spin will start downloading automatically when the DOM is ready. Once all images have downloaded, it will auto-rotate by default.

Your spin will not download if it is hidden on your page. This is a common scenario when displaying product images in a carousel where the spin is not the primary image (example).

Hidden spins will download on demand. Typically, they would be shown upon click of a thumbnail, button or text link.

Spins can be hidden in many ways, for example with display:none inside a

or another HTML element. You can use JavaScript to show this

when needed.

To avoid the delay of images loading when a hidden spin is requested, you can download hidden spins on page load. One way to do this is to show the spin code as normal (not hidden) and hide it in a visual way, for example with opacity:0.

Another method to control trigger when images are downloaded is to use the Sirv Spin API.

Sirv Spin API

Start/stop spin

Your 360 spin will automatically start downloading when the DOM is ready. Once all images have downloaded, it will auto-rotate by default.

  • Sirv.start() – starts all instances of .Sirv on the page.
  • Sirv.stop() – stops all instances of .Sirv on the page.

If you have multiple spins on the page and need to control a particular one, specify the #id of that spin:

  • Sirv.start(<#id>) – starts the .Sirv instance with a specific #id.
  • Sirv.stop(<#id>) – stops the .Sirv instance with a specific #id.

To turn off autostart on page load, apply this:

<script>
  var SirvOptions = {
    autostart: false
  };
</script>

API methods for spin behaviour

Control the behaviour of a spin, for example with buttons on your spin/page, using these API calls:

  • Sirv.instance(‘#id’).play([frames]) – Rotate by +/-X number of frames on X-axis. If frames are omitted, start infinite spin.
  • Sirv.instance(‘#id’).pause() – Stop rotation.
  • Sirv.instance(‘#id’).rotate(columns, [rows]) – Rotate by +/-X number of frames on X-axis and/or Y-axis.
  • Sirv.instance(‘#id’).rotateX(frames) – Rotate by +/-X number of frames on X-axis.
  • Sirv.instance(‘#id’).rotateY(frames) – Rotate by +/-X number of frames on Y-axis.
  • Sirv.instance(‘#id’).jump(rows) – Jump by +/-X number rows.
  • Sirv.instance(‘#id’).zoomIn() – Zoom in to current frame.
  • Sirv.instance(‘#id’).zoomOut() – Zoom out of current frame.
  • Sirv.instance(‘#id’).fullscreen() – Enter full-screen.
  • Sirv.instance(‘#id’).currentFrame() – Get the current row and column number (currentFrame.row / currentFrame.column).

Where #id is the id of the spin in your div.

Apply it by passing #id, like this:

<div class="Sirv" id="EXAMPLESPIN" data-src="https://sirv.sirv.com/Examples/drill/drill.spin">

<script>
    Sirv.instance('EXAMPLESPIN').play(18);
</script>

Or apply it by passing the reference to the div, like this:

<div class="Sirv" id="EXAMPLESPIN" data-src="https://sirv.sirv.com/Examples/drill/drill.spin">

<script>
   var spin = document.getElementById('EXAMPLESPIN');
    Sirv.instance(spin).play(18);
</script>

Animated GIFs

Sirv can create animated GIFs of your spins. This is great for showing spins where JavaScript is not permitted, such as:

  • Emails
  • Facebook posts
  • Twitter posts
  • Google+ posts
  • Classified ad sites (Gumtree, Craigslist etc)

Sirv automatically generates GIFs of up to:

  • 72 frames
  • 640px/500px width/height

If your spin has more than 72 frames, Sirv will drop some frames, automatically calculating the optimal space between frames for a smoothly animated GIF. If you specify dimensions greater than 640px width or 500px height, Sirv will scale down the GIF to fit within those dimensions.

Create a GIF

To display any of your spins as a GIF, add the ?image parameter to the URL, along with scale.width and/or scale.height. For example, here is a GIF with 300px height:

https://sirv.sirv.com/Examples/drill/drill.spin?image&scale.height=300

360 degree spin - animated GIF

Reduce number of frames

You can reduce the number of frames in a GIF by explicitly setting the number. After the ?image parameter, enter the number of frames the GIF should have. For example, this spin has only 18 frames:

https://sirv.sirv.com/Examples/drill/drill.spin?image=18&scale.height=300

Animated GIF with 18 frames

Reduce GIF file size

Sirv generates very high quality GIFs by default. This gives excellent clarity, however, a GIF with large dimensions and a great number of frames will have a very large file-size. It may be slow to download for your visitors.

To overcome this, consider applying lossy compression. It can reduce the file size by 40-60%, with a small reduction in image quality.

To apply lossy compression, add the gif.lossy parameter to the URL. It’s value can be from 0 to 100, where 0 is no compression and 100 is maximum compression (lowest quality and smallest file-size). This example has 80% compression:

https://sirv.sirv.com/Examples/drill/drill.spin?image&scale.height=300&gif.lossy=80

Animated GIF with 80% lossy compression

Compare that GIF against the previous example and you’ll notice a visible reduction in image quality. The quality differs depending on the images – there is no single ideal compression value for all GIFs – so try a few variations to see what amount of compression suits your images.

Image dimensions also have a big impact on file-size. Compare the difference in file-size of the spinning drill at different dimensions:

WidthFramesFile size without compressionFile size with 80% compressionReduction
120px36103kb65kb37%
256px36368kb201kb45%
350px36625kb316kb49%
500px361220kb577kb53%

Change the GIF design

You can use the entire collection of Sirv dynamic imaging options (speed, watermark, text, frame, scale, crop etc.) to customize your animated GIF. The example below shows a larger image with a text overlay:

360 degree spin - animated GIF

The image URL looks like this:

https://sirv.sirv.com/Examples/drill/drill.spin?image&scale.height=300&text.0.text=Makita%208391D&text.0.position=north&text.0.size=50%&text.0.color=356C78&text.1.text=12%20months%20warranty&text.1.position=south&text.1.size=50%&text.1.color=222222

Add GIFs to a web page

Embed a GIF just like any image, using an img tag, for example:

<img src="https://sirv.sirv.com/Examples/drill/drill.spin?image&scale.height=200" />

Add GIFs to an email

GIFs can be embedded in the content of an HTML with an img tag, like above. However, most email programs and email marketing tools allow you to embed an image simply with the URL. In Gmail for example, the Gmail embed image icon icon lets you add an image from a URL. Try it by copying and pasting this URL:

https://sirv.sirv.com/Examples/drill/drill.spin?image&scale.height=300

Add GIFs to Facebook / Google+

The best way to embed a spin in a Facebook or Google+ post, is to reference the spin file itself. You don’t need to reference a GIF, Sirv automatically serves animated GIFs to Facebook. Try this yourself – go ahead and paste this URL into a Facebook post and when you submit it, you’ll see the animated GIF:

https://sirv.sirv.com/Examples/drill/drill.spin

If a user clicks the GIF, they will be taken to the fully-interactive version of your spin with drag, zoom and full-screen features.

Square GIF thumbnails

Sirv has a thumbnail parameter for quickly creating square thumbnail images. Regardless of aspect ratio, your images will be cropped square from their central point. The thumbnail parameter can be used to create static images or animated GIFs.

The example below creates a 150px square thumbnail of the animated GIF:

https://sirv.sirv.com/Examples/drill/drill.spin?image&thumbnail=150

Image thumbnail, generated on demand

256px is the largest thumbnail size available.

Auto spin

Spins can rotate automatically. By default, one full rotation is shown after all the images have downloaded. You can change this to spin twice, infineitely or turn off auto-spin.

This example shows infinite spin:

https://sirv.sirv.com/Examples/drill/drill.spin?autospin=infinite

First image in spin

Sirv has a thumb parameter to automatically serve the first image in a spin. This image will always match the image the user sees when a spin loads.

The thumbnail can be any size and can have any of the Sirv dynamic imaging settings applied to it.

To fetch the first image of a spin, enter ?thumb after the .spin reference. For example:

https://sirv.sirv.com/Examples/drill/drill.spin?thumb

Resize the image with the usual Sirv dynamic imaging options, for example:

https://sirv.sirv.com/Examples/drill/drill.spin?thumb&scale.width=200

Image at 200px width

Apply any other Sirv dynamic imaging settings as you wish, for example:

https://sirv.sirv.com/Examples/drill/drill.spin?thumb&scale.width=200&text.text=360&text.color=black&text.position=center&text.size=90&text.opacity=70&text.outline.width=4&text.outline.color=white&text.outline.blur=2

Image with text overlay

By default, the first image is column 1. In the case of a 3D spin, the first image is column 1, row 1. To choose another image, right-click the spin, choose Edit and choose the start row and start column:

When you choose an image, the settings are saved in the .spin file.

You can also update the .spin file directly itself – it is a JSON text file. This can be used to automate your workflow for example with a local application you use for managing your spins.

Text overlays

You can overlay text or image layers to your spins to display things like product names, copyright information or logo watermarks.

Apply text overlays either by creating a profile or editing the .spin file. A profile is usually best because it permits you to apply the same settings to multiple spins.

Example of a spin with a text profile:

Multi-language

You can display text in different languages by creating a profile for each language you wish to provide. Each profile can contain different UI messages (e.g. Swipe to spin) or button alt text (e.g. Full-screen). Once you’ve created your profiles, one for each language, serve the profile for the language the customer requires. For example, if you named your profile “spin-spanish”, append it to the URL like so:

https://sirv.sirv.com/Examples/drill/drill.spin?profile=spin-spanish

Retina images

Sirv automatically creates and serves hi-res images to retina devices. These images have 4 times the number of pixels as normal resolution images, so they look very sharp on iPhone, iPad and other retina screens.

Retina images have larger file sizes than standard images. To compensate for this, Sirv automatically applies stronger image compression to reduce their large size. This reduction in JPEG/WebP quality to 60% has a very subtle and usually indistinguishable effect on image quality, so users will see stunningly sharp images which load quickly.

JSON .spin files

The .spin text files automatically generated by Sirv use JSON code to reference the images in your spin and any additional settings for the spin.

When you edit files in your Sirv control panel, the JSON code is updated. You don’t need to write or edit any JSON code under normal Sirv usage.

You’re able to create and edit .spin files manually. This can be useful for programmatically automating the creation and management of many spins. You can open .spin and .profile files in a text editor to see how they are structured. You can create brand new .spin files by following the format Sirv uses to construct a spin file.

Example spin file:

{
  "pattern": "^animated\ wallet\-(\d+)\.jpg$",
  "layers": {
    "1": {
      "1": "Animated Wallet-1.jpg",
      "2": "Animated Wallet-2.jpg",
      "3": "Animated Wallet-3.jpg",
      "4": "Animated Wallet-4.jpg",
      "5": "Animated Wallet-5.jpg",
      "6": "Animated Wallet-6.jpg",
      "7": "Animated Wallet-7.jpg",
      "8": "Animated Wallet-8.jpg",
      "9": "Animated Wallet-9.jpg",
      "10": "Animated Wallet-10.jpg",
      "11": "Animated Wallet-11.jpg",
      "12": "Animated Wallet-12.jpg",
      "13": "Animated Wallet-13.jpg",
      "14": "Animated Wallet-14.jpg",
      "15": "Animated Wallet-15.jpg",
      "16": "Animated Wallet-16.jpg",
      "17": "Animated Wallet-17.jpg",
      "18": "Animated Wallet-18.jpg",
      "19": "Animated Wallet-19.jpg",
      "20": "Animated Wallet-20.jpg",
      "21": "Animated Wallet-21.jpg",
      "22": "Animated Wallet-22.jpg",
      "23": "Animated Wallet-23.jpg",
      "24": "Animated Wallet-24.jpg",
      "25": "Animated Wallet-25.jpg",
      "26": "Animated Wallet-26.jpg",
      "27": "Animated Wallet-27.jpg",
      "28": "Animated Wallet-28.jpg",
      "29": "Animated Wallet-29.jpg",
      "30": "Animated Wallet-30.jpg",
      "31": "Animated Wallet-31.jpg",
      "32": "Animated Wallet-32.jpg"
    }
  },
  "settings": {
    "retina": false
  }
}

Likewise, you can create and edit .profile files. These JSON files can contain spin settings, allowing you to apply the same profile to many spins and have all the settings stored and updatable in one place.

Example .profile file:

{
  "spin": {
    "images": {
      "fullscreen": {
        "canvas": {
          "height": "66.666%"
        }
      },
      "zoom": {
        "canvas": {
          "height": "66.666%"
        }
      },
      "main": {
        "canvas": {
          "height": "66.666%"
        }
      }
    },
    "startRow": "2",
    "hintText": "Drag to spin",
    "zoom": 2.5,
    "retina": false
  }
}

Example profile with a text overlay:

{
  "image": {
    "text": {
      "text": "Also available in black",
      "style": "simple",
      "position": "south",
      "size": "60%",
      "font": {
        "family": "Lato"
      },
      "color": "black",
      "opacity": 50
    }
  },
  "spin": {
    "autospin": "infinite",
    "autospin-speed": "10"
    "zoom": 2.5
  }
}

To take a closer look at .spin and .profile files, download them and open them in a text editor. The files can be uploaded and downloaded just like any other file, by FTP, S3 or through your Sirv control panel.

The example below shows the settings section of the .spin file, with infinite spin, faster speed and magnifier and full-screen disabled:

{
  "settings": {
    "autospin": "infinite",
    "autospinSpeed": 2000,
    "autospinStart": "click",
    "magnify": false,
    "fullscreen": false
  }
}

These same settings could be applied in a profile like so:

{
  "spin": {
    "autospin": "infinite",
    "autospinSpeed": 2000,
    "autospinStart": "click",
    "magnify": false,
    "fullscreen": false
  }
}

The example below has hover to spin, faster speed and a round magnifier:

{
  "spin": {
    "spin": "hover",
    "speed": 60,
    "magnifierShape": "circle"
  }
}

Disable spin detection

If you’re not using Sirv for 360 spins, you can turn off the automatic creation of .spin files like so:

  1. Go to your Sirv account.
  2. Right-click the folder containing your images.
  3. Click “Options”.
  4. Set “Scan for spins” to “Never” (screenshot below).

Get expert help

If you need assistance with Sirv spin, please contact our support team from your account.

Was this article helpful?