Support Google Photorealistic 3D Tiles in iTwin.js

common/api/core-frontend.api.md

@@ -3764,9 +3764,15 @@ export function getCesiumAssetUrl(osmAssetId: number, requestKey: string): strin
 // @public
 export function getCompressedJpegFromCanvas(canvas: HTMLCanvasElement, maxBytes?: number, minCompressionQuality?: number): string | undefined;
 
+// @internal
+export function getCopyrights(vp: ScreenViewport): Map<string, number>;
+
 // @internal (undocumented)
 export function getFrustumPlaneIntersectionDepthRange(frustum: Frustum, plane: Plane3dByOriginAndUnitNormal): Range1d;
 
+// @alpha
+export function getGooglePhotorealistic3DTilesURL(): string;
+
 // @public
 export function getImageSourceFormatForMimeType(mimeType: string): ImageSourceFormat | undefined;
 
@@ -4075,6 +4081,8 @@ export interface GltfReaderArgs {
 
 // @internal
 export interface GltfReaderResult extends TileContent {
+    // (undocumented)
+    copyright?: string;
     // (undocumented)
     range?: AxisAlignedBox3d;
     // (undocumented)
@@ -4095,6 +4103,15 @@ export interface GLTimerResult {
     nanoseconds: number;
 }
 
+// @internal
+export class GoogleMapsDecorator implements Decorator {
+    constructor(showCreditsOnScreen?: boolean);
+    activate(mapType: GoogleMapsMapTypes): Promise<boolean>;
+    decorate: (context: DecorateContext) => void;
+    // (undocumented)
+    readonly logo: LogoDecoration;
+}
+
 // @public
 export type GpuMemoryLimit = "none" | "default" | "aggressive" | "relaxed" | number;
 
@@ -5620,6 +5637,20 @@ export enum LockedStates {
     Y_BM = 2
 }
 
+// @internal
+export class LogoDecoration implements CanvasDecoration {
+    // (undocumented)
+    activate(sprite: Sprite): Promise<boolean>;
+    // (undocumented)
+    decorate(context: DecorateContext): void;
+    drawDecoration(ctx: CanvasRenderingContext2D): void;
+    get isLoaded(): boolean;
+    moveToLowerLeftCorner(context: DecorateContext): boolean;
+    set offset(offset: Point3d | undefined);
+    get offset(): Point3d | undefined;
+    readonly position: Point3d;
+}
+
 // @public
 export class LookAndMoveTool extends ViewManip {
     constructor(vp: ScreenViewport, oneShot?: boolean, isDraggingRequired?: boolean);
@@ -8115,11 +8146,24 @@ export namespace RealityDataSource {
     export function createOrbitGtBlobPropsFromKey(rdSourceKey: RealityDataSourceKey): OrbitGtBlobProps | undefined;
     // @alpha
     export function fromKey(key: RealityDataSourceKey, iTwinId: GuidString | undefined): Promise<RealityDataSource | undefined>;
+    // @alpha
+    export function setBaseUrl(id: string): void;
+}
+
+// @alpha
+export class RealityDataSourceGP3DTProvider implements RealityDataSourceProvider {
+    constructor(options: RealityDataSourceGP3DTProviderOptions);
+    // (undocumented)
+    createRealityDataSource(key: RealityDataSourceKey, iTwinId: GuidString | undefined): Promise<RealityDataSource | undefined>;
+    // (undocumented)
+    decorate(_context: DecorateContext): void;
+    initialize(): Promise<boolean>;
 }
 
 // @alpha
 export interface RealityDataSourceProvider {
     createRealityDataSource(key: RealityDataSourceKey, iTwinId: GuidString | undefined): Promise<RealityDataSource | undefined>;
+    decorate?(_context: DecorateContext): void;
 }
 
 // @alpha
@@ -8217,6 +8261,10 @@ export class RealityTile extends Tile {
     // @internal (undocumented)
     computeVisibilityFactor(args: TileDrawArgs): number;
     // @internal (undocumented)
+    get copyright(): string | undefined;
+    // @internal (undocumented)
+    protected _copyright?: string;
+    // @internal (undocumented)
     disposeContents(): void;
     // @internal (undocumented)
     protected forceSelectRealityTile(): boolean;

common/api/summary/core-frontend.exports.csv

@@ -224,7 +224,9 @@ internal;interface;GetAttachmentViewportArgs
 public;function;getCenteredViewRect
 public;function;getCesiumAssetUrl
 public;function;getCompressedJpegFromCanvas
+internal;function;getCopyrights
 internal;function;getFrustumPlaneIntersectionDepthRange
+alpha;function;getGooglePhotorealistic3DTilesURL
 public;function;getImageSourceFormatForMimeType
 public;function;getImageSourceMimeType
 public;interface;GetPixelDataWorldPointArgs
@@ -241,6 +243,7 @@ internal;interface;GltfReaderArgs
 internal;interface;GltfReaderResult
 beta;interface;GltfTemplate
 internal;interface;GLTimerResult
+internal;class;GoogleMapsDecorator
 public;type;GpuMemoryLimit
 public;interface;GpuMemoryLimits
 public;class;GraphicalEditingScope
@@ -346,6 +349,7 @@ public;enum;LocateFilterStatus
 public;class;LocateOptions
 public;class;LocateResponse
 internal;enum;LockedStates
+internal;class;LogoDecoration
 public;class;LookAndMoveTool
 public;interface;LookAtArgs
 public;interface;LookAtOrthoArgs
@@ -507,6 +511,8 @@ alpha;function;createKeyFromBlobUrl
 alpha;function;createKeyFromOrbitGtBlobProps
 alpha;function;createOrbitGtBlobPropsFromKey
 alpha;function;fromKey
+alpha;function;setBaseUrl
+alpha;class;RealityDataSourceGP3DTProvider
 alpha;interface;RealityDataSourceProvider
 alpha;class;RealityDataSourceProviderRegistry
 public;interface;RealityMeshParams

common/changes/@itwin/core-common/google-3d-tiles_2025-05-29-15-10.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@itwin/core-common",
+      "comment": "",
+      "type": "none"
+    }
+  ],
+  "packageName": "@itwin/core-common"
+}

common/changes/@itwin/core-frontend/google-3d-tiles_2025-05-21-15-03.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@itwin/core-frontend",
+      "comment": "Support Google Photorealistic 3D Tiles.",
+      "type": "none"
+    }
+  ],
+  "packageName": "@itwin/core-frontend"
+}

common/changes/@itwin/map-layers-formats/google-3d-tiles_2025-05-21-21-05.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@itwin/map-layers-formats",
+      "comment": "",
+      "type": "none"
+    }
+  ],
+  "packageName": "@itwin/map-layers-formats"
+}

core/common/src/ContextRealityModel.ts

@@ -28,22 +28,22 @@ export interface OrbitGtBlobProps {
  */
 export enum RealityDataProvider {
   /**
-   * This is the legacy mode where the access to the 3d tiles is harcoded in ContextRealityModelProps.tilesetUrl property.
-   * It was use to support RealityMesh3DTiles, Terrain3DTiles, Cesium3DTiles
-   * You should use other mode when possible
+   * This is the legacy mode where the access to the 3d tiles is hardcoded in ContextRealityModelProps.tilesetUrl property.
+   * It was used to support RealityMesh3DTiles, Terrain3DTiles, Cesium3DTiles
+   * You should use other modes when possible
    * @see [[RealityDataSource.createKeyFromUrl]] that will try to detect provider from an URL
    */
   TilesetUrl = "TilesetUrl",
   /**
-   * This is the legacy mode where the access to the 3d tiles is harcoded in ContextRealityModelProps.OrbitGtBlob property.
-   * It was use to support OrbitPointCloud (OPC) from other server than ContextShare
-   * You should use other mode when possible
+   * This is the legacy mode where the access to the 3d tiles is hardcoded in ContextRealityModelProps.OrbitGtBlob property.
+   * It was used to support OrbitPointCloud (OPC) from other server than ContextShare
+   * You should use other modes when possible
    * @see [[RealityDataSource.createKeyFromOrbitGtBlobProps]] that will try to detect provider from an URL
    */
   OrbitGtBlob = "OrbitGtBlob",
   /**
-   * Will provide access url from realityDataId and iTwinId on contextShare for 3dTile storage format or  OPC storage format
-   * This provider support all type of 3dTile storage fomat and OrbitPointCloud: RealityMesh3DTiles, Terrain3DTiles, Cesium3DTiles, OPC
+   * Will provide access url from realityDataId and iTwinId on contextShare for 3dTile storage format or OPC storage format
+   * This provider supports all types of 3dTile storage format and OrbitPointCloud: RealityMesh3DTiles, Terrain3DTiles, Cesium3DTiles, OPC
    * @see [[RealityDataFormat]].
    */
   ContextShare = "ContextShare",

core/frontend/package.json

@@ -82,7 +82,9 @@
     "vitest": "^3.0.6",
     "vite-multiple-assets": "^1.3.1",
     "vite-plugin-static-copy": "2.2.0",
-    "webpack": "^5.97.1"
+    "webpack": "^5.97.1",
+    "sinon": "^17.0.2",
+    "@types/sinon": "^17.0.2"
   },
   "//dependencies": [
     "NOTE: these dependencies should be only for things that DO NOT APPEAR IN THE API",

core/frontend/src/GoogleMapsDecorator.ts

@@ -0,0 +1,158 @@
+/*---------------------------------------------------------------------------------------------
+* Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+* See LICENSE.md in the project root for license terms and full copyright notice.
+*--------------------------------------------------------------------------------------------*/
+
+import { Point3d } from "@itwin/core-geometry";
+import { CanvasDecoration } from "./render/CanvasDecoration";
+import { DecorateContext } from "./ViewContext";
+import { IModelApp } from "./IModelApp";
+import { Decorator } from "./ViewManager";
+import { IconSprites, Sprite } from "./Sprites";
+import { RealityTile } from "./tile/internal";
+import { ScreenViewport } from "./Viewport";
+
+/** Layer types that can be added to the map.
+ * @internal
+ */
+type GoogleMapsMapTypes =  "roadmap" | "satellite" | "terrain";
+
+/** A simple decorator that shows the logo at a given screen position.
+ * @internal
+ */
+export class LogoDecoration implements CanvasDecoration {
+  private _sprite?: Sprite;
+
+  /** The current position of the logo in view coordinates. */
+  public readonly position = new Point3d();
+
+  private _offset: Point3d | undefined;
+
+  public set offset(offset: Point3d | undefined) {
+    this._offset = offset;
+  }
+
+  /** The logo offset in view coordinates.*/
+  public get offset() {
+    return this._offset;
+  }
+
+  /** Move the logo to the lower left corner of the screen. */
+  public moveToLowerLeftCorner(context: DecorateContext): boolean {
+    if (!this._sprite || !this._sprite.isLoaded)
+      return false;
+
+    this.position.x = this._offset?.x ?? 0;
+    this.position.y = context.viewport.parentDiv.clientHeight - this._sprite.size.y;
+    if (this._offset?.y)
+      this.position.y -= this._offset.y;
+    return true;
+  }
+
+  /* TODO: Add other move methods as needed */
+
+  /** Indicate if the logo is loaded and ready to be drawn. */
+  public get isLoaded() { return this._sprite?.isLoaded ?? false; }
+
+  public async activate(sprite: Sprite): Promise<boolean> {
+    this._sprite = sprite;
+    return new Promise<boolean>((resolve, _reject) => {
+      sprite.loadPromise.then(() => {
+        resolve(true);
+      }).catch(() => {
+        resolve (false);
+      });
+    });
+  }
+
+  /** Draw this sprite onto the supplied canvas.
+   * @see [[CanvasDecoration.drawDecoration]]
+   */
+  public drawDecoration(ctx: CanvasRenderingContext2D): void {
+    if (this.isLoaded) {
+      // Draw image with an origin at the top left corner
+      ctx.drawImage(this._sprite!.image!, 0, 0);
+    }
+  }
+
+  public decorate(context: DecorateContext) {
+    context.addCanvasDecoration(this);
+  }
+}
+
+/** A decorator that adds the Google Maps logo to the lower left corner of the screen.
+ * @internal
+ */
+export class GoogleMapsDecorator implements Decorator {
+  public readonly logo = new LogoDecoration();
+  private _showCreditsOnScreen?: boolean;
+
+  /** Create a new GoogleMapsDecorator.
+   * @param showCreditsOnScreen If true, the data attributions/copyrights from the Google Photorealistic 3D Tiles will be displayed on screen. The Google Maps logo will always be displayed.
+   */
+  constructor(showCreditsOnScreen?: boolean) {
+    this._showCreditsOnScreen = showCreditsOnScreen;
+  }
+
+  /** Activate the logo based on the given map type. */
+  public async activate(mapType: GoogleMapsMapTypes): Promise<boolean> {
+    // Pick the logo that is the most visible on the background map
+    const imageName = mapType === "roadmap" ?
+    "google_on_white" :
+    "google_on_non_white";
+
+    // We need to move the logo right after the 'i.js' button
+    this.logo.offset = new Point3d(45, 10);
+
+    return this.logo.activate(IconSprites.getSpriteFromUrl(`${IModelApp.publicPath}images/${imageName}.png`));
+  };
+
+  /** Decorate implementation */
+  public decorate = (context: DecorateContext) => {
+    if (!this.logo.isLoaded)
+      return;
+    this.logo.moveToLowerLeftCorner(context);
+    this.logo.decorate(context);
+
+    if (!this._showCreditsOnScreen)
+      return;
+
+    // Get data attribution (copyright) text
+    const copyrightMap = getCopyrights(context.viewport);
+    // Order by most occurances to least
+    // See https://developers.google.com/maps/documentation/tile/create-renderer#display-attributions
+    const sortedCopyrights = [...copyrightMap.entries()].sort((a, b) => b[1] - a[1]);
+    const copyrightText = sortedCopyrights.map(([key]) => ` • ${key}`).join("");
+
+    // Create and add element, offset to leave space for i.js and Google logos
+    const elem = document.createElement("div");
+    elem.innerHTML = copyrightText;
+    elem.style.color = "white";
+    elem.style.fontSize = "10px";
+    elem.style.textWrap = "wrap";
+    elem.style.position = "absolute";
+    elem.style.bottom = "10px";
+    elem.style.left = "107px";
+
+    context.addHtmlDecoration(elem);
+  };
+}
+
+/** Get copyrights from tiles currently in the viewport.
+ * @internal
+ */
+export function getCopyrights(vp: ScreenViewport): Map<string, number> {
+  const tiles = IModelApp.tileAdmin.getTilesForUser(vp)?.selected;
+  const copyrightMap = new Map<string, number>();
+  if (tiles) {
+    for (const tile of tiles as Set<RealityTile>) {
+      if (tile.copyright) {
+        for (const copyright of tile.copyright?.split(";")) {
+          const currentCount = copyrightMap.get(copyright);
+          copyrightMap.set(copyright, currentCount ? currentCount + 1 : 1);
+        }
+      }
+    }
+  }
+  return copyrightMap;
+}