OpenSeadragon 6.0.1

example: custom tile sources

A Custom Tile Source can be created via inline configuration by specifying a single function named getTileUrl, along with the required values for height and width. Optional values include tileSize, tileOverlap, minLevel, and maxLevel. Additionally, any default functions implemented by OpenSeadragon.TileSource can be overridden. Functionally, this allows you to define a new TileSource implementation inline.

Alternatively, you can create a new tile source which implements the required interfaces getTileUrl, configure, and supports.

Inline Configuration for Custom Tile Sources

Minimally, an inline configuration for a custom tile source only needs to implement the getTileUrl interface and provide a height and width for the maximum resolution of the image.

Example Inline Configuration for Custom Tile Sources

Below is a minimal inline configuration which pulls tiles from a NASA Blue Marble tile set transformed into tiles hosted on Amazon S3 (compliments of Michal Migurski). Note that the default tileSize is available as a property of the tile source.

OpenSeadragon({
    id:            "example-custom-tilesource",
    prefixUrl:     "/openseadragon/images/",
    navigatorSizeRatio: 0.25,
    wrapHorizontal:     true,
    tileSources:   {
        height: 512*256,
        width:  512*256,
        tileSize: 256,
        minLevel: 8,
        getTileUrl: function( level, x, y ){
            return "http://s3.amazonaws.com/com.modestmaps.bluemarble/" +
                    (level-8) + "-r" + y + "-c" + x + ".jpg";
        }
    }
});

Another Inline Configuration for Custom Tile Sources

Here is another inline example which makes use of a tile set created by Aaron Straup Cope which provides a visualization of geotagged Flickr photos.

Another Inline Configuration for Custom Tile Sources

Note in this case we set blendTime to zero since PNG images with alpha channel (transparency) can look unusual during blending.

OpenSeadragon({
    ...
    showNavigator:      false,
    blendTime:          0,
    wrapHorizontal:     true,
    tileSources:   {
        height: 1024*256,
        width:  1024*256,
        tileSize: 256,
        minLevel: 9,
        getTileUrl: function( level, x, y ){

            function zeropad( i ) {
                var n = String( i ),
                    m = 6 - n.length;
                n = (m < 1) ? n : new Array(m + 1).join( "0" ) + n;
                return n.substr(0, 3) + "/" + n.substr(3);
            };

            return "http://s3.amazonaws.com/info.aaronland.tiles.shapetiles/" +
                    (level-8) + "/" + zeropad(x) + "/" + zeropad(y) + ".png";
        }
    }
    ...
});

Where to next?

OpenSeadragon offers a variety of ways to add custom tile sources. You can define your own data types, override the default tile data access logic and more!

If you need OpenSeadragon to fetch your data in a custom way, if you need to support asynchronous resolution of your tile-related data or even downloading the data in a custom way, see the next article. You will find out, that getTileUrl does not actually need to return a URL value at all - by overriding relevant methods, everything is in your hands.

OpenSeadragon goes even further: you can define custom data types, have plugins that require other data types, and drawers that require yet another type to actually render. Everything is kept interoperable by OpenSeadragon's conversion pipeline and the data type system. In OpenSeadragon, you can implement custom data acquisition, conversion, tile-level preprocessing and even the final rendering.