1 of 1

Hosting and Displaying Zoomable Images on Your Webpage

This tutorial goes along with the tutorials Tiling High-Resolution Images for Knightlab StoryMapJS.

Problem

So, you have some tiles of a high-resolution image, now you need to allow other people to see those high-resolution images in a zoomable viewer. While the previous tutorial (linked above) allowed you to import your image into KnightLab StoryMap JS, sometimes you want to display the image on your personal site. This tutorial will show you how to create an iFrame embed that can be used on sites like CampusPress or Omeka, with your tiles hosted in GitHub (as with the StoryMap example).

Here we will review 3 tools that can help you achieve this goal: Zoomable, Zoomify, and Leaflet

Using Zoomable

Zoomable (https://zoomable.ca) allows users to quickly create zoomable images, but it is free version is limited (5 uses per email). Various plugins for sites like WordPress and Knightlab do exist but must be purchased individually. The free version also does not allow you to host your own images, so you are beholden to their servers functioning. However, it is a very quick process if you only have a few images.

Go to the free Zoomable upload page (https://srv2.zoomable.ca/upload_new.php)
Upload your image (30MB max; supports JPG/PNG/TIF) and enter your email address
An email containing your zoomable image will be sent to you; once it has, click on the included link (Example from San Francisco Chinatown Image)
In the top-right corner is the "embed image" button. Clicking this button will give you an iFrame embed code that you can copy and paste into your website html (for information on iFrame html code, see this page for examples)

Pros: Very fast and very little coding required (only iFrame embed); don't need to tile the images yourself

Cons: Minimal free service, don't control your own tiles

Check out our example CampusPress page for what this embed looks like

Using Zoomify

Our old friend Zoomify (last seen in the previous tutorial where we used Zoomify Free to tile an image) also provides us the basic information we need to host our image on a site like GitHub. When you download Zoomify free, it comes with a variety of other files, including a javascript file (ZoomifyImageViewerFree-min.js) and an HTML file (TemplateWebPage.htm). The files are linked below for your reference.

In order to visualize our image using the Zoomify web viewer, we need to create a GitHub repository that contains (1) our tiles, (2) the javascript file linked above, and (3) an HTML file specific for our image.

First, we need a GitHub repository to put our image. If you are unfamiliar with GitHub, the previous tutorial walks you step by step on how to create an account, create a repository, and download Github Desktop to make everything easier. It also shows you how to upload your tiles, which we will do again here.

For this tutorial, I've created a Tiling and Mapping GitHub repository and linked it to my Github Desktop. I will now copy into it the tiles created in the previous tutorial and the Javascript file linked above.

Now we need to create an HTML file that will contain our zoomable image. Luckily, this is easier than it might sound because Zoomify has already done most of the work for us! First, open up a blank text document to create your file. I reccomend using Atom (any iOs) or Notepad++ (PC only) as these text editors are helpful for coding. I'm going to save mine as zoomifySanFran.html in my repository folder (make sure you save it as an html file and not a text file!)

Copy the following code into your html file, which is directly copied from the example html file supplied by Zoomify and save your file.

<!DOCTYPE html>
<html xml:lang="EN" xmlns="http://www.w3.org/1999/xhtml" lang="en">

	<head>
		<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />

		<!--COPY ME INTO HEAD--><script type="text/javascript" src="ZoomifyImageViewerFree-min.js"></script>
		<!--COPY ME INTO HEAD--><script type="text/javascript"> Z.showImage("myContainer", "ZoomifyImageExample"); </script>

	</head>

	<body>

		<!--COPY ME INTO BODY--><div id="myContainer" style="width:900px; height:500px; margin:auto; border:1px; border-style:solid; border-color:#696969; background-color:#000000;" ></div>


	</body>
</html>

In order to load your file into the viewer, you only need to change 1 line of code! In line 8, where it says ZoomifyImageExample, change the name of the folder to the folder containing your tiles; in my case, that is sanFran (see above), so the code line 8 ends up looking like:

		<!--COPY ME INTO HEAD--><script type="text/javascript"> Z.showImage("myContainer", "sanFran"); </script>

Save your HTML file, and sync it with GitHub as described in the previous tutorial (Commit to Main-->Push Origin in your Github Desktop window). Once synced, your GitHub repository will look something like this:

Now if you have published your page in the settings tab, your image should now be viewable in the viewer using the HTML page for your site + the name of the webpage you created; in my case, this is: https://bcdigschol.github.io/tilingMappingWorkshop/zoomifySanFran

Once it is hosted on GitHub, you can embed it as an iFrame on any website you want, with the syntax being as follows (where you can replace the URL with your own file URL, and the title with your own title)

<iframe src="https://bcdigschol.github.io/tilingMappingWorkshop/zoomifySanFran" title="Self-tiled San Francisco Chinatown Image" width="900px" height="500px"></iframe>

To see an example iFrame embed, see our Test CampusPress Page.

And that's it! You can use the same repository for all of your images if you wish, just make a separate .html file that you can use for your iFrame embed!

Using Leaflet

Leaflet is the leading open-source JavaScript library for mobile-friendly interactive maps. Weighing just about 39 KB of JS, it has all the mapping features most developers ever need.

For more details about setting up an interactive leaflet map and adding spatial data, check out our tutorial on the subject. Here we will just be using the viewer to view a tiled image.

Let's return to our depository, but this time we will download the leaflet javascript package as well as a plugin for viewing tiled images

Download Leafletjs and the Zoomify leaflet plugin (Code --> Download .zip file). Drop them into your repository folder with your tiled images.

There are lots of other leaflet plugins for viewing tiled images and doing lots of other stuff as well. Check out the Leaflet Plugin Page

Like the previous example, this plugin comes with a nice example script for your html. You can find it in the downloaded folder (example.html) or can copy it from below. As before, you want to create a new html file. I called mine "leafletZoomifySanFran.html"

<!doctype html>
<html>
<head>
    <meta charset="utf-8">
    <title>Leaflet 1.0.0-b1 Zoomify Demo</title>
    <link rel="stylesheet" href="http://cdn.leafletjs.com/leaflet-1.0.0-b1/leaflet.css" />
    <style type="text/css">
        html, body, #photo {
            width: 100%;
            height: 100%;
            padding: 0;
            margin: 0;
        }
    </style>
</head>

<body>
    <div id="photo"></div>
    <script src="http://cdn.leafletjs.com/leaflet-1.0.0-b1/leaflet-src.js"></script>
    <script type="text/javascript" src="L.TileLayer.Zoomify.js"></script>  
    
    <script type="application/javascript">
		var map = L.map('photo', {
        	maxZoom: 15, //Does not matter anymore, maxNativeZoom prevents loading of missing zoom levels
	        minZoom: 0,
   	     	crs: L.CRS.Simple //Set a flat projection, as we are projecting an image
    	});
    	
    	//Loading the Zoomify tile layer, notice the URL
    	var layer = L.tileLayer.zoomify('http://thematicmapping.org/playground/zoomify/books/{g}/{z}-{x}-{y}.jpg', {
			width: 5472,
			height: 3648,
			attribution: '&copy; Photo: Bjørn Sandvik'
		}).addTo(map);

		//Setting the view to our layer bounds, set by our Zoomify plugin
		map.fitBounds(layer.options.bounds);
    </script>
</body>
</html>

Now, there are a few changes we want to make to alter the code for our needs.

On lines 5, you can change the Title of the page to whatever is appropriate for your image
On lines 6 and 19, you should change the URL to point to the local version of leaflet you have downloaded into your repository. This means it will look something like "./leaflet/leaflet.css" and "./leaflet/leaflet-src.js" depending on the name of your leaflet directory inside your repository
On line 20, make sure "src" points to the location of the downloaded Leaflet Zoomify Plugin. In my case, I changed it to "./Leaflet.Zoomify-master/L.TileLayer.Zoomify.js"
On line 30, you need to change the URL to your github repository folder containing the tiled images. In my case, this was "https://bcdigschol.github.io/tilingMappingWorkshop/sanFran/{g}/{z}-{x}-{y}.jpg"
Finally, on lines 31, 32, and 33, change the information to the width, height, and attribution of your image, which can be found in the Properties or Info of your image.

The final version of my script is as follows:

<!doctype html>
<html>
<head>
    <meta charset="utf-8">
    <title>Leaflet Zoomify San Fran Demo</title>
    <link rel="stylesheet" href="./leaflet/leaflet.css" />
    <style type="text/css">
        html, body, #photo {
            width: 100%;
            height: 100%;
            padding: 0;
            margin: 0;
        }
    </style>
</head>

<body>
    <div id="photo"></div>
    <script src="./leaflet/leaflet-src.js"></script>
    <script type="text/javascript" src="./Leaflet.Zoomify-master/L.TileLayer.Zoomify.js"></script>

    <script type="application/javascript">
		var map = L.map('photo', {
        	maxZoom: 15, //Does not matter anymore, maxNativeZoom prevents loading of missing zoom levels
	        minZoom: 0,
   	     	crs: L.CRS.Simple //Set a flat projection, as we are projecting an image
    	});

    	//Loading the Zoomify tile layer, notice the URL
    	var layer = L.tileLayer.zoomify('https://bcdigschol.github.io/tilingMappingWorkshop/sanFran/{g}/{z}-{x}-{y}.jpg', {
			width: 13463,
			height: 5952,
			attribution: 'David Rumsey'
		}).addTo(map);

		//Setting the view to our layer bounds, set by our Zoomify plugin
		map.fitBounds(layer.options.bounds);
    </script>
</body>
</html>

Sync your repository and then your image should be visible on the web (https://bcdigschol.github.io/tilingMappingWorkshop/leafletZoomifySanFran.html)

And the iFrame works the same way as previously!

<iframe src="https://bcdigschol.github.io/tilingMappingWorkshop/leafletZoomifySanFran" title="Self-tiled San Francisco Chinatown Image" width="900px" height="500px"></iframe>

See the results on our embed test page!

That's all for now. Please contact Matt Naglak, Digital Scholarship Librarian (naglak@bc.edu) if you have questions or come across any errors. And check out our other tutorials!