Dynamic graphics (#1087)

* Generalize ElementGraphicsRequestProps to support non-persistent geometry.

Make element graphics APIs beta and clean them up.

* Default format version to latest.

* category is required; placement omits bounding box.

* 2d vs 3d

* test.

* extract-api

common/api/imodeljs-backend.api.md

@@ -60,6 +60,7 @@ import { ElementAlignedBox3d } from '@bentley/imodeljs-common';
 import { ElementAspectProps } from '@bentley/imodeljs-common';
 import { ElementGeometryRequest } from '@bentley/imodeljs-common';
 import { ElementGeometryUpdate } from '@bentley/imodeljs-common';
+import { ElementGraphicsRequestProps } from '@bentley/imodeljs-common';
 import { ElementLoadProps } from '@bentley/imodeljs-common';
 import { ElementProps } from '@bentley/imodeljs-common';
 import { EntityMetaData } from '@bentley/imodeljs-common';
@@ -2186,6 +2187,9 @@ export abstract class FunctionalType extends TypeDefinitionElement {
     static get className(): string;
 }
 
+// @internal
+export function generateElementGraphics(request: ElementGraphicsRequestProps, iModel: IModelDb): Promise<Uint8Array | undefined>;
+
 // @public
 export class GenericDocument extends Document {
     constructor(props: ElementProps, iModel: IModelDb);
@@ -2530,6 +2534,8 @@ export abstract class IModelDb extends IModel {
     // (undocumented)
     protected _fontMap?: FontMap;
     static forEachMetaData(iModel: IModelDb, classFullName: string, wantSuper: boolean, func: PropertyCallback, includeCustom?: boolean): void;
+    // @beta
+    generateElementGraphics(request: ElementGraphicsRequestProps): Promise<Uint8Array | undefined>;
     getBriefcaseId(): BriefcaseId;
     getGeoCoordinatesFromIModelCoordinates(requestContext: ClientRequestContext, props: string): Promise<GeoCoordinatesResponseProps>;
     // @beta

common/api/imodeljs-common.api.md

@@ -1487,7 +1487,7 @@ export function computeChildTileRanges(tile: TileMetadata, root: TileTreeMetadat
 // @internal
 export function computeTileChordTolerance(tile: TileMetadata, is3d: boolean): number;
 
-// @internal
+// @alpha
 export enum ContentFlags {
     // (undocumented)
     AllowInstancing = 1,
@@ -1935,6 +1935,30 @@ export enum DownloadBriefcaseStatus {
 // @beta
 export type DPoint2dProps = number[];
 
+// @beta
+export interface DynamicGraphicsRequest2dProps extends DynamicGraphicsRequestProps {
+    // (undocumented)
+    readonly placement: Omit<Placement2dProps, "bbox">;
+    // (undocumented)
+    readonly type: "2d";
+}
+
+// @beta
+export interface DynamicGraphicsRequest3dProps extends DynamicGraphicsRequestProps {
+    // (undocumented)
+    readonly placement: Omit<Placement3dProps, "bbox">;
+    // (undocumented)
+    readonly type: "3d";
+}
+
+// @beta
+export interface DynamicGraphicsRequestProps extends GraphicsRequestProps {
+    readonly categoryId: Id64String;
+    readonly elementId?: Id64String;
+    readonly geometry: GeometryStreamProps;
+    readonly modelId?: Id64String;
+}
+
 // @beta
 export const Easing: {
     Linear: {
@@ -2264,18 +2288,8 @@ export interface ElementGeometryUpdate {
     viewIndependent?: boolean;
 }
 
-// @internal
-export interface ElementGraphicsRequestProps {
-    readonly clipToProjectExtents?: boolean;
-    readonly contentFlags?: ContentFlags;
-    readonly elementId: Id64String;
-    readonly formatVersion: number;
-    readonly id: string;
-    readonly location?: TransformProps;
-    readonly omitEdges?: boolean;
-    readonly toleranceLog10: number;
-    readonly treeFlags?: TreeFlags;
-}
+// @beta
+export type ElementGraphicsRequestProps = PersistentGraphicsRequestProps | DynamicGraphicsRequest2dProps | DynamicGraphicsRequest3dProps;
 
 // @alpha
 export interface ElementIdsAndRangesProps {
@@ -3358,6 +3372,21 @@ export class GraphicParams {
     setLineTransparency(transparency: number): void;
 }
 
+// @beta
+export interface GraphicsRequestProps {
+    readonly clipToProjectExtents?: boolean;
+    // @alpha
+    readonly contentFlags?: ContentFlags;
+    // @alpha
+    readonly formatVersion?: number;
+    readonly id: string;
+    readonly location?: TransformProps;
+    readonly omitEdges?: boolean;
+    readonly toleranceLog10: number;
+    // @alpha
+    readonly treeFlags?: TreeFlags;
+}
+
 // @public
 export enum GridOrientationType {
     AuxCoord = 4,
@@ -5119,6 +5148,11 @@ export interface PartReference {
     type: "partReference";
 }
 
+// @beta
+export interface PersistentGraphicsRequestProps extends GraphicsRequestProps {
+    readonly elementId: Id64String;
+}
+
 // @public
 export interface PhysicalElementProps extends GeometricElement3dProps {
     // (undocumented)
@@ -7611,7 +7645,7 @@ export interface TileVersionInfo {
     formatVersion: number;
 }
 
-// @internal
+// @alpha
 export enum TreeFlags {
     // (undocumented)
     EnforceDisplayPriority = 2,

common/api/imodeljs-frontend.api.md

@@ -7280,6 +7280,9 @@ export function queryTerrainElevationOffset(viewport: ScreenViewport, carto: Car
 // @internal
 export function rangeToCartographicArea(view3d: ViewState3d, range: Range3d): GlobalLocationArea | undefined;
 
+// @beta
+export function readElementGraphics(bytes: Uint8Array, iModel: IModelConnection, modelId: Id64String, is3d: boolean): Promise<RenderGraphic | undefined>;
+
 // @internal
 export function readPointCloudTileContent(stream: ByteStream, iModel: IModelConnection, modelId: Id64String, _is3d: boolean, range: ElementAlignedBox3d, system: RenderSystem): RenderGraphic | undefined;
 
@@ -10014,7 +10017,6 @@ export class TileAdmin {
     registerViewport(vp: Viewport): void;
     // @internal (undocumented)
     requestCachedTileContent(tile: IModelTile): Promise<Uint8Array | undefined>;
-    // @internal (undocumented)
     requestElementGraphics(iModel: IModelConnection, requestProps: ElementGraphicsRequestProps): Promise<Uint8Array | undefined>;
     // @internal
     requestTiles(vp: Viewport, tiles: Set<Tile>): void;

common/api/summary/imodeljs-backend.exports.csv

@@ -155,6 +155,7 @@ public;FunctionalModel
 public;FunctionalPartition 
 public;FunctionalSchema 
 public;class FunctionalType 
+internal;generateElementGraphics(request: ElementGraphicsRequestProps, iModel: IModelDb): Promise
 public;GenericDocument 
 public;GenericGraphicalModel3d 
 public;GenericGraphicalType2d 

common/api/summary/imodeljs-common.exports.csv

@@ -89,7 +89,7 @@ internal;compareIModelTileTreeIds(lhs: IModelTileTreeId, rhs: IModelTileTreeId):
 internal;CompositeTileHeader 
 internal;computeChildTileProps(parent: TileMetadata, idProvider: ContentIdProvider, root: TileTreeMetadata):
 internal;computeTileChordTolerance(tile: TileMetadata, is3d: boolean): number
-internal;ContentFlags
+alpha;ContentFlags
 internal;class ContentIdProvider
 public;ContextRealityModelProps
 public;CreateEmptySnapshotIModelProps = CreateIModelProps & CreateSnapshotIModelProps
@@ -123,6 +123,9 @@ public;DisplayStyleSubCategoryProps
 beta;DomainOptions
 internal;DownloadBriefcaseStatus
 beta;DPoint2dProps = number[]
+beta;DynamicGraphicsRequest2dProps 
+beta;DynamicGraphicsRequest3dProps 
+beta;DynamicGraphicsRequestProps 
 beta;Easing:
 beta;EasingFunction = (k: number) => number
 public;EcefLocation 
@@ -144,7 +147,7 @@ alpha;ElementGeometryInfo
 alpha;ElementGeometryOpcode
 alpha;ElementGeometryRequest
 alpha;ElementGeometryUpdate
-internal;ElementGraphicsRequestProps
+beta;ElementGraphicsRequestProps = PersistentGraphicsRequestProps | DynamicGraphicsRequest2dProps | DynamicGraphicsRequest3dProps
 alpha;ElementIdsAndRangesProps
 public;ElementLoadProps
 public;ElementProps 
@@ -224,6 +227,7 @@ internal;GltfV2ChunkTypes
 internal;GltfVersions
 public;Gradient
 public;GraphicParams
+beta;GraphicsRequestProps
 public;GridOrientationType
 public;GroundPlane
 public;GroundPlaneProps
@@ -369,6 +373,7 @@ beta;OverriddenBy
 internal;PackedFeature
 internal;PackedFeatureTable
 public;PartReference
+beta;PersistentGraphicsRequestProps 
 public;PhysicalElementProps 
 public;PhysicalTypeProps 
 public;Placement2d 
@@ -568,7 +573,7 @@ internal;TileTreeContentIds
 internal;TileTreeMetadata
 internal;TileTreeProps
 alpha;TileVersionInfo
-internal;TreeFlags
+alpha;TreeFlags
 beta;Tween
 beta;TweenCallback = (obj: any) => void
 beta;Tweens

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

@@ -398,6 +398,7 @@ beta;QuantityTypeDefinition
 beta;QuantityTypeKey = string
 internal;queryTerrainElevationOffset(viewport: ScreenViewport, carto: Cartographic): Promise
 internal;rangeToCartographicArea(view3d: ViewState3d, range: Range3d): GlobalLocationArea | undefined
+beta;readElementGraphics(bytes: Uint8Array, iModel: IModelConnection, modelId: Id64String, is3d: boolean): Promise
 internal;readPointCloudTileContent(stream: ByteStream, iModel: IModelConnection, modelId: Id64String, _is3d: boolean, range: ElementAlignedBox3d, system: RenderSystem): RenderGraphic | undefined
 internal;RealityModelSource = ViewState | DisplayStyleState
 internal;RealityModelTileClient

common/changes/@bentley/imodeljs-backend/dynamic-graphics_2021-03-31-16-42.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@bentley/imodeljs-backend",
+      "comment": "IModelDb.generateElementGraphics can generate graphics for a non-persistent geometry stream.",
+      "type": "none"
+    }
+  ],
+  "packageName": "@bentley/imodeljs-backend",
+  "email": "22944042+pmconne@users.noreply.github.com"
+}

common/changes/@bentley/imodeljs-common/dynamic-graphics_2021-03-31-16-42.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@bentley/imodeljs-common",
+      "comment": "An ElementGraphicsRequest can supply a non-persistent geometry stream.",
+      "type": "none"
+    }
+  ],
+  "packageName": "@bentley/imodeljs-common",
+  "email": "22944042+pmconne@users.noreply.github.com"
+}

common/changes/@bentley/imodeljs-frontend/dynamic-graphics_2021-03-31-16-42.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@bentley/imodeljs-frontend",
+      "comment": "TileAdmin.requestElementGraphics can obtain graphics for a non-persistent geometry stream.",
+      "type": "none"
+    }
+  ],
+  "packageName": "@bentley/imodeljs-frontend",
+  "email": "22944042+pmconne@users.noreply.github.com"
+}

core/backend/src/ElementGraphics.ts

@@ -0,0 +1,45 @@
+/*---------------------------------------------------------------------------------------------
+* Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+* See LICENSE.md in the project root for license terms and full copyright notice.
+*--------------------------------------------------------------------------------------------*/
+/** @packageDocumentation
+ * @module Tiles
+ */
+
+import { assert, ClientRequestContext, IModelStatus } from "@bentley/bentleyjs-core";
+import { ElementGraphicsRequestProps, IModelError } from "@bentley/imodeljs-common";
+import { ElementGraphicsStatus } from "@bentley/imodeljs-native";
+import { IModelDb } from "./IModelDb";
+
+/** See [[IModelDb.generateElementGraphics]] and IModelTileRpcImpl.requestElementGraphics.
+ * @internal
+ */
+export async function generateElementGraphics(request: ElementGraphicsRequestProps, iModel: IModelDb): Promise<Uint8Array | undefined> {
+  const requestContext = ClientRequestContext.current;
+  const result = await iModel.nativeDb.generateElementGraphics(request);
+
+  requestContext.enter();
+  let error: string | undefined;
+  switch (result.status) {
+    case ElementGraphicsStatus.NoGeometry:
+    case ElementGraphicsStatus.Canceled:
+      return undefined;
+    case ElementGraphicsStatus.Success:
+      return result.content;
+    case ElementGraphicsStatus.InvalidJson:
+      error = "Invalid JSON";
+      break;
+    case ElementGraphicsStatus.UnknownMajorFormatVersion:
+      error = "Unknown major format version";
+      break;
+    case ElementGraphicsStatus.ElementNotFound:
+      error = `Element Id ${request.elementId} not found`;
+      break;
+    case ElementGraphicsStatus.DuplicateRequestId:
+      error = `Duplicate request Id "${request.id}"`;
+      break;
+  }
+
+  assert(undefined !== error);
+  throw new IModelError(IModelStatus.BadRequest, error);
+}

core/backend/src/IModelDb.ts

@@ -18,7 +18,7 @@ import { ChangesType, Lock, LockLevel, LockType } from "@bentley/imodelhub-clien
 import {
   AxisAlignedBox3d, Base64EncodedString, BRepGeometryCreate, BriefcaseIdValue, CategorySelectorProps, Code, CodeSpec, CreateEmptySnapshotIModelProps, CreateEmptyStandaloneIModelProps,
   CreateSnapshotIModelProps, DisplayStyleProps, DomainOptions, EcefLocation, ElementAspectProps, ElementGeometryRequest, ElementGeometryUpdate,
-  ElementLoadProps, ElementProps, EntityMetaData, EntityProps, EntityQueryParams, FilePropertyProps, FontMap, FontMapProps, FontProps,
+  ElementGraphicsRequestProps, ElementLoadProps, ElementProps, EntityMetaData, EntityProps, EntityQueryParams, FilePropertyProps, FontMap, FontMapProps, FontProps,
   GeoCoordinatesResponseProps, GeometryContainmentRequestProps, GeometryContainmentResponseProps, IModel, IModelCoordinatesResponseProps, IModelError,
   IModelNotFoundResponse, IModelProps, IModelRpcProps, IModelTileTreeProps, IModelVersion, LocalBriefcaseProps,
   MassPropertiesRequestProps, MassPropertiesResponseProps, ModelLoadProps, ModelProps, ModelSelectorProps, OpenBriefcaseProps, ProfileOptions,
@@ -46,6 +46,7 @@ import { Relationships } from "./Relationship";
 import { CachedSqliteStatement, SqliteStatement, SqliteStatementCache } from "./SqliteStatement";
 import { TxnManager } from "./TxnManager";
 import { DrawingViewDefinition, SheetViewDefinition, ViewDefinition } from "./ViewDefinition";
+import { generateElementGraphics } from "./ElementGraphics";
 
 const loggerCategory: string = BackendLoggerCategory.IModelDb;
 
@@ -1249,6 +1250,14 @@ export abstract class IModelDb extends IModel {
   public createBRepGeometry(createProps: BRepGeometryCreate): DbResult {
     return this.nativeDb.createBRepGeometry(createProps);
   }
+
+  /** Generate graphics for an element or geometry stream.
+   * @see [readElementGraphics]($frontend) to convert the result to a [RenderGraphic]($frontend) for display.
+   * @beta
+   */
+  public async generateElementGraphics(request: ElementGraphicsRequestProps): Promise<Uint8Array | undefined> {
+    return generateElementGraphics(request, this);
+  }
 }
 
 /** @public */

core/backend/src/imodeljs-backend.ts

@@ -52,6 +52,7 @@ export * from "./AliCloudStorageService";
 export * from "./DevTools";
 export * from "./usage-logging/UsageLoggingUtilities";
 export * from "./LocalhostIpcHost";
+export * from "./ElementGraphics";
 export * from "./IModelDb"; // must be last
 
 /** @docs-package-description
@@ -150,4 +151,7 @@ export * from "./IModelDb"; // must be last
  * @docs-group-description Authentication
  * Classes for working with Authentication.
  */
-
+/**
+ * @docs-group-description Tiles
+ * APIs for working with tile graphics.
+ */