Cartographic-fe4be337.js 60 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527
  1. /**
  2. * Cesium - https://github.com/CesiumGS/cesium
  3. *
  4. * Copyright 2011-2020 Cesium Contributors
  5. *
  6. * Licensed under the Apache License, Version 2.0 (the "License");
  7. * you may not use this file except in compliance with the License.
  8. * You may obtain a copy of the License at
  9. *
  10. * http://www.apache.org/licenses/LICENSE-2.0
  11. *
  12. * Unless required by applicable law or agreed to in writing, software
  13. * distributed under the License is distributed on an "AS IS" BASIS,
  14. * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15. * See the License for the specific language governing permissions and
  16. * limitations under the License.
  17. *
  18. * Columbus View (Pat. Pend.)
  19. *
  20. * Portions licensed separately.
  21. * See https://github.com/CesiumGS/cesium/blob/master/LICENSE.md for full licensing details.
  22. */
  23. define(['exports', './when-8d13db60', './Check-70bec281', './Math-61ede240'], function (exports, when, Check, _Math) { 'use strict';
  24. /**
  25. * A 3D Cartesian point.
  26. * @alias Cartesian3
  27. * @constructor
  28. *
  29. * @param {Number} [x=0.0] The X component.
  30. * @param {Number} [y=0.0] The Y component.
  31. * @param {Number} [z=0.0] The Z component.
  32. *
  33. * @see Cartesian2
  34. * @see Cartesian4
  35. * @see Packable
  36. */
  37. function Cartesian3(x, y, z) {
  38. /**
  39. * The X component.
  40. * @type {Number}
  41. * @default 0.0
  42. */
  43. this.x = when.defaultValue(x, 0.0);
  44. /**
  45. * The Y component.
  46. * @type {Number}
  47. * @default 0.0
  48. */
  49. this.y = when.defaultValue(y, 0.0);
  50. /**
  51. * The Z component.
  52. * @type {Number}
  53. * @default 0.0
  54. */
  55. this.z = when.defaultValue(z, 0.0);
  56. }
  57. /**
  58. * Converts the provided Spherical into Cartesian3 coordinates.
  59. *
  60. * @param {Spherical} spherical The Spherical to be converted to Cartesian3.
  61. * @param {Cartesian3} [result] The object onto which to store the result.
  62. * @returns {Cartesian3} The modified result parameter or a new Cartesian3 instance if one was not provided.
  63. */
  64. Cartesian3.fromSpherical = function(spherical, result) {
  65. //>>includeStart('debug', pragmas.debug);
  66. Check.Check.typeOf.object('spherical', spherical);
  67. //>>includeEnd('debug');
  68. if (!when.defined(result)) {
  69. result = new Cartesian3();
  70. }
  71. var clock = spherical.clock;
  72. var cone = spherical.cone;
  73. var magnitude = when.defaultValue(spherical.magnitude, 1.0);
  74. var radial = magnitude * Math.sin(cone);
  75. result.x = radial * Math.cos(clock);
  76. result.y = radial * Math.sin(clock);
  77. result.z = magnitude * Math.cos(cone);
  78. return result;
  79. };
  80. /**
  81. * Creates a Cartesian3 instance from x, y and z coordinates.
  82. *
  83. * @param {Number} x The x coordinate.
  84. * @param {Number} y The y coordinate.
  85. * @param {Number} z The z coordinate.
  86. * @param {Cartesian3} [result] The object onto which to store the result.
  87. * @returns {Cartesian3} The modified result parameter or a new Cartesian3 instance if one was not provided.
  88. */
  89. Cartesian3.fromElements = function(x, y, z, result) {
  90. if (!when.defined(result)) {
  91. return new Cartesian3(x, y, z);
  92. }
  93. result.x = x;
  94. result.y = y;
  95. result.z = z;
  96. return result;
  97. };
  98. /**
  99. * Duplicates a Cartesian3 instance.
  100. *
  101. * @param {Cartesian3} cartesian The Cartesian to duplicate.
  102. * @param {Cartesian3} [result] The object onto which to store the result.
  103. * @returns {Cartesian3} The modified result parameter or a new Cartesian3 instance if one was not provided. (Returns undefined if cartesian is undefined)
  104. */
  105. Cartesian3.clone = function(cartesian, result) {
  106. if (!when.defined(cartesian)) {
  107. return undefined;
  108. }
  109. if (!when.defined(result)) {
  110. return new Cartesian3(cartesian.x, cartesian.y, cartesian.z);
  111. }
  112. result.x = cartesian.x;
  113. result.y = cartesian.y;
  114. result.z = cartesian.z;
  115. return result;
  116. };
  117. /**
  118. * Creates a Cartesian3 instance from an existing Cartesian4. This simply takes the
  119. * x, y, and z properties of the Cartesian4 and drops w.
  120. * @function
  121. *
  122. * @param {Cartesian4} cartesian The Cartesian4 instance to create a Cartesian3 instance from.
  123. * @param {Cartesian3} [result] The object onto which to store the result.
  124. * @returns {Cartesian3} The modified result parameter or a new Cartesian3 instance if one was not provided.
  125. */
  126. Cartesian3.fromCartesian4 = Cartesian3.clone;
  127. /**
  128. * The number of elements used to pack the object into an array.
  129. * @type {Number}
  130. */
  131. Cartesian3.packedLength = 3;
  132. /**
  133. * Stores the provided instance into the provided array.
  134. *
  135. * @param {Cartesian3} value The value to pack.
  136. * @param {Number[]} array The array to pack into.
  137. * @param {Number} [startingIndex=0] The index into the array at which to start packing the elements.
  138. *
  139. * @returns {Number[]} The array that was packed into
  140. */
  141. Cartesian3.pack = function(value, array, startingIndex) {
  142. //>>includeStart('debug', pragmas.debug);
  143. Check.Check.typeOf.object('value', value);
  144. Check.Check.defined('array', array);
  145. //>>includeEnd('debug');
  146. startingIndex = when.defaultValue(startingIndex, 0);
  147. array[startingIndex++] = value.x;
  148. array[startingIndex++] = value.y;
  149. array[startingIndex] = value.z;
  150. return array;
  151. };
  152. /**
  153. * Retrieves an instance from a packed array.
  154. *
  155. * @param {Number[]} array The packed array.
  156. * @param {Number} [startingIndex=0] The starting index of the element to be unpacked.
  157. * @param {Cartesian3} [result] The object into which to store the result.
  158. * @returns {Cartesian3} The modified result parameter or a new Cartesian3 instance if one was not provided.
  159. */
  160. Cartesian3.unpack = function(array, startingIndex, result) {
  161. //>>includeStart('debug', pragmas.debug);
  162. Check.Check.defined('array', array);
  163. //>>includeEnd('debug');
  164. startingIndex = when.defaultValue(startingIndex, 0);
  165. if (!when.defined(result)) {
  166. result = new Cartesian3();
  167. }
  168. result.x = array[startingIndex++];
  169. result.y = array[startingIndex++];
  170. result.z = array[startingIndex];
  171. return result;
  172. };
  173. /**
  174. * Flattens an array of Cartesian3s into an array of components.
  175. *
  176. * @param {Cartesian3[]} array The array of cartesians to pack.
  177. * @param {Number[]} result The array onto which to store the result.
  178. * @returns {Number[]} The packed array.
  179. */
  180. Cartesian3.packArray = function(array, result) {
  181. //>>includeStart('debug', pragmas.debug);
  182. Check.Check.defined('array', array);
  183. //>>includeEnd('debug');
  184. var length = array.length;
  185. if (!when.defined(result)) {
  186. result = new Array(length * 3);
  187. } else {
  188. result.length = length * 3;
  189. }
  190. for (var i = 0; i < length; ++i) {
  191. Cartesian3.pack(array[i], result, i * 3);
  192. }
  193. return result;
  194. };
  195. /**
  196. * Unpacks an array of cartesian components into an array of Cartesian3s.
  197. *
  198. * @param {Number[]} array The array of components to unpack.
  199. * @param {Cartesian3[]} result The array onto which to store the result.
  200. * @returns {Cartesian3[]} The unpacked array.
  201. */
  202. Cartesian3.unpackArray = function(array, result) {
  203. //>>includeStart('debug', pragmas.debug);
  204. Check.Check.defined('array', array);
  205. Check.Check.typeOf.number.greaterThanOrEquals('array.length', array.length, 3);
  206. if (array.length % 3 !== 0) {
  207. throw new Check.DeveloperError('array length must be a multiple of 3.');
  208. }
  209. //>>includeEnd('debug');
  210. var length = array.length;
  211. if (!when.defined(result)) {
  212. result = new Array(length / 3);
  213. } else {
  214. result.length = length / 3;
  215. }
  216. for (var i = 0; i < length; i += 3) {
  217. var index = i / 3;
  218. result[index] = Cartesian3.unpack(array, i, result[index]);
  219. }
  220. return result;
  221. };
  222. /**
  223. * Creates a Cartesian3 from three consecutive elements in an array.
  224. * @function
  225. *
  226. * @param {Number[]} array The array whose three consecutive elements correspond to the x, y, and z components, respectively.
  227. * @param {Number} [startingIndex=0] The offset into the array of the first element, which corresponds to the x component.
  228. * @param {Cartesian3} [result] The object onto which to store the result.
  229. * @returns {Cartesian3} The modified result parameter or a new Cartesian3 instance if one was not provided.
  230. *
  231. * @example
  232. * // Create a Cartesian3 with (1.0, 2.0, 3.0)
  233. * var v = [1.0, 2.0, 3.0];
  234. * var p = Cesium.Cartesian3.fromArray(v);
  235. *
  236. * // Create a Cartesian3 with (1.0, 2.0, 3.0) using an offset into an array
  237. * var v2 = [0.0, 0.0, 1.0, 2.0, 3.0];
  238. * var p2 = Cesium.Cartesian3.fromArray(v2, 2);
  239. */
  240. Cartesian3.fromArray = Cartesian3.unpack;
  241. /**
  242. * Computes the value of the maximum component for the supplied Cartesian.
  243. *
  244. * @param {Cartesian3} cartesian The cartesian to use.
  245. * @returns {Number} The value of the maximum component.
  246. */
  247. Cartesian3.maximumComponent = function(cartesian) {
  248. //>>includeStart('debug', pragmas.debug);
  249. Check.Check.typeOf.object('cartesian', cartesian);
  250. //>>includeEnd('debug');
  251. return Math.max(cartesian.x, cartesian.y, cartesian.z);
  252. };
  253. /**
  254. * Computes the value of the minimum component for the supplied Cartesian.
  255. *
  256. * @param {Cartesian3} cartesian The cartesian to use.
  257. * @returns {Number} The value of the minimum component.
  258. */
  259. Cartesian3.minimumComponent = function(cartesian) {
  260. //>>includeStart('debug', pragmas.debug);
  261. Check.Check.typeOf.object('cartesian', cartesian);
  262. //>>includeEnd('debug');
  263. return Math.min(cartesian.x, cartesian.y, cartesian.z);
  264. };
  265. /**
  266. * Compares two Cartesians and computes a Cartesian which contains the minimum components of the supplied Cartesians.
  267. *
  268. * @param {Cartesian3} first A cartesian to compare.
  269. * @param {Cartesian3} second A cartesian to compare.
  270. * @param {Cartesian3} result The object into which to store the result.
  271. * @returns {Cartesian3} A cartesian with the minimum components.
  272. */
  273. Cartesian3.minimumByComponent = function(first, second, result) {
  274. //>>includeStart('debug', pragmas.debug);
  275. Check.Check.typeOf.object('first', first);
  276. Check.Check.typeOf.object('second', second);
  277. Check.Check.typeOf.object('result', result);
  278. //>>includeEnd('debug');
  279. result.x = Math.min(first.x, second.x);
  280. result.y = Math.min(first.y, second.y);
  281. result.z = Math.min(first.z, second.z);
  282. return result;
  283. };
  284. /**
  285. * Compares two Cartesians and computes a Cartesian which contains the maximum components of the supplied Cartesians.
  286. *
  287. * @param {Cartesian3} first A cartesian to compare.
  288. * @param {Cartesian3} second A cartesian to compare.
  289. * @param {Cartesian3} result The object into which to store the result.
  290. * @returns {Cartesian3} A cartesian with the maximum components.
  291. */
  292. Cartesian3.maximumByComponent = function(first, second, result) {
  293. //>>includeStart('debug', pragmas.debug);
  294. Check.Check.typeOf.object('first', first);
  295. Check.Check.typeOf.object('second', second);
  296. Check.Check.typeOf.object('result', result);
  297. //>>includeEnd('debug');
  298. result.x = Math.max(first.x, second.x);
  299. result.y = Math.max(first.y, second.y);
  300. result.z = Math.max(first.z, second.z);
  301. return result;
  302. };
  303. /**
  304. * Computes the provided Cartesian's squared magnitude.
  305. *
  306. * @param {Cartesian3} cartesian The Cartesian instance whose squared magnitude is to be computed.
  307. * @returns {Number} The squared magnitude.
  308. */
  309. Cartesian3.magnitudeSquared = function(cartesian) {
  310. //>>includeStart('debug', pragmas.debug);
  311. Check.Check.typeOf.object('cartesian', cartesian);
  312. //>>includeEnd('debug');
  313. return cartesian.x * cartesian.x + cartesian.y * cartesian.y + cartesian.z * cartesian.z;
  314. };
  315. /**
  316. * Computes the Cartesian's magnitude (length).
  317. *
  318. * @param {Cartesian3} cartesian The Cartesian instance whose magnitude is to be computed.
  319. * @returns {Number} The magnitude.
  320. */
  321. Cartesian3.magnitude = function(cartesian) {
  322. return Math.sqrt(Cartesian3.magnitudeSquared(cartesian));
  323. };
  324. var distanceScratch = new Cartesian3();
  325. /**
  326. * Computes the distance between two points.
  327. *
  328. * @param {Cartesian3} left The first point to compute the distance from.
  329. * @param {Cartesian3} right The second point to compute the distance to.
  330. * @returns {Number} The distance between two points.
  331. *
  332. * @example
  333. * // Returns 1.0
  334. * var d = Cesium.Cartesian3.distance(new Cesium.Cartesian3(1.0, 0.0, 0.0), new Cesium.Cartesian3(2.0, 0.0, 0.0));
  335. */
  336. Cartesian3.distance = function(left, right) {
  337. //>>includeStart('debug', pragmas.debug);
  338. Check.Check.typeOf.object('left', left);
  339. Check.Check.typeOf.object('right', right);
  340. //>>includeEnd('debug');
  341. Cartesian3.subtract(left, right, distanceScratch);
  342. return Cartesian3.magnitude(distanceScratch);
  343. };
  344. /**
  345. * Computes the squared distance between two points. Comparing squared distances
  346. * using this function is more efficient than comparing distances using {@link Cartesian3#distance}.
  347. *
  348. * @param {Cartesian3} left The first point to compute the distance from.
  349. * @param {Cartesian3} right The second point to compute the distance to.
  350. * @returns {Number} The distance between two points.
  351. *
  352. * @example
  353. * // Returns 4.0, not 2.0
  354. * var d = Cesium.Cartesian3.distanceSquared(new Cesium.Cartesian3(1.0, 0.0, 0.0), new Cesium.Cartesian3(3.0, 0.0, 0.0));
  355. */
  356. Cartesian3.distanceSquared = function(left, right) {
  357. //>>includeStart('debug', pragmas.debug);
  358. Check.Check.typeOf.object('left', left);
  359. Check.Check.typeOf.object('right', right);
  360. //>>includeEnd('debug');
  361. Cartesian3.subtract(left, right, distanceScratch);
  362. return Cartesian3.magnitudeSquared(distanceScratch);
  363. };
  364. /**
  365. * Computes the normalized form of the supplied Cartesian.
  366. *
  367. * @param {Cartesian3} cartesian The Cartesian to be normalized.
  368. * @param {Cartesian3} result The object onto which to store the result.
  369. * @returns {Cartesian3} The modified result parameter.
  370. */
  371. Cartesian3.normalize = function(cartesian, result) {
  372. //>>includeStart('debug', pragmas.debug);
  373. Check.Check.typeOf.object('cartesian', cartesian);
  374. Check.Check.typeOf.object('result', result);
  375. //>>includeEnd('debug');
  376. var magnitude = Cartesian3.magnitude(cartesian);
  377. result.x = cartesian.x / magnitude;
  378. result.y = cartesian.y / magnitude;
  379. result.z = cartesian.z / magnitude;
  380. //>>includeStart('debug', pragmas.debug);
  381. if (isNaN(result.x) || isNaN(result.y) || isNaN(result.z)) {
  382. throw new Check.DeveloperError('normalized result is not a number');
  383. }
  384. //>>includeEnd('debug');
  385. return result;
  386. };
  387. /**
  388. * Computes the dot (scalar) product of two Cartesians.
  389. *
  390. * @param {Cartesian3} left The first Cartesian.
  391. * @param {Cartesian3} right The second Cartesian.
  392. * @returns {Number} The dot product.
  393. */
  394. Cartesian3.dot = function(left, right) {
  395. //>>includeStart('debug', pragmas.debug);
  396. Check.Check.typeOf.object('left', left);
  397. Check.Check.typeOf.object('right', right);
  398. //>>includeEnd('debug');
  399. return left.x * right.x + left.y * right.y + left.z * right.z;
  400. };
  401. /**
  402. * Computes the componentwise product of two Cartesians.
  403. *
  404. * @param {Cartesian3} left The first Cartesian.
  405. * @param {Cartesian3} right The second Cartesian.
  406. * @param {Cartesian3} result The object onto which to store the result.
  407. * @returns {Cartesian3} The modified result parameter.
  408. */
  409. Cartesian3.multiplyComponents = function(left, right, result) {
  410. //>>includeStart('debug', pragmas.debug);
  411. Check.Check.typeOf.object('left', left);
  412. Check.Check.typeOf.object('right', right);
  413. Check.Check.typeOf.object('result', result);
  414. //>>includeEnd('debug');
  415. result.x = left.x * right.x;
  416. result.y = left.y * right.y;
  417. result.z = left.z * right.z;
  418. return result;
  419. };
  420. /**
  421. * Computes the componentwise quotient of two Cartesians.
  422. *
  423. * @param {Cartesian3} left The first Cartesian.
  424. * @param {Cartesian3} right The second Cartesian.
  425. * @param {Cartesian3} result The object onto which to store the result.
  426. * @returns {Cartesian3} The modified result parameter.
  427. */
  428. Cartesian3.divideComponents = function(left, right, result) {
  429. //>>includeStart('debug', pragmas.debug);
  430. Check.Check.typeOf.object('left', left);
  431. Check.Check.typeOf.object('right', right);
  432. Check.Check.typeOf.object('result', result);
  433. //>>includeEnd('debug');
  434. result.x = left.x / right.x;
  435. result.y = left.y / right.y;
  436. result.z = left.z / right.z;
  437. return result;
  438. };
  439. /**
  440. * Computes the componentwise sum of two Cartesians.
  441. *
  442. * @param {Cartesian3} left The first Cartesian.
  443. * @param {Cartesian3} right The second Cartesian.
  444. * @param {Cartesian3} result The object onto which to store the result.
  445. * @returns {Cartesian3} The modified result parameter.
  446. */
  447. Cartesian3.add = function(left, right, result) {
  448. //>>includeStart('debug', pragmas.debug);
  449. Check.Check.typeOf.object('left', left);
  450. Check.Check.typeOf.object('right', right);
  451. Check.Check.typeOf.object('result', result);
  452. //>>includeEnd('debug');
  453. result.x = left.x + right.x;
  454. result.y = left.y + right.y;
  455. result.z = left.z + right.z;
  456. return result;
  457. };
  458. /**
  459. * Computes the componentwise difference of two Cartesians.
  460. *
  461. * @param {Cartesian3} left The first Cartesian.
  462. * @param {Cartesian3} right The second Cartesian.
  463. * @param {Cartesian3} result The object onto which to store the result.
  464. * @returns {Cartesian3} The modified result parameter.
  465. */
  466. Cartesian3.subtract = function(left, right, result) {
  467. //>>includeStart('debug', pragmas.debug);
  468. Check.Check.typeOf.object('left', left);
  469. Check.Check.typeOf.object('right', right);
  470. Check.Check.typeOf.object('result', result);
  471. //>>includeEnd('debug');
  472. result.x = left.x - right.x;
  473. result.y = left.y - right.y;
  474. result.z = left.z - right.z;
  475. return result;
  476. };
  477. /**
  478. * Multiplies the provided Cartesian componentwise by the provided scalar.
  479. *
  480. * @param {Cartesian3} cartesian The Cartesian to be scaled.
  481. * @param {Number} scalar The scalar to multiply with.
  482. * @param {Cartesian3} result The object onto which to store the result.
  483. * @returns {Cartesian3} The modified result parameter.
  484. */
  485. Cartesian3.multiplyByScalar = function(cartesian, scalar, result) {
  486. //>>includeStart('debug', pragmas.debug);
  487. Check.Check.typeOf.object('cartesian', cartesian);
  488. Check.Check.typeOf.number('scalar', scalar);
  489. Check.Check.typeOf.object('result', result);
  490. //>>includeEnd('debug');
  491. result.x = cartesian.x * scalar;
  492. result.y = cartesian.y * scalar;
  493. result.z = cartesian.z * scalar;
  494. return result;
  495. };
  496. /**
  497. * Divides the provided Cartesian componentwise by the provided scalar.
  498. *
  499. * @param {Cartesian3} cartesian The Cartesian to be divided.
  500. * @param {Number} scalar The scalar to divide by.
  501. * @param {Cartesian3} result The object onto which to store the result.
  502. * @returns {Cartesian3} The modified result parameter.
  503. */
  504. Cartesian3.divideByScalar = function(cartesian, scalar, result) {
  505. //>>includeStart('debug', pragmas.debug);
  506. Check.Check.typeOf.object('cartesian', cartesian);
  507. Check.Check.typeOf.number('scalar', scalar);
  508. Check.Check.typeOf.object('result', result);
  509. //>>includeEnd('debug');
  510. result.x = cartesian.x / scalar;
  511. result.y = cartesian.y / scalar;
  512. result.z = cartesian.z / scalar;
  513. return result;
  514. };
  515. /**
  516. * Negates the provided Cartesian.
  517. *
  518. * @param {Cartesian3} cartesian The Cartesian to be negated.
  519. * @param {Cartesian3} result The object onto which to store the result.
  520. * @returns {Cartesian3} The modified result parameter.
  521. */
  522. Cartesian3.negate = function(cartesian, result) {
  523. //>>includeStart('debug', pragmas.debug);
  524. Check.Check.typeOf.object('cartesian', cartesian);
  525. Check.Check.typeOf.object('result', result);
  526. //>>includeEnd('debug');
  527. result.x = -cartesian.x;
  528. result.y = -cartesian.y;
  529. result.z = -cartesian.z;
  530. return result;
  531. };
  532. /**
  533. * Computes the absolute value of the provided Cartesian.
  534. *
  535. * @param {Cartesian3} cartesian The Cartesian whose absolute value is to be computed.
  536. * @param {Cartesian3} result The object onto which to store the result.
  537. * @returns {Cartesian3} The modified result parameter.
  538. */
  539. Cartesian3.abs = function(cartesian, result) {
  540. //>>includeStart('debug', pragmas.debug);
  541. Check.Check.typeOf.object('cartesian', cartesian);
  542. Check.Check.typeOf.object('result', result);
  543. //>>includeEnd('debug');
  544. result.x = Math.abs(cartesian.x);
  545. result.y = Math.abs(cartesian.y);
  546. result.z = Math.abs(cartesian.z);
  547. return result;
  548. };
  549. var lerpScratch = new Cartesian3();
  550. /**
  551. * Computes the linear interpolation or extrapolation at t using the provided cartesians.
  552. *
  553. * @param {Cartesian3} start The value corresponding to t at 0.0.
  554. * @param {Cartesian3} end The value corresponding to t at 1.0.
  555. * @param {Number} t The point along t at which to interpolate.
  556. * @param {Cartesian3} result The object onto which to store the result.
  557. * @returns {Cartesian3} The modified result parameter.
  558. */
  559. Cartesian3.lerp = function(start, end, t, result) {
  560. //>>includeStart('debug', pragmas.debug);
  561. Check.Check.typeOf.object('start', start);
  562. Check.Check.typeOf.object('end', end);
  563. Check.Check.typeOf.number('t', t);
  564. Check.Check.typeOf.object('result', result);
  565. //>>includeEnd('debug');
  566. Cartesian3.multiplyByScalar(end, t, lerpScratch);
  567. result = Cartesian3.multiplyByScalar(start, 1.0 - t, result);
  568. return Cartesian3.add(lerpScratch, result, result);
  569. };
  570. var angleBetweenScratch = new Cartesian3();
  571. var angleBetweenScratch2 = new Cartesian3();
  572. /**
  573. * Returns the angle, in radians, between the provided Cartesians.
  574. *
  575. * @param {Cartesian3} left The first Cartesian.
  576. * @param {Cartesian3} right The second Cartesian.
  577. * @returns {Number} The angle between the Cartesians.
  578. */
  579. Cartesian3.angleBetween = function(left, right) {
  580. //>>includeStart('debug', pragmas.debug);
  581. Check.Check.typeOf.object('left', left);
  582. Check.Check.typeOf.object('right', right);
  583. //>>includeEnd('debug');
  584. Cartesian3.normalize(left, angleBetweenScratch);
  585. Cartesian3.normalize(right, angleBetweenScratch2);
  586. var cosine = Cartesian3.dot(angleBetweenScratch, angleBetweenScratch2);
  587. var sine = Cartesian3.magnitude(Cartesian3.cross(angleBetweenScratch, angleBetweenScratch2, angleBetweenScratch));
  588. return Math.atan2(sine, cosine);
  589. };
  590. var mostOrthogonalAxisScratch = new Cartesian3();
  591. /**
  592. * Returns the axis that is most orthogonal to the provided Cartesian.
  593. *
  594. * @param {Cartesian3} cartesian The Cartesian on which to find the most orthogonal axis.
  595. * @param {Cartesian3} result The object onto which to store the result.
  596. * @returns {Cartesian3} The most orthogonal axis.
  597. */
  598. Cartesian3.mostOrthogonalAxis = function(cartesian, result) {
  599. //>>includeStart('debug', pragmas.debug);
  600. Check.Check.typeOf.object('cartesian', cartesian);
  601. Check.Check.typeOf.object('result', result);
  602. //>>includeEnd('debug');
  603. var f = Cartesian3.normalize(cartesian, mostOrthogonalAxisScratch);
  604. Cartesian3.abs(f, f);
  605. if (f.x <= f.y) {
  606. if (f.x <= f.z) {
  607. result = Cartesian3.clone(Cartesian3.UNIT_X, result);
  608. } else {
  609. result = Cartesian3.clone(Cartesian3.UNIT_Z, result);
  610. }
  611. } else if (f.y <= f.z) {
  612. result = Cartesian3.clone(Cartesian3.UNIT_Y, result);
  613. } else {
  614. result = Cartesian3.clone(Cartesian3.UNIT_Z, result);
  615. }
  616. return result;
  617. };
  618. /**
  619. * Projects vector a onto vector b
  620. * @param {Cartesian3} a The vector that needs projecting
  621. * @param {Cartesian3} b The vector to project onto
  622. * @param {Cartesian3} result The result cartesian
  623. * @returns {Cartesian3} The modified result parameter
  624. */
  625. Cartesian3.projectVector = function(a, b, result) {
  626. //>>includeStart('debug', pragmas.debug);
  627. Check.Check.defined('a', a);
  628. Check.Check.defined('b', b);
  629. Check.Check.defined('result', result);
  630. //>>includeEnd('debug');
  631. var scalar = Cartesian3.dot(a, b) / Cartesian3.dot(b, b);
  632. return Cartesian3.multiplyByScalar(b, scalar, result);
  633. };
  634. /**
  635. * Compares the provided Cartesians componentwise and returns
  636. * <code>true</code> if they are equal, <code>false</code> otherwise.
  637. *
  638. * @param {Cartesian3} [left] The first Cartesian.
  639. * @param {Cartesian3} [right] The second Cartesian.
  640. * @returns {Boolean} <code>true</code> if left and right are equal, <code>false</code> otherwise.
  641. */
  642. Cartesian3.equals = function(left, right) {
  643. return (left === right) ||
  644. ((when.defined(left)) &&
  645. (when.defined(right)) &&
  646. (left.x === right.x) &&
  647. (left.y === right.y) &&
  648. (left.z === right.z));
  649. };
  650. /**
  651. * @private
  652. */
  653. Cartesian3.equalsArray = function(cartesian, array, offset) {
  654. return cartesian.x === array[offset] &&
  655. cartesian.y === array[offset + 1] &&
  656. cartesian.z === array[offset + 2];
  657. };
  658. /**
  659. * Compares the provided Cartesians componentwise and returns
  660. * <code>true</code> if they pass an absolute or relative tolerance test,
  661. * <code>false</code> otherwise.
  662. *
  663. * @param {Cartesian3} [left] The first Cartesian.
  664. * @param {Cartesian3} [right] The second Cartesian.
  665. * @param {Number} relativeEpsilon The relative epsilon tolerance to use for equality testing.
  666. * @param {Number} [absoluteEpsilon=relativeEpsilon] The absolute epsilon tolerance to use for equality testing.
  667. * @returns {Boolean} <code>true</code> if left and right are within the provided epsilon, <code>false</code> otherwise.
  668. */
  669. Cartesian3.equalsEpsilon = function(left, right, relativeEpsilon, absoluteEpsilon) {
  670. return (left === right) ||
  671. (when.defined(left) &&
  672. when.defined(right) &&
  673. _Math.CesiumMath.equalsEpsilon(left.x, right.x, relativeEpsilon, absoluteEpsilon) &&
  674. _Math.CesiumMath.equalsEpsilon(left.y, right.y, relativeEpsilon, absoluteEpsilon) &&
  675. _Math.CesiumMath.equalsEpsilon(left.z, right.z, relativeEpsilon, absoluteEpsilon));
  676. };
  677. /**
  678. * Computes the cross (outer) product of two Cartesians.
  679. *
  680. * @param {Cartesian3} left The first Cartesian.
  681. * @param {Cartesian3} right The second Cartesian.
  682. * @param {Cartesian3} result The object onto which to store the result.
  683. * @returns {Cartesian3} The cross product.
  684. */
  685. Cartesian3.cross = function(left, right, result) {
  686. //>>includeStart('debug', pragmas.debug);
  687. Check.Check.typeOf.object('left', left);
  688. Check.Check.typeOf.object('right', right);
  689. Check.Check.typeOf.object('result', result);
  690. //>>includeEnd('debug');
  691. var leftX = left.x;
  692. var leftY = left.y;
  693. var leftZ = left.z;
  694. var rightX = right.x;
  695. var rightY = right.y;
  696. var rightZ = right.z;
  697. var x = leftY * rightZ - leftZ * rightY;
  698. var y = leftZ * rightX - leftX * rightZ;
  699. var z = leftX * rightY - leftY * rightX;
  700. result.x = x;
  701. result.y = y;
  702. result.z = z;
  703. return result;
  704. };
  705. /**
  706. * Computes the midpoint between the right and left Cartesian.
  707. * @param {Cartesian3} left The first Cartesian.
  708. * @param {Cartesian3} right The second Cartesian.
  709. * @param {Cartesian3} result The object onto which to store the result.
  710. * @returns {Cartesian3} The midpoint.
  711. */
  712. Cartesian3.midpoint = function(left, right, result) {
  713. //>>includeStart('debug', pragmas.debug);
  714. Check.Check.typeOf.object('left', left);
  715. Check.Check.typeOf.object('right', right);
  716. Check.Check.typeOf.object('result', result);
  717. //>>includeEnd('debug');
  718. result.x = (left.x + right.x) * 0.5;
  719. result.y = (left.y + right.y) * 0.5;
  720. result.z = (left.z + right.z) * 0.5;
  721. return result;
  722. };
  723. /**
  724. * Returns a Cartesian3 position from longitude and latitude values given in degrees.
  725. *
  726. * @param {Number} longitude The longitude, in degrees
  727. * @param {Number} latitude The latitude, in degrees
  728. * @param {Number} [height=0.0] The height, in meters, above the ellipsoid.
  729. * @param {Ellipsoid} [ellipsoid=Ellipsoid.WGS84] The ellipsoid on which the position lies.
  730. * @param {Cartesian3} [result] The object onto which to store the result.
  731. * @returns {Cartesian3} The position
  732. *
  733. * @example
  734. * var position = Cesium.Cartesian3.fromDegrees(-115.0, 37.0);
  735. */
  736. Cartesian3.fromDegrees = function(longitude, latitude, height, ellipsoid, result) {
  737. //>>includeStart('debug', pragmas.debug);
  738. Check.Check.typeOf.number('longitude', longitude);
  739. Check.Check.typeOf.number('latitude', latitude);
  740. //>>includeEnd('debug');
  741. longitude = _Math.CesiumMath.toRadians(longitude);
  742. latitude = _Math.CesiumMath.toRadians(latitude);
  743. return Cartesian3.fromRadians(longitude, latitude, height, ellipsoid, result);
  744. };
  745. var scratchN = new Cartesian3();
  746. var scratchK = new Cartesian3();
  747. var wgs84RadiiSquared = new Cartesian3(6378137.0 * 6378137.0, 6378137.0 * 6378137.0, 6356752.3142451793 * 6356752.3142451793);
  748. var wgs84RadiiSquaredEx = new Cartesian3(6378137.0 * 6378137.0, 6378137.0 * 6378137.0, 6378137 * 6378137);
  749. /**
  750. * Returns a Cartesian3 position from longitude and latitude values given in radians.
  751. *
  752. * @param {Number} longitude The longitude, in radians
  753. * @param {Number} latitude The latitude, in radians
  754. * @param {Number} [height=0.0] The height, in meters, above the ellipsoid.
  755. * @param {Ellipsoid} [ellipsoid=Ellipsoid.WGS84] The ellipsoid on which the position lies.
  756. * @param {Cartesian3} [result] The object onto which to store the result.
  757. * @returns {Cartesian3} The position
  758. *
  759. * @example
  760. * var position = Cesium.Cartesian3.fromRadians(-2.007, 0.645);
  761. */
  762. Cartesian3.fromRadians = function(longitude, latitude, height, ellipsoid, result) {
  763. //>>includeStart('debug', pragmas.debug);
  764. Check.Check.typeOf.number('longitude', longitude);
  765. Check.Check.typeOf.number('latitude', latitude);
  766. //>>includeEnd('debug');
  767. height = when.defaultValue(height, 0.0);
  768. var radiiSquared = when.defined(ellipsoid) ? ellipsoid.radiiSquared : wgs84RadiiSquaredEx;
  769. if(_Math.CesiumMath.equalsEpsilon(_Math.CesiumMath.Radius, 6356752.3142451793, _Math.CesiumMath.EPSILON10))
  770. {
  771. radiiSquared = when.defined(ellipsoid) ? ellipsoid.radiiSquared : wgs84RadiiSquared;
  772. }
  773. var cosLatitude = Math.cos(latitude);
  774. scratchN.x = cosLatitude * Math.cos(longitude);
  775. scratchN.y = cosLatitude * Math.sin(longitude);
  776. scratchN.z = Math.sin(latitude);
  777. scratchN = Cartesian3.normalize(scratchN, scratchN);
  778. Cartesian3.multiplyComponents(radiiSquared, scratchN, scratchK);
  779. var gamma = Math.sqrt(Cartesian3.dot(scratchN, scratchK));
  780. scratchK = Cartesian3.divideByScalar(scratchK, gamma, scratchK);
  781. scratchN = Cartesian3.multiplyByScalar(scratchN, height, scratchN);
  782. if (!when.defined(result)) {
  783. result = new Cartesian3();
  784. }
  785. return Cartesian3.add(scratchK, scratchN, result);
  786. };
  787. /**
  788. * Returns an array of Cartesian3 positions given an array of longitude and latitude values given in degrees.
  789. *
  790. * @param {Number[]} coordinates A list of longitude and latitude values. Values alternate [longitude, latitude, longitude, latitude...].
  791. * @param {Ellipsoid} [ellipsoid=Ellipsoid.WGS84] The ellipsoid on which the coordinates lie.
  792. * @param {Cartesian3[]} [result] An array of Cartesian3 objects to store the result.
  793. * @returns {Cartesian3[]} The array of positions.
  794. *
  795. * @example
  796. * var positions = Cesium.Cartesian3.fromDegreesArray([-115.0, 37.0, -107.0, 33.0]);
  797. */
  798. Cartesian3.fromDegreesArray = function(coordinates, ellipsoid, result) {
  799. //>>includeStart('debug', pragmas.debug);
  800. Check.Check.defined('coordinates', coordinates);
  801. if (coordinates.length < 2 || coordinates.length % 2 !== 0) {
  802. throw new Check.DeveloperError('the number of coordinates must be a multiple of 2 and at least 2');
  803. }
  804. //>>includeEnd('debug');
  805. var length = coordinates.length;
  806. if (!when.defined(result)) {
  807. result = new Array(length / 2);
  808. } else {
  809. result.length = length / 2;
  810. }
  811. for (var i = 0; i < length; i += 2) {
  812. var longitude = coordinates[i];
  813. var latitude = coordinates[i + 1];
  814. var index = i / 2;
  815. result[index] = Cartesian3.fromDegrees(longitude, latitude, 0, ellipsoid, result[index]);
  816. }
  817. return result;
  818. };
  819. /**
  820. * Returns an array of Cartesian3 positions given an array of longitude and latitude values given in radians.
  821. *
  822. * @param {Number[]} coordinates A list of longitude and latitude values. Values alternate [longitude, latitude, longitude, latitude...].
  823. * @param {Ellipsoid} [ellipsoid=Ellipsoid.WGS84] The ellipsoid on which the coordinates lie.
  824. * @param {Cartesian3[]} [result] An array of Cartesian3 objects to store the result.
  825. * @returns {Cartesian3[]} The array of positions.
  826. *
  827. * @example
  828. * var positions = Cesium.Cartesian3.fromRadiansArray([-2.007, 0.645, -1.867, .575]);
  829. */
  830. Cartesian3.fromRadiansArray = function(coordinates, ellipsoid, result) {
  831. //>>includeStart('debug', pragmas.debug);
  832. Check.Check.defined('coordinates', coordinates);
  833. if (coordinates.length < 2 || coordinates.length % 2 !== 0) {
  834. throw new Check.DeveloperError('the number of coordinates must be a multiple of 2 and at least 2');
  835. }
  836. //>>includeEnd('debug');
  837. var length = coordinates.length;
  838. if (!when.defined(result)) {
  839. result = new Array(length / 2);
  840. } else {
  841. result.length = length / 2;
  842. }
  843. for (var i = 0; i < length; i += 2) {
  844. var longitude = coordinates[i];
  845. var latitude = coordinates[i + 1];
  846. var index = i / 2;
  847. result[index] = Cartesian3.fromRadians(longitude, latitude, 0, ellipsoid, result[index]);
  848. }
  849. return result;
  850. };
  851. /**
  852. * Returns an array of Cartesian3 positions given an array of longitude, latitude and height values where longitude and latitude are given in degrees.
  853. *
  854. * @param {Number[]} coordinates A list of longitude, latitude and height values. Values alternate [longitude, latitude, height, longitude, latitude, height...].
  855. * @param {Ellipsoid} [ellipsoid=Ellipsoid.WGS84] The ellipsoid on which the position lies.
  856. * @param {Cartesian3[]} [result] An array of Cartesian3 objects to store the result.
  857. * @returns {Cartesian3[]} The array of positions.
  858. *
  859. * @example
  860. * var positions = Cesium.Cartesian3.fromDegreesArrayHeights([-115.0, 37.0, 100000.0, -107.0, 33.0, 150000.0]);
  861. */
  862. Cartesian3.fromDegreesArrayHeights = function(coordinates, ellipsoid, result) {
  863. //>>includeStart('debug', pragmas.debug);
  864. Check.Check.defined('coordinates', coordinates);
  865. if (coordinates.length < 3 || coordinates.length % 3 !== 0) {
  866. throw new Check.DeveloperError('the number of coordinates must be a multiple of 3 and at least 3');
  867. }
  868. //>>includeEnd('debug');
  869. var length = coordinates.length;
  870. if (!when.defined(result)) {
  871. result = new Array(length / 3);
  872. } else {
  873. result.length = length / 3;
  874. }
  875. for (var i = 0; i < length; i += 3) {
  876. var longitude = coordinates[i];
  877. var latitude = coordinates[i + 1];
  878. var height = coordinates[i + 2];
  879. var index = i / 3;
  880. result[index] = Cartesian3.fromDegrees(longitude, latitude, height, ellipsoid, result[index]);
  881. }
  882. return result;
  883. };
  884. /**
  885. * Returns an array of Cartesian3 positions given an array of longitude, latitude and height values where longitude and latitude are given in radians.
  886. *
  887. * @param {Number[]} coordinates A list of longitude, latitude and height values. Values alternate [longitude, latitude, height, longitude, latitude, height...].
  888. * @param {Ellipsoid} [ellipsoid=Ellipsoid.WGS84] The ellipsoid on which the position lies.
  889. * @param {Cartesian3[]} [result] An array of Cartesian3 objects to store the result.
  890. * @returns {Cartesian3[]} The array of positions.
  891. *
  892. * @example
  893. * var positions = Cesium.Cartesian3.fromRadiansArrayHeights([-2.007, 0.645, 100000.0, -1.867, .575, 150000.0]);
  894. */
  895. Cartesian3.fromRadiansArrayHeights = function(coordinates, ellipsoid, result) {
  896. //>>includeStart('debug', pragmas.debug);
  897. Check.Check.defined('coordinates', coordinates);
  898. if (coordinates.length < 3 || coordinates.length % 3 !== 0) {
  899. throw new Check.DeveloperError('the number of coordinates must be a multiple of 3 and at least 3');
  900. }
  901. //>>includeEnd('debug');
  902. var length = coordinates.length;
  903. if (!when.defined(result)) {
  904. result = new Array(length / 3);
  905. } else {
  906. result.length = length / 3;
  907. }
  908. for (var i = 0; i < length; i += 3) {
  909. var longitude = coordinates[i];
  910. var latitude = coordinates[i + 1];
  911. var height = coordinates[i + 2];
  912. var index = i / 3;
  913. result[index] = Cartesian3.fromRadians(longitude, latitude, height, ellipsoid, result[index]);
  914. }
  915. return result;
  916. };
  917. /**
  918. * An immutable Cartesian3 instance initialized to (0.0, 0.0, 0.0).
  919. *
  920. * @type {Cartesian3}
  921. * @constant
  922. */
  923. Cartesian3.ZERO = Object.freeze(new Cartesian3(0.0, 0.0, 0.0));
  924. /**
  925. * An immutable Cartesian3 instance initialized to (1.0, 0.0, 0.0).
  926. *
  927. * @type {Cartesian3}
  928. * @constant
  929. */
  930. Cartesian3.UNIT_X = Object.freeze(new Cartesian3(1.0, 0.0, 0.0));
  931. /**
  932. * An immutable Cartesian3 instance initialized to (0.0, 1.0, 0.0).
  933. *
  934. * @type {Cartesian3}
  935. * @constant
  936. */
  937. Cartesian3.UNIT_Y = Object.freeze(new Cartesian3(0.0, 1.0, 0.0));
  938. /**
  939. * An immutable Cartesian3 instance initialized to (0.0, 0.0, 1.0).
  940. *
  941. * @type {Cartesian3}
  942. * @constant
  943. */
  944. Cartesian3.UNIT_Z = Object.freeze(new Cartesian3(0.0, 0.0, 1.0));
  945. /**
  946. * Duplicates this Cartesian3 instance.
  947. *
  948. * @param {Cartesian3} [result] The object onto which to store the result.
  949. * @returns {Cartesian3} The modified result parameter or a new Cartesian3 instance if one was not provided.
  950. */
  951. Cartesian3.prototype.clone = function(result) {
  952. return Cartesian3.clone(this, result);
  953. };
  954. /**
  955. * Compares this Cartesian against the provided Cartesian componentwise and returns
  956. * <code>true</code> if they are equal, <code>false</code> otherwise.
  957. *
  958. * @param {Cartesian3} [right] The right hand side Cartesian.
  959. * @returns {Boolean} <code>true</code> if they are equal, <code>false</code> otherwise.
  960. */
  961. Cartesian3.prototype.equals = function(right) {
  962. return Cartesian3.equals(this, right);
  963. };
  964. /**
  965. * Compares this Cartesian against the provided Cartesian componentwise and returns
  966. * <code>true</code> if they pass an absolute or relative tolerance test,
  967. * <code>false</code> otherwise.
  968. *
  969. * @param {Cartesian3} [right] The right hand side Cartesian.
  970. * @param {Number} relativeEpsilon The relative epsilon tolerance to use for equality testing.
  971. * @param {Number} [absoluteEpsilon=relativeEpsilon] The absolute epsilon tolerance to use for equality testing.
  972. * @returns {Boolean} <code>true</code> if they are within the provided epsilon, <code>false</code> otherwise.
  973. */
  974. Cartesian3.prototype.equalsEpsilon = function(right, relativeEpsilon, absoluteEpsilon) {
  975. return Cartesian3.equalsEpsilon(this, right, relativeEpsilon, absoluteEpsilon);
  976. };
  977. /**
  978. * Creates a string representing this Cartesian in the format '(x, y, z)'.
  979. *
  980. * @returns {String} A string representing this Cartesian in the format '(x, y, z)'.
  981. */
  982. Cartesian3.prototype.toString = function() {
  983. return '(' + this.x + ', ' + this.y + ', ' + this.z + ')';
  984. };
  985. var scaleToGeodeticSurfaceIntersection = new Cartesian3();
  986. var scaleToGeodeticSurfaceGradient = new Cartesian3();
  987. /**
  988. * Scales the provided Cartesian position along the geodetic surface normal
  989. * so that it is on the surface of this ellipsoid. If the position is
  990. * at the center of the ellipsoid, this function returns undefined.
  991. *
  992. * @param {Cartesian3} cartesian The Cartesian position to scale.
  993. * @param {Cartesian3} oneOverRadii One over radii of the ellipsoid.
  994. * @param {Cartesian3} oneOverRadiiSquared One over radii squared of the ellipsoid.
  995. * @param {Number} centerToleranceSquared Tolerance for closeness to the center.
  996. * @param {Cartesian3} [result] The object onto which to store the result.
  997. * @returns {Cartesian3} The modified result parameter, a new Cartesian3 instance if none was provided, or undefined if the position is at the center.
  998. *
  999. * @exports scaleToGeodeticSurface
  1000. *
  1001. * @private
  1002. */
  1003. function scaleToGeodeticSurface(cartesian, oneOverRadii, oneOverRadiiSquared, centerToleranceSquared, result) {
  1004. //>>includeStart('debug', pragmas.debug);
  1005. if (!when.defined(cartesian)) {
  1006. throw new Check.DeveloperError('cartesian is required.');
  1007. }
  1008. if (!when.defined(oneOverRadii)) {
  1009. throw new Check.DeveloperError('oneOverRadii is required.');
  1010. }
  1011. if (!when.defined(oneOverRadiiSquared)) {
  1012. throw new Check.DeveloperError('oneOverRadiiSquared is required.');
  1013. }
  1014. if (!when.defined(centerToleranceSquared)) {
  1015. throw new Check.DeveloperError('centerToleranceSquared is required.');
  1016. }
  1017. //>>includeEnd('debug');
  1018. var positionX = cartesian.x;
  1019. var positionY = cartesian.y;
  1020. var positionZ = cartesian.z;
  1021. var oneOverRadiiX = oneOverRadii.x;
  1022. var oneOverRadiiY = oneOverRadii.y;
  1023. var oneOverRadiiZ = oneOverRadii.z;
  1024. var x2 = positionX * positionX * oneOverRadiiX * oneOverRadiiX;
  1025. var y2 = positionY * positionY * oneOverRadiiY * oneOverRadiiY;
  1026. var z2 = positionZ * positionZ * oneOverRadiiZ * oneOverRadiiZ;
  1027. // Compute the squared ellipsoid norm.
  1028. var squaredNorm = x2 + y2 + z2;
  1029. var ratio = Math.sqrt(1.0 / squaredNorm);
  1030. // As an initial approximation, assume that the radial intersection is the projection point.
  1031. var intersection = Cartesian3.multiplyByScalar(cartesian, ratio, scaleToGeodeticSurfaceIntersection);
  1032. // If the position is near the center, the iteration will not converge.
  1033. if (squaredNorm < centerToleranceSquared) {
  1034. return !isFinite(ratio) ? undefined : Cartesian3.clone(intersection, result);
  1035. }
  1036. var oneOverRadiiSquaredX = oneOverRadiiSquared.x;
  1037. var oneOverRadiiSquaredY = oneOverRadiiSquared.y;
  1038. var oneOverRadiiSquaredZ = oneOverRadiiSquared.z;
  1039. // Use the gradient at the intersection point in place of the true unit normal.
  1040. // The difference in magnitude will be absorbed in the multiplier.
  1041. var gradient = scaleToGeodeticSurfaceGradient;
  1042. gradient.x = intersection.x * oneOverRadiiSquaredX * 2.0;
  1043. gradient.y = intersection.y * oneOverRadiiSquaredY * 2.0;
  1044. gradient.z = intersection.z * oneOverRadiiSquaredZ * 2.0;
  1045. // Compute the initial guess at the normal vector multiplier, lambda.
  1046. var lambda = (1.0 - ratio) * Cartesian3.magnitude(cartesian) / (0.5 * Cartesian3.magnitude(gradient));
  1047. var correction = 0.0;
  1048. var func;
  1049. var denominator;
  1050. var xMultiplier;
  1051. var yMultiplier;
  1052. var zMultiplier;
  1053. var xMultiplier2;
  1054. var yMultiplier2;
  1055. var zMultiplier2;
  1056. var xMultiplier3;
  1057. var yMultiplier3;
  1058. var zMultiplier3;
  1059. do {
  1060. lambda -= correction;
  1061. xMultiplier = 1.0 / (1.0 + lambda * oneOverRadiiSquaredX);
  1062. yMultiplier = 1.0 / (1.0 + lambda * oneOverRadiiSquaredY);
  1063. zMultiplier = 1.0 / (1.0 + lambda * oneOverRadiiSquaredZ);
  1064. xMultiplier2 = xMultiplier * xMultiplier;
  1065. yMultiplier2 = yMultiplier * yMultiplier;
  1066. zMultiplier2 = zMultiplier * zMultiplier;
  1067. xMultiplier3 = xMultiplier2 * xMultiplier;
  1068. yMultiplier3 = yMultiplier2 * yMultiplier;
  1069. zMultiplier3 = zMultiplier2 * zMultiplier;
  1070. func = x2 * xMultiplier2 + y2 * yMultiplier2 + z2 * zMultiplier2 - 1.0;
  1071. // "denominator" here refers to the use of this expression in the velocity and acceleration
  1072. // computations in the sections to follow.
  1073. denominator = x2 * xMultiplier3 * oneOverRadiiSquaredX + y2 * yMultiplier3 * oneOverRadiiSquaredY + z2 * zMultiplier3 * oneOverRadiiSquaredZ;
  1074. var derivative = -2.0 * denominator;
  1075. correction = func / derivative;
  1076. } while (Math.abs(func) > _Math.CesiumMath.EPSILON12);
  1077. if (!when.defined(result)) {
  1078. return new Cartesian3(positionX * xMultiplier, positionY * yMultiplier, positionZ * zMultiplier);
  1079. }
  1080. result.x = positionX * xMultiplier;
  1081. result.y = positionY * yMultiplier;
  1082. result.z = positionZ * zMultiplier;
  1083. return result;
  1084. }
  1085. /**
  1086. * A position defined by longitude, latitude, and height.
  1087. * @alias Cartographic
  1088. * @constructor
  1089. *
  1090. * @param {Number} [longitude=0.0] The longitude, in radians.
  1091. * @param {Number} [latitude=0.0] The latitude, in radians.
  1092. * @param {Number} [height=0.0] The height, in meters, above the ellipsoid.
  1093. *
  1094. * @see Ellipsoid
  1095. */
  1096. function Cartographic(longitude, latitude, height) {
  1097. /**
  1098. * The longitude, in radians.
  1099. * @type {Number}
  1100. * @default 0.0
  1101. */
  1102. this.longitude = when.defaultValue(longitude, 0.0);
  1103. /**
  1104. * The latitude, in radians.
  1105. * @type {Number}
  1106. * @default 0.0
  1107. */
  1108. this.latitude = when.defaultValue(latitude, 0.0);
  1109. /**
  1110. * The height, in meters, above the ellipsoid.
  1111. * @type {Number}
  1112. * @default 0.0
  1113. */
  1114. this.height = when.defaultValue(height, 0.0);
  1115. }
  1116. /**
  1117. * Creates a new Cartographic instance from longitude and latitude
  1118. * specified in radians.
  1119. *
  1120. * @param {Number} longitude The longitude, in radians.
  1121. * @param {Number} latitude The latitude, in radians.
  1122. * @param {Number} [height=0.0] The height, in meters, above the ellipsoid.
  1123. * @param {Cartographic} [result] The object onto which to store the result.
  1124. * @returns {Cartographic} The modified result parameter or a new Cartographic instance if one was not provided.
  1125. */
  1126. Cartographic.fromRadians = function(longitude, latitude, height, result) {
  1127. //>>includeStart('debug', pragmas.debug);
  1128. Check.Check.typeOf.number('longitude', longitude);
  1129. Check.Check.typeOf.number('latitude', latitude);
  1130. //>>includeEnd('debug');
  1131. height = when.defaultValue(height, 0.0);
  1132. if (!when.defined(result)) {
  1133. return new Cartographic(longitude, latitude, height);
  1134. }
  1135. result.longitude = longitude;
  1136. result.latitude = latitude;
  1137. result.height = height;
  1138. return result;
  1139. };
  1140. /**
  1141. * Creates a new Cartographic instance from longitude and latitude
  1142. * specified in degrees. The values in the resulting object will
  1143. * be in radians.
  1144. *
  1145. * @param {Number} longitude The longitude, in degrees.
  1146. * @param {Number} latitude The latitude, in degrees.
  1147. * @param {Number} [height=0.0] The height, in meters, above the ellipsoid.
  1148. * @param {Cartographic} [result] The object onto which to store the result.
  1149. * @returns {Cartographic} The modified result parameter or a new Cartographic instance if one was not provided.
  1150. */
  1151. Cartographic.fromDegrees = function(longitude, latitude, height, result) {
  1152. //>>includeStart('debug', pragmas.debug);
  1153. Check.Check.typeOf.number('longitude', longitude);
  1154. Check.Check.typeOf.number('latitude', latitude);
  1155. //>>includeEnd('debug');
  1156. longitude = _Math.CesiumMath.toRadians(longitude);
  1157. latitude = _Math.CesiumMath.toRadians(latitude);
  1158. return Cartographic.fromRadians(longitude, latitude, height, result);
  1159. };
  1160. var cartesianToCartographicN = new Cartesian3();
  1161. var cartesianToCartographicP = new Cartesian3();
  1162. var cartesianToCartographicH = new Cartesian3();
  1163. var wgs84OneOverRadii = new Cartesian3(1.0 / 6378137.0, 1.0 / 6378137.0, 1.0 / 6356752.3142451793);
  1164. var wgs84OneOverRadiiEx = new Cartesian3(1.0 / 6378137.0, 1.0 / 6378137.0, 1.0 / 6378137.0);
  1165. var wgs84OneOverRadiiSquared = new Cartesian3(1.0 / (6378137.0 * 6378137.0), 1.0 / (6378137.0 * 6378137.0), 1.0 / (6356752.3142451793 * 6356752.3142451793));
  1166. var wgs84OneOverRadiiSquaredEx = new Cartesian3(1.0 / (6378137.0 * 6378137.0), 1.0 / (6378137.0 * 6378137.0), 1.0 / (6378137.0 * 6378137.0));
  1167. var wgs84CenterToleranceSquared = _Math.CesiumMath.EPSILON1;
  1168. /**
  1169. * Creates a new Cartographic instance from a Cartesian position. The values in the
  1170. * resulting object will be in radians.
  1171. *
  1172. * @param {Cartesian3} cartesian The Cartesian position to convert to cartographic representation.
  1173. * @param {Ellipsoid} [ellipsoid=Ellipsoid.WGS84] The ellipsoid on which the position lies.
  1174. * @param {Cartographic} [result] The object onto which to store the result.
  1175. * @returns {Cartographic} The modified result parameter, new Cartographic instance if none was provided, or undefined if the cartesian is at the center of the ellipsoid.
  1176. */
  1177. Cartographic.fromCartesian = function(cartesian, ellipsoid, result) {
  1178. var oneOverRadii = when.defined(ellipsoid) ? ellipsoid.oneOverRadii : wgs84OneOverRadiiEx;
  1179. var oneOverRadiiSquared = when.defined(ellipsoid) ? ellipsoid.oneOverRadiiSquared : wgs84OneOverRadiiSquaredEx;
  1180. var centerToleranceSquared = when.defined(ellipsoid) ? ellipsoid._centerToleranceSquared : wgs84CenterToleranceSquared;
  1181. if(_Math.CesiumMath.equalsEpsilon(_Math.CesiumMath.Radius, 6356752.3142451793, _Math.CesiumMath.EPSILON10)) {
  1182. oneOverRadii = when.defined(ellipsoid) ? ellipsoid.oneOverRadii : wgs84OneOverRadii;
  1183. oneOverRadiiSquared = when.defined(ellipsoid) ? ellipsoid.oneOverRadiiSquared : wgs84OneOverRadiiSquared;
  1184. }
  1185. //`cartesian is required.` is thrown from scaleToGeodeticSurface
  1186. var p = scaleToGeodeticSurface(cartesian, oneOverRadii, oneOverRadiiSquared, centerToleranceSquared, cartesianToCartographicP);
  1187. if (!when.defined(p)) {
  1188. return undefined;
  1189. }
  1190. var n = Cartesian3.multiplyComponents(p, oneOverRadiiSquared, cartesianToCartographicN);
  1191. n = Cartesian3.normalize(n, n);
  1192. var h = Cartesian3.subtract(cartesian, p, cartesianToCartographicH);
  1193. var longitude = Math.atan2(n.y, n.x);
  1194. var latitude = Math.asin(n.z);
  1195. var height = _Math.CesiumMath.sign(Cartesian3.dot(h, cartesian)) * Cartesian3.magnitude(h);
  1196. if (!when.defined(result)) {
  1197. return new Cartographic(longitude, latitude, height);
  1198. }
  1199. result.longitude = longitude;
  1200. result.latitude = latitude;
  1201. result.height = height;
  1202. return result;
  1203. };
  1204. /**
  1205. * Creates a new Cartesian3 instance from a Cartographic input. The values in the inputted
  1206. * object should be in radians.
  1207. *
  1208. * @param {Cartographic} cartographic Input to be converted into a Cartesian3 output.
  1209. * @param {Ellipsoid} [ellipsoid=Ellipsoid.WGS84] The ellipsoid on which the position lies.
  1210. * @param {Cartesian3} [result] The object onto which to store the result.
  1211. * @returns {Cartesian3} The position
  1212. */
  1213. Cartographic.toCartesian = function(cartographic, ellipsoid, result) {
  1214. //>>includeStart('debug', pragmas.debug);
  1215. Check.Check.defined('cartographic', cartographic);
  1216. //>>includeEnd('debug');
  1217. return Cartesian3.fromRadians(cartographic.longitude, cartographic.latitude, cartographic.height, ellipsoid, result);
  1218. };
  1219. /**
  1220. * Computes the distance between two points by global
  1221. *
  1222. * @param {Number} longitudeA The longitude, in degrees.
  1223. * @param {Number} latitudeA The latitude, in degrees.
  1224. * @param {Number} longitudeB The longitude, in degrees.
  1225. * @param {Number} latitudeB The latitude, in degrees.
  1226. */
  1227. Cartographic.sphericalDistance = function(longitudeA, latitudeA, longitudeB, latitudeB) {
  1228. Check.Check.defined('longitudeA', longitudeA);
  1229. Check.Check.defined('longitudeB', longitudeB);
  1230. Check.Check.defined('latitudeA', latitudeA);
  1231. Check.Check.defined('latitudeB', latitudeB);
  1232. if(longitudeA === longitudeB && latitudeA === latitudeB){
  1233. return 0.0;
  1234. }
  1235. var latA = _Math.CesiumMath.toRadians(latitudeA);
  1236. var latB = _Math.CesiumMath.toRadians(latitudeB);
  1237. var lonA = _Math.CesiumMath.toRadians(longitudeA);
  1238. var lonB = _Math.CesiumMath.toRadians(longitudeB);
  1239. var a2 = lonA * lonA + latA * latA;
  1240. var b2 = lonB * lonB + latB * latB;
  1241. var c2 = (lonA - lonB) * (lonA - lonB) + (latA - latB) * (latA - latB);
  1242. var dacos = (a2 + b2 - c2) / (2.0 * Math.sqrt(a2) * Math.sqrt(b2));
  1243. dacos = _Math.CesiumMath.clamp(dacos, -1.0, 1.0);
  1244. return Math.acos(dacos) * _Math.CesiumMath.Radius;
  1245. };
  1246. /**
  1247. * Duplicates a Cartographic instance.
  1248. *
  1249. * @param {Cartographic} cartographic The cartographic to duplicate.
  1250. * @param {Cartographic} [result] The object onto which to store the result.
  1251. * @returns {Cartographic} The modified result parameter or a new Cartographic instance if one was not provided. (Returns undefined if cartographic is undefined)
  1252. */
  1253. Cartographic.clone = function(cartographic, result) {
  1254. if (!when.defined(cartographic)) {
  1255. return undefined;
  1256. }
  1257. if (!when.defined(result)) {
  1258. return new Cartographic(cartographic.longitude, cartographic.latitude, cartographic.height);
  1259. }
  1260. result.longitude = cartographic.longitude;
  1261. result.latitude = cartographic.latitude;
  1262. result.height = cartographic.height;
  1263. return result;
  1264. };
  1265. /**
  1266. * Compares the provided cartographics componentwise and returns
  1267. * <code>true</code> if they are equal, <code>false</code> otherwise.
  1268. *
  1269. * @param {Cartographic} [left] The first cartographic.
  1270. * @param {Cartographic} [right] The second cartographic.
  1271. * @returns {Boolean} <code>true</code> if left and right are equal, <code>false</code> otherwise.
  1272. */
  1273. Cartographic.equals = function(left, right) {
  1274. return (left === right) ||
  1275. ((when.defined(left)) &&
  1276. (when.defined(right)) &&
  1277. (left.longitude === right.longitude) &&
  1278. (left.latitude === right.latitude) &&
  1279. (left.height === right.height));
  1280. };
  1281. /**
  1282. * Compares the provided cartographics componentwise and returns
  1283. * <code>true</code> if they are within the provided epsilon,
  1284. * <code>false</code> otherwise.
  1285. *
  1286. * @param {Cartographic} [left] The first cartographic.
  1287. * @param {Cartographic} [right] The second cartographic.
  1288. * @param {Number} epsilon The epsilon to use for equality testing.
  1289. * @returns {Boolean} <code>true</code> if left and right are within the provided epsilon, <code>false</code> otherwise.
  1290. */
  1291. Cartographic.equalsEpsilon = function(left, right, epsilon) {
  1292. //>>includeStart('debug', pragmas.debug);
  1293. Check.Check.typeOf.number('epsilon', epsilon);
  1294. //>>includeEnd('debug');
  1295. return (left === right) ||
  1296. ((when.defined(left)) &&
  1297. (when.defined(right)) &&
  1298. (Math.abs(left.longitude - right.longitude) <= epsilon) &&
  1299. (Math.abs(left.latitude - right.latitude) <= epsilon) &&
  1300. (Math.abs(left.height - right.height) <= epsilon));
  1301. };
  1302. /**
  1303. * An immutable Cartographic instance initialized to (0.0, 0.0, 0.0).
  1304. *
  1305. * @type {Cartographic}
  1306. * @constant
  1307. */
  1308. Cartographic.ZERO = Object.freeze(new Cartographic(0.0, 0.0, 0.0));
  1309. /**
  1310. * Duplicates this instance.
  1311. *
  1312. * @param {Cartographic} [result] The object onto which to store the result.
  1313. * @returns {Cartographic} The modified result parameter or a new Cartographic instance if one was not provided.
  1314. */
  1315. Cartographic.prototype.clone = function(result) {
  1316. return Cartographic.clone(this, result);
  1317. };
  1318. /**
  1319. * Compares the provided against this cartographic componentwise and returns
  1320. * <code>true</code> if they are equal, <code>false</code> otherwise.
  1321. *
  1322. * @param {Cartographic} [right] The second cartographic.
  1323. * @returns {Boolean} <code>true</code> if left and right are equal, <code>false</code> otherwise.
  1324. */
  1325. Cartographic.prototype.equals = function(right) {
  1326. return Cartographic.equals(this, right);
  1327. };
  1328. /**
  1329. * Compares the provided against this cartographic componentwise and returns
  1330. * <code>true</code> if they are within the provided epsilon,
  1331. * <code>false</code> otherwise.
  1332. *
  1333. * @param {Cartographic} [right] The second cartographic.
  1334. * @param {Number} epsilon The epsilon to use for equality testing.
  1335. * @returns {Boolean} <code>true</code> if left and right are within the provided epsilon, <code>false</code> otherwise.
  1336. */
  1337. Cartographic.prototype.equalsEpsilon = function(right, epsilon) {
  1338. return Cartographic.equalsEpsilon(this, right, epsilon);
  1339. };
  1340. /**
  1341. * Creates a string representing this cartographic in the format '(longitude, latitude, height)'.
  1342. *
  1343. * @returns {String} A string representing the provided cartographic in the format '(longitude, latitude, height)'.
  1344. */
  1345. Cartographic.prototype.toString = function() {
  1346. return '(' + this.longitude + ', ' + this.latitude + ', ' + this.height + ')';
  1347. };
  1348. exports.Cartesian3 = Cartesian3;
  1349. exports.Cartographic = Cartographic;
  1350. exports.scaleToGeodeticSurface = scaleToGeodeticSurface;
  1351. });