@math.gl/web-mercator 3.5.6 → 3.6.0-alpha.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (91) hide show
  1. package/dist/assert.d.ts +2 -0
  2. package/dist/assert.d.ts.map +1 -0
  3. package/dist/assert.js +8 -0
  4. package/dist/es5/assert.js.map +1 -1
  5. package/dist/es5/fit-bounds.js +40 -50
  6. package/dist/es5/fit-bounds.js.map +1 -1
  7. package/dist/es5/fly-to-viewport.js +82 -98
  8. package/dist/es5/fly-to-viewport.js.map +1 -1
  9. package/dist/es5/get-bounds.js +25 -24
  10. package/dist/es5/get-bounds.js.map +1 -1
  11. package/dist/es5/index.js +23 -25
  12. package/dist/es5/index.js.map +1 -1
  13. package/dist/es5/math-utils.js +5 -11
  14. package/dist/es5/math-utils.js.map +1 -1
  15. package/dist/es5/normalize-viewport-props.js +25 -23
  16. package/dist/es5/normalize-viewport-props.js.map +1 -1
  17. package/dist/es5/web-mercator-utils.js +104 -144
  18. package/dist/es5/web-mercator-utils.js.map +1 -1
  19. package/dist/es5/web-mercator-viewport.js +198 -241
  20. package/dist/es5/web-mercator-viewport.js.map +1 -1
  21. package/dist/esm/assert.js.map +1 -1
  22. package/dist/esm/fit-bounds.js +24 -22
  23. package/dist/esm/fit-bounds.js.map +1 -1
  24. package/dist/esm/fly-to-viewport.js +13 -9
  25. package/dist/esm/fly-to-viewport.js.map +1 -1
  26. package/dist/esm/get-bounds.js.map +1 -1
  27. package/dist/esm/index.js.map +1 -1
  28. package/dist/esm/math-utils.js +3 -3
  29. package/dist/esm/math-utils.js.map +1 -1
  30. package/dist/esm/normalize-viewport-props.js +13 -9
  31. package/dist/esm/normalize-viewport-props.js.map +1 -1
  32. package/dist/esm/web-mercator-utils.js +46 -52
  33. package/dist/esm/web-mercator-utils.js.map +1 -1
  34. package/dist/esm/web-mercator-viewport.js +75 -33
  35. package/dist/esm/web-mercator-viewport.js.map +1 -1
  36. package/dist/fit-bounds.d.ts +49 -0
  37. package/dist/fit-bounds.d.ts.map +1 -0
  38. package/dist/fit-bounds.js +70 -0
  39. package/dist/fly-to-viewport.d.ts +19 -0
  40. package/dist/fly-to-viewport.d.ts.map +1 -0
  41. package/dist/fly-to-viewport.js +87 -0
  42. package/dist/get-bounds.d.ts +3 -0
  43. package/dist/get-bounds.d.ts.map +1 -0
  44. package/dist/get-bounds.js +51 -0
  45. package/dist/index.d.ts +8 -0
  46. package/dist/index.d.ts.map +1 -0
  47. package/dist/index.js +8 -0
  48. package/dist/math-utils.d.ts +6 -0
  49. package/dist/math-utils.d.ts.map +1 -0
  50. package/dist/math-utils.js +23 -0
  51. package/dist/normalize-viewport-props.d.ts +17 -0
  52. package/dist/normalize-viewport-props.d.ts.map +1 -0
  53. package/dist/normalize-viewport-props.js +41 -0
  54. package/dist/{es5/web-mercator-utils.d.ts → web-mercator-utils.d.ts} +77 -94
  55. package/dist/web-mercator-utils.d.ts.map +1 -0
  56. package/dist/web-mercator-utils.js +289 -0
  57. package/dist/web-mercator-viewport.d.ts +183 -0
  58. package/dist/web-mercator-viewport.d.ts.map +1 -0
  59. package/dist/web-mercator-viewport.js +282 -0
  60. package/package.json +3 -3
  61. package/src/{assert.js → assert.ts} +1 -1
  62. package/src/fit-bounds.ts +135 -0
  63. package/src/{fly-to-viewport.js → fly-to-viewport.ts} +33 -10
  64. package/src/{get-bounds.js → get-bounds.ts} +4 -2
  65. package/src/{index.js → index.ts} +0 -0
  66. package/src/{math-utils.js → math-utils.ts} +7 -7
  67. package/src/{normalize-viewport-props.js → normalize-viewport-props.ts} +19 -10
  68. package/src/{web-mercator-utils.js → web-mercator-utils.ts} +181 -72
  69. package/src/web-mercator-viewport.ts +417 -0
  70. package/dist/es5/fit-bounds.d.ts +0 -64
  71. package/dist/es5/fly-to-viewport.d.ts +0 -31
  72. package/dist/es5/get-bounds.d.ts +0 -3
  73. package/dist/es5/index.d.ts +0 -23
  74. package/dist/es5/normalize-viewport-props.d.ts +0 -16
  75. package/dist/es5/web-mercator-viewport.d.ts +0 -187
  76. package/dist/esm/fit-bounds.d.ts +0 -64
  77. package/dist/esm/fly-to-viewport.d.ts +0 -31
  78. package/dist/esm/get-bounds.d.ts +0 -3
  79. package/dist/esm/index.d.ts +0 -23
  80. package/dist/esm/normalize-viewport-props.d.ts +0 -16
  81. package/dist/esm/web-mercator-utils.d.ts +0 -189
  82. package/dist/esm/web-mercator-viewport.d.ts +0 -187
  83. package/src/fit-bounds.d.ts +0 -64
  84. package/src/fit-bounds.js +0 -84
  85. package/src/fly-to-viewport.d.ts +0 -31
  86. package/src/get-bounds.d.ts +0 -3
  87. package/src/index.d.ts +0 -23
  88. package/src/normalize-viewport-props.d.ts +0 -16
  89. package/src/web-mercator-utils.d.ts +0 -189
  90. package/src/web-mercator-viewport.d.ts +0 -187
  91. package/src/web-mercator-viewport.js +0 -262
@@ -10,29 +10,47 @@ const DEFAULT_OPTS = {
10
10
  // screenSpeed and maxDuration are used only if specified
11
11
  };
12
12
 
13
+ export type FlytoTransitionOptions = {
14
+ curve?: number;
15
+ speed?: number;
16
+ screenSpeed?: number;
17
+ maxDuration?: number;
18
+ };
19
+
20
+ export type ViewportProps = {
21
+ longitude: number;
22
+ latitude: number;
23
+ zoom: number;
24
+ };
25
+
13
26
  /**
14
27
  * mapbox-gl-js flyTo : https://www.mapbox.com/mapbox-gl-js/api/#map#flyto.
15
28
  * It implements “Smooth and efficient zooming and panning.” algorithm by
16
29
  * "Jarke J. van Wijk and Wim A.A. Nuij"
17
30
  */
18
- export default function flyToViewport(startProps, endProps, t, opts = {}) {
31
+ export default function flyToViewport(
32
+ startProps: ViewportProps,
33
+ endProps: ViewportProps,
34
+ t: number,
35
+ options?: FlytoTransitionOptions
36
+ ): ViewportProps {
19
37
  // Equations from above paper are referred where needed.
20
38
 
21
- const viewport = {};
22
-
23
39
  const {startZoom, startCenterXY, uDelta, w0, u1, S, rho, rho2, r0} = getFlyToTransitionParams(
24
40
  startProps,
25
41
  endProps,
26
- opts
42
+ options
27
43
  );
28
44
 
29
45
  // If change in center is too small, do linear interpolaiton.
30
46
  if (u1 < EPSILON) {
47
+ const viewport = {};
31
48
  for (const key of VIEWPORT_TRANSITION_PROPS) {
32
49
  const startValue = startProps[key];
33
50
  const endValue = endProps[key];
34
51
  viewport[key] = lerp(startValue, endValue, t);
35
52
  }
53
+ // @ts-expect-error
36
54
  return viewport;
37
55
  }
38
56
 
@@ -48,15 +66,20 @@ export default function flyToViewport(startProps, endProps, t, opts = {}) {
48
66
  vec2.add(newCenterWorld, newCenterWorld, startCenterXY);
49
67
 
50
68
  const newCenter = worldToLngLat(newCenterWorld);
51
- viewport.longitude = newCenter[0];
52
- viewport.latitude = newCenter[1];
53
- viewport.zoom = newZoom;
54
- return viewport;
69
+ return {
70
+ longitude: newCenter[0],
71
+ latitude: newCenter[1],
72
+ zoom: newZoom
73
+ };
55
74
  }
56
75
 
57
76
  // returns transition duration in milliseconds
58
- export function getFlyToDuration(startProps, endProps, opts = {}) {
59
- opts = Object.assign({}, DEFAULT_OPTS, opts);
77
+ export function getFlyToDuration(
78
+ startProps: ViewportProps,
79
+ endProps: ViewportProps,
80
+ options?: FlytoTransitionOptions
81
+ ): number {
82
+ const opts = {...DEFAULT_OPTS, ...options};
60
83
  const {screenSpeed, speed, maxDuration} = opts;
61
84
  const {S, rho} = getFlyToTransitionParams(startProps, endProps, opts);
62
85
  const length = 1000 * S;
@@ -1,6 +1,7 @@
1
1
  import {worldToLngLat} from './web-mercator-utils';
2
2
  import * as vec2 from 'gl-matrix/vec2';
3
3
  import {transformVector} from './math-utils';
4
+ import type WebMercatorViewport from './web-mercator-viewport';
4
5
 
5
6
  const DEGREES_TO_RADIANS = Math.PI / 180;
6
7
 
@@ -9,7 +10,8 @@ const DEGREES_TO_RADIANS = Math.PI / 180;
9
10
  * @param {WebMercatorViewport} viewport
10
11
  * @param {Number} z - elevation in meters
11
12
  */
12
- export default function getBounds(viewport, z = 0) {
13
+ export default function getBounds(viewport: WebMercatorViewport, z: number = 0): number[][] {
14
+ // eslint-disable-next-line @typescript-eslint/unbound-method
13
15
  const {width, height, unproject} = viewport;
14
16
  const unprojectOps = {targetZ: z};
15
17
  const bottomLeft = unproject([0, height], unprojectOps);
@@ -41,7 +43,7 @@ export default function getBounds(viewport, z = 0) {
41
43
  * @param {Number} x - projected x in screen space
42
44
  * @param {Number} targetZ - the elevation of the point in meters
43
45
  */
44
- function unprojectOnFarPlane(viewport, x, targetZ) {
46
+ function unprojectOnFarPlane(viewport: WebMercatorViewport, x: number, targetZ) {
45
47
  const {pixelUnprojectionMatrix} = viewport;
46
48
  const coord0 = transformVector(pixelUnprojectionMatrix, [x, 0, 1, 1]);
47
49
  const coord1 = transformVector(pixelUnprojectionMatrix, [x, viewport.height, 1, 1]);
File without changes
@@ -1,27 +1,27 @@
1
- import * as vec4 from 'gl-matrix/vec4';
1
+ import {transformMat4, scale} from 'gl-matrix/vec4';
2
2
 
3
3
  // Helper, avoids low-precision 32 bit matrices from gl-matrix mat4.create()
4
- export function createMat4() {
4
+ export function createMat4(): number[] {
5
5
  return [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
6
6
  }
7
7
 
8
8
  // Transforms a vec4 with a projection matrix
9
9
  export function transformVector(matrix, vector) {
10
- const result = vec4.transformMat4([], vector, matrix);
11
- vec4.scale(result, result, 1 / result[3]);
10
+ const result = transformMat4([], vector, matrix);
11
+ scale(result, result, 1 / result[3]);
12
12
  return result;
13
13
  }
14
14
 
15
- export function mod(value, divisor) {
15
+ export function mod(value: number, divisor: number): number {
16
16
  const modulus = value % divisor;
17
17
  return modulus < 0 ? divisor + modulus : modulus;
18
18
  }
19
19
 
20
- export function lerp(start, end, step) {
20
+ export function lerp(start: number, end: number, step: number): number {
21
21
  return step * end + (1 - step) * start;
22
22
  }
23
23
 
24
- function ieLog2(x) {
24
+ function ieLog2(x: number): number {
25
25
  return Math.log(x) * Math.LOG2E;
26
26
  }
27
27
  // Handle missing log2 in IE 11
@@ -4,17 +4,26 @@ import {mod, log2} from './math-utils';
4
4
  // defined by mapbox-gl
5
5
  const TILE_SIZE = 512;
6
6
 
7
- // Apply mathematical constraints to viewport props
7
+ /** Description of viewport */
8
+ type ViewportProps = {
9
+ width: number;
10
+ height: number;
11
+ longitude: number;
12
+ latitude: number;
13
+ zoom: number;
14
+ pitch?: number;
15
+ bearing?: number;
16
+ };
17
+
18
+ /**
19
+ * Apply mathematical constraints to viewport props
20
+ * @param props
21
+ */
8
22
  // eslint-disable-next-line complexity
9
- export default function normalizeViewportProps({
10
- width,
11
- height,
12
- longitude,
13
- latitude,
14
- zoom,
15
- pitch = 0,
16
- bearing = 0
17
- }) {
23
+ export default function normalizeViewportProps(props: ViewportProps): ViewportProps {
24
+ const {width, height, pitch = 0} = props;
25
+ let {longitude, latitude, zoom, bearing = 0} = props;
26
+
18
27
  // Normalize degrees
19
28
  if (longitude < -180 || longitude > 180) {
20
29
  longitude = mod(longitude + 180, 360) - 180;
@@ -19,12 +19,40 @@ const EARTH_CIRCUMFERENCE = 40.03e6;
19
19
  // Mapbox default altitude
20
20
  export const DEFAULT_ALTITUDE = 1.5;
21
21
 
22
- /** Util functions **/
23
- export function zoomToScale(zoom) {
22
+ export type DistanceScales = {
23
+ unitsPerMeter: number[];
24
+ metersPerUnit: number[];
25
+ unitsPerMeter2?: number[];
26
+ unitsPerDegree: number[];
27
+ degreesPerUnit: number[];
28
+ unitsPerDegree2?: number[];
29
+ };
30
+
31
+ /**
32
+ * PROJECTION MATRIX PARAMETERS
33
+ *
34
+ * TODO how to document mebers
35
+ * @param fov in radians. fov is variable, depends on pitch and altitude
36
+ * @param aspect width/height
37
+ * @param focalDistance distance at which visual scale factor is 1
38
+ * @param near near clipping plane
39
+ * @param far far clipping plane
40
+ */
41
+ type ProjectionParameters = {
42
+ fov: number;
43
+ aspect: number;
44
+ focalDistance: number;
45
+ near: number;
46
+ far: number;
47
+ };
48
+
49
+ /** Logarithimic zoom to linear scale **/
50
+ export function zoomToScale(zoom: number): number {
24
51
  return Math.pow(2, zoom);
25
52
  }
26
53
 
27
- export function scaleToZoom(scale) {
54
+ /** Linear scale to logarithimic zoom **/
55
+ export function scaleToZoom(scale: number): number {
28
56
  return log2(scale);
29
57
  }
30
58
 
@@ -38,7 +66,8 @@ export function scaleToZoom(scale) {
38
66
  * Specifies a point on the sphere to project onto the map.
39
67
  * @return [x,y] coordinates.
40
68
  */
41
- export function lngLatToWorld([lng, lat]) {
69
+ export function lngLatToWorld(lngLat: number[]): number[] {
70
+ const [lng, lat] = lngLat;
42
71
  assert(Number.isFinite(lng));
43
72
  assert(Number.isFinite(lat) && lat >= -90 && lat <= 90, 'invalid latitude');
44
73
 
@@ -49,16 +78,28 @@ export function lngLatToWorld([lng, lat]) {
49
78
  return [x, y];
50
79
  }
51
80
 
52
- // Unproject world point [x,y] on map onto {lat, lon} on sphere
53
- export function worldToLngLat([x, y]) {
81
+ /**
82
+ * Unproject world point [x,y] on map onto {lat, lon} on sphere
83
+ *
84
+ * @param xy - array with [x,y] members
85
+ * representing point on projected map plane
86
+ * @return - array with [x,y] of point on sphere.
87
+ * Has toArray method if you need a GeoJSON Array.
88
+ * Per cartographic tradition, lat and lon are specified as degrees.
89
+ */
90
+ export function worldToLngLat(xy: number[]): number[] {
91
+ const [x, y] = xy;
54
92
  const lambda2 = (x / TILE_SIZE) * (2 * PI) - PI;
55
93
  const phi2 = 2 * (Math.atan(Math.exp((y / TILE_SIZE) * (2 * PI) - PI)) - PI_4);
56
94
  return [lambda2 * RADIANS_TO_DEGREES, phi2 * RADIANS_TO_DEGREES];
57
95
  }
58
96
 
59
- // Returns the zoom level that gives a 1 meter pixel at a certain latitude
60
- // 1 = C*cos(y)/2^z/TILE_SIZE = C*cos(y)/2^(z+9)
61
- export function getMeterZoom({latitude}) {
97
+ /**
98
+ * Returns the zoom level that gives a 1 meter pixel at a certain latitude
99
+ * 1 = C*cos(y)/2^z/TILE_SIZE = C*cos(y)/2^(z+9)
100
+ */
101
+ export function getMeterZoom(options: {latitude: number}): number {
102
+ const {latitude} = options;
62
103
  assert(Number.isFinite(latitude));
63
104
  const latCosine = Math.cos(latitude * DEGREES_TO_RADIANS);
64
105
  return scaleToZoom(EARTH_CIRCUMFERENCE * latCosine) - 9;
@@ -70,11 +111,14 @@ export function getMeterZoom({latitude}) {
70
111
  * In mercator projection mode, the distance scales vary significantly
71
112
  * with latitude.
72
113
  */
73
-
74
- export function getDistanceScales({latitude, longitude, highPrecision = false}) {
114
+ export function getDistanceScales(options: {
115
+ latitude: number;
116
+ longitude: number;
117
+ highPrecision?: boolean;
118
+ }): DistanceScales {
119
+ const {latitude, longitude, highPrecision = false} = options;
75
120
  assert(Number.isFinite(latitude) && Number.isFinite(longitude));
76
121
 
77
- const result = {};
78
122
  const worldSize = TILE_SIZE;
79
123
  const latCosine = Math.cos(latitude * DEGREES_TO_RADIANS);
80
124
 
@@ -100,11 +144,13 @@ export function getDistanceScales({latitude, longitude, highPrecision = false})
100
144
  *
101
145
  * Y needs to be flipped when converting delta degree/meter to delta pixels
102
146
  */
103
- result.unitsPerMeter = [altUnitsPerMeter, altUnitsPerMeter, altUnitsPerMeter];
104
- result.metersPerUnit = [1 / altUnitsPerMeter, 1 / altUnitsPerMeter, 1 / altUnitsPerMeter];
147
+ const result: DistanceScales = {
148
+ unitsPerMeter: [altUnitsPerMeter, altUnitsPerMeter, altUnitsPerMeter],
149
+ metersPerUnit: [1 / altUnitsPerMeter, 1 / altUnitsPerMeter, 1 / altUnitsPerMeter],
105
150
 
106
- result.unitsPerDegree = [unitsPerDegreeX, unitsPerDegreeY, altUnitsPerMeter];
107
- result.degreesPerUnit = [1 / unitsPerDegreeX, 1 / unitsPerDegreeY, 1 / altUnitsPerMeter];
151
+ unitsPerDegree: [unitsPerDegreeX, unitsPerDegreeY, altUnitsPerMeter],
152
+ degreesPerUnit: [1 / unitsPerDegreeX, 1 / unitsPerDegreeY, 1 / altUnitsPerMeter]
153
+ };
108
154
 
109
155
  /**
110
156
  * Taylor series 2nd order for 1/latCosine
@@ -129,7 +175,7 @@ export function getDistanceScales({latitude, longitude, highPrecision = false})
129
175
  /**
130
176
  * Offset a lng/lat position by meterOffset (northing, easting)
131
177
  */
132
- export function addMetersToLngLat(lngLatZ, xyz) {
178
+ export function addMetersToLngLat(lngLatZ: number[], xyz: number[]): number[] {
133
179
  const [longitude, latitude, z0] = lngLatZ;
134
180
  const [x, y, z] = xyz;
135
181
 
@@ -150,21 +196,32 @@ export function addMetersToLngLat(lngLatZ, xyz) {
150
196
  return Number.isFinite(z0) || Number.isFinite(z) ? [newLngLat[0], newLngLat[1], newZ] : newLngLat;
151
197
  }
152
198
 
153
- // ATTRIBUTION:
154
- // view and projection matrix creation is intentionally kept compatible with
155
- // mapbox-gl's implementation to ensure that seamless interoperation
156
- // with mapbox and react-map-gl. See: https://github.com/mapbox/mapbox-gl-js
157
-
158
- export function getViewMatrix({
199
+ /**
200
+ *
201
+ * view and projection matrix creation is intentionally kept compatible with
202
+ * mapbox-gl's implementation to ensure that seamless interoperation
203
+ * with mapbox and react-map-gl. See: https://github.com/mapbox/mapbox-gl-js
204
+ */
205
+ export function getViewMatrix(options: {
159
206
  // Viewport props
160
- height,
161
- pitch,
162
- bearing,
163
- altitude,
207
+ height: number;
208
+ pitch: number;
209
+ bearing: number;
210
+ altitude: number;
164
211
  // Pre-calculated parameters
165
- scale,
166
- center = null
167
- }) {
212
+ scale: number;
213
+ center: number[];
214
+ }): number[] {
215
+ const {
216
+ // Viewport props
217
+ height,
218
+ pitch,
219
+ bearing,
220
+ altitude,
221
+ // Pre-calculated parameters
222
+ scale,
223
+ center = null
224
+ } = options;
168
225
  // VIEW MATRIX: PROJECTS MERCATOR WORLD COORDINATES
169
226
  // Note that mercator world coordinates typically need to be flipped
170
227
  //
@@ -179,8 +236,8 @@ export function getViewMatrix({
179
236
  mat4.rotateX(vm, vm, -pitch * DEGREES_TO_RADIANS);
180
237
  mat4.rotateZ(vm, vm, bearing * DEGREES_TO_RADIANS);
181
238
 
182
- scale /= height;
183
- mat4.scale(vm, vm, [scale, scale, scale]);
239
+ const relativeScale = scale / height;
240
+ mat4.scale(vm, vm, [relativeScale, relativeScale, relativeScale]);
184
241
 
185
242
  if (center) {
186
243
  mat4.translate(vm, vm, vec3.negate([], center));
@@ -189,17 +246,30 @@ export function getViewMatrix({
189
246
  return vm;
190
247
  }
191
248
 
192
- // PROJECTION MATRIX PARAMETERS
193
- // Variable fov (in radians)
194
- export function getProjectionParameters({
195
- width,
196
- height,
197
- fovy = altitudeToFovy(DEFAULT_ALTITUDE),
198
- altitude,
199
- pitch = 0,
200
- nearZMultiplier = 1,
201
- farZMultiplier = 1
202
- }) {
249
+ /**
250
+ * Calculates mapbox compatible projection matrix from parameters
251
+ *
252
+ * @param options.width Width of "viewport" or window
253
+ * @param options.height Height of "viewport" or window
254
+ * @param options.pitch Camera angle in degrees (0 is straight down)
255
+ * @param options.fovy field of view in degrees
256
+ * @param options.altitude if provided, field of view is calculated using `altitudeToFovy()`
257
+ * @param options.nearZMultiplier control z buffer
258
+ * @param options.farZMultiplier control z buffer
259
+ * @returns project parameters object
260
+ */
261
+ export function getProjectionParameters(options: {
262
+ width: number;
263
+ height: number;
264
+ fovy?: number;
265
+ altitude?: number;
266
+ pitch?: number;
267
+ nearZMultiplier?: number;
268
+ farZMultiplier?: number;
269
+ }): ProjectionParameters {
270
+ const {width, height, altitude, pitch = 0, nearZMultiplier = 1, farZMultiplier = 1} = options;
271
+ let {fovy = altitudeToFovy(DEFAULT_ALTITUDE)} = options;
272
+
203
273
  // For back-compatibility allow field of view to be
204
274
  // derived from altitude
205
275
  if (altitude !== undefined) {
@@ -227,28 +297,33 @@ export function getProjectionParameters({
227
297
  };
228
298
  }
229
299
 
230
- // PROJECTION MATRIX: PROJECTS FROM CAMERA (VIEW) SPACE TO CLIPSPACE
231
- // To match mapbox's z buffer:
232
- // <= 0.28 - nearZMultiplier: 0.1, farZmultiplier: 1
233
- // >= 0.29 - nearZMultiplier: 1 / height, farZMultiplier: 1.01
234
- export function getProjectionMatrix({
235
- width,
236
- height,
237
- pitch,
238
- altitude,
239
- fovy,
240
- nearZMultiplier,
241
- farZMultiplier
242
- }) {
243
- const {fov, aspect, near, far} = getProjectionParameters({
244
- width,
245
- height,
246
- altitude,
247
- fovy,
248
- pitch,
249
- nearZMultiplier,
250
- farZMultiplier
251
- });
300
+ /**
301
+ * CALCULATE PROJECTION MATRIX: PROJECTS FROM CAMERA (VIEW) SPACE TO CLIPSPACE
302
+ *
303
+ * To match mapbox's z buffer:
304
+ * - \<= 0.28: nearZMultiplier: 0.1, farZmultiplier: 1
305
+ * - \>= 0.29: nearZMultiplier: 1 / height, farZMultiplier: 1.01
306
+ *
307
+ * @param options Viewport options
308
+ * @param options.width Width of "viewport" or window
309
+ * @param options.height Height of "viewport" or window
310
+ * @param options.pitch Camera angle in degrees (0 is straight down)
311
+ * @param options.fovy field of view in degrees
312
+ * @param options.altitude if provided, field of view is calculated using `altitudeToFovy()`
313
+ * @param options.nearZMultiplier control z buffer
314
+ * @param options.farZMultiplier control z buffer
315
+ * @returns 4x4 projection matrix
316
+ */
317
+ export function getProjectionMatrix(options: {
318
+ width: number;
319
+ height: number;
320
+ pitch: number;
321
+ fovy?: number;
322
+ altitude?: number;
323
+ nearZMultiplier: number;
324
+ farZMultiplier: number;
325
+ }): number[] {
326
+ const {fov, aspect, near, far} = getProjectionParameters(options);
252
327
 
253
328
  const projectionMatrix = mat4.perspective(
254
329
  [],
@@ -261,17 +336,39 @@ export function getProjectionMatrix({
261
336
  return projectionMatrix;
262
337
  }
263
338
 
264
- // Utility function to calculate the field of view such that
265
- // the focal distance is equal to the ground distance. This
266
- // is how mapbox's z fov is calculated
267
- export function altitudeToFovy(altitude) {
339
+ /**
340
+ *
341
+ * Convert an altitude to field of view such that the
342
+ * focal distance is equal to the altitude
343
+ *
344
+ * @param altitude - altitude of camera in screen units
345
+ * @return fovy field of view in degrees
346
+ */
347
+ export function altitudeToFovy(altitude: number): number {
268
348
  return 2 * Math.atan(0.5 / altitude) * RADIANS_TO_DEGREES;
269
349
  }
270
350
 
271
- export function fovyToAltitude(fovy) {
351
+ /**
352
+ *
353
+ * Convert an field of view such that the
354
+ * focal distance is equal to the altitude
355
+ *
356
+ * @param fovy - field of view in degrees
357
+ * @return altitude altitude of camera in screen units
358
+ */
359
+ export function fovyToAltitude(fovy: number): number {
272
360
  return 0.5 / Math.tan(0.5 * fovy * DEGREES_TO_RADIANS);
273
361
  }
274
362
 
363
+ /**
364
+ * Project flat coordinates to pixels on screen.
365
+ *
366
+ * @param xyz - flat coordinate on 512*512 Mercator Zoom 0 tile
367
+ * @param pixelProjectionMatrix - projection matrix 4x4
368
+ * @return [x, y, depth] pixel coordinate on screen.
369
+ */
370
+ export function worldToPixels(xyz: number[], pixelProjectionMatrix: number[]): number[];
371
+
275
372
  // Project flat coordinates to pixels on screen.
276
373
  export function worldToPixels(xyz, pixelProjectionMatrix) {
277
374
  const [x, y, z = 0] = xyz;
@@ -280,8 +377,20 @@ export function worldToPixels(xyz, pixelProjectionMatrix) {
280
377
  return transformVector(pixelProjectionMatrix, [x, y, z, 1]);
281
378
  }
282
379
 
283
- // Unproject pixels on screen to flat coordinates.
284
- export function pixelsToWorld(xyz, pixelUnprojectionMatrix, targetZ = 0) {
380
+ /**
381
+ * Unproject pixels on screen to flat coordinates.
382
+ *
383
+ * @param xyz - pixel coordinate on screen.
384
+ * @param pixelUnprojectionMatrix - unprojection matrix 4x4
385
+ * @param targetZ - if pixel coordinate does not have a 3rd component (depth),
386
+ * targetZ is used as the elevation plane to unproject onto
387
+ * @return [x, y, Z] flat coordinates on 512*512 Mercator Zoom 0 tile.
388
+ */
389
+ export function pixelsToWorld(
390
+ xyz: number[],
391
+ pixelUnprojectionMatrix: number[],
392
+ targetZ: number = 0
393
+ ): number[] {
285
394
  const [x, y, z] = xyz;
286
395
  assert(Number.isFinite(x) && Number.isFinite(y), 'invalid pixel coordinate');
287
396