BingMapsImageryProvider.js 25 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862
  1. import BingMapsApi from "../Core/BingMapsApi.js";
  2. import buildModuleUrl from "../Core/buildModuleUrl.js";
  3. import Check from "../Core/Check.js";
  4. import Credit from "../Core/Credit.js";
  5. import defaultValue from "../Core/defaultValue.js";
  6. import defined from "../Core/defined.js";
  7. import DeveloperError from "../Core/DeveloperError.js";
  8. import Event from "../Core/Event.js";
  9. import CesiumMath from "../Core/Math.js";
  10. import Rectangle from "../Core/Rectangle.js";
  11. import Resource from "../Core/Resource.js";
  12. import RuntimeError from "../Core/RuntimeError.js";
  13. import TileProviderError from "../Core/TileProviderError.js";
  14. import WebMercatorTilingScheme from "../Core/WebMercatorTilingScheme.js";
  15. import when from "../ThirdParty/when.js";
  16. import BingMapsStyle from "./BingMapsStyle.js";
  17. import DiscardEmptyTilePolicy from "./DiscardEmptyTileImagePolicy.js";
  18. import ImageryProvider from "./ImageryProvider.js";
  19. /**
  20. * @typedef {Object} BingMapsImageryProvider.ConstructorOptions
  21. *
  22. * Initialization options for the BingMapsImageryProvider constructor
  23. *
  24. * @property {Resource|String} url The url of the Bing Maps server hosting the imagery.
  25. * @property {String} key The Bing Maps key for your application, which can be
  26. * created at {@link https://www.bingmapsportal.com/}.
  27. * If this parameter is not provided, {@link BingMapsApi.defaultKey} is used, which is undefined by default.
  28. * @property {String} [tileProtocol] The protocol to use when loading tiles, e.g. 'http' or 'https'.
  29. * By default, tiles are loaded using the same protocol as the page.
  30. * @property {BingMapsStyle} [mapStyle=BingMapsStyle.AERIAL] The type of Bing Maps imagery to load.
  31. * @property {String} [culture=''] The culture to use when requesting Bing Maps imagery. Not
  32. * all cultures are supported. See {@link http://msdn.microsoft.com/en-us/library/hh441729.aspx}
  33. * for information on the supported cultures.
  34. * @property {Ellipsoid} [ellipsoid] The ellipsoid. If not specified, the WGS84 ellipsoid is used.
  35. * @property {TileDiscardPolicy} [tileDiscardPolicy] The policy that determines if a tile
  36. * is invalid and should be discarded. By default, a {@link DiscardEmptyTileImagePolicy}
  37. * will be used, with the expectation that the Bing Maps server will send a zero-length response for missing tiles.
  38. * To ensure that no tiles are discarded, construct and pass a {@link NeverTileDiscardPolicy} for this parameter.
  39. */
  40. /**
  41. * Provides tiled imagery using the Bing Maps Imagery REST API.
  42. *
  43. * @alias BingMapsImageryProvider
  44. * @constructor
  45. *
  46. * @param {BingMapsImageryProvider.ConstructorOptions} options Object describing initialization options
  47. *
  48. * @see ArcGisMapServerImageryProvider
  49. * @see GoogleEarthEnterpriseMapsProvider
  50. * @see OpenStreetMapImageryProvider
  51. * @see SingleTileImageryProvider
  52. * @see TileMapServiceImageryProvider
  53. * @see WebMapServiceImageryProvider
  54. * @see WebMapTileServiceImageryProvider
  55. * @see UrlTemplateImageryProvider
  56. *
  57. *
  58. * @example
  59. * var bing = new Cesium.BingMapsImageryProvider({
  60. * url : 'https://dev.virtualearth.net',
  61. * key : 'get-yours-at-https://www.bingmapsportal.com/',
  62. * mapStyle : Cesium.BingMapsStyle.AERIAL
  63. * });
  64. *
  65. * @see {@link http://msdn.microsoft.com/en-us/library/ff701713.aspx|Bing Maps REST Services}
  66. * @see {@link http://www.w3.org/TR/cors/|Cross-Origin Resource Sharing}
  67. */
  68. function BingMapsImageryProvider(options) {
  69. options = defaultValue(options, defaultValue.EMPTY_OBJECT);
  70. var accessKey = BingMapsApi._getKeyNoDeprecate(options.key);
  71. //>>includeStart('debug', pragmas.debug);
  72. if (!defined(options.url)) {
  73. throw new DeveloperError("options.url is required.");
  74. }
  75. if (!defined(accessKey)) {
  76. throw new DeveloperError("options.key is required.");
  77. }
  78. //>>includeEnd('debug');
  79. /**
  80. * The default alpha blending value of this provider, with 0.0 representing fully transparent and
  81. * 1.0 representing fully opaque.
  82. *
  83. * @type {Number|undefined}
  84. * @default undefined
  85. */
  86. this.defaultAlpha = undefined;
  87. /**
  88. * The default alpha blending value on the night side of the globe of this provider, with 0.0 representing fully transparent and
  89. * 1.0 representing fully opaque.
  90. *
  91. * @type {Number|undefined}
  92. * @default undefined
  93. */
  94. this.defaultNightAlpha = undefined;
  95. /**
  96. * The default alpha blending value on the day side of the globe of this provider, with 0.0 representing fully transparent and
  97. * 1.0 representing fully opaque.
  98. *
  99. * @type {Number|undefined}
  100. * @default undefined
  101. */
  102. this.defaultDayAlpha = undefined;
  103. /**
  104. * The default brightness of this provider. 1.0 uses the unmodified imagery color. Less than 1.0
  105. * makes the imagery darker while greater than 1.0 makes it brighter.
  106. *
  107. * @type {Number|undefined}
  108. * @default undefined
  109. */
  110. this.defaultBrightness = undefined;
  111. /**
  112. * The default contrast of this provider. 1.0 uses the unmodified imagery color. Less than 1.0 reduces
  113. * the contrast while greater than 1.0 increases it.
  114. *
  115. * @type {Number|undefined}
  116. * @default undefined
  117. */
  118. this.defaultContrast = undefined;
  119. /**
  120. * The default hue of this provider in radians. 0.0 uses the unmodified imagery color.
  121. *
  122. * @type {Number|undefined}
  123. * @default undefined
  124. */
  125. this.defaultHue = undefined;
  126. /**
  127. * The default saturation of this provider. 1.0 uses the unmodified imagery color. Less than 1.0 reduces the
  128. * saturation while greater than 1.0 increases it.
  129. *
  130. * @type {Number|undefined}
  131. * @default undefined
  132. */
  133. this.defaultSaturation = undefined;
  134. /**
  135. * The default gamma correction to apply to this provider. 1.0 uses the unmodified imagery color.
  136. *
  137. * @type {Number|undefined}
  138. * @default 1.0
  139. */
  140. this.defaultGamma = 1.0;
  141. /**
  142. * The default texture minification filter to apply to this provider.
  143. *
  144. * @type {TextureMinificationFilter}
  145. * @default undefined
  146. */
  147. this.defaultMinificationFilter = undefined;
  148. /**
  149. * The default texture magnification filter to apply to this provider.
  150. *
  151. * @type {TextureMagnificationFilter}
  152. * @default undefined
  153. */
  154. this.defaultMagnificationFilter = undefined;
  155. this._key = accessKey;
  156. this._resource = Resource.createIfNeeded(options.url);
  157. this._resource.appendForwardSlash();
  158. this._tileProtocol = options.tileProtocol;
  159. this._mapStyle = defaultValue(options.mapStyle, BingMapsStyle.AERIAL);
  160. this._culture = defaultValue(options.culture, "");
  161. this._tileDiscardPolicy = options.tileDiscardPolicy;
  162. if (!defined(this._tileDiscardPolicy)) {
  163. this._tileDiscardPolicy = new DiscardEmptyTilePolicy();
  164. }
  165. this._proxy = options.proxy;
  166. this._credit = new Credit(
  167. '<a href="http://www.bing.com"><img src="' +
  168. BingMapsImageryProvider.logoUrl +
  169. '" title="Bing Imagery"/></a>'
  170. );
  171. this._tilingScheme = new WebMercatorTilingScheme({
  172. numberOfLevelZeroTilesX: 2,
  173. numberOfLevelZeroTilesY: 2,
  174. ellipsoid: options.ellipsoid,
  175. });
  176. this._tileWidth = undefined;
  177. this._tileHeight = undefined;
  178. this._maximumLevel = undefined;
  179. this._imageUrlTemplate = undefined;
  180. this._imageUrlSubdomains = undefined;
  181. this._errorEvent = new Event();
  182. this._ready = false;
  183. this._readyPromise = when.defer();
  184. var tileProtocol = this._tileProtocol;
  185. // For backward compatibility reasons, the tileProtocol may end with
  186. // a `:`. Remove it.
  187. if (defined(tileProtocol)) {
  188. if (
  189. tileProtocol.length > 0 &&
  190. tileProtocol[tileProtocol.length - 1] === ":"
  191. ) {
  192. tileProtocol = tileProtocol.substr(0, tileProtocol.length - 1);
  193. }
  194. } else {
  195. // use http if the document's protocol is http, otherwise use https
  196. var documentProtocol = document.location.protocol;
  197. tileProtocol = documentProtocol === "http:" ? "http" : "https";
  198. }
  199. var metadataResource = this._resource.getDerivedResource({
  200. url: "REST/v1/Imagery/Metadata/" + this._mapStyle,
  201. queryParameters: {
  202. incl: "ImageryProviders",
  203. key: this._key,
  204. uriScheme: tileProtocol,
  205. },
  206. });
  207. var that = this;
  208. var metadataError;
  209. function metadataSuccess(data) {
  210. if (data.resourceSets.length !== 1) {
  211. metadataFailure();
  212. return;
  213. }
  214. var resource = data.resourceSets[0].resources[0];
  215. that._tileWidth = resource.imageWidth;
  216. that._tileHeight = resource.imageHeight;
  217. that._maximumLevel = resource.zoomMax - 1;
  218. that._imageUrlSubdomains = resource.imageUrlSubdomains;
  219. that._imageUrlTemplate = resource.imageUrl;
  220. var attributionList = (that._attributionList = resource.imageryProviders);
  221. if (!attributionList) {
  222. attributionList = that._attributionList = [];
  223. }
  224. for (
  225. var attributionIndex = 0, attributionLength = attributionList.length;
  226. attributionIndex < attributionLength;
  227. ++attributionIndex
  228. ) {
  229. var attribution = attributionList[attributionIndex];
  230. if (attribution.credit instanceof Credit) {
  231. // If attribution.credit has already been created
  232. // then we are using a cached value, which means
  233. // none of the remaining processing needs to be done.
  234. break;
  235. }
  236. attribution.credit = new Credit(attribution.attribution);
  237. var coverageAreas = attribution.coverageAreas;
  238. for (
  239. var areaIndex = 0, areaLength = attribution.coverageAreas.length;
  240. areaIndex < areaLength;
  241. ++areaIndex
  242. ) {
  243. var area = coverageAreas[areaIndex];
  244. var bbox = area.bbox;
  245. area.bbox = new Rectangle(
  246. CesiumMath.toRadians(bbox[1]),
  247. CesiumMath.toRadians(bbox[0]),
  248. CesiumMath.toRadians(bbox[3]),
  249. CesiumMath.toRadians(bbox[2])
  250. );
  251. }
  252. }
  253. that._ready = true;
  254. that._readyPromise.resolve(true);
  255. TileProviderError.handleSuccess(metadataError);
  256. }
  257. function metadataFailure(e) {
  258. var message =
  259. "An error occurred while accessing " + metadataResource.url + ".";
  260. metadataError = TileProviderError.handleError(
  261. metadataError,
  262. that,
  263. that._errorEvent,
  264. message,
  265. undefined,
  266. undefined,
  267. undefined,
  268. requestMetadata
  269. );
  270. that._readyPromise.reject(new RuntimeError(message));
  271. }
  272. var cacheKey = metadataResource.url;
  273. function requestMetadata() {
  274. var promise = metadataResource.fetchJsonp("jsonp");
  275. BingMapsImageryProvider._metadataCache[cacheKey] = promise;
  276. promise.then(metadataSuccess).otherwise(metadataFailure);
  277. }
  278. var promise = BingMapsImageryProvider._metadataCache[cacheKey];
  279. if (defined(promise)) {
  280. promise.then(metadataSuccess).otherwise(metadataFailure);
  281. } else {
  282. requestMetadata();
  283. }
  284. }
  285. Object.defineProperties(BingMapsImageryProvider.prototype, {
  286. /**
  287. * Gets the name of the BingMaps server url hosting the imagery.
  288. * @memberof BingMapsImageryProvider.prototype
  289. * @type {String}
  290. * @readonly
  291. */
  292. url: {
  293. get: function () {
  294. return this._resource.url;
  295. },
  296. },
  297. /**
  298. * Gets the proxy used by this provider.
  299. * @memberof BingMapsImageryProvider.prototype
  300. * @type {Proxy}
  301. * @readonly
  302. */
  303. proxy: {
  304. get: function () {
  305. return this._resource.proxy;
  306. },
  307. },
  308. /**
  309. * Gets the Bing Maps key.
  310. * @memberof BingMapsImageryProvider.prototype
  311. * @type {String}
  312. * @readonly
  313. */
  314. key: {
  315. get: function () {
  316. return this._key;
  317. },
  318. },
  319. /**
  320. * Gets the type of Bing Maps imagery to load.
  321. * @memberof BingMapsImageryProvider.prototype
  322. * @type {BingMapsStyle}
  323. * @readonly
  324. */
  325. mapStyle: {
  326. get: function () {
  327. return this._mapStyle;
  328. },
  329. },
  330. /**
  331. * The culture to use when requesting Bing Maps imagery. Not
  332. * all cultures are supported. See {@link http://msdn.microsoft.com/en-us/library/hh441729.aspx}
  333. * for information on the supported cultures.
  334. * @memberof BingMapsImageryProvider.prototype
  335. * @type {String}
  336. * @readonly
  337. */
  338. culture: {
  339. get: function () {
  340. return this._culture;
  341. },
  342. },
  343. /**
  344. * Gets the width of each tile, in pixels. This function should
  345. * not be called before {@link BingMapsImageryProvider#ready} returns true.
  346. * @memberof BingMapsImageryProvider.prototype
  347. * @type {Number}
  348. * @readonly
  349. */
  350. tileWidth: {
  351. get: function () {
  352. //>>includeStart('debug', pragmas.debug);
  353. if (!this._ready) {
  354. throw new DeveloperError(
  355. "tileWidth must not be called before the imagery provider is ready."
  356. );
  357. }
  358. //>>includeEnd('debug');
  359. return this._tileWidth;
  360. },
  361. },
  362. /**
  363. * Gets the height of each tile, in pixels. This function should
  364. * not be called before {@link BingMapsImageryProvider#ready} returns true.
  365. * @memberof BingMapsImageryProvider.prototype
  366. * @type {Number}
  367. * @readonly
  368. */
  369. tileHeight: {
  370. get: function () {
  371. //>>includeStart('debug', pragmas.debug);
  372. if (!this._ready) {
  373. throw new DeveloperError(
  374. "tileHeight must not be called before the imagery provider is ready."
  375. );
  376. }
  377. //>>includeEnd('debug');
  378. return this._tileHeight;
  379. },
  380. },
  381. /**
  382. * Gets the maximum level-of-detail that can be requested. This function should
  383. * not be called before {@link BingMapsImageryProvider#ready} returns true.
  384. * @memberof BingMapsImageryProvider.prototype
  385. * @type {Number|undefined}
  386. * @readonly
  387. */
  388. maximumLevel: {
  389. get: function () {
  390. //>>includeStart('debug', pragmas.debug);
  391. if (!this._ready) {
  392. throw new DeveloperError(
  393. "maximumLevel must not be called before the imagery provider is ready."
  394. );
  395. }
  396. //>>includeEnd('debug');
  397. return this._maximumLevel;
  398. },
  399. },
  400. /**
  401. * Gets the minimum level-of-detail that can be requested. This function should
  402. * not be called before {@link BingMapsImageryProvider#ready} returns true.
  403. * @memberof BingMapsImageryProvider.prototype
  404. * @type {Number}
  405. * @readonly
  406. */
  407. minimumLevel: {
  408. get: function () {
  409. //>>includeStart('debug', pragmas.debug);
  410. if (!this._ready) {
  411. throw new DeveloperError(
  412. "minimumLevel must not be called before the imagery provider is ready."
  413. );
  414. }
  415. //>>includeEnd('debug');
  416. return 0;
  417. },
  418. },
  419. /**
  420. * Gets the tiling scheme used by this provider. This function should
  421. * not be called before {@link BingMapsImageryProvider#ready} returns true.
  422. * @memberof BingMapsImageryProvider.prototype
  423. * @type {TilingScheme}
  424. * @readonly
  425. */
  426. tilingScheme: {
  427. get: function () {
  428. //>>includeStart('debug', pragmas.debug);
  429. if (!this._ready) {
  430. throw new DeveloperError(
  431. "tilingScheme must not be called before the imagery provider is ready."
  432. );
  433. }
  434. //>>includeEnd('debug');
  435. return this._tilingScheme;
  436. },
  437. },
  438. /**
  439. * Gets the rectangle, in radians, of the imagery provided by this instance. This function should
  440. * not be called before {@link BingMapsImageryProvider#ready} returns true.
  441. * @memberof BingMapsImageryProvider.prototype
  442. * @type {Rectangle}
  443. * @readonly
  444. */
  445. rectangle: {
  446. get: function () {
  447. //>>includeStart('debug', pragmas.debug);
  448. if (!this._ready) {
  449. throw new DeveloperError(
  450. "rectangle must not be called before the imagery provider is ready."
  451. );
  452. }
  453. //>>includeEnd('debug');
  454. return this._tilingScheme.rectangle;
  455. },
  456. },
  457. /**
  458. * Gets the tile discard policy. If not undefined, the discard policy is responsible
  459. * for filtering out "missing" tiles via its shouldDiscardImage function. If this function
  460. * returns undefined, no tiles are filtered. This function should
  461. * not be called before {@link BingMapsImageryProvider#ready} returns true.
  462. * @memberof BingMapsImageryProvider.prototype
  463. * @type {TileDiscardPolicy}
  464. * @readonly
  465. */
  466. tileDiscardPolicy: {
  467. get: function () {
  468. //>>includeStart('debug', pragmas.debug);
  469. if (!this._ready) {
  470. throw new DeveloperError(
  471. "tileDiscardPolicy must not be called before the imagery provider is ready."
  472. );
  473. }
  474. //>>includeEnd('debug');
  475. return this._tileDiscardPolicy;
  476. },
  477. },
  478. /**
  479. * Gets an event that is raised when the imagery provider encounters an asynchronous error. By subscribing
  480. * to the event, you will be notified of the error and can potentially recover from it. Event listeners
  481. * are passed an instance of {@link TileProviderError}.
  482. * @memberof BingMapsImageryProvider.prototype
  483. * @type {Event}
  484. * @readonly
  485. */
  486. errorEvent: {
  487. get: function () {
  488. return this._errorEvent;
  489. },
  490. },
  491. /**
  492. * Gets a value indicating whether or not the provider is ready for use.
  493. * @memberof BingMapsImageryProvider.prototype
  494. * @type {Boolean}
  495. * @readonly
  496. */
  497. ready: {
  498. get: function () {
  499. return this._ready;
  500. },
  501. },
  502. /**
  503. * Gets a promise that resolves to true when the provider is ready for use.
  504. * @memberof BingMapsImageryProvider.prototype
  505. * @type {Promise.<Boolean>}
  506. * @readonly
  507. */
  508. readyPromise: {
  509. get: function () {
  510. return this._readyPromise.promise;
  511. },
  512. },
  513. /**
  514. * Gets the credit to display when this imagery provider is active. Typically this is used to credit
  515. * the source of the imagery. This function should not be called before {@link BingMapsImageryProvider#ready} returns true.
  516. * @memberof BingMapsImageryProvider.prototype
  517. * @type {Credit}
  518. * @readonly
  519. */
  520. credit: {
  521. get: function () {
  522. return this._credit;
  523. },
  524. },
  525. /**
  526. * Gets a value indicating whether or not the images provided by this imagery provider
  527. * include an alpha channel. If this property is false, an alpha channel, if present, will
  528. * be ignored. If this property is true, any images without an alpha channel will be treated
  529. * as if their alpha is 1.0 everywhere. Setting this property to false reduces memory usage
  530. * and texture upload time.
  531. * @memberof BingMapsImageryProvider.prototype
  532. * @type {Boolean}
  533. * @readonly
  534. */
  535. hasAlphaChannel: {
  536. get: function () {
  537. return false;
  538. },
  539. },
  540. });
  541. var rectangleScratch = new Rectangle();
  542. /**
  543. * Gets the credits to be displayed when a given tile is displayed.
  544. *
  545. * @param {Number} x The tile X coordinate.
  546. * @param {Number} y The tile Y coordinate.
  547. * @param {Number} level The tile level;
  548. * @returns {Credit[]} The credits to be displayed when the tile is displayed.
  549. *
  550. * @exception {DeveloperError} <code>getTileCredits</code> must not be called before the imagery provider is ready.
  551. */
  552. BingMapsImageryProvider.prototype.getTileCredits = function (x, y, level) {
  553. //>>includeStart('debug', pragmas.debug);
  554. if (!this._ready) {
  555. throw new DeveloperError(
  556. "getTileCredits must not be called before the imagery provider is ready."
  557. );
  558. }
  559. //>>includeEnd('debug');
  560. var rectangle = this._tilingScheme.tileXYToRectangle(
  561. x,
  562. y,
  563. level,
  564. rectangleScratch
  565. );
  566. var result = getRectangleAttribution(this._attributionList, level, rectangle);
  567. return result;
  568. };
  569. /**
  570. * Requests the image for a given tile. This function should
  571. * not be called before {@link BingMapsImageryProvider#ready} returns true.
  572. *
  573. * @param {Number} x The tile X coordinate.
  574. * @param {Number} y The tile Y coordinate.
  575. * @param {Number} level The tile level.
  576. * @param {Request} [request] The request object. Intended for internal use only.
  577. * @returns {Promise.<HTMLImageElement|HTMLCanvasElement>|undefined} A promise for the image that will resolve when the image is available, or
  578. * undefined if there are too many active requests to the server, and the request
  579. * should be retried later. The resolved image may be either an
  580. * Image or a Canvas DOM object.
  581. *
  582. * @exception {DeveloperError} <code>requestImage</code> must not be called before the imagery provider is ready.
  583. */
  584. BingMapsImageryProvider.prototype.requestImage = function (
  585. x,
  586. y,
  587. level,
  588. request
  589. ) {
  590. //>>includeStart('debug', pragmas.debug);
  591. if (!this._ready) {
  592. throw new DeveloperError(
  593. "requestImage must not be called before the imagery provider is ready."
  594. );
  595. }
  596. //>>includeEnd('debug');
  597. var promise = ImageryProvider.loadImage(
  598. this,
  599. buildImageResource(this, x, y, level, request)
  600. );
  601. if (defined(promise)) {
  602. return promise.otherwise(function (error) {
  603. // One cause of an error here is that the image we tried to load was zero-length.
  604. // This isn't actually a problem, since it indicates that there is no tile.
  605. // So, in that case we return the EMPTY_IMAGE sentinel value for later discarding.
  606. if (defined(error.blob) && error.blob.size === 0) {
  607. return DiscardEmptyTilePolicy.EMPTY_IMAGE;
  608. }
  609. return when.reject(error);
  610. });
  611. }
  612. return undefined;
  613. };
  614. /**
  615. * Picking features is not currently supported by this imagery provider, so this function simply returns
  616. * undefined.
  617. *
  618. * @param {Number} x The tile X coordinate.
  619. * @param {Number} y The tile Y coordinate.
  620. * @param {Number} level The tile level.
  621. * @param {Number} longitude The longitude at which to pick features.
  622. * @param {Number} latitude The latitude at which to pick features.
  623. * @return {Promise.<ImageryLayerFeatureInfo[]>|undefined} A promise for the picked features that will resolve when the asynchronous
  624. * picking completes. The resolved value is an array of {@link ImageryLayerFeatureInfo}
  625. * instances. The array may be empty if no features are found at the given location.
  626. * It may also be undefined if picking is not supported.
  627. */
  628. BingMapsImageryProvider.prototype.pickFeatures = function (
  629. x,
  630. y,
  631. level,
  632. longitude,
  633. latitude
  634. ) {
  635. return undefined;
  636. };
  637. /**
  638. * Converts a tiles (x, y, level) position into a quadkey used to request an image
  639. * from a Bing Maps server.
  640. *
  641. * @param {Number} x The tile's x coordinate.
  642. * @param {Number} y The tile's y coordinate.
  643. * @param {Number} level The tile's zoom level.
  644. *
  645. * @see {@link http://msdn.microsoft.com/en-us/library/bb259689.aspx|Bing Maps Tile System}
  646. * @see BingMapsImageryProvider#quadKeyToTileXY
  647. */
  648. BingMapsImageryProvider.tileXYToQuadKey = function (x, y, level) {
  649. var quadkey = "";
  650. for (var i = level; i >= 0; --i) {
  651. var bitmask = 1 << i;
  652. var digit = 0;
  653. if ((x & bitmask) !== 0) {
  654. digit |= 1;
  655. }
  656. if ((y & bitmask) !== 0) {
  657. digit |= 2;
  658. }
  659. quadkey += digit;
  660. }
  661. return quadkey;
  662. };
  663. /**
  664. * Converts a tile's quadkey used to request an image from a Bing Maps server into the
  665. * (x, y, level) position.
  666. *
  667. * @param {String} quadkey The tile's quad key
  668. *
  669. * @see {@link http://msdn.microsoft.com/en-us/library/bb259689.aspx|Bing Maps Tile System}
  670. * @see BingMapsImageryProvider#tileXYToQuadKey
  671. */
  672. BingMapsImageryProvider.quadKeyToTileXY = function (quadkey) {
  673. var x = 0;
  674. var y = 0;
  675. var level = quadkey.length - 1;
  676. for (var i = level; i >= 0; --i) {
  677. var bitmask = 1 << i;
  678. var digit = +quadkey[level - i];
  679. if ((digit & 1) !== 0) {
  680. x |= bitmask;
  681. }
  682. if ((digit & 2) !== 0) {
  683. y |= bitmask;
  684. }
  685. }
  686. return {
  687. x: x,
  688. y: y,
  689. level: level,
  690. };
  691. };
  692. BingMapsImageryProvider._logoUrl = undefined;
  693. Object.defineProperties(BingMapsImageryProvider, {
  694. /**
  695. * Gets or sets the URL to the Bing logo for display in the credit.
  696. * @memberof BingMapsImageryProvider
  697. * @type {String}
  698. */
  699. logoUrl: {
  700. get: function () {
  701. if (!defined(BingMapsImageryProvider._logoUrl)) {
  702. BingMapsImageryProvider._logoUrl = buildModuleUrl(
  703. "Assets/Images/bing_maps_credit.png"
  704. );
  705. }
  706. return BingMapsImageryProvider._logoUrl;
  707. },
  708. set: function (value) {
  709. //>>includeStart('debug', pragmas.debug);
  710. Check.defined("value", value);
  711. //>>includeEnd('debug');
  712. BingMapsImageryProvider._logoUrl = value;
  713. },
  714. },
  715. });
  716. function buildImageResource(imageryProvider, x, y, level, request) {
  717. var imageUrl = imageryProvider._imageUrlTemplate;
  718. var subdomains = imageryProvider._imageUrlSubdomains;
  719. var subdomainIndex = (x + y + level) % subdomains.length;
  720. return imageryProvider._resource.getDerivedResource({
  721. url: imageUrl,
  722. request: request,
  723. templateValues: {
  724. quadkey: BingMapsImageryProvider.tileXYToQuadKey(x, y, level),
  725. subdomain: subdomains[subdomainIndex],
  726. culture: imageryProvider._culture,
  727. },
  728. queryParameters: {
  729. // this parameter tells the Bing servers to send a zero-length response
  730. // instead of a placeholder image for missing tiles.
  731. n: "z",
  732. },
  733. });
  734. }
  735. var intersectionScratch = new Rectangle();
  736. function getRectangleAttribution(attributionList, level, rectangle) {
  737. // Bing levels start at 1, while ours start at 0.
  738. ++level;
  739. var result = [];
  740. for (
  741. var attributionIndex = 0, attributionLength = attributionList.length;
  742. attributionIndex < attributionLength;
  743. ++attributionIndex
  744. ) {
  745. var attribution = attributionList[attributionIndex];
  746. var coverageAreas = attribution.coverageAreas;
  747. var included = false;
  748. for (
  749. var areaIndex = 0, areaLength = attribution.coverageAreas.length;
  750. !included && areaIndex < areaLength;
  751. ++areaIndex
  752. ) {
  753. var area = coverageAreas[areaIndex];
  754. if (level >= area.zoomMin && level <= area.zoomMax) {
  755. var intersection = Rectangle.intersection(
  756. rectangle,
  757. area.bbox,
  758. intersectionScratch
  759. );
  760. if (defined(intersection)) {
  761. included = true;
  762. }
  763. }
  764. }
  765. if (included) {
  766. result.push(attribution.credit);
  767. }
  768. }
  769. return result;
  770. }
  771. // Exposed for testing
  772. BingMapsImageryProvider._metadataCache = {};
  773. export default BingMapsImageryProvider;