PanoJS Quick Reference

Overview

This library provides a browser client with an interface to pan and zoom an image that is much larger than the screen, fetching tiled sections on demand. As one edge of the image moves off the screen in one direction, new portions of the image appear on the opposing side. Using this type of interface allows the image being viewed to theoretically be infinite. As such, the taxation on the network connection is minimized tremendously by the fact that only portions of the image are needed at any given time.

Usage

In order to use this library, it is necessary to first generate the tiles for your image. For that, the tilemaker.py python script can be used. This script requires the Python Imaging Library (PIL) module. The script performs two primary functions. It creates tiles of the given size for the 1:1 resolution and also for each power-of-two scaling until the whole image fits within the given size of a single tile. This progressive scaling provides the zoom out capability in the interface. (Please note that padding will likely be applied to the image to make it square and mathematically perfect)

The following snippet will take the file canvas.png and generate 256 pixel tiles at png quality 9. The filename pattern allows for customization of the output, but is often left as is. The tiles are put in the current working directory.

python tilemaker.py -s256 -Q9 -t"tile-%d-%d-%d.png" -bFFFFFF -v canvas.png

Once the tiles are generated, it is time to setup the webpage for displaying them. There are several crucial components required to make the viewer work. The example index file provided with the library demonstrates these inclusions.

  • include the PanoJS.js javascript library
    <script type="text/javascript" src="PanoJS.js" />
  • include the panojs.css stylesheet
    <link rel="stylesheet" href="panojs.css" />
  • create a target html container for the viewer
    <div id="viewer">
      <div class="well"><!-- --></div>
      <div class="surface"><!-- --></div>
      <p class="controls">
        <span class="zoomIn" title="Zoom In">+</span>
        <span class="zoomOut" title="Zoom Out">-</span>
      </p>
    </div>
  • All that is left is to initialize the viewer on page load with the settings specific to your environment. This step involves some trickery to get the viewer to initialize itself at the correct time in all browsers, but aside from that logic (which can be found in the example index file), the snippet below we get you up and running.

    var viewerBean;
    window.onload = function() {
    	viewerBean = new PanoJS('viewer', {
    		tileBaseUri: 'tiles',
    		tileSize: 256,
    		tilePrefix: 'tile-',
    		tileExtension: 'png',
    		maxZoom: 5,
    		initialZoom: 3,
    		blankTile: 'blank.gif',
    		loadingTile: 'blank.gif'
    	});
    	viewerBean.init();
    }
    		

    The only area where you might get tripped up is the maxZoom setting. The maxZoom is dependent entirely on the dimensions of your original image. To determine the maxZoom, look at the tiles and find the highest value of the first digit (tile-5-0-0.jpg). That number is the maxZoom value.

    Options

    The following is a list of available settings that can be provided in the constructor.

    tileUrlProvider [object]
    An object which extends PanoJS.TileUrlProvider that provides a method assembleUrl, which will be called each time a new tile is fetched. Internally, a default implementation is provided if one is not given.
    tileBaseUri [string]
    A relative or absolute URL that prefixes the tile name when fetching a tile. This option is only used if tileUrlProvider is not used.
    tilePrefix [string]
    The file name prefix of the tile. This option is only used if tileUrlProvider is not used.
    tileExtension [string]
    The file name extension of the tiles (also determines the image type of the tiles). This option is only used if tileUrlProvider is not used.
    tileSize [int]
    The size of each tile, used to calculate the placement of tiles.
    initialZoom [int]
    The initial zoom level used when loading up the viewer.
    maxZoom [int]
    The max zoom level the viewer is capable of displaying using the generated tiles.
    initialPan [coordinates]
    An object, in the form {0, 0} that determines the initial pan (placement) of the image within the viewer.
    blankTile [url]
    The url of an image that is used when there is no tile to display (such as at the edges of the image).
    loadingTile [url]
    An image to be used when the tile is loading, but before it is made visible.

    Global Settings

    The following options are provided on a global level, many of which are used as fallback values if an override is not provided in the options of the constructor.

    PanoJS.TILE_BASE_URI
    The relative or absolute URI that is prepended to the tile file name.
    PanoJS.TILE_PREFIX
    The prefix for each tile file name.
    PanoJS.TILE_EXTENSION
    The extension of the tile image, which also determines file type.
    PanoJS.TILE_SIZE
    The size of the image tiles, in pixels.
    PanoJS.BLANK_TILE_IMAGE
    The image to be displayed when there is no tile to display (such as at the boundaries of the image).
    PanoJS.LOADING_TILE_IMAGE
    The image to be displayed when a tile is loading but not yet revealed.
    PanoJS.INITIAL_PAN
    The coordinates of the inital pan of the viewer on initialization.
    PanoJS.USE_LOADER_IMAGE
    Determines if the loading image should be used.
    PanoJS.USE_SLIDE
    Should the image smooth slide to position when repositioning.
    PanoJS.USE_KEYBOARD
    Should keyboard events be captured to allow control for panning of the image.
    PanoJS.MOVE_THROTTLE
    The number of events that should be discarded before moving the image. Helps performance.
    PanoJS.SLIDE_DELAY
    The number of milliseconds of pause before sliding to reposition.
    PanoJS.SLIDE_ACCELERATION_FACTOR
    The multiplier used to speed of the sliding over time.