MapzenTerrainProvider.js

define([
    '../ThirdParty/when',
    './Credit',
    './defaultValue',
    './defined',
    './defineProperties',
    './DeveloperError',
    './Ellipsoid',
    './Event',
    './GeographicTilingScheme',
    './WebMercatorTilingScheme',
    './getImagePixels',
    './HeightmapTerrainData',
    './loadImage',
    './Math',
    './Rectangle',
    './Request',
    './RequestType',
    './TerrainProvider',
    './TileProviderError'
], function(
    when,
    Credit,
    defaultValue,
    defined,
    defineProperties,
    DeveloperError,
    Ellipsoid,
    Event,
    GeographicTilingScheme,
    WebMercatorTilingScheme,
    getImagePixels,
    HeightmapTerrainData,
    loadImage,
    CesiumMath,
    Rectangle,
    Request,
    RequestType,
    TerrainProvider,
    TileProviderError) {
'use strict';

/**
 * A {@link TerrainProvider} that produces terrain geometry by tessellating height maps
 * retrieved from a {@link https://mapzen.com/documentation/terrain-tiles/ }.
 *
 * @alias MapzenTerrainProvider
 * @constructor
 *
 * @param {Object} options Object with the following properties:
 * @param {String} options.url The URL of the VR-TheWorld TileMap.
 * @param {Object} [options.proxy] A proxy to use for requests. This object is expected to have a getURL function which returns the proxied URL, if needed.
 * @param {Ellipsoid} [options.ellipsoid=Ellipsoid.WGS84] The ellipsoid.  If this parameter is not
 *                    specified, the WGS84 ellipsoid is used.
 * @param {Credit|String} [options.credit] A credit for the data source, which is displayed on the canvas.
 *
 *
 * @example
 * var terrainProvider = new Cesium.VRTheWorldTerrainProvider({
 *   url : 'https://www.vr-theworld.com/vr-theworld/tiles1.0.0/73/'
 * });
 * viewer.terrainProvider = terrainProvider;
 *
 * @see TerrainProvider
 */
function MapzenTerrainProvider(options) {
    options = defaultValue(options, defaultValue.EMPTY_OBJECT);

    this._key = options.apiKey;

    this._url = options.url;
    if(!defined(this._url)) {
        this._url = 'https://tile.mapzen.com/mapzen/terrain/v1/terrarium/';
    }
    if (this._url.length > 0 && this._url[this._url.length - 1] !== '/') {
        this._url += '/';
    }

    this._errorEvent = new Event();
    this._ready = false;
    this._readyPromise = when.defer();

    this._proxy = options.proxy;

    this._heightmapWidth = 256;
    this._heightmapHeight = 256;
    this._terrainDataStructure = {
        heightScale : 1.0 / 256.0,
        heightOffset : -32768.0,
        elementsPerHeight : 3,
        stride : 3,
        elementMultiplier : 256.0,
        isBigEndian : true,
        lowestEncodedHeight : 0,
        highestEncodedHeight : 256 * 256 * 256 - 1
    };

    var credit = options.credit;
    if (typeof credit === 'string') {
        credit = new Credit(credit);
    }
    this._credit = credit;

    this._tilingScheme = options.tilingScheme;
    if (!defined(this._tilingScheme)) {
        this._tilingScheme = new WebMercatorTilingScheme({
            ellipsoid : defaultValue(options.ellipsoid, Ellipsoid.WGS84),
            numberOfLevelZeroTilesX : 2,
            numberOfLevelZeroTilesY : 2
        });
    }

    this._rectangles = [];

    this._ready = true;
    this._readyPromise.resolve(true);
}

defineProperties(MapzenTerrainProvider.prototype, {
    /**
     * Gets an event that is raised when the terrain provider encounters an asynchronous error.  By subscribing
     * to the event, you will be notified of the error and can potentially recover from it.  Event listeners
     * are passed an instance of {@link TileProviderError}.
     * @memberof VRTheWorldTerrainProvider.prototype
     * @type {Event}
     */
    errorEvent : {
        get : function() {
            return this._errorEvent;
        }
    },

    /**
     * Gets the credit to display when this terrain provider is active.  Typically this is used to credit
     * the source of the terrain.  This function should not be called before {@link VRTheWorldTerrainProvider#ready} returns true.
     * @memberof VRTheWorldTerrainProvider.prototype
     * @type {Credit}
     */
    credit : {
        get : function() {
            return this._credit;
        }
    },

    /**
     * Gets the tiling scheme used by this provider.  This function should
     * not be called before {@link VRTheWorldTerrainProvider#ready} returns true.
     * @memberof VRTheWorldTerrainProvider.prototype
     * @type {GeographicTilingScheme}
     */
    tilingScheme : {
        get : function() {
            //>>includeStart('debug', pragmas.debug);
            if (!this.ready) {
                throw new DeveloperError('requestTileGeometry must not be called before ready returns true.');
            }
            //>>includeEnd('debug');

            return this._tilingScheme;
        }
    },

    /**
     * Gets a value indicating whether or not the provider is ready for use.
     * @memberof VRTheWorldTerrainProvider.prototype
     * @type {Boolean}
     */
    ready : {
        get : function() {
            return this._ready;
        }
    },

    /**
     * Gets a promise that resolves to true when the provider is ready for use.
     * @memberof VRTheWorldTerrainProvider.prototype
     * @type {Promise.<Boolean>}
     * @readonly
     */
    readyPromise : {
        get : function() {
            return this._readyPromise.promise;
        }
    },

    /**
     * Gets a value indicating whether or not the provider includes a water mask.  The water mask
     * indicates which areas of the globe are water rather than land, so they can be rendered
     * as a reflective surface with animated waves.  This function should not be
     * called before {@link VRTheWorldTerrainProvider#ready} returns true.
     * @memberof VRTheWorldTerrainProvider.prototype
     * @type {Boolean}
     */
    hasWaterMask : {
        get : function() {
            return false;
        }
    },

    /**
     * Gets a value indicating whether or not the requested tiles include vertex normals.
     * This function should not be called before {@link VRTheWorldTerrainProvider#ready} returns true.
     * @memberof VRTheWorldTerrainProvider.prototype
     * @type {Boolean}
     */
    hasVertexNormals : {
        get : function() {
            return false;
        }
    }
});

/**
 * Requests the geometry for a given tile.  This function should not be called before
 * {@link VRTheWorldTerrainProvider#ready} returns true.  The result includes terrain
 * data and indicates that all child tiles are available.
 *
 * @param {Number} x The X coordinate of the tile for which to request geometry.
 * @param {Number} y The Y coordinate of the tile for which to request geometry.
 * @param {Number} level The level of the tile for which to request geometry.
 * @param {Request} [request] The request object. Intended for internal use only.
 * @returns {Promise.<TerrainData>|undefined} A promise for the requested geometry.  If this method
 *          returns undefined instead of a promise, it is an indication that too many requests are already
 *          pending and the request will be retried later.
 */
MapzenTerrainProvider.prototype.requestTileGeometry = function(x, y, level, request) {
    //>>includeStart('debug', pragmas.debug);
    if (!this.ready) {
        throw new DeveloperError('requestTileGeometry must not be called before ready returns true.');
    }
    //>>includeEnd('debug');

    var url = this._url + (level + 1) + '/' + x + '/' + y + '.png';
    if (this._key) {
        url += '?api_key=' + this._key;
    }

    var proxy = this._proxy;
    if (defined(proxy)) {
        url = proxy.getURL(url);
    }

    var promise = loadImage(url, undefined, request);
    if (!defined(promise)) {
        return undefined;
    }

    var that = this;
    return when(promise, function(image) {
        return new HeightmapTerrainData({
            buffer : getImagePixels(image),
            width : that._heightmapWidth,
            height : that._heightmapHeight,
            childTileMask : 15,
            structure : that._terrainDataStructure
        });
    });
};

/**
 * Gets the maximum geometric error allowed in a tile at a given level.
 *
 * @param {Number} level The tile level for which to get the maximum geometric error.
 * @returns {Number} The maximum geometric error.
 */
MapzenTerrainProvider.prototype.getLevelMaximumGeometricError = function(level) {
    //>>includeStart('debug', pragmas.debug);
    if (!this.ready) {
        throw new DeveloperError('requestTileGeometry must not be called before ready returns true.');
    }
    //>>includeEnd('debug');
    return this._levelZeroMaximumGeometricError / (1 << level);
};

/**
 * Determines whether data for a tile is available to be loaded.
 *
 * @param {Number} x The X coordinate of the tile for which to request geometry.
 * @param {Number} y The Y coordinate of the tile for which to request geometry.
 * @param {Number} level The level of the tile for which to request geometry.
 * @returns {Boolean} Undefined if not supported, otherwise true or false.
 */
MapzenTerrainProvider.prototype.getTileDataAvailable = function(x, y, level) {
    return undefined;
};

return MapzenTerrainProvider;
});