Embedding and Hosting Gigapans

Generate the code to Embed a gigapan Enter a gigapan.org gigapan id, get back code you can paste into your si te to embed a gigapan.

This is an embedded gigapan. There is a reference in the HTML code to the Flash gigapan viewer along with the parameters needed to allow the gigapan viewer (a modified version of Paul Neave's Flash Earth viewer ) to show the gigapan. You can embed your own gigapans in your own page by Following the Instructions in the Gigapan Panorama Embedding page.

Here is the code required to embed the Marriot Panorama in this page:


        <embed type="application/x-shockwave-flash"
        src="http://gigapan.org/viewer/PanoramaViewer.swf?url=http://share.gigapan.org/gigapans0/2477/tiles/&suffix=.jpg&width=57029&height=16095&nlevels=9&cleft=0&ctop=0&cright=57029.0&cbottom=16095.0"
        height="300" width="100%">

Understanding the Embedding Code

Here is that same code, split into pieces:

<embed type="application/x-shockwave-flash": We are using the embed tag to embed a Flash applet in the page.
src="http://gigapan.org/viewer/PanoramaViewer.swf: The URL of the Flash applet. If you wanted to write your own tiled Flash viewer you would replace this url with your own.
?url=http://share.gigapan.org/gigapans0/2477/tiles/&suffix=.jpg&width=57029&height=16095&nlevels=9&cleft=0&ctop=0&cright=57029.0&cbottom=16095.0": The items after the question mark are the parameters which are passed to the 'PanoramaViewer' flash applet.
url=http://share.gigapan.org/gigapans0/2477/tiles/: The url for our tiles. This is on the gigapan server, but you can host your tiles on your own server. The image pyramid is created when you stitch a gigapan. The uploader uploads each of of the individual tiles to the server. It appears that the tiles are uploaded in the same directory structure as when they are stitched, the only difference is that the panorama id is the base directory, rather than 'yourname.data.' In this case 2477 is the gigapan id for this panorama.
&suffix=.jpg: Our tiles are jpegs. This implies that flash earth supports other tile image formats.
&width=57029&height=16095: Width and Height of our gigapan - the dimensions of the exported TIF. &nlevels=9
nlevels=9: Number of zoom levels to support (see below for more on levels)
cleft=0&ctop=0&cright=57029.0&cbottom=16095.0: The window where you want to start viewing the image. In this case the whole image will be shown.

Hosting your own Gigapans

The Gigapan project wants you to host your gigapans on their site for a number of reasons. But sometimes that won't work. I had to figure out a way to host my own gigapans because I had gigapans which were too small to upload (you must have a 50 megapixel image or greater. How cool is it that they run a site with a _minimum_ file size!).

Gigapan.org simply stores a copy of the tiles directory for your gigapan. You can put your gigapans on your own server and point the URL parameter at your server. This non-giga pan was only six images. I wanted to capture the contents of the white board after a talk at Where Camp, but my lens is not wide enough to get it all in one shot. Gigapan to the rescue! (hosted locally):

The code is: <embed type="application/x-shockwave-flash" src="http://gigapan.org/viewer/PanoramaViewer.swf?url=http://geocoder.us/gigapan/pans/wherecamp_07_paige_board.data/tiles/&suffix=.jpg&startHideControls=0&width=6247&height=3245&nlevels=6&cleft=0&ctop=0&cright=6247.0&cbottom=3245.0", height="300" width="100%">

Browsing the Image Pyramid

The tiles directory, either on your local drive after stitching or http://share.gigapan.org/giapans0//tiles contains the Image Pyramid. The Image Pyramid contains 256x256 pixel jpeg tiles for the whole image at each zoom level.

Different images have different numbers of zoom levels. The more pixels the more zoom levels. See the 'nlevels' parameter for a particular image. See 'tile math' below.

These images are named in a Quadtree fashion. The initial full image is r.jpg. To zoom in the image is split into four pieces. Add a digit to the filename from 0-3. Whee 0 is the upper left, 1 the upper right, 2 lower left, and 3 lower right.

Here is an example of the naming structure for zoom level one (r), two (r0), and three (r00), along with matching tiles from a sample image.

r

r0 r1

r2 r3

r00 r01

r02 r03

r10 r11

r12 r13

r20 r21

r22 r23

r30 r31

r32 r33

Direct Access To Tiles

Tiles live on the gigapan server. Here is a link to the top level tile for the above gigapan 2770.

http://share.gigapan.org/gigapans0/2770/tiles/r.jpg

And here is direct link to a tile further down:

http://share.gigapan.org/gigapans0/2770/tiles/r01.jpg

In order to have a manageable number of files in a directory each three digits (including the 'r') or three zoom levels, the tiles are split into subdirectories. So to get the next level down requires another level in the url:

http://share.gigapan.org/gigapans0/2770/tiles/r01/r010.jpg

You can then descend three more zoom levels by just changing the file name. This image could be read as the top right of the top right of the lower left of the upper left of the full image :-)

http://share.gigapan.org/gigapans0/2770/tiles/r01/r01211.jpg

Because the name is now 6 characters we need to drop down a directory level in order to get the next zoom level:

http://share.gigapan.org/gigapans0/2770/tiles/r01/211/r012113.jpg
This image only has seven zoom levels, but here is a tile from the tenth level of a ten level gigapan.

http://share.gigapan.org/gigapans0/5517/tiles/r10/000/121/r100001210.jpg
That is the top left tile
of the top right tile
of the lower left tile
of the top right tile
of the top left tile
of the top left tile
of the top left tile
of the top left tile
of the top right tile
Of the full image...

Converting between tile space and pixel space

There is a simple function to map from any point within an image to the tile which includes that point, or from any tile to the 256 x 256 pixels which are contained within that tile.

Sadly I have not written it yet :-)

Converting between tile space and filename space

Another simple function does this :-) Just throw in a directory for every three characters of the tile name.

Tile Math and Number of Levels

The number of tile or zoom levels in a panorama can be determined in a couple of ways. If you have the .data directory then descend as far as you can until you get to a directory with no subdirectories, then count the number of characters in the longest filename. For example, I have a gigapan where I can descend like this:
where_bay_01b.data/tiles/r00/000/000/r000000000.jpg

There is the 'r' plus nine 0's, so the number of levels will be 10.

You can also calculate the number of levels from a full size image (such as as tif exported by the stitcher).

Determine the height and width
(I use gdalinfo from the FWTools Open Source GIS Toolkit)
gdalinfo where_bay_01b.tif
Size is 88415, 13518
Select the larger, 88415 in this case, and divide by 256
88415/256=345 (and change)
Take the square
345^2 = 119025
Find the 4th root
Round up
Add one...

(or just use this table-this assumes a square image. Non-square images will be smaller, and uneeded tiles will not be generated) Using the table, I find level 9 is up to 65,536 pixels on a side, and level ten is up to 131,076. My image is 88,415, so rounding up it is level ten.

level	max pixels wide or high	Total Tiles	sample file name
1	256	1	r.jpg
2	512	4	r0.jpg
3	1024	16	r00.jpg
4	2048	64	r000.jpg
5	4096	256	r0000.jpg
6	8192	1024	r00000.jpg
7	16384	4096	r000000.jpg
8	32768	16384	r0000000.jpg
9	65536	65536	r00000000.jpg
10	131072	262144	r000000000.jpg
11	262144	1048576	r0000000000.jpg

An image with ten levels can be up to 17 gigapixels. A square panorama with Eleven levels would be 68+ gigapixels. I know there are images with ten levels, I have not actually seen an eleven level image.