source: sandbox/tschaub/arcgiscache/lib/OpenLayers/Layer/ArcGISCache.js

/**
 * @requires OpenLayers/Layer/XYZ.js
 * @requires OpenLayers/Tile/Image.js
 */

/** 
 * Class: OpenLayers.Layer.ArcGISCache
 * Create a layer to read from an ArcGIS tile cache.
 * 
 * Examples:
 *
 * Create a new layer based on a cache in geographic coordinates.
 * (code)
 *     var layer = new OpenLayers.Layer.ArcGISCache({
 *         url: "http://example.com/mylayer/"
 *     });
 * (end)
 *
 * Create a new layer based on a cache in spherical mercator.
 * (code)
 *     var layer = new OpenLayers.Layer.ArcGISCache({
 *         url: "http://example.com/mylayer/",
 *         sphericalMercator: true
 *     });
 * (end)
 *
 * Create a layer in geographic coordinates with a custom tile origin.
 * (code)
 *     var layer = new OpenLayers.Layer.ArcGISCache({
 *         url: "http://example.com/mylayer/",
 *         tileOrigin: new OpenLayers.LonLat(-100, 45)
 *     });
 * (end)
 * 
 * Inherits from: 
 *  - <OpenLayers.Layer.XYZ>
 */
OpenLayers.Layer.ArcGISCache = OpenLayers.Class(OpenLayers.Layer.XYZ, {
    
    /**
     * APIProperty: url
     * {String | Array} The base URL for the layer cache.  If your tiles can
     *     be accessed at "http://example.com/mylayer/L00/R00000000/C00000000.png"
     *     this value would be "http://example.com/mylayer/".  You can also
     *     provide a list of URL strings for the layer if your cache is
     *     available from multiple origins.  This must be set before the layer
     *     is drawn.
     */
    url: null,
    
    /**
     * APIProperty: tileOrigin
     * {<OpenLayers.LonLat>} The location of the tile origin for the cache.
     *     An ArcGIS cache has it's origin at the upper-left (lowest x value
     *     and highest y value of the coordinate system).  The units for the
     *     tile origin should be the same as the units for the cached data.
     *     If this is not set, it will be derived from the layer maxExtent.
     */
    tileOrigin: null,
    
    /**
     * APIProperty: sphericalMercator
     * {Boolean} This layer is in a sperical (or web) mercator projection.
     *     Default is false.  If set to true, resolution and projection related
     *     parameters will be calculated if not provided (maxExtent,
     *     maxResolution, numZoomLevels, units, and projection).
     */
    sphericalMercator: false,
    
    /**
     * APIProperty: type
     * {String} Image type for the layer.  This becomes the filename extension
     *     in tile requests.  Default is "png" (generating a url like
     *     "http://example.com/mylayer/L00/R00000000/C00000000.png").
     */
    type: "png",
    
    /**
     * APIProperty: params
     * {Object} An optional object with members representing query string
     *     parameters to be appended to tile requests.  By default, no query
     *     string is appended (params is null).  If a params object is provided,
     *     all property name/value pairs will be URI component encoded in the
     *     query string for each tile.  Call mergeNewParams to update the
     *     params object after layer construction.
     */
    params: null,

    /**
     * APIProperty: zoomOffset
     * {Number} If your cache has more zoom levels than you want to provide
     *     access to with this layer, supply a zoomOffset.  This zoom offset
     *     is added to the current map zoom level to determine the level
     *     for a requested tile.  For example, if you supply a zoomOffset
     *     of 3, when the map is at the zoom 0, tiles will be requested from
     *     level 3 of your cache.  Default is 0 (assumes cache level and map
     *     zoom are equivalent).
     */
    zoomOffset: 0,
    
    /**
     * APIProperty: upperCase
     * {Boolean} Use upper case for row and column ids.  Default is true.
     */
    upperCase: true,
    
    /**
     * APIProperty: name
     * {String} The layer title (for display in UI components like a layer
     *     switcher.)
     */
    name: "",
    
    /**
     * Constructor: OpenLayers.Layer.ArcGISCache
     * Create a new layer for displaying tiles from an ArcGIS tile cache.
     *
     * Parameters:
     * options - {Object} Properties to be set on the layer.  Any of the layer
     *     properties may be set by including members in this object.  The <url>
     *     property is the only required property.
     */
    initialize: function(options) {
        var args = [options.name, options.url, options];
        OpenLayers.Layer.XYZ.prototype.initialize.apply(this, args);

        if (this.maxExtent && !this.tileOrigin) {
            this.tileOrigin = new OpenLayers.LonLat(
                this.maxExtent.left, this.maxExtent.top
            )
        }
        if (options && options.params) {
            this.params = OpenLayers.Util.extend({}, options.params);
        } else {
            this.params = null;
        }
    },
    
    /**
     * Method: zeroPad
     * Create a zero padded string optionally with a radix for casting numbers.
     *
     * Parameters:
     * num - {Number} The number to be zero padded.
     * len - {Number} The length of the string to be returned.
     * radix - {Number} An integer between 2 and 36 specifying the base to use
     *     for representing numeric values.
     */
    zeroPad: function(num, len, radix) {
        var str = num.toString(radix || 10);
        while (str.length < len) {
            str = "0" + str;
        }
        return str;
    },

    
    /**
     * Method: getUrl
     * Determine the URL for a tile given the tile bounds.  This is a generous
     *     algorithm that determines the row and column numbers given the center
     *     of the tile bounds.  This allows for some imprecision in the
     *     <tileOrigin> and resolution based calculations.
     * 
     * Parameters:
     * bounds - {<OpenLayers.Bounds>}
     *
     * Returns:
     * {String} The URL for a tile based on given bounds.
     */
    getURL: function(bounds) {
        
        // allow for level to be offset from zoom
        var level = "L" + this.zeroPad(this.zoomOffset + this.map.getZoom(), 2);

        // use tile center to avoid precision issues at tile edges
        var center = bounds.getCenterLonLat();        
        var res = this.map.getResolution();

        // column id is a zero padded base 16 number
        // counting in the positive x direction
        var colWidth = res * this.tileSize.h;
        var xOffset = center.lon - this.tileOrigin.lon;
        var col = "C" + this.zeroPad(Math.floor(xOffset / colWidth), 8, 16);
        if (this.upperCase) {
            col = col.toUpperCase();
        }
        
        // row id is a zero padded base 16 number
        // counting in the negative y direction
        var rowHeight = res * this.tileSize.w;
        var yOffset = center.lat - this.tileOrigin.lat;
        var row = "R" + this.zeroPad(Math.floor(-yOffset / rowHeight), 8, 16);
        if (this.upperCase) {
            row = row.toUpperCase();
        }
        
        var url = this.url;
        if (url instanceof Array) {
            url = this.selectUrl(level + row + col, url);
        }
        
        // optionally append a query string based on params
        var query = "";
        if (this.params) {
            query = "?" + OpenLayers.Util.getParameterString(this.params);
        }

        var base = url.replace(/\/$/, "") + "/";
        return base + level + "/" + row + "/" + col + "." + this.type + query; 
    },
    
    /**
     * APIMethod: clone
     * Create a copy of this layer.
     *
     * Returns:
     * {<OpenLayers.Layer.ArcGISCache>} A new layer with the same properties
     *     as this one.
     */
    clone: function(obj) {
        // this allows subclasses to apply this method with impunity
        if (!obj) {
            var options = OpenLayers.Util.extend({}, this.options);
            obj = new OpenLayers.Layer.ArcGISCache(options);
        }
        return OpenLayers.Layer.XYZ.prototype.clone.apply(this, [obj]);
    },

    CLASS_NAME: "OpenLayers.Layer.ArcGISCache"
});