SingleTileImageryProvider.js 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502
  1. import Credit from "../Core/Credit.js";
  2. import defaultValue from "../Core/defaultValue.js";
  3. import defined from "../Core/defined.js";
  4. import DeveloperError from "../Core/DeveloperError.js";
  5. import Event from "../Core/Event.js";
  6. import GeographicTilingScheme from "../Core/GeographicTilingScheme.js";
  7. import Rectangle from "../Core/Rectangle.js";
  8. import Resource from "../Core/Resource.js";
  9. import RuntimeError from "../Core/RuntimeError.js";
  10. import TileProviderError from "../Core/TileProviderError.js";
  11. import when from "../ThirdParty/when.js";
  12. import ImageryProvider from "./ImageryProvider.js";
  13. /**
  14. * @typedef {Object} SingleTileImageryProvider.ConstructorOptions
  15. *
  16. * Initialization options for the SingleTileImageryProvider constructor
  17. *
  18. * @property {Resource|String} url The url for the tile.
  19. * @property {Rectangle} [rectangle=Rectangle.MAX_VALUE] The rectangle, in radians, covered by the image.
  20. * @property {Credit|String} [credit] A credit for the data source, which is displayed on the canvas.
  21. * @property {Ellipsoid} [ellipsoid] The ellipsoid. If not specified, the WGS84 ellipsoid is used.
  22. */
  23. /**
  24. * Provides a single, top-level imagery tile. The single image is assumed to use a
  25. * {@link GeographicTilingScheme}.
  26. *
  27. * @alias SingleTileImageryProvider
  28. * @constructor
  29. *
  30. * @param {SingleTileImageryProvider.ConstructorOptions} options Object describing initialization options
  31. *
  32. * @see ArcGisMapServerImageryProvider
  33. * @see BingMapsImageryProvider
  34. * @see GoogleEarthEnterpriseMapsProvider
  35. * @see OpenStreetMapImageryProvider
  36. * @see TileMapServiceImageryProvider
  37. * @see WebMapServiceImageryProvider
  38. * @see WebMapTileServiceImageryProvider
  39. * @see UrlTemplateImageryProvider
  40. */
  41. function SingleTileImageryProvider(options) {
  42. options = defaultValue(options, defaultValue.EMPTY_OBJECT);
  43. //>>includeStart('debug', pragmas.debug);
  44. if (!defined(options.url)) {
  45. throw new DeveloperError("options.url is required.");
  46. }
  47. //>>includeEnd('debug');
  48. /**
  49. * The default alpha blending value of this provider, with 0.0 representing fully transparent and
  50. * 1.0 representing fully opaque.
  51. *
  52. * @type {Number|undefined}
  53. * @default undefined
  54. */
  55. this.defaultAlpha = undefined;
  56. /**
  57. * The default alpha blending value on the night side of the globe of this provider, with 0.0 representing fully transparent and
  58. * 1.0 representing fully opaque.
  59. *
  60. * @type {Number|undefined}
  61. * @default undefined
  62. */
  63. this.defaultNightAlpha = undefined;
  64. /**
  65. * The default alpha blending value on the day side of the globe of this provider, with 0.0 representing fully transparent and
  66. * 1.0 representing fully opaque.
  67. *
  68. * @type {Number|undefined}
  69. * @default undefined
  70. */
  71. this.defaultDayAlpha = undefined;
  72. /**
  73. * The default brightness of this provider. 1.0 uses the unmodified imagery color. Less than 1.0
  74. * makes the imagery darker while greater than 1.0 makes it brighter.
  75. *
  76. * @type {Number|undefined}
  77. * @default undefined
  78. */
  79. this.defaultBrightness = undefined;
  80. /**
  81. * The default contrast of this provider. 1.0 uses the unmodified imagery color. Less than 1.0 reduces
  82. * the contrast while greater than 1.0 increases it.
  83. *
  84. * @type {Number|undefined}
  85. * @default undefined
  86. */
  87. this.defaultContrast = undefined;
  88. /**
  89. * The default hue of this provider in radians. 0.0 uses the unmodified imagery color.
  90. *
  91. * @type {Number|undefined}
  92. * @default undefined
  93. */
  94. this.defaultHue = undefined;
  95. /**
  96. * The default saturation of this provider. 1.0 uses the unmodified imagery color. Less than 1.0 reduces the
  97. * saturation while greater than 1.0 increases it.
  98. *
  99. * @type {Number|undefined}
  100. * @default undefined
  101. */
  102. this.defaultSaturation = undefined;
  103. /**
  104. * The default gamma correction to apply to this provider. 1.0 uses the unmodified imagery color.
  105. *
  106. * @type {Number|undefined}
  107. * @default undefined
  108. */
  109. this.defaultGamma = undefined;
  110. /**
  111. * The default texture minification filter to apply to this provider.
  112. *
  113. * @type {TextureMinificationFilter}
  114. * @default undefined
  115. */
  116. this.defaultMinificationFilter = undefined;
  117. /**
  118. * The default texture magnification filter to apply to this provider.
  119. *
  120. * @type {TextureMagnificationFilter}
  121. * @default undefined
  122. */
  123. this.defaultMagnificationFilter = undefined;
  124. var resource = Resource.createIfNeeded(options.url);
  125. var rectangle = defaultValue(options.rectangle, Rectangle.MAX_VALUE);
  126. var tilingScheme = new GeographicTilingScheme({
  127. rectangle: rectangle,
  128. numberOfLevelZeroTilesX: 1,
  129. numberOfLevelZeroTilesY: 1,
  130. ellipsoid: options.ellipsoid,
  131. });
  132. this._tilingScheme = tilingScheme;
  133. this._resource = resource;
  134. this._image = undefined;
  135. this._texture = undefined;
  136. this._tileWidth = 0;
  137. this._tileHeight = 0;
  138. this._errorEvent = new Event();
  139. this._ready = false;
  140. this._readyPromise = when.defer();
  141. var credit = options.credit;
  142. if (typeof credit === "string") {
  143. credit = new Credit(credit);
  144. }
  145. this._credit = credit;
  146. var that = this;
  147. var error;
  148. function success(image) {
  149. that._image = image;
  150. that._tileWidth = image.width;
  151. that._tileHeight = image.height;
  152. that._ready = true;
  153. that._readyPromise.resolve(true);
  154. TileProviderError.handleSuccess(that._errorEvent);
  155. }
  156. function failure(e) {
  157. var message = "Failed to load image " + resource.url + ".";
  158. error = TileProviderError.handleError(
  159. error,
  160. that,
  161. that._errorEvent,
  162. message,
  163. 0,
  164. 0,
  165. 0,
  166. doRequest,
  167. e
  168. );
  169. that._readyPromise.reject(new RuntimeError(message));
  170. }
  171. function doRequest() {
  172. ImageryProvider.loadImage(null, resource).then(success).otherwise(failure);
  173. }
  174. doRequest();
  175. }
  176. Object.defineProperties(SingleTileImageryProvider.prototype, {
  177. /**
  178. * Gets the URL of the single, top-level imagery tile.
  179. * @memberof SingleTileImageryProvider.prototype
  180. * @type {String}
  181. * @readonly
  182. */
  183. url: {
  184. get: function () {
  185. return this._resource.url;
  186. },
  187. },
  188. /**
  189. * Gets the proxy used by this provider.
  190. * @memberof SingleTileImageryProvider.prototype
  191. * @type {Proxy}
  192. * @readonly
  193. */
  194. proxy: {
  195. get: function () {
  196. return this._resource.proxy;
  197. },
  198. },
  199. /**
  200. * Gets the width of each tile, in pixels. This function should
  201. * not be called before {@link SingleTileImageryProvider#ready} returns true.
  202. * @memberof SingleTileImageryProvider.prototype
  203. * @type {Number}
  204. * @readonly
  205. */
  206. tileWidth: {
  207. get: function () {
  208. //>>includeStart('debug', pragmas.debug);
  209. if (!this._ready) {
  210. throw new DeveloperError(
  211. "tileWidth must not be called before the imagery provider is ready."
  212. );
  213. }
  214. //>>includeEnd('debug');
  215. return this._tileWidth;
  216. },
  217. },
  218. /**
  219. * Gets the height of each tile, in pixels. This function should
  220. * not be called before {@link SingleTileImageryProvider#ready} returns true.
  221. * @memberof SingleTileImageryProvider.prototype
  222. * @type {Number}
  223. * @readonly
  224. */
  225. tileHeight: {
  226. get: function () {
  227. //>>includeStart('debug', pragmas.debug);
  228. if (!this._ready) {
  229. throw new DeveloperError(
  230. "tileHeight must not be called before the imagery provider is ready."
  231. );
  232. }
  233. //>>includeEnd('debug');
  234. return this._tileHeight;
  235. },
  236. },
  237. /**
  238. * Gets the maximum level-of-detail that can be requested. This function should
  239. * not be called before {@link SingleTileImageryProvider#ready} returns true.
  240. * @memberof SingleTileImageryProvider.prototype
  241. * @type {Number|undefined}
  242. * @readonly
  243. */
  244. maximumLevel: {
  245. get: function () {
  246. //>>includeStart('debug', pragmas.debug);
  247. if (!this._ready) {
  248. throw new DeveloperError(
  249. "maximumLevel must not be called before the imagery provider is ready."
  250. );
  251. }
  252. //>>includeEnd('debug');
  253. return 0;
  254. },
  255. },
  256. /**
  257. * Gets the minimum level-of-detail that can be requested. This function should
  258. * not be called before {@link SingleTileImageryProvider#ready} returns true.
  259. * @memberof SingleTileImageryProvider.prototype
  260. * @type {Number}
  261. * @readonly
  262. */
  263. minimumLevel: {
  264. get: function () {
  265. //>>includeStart('debug', pragmas.debug);
  266. if (!this._ready) {
  267. throw new DeveloperError(
  268. "minimumLevel must not be called before the imagery provider is ready."
  269. );
  270. }
  271. //>>includeEnd('debug');
  272. return 0;
  273. },
  274. },
  275. /**
  276. * Gets the tiling scheme used by this provider. This function should
  277. * not be called before {@link SingleTileImageryProvider#ready} returns true.
  278. * @memberof SingleTileImageryProvider.prototype
  279. * @type {TilingScheme}
  280. * @readonly
  281. */
  282. tilingScheme: {
  283. get: function () {
  284. //>>includeStart('debug', pragmas.debug);
  285. if (!this._ready) {
  286. throw new DeveloperError(
  287. "tilingScheme must not be called before the imagery provider is ready."
  288. );
  289. }
  290. //>>includeEnd('debug');
  291. return this._tilingScheme;
  292. },
  293. },
  294. /**
  295. * Gets the rectangle, in radians, of the imagery provided by this instance. This function should
  296. * not be called before {@link SingleTileImageryProvider#ready} returns true.
  297. * @memberof SingleTileImageryProvider.prototype
  298. * @type {Rectangle}
  299. * @readonly
  300. */
  301. rectangle: {
  302. get: function () {
  303. return this._tilingScheme.rectangle;
  304. },
  305. },
  306. /**
  307. * Gets the tile discard policy. If not undefined, the discard policy is responsible
  308. * for filtering out "missing" tiles via its shouldDiscardImage function. If this function
  309. * returns undefined, no tiles are filtered. This function should
  310. * not be called before {@link SingleTileImageryProvider#ready} returns true.
  311. * @memberof SingleTileImageryProvider.prototype
  312. * @type {TileDiscardPolicy}
  313. * @readonly
  314. */
  315. tileDiscardPolicy: {
  316. get: function () {
  317. //>>includeStart('debug', pragmas.debug);
  318. if (!this._ready) {
  319. throw new DeveloperError(
  320. "tileDiscardPolicy must not be called before the imagery provider is ready."
  321. );
  322. }
  323. //>>includeEnd('debug');
  324. return undefined;
  325. },
  326. },
  327. /**
  328. * Gets an event that is raised when the imagery provider encounters an asynchronous error. By subscribing
  329. * to the event, you will be notified of the error and can potentially recover from it. Event listeners
  330. * are passed an instance of {@link TileProviderError}.
  331. * @memberof SingleTileImageryProvider.prototype
  332. * @type {Event}
  333. * @readonly
  334. */
  335. errorEvent: {
  336. get: function () {
  337. return this._errorEvent;
  338. },
  339. },
  340. /**
  341. * Gets a value indicating whether or not the provider is ready for use.
  342. * @memberof SingleTileImageryProvider.prototype
  343. * @type {Boolean}
  344. * @readonly
  345. */
  346. ready: {
  347. get: function () {
  348. return this._ready;
  349. },
  350. },
  351. /**
  352. * Gets a promise that resolves to true when the provider is ready for use.
  353. * @memberof SingleTileImageryProvider.prototype
  354. * @type {Promise.<Boolean>}
  355. * @readonly
  356. */
  357. readyPromise: {
  358. get: function () {
  359. return this._readyPromise.promise;
  360. },
  361. },
  362. /**
  363. * Gets the credit to display when this imagery provider is active. Typically this is used to credit
  364. * the source of the imagery. This function should not be called before {@link SingleTileImageryProvider#ready} returns true.
  365. * @memberof SingleTileImageryProvider.prototype
  366. * @type {Credit}
  367. * @readonly
  368. */
  369. credit: {
  370. get: function () {
  371. return this._credit;
  372. },
  373. },
  374. /**
  375. * Gets a value indicating whether or not the images provided by this imagery provider
  376. * include an alpha channel. If this property is false, an alpha channel, if present, will
  377. * be ignored. If this property is true, any images without an alpha channel will be treated
  378. * as if their alpha is 1.0 everywhere. When this property is false, memory usage
  379. * and texture upload time are reduced.
  380. * @memberof SingleTileImageryProvider.prototype
  381. * @type {Boolean}
  382. * @readonly
  383. */
  384. hasAlphaChannel: {
  385. get: function () {
  386. return true;
  387. },
  388. },
  389. });
  390. /**
  391. * Gets the credits to be displayed when a given tile is displayed.
  392. *
  393. * @param {Number} x The tile X coordinate.
  394. * @param {Number} y The tile Y coordinate.
  395. * @param {Number} level The tile level;
  396. * @returns {Credit[]} The credits to be displayed when the tile is displayed.
  397. *
  398. * @exception {DeveloperError} <code>getTileCredits</code> must not be called before the imagery provider is ready.
  399. */
  400. SingleTileImageryProvider.prototype.getTileCredits = function (x, y, level) {
  401. return undefined;
  402. };
  403. /**
  404. * Requests the image for a given tile. This function should
  405. * not be called before {@link SingleTileImageryProvider#ready} returns true.
  406. *
  407. * @param {Number} x The tile X coordinate.
  408. * @param {Number} y The tile Y coordinate.
  409. * @param {Number} level The tile level.
  410. * @param {Request} [request] The request object. Intended for internal use only.
  411. * @returns {Promise.<HTMLImageElement|HTMLCanvasElement>|undefined} A promise for the image that will resolve when the image is available, or
  412. * undefined if there are too many active requests to the server, and the request
  413. * should be retried later. The resolved image may be either an
  414. * Image or a Canvas DOM object.
  415. *
  416. * @exception {DeveloperError} <code>requestImage</code> must not be called before the imagery provider is ready.
  417. */
  418. SingleTileImageryProvider.prototype.requestImage = function (
  419. x,
  420. y,
  421. level,
  422. request
  423. ) {
  424. //>>includeStart('debug', pragmas.debug);
  425. if (!this._ready) {
  426. throw new DeveloperError(
  427. "requestImage must not be called before the imagery provider is ready."
  428. );
  429. }
  430. //>>includeEnd('debug');
  431. return this._image;
  432. };
  433. /**
  434. * Picking features is not currently supported by this imagery provider, so this function simply returns
  435. * undefined.
  436. *
  437. * @param {Number} x The tile X coordinate.
  438. * @param {Number} y The tile Y coordinate.
  439. * @param {Number} level The tile level.
  440. * @param {Number} longitude The longitude at which to pick features.
  441. * @param {Number} latitude The latitude at which to pick features.
  442. * @return {Promise.<ImageryLayerFeatureInfo[]>|undefined} A promise for the picked features that will resolve when the asynchronous
  443. * picking completes. The resolved value is an array of {@link ImageryLayerFeatureInfo}
  444. * instances. The array may be empty if no features are found at the given location.
  445. * It may also be undefined if picking is not supported.
  446. */
  447. SingleTileImageryProvider.prototype.pickFeatures = function (
  448. x,
  449. y,
  450. level,
  451. longitude,
  452. latitude
  453. ) {
  454. return undefined;
  455. };
  456. export default SingleTileImageryProvider;