refacto(view): rename pickCoordinates to pickTerrainCoordinates

BREAKING CHANGE: View.pickCoordinates has been renamed to View.pickTerrainCoordinates and returns the coordinates in the referenceCrs of the view instead of in the crs of the tiledLayer extent.
iTowns · Mar 15, 2023 · 9c701db · 9c701db
1 parent 15b438c
commit 9c701db
Show file tree

Hide file tree

Showing 2 changed files with 32 additions and 12 deletions.
diff --git a/examples/widgets_minimap.html b/examples/widgets_minimap.html
@@ -109,7 +109,7 @@
             // When double-clicking the minimap, travel to the cursor location.
             const cursorCoordinates = new itowns.Coordinates(minimap.view.referenceCrs);
             minimap.domElement.addEventListener('dblclick', (event) => {
-                minimap.view.pickCoordinates(event, cursorCoordinates);
+                minimap.view.pickTerrainCoordinates(event, cursorCoordinates);
                 view.controls.lookAtCoordinate({ coord: cursorCoordinates });
             });
 

diff --git a/src/Core/View.js b/src/Core/View.js
@@ -960,12 +960,12 @@ class View extends THREE.EventDispatcher {
     }
 
     /**
-     * Returns the world position (view's crs: referenceCrs) under view coordinates.
+     * Returns the world position on the terrain (view's crs: referenceCrs) under view coordinates.
      * This position is computed with depth buffer.
      *
      * @param      {THREE.Vector2}  mouse  position in view coordinates (in pixel), if it's null so it's view's center.
      * @param      {THREE.Vector3}  [target=THREE.Vector3()] target. the result will be copied into this Vector3. If not present a new one will be created.
-     * @return     {THREE.Vector3}  the world position in view's crs: referenceCrs.
+     * @return     {THREE.Vector3}  the world position on the terrain in view's crs: referenceCrs.
      */
 
     getPickingPositionFromDepth(mouse, target = new THREE.Vector3()) {
@@ -1032,18 +1032,19 @@ class View extends THREE.EventDispatcher {
     }
 
     /**
-     * Returns the world {@link Coordinates} at given view coordinates.
+     * Returns the world {@link Coordinates} of the terrain at given view coordinates.
      *
-     * @param   {THREE.Vector2|event}   [mouse]     The view coordinates at which the world coordinates must be
-                                                    * returned. This parameter can also be set to a mouse event from
-                                                    * which the view coordinates will be deducted. If not specified, it
-                                                    * will be defaulted to the view's center coordinates.
-     * @param   {Coordinates}           [target]    The result will be copied into this {@link Coordinates}. If not
-                                                    * specified, a new {@link Coordinates} instance will be created.
+     * @param {THREE.Vector2|event} [mouse] The view coordinates at which the world coordinates must be returned. This
+     * parameter can also be set to a mouse event from which the view coordinates will be deducted. If not specified,
+     * it will be defaulted to the view's center coordinates.
+     * @param {Coordinates} [target] The result will be copied into this {@link Coordinates} in the coordinate reference
+     * system of the given coordinate. If not specified, a new {@link Coordinates} instance will be created (in the
+     * view referenceCrs).
      *
-     * @returns {Coordinates}   The world {@link Coordinates} at the given view coordinates.
+     * @returns {Coordinates}   The world {@link Coordinates} of the terrain at the given view coordinates in the
+     * coordinate reference system of the target or in the view referenceCrs if no target is specified.
      */
-    pickCoordinates(mouse, target = new Coordinates(this.tileLayer.extent.crs)) {
+    pickTerrainCoordinates(mouse, target = new Coordinates(this.referenceCrs)) {
         if (mouse instanceof Event) {
             this.eventToViewCoords(mouse);
         } else if (mouse && mouse.x !== undefined && mouse.y !== undefined) {
@@ -1063,6 +1064,25 @@ class View extends THREE.EventDispatcher {
         return target;
     }
 
+    /**
+     * Returns the world {@link Coordinates} of the terrain at given view coordinates.
+     *
+     * @param   {THREE.Vector2|event}   [mouse]     The view coordinates at which the world coordinates must be
+                                                    * returned. This parameter can also be set to a mouse event from
+                                                    * which the view coordinates will be deducted. If not specified, it
+                                                    * will be defaulted to the view's center coordinates.
+     * @param   {Coordinates}           [target]    The result will be copied into this {@link Coordinates}. If not
+                                                    * specified, a new {@link Coordinates} instance will be created.
+     *
+     * @returns {Coordinates}   The world {@link Coordinates} of the terrain at the given view coordinates.
+     *
+     * @deprecated Use View#pickTerrainCoordinates instead.
+     */
+    pickCoordinates(mouse, target = new Coordinates(this.referenceCrs)) {
+        console.warn('Deprecated, use View#pickTerrainCoordinates instead.');
+        return this.pickTerrainCoordinates(mouse, target);
+    }
+
     /**
      * Resize the viewer.
      *