C. Using a Picture to make a Story Panorama (Gigapixel)

This module explains how to create an online exhibition which tells a story based around a picture, or non-georeferenced map.

Estimated time: 1 hour

About Gigapixel and Story Panoramas

This module creates a story panorama using the Gigapixel option in the free StoryMapJS tool by KnightLab. The lesson assumes familiarity with the core features of StoryMapJS covered in previous modules of this tutorial.

Just as a storymap tells a story based around a map, a story panorama tells a story based around a picture. Story panoramas are used to communicate information about an image in a visual way, and tells a story or explains an idea using an annotated image. The Gigapixel option in StoryMapJS makes a story panorama.

In a story panorama, we use an image instead of a map to anchor the set of slides. The navigation in a Gigapixel story panorama is just like navigation in a storymap. Visitors can follow through the slides in sequence, or use the marker pins on the reference image on the left to jump to a specific part of the image.

We might use a story panorama to:

  • Tell a historical story around an image
  • Explore or analyse a work of art
  • Create a storymap using an image file of a historical map

You can also use the Gigapixel option to make a StoryMap around a map which has not been georeferenced. (To use your own georeferenced map for a StoryMap, see Using Your Own Map.)

How to use your image with StoryMapJS

This module assumes you are already familiar with StoryMapJS.

To make a story panorama with StoryMapJS, you need to prepare the image. You will need:

  • A high-quality image.
  • The size of your image in pixels.
  • A Zoomify tile version of your image (see Part I to create this). StoryMapJS can only use images in this format.
  • A public host for your Zoomify tiles (Part II). You cannot upload the panorama image directly to StoryMapJS.

Part I: Preparing Your Image

In this part, we will see how to prepare an image for use on StoryMapsJS.

Estimated time: 10-30 mins

Choosing Your Image

To build a story panorama around an image such as a painting, a photograph, or a historical map, you will need a high-quality image. Your image doesn’t need literally a billion pixels (‘gigapixel’), but the higher the resolution, the better it will look. Very large images will take longer to process and to upload.

Getting the Image Dimensions

To get the dimensions of your image in pixels, locate the image file on your computer and right-click on it (Mac: Ctrl+click). Go to the image tab: this will state the image dimensions (width and height) in pixels.

Make a note of these. You will need these dimensions later in StoryMapJS.

Making Your Tile Image

StoryMapJS builds your story panorama using image tiles. Instead of one single large image, StoryMapJS stiches together your panorama out of lots of individual tiles covering different parts of the image.

StoryMapJS can only use tiles in the Zoomify format. Zoomify is a commercial format which is often used by archives and libraries to provide access to large images.

To generate a set of Zoomify tiles from your chosen panorama image, you can use:

– with Zoomify Free (Windows or Mac)

Once you have downloaded the software, unzip the folder. Then drag and drop your image file onto Zoomify Free Converter. The app will create a tile set for you.

Make a note of the name of the folder containing the tile set, and where it is saved on your computer.

– with Zoomify Export in Photoshop

Zoomify-format export is included in Photoshop CS3 and later (plugin details).

Using Zoomify export in Photoshop (more details):

  • Open your image in Adobe Photoshop.
  • From Photoshop’s File menu choose Export > Zoomify
  • The Template option can stay unchanged.
  • For Output Location, choose the folder where you want your tile set folder to be created. Click OK.
  • For Base Name, give the name you want for the tile set you are creating, e.g. “Image-Zoomify”.
  • The Image Tile and Browser options can stay unchanged.
  • Click OK.
  • Photoshop will open a browser window in which Zoomify will attempt to show your tiled image using a Flash plugin. Some systems and browsers (e.g. Mac OS) cannot display the tiled image, so do not worry if your image does not display. Exit the browser window.

Your tiled set folder should be saved on your computer, with the Output Location and Base Name you specified.

– with command line tools

ZoomifyImage (command line)

ZoomifyImage needs Python and PIL. If you’re not familiar with these, you may prefer to use VIPS instead (below).

Download the ZoomifyImage tarball and extract it somewhere convenient. In the command line, move into your new ZoomifyImage directory. Now enter:
python ZoomifyFileProcessor.py IMAGE
replacing IMAGE with the full path to the image file you want to zoomify.

Your tile set will be created as a new sub-directory in the same directory as your image file. Make a note of the name and the location of the folder containing the tile set.

VIPS (command line)

VIPS is a versatile image processing package, accessed through the command line.


  • Linux: VIPS is on distro repositories as libvips*, or can be built from source.
  • Mac: Installation with Homebrew.
  • Windows:
    — Download the VIPS for Windows zip file. It will be called something like vips-dev-w64-all-8.x.x.zip.
    — Extract the .zip fie to a convenient location. The extracted VIPS folder will have a title like vips-dev-8.x.
    — Open a command line/ terminal window.
    — Either: a) move into the bin sub-directory of your VIPS directory; or b) add VIPS to your PATH.

Usage: To use VIPS from the command line to make Zoomify tiles, enter:
vips dzsave EXISTING_IMAGE NEW_FOLDER --layout zoomify
replacing: EXISTING_IMAGE with the full path to the image file you want to zoomify; and NEW_FOLDER with the full path to a folder name you want VIPS to create for your new Zoomify tile set.

Checking your Zoomify tile set

Your tile set will be a folder containing an .xml file and one or more subfolders with titles like TileGroup0. Inside the subfolders you will find image tiles for each part of your original image.

Check whether the name of the tile set folder includes spaces or special characters. Web hosting will be simpler if you edit the name to remove these characters. Do not edit the names of the files or subfolders inside the tile set.

Congratulations! You have turned your image into a tile set which can be used with StoryMapJS.

Part II: Hosting Your Image Tiles

In this part, we will see how to host an image tile set so that it becomes available for use on StoryMapsJS. This step will make your image publicly accessible on the web.

Estimated time: 10-30 mins

How to host your images

Now you have a folder with a Zoomify tile version of your image. The next step is to make that folder accessible on the web.

You cannot upload your image directly to StoryMapJS. Instead you need to host your image tile set on a different website. StoryMapJS will access the image tiles every time your story panorama is edited or viewed.

Any public web hosting will work with StoryMapJS. You can use:

Amazon Web Services

You can use AWS to host an image for StoryMapJS. AWS offers a free tier.


You can use GitHub to host an image for StoryMapJS. GitHub offers a free tier.

Any web server

If you already have access to a web server, simply upload the folder containing your set of image tiles. Make sure the folder is publicly accessible and that the file hierarchy is preserved.

Make a note of the base URL for the image tiles (i.e. http://WEBSITE/TILES_FOLDER) where WEBSITE is the URL for your website and TILES_FOLDER is the name of the folder containing the image tiles. You will need this in a moment in StoryMapJS.

To test your new tile images, enter the following URL:
A small version of your image should load.

If you do not have a server already, free hosting is provided by several companies, e.g. Neocities.

Testing your server

To test your new image server, use a web browser to navigate to:
http://WEBSITE/TILES_FOLDER/TileGroup0/0-0-0.jpg , where WEBSITE is your server and TILES_FOLDER is the directory containing your tiles. A small version of your image should display.

Congratulations! You have now hosted your image successfully.

Part III: Creating Your Story Panorama

In this part, we will set up a story panorama using the Gigapixel option in StoryMapJS.

Estimated time: 10 mins

Creating Your Gigapixel story panorama

Log into the StoryMapJS web authoring tool and either create a new storymap or open an existing one.

WARNING: If you change a storymap to a Gigapixel story panorama, you cannot change it back into a storymap. You will not be able to restore a map under your slides instead of an image. To experiment with changing a storymap into a story panorama, first copy your storymap using the Settings icon next to that storymap on Your Storymaps.

Go to Options/Map Type and select Gigapixel. Some new options will appear.

Under Zoomify URL, enter the base URL for the tile image folder you uploaded to the Web in the previous module. This will be something like http://WEBSITE/TILES_FOLDER

Under Max Image Size, enter the original dimensions (width and height) of your image, which we retrieved in Module A. If these are incorrect, the image may not display correctly.

Click Close, and your Gigapixel story panorama will be created.

Completing your Gigapixel

You can now add content to your slides, just as we did in the previous lesson.

Most StoryMapJS options are discussed in the previous modules. In Gigapixel mode, you will be offered the following additional choices under Options:

  • Map Background Color: a hexadecimal colour, to display around your reference image.
  • An Attribution box is available to give credit to the owner of the image as required.
  • An explanation of the Treat as Image / Cartography option is provided here.

When you have finished, you can publish your Gigapixel story panorama in the same way as any other StoryMap.

You have now completed your Gigapixel story panorama.