@itwin/core-frontend 4.1.0-dev.6 → 4.1.0-dev.62

package/lib/esm/IModelConnection.js

@@ -6,9 +6,9 @@
  * @module IModelConnection
  */
 import { assert, BeEvent, GeoServiceStatus, Id64, Logger, OneAtATimeAction, OpenMode, TransientIdSequence, } from "@itwin/core-bentley";
-import { Cartographic, CodeSpec, DbResult, EcefLocation, ECSqlReader, FontMap, GeoCoordStatus, ImageSourceFormat, IModel, IModelError, IModelReadRpcInterface, IModelStatus, mapToGeoServiceStatus, NoContentError, Placement2d, Placement3d, QueryOptionsBuilder, QueryRowFormat, RpcManager, SnapshotIModelRpcInterface, } from "@itwin/core-common";
+import { Cartographic, CodeSpec, DbResult, EcefLocation, ECSqlReader, FontMap, GeoCoordStatus, ImageSourceFormat, IModel, IModelError, IModelReadRpcInterface, IModelStatus, mapToGeoServiceStatus, NoContentError, Placement2d, Placement3d, QueryOptionsBuilder, QueryRowFormat, RpcManager, SnapshotIModelRpcInterface, ViewStoreRpc, } from "@itwin/core-common";
 import { Point3d, Range3d, Transform } from "@itwin/core-geometry";
-import { FrontendLoggerCategory } from "./FrontendLoggerCategory";
+import { FrontendLoggerCategory } from "./common/FrontendLoggerCategory";
 import { GeoServices } from "./GeoServices";
 import { IModelApp } from "./IModelApp";
 import { IModelRoutingContext } from "./IModelRoutingContext";
@@ -133,7 +133,7 @@ class IModelConnection extends IModel {
         this.selectionSet = new SelectionSet(this);
         this.hilited = new HiliteSet(this);
         this.tiles = new Tiles(this);
-        this.geoServices = new GeoServices(this);
+        this.geoServices = GeoServices.createForIModel(this);
         /* eslint-disable-next-line deprecation/deprecation */
         this.displayedExtents = Range3d.fromJSON(this.projectExtents);
         this.onProjectExtentsChanged.addListener(() => {
@@ -155,6 +155,12 @@ class IModelConnection extends IModel {
         this.subcategories.onIModelConnectionClose();
     }
     /** Allow to execute query and read results along with meta data. The result are streamed.
+     *
+     * See also:
+     * - [ECSQL Overview]($docs/learning/frontend/ExecutingECSQL)
+     * - [Code Examples]($docs/learning/frontend/ECSQLCodeExamples)
+     * - [ECSQL Row Format]($docs/learning/ECSQLRowFormat)
+     *
      * @param params The values to bind to the parameters (if the ECSQL has any).
      * @param config Allow to specify certain flags which control how query is executed.
      * @returns Returns an [ECSqlReader]($common) which helps iterate over the result set and also give access to metadata.
@@ -182,8 +188,8 @@ class IModelConnection extends IModel {
      * [ECSQL row]($docs/learning/ECSQLRowFormat).
      *
      * See also:
-     * - [ECSQL Overview]($docs/learning/backend/ExecutingECSQL)
-     * - [Code Examples]($docs/learning/backend/ECSQLCodeExamples)
+     * - [ECSQL Overview]($docs/learning/frontend/ExecutingECSQL)
+     * - [Code Examples]($docs/learning/frontend/ECSQLCodeExamples)
      *
      * @param ecsql The ECSQL statement to execute
      * @param params The values to bind to the parameters (if the ECSQL has any).
@@ -202,8 +208,8 @@ class IModelConnection extends IModel {
     /** Compute number of rows that would be returned by the ECSQL.
      *
      * See also:
-     * - [ECSQL Overview]($docs/learning/backend/ExecutingECSQL)
-     * - [Code Examples]($docs/learning/backend/ECSQLCodeExamples)
+     * - [ECSQL Overview]($docs/learning/frontend/ExecutingECSQL)
+     * - [Code Examples]($docs/learning/frontend/ECSQLCodeExamples)
      *
      * @param ecsql The ECSQL statement to execute
      * @param params The values to bind to the parameters (if the ECSQL has any).
@@ -223,8 +229,8 @@ class IModelConnection extends IModel {
      * [ECSQL row]($docs/learning/ECSQLRowFormat).
      *
      * See also:
-     * - [ECSQL Overview]($docs/learning/backend/ExecutingECSQL)
-     * - [Code Examples]($docs/learning/backend/ECSQLCodeExamples)
+     * - [ECSQL Overview]($docs/learning/frontend/ExecutingECSQL)
+     * - [Code Examples]($docs/learning/frontend/ECSQLCodeExamples)
      *
      * @param ecsql The ECSQL statement to execute
      * @param token None empty restart token. The previous query with same token would be cancelled. This would cause
@@ -312,8 +318,9 @@ class IModelConnection extends IModel {
     /** Convert a point in this iModel's Spatial coordinates to a [[Cartographic]] using the Geographic location services for this IModelConnection.
      * @param spatial A point in the iModel's spatial coordinates
      * @param result If defined, use this for output
-     * @returns A Cartographic location
+     * @returns A Cartographic location (Horizontal datum depends on iModel's GCS)
      * @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)
@@ -332,19 +339,67 @@ class IModelConnection extends IModel {
     /** Convert a point in this iModel's Spatial coordinates to a [[Cartographic]] using the Geographic location services for this IModelConnection or [[IModel.ecefLocation]].
      * @param spatial A point in the iModel's spatial coordinates
      * @param result If defined, use this for output
-     * @returns A Cartographic location
+     * @returns A Cartographic location (Horizontal datum depends on iModel's GCS)
      * @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 Coordinates 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) {
+        return this.cartographicFromSpatialWithGcs(spatial);
+    }
+    /** 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 Coordinates to be converted from the iModel's spatial coordinate system
+     * @returns The `spatial` coordinates converted to cartographic coordinates (WGS84 horizontal datum), of the same length and order as the `spatial`.
+     * @throws IModelError if [[isGeoLocated]] is false or any point could not be converted.
+     * @see [[cartographicFromSpatial]] to perform conversion using iModel's GCS horizontal datum
+     * @beta
+     */
+    async wgs84CartographicFromSpatial(spatial) {
+        return this.cartographicFromSpatialWithGcs(spatial, "WGS84");
+    }
+    /** @internal */
+    async cartographicFromSpatialWithGcs(spatial, datumOrGCRS) {
+        if (this.noGcsDefined)
+            return spatial.map((p) => this.spatialToCartographicFromEcef(p));
+        if (!this.isGeoLocated)
+            throw new IModelError(GeoServiceStatus.NoGeoLocation, "iModel is not GeoLocated");
+        if (!this.isOpen)
+            throw new IModelError(GeoServiceStatus.NoGeoLocation, "iModel is not open");
+        if (spatial.length === 0)
+            return [];
+        const geoConverter = this.geoServices.getConverter(datumOrGCRS);
+        assert(undefined !== geoConverter);
+        const coordResponse = await geoConverter.getGeoCoordinatesFromIModelCoordinates(spatial);
+        if (coordResponse.geoCoords.length !== spatial.length)
+            throw new IModelError(GeoServiceStatus.NoGeoLocation, "iModel is not GeoLocated");
+        return coordResponse.geoCoords.map((coord) => {
+            switch (coord.s) {
+                case GeoCoordStatus.NoGCSDefined:
+                    throw new IModelError(GeoServiceStatus.NoGeoLocation, "iModel is not GeoLocated");
+                case GeoCoordStatus.Success:
+                    const llh = Point3d.fromJSON(coord.p);
+                    return Cartographic.fromDegrees({ longitude: llh.x, latitude: llh.y, height: llh.z });
+                default:
+                    throw new IModelError(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)
@@ -362,17 +417,59 @@ class IModelConnection extends IModel {
         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));
+        const geoCoords = cartographic.map((p) => Point3d.create(p.longitudeDegrees, p.latitudeDegrees, p.height));
+        return this.toSpatialFromGcs(geoCoords);
+    }
+    /** Convert geographic coordinates into points in this iModel's spatial coordinate system using a [[GeoConverter]] or the iModel's [EcefLocation]($common).
+     * @param geoCoords Coordinates to be converted are in the coordinate system described by the `datumOrGCRS` parameter.  Defaults iModel's spatial coordinate system otherwise.
+     * @param datumOrGCRS Datum name or Geographic CRS object definition to use for the conversion.
+     * @returns The `geographics` coordinates converted to spatial coordinates, of the same length and order as `geographics`.
+     * @throws IModelError if [[isGeoLocated]] is false or any point could not be converted.
+     * @beta
+     */
+    async toSpatialFromGcs(geoCoords, datumOrGCRS) {
+        if (!this.isGeoLocated)
+            throw new IModelError(GeoServiceStatus.NoGeoLocation, "iModel is not GeoLocated");
+        if (!this.isOpen)
+            throw new IModelError(GeoServiceStatus.NoGeoLocation, "iModel is not open");
+        if (geoCoords.length === 0)
+            return [];
+        const geoConverter = this.geoServices.getConverter(datumOrGCRS);
+        assert(undefined !== geoConverter);
+        const coordResponse = await geoConverter.getIModelCoordinatesFromGeoCoordinates(geoCoords);
+        if (coordResponse.iModelCoords.length !== geoCoords.length)
+            throw new IModelError(GeoServiceStatus.NoGeoLocation, "iModel is not GeoLocated");
+        return coordResponse.iModelCoords.map((coord) => {
+            switch (coord.s) {
+                case GeoCoordStatus.NoGCSDefined:
+                    throw new IModelError(GeoServiceStatus.NoGeoLocation, "iModel is not GeoLocated");
+                case GeoCoordStatus.Success:
+                    return Point3d.fromJSON(coord.p);
+                default:
+                    throw new IModelError(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.
@@ -850,6 +947,22 @@ export class SnapshotConnection extends IModelConnection {
         constructor(_iModel) {
             this._iModel = _iModel;
         }
+        get viewStoreWriter() {
+            return this._writeViewStoreProxy ??= new Proxy(this, {
+                get(views, methodName) {
+                    const iModel = views._iModel;
+                    return async (...args) => IModelReadRpcInterface.getClientForRouting(iModel.routingContext.token).callViewStore(iModel.getRpcProps(), ViewStoreRpc.version, true, methodName, ...args);
+                },
+            });
+        }
+        get viewsStoreReader() {
+            return this._readViewStoreProxy ??= new Proxy(this, {
+                get(views, methodName) {
+                    const iModel = views._iModel;
+                    return async (...args) => IModelReadRpcInterface.getClientForRouting(iModel.routingContext.token).callViewStore(iModel.getRpcProps(), ViewStoreRpc.version, false, methodName, ...args);
+                },
+            });
+        }
         /** Query for an array of ViewDefinitionProps
          * @param queryParams Query parameters specifying the views to return. The `limit` and `offset` members should be used to page results.
          * @throws [IModelError]($common) If the generated statement is invalid or would return too many props.
@@ -891,7 +1004,7 @@ export class SnapshotConnection extends IModelConnection {
         }
         /** Query the Id of the default view associated with this iModel. Applications can choose to use this as the default view to which to open a viewport upon startup, or the initial selection
          * within a view selection dialog, or similar purposes.
-         * @returns the ID of the default view, or an invalid ID if no default view is defined.
+         * @returns the Id of the default view, or an invalid ID if no default view is defined.
          */
         async queryDefaultViewId() {
             const iModel = this._iModel;
@@ -899,8 +1012,6 @@ export class SnapshotConnection extends IModelConnection {
         }
         /** Load a [[ViewState]] object from the specified [[ViewDefinition]] id. */
         async load(viewDefinitionId) {
-            if (!Id64.isValidId64(viewDefinitionId))
-                throw new IModelError(IModelStatus.InvalidId, `Invalid view definition Id ${viewDefinitionId}`);
             const options = {
                 displayStyle: {
                     omitScheduleScriptElementIds: !IModelApp.tileAdmin.enableFrontendScheduleScripts,
@@ -925,7 +1036,7 @@ export class SnapshotConnection extends IModelConnection {
          * @param viewId The id of the view of the thumbnail.
          * @returns A Promise of the ThumbnailProps.
          * @throws "No content" error if invalid thumbnail.
-         * @deprecated in 3.x with no replacement; thumbnails are rarely added to the iModel.
+         * @deprecated in 3.x use ViewStore apis
          */
         async getThumbnail(_viewId) {
             // eslint-disable-next-line deprecation/deprecation