@itwin/ecschema-rpcinterface-tests 4.1.0-dev.29 → 4.1.0-dev.30

package/lib/dist/_a8a9.bundled-tests.js.map

@@ -1 +1 @@
-{"version":3,"file":"_a8a9.bundled-tests.js","mappings":";;;;;;;;AAAA","sources":["file:///ignored|D:\\vsts_a\\4\\s\\common\\temp\\node_modules\\.pnpm\\@loaders.gl+worker-utils@3.3.3\\node_modules\\@loaders.gl\\worker-utils\\dist\\esm\\lib\\library-utils|../node/require-utils.node"],"names":[],"sourceRoot":""}
+{"version":3,"file":"_a8a9.bundled-tests.js","mappings":";;;;;;;;AAAA","sources":["file:///ignored|D:\\vsts_a\\7\\s\\common\\temp\\node_modules\\.pnpm\\@loaders.gl+worker-utils@3.3.3\\node_modules\\@loaders.gl\\worker-utils\\dist\\esm\\lib\\library-utils|../node/require-utils.node"],"names":[],"sourceRoot":""}

package/lib/dist/bundled-tests.js

@@ -73748,8 +73748,12 @@ class BackgroundMapGeometry {
     static getCartesianTransitionDistance(iModel) {
         return BackgroundMapGeometry.getCartesianRange(iModel, scratchRange).diagonal().magnitudeXY() * BackgroundMapGeometry._transitionDistanceMultiplier;
     }
-    async dbToCartographicFromGcs(db, result) {
-        return this.cartesianRange.containsPoint(_itwin_core_geometry__WEBPACK_IMPORTED_MODULE_1__.Point3d.createFrom(db)) ? this._iModel.spatialToCartographic(db, result) : this.dbToCartographic(db, result);
+    async dbToCartographicFromGcs(db) {
+        const scratch = new _itwin_core_geometry__WEBPACK_IMPORTED_MODULE_1__.Point3d();
+        const promises = db.map(async (p) => {
+            return this.cartesianRange.containsPoint(_itwin_core_geometry__WEBPACK_IMPORTED_MODULE_1__.Point3d.createFrom(p, scratch)) ? this._iModel.spatialToCartographic(p) : this.dbToCartographic(p);
+        });
+        return Promise.all(promises);
     }
     dbToCartographic(db, result) {
         if (undefined === result)
@@ -73763,17 +73767,24 @@ class BackgroundMapGeometry {
             return _itwin_core_common__WEBPACK_IMPORTED_MODULE_2__.Cartographic.fromEcef(ecef, result);
         }
     }
-    async cartographicToDbFromGcs(cartographic, result) {
+    async cartographicToDbFromGcs(cartographic) {
         let db;
         if (this.globeMode === _itwin_core_common__WEBPACK_IMPORTED_MODULE_2__.GlobeMode.Plane) {
             const fraction = _itwin_core_geometry__WEBPACK_IMPORTED_MODULE_1__.Point2d.create(0, 0);
-            this._mercatorTilingScheme.cartographicToFraction(cartographic.latitude, cartographic.longitude, fraction);
-            db = this._mercatorFractionToDb.multiplyXYZ(fraction.x, fraction.y, cartographic.height, result);
+            db = cartographic.map((p) => {
+                this._mercatorTilingScheme.cartographicToFraction(p.latitude, p.longitude, fraction);
+                return this._mercatorFractionToDb.multiplyXYZ(fraction.x, fraction.y, p.height);
+            });
         }
         else {
-            db = this._ecefToDb.multiplyPoint3d(cartographic.toEcef());
+            db = cartographic.map((p) => this._ecefToDb.multiplyPoint3d(p.toEcef()));
         }
-        return (!this._iModel.noGcsDefined && this.cartesianRange.containsPoint(db)) ? this._iModel.cartographicToSpatialFromGcs(cartographic) : db;
+        if (this._iModel.noGcsDefined)
+            return db;
+        const promises = db.map(async (p, i) => {
+            return this.cartesianRange.containsPoint(p) ? this._iModel.cartographicToSpatialFromGcs(cartographic[i]) : p;
+        });
+        return Promise.all(promises);
     }
     cartographicToDb(cartographic, result) {
         if (this.globeMode === _itwin_core_common__WEBPACK_IMPORTED_MODULE_2__.GlobeMode.Plane) {
@@ -78427,6 +78438,9 @@ function cloneXYAndZ(xyz) {
  * @internal exported strictly for tests.
  */
 class CoordinateConverter {
+    get isIdle() {
+        return "idle" === this._state;
+    }
     toXYAndZ(input, output) {
         if (Array.isArray(input)) {
             output.x = input[0] ?? 0;
@@ -78446,8 +78460,12 @@ class CoordinateConverter {
         this._onCompleted = new _itwin_core_bentley__WEBPACK_IMPORTED_MODULE_0__.BeEvent();
         // Used for creating cache keys (XYAndZ) from XYZProps without having to allocate temporary objects.
         this._scratchXYZ = { x: 0, y: 0, z: 0 };
+        // If true, [[dispatch]] will schedule another dispatch after it receives a response.
+        // This is needed when all the points requested after the most recent dispatch were included in the currently-in-flight request -
+        // _pending will be empty but new callers will be awaiting the results of the in-flight request.
+        this._redispatchOnCompletion = false;
         this._maxPointsPerRequest = Math.max(1, opts.maxPointsPerRequest ?? 300);
-        this._iModel = opts.iModel;
+        this._isIModelClosed = opts.isIModelClosed;
         this._requestPoints = opts.requestPoints;
         this._cache = new _itwin_core_bentley__WEBPACK_IMPORTED_MODULE_0__.Dictionary(compareXYAndZ, cloneXYAndZ);
         this._pending = new _itwin_core_bentley__WEBPACK_IMPORTED_MODULE_0__.SortedArray(compareXYAndZ, false, cloneXYAndZ);
@@ -78455,7 +78473,7 @@ class CoordinateConverter {
     }
     async dispatch() {
         (0,_itwin_core_bentley__WEBPACK_IMPORTED_MODULE_0__.assert)(this._state === "scheduled");
-        if (this._iModel.isClosed || this._pending.isEmpty) {
+        if (this._isIModelClosed() || this._pending.isEmpty) {
             this._state = "idle";
             this._onCompleted.raiseEvent();
             return;
@@ -78474,7 +78492,7 @@ class CoordinateConverter {
         for (let i = 0; i < inflight.length; i += this._maxPointsPerRequest) {
             const requests = inflight.slice(i, i + this._maxPointsPerRequest).extractArray();
             const promise = this._requestPoints(requests).then((results) => {
-                if (this._iModel.isClosed)
+                if (this._isIModelClosed())
                     return;
                 if (results.length !== requests.length)
                     _itwin_core_bentley__WEBPACK_IMPORTED_MODULE_0__.Logger.logError(`${_common_FrontendLoggerCategory__WEBPACK_IMPORTED_MODULE_2__.FrontendLoggerCategory.Package}.geoservices`, `requested conversion of ${requests.length} points, but received ${results.length} points`);
@@ -78492,8 +78510,10 @@ class CoordinateConverter {
         this._state = "idle";
         this._inflight.clear();
         // If any more pending conversions arrived while awaiting this request, schedule another request.
-        if (!this._pending.isEmpty)
+        if (!this._pending.isEmpty || this._redispatchOnCompletion) {
+            this._redispatchOnCompletion = false;
             this.scheduleDispatch(); // eslint-disable-line @typescript-eslint/no-floating-promises
+        }
         // Resolve promises of all callers who were awaiting this request.
         onCompleted.raiseEvent();
     }
@@ -78505,7 +78525,9 @@ class CoordinateConverter {
             const xyz = this.toXYAndZ(point, this._scratchXYZ);
             if (this._cache.get(xyz))
                 ++numInCache;
-            else if (!this._inflight.contains(xyz))
+            else if (this._inflight.contains(xyz))
+                this._redispatchOnCompletion = true;
+            else
                 this._pending.insert(xyz);
         }
         return numInCache;
@@ -78566,25 +78588,19 @@ class CoordinateConverter {
  */
 class GeoConverter {
     /** @internal */
-    constructor(iModel, datumOrGCRS) {
-        const datum = typeof datumOrGCRS === "object" ? JSON.stringify(datumOrGCRS) : datumOrGCRS;
+    constructor(opts) {
+        /** Used for removing this converter from GeoServices' cache after all requests are completed.
+         * @internal
+         */
+        this.onAllRequestsCompleted = new _itwin_core_bentley__WEBPACK_IMPORTED_MODULE_0__.BeEvent();
+        const isIModelClosed = opts.isIModelClosed;
         this._geoToIModel = new CoordinateConverter({
-            iModel,
-            requestPoints: async (geoCoords) => {
-                const request = { source: datum, geoCoords };
-                const rpc = _itwin_core_common__WEBPACK_IMPORTED_MODULE_1__.IModelReadRpcInterface.getClientForRouting(iModel.routingContext.token);
-                const response = await rpc.getIModelCoordinatesFromGeoCoordinates(iModel.getRpcProps(), request);
-                return response.iModelCoords;
-            },
+            isIModelClosed,
+            requestPoints: async (geoCoords) => opts.toIModelCoords({ source: opts.datum, geoCoords }),
         });
         this._iModelToGeo = new CoordinateConverter({
-            iModel,
-            requestPoints: async (iModelCoords) => {
-                const request = { target: datum, iModelCoords };
-                const rpc = _itwin_core_common__WEBPACK_IMPORTED_MODULE_1__.IModelReadRpcInterface.getClientForRouting(iModel.routingContext.token);
-                const response = await rpc.getGeoCoordinatesFromIModelCoordinates(iModel.getRpcProps(), request);
-                return response.geoCoords;
-            },
+            isIModelClosed,
+            requestPoints: async (iModelCoords) => opts.fromIModelCoords({ target: opts.datum, iModelCoords }),
         });
     }
     /** Convert the specified geographic coordinates into iModel coordinates. */
@@ -78600,6 +78616,7 @@ class GeoConverter {
     /** @internal */
     async getIModelCoordinatesFromGeoCoordinates(geoPoints) {
         const result = await this._geoToIModel.convert(geoPoints);
+        this.checkCompletion();
         return {
             iModelCoords: result.points,
             fromCache: result.fromCache,
@@ -78608,11 +78625,16 @@ class GeoConverter {
     /** @internal */
     async getGeoCoordinatesFromIModelCoordinates(iModelPoints) {
         const result = await this._iModelToGeo.convert(iModelPoints);
+        this.checkCompletion();
         return {
             geoCoords: result.points,
             fromCache: result.fromCache,
         };
     }
+    checkCompletion() {
+        if (this._geoToIModel.isIdle && this._iModelToGeo.isIdle)
+            this.onAllRequestsCompleted.raiseEvent();
+    }
     /** @internal */
     getCachedIModelCoordinatesFromGeoCoordinates(geoPoints) {
         return this._geoToIModel.findCached(geoPoints);
@@ -78624,8 +78646,35 @@ class GeoConverter {
  */
 class GeoServices {
     /** @internal */
-    constructor(iModel) {
-        this._iModel = iModel;
+    constructor(options) {
+        /** Each GeoConverter has its own independent request queue and cache of previously-converted points.
+         * Some callers like RealityTileTree obtain a single GeoConverter and reuse it throughout their own lifetime. Therefore they benefit from both batching and caching, and
+         * the cache gets deleted once the RealityTileTree becomes disused.
+         *
+         * Other callers like IModelConnection.spatialToCartographic obtain a new GeoConverter every time they need one, use it to convert a single point(!), and then discard the converter.
+         * This entirely prevents batching - e.g., calling spatialToCartographic 20 times in one frame results in 20 http requests.
+         * To address that, we cache each GeoConverter returned by getConverter until it has converted at least one point and has no further outstanding conversion requests.
+         * In this way, the converter lives for as long as (and no longer than) any caller is awaiting conversion to/from its datum - it and its cache are deleted once it becomes disused.
+         * This makes the coordinate caching generally less useful, but at least bounded - and maximizes batching of requests.
+         */
+        this._cache = new Map();
+        this._options = options;
+    }
+    /** @internal */
+    static createForIModel(iModel) {
+        return new GeoServices({
+            isIModelClosed: () => iModel.isClosed,
+            toIModelCoords: async (request) => {
+                const rpc = _itwin_core_common__WEBPACK_IMPORTED_MODULE_1__.IModelReadRpcInterface.getClientForRouting(iModel.routingContext.token);
+                const response = await rpc.getIModelCoordinatesFromGeoCoordinates(iModel.getRpcProps(), request);
+                return response.iModelCoords;
+            },
+            fromIModelCoords: async (request) => {
+                const rpc = _itwin_core_common__WEBPACK_IMPORTED_MODULE_1__.IModelReadRpcInterface.getClientForRouting(iModel.routingContext.token);
+                const response = await rpc.getGeoCoordinatesFromIModelCoordinates(iModel.getRpcProps(), request);
+                return response.geoCoords;
+            },
+        });
     }
     /** Obtain a converter that can convert between a geographic coordinate system and the iModel's own coordinate system.
      * @param datumOrGCRS The name or JSON representation of the geographic coordinate system datum - for example, "WGS84".
@@ -78633,7 +78682,19 @@ class GeoServices {
      * @note A [[BlankConnection]] has no connection to a backend, so it is never "open"; therefore it always returns `undefined`.
      */
     getConverter(datumOrGCRS) {
-        return this._iModel.isOpen ? new GeoConverter(this._iModel, datumOrGCRS ? datumOrGCRS : "") : undefined;
+        if (this._options.isIModelClosed())
+            return undefined;
+        const datum = (typeof datumOrGCRS === "object" ? JSON.stringify(datumOrGCRS) : datumOrGCRS) ?? "";
+        let converter = this._cache.get(datum);
+        if (!converter) {
+            converter = new GeoConverter({ ...this._options, datum });
+            this._cache.set(datum, converter);
+            converter.onAllRequestsCompleted.addOnce(() => {
+                if (converter === this._cache.get(datum))
+                    this._cache.delete(datum);
+            });
+        }
+        return converter;
     }
 }
 
@@ -80283,7 +80344,7 @@ class IModelConnection extends _itwin_core_common__WEBPACK_IMPORTED_MODULE_1__.I
         this.selectionSet = new _SelectionSet__WEBPACK_IMPORTED_MODULE_8__.SelectionSet(this);
         this.hilited = new _SelectionSet__WEBPACK_IMPORTED_MODULE_8__.HiliteSet(this);
         this.tiles = new _Tiles__WEBPACK_IMPORTED_MODULE_11__.Tiles(this);
-        this.geoServices = new _GeoServices__WEBPACK_IMPORTED_MODULE_4__.GeoServices(this);
+        this.geoServices = _GeoServices__WEBPACK_IMPORTED_MODULE_4__.GeoServices.createForIModel(this);
         /* eslint-disable-next-line deprecation/deprecation */
         this.displayedExtents = _itwin_core_geometry__WEBPACK_IMPORTED_MODULE_2__.Range3d.fromJSON(this.projectExtents);
         this.onProjectExtentsChanged.addListener(() => {
@@ -80464,6 +80525,7 @@ class IModelConnection extends _itwin_core_common__WEBPACK_IMPORTED_MODULE_1__.I
      * @param result If defined, use this for output
      * @returns A Cartographic location
      * @throws IModelError if [[isGeoLocated]] is false or point could not be converted.
+     * @see [[cartographicFromSpatial]] if you have more than one point to convert, or you don't know whether the iModel has a GCS.
      */
     async spatialToCartographicFromGcs(spatial, result) {
         if (!this.isGeoLocated && this.noGcsDefined)
@@ -80484,17 +80546,51 @@ class IModelConnection extends _itwin_core_common__WEBPACK_IMPORTED_MODULE_1__.I
      * @param result If defined, use this for output
      * @returns A Cartographic location
      * @throws IModelError if [[isGeoLocated]] is false or point could not be converted.
-     * @see [[spatialToCartographicFromGcs]]
-     * @see [[spatialToCartographicFromEcef]]
+     * @see [[cartographicFromSpatial]] to convert multiple points at once.
+     * @see [[spatialToCartographicFromEcef]] to synchronously convert points using the iModel's ECEF transform.
      */
     async spatialToCartographic(spatial, result) {
         return (this.noGcsDefined ? this.spatialToCartographicFromEcef(spatial, result) : this.spatialToCartographicFromGcs(spatial, result));
     }
-    /** Convert a [[Cartographic]] to a point in this iModel's Spatial coordinates using the Geographic location services for this IModelConnection.
+    /** Convert points in this iModel's spatial coordinate system to [Cartographic]($common) coordinates using either a [[GeoConverter]] or the iModel's [EcefLocation]($common).
+     * @param spatial Coordiantes to be converted from the iModel's spatial coordinate system
+     * @returns The `spatial` coordinates converted to cartographic coordinates, of the same length and order as the `spatial`.
+     * @throws IModelError if [[isGeoLocated]] is false or any point could not be converted.
+     * @see [[spatialFromCartographic]] to perform the inverse conversion.
+     * @see [[spatialToCartographicFromEcef]] to synchronously convert points using the iModel's ECEF transform.
+     */
+    async cartographicFromSpatial(spatial) {
+        if (this.noGcsDefined)
+            return spatial.map((p) => this.spatialToCartographicFromEcef(p));
+        if (!this.isGeoLocated)
+            throw new _itwin_core_common__WEBPACK_IMPORTED_MODULE_1__.IModelError(_itwin_core_bentley__WEBPACK_IMPORTED_MODULE_0__.GeoServiceStatus.NoGeoLocation, "iModel is not GeoLocated");
+        if (!this.isOpen)
+            throw new _itwin_core_common__WEBPACK_IMPORTED_MODULE_1__.IModelError(_itwin_core_bentley__WEBPACK_IMPORTED_MODULE_0__.GeoServiceStatus.NoGeoLocation, "iModel is not open");
+        if (spatial.length === 0)
+            return [];
+        const geoConverter = this.geoServices.getConverter();
+        (0,_itwin_core_bentley__WEBPACK_IMPORTED_MODULE_0__.assert)(undefined !== geoConverter);
+        const coordResponse = await geoConverter.getGeoCoordinatesFromIModelCoordinates(spatial);
+        if (coordResponse.geoCoords.length !== spatial.length)
+            throw new _itwin_core_common__WEBPACK_IMPORTED_MODULE_1__.IModelError(_itwin_core_bentley__WEBPACK_IMPORTED_MODULE_0__.GeoServiceStatus.NoGeoLocation, "iModel is not GeoLocated");
+        return coordResponse.geoCoords.map((coord) => {
+            switch (coord.s) {
+                case _itwin_core_common__WEBPACK_IMPORTED_MODULE_1__.GeoCoordStatus.NoGCSDefined:
+                    throw new _itwin_core_common__WEBPACK_IMPORTED_MODULE_1__.IModelError(_itwin_core_bentley__WEBPACK_IMPORTED_MODULE_0__.GeoServiceStatus.NoGeoLocation, "iModel is not GeoLocated");
+                case _itwin_core_common__WEBPACK_IMPORTED_MODULE_1__.GeoCoordStatus.Success:
+                    const llh = _itwin_core_geometry__WEBPACK_IMPORTED_MODULE_2__.Point3d.fromJSON(coord.p);
+                    return _itwin_core_common__WEBPACK_IMPORTED_MODULE_1__.Cartographic.fromDegrees({ longitude: llh.x, latitude: llh.y, height: llh.z });
+                default:
+                    throw new _itwin_core_common__WEBPACK_IMPORTED_MODULE_1__.IModelError((0,_itwin_core_common__WEBPACK_IMPORTED_MODULE_1__.mapToGeoServiceStatus)(coord.s), "Error converting spatial to cartographic");
+            }
+        });
+    }
+    /** Convert a [Cartographic]($common) to a point in this iModel's spatial coordinate system using a [[GeoConverter]].
      * @param cartographic A cartographic location
      * @param result If defined, use this for output
      * @returns A point in this iModel's spatial coordinates
      * @throws IModelError if [[isGeoLocated]] is false or cartographic location could not be converted.
+     * @see [[spatialFromCartographic]] to convert multiple points at once, or you don't know whether the iModel has a GCS.
      */
     async cartographicToSpatialFromGcs(cartographic, result) {
         if (!this.isGeoLocated && this.noGcsDefined)
@@ -80512,17 +80608,49 @@ class IModelConnection extends _itwin_core_common__WEBPACK_IMPORTED_MODULE_1__.I
         result.setFromJSON(coordResponse.iModelCoords[0].p);
         return result;
     }
-    /** Convert a [[Cartographic]] to a point in this iModel's Spatial coordinates using the Geographic location services for this IModelConnection or [[IModel.ecefLocation]].
+    /** Convert a [Cartographic]($common) to a point in this iModel's Spatial coordinates using a [[GeoConverter]] or[[IModel.ecefLocation]($common).
      * @param cartographic A cartographic location
      * @param result If defined, use this for output
      * @returns A point in this iModel's spatial coordinates
      * @throws IModelError if [[isGeoLocated]] is false or cartographic location could not be converted.
-     * @see [[cartographicToSpatialFromGcs]]
-     * @see [[cartographicToSpatialFromEcef]]
+     * @see [[spatialFromCartographic]] to convert multiple points at once.
+     * @see [[cartographicToSpatialFromEcef]] to synchronously convert points using the iModel's ECEF transform.
      */
     async cartographicToSpatial(cartographic, result) {
         return (this.noGcsDefined ? this.cartographicToSpatialFromEcef(cartographic, result) : this.cartographicToSpatialFromGcs(cartographic, result));
     }
+    /** Convert [Cartographic]($common) coordinates into points in this iModel's spatial coordinate system using a [[GeoConverter]] or the iModel's [EcefLocation]($common).
+     * @param cartographic Coordinates to be converted to the iModel's spatial coordinate system.
+     * @returns The `cartographic` coordinates converted to spatial coordinates, of the same length and order as `cartographic`.
+     * @throws IModelError if [[isGeoLocated]] is false or any point could not be converted.
+     * @see [[cartographicFromSpatial]] to perform the inverse conversion.
+     */
+    async spatialFromCartographic(cartographic) {
+        if (this.noGcsDefined)
+            return cartographic.map((p) => this.cartographicToSpatialFromEcef(p));
+        if (!this.isGeoLocated)
+            throw new _itwin_core_common__WEBPACK_IMPORTED_MODULE_1__.IModelError(_itwin_core_bentley__WEBPACK_IMPORTED_MODULE_0__.GeoServiceStatus.NoGeoLocation, "iModel is not GeoLocated");
+        if (!this.isOpen)
+            throw new _itwin_core_common__WEBPACK_IMPORTED_MODULE_1__.IModelError(_itwin_core_bentley__WEBPACK_IMPORTED_MODULE_0__.GeoServiceStatus.NoGeoLocation, "iModel is not open");
+        if (cartographic.length === 0)
+            return [];
+        const geoConverter = this.geoServices.getConverter();
+        (0,_itwin_core_bentley__WEBPACK_IMPORTED_MODULE_0__.assert)(undefined !== geoConverter);
+        const geoCoords = cartographic.map((p) => _itwin_core_geometry__WEBPACK_IMPORTED_MODULE_2__.Point3d.create(p.longitudeDegrees, p.latitudeDegrees, p.height));
+        const coordResponse = await geoConverter.getIModelCoordinatesFromGeoCoordinates(geoCoords);
+        if (coordResponse.iModelCoords.length !== cartographic.length)
+            throw new _itwin_core_common__WEBPACK_IMPORTED_MODULE_1__.IModelError(_itwin_core_bentley__WEBPACK_IMPORTED_MODULE_0__.GeoServiceStatus.NoGeoLocation, "iModel is not GeoLocated");
+        return coordResponse.iModelCoords.map((coord) => {
+            switch (coord.s) {
+                case _itwin_core_common__WEBPACK_IMPORTED_MODULE_1__.GeoCoordStatus.NoGCSDefined:
+                    throw new _itwin_core_common__WEBPACK_IMPORTED_MODULE_1__.IModelError(_itwin_core_bentley__WEBPACK_IMPORTED_MODULE_0__.GeoServiceStatus.NoGeoLocation, "iModel is not GeoLocated");
+                case _itwin_core_common__WEBPACK_IMPORTED_MODULE_1__.GeoCoordStatus.Success:
+                    return _itwin_core_geometry__WEBPACK_IMPORTED_MODULE_2__.Point3d.fromJSON(coord.p);
+                default:
+                    throw new _itwin_core_common__WEBPACK_IMPORTED_MODULE_1__.IModelError((0,_itwin_core_common__WEBPACK_IMPORTED_MODULE_1__.mapToGeoServiceStatus)(coord.s), "Error converting cartographic to spatial");
+            }
+        });
+    }
     /** Expand this iModel's [[displayedExtents]] to include the specified range.
      * This is done automatically when reality models are added to a spatial view. In some cases a [[TiledGraphicsProvider]] may wish to expand
      * the extents explicitly to include its geometry.
@@ -87737,9 +87865,10 @@ function areaToEyeHeight(view3d, area, offset = 0) {
  * @internal
  */
 async function areaToEyeHeightFromGcs(view3d, area, offset = 0) {
-    const ne = await view3d.cartographicToRootFromGcs(area.northeast);
-    const sw = await view3d.cartographicToRootFromGcs(area.southwest);
-    return _areaToEyeHeight(view3d, ne, sw, offset);
+    const corners = await view3d.cartographicToRootUsingGcs([area.northeast, area.southwest]);
+    if (!corners)
+        return 0;
+    return _areaToEyeHeight(view3d, corners[0], corners[1], offset);
 }
 /** Converts a root range (often project extents) to a cartographic area.
  * @internal
@@ -89611,25 +89740,55 @@ class ViewState3d extends ViewState {
             this.turnCameraOff();
         return eyePoint.distance(origEyePoint);
     }
-    /** Convert a point in spatial space to a cartographic coordinate. */
+    /** Convert a point in spatial coordinates to a cartographic coordinate. */
     rootToCartographic(root, result) {
         const backgroundMapGeometry = this.displayStyle.getBackgroundMapGeometry();
         return backgroundMapGeometry ? backgroundMapGeometry.dbToCartographic(root, result) : undefined;
     }
-    /** Convert a cartographic coordinate to a point in spatial space. */
+    /** Convert a cartographic coordinate to a point in spatial coordinates. */
     cartographicToRoot(cartographic, result) {
         const backgroundMapGeometry = this.displayStyle.getBackgroundMapGeometry();
         return backgroundMapGeometry ? backgroundMapGeometry.cartographicToDb(cartographic, result) : undefined;
     }
-    /** Convert a point in spatial space to a cartographic coordinate using the GCS reprojection. */
+    /** Convert a point in spatial coordinates to a cartographic coordinate using the GCS reprojection.
+     * @see [[rootToCartographicUsingGcs]] to convert multiple points at once.
+     * @see [[cartographicToRootFromGcs]] for the inverse conversion.
+     */
     async rootToCartographicFromGcs(root, result) {
         const backgroundMapGeometry = this.displayStyle.getBackgroundMapGeometry();
-        return backgroundMapGeometry ? backgroundMapGeometry.dbToCartographicFromGcs(root, result) : undefined;
+        if (!backgroundMapGeometry)
+            return undefined;
+        const carto = (await backgroundMapGeometry.dbToCartographicFromGcs([root]))[0];
+        return carto.clone(result);
     }
-    /** Convert a cartographic coordinate to a point in spatial space using the GCS reprojection. */
+    /** Convert spatial coordinates to cartographic coordinates using the GCS reprojection.
+     * @param root Spatial coordinates to be converted
+     * @returns the converted coordinates of the same length and order as `root`, or `undefined` if the conversion cannot be performed.
+     * @see [[cartographicToRootUsingGcs]] for the inverse conversion.
+     */
+    async rootToCartographicUsingGcs(root) {
+        const bgmap = this.displayStyle.getBackgroundMapGeometry();
+        return bgmap?.dbToCartographicFromGcs(root);
+    }
+    /** Convert a cartographic coordinate to a point in spatial coordinates using the GCS reprojection.
+     * @see [[cartographicToRootUsingGcs]] to convert multiple points at once.
+     * @see [[rootToCartographicFromGcs]] for the inverse conversion.
+     */
     async cartographicToRootFromGcs(cartographic, result) {
         const backgroundMapGeometry = this.displayStyle.getBackgroundMapGeometry();
-        return backgroundMapGeometry ? backgroundMapGeometry.cartographicToDbFromGcs(cartographic, result) : undefined;
+        if (!backgroundMapGeometry)
+            return undefined;
+        const root = (await backgroundMapGeometry.cartographicToDbFromGcs([cartographic]))[0];
+        return root.clone(result);
+    }
+    /** Convert cartographic coordinates to spatial coordinates using the GCS reprojection.
+     * @param cartographic Cartographic coordinates to be converted
+     * @returns the converted coordinates of the same length and order as `cartographic`, or `undefined` if the conversion cannot be performed.
+     * @see [[rootToCartographicUsingGcs]] for the inverse conversion.
+     */
+    async cartographicToRootUsingGcs(cartographic) {
+        const bgmap = this.displayStyle.getBackgroundMapGeometry();
+        return bgmap?.cartographicToDbFromGcs(cartographic);
     }
     setupFromFrustum(frustum, opts) {
         const stat = super.setupFromFrustum(frustum, opts);
@@ -91480,7 +91639,7 @@ class Viewport {
         const worldPoint = hit.hitPoint.clone();
         const backgroundMapGeometry = hit.viewport.displayStyle.getBackgroundMapGeometry();
         if (undefined !== backgroundMapGeometry) {
-            featureInfo.hitPoint = await backgroundMapGeometry.dbToCartographicFromGcs(worldPoint);
+            featureInfo.hitPoint = (await backgroundMapGeometry.dbToCartographicFromGcs([worldPoint]))[0];
         }
         const results = await Promise.all(promises);
         for (const result of results)
@@ -152844,7 +153003,7 @@ class MapTileTreeReference extends _internal__WEBPACK_IMPORTED_MODULE_7__.TileTr
         const worldPoint = hit.hitPoint.clone();
         let cartoGraphic;
         try {
-            cartoGraphic = await backgroundMapGeometry.dbToCartographicFromGcs(worldPoint);
+            cartoGraphic = (await backgroundMapGeometry.dbToCartographicFromGcs([worldPoint]))[0];
         }
         catch {
         }
@@ -284880,7 +285039,7 @@ module.exports = JSON.parse('{"name":"axios","version":"0.21.4","description":"P
 /***/ ((module) => {
 
 "use strict";
-module.exports = JSON.parse('{"name":"@itwin/core-frontend","version":"4.1.0-dev.29","description":"iTwin.js frontend components","main":"lib/cjs/core-frontend.js","module":"lib/esm/core-frontend.js","typings":"lib/cjs/core-frontend","license":"MIT","scripts":{"build":"npm run -s copy:public && npm run -s build:cjs && npm run -s build:esm && npm run -s webpackWorkers && npm run -s copy:workers","build:cjs":"npm run -s copy:js:cjs && tsc 1>&2 --outDir lib/cjs","build:esm":"npm run -s copy:js:esm && tsc 1>&2 --module ES2020 --outDir lib/esm","clean":"rimraf lib .rush/temp/package-deps*.json","copy:public":"cpx \\"./src/public/**/*\\" ./lib/public","copy:js:cjs":"cpx \\"./src/**/*.js\\" ./lib/cjs","copy:js:esm":"cpx \\"./src/**/*.js\\" ./lib/esm","copy:workers":"cpx \\"./lib/workers/webpack/parse-imdl-worker.js\\" ./lib/public/scripts","docs":"betools docs --includes=../../generated-docs/extract --json=../../generated-docs/core/core-frontend/file.json --tsIndexFile=./core-frontend.ts --onlyJson --excludes=webgl/**/*,**/primitives,**/map/*.d.ts,**/tile/*.d.ts,**/*-css.ts","extract-api":"betools extract-api --entry=core-frontend && npm run extract-extension-api","extract-extension-api":"eslint --no-eslintrc -c \\"./node_modules/@itwin/eslint-plugin/dist/configs/extension-exports-config.js\\" \\"./src/**/*.ts\\" 1>&2","lint":"eslint -f visualstudio \\"./src/**/*.ts\\" 1>&2","pseudolocalize":"betools pseudolocalize --englishDir ./src/public/locales/en --out ./public/locales/en-PSEUDO","test":"npm run -s webpackTests && certa -r chrome","cover":"npm -s test","test:debug":"certa -r chrome --debug","webpackTests":"webpack --config ./src/test/utils/webpack.config.js 1>&2 && npm run -s webpackTestWorker","webpackTestWorker":"webpack --config ./src/test/worker/webpack.config.js 1>&2 && cpx \\"./lib/test/test-worker.js\\" ./lib/test","webpackWorkers":"webpack --config ./src/workers/ImdlParser/webpack.config.js 1>&2"},"repository":{"type":"git","url":"https://github.com/iTwin/itwinjs-core.git","directory":"core/frontend"},"keywords":["Bentley","BIM","iModel","digital-twin","iTwin"],"author":{"name":"Bentley Systems, Inc.","url":"http://www.bentley.com"},"peerDependencies":{"@itwin/appui-abstract":"workspace:^4.1.0-dev.29","@itwin/core-bentley":"workspace:^4.1.0-dev.29","@itwin/core-common":"workspace:^4.1.0-dev.29","@itwin/core-geometry":"workspace:^4.1.0-dev.29","@itwin/core-orbitgt":"workspace:^4.1.0-dev.29","@itwin/core-quantity":"workspace:^4.1.0-dev.29"},"//devDependencies":["NOTE: All peerDependencies should also be listed as devDependencies since peerDependencies are not considered by npm install","NOTE: All tools used by scripts in this package must be listed as devDependencies"],"devDependencies":{"@itwin/appui-abstract":"workspace:*","@itwin/build-tools":"workspace:*","@itwin/core-bentley":"workspace:*","@itwin/core-common":"workspace:*","@itwin/core-geometry":"workspace:*","@itwin/core-orbitgt":"workspace:*","@itwin/core-quantity":"workspace:*","@itwin/certa":"workspace:*","@itwin/eslint-plugin":"^4.0.0-dev.33","@types/chai":"4.3.1","@types/chai-as-promised":"^7","@types/mocha":"^8.2.2","@types/node":"^18.11.5","@types/sinon":"^9.0.0","babel-loader":"~8.2.5","babel-plugin-istanbul":"~6.1.1","chai":"^4.1.2","chai-as-promised":"^7","cpx2":"^3.0.0","eslint":"^8.36.0","glob":"^7.1.2","mocha":"^10.0.0","nyc":"^15.1.0","rimraf":"^3.0.2","sinon":"^9.0.2","source-map-loader":"^4.0.0","typescript":"~5.0.2","webpack":"^5.76.0"},"//dependencies":["NOTE: these dependencies should be only for things that DO NOT APPEAR IN THE API","NOTE: core-frontend should remain UI technology agnostic, so no react/angular dependencies are allowed"],"dependencies":{"@itwin/object-storage-azure":"^1.5.0","@itwin/cloud-agnostic-core":"^1.5.0","@itwin/object-storage-core":"^1.5.0","@itwin/core-i18n":"workspace:*","@itwin/core-telemetry":"workspace:*","@itwin/webgl-compatibility":"workspace:*","@loaders.gl/core":"^3.1.6","@loaders.gl/draco":"^3.1.6","fuse.js":"^3.3.0","wms-capabilities":"0.4.0","reflect-metadata":"0.1.13"},"nyc":{"extends":"./node_modules/@itwin/build-tools/.nycrc"},"eslintConfig":{"plugins":["@itwin"],"extends":"plugin:@itwin/itwinjs-recommended","rules":{"@itwin/no-internal-barrel-imports":["error",{"required-barrel-modules":["./src/tile/internal.ts"]}],"@itwin/public-extension-exports":["error",{"releaseTags":["public","preview"],"outputApiFile":false}]},"overrides":[{"files":["*.test.ts","*.test.tsx","**/test/**/*.ts"],"rules":{"@itwin/no-internal-barrel-imports":"off"}}]}}');
+module.exports = JSON.parse('{"name":"@itwin/core-frontend","version":"4.1.0-dev.30","description":"iTwin.js frontend components","main":"lib/cjs/core-frontend.js","module":"lib/esm/core-frontend.js","typings":"lib/cjs/core-frontend","license":"MIT","scripts":{"build":"npm run -s copy:public && npm run -s build:cjs && npm run -s build:esm && npm run -s webpackWorkers && npm run -s copy:workers","build:cjs":"npm run -s copy:js:cjs && tsc 1>&2 --outDir lib/cjs","build:esm":"npm run -s copy:js:esm && tsc 1>&2 --module ES2020 --outDir lib/esm","clean":"rimraf lib .rush/temp/package-deps*.json","copy:public":"cpx \\"./src/public/**/*\\" ./lib/public","copy:js:cjs":"cpx \\"./src/**/*.js\\" ./lib/cjs","copy:js:esm":"cpx \\"./src/**/*.js\\" ./lib/esm","copy:workers":"cpx \\"./lib/workers/webpack/parse-imdl-worker.js\\" ./lib/public/scripts","docs":"betools docs --includes=../../generated-docs/extract --json=../../generated-docs/core/core-frontend/file.json --tsIndexFile=./core-frontend.ts --onlyJson --excludes=webgl/**/*,**/primitives,**/map/*.d.ts,**/tile/*.d.ts,**/*-css.ts","extract-api":"betools extract-api --entry=core-frontend && npm run extract-extension-api","extract-extension-api":"eslint --no-eslintrc -c \\"./node_modules/@itwin/eslint-plugin/dist/configs/extension-exports-config.js\\" \\"./src/**/*.ts\\" 1>&2","lint":"eslint -f visualstudio \\"./src/**/*.ts\\" 1>&2","pseudolocalize":"betools pseudolocalize --englishDir ./src/public/locales/en --out ./public/locales/en-PSEUDO","test":"npm run -s webpackTests && certa -r chrome","cover":"npm -s test","test:debug":"certa -r chrome --debug","webpackTests":"webpack --config ./src/test/utils/webpack.config.js 1>&2 && npm run -s webpackTestWorker","webpackTestWorker":"webpack --config ./src/test/worker/webpack.config.js 1>&2 && cpx \\"./lib/test/test-worker.js\\" ./lib/test","webpackWorkers":"webpack --config ./src/workers/ImdlParser/webpack.config.js 1>&2"},"repository":{"type":"git","url":"https://github.com/iTwin/itwinjs-core.git","directory":"core/frontend"},"keywords":["Bentley","BIM","iModel","digital-twin","iTwin"],"author":{"name":"Bentley Systems, Inc.","url":"http://www.bentley.com"},"peerDependencies":{"@itwin/appui-abstract":"workspace:^4.1.0-dev.30","@itwin/core-bentley":"workspace:^4.1.0-dev.30","@itwin/core-common":"workspace:^4.1.0-dev.30","@itwin/core-geometry":"workspace:^4.1.0-dev.30","@itwin/core-orbitgt":"workspace:^4.1.0-dev.30","@itwin/core-quantity":"workspace:^4.1.0-dev.30"},"//devDependencies":["NOTE: All peerDependencies should also be listed as devDependencies since peerDependencies are not considered by npm install","NOTE: All tools used by scripts in this package must be listed as devDependencies"],"devDependencies":{"@itwin/appui-abstract":"workspace:*","@itwin/build-tools":"workspace:*","@itwin/core-bentley":"workspace:*","@itwin/core-common":"workspace:*","@itwin/core-geometry":"workspace:*","@itwin/core-orbitgt":"workspace:*","@itwin/core-quantity":"workspace:*","@itwin/certa":"workspace:*","@itwin/eslint-plugin":"^4.0.0-dev.33","@types/chai":"4.3.1","@types/chai-as-promised":"^7","@types/mocha":"^8.2.2","@types/node":"^18.11.5","@types/sinon":"^9.0.0","babel-loader":"~8.2.5","babel-plugin-istanbul":"~6.1.1","chai":"^4.1.2","chai-as-promised":"^7","cpx2":"^3.0.0","eslint":"^8.36.0","glob":"^7.1.2","mocha":"^10.0.0","nyc":"^15.1.0","rimraf":"^3.0.2","sinon":"^9.0.2","source-map-loader":"^4.0.0","typescript":"~5.0.2","webpack":"^5.76.0"},"//dependencies":["NOTE: these dependencies should be only for things that DO NOT APPEAR IN THE API","NOTE: core-frontend should remain UI technology agnostic, so no react/angular dependencies are allowed"],"dependencies":{"@itwin/object-storage-azure":"^1.5.0","@itwin/cloud-agnostic-core":"^1.5.0","@itwin/object-storage-core":"^1.5.0","@itwin/core-i18n":"workspace:*","@itwin/core-telemetry":"workspace:*","@itwin/webgl-compatibility":"workspace:*","@loaders.gl/core":"^3.1.6","@loaders.gl/draco":"^3.1.6","fuse.js":"^3.3.0","wms-capabilities":"0.4.0","reflect-metadata":"0.1.13"},"nyc":{"extends":"./node_modules/@itwin/build-tools/.nycrc"},"eslintConfig":{"plugins":["@itwin"],"extends":"plugin:@itwin/itwinjs-recommended","rules":{"@itwin/no-internal-barrel-imports":["error",{"required-barrel-modules":["./src/tile/internal.ts"]}],"@itwin/public-extension-exports":["error",{"releaseTags":["public","preview"],"outputApiFile":false}]},"overrides":[{"files":["*.test.ts","*.test.tsx","**/test/**/*.ts"],"rules":{"@itwin/no-internal-barrel-imports":"off"}}]}}');
 
 /***/ })