Tiling High-Resolution Images for Knightlab StoryMapJS

The Problem

Knightlab StoryMap JS is an excellent tool for quickly and easily creating basic storymaps, which combine spatial data with text and various multimedia. One feature that makes it particularly useful is the ability to import high-resolution imagery as tiles from sites like the David Rumsey Map Collection or the New York Public Library. However, when importing these maps, Knightlab StoryMap automatically sets the maximum zoom level to what it thinks is "appropriate" based on the size of the map. This does not allow the user or the creator to take advantage of such high-resolution images.

The solution has three steps:

1. To create your own high-resolution map tiles

2. To host your tiles on Github

3. To import your tiles as a Gigapixel map into Knightlab

To Create Tiles of your Map...

...using Adobe Photoshop (2020 and earlier)

There are two ways to go about creating your own tiles. If you have access to Adobe Photoshop, the process is quick and easy.

• Download your image as a .tiff/.geotiff file from a site like David Rumsey or the NYPL, or use your own image.

• Open your image in Adobe Photoshop.

• Write down the size of your image in pixels. This can be seen by going to Image-->Image Size in the main toolbar. The width and height should then be displayed; make sure your units are in pixels! You'll need this information for adding your tiles to your storymap later.

Photoshop makes it easy to see the size of your image and export it in tile form

• It's time to Zoomify your map! Just go to File --> Export--->Zoomify and the Zoomify export menu will pop up. Here you can set the export folder where your tiles will be sent to, as well as the Image Quality. For high-res images, you might as well use the highest quality possibly. Once you are ready, hit Ok. A web browser may pop up, but you can close it. If you navigate to the location where you saved your files, you should now see a series of folders containing your tiles!

The Zoomify export menu lets you set where to save your tiles

Once exported, your tiles will appear in a series of TileGroup folders

...using Zoomify Free (Windows only)

If you do not have access to Photoshop, don't despair! Zoomify has a free tool you can download which will perform the same tiling as photoshop does.

• Go to Zoomify and download their free tool for Windows or Mac

• Once downloaded, open the Zoomify Free Converter application on your computer

• After downloading your high-resolution image, drag and drop the downloaded file onto the converter (or use File-->Open). The tiling will begin automatically and will save to the folder where your image is located. And you are done!

Just drag and drop and your image will be tiled!

...using OSgeo4W/gdal2tiles (Windows)

OSGeo4W is a distribution of a broad set of open source geospatial software for Windows environments (Windows 10 down to XP). OSGeo4W includes ​QGIS, ​GDAL/OGR, ​GRASS as well as many other packages (over 150).

To tile your image using OSgeo4w, follow these steps:

1. Install Osgeo4w from the OsGeo Website

2. Save your georeferenced map to a known location on your computer by exporting it from ArcGIS, QGIS, or MapWarper (see our tutorial for georeferencing maps in MapWarper).

3. Open up the Osgeo4w command line from the start menu

4. Navigate the command line to the folder where your raster image is stored using the cd ('change directory') command (e.g. cd c:\temp\saved\testImageFolder)

5. Type “gdal2tiles -geodetic imageToBeTiled.tif FolderName” where imageToBeTiled.tif is your exported georeferenced image and FolderName is the Folder you want to be created to hold the tiles

   1. To add control for what zoom levels are created add: -z 2-15 after -geodetic. This example would create tiles for zoom levels 2 through 15

6. Your image is now tiled! A variety of test maps are automatically created in your folder holding the tiles which you can drag and drop into a browser. In some cases, tiling a .jpg may work better than tiling a .tiff, especially if you have self-georeferenced the image.

...using Maptiler (Windows and Mac)

Maptiler has a free version that you can download for both Windows and Mac. On the plus side, it works with Macs unlike some other tools; on the downside, it has its own restrictions.

The free version of Maptiler restricts the size of your image in pixels (10k x 10k) and file size (30 MB), as well as creates a watermark on your tiles. It also does not let you control the zoom levels which are created, meaning that smaller maps (e.g. portions of a city) cannot be tiled appropriately. It also requires spatial data for the map, meaning that you must georeference your image either within the platform or on software like ArcGIS or QGIS.

Yet, it is quite user-friendly otherwise. Simply drop your image into the window after opening...

Just drag and drop your map file, as long as it meets the requirements

...and you will be asked about spatial data. If you previously georeferenced your image in ArcGIS, it will automatically detect the spatial data; otherwise, you will need to match up your map with a full-world map using control points. This is, however, quite easy for larger maps, just click the location on your image, then on the world map, and those locations will be linked together. It is recommended to choose at least 4 points scattered across your map.

Adding control points for a map of the Boston region

Once you have added enough points and hit "Continue," you will be asked how you want to export your map. For our purposes, a "Folder with tiles" is fine (MBtiles is for Mapbox, OGC GeoPackage is for SQL databases, neither of which we are concerned with here.

File export options

Once you choose your folder, your image tiles will be exported!

To Host your Tiles on GitHub

So you have your tiles; now you need to make them publicly accessible online so your storymap can access them! To do this, we want to use the free hosting site Github. We will be hosting the tiles created through Zoomify Free here.

• Sign up to create an account on Github.

• Start a new project either by pressing the “Start a project” button or, if you already have a Github account, clicking on the plus sign in the top right and selecting “New repository.” Give it an identifying name and make sure it is set to "Public"

Create a new repository for your files

• If you’re new to Github, download Github Desktop, which lets you upload many files at once. Once installed, go to the “Code” button in your online depository and click “Open in Desktop.” Allow the site to open Desktop for you, and click "Clone". This will create a copy of your repository on your computer.

Open your repository in Github Desktop

• Once your repository is open in Github Desktop, you can open the folder in your Finder/Explorer window by clicking the "Show in Explorer" button on the right side of the screen. This folder is often located in a folder named "Github" in the Documents section of Explorer in Windows. Once you’ve located the folder on your computer, move all the files and folders generated by Zoomify into your repository folder.

Open your repository in Github Desktop and then copy your Zoomify files to it

• Once your files are copied, return to the Github Desktop application. You should now see a series of files that have been changed in your repository, all the files you just copied over! In the “Summary” field, type a descriptive message of your content. Then click “Commit to Main” to upload your files. This process may take a few minutes depending on the size of your files. Finally, when a blue button appears, click "Push Origin" to push your files to the online version of the repository.

Once the files are copied, click "Commit to main" and then "Push Origin"

When the "Push origin" button appears, click it!

• Once your sync has completed, return to your online github repository and you should see your tile folders. The final step is to make these files publicly available with a URL. Navigate to the "Settings" tab and scroll down to the “Github Pages” section. Create a page for your project by selecting the source branch (main) and clicking “Save.” After the page refreshes, scroll back down to the Github Pages section and you will find the url you can use to create your Gigapixel (Note: clicking on this link directly will take you to an error page saying that Github can’t find what you’re looking for. This is normal.).

Go to the Settings tab...

...scroll down to Github pages, select the Main branch and save

The page will refresh; scroll down for your URL

To Load your Tiles in Knightlab StoryMap JS

Now you have made your tiles and hosted them on Github; the last step is to load them into Knightlab. (Note: this tutorial assumes you are familiar with StoryMap JS; if you are not, see our tutorial on StoryMap JS here)

• Go to Knightlab Storymap JS and create a new StoryMap

• From the Options menu, where you select your background map image, change the Map Type to Gigapixel, insert the URL for your github tiles into the Zoomify URL box, and finally, under Max Image Size, insert the width and height of the original image in pixels. This can be found by opening the file in Photoshop (see above) or by looking at the Details tab under the Properties of the original image.

• Make sure "Image" is chosen under the "Treat As" option, as we are using a map that does not have any real spatial data attached

And you are done! You should now be able to zoom in much closer into your high-resolution image on each slide of your storymap.