@itwin/frontend-devtools 3.0.0-dev.72

package/lib/tools/EmphasizeElementsTool.js

@@ -0,0 +1,155 @@
+"use strict";
+/*---------------------------------------------------------------------------------------------
+* Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+* See LICENSE.md in the project root for license terms and full copyright notice.
+*--------------------------------------------------------------------------------------------*/
+/** @packageDocumentation
+ * @module Tools
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EmphasizeVisibleElementsTool = exports.ClearEmphasizedElementsTool = exports.ClearIsolatedElementsTool = exports.IsolateSelectedElementsTool = exports.EmphasizeSelectedElementsTool = exports.EmphasizeElementsTool = void 0;
+const core_bentley_1 = require("@itwin/core-bentley");
+const core_common_1 = require("@itwin/core-common");
+const core_frontend_1 = require("@itwin/core-frontend");
+const parseArgs_1 = require("./parseArgs");
+/** Applies the `EmphasizeElements` API in some way to the selected Viewport.
+ * @beta
+ */
+class EmphasizeElementsTool extends core_frontend_1.Tool {
+    get _wantCreate() { return true; }
+    get _wantClear() { return false; }
+    async run(_args) {
+        const vp = core_frontend_1.IModelApp.viewManager.selectedView;
+        if (undefined === vp)
+            return true;
+        if (this._wantClear)
+            core_frontend_1.EmphasizeElements.clear(vp);
+        const emph = this._wantCreate ? core_frontend_1.EmphasizeElements.getOrCreate(vp) : core_frontend_1.EmphasizeElements.get(vp);
+        if (undefined !== emph)
+            this.execute(emph, vp);
+        return true;
+    }
+}
+exports.EmphasizeElementsTool = EmphasizeElementsTool;
+/** If any elements are selected, emphasize them all by overriding their color to be orange; and de-emphasize all other elements by drawing them transparent grey.
+ * @beta
+ */
+class EmphasizeSelectedElementsTool extends EmphasizeElementsTool {
+    constructor() {
+        super(...arguments);
+        this._type = 0 /* None */;
+    }
+    static get minArgs() { return 0; }
+    static get maxArgs() { return 1; }
+    execute(emph, vp) {
+        if (0 /* None */ === (this._type & 1 /* Color */) || emph.overrideSelectedElements(vp, core_common_1.ColorDef.white, undefined, true, false)) {
+            emph.wantEmphasis = 0 /* None */ !== (this._type & 2 /* Emphasis */);
+            if (emph.emphasizeSelectedElements(vp, undefined, true)) {
+                vp.isFadeOutActive = true;
+                return;
+            }
+        }
+        // Empty selection set - clear any previous overrides.
+        core_frontend_1.EmphasizeElements.clear(vp);
+        emph.wantEmphasis = false;
+        vp.isFadeOutActive = false;
+    }
+    async parseAndRun(...args) {
+        if (1 === args.length) {
+            switch (args[0].toLowerCase()[0]) {
+                case "n":
+                    break;
+                case "c":
+                    this._type = 1 /* Color */;
+                    break;
+                case "e":
+                    this._type = 2 /* Emphasis */;
+                    break;
+                case "b":
+                    this._type = 3 /* Both */;
+                    break;
+            }
+        }
+        return this.run(args);
+    }
+}
+exports.EmphasizeSelectedElementsTool = EmphasizeSelectedElementsTool;
+EmphasizeSelectedElementsTool.toolId = "EmphasizeSelectedElements";
+/** Isolate all selected elements so that *only* those elements will be drawn.
+ * @beta
+ */
+class IsolateSelectedElementsTool extends EmphasizeElementsTool {
+    execute(emph, vp) {
+        emph.isolateSelectedElements(vp, true, true);
+    }
+}
+exports.IsolateSelectedElementsTool = IsolateSelectedElementsTool;
+IsolateSelectedElementsTool.toolId = "IsolateSelectedElements";
+/** Clear the set of isolated elements.
+ * @beta
+ */
+class ClearIsolatedElementsTool extends EmphasizeElementsTool {
+    get _wantCreate() { return false; }
+    execute(emph, vp) {
+        emph.clearIsolatedElements(vp);
+    }
+}
+exports.ClearIsolatedElementsTool = ClearIsolatedElementsTool;
+ClearIsolatedElementsTool.toolId = "ClearIsolatedElements";
+/** Reset [EmphasizeElements]($frontend) for the active [Viewport]($frontend).
+ * @beta
+ */
+class ClearEmphasizedElementsTool extends EmphasizeElementsTool {
+    get _wantCreate() { return false; }
+    get _wantClear() { return true; }
+    execute(emph, vp) {
+        emph.clearEmphasizedElements(vp);
+        vp.isFadeOutActive = false;
+    }
+}
+exports.ClearEmphasizedElementsTool = ClearEmphasizedElementsTool;
+ClearEmphasizedElementsTool.toolId = "ClearEmphasizedElements";
+/** Emphasize the set of elements currently visible in the view based on [Viewport.queryVisibleFeatures]($frontend).
+ * @beta
+ */
+class EmphasizeVisibleElementsTool extends EmphasizeElementsTool {
+    constructor() {
+        super(...arguments);
+        this._options = { source: "screen" };
+    }
+    static get minArgs() { return 1; }
+    static get maxArgs() { return 2; }
+    get _wantClear() { return true; }
+    async parseAndRun(...input) {
+        const args = (0, parseArgs_1.parseArgs)(input);
+        const includeNonLocatable = args.getBoolean("n");
+        let source;
+        switch (input[0].toLowerCase()) {
+            case "screen":
+                source = "screen";
+                break;
+            case "tiles":
+                source = "tiles";
+                break;
+            default:
+                return false;
+        }
+        this._options = { source, includeNonLocatable };
+        return this.run(input);
+    }
+    execute(emph, vp) {
+        const elementIds = new Set();
+        vp.queryVisibleFeatures(this._options, (features) => {
+            for (const feature of features) {
+                if (feature.iModel === vp.iModel && core_bentley_1.Id64.isValid(feature.elementId))
+                    elementIds.add(feature.elementId);
+            }
+        });
+        emph.wantEmphasis = true;
+        if (emph.emphasizeElements(elementIds, vp))
+            vp.isFadeOutActive = true;
+    }
+}
+exports.EmphasizeVisibleElementsTool = EmphasizeVisibleElementsTool;
+EmphasizeVisibleElementsTool.toolId = "EmphasizeVisibleElements";
+//# sourceMappingURL=EmphasizeElementsTool.js.map

package/lib/tools/EmphasizeElementsTool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EmphasizeElementsTool.js","sourceRoot":"","sources":["../../src/tools/EmphasizeElementsTool.ts"],"names":[],"mappings":"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","sourcesContent":["/*---------------------------------------------------------------------------------------------\r\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\r\n* See LICENSE.md in the project root for license terms and full copyright notice.\r\n*--------------------------------------------------------------------------------------------*/\r\n/** @packageDocumentation\r\n * @module Tools\r\n */\r\n\r\nimport { Id64 } from \"@itwin/core-bentley\";\r\nimport { ColorDef } from \"@itwin/core-common\";\r\nimport { EmphasizeElements, IModelApp, QueryVisibleFeaturesOptions, ScreenViewport, Tool } from \"@itwin/core-frontend\";\r\nimport { parseArgs } from \"./parseArgs\";\r\n\r\n/** Applies the `EmphasizeElements` API in some way to the selected Viewport.\r\n * @beta\r\n */\r\nexport abstract class EmphasizeElementsTool extends Tool {\r\n  protected get _wantCreate(): boolean { return true; }\r\n  protected get _wantClear(): boolean { return false; }\r\n  protected abstract execute(emph: EmphasizeElements, vp: ScreenViewport): void;\r\n\r\n  public override async run(_args: any[]): Promise<boolean> {\r\n    const vp = IModelApp.viewManager.selectedView;\r\n    if (undefined === vp)\r\n      return true;\r\n\r\n    if (this._wantClear)\r\n      EmphasizeElements.clear(vp);\r\n\r\n    const emph = this._wantCreate ? EmphasizeElements.getOrCreate(vp) : EmphasizeElements.get(vp);\r\n    if (undefined !== emph)\r\n      this.execute(emph, vp);\r\n\r\n    return true;\r\n  }\r\n}\r\n\r\nconst enum OverrideType { // eslint-disable-line no-restricted-syntax\r\n  None = 0,\r\n  Color = 1 << 0,\r\n  Emphasis = 1 << 1,\r\n  Both = Color | Emphasis,\r\n}\r\n\r\n/** If any elements are selected, emphasize them all by overriding their color to be orange; and de-emphasize all other elements by drawing them transparent grey.\r\n * @beta\r\n */\r\nexport class EmphasizeSelectedElementsTool extends EmphasizeElementsTool {\r\n  public static override toolId = \"EmphasizeSelectedElements\";\r\n  public static override get minArgs() { return 0; }\r\n  public static override get maxArgs() { return 1; }\r\n  private _type = OverrideType.None;\r\n\r\n  public execute(emph: EmphasizeElements, vp: ScreenViewport): void {\r\n    if (OverrideType.None === (this._type & OverrideType.Color) || emph.overrideSelectedElements(vp, ColorDef.white, undefined, true, false)) {\r\n      emph.wantEmphasis = OverrideType.None !== (this._type & OverrideType.Emphasis);\r\n      if (emph.emphasizeSelectedElements(vp, undefined, true)) {\r\n        vp.isFadeOutActive = true;\r\n        return;\r\n      }\r\n    }\r\n\r\n    // Empty selection set - clear any previous overrides.\r\n    EmphasizeElements.clear(vp);\r\n    emph.wantEmphasis = false;\r\n    vp.isFadeOutActive = false;\r\n  }\r\n\r\n  public override async parseAndRun(...args: string[]): Promise<boolean> {\r\n    if (1 === args.length) {\r\n      switch (args[0].toLowerCase()[0]) {\r\n        case \"n\":\r\n          break;\r\n        case \"c\":\r\n          this._type = OverrideType.Color;\r\n          break;\r\n        case \"e\":\r\n          this._type = OverrideType.Emphasis;\r\n          break;\r\n        case \"b\":\r\n          this._type = OverrideType.Both;\r\n          break;\r\n      }\r\n    }\r\n\r\n    return this.run(args);\r\n  }\r\n}\r\n\r\n/** Isolate all selected elements so that *only* those elements will be drawn.\r\n * @beta\r\n */\r\nexport class IsolateSelectedElementsTool extends EmphasizeElementsTool {\r\n  public static override toolId = \"IsolateSelectedElements\";\r\n  public execute(emph: EmphasizeElements, vp: ScreenViewport): void {\r\n    emph.isolateSelectedElements(vp, true, true);\r\n  }\r\n}\r\n\r\n/** Clear the set of isolated elements.\r\n * @beta\r\n */\r\nexport class ClearIsolatedElementsTool extends EmphasizeElementsTool {\r\n  public static override toolId = \"ClearIsolatedElements\";\r\n  protected override get _wantCreate() { return false; }\r\n  public execute(emph: EmphasizeElements, vp: ScreenViewport): void {\r\n    emph.clearIsolatedElements(vp);\r\n  }\r\n}\r\n\r\n/** Reset [EmphasizeElements]($frontend) for the active [Viewport]($frontend).\r\n * @beta\r\n */\r\nexport class ClearEmphasizedElementsTool extends EmphasizeElementsTool {\r\n  public static override toolId = \"ClearEmphasizedElements\";\r\n  protected override get _wantCreate() { return false; }\r\n  protected override get _wantClear() { return true; }\r\n\r\n  public execute(emph: EmphasizeElements, vp: ScreenViewport): void {\r\n    emph.clearEmphasizedElements(vp);\r\n    vp.isFadeOutActive = false;\r\n  }\r\n}\r\n\r\n/** Emphasize the set of elements currently visible in the view based on [Viewport.queryVisibleFeatures]($frontend).\r\n * @beta\r\n */\r\nexport class EmphasizeVisibleElementsTool extends EmphasizeElementsTool {\r\n  public static override toolId = \"EmphasizeVisibleElements\";\r\n  public static override get minArgs() { return 1; }\r\n  public static override get maxArgs() { return 2; }\r\n  private _options: QueryVisibleFeaturesOptions = { source: \"screen\" };\r\n  protected override get _wantClear() { return true; }\r\n\r\n  public override async parseAndRun(...input: string[]): Promise<boolean> {\r\n    const args = parseArgs(input);\r\n    const includeNonLocatable = args.getBoolean(\"n\");\r\n    let source: \"screen\" | \"tiles\";\r\n    switch (input[0].toLowerCase()) {\r\n      case \"screen\":\r\n        source = \"screen\";\r\n        break;\r\n      case \"tiles\":\r\n        source = \"tiles\";\r\n        break;\r\n      default:\r\n        return false;\r\n    }\r\n\r\n    this._options = { source, includeNonLocatable };\r\n    return this.run(input);\r\n  }\r\n\r\n  public execute(emph: EmphasizeElements, vp: ScreenViewport): void {\r\n    const elementIds = new Set<string>();\r\n    vp.queryVisibleFeatures(this._options, (features) => {\r\n      for (const feature of features) {\r\n        if (feature.iModel === vp.iModel && Id64.isValid(feature.elementId))\r\n          elementIds.add(feature.elementId);\r\n      }\r\n    });\r\n\r\n    emph.wantEmphasis = true;\r\n    if (emph.emphasizeElements(elementIds, vp))\r\n      vp.isFadeOutActive = true;\r\n  }\r\n}\r\n"]}

package/lib/tools/FrustumDecoration.d.ts

@@ -0,0 +1,58 @@
+import { DecorateContext, Decorator, Tool, Viewport } from "@itwin/core-frontend";
+interface FrustumDecorationOptions {
+    showPreloadFrustum?: boolean;
+    showBackgroundIntersections?: boolean;
+}
+/**
+ * Decorates the viewport with a graphical depiction of a Frustum.
+ * This is obviously only useful when drawn inside a viewport using a *different* Frustum.
+ * Options for doing so include:
+ *  - Having more than one viewport, and drawing the frustum of one viewport inside the other viewports; and
+ *  - Allowing the user to take a snapshot of the current frustum, then navigate the view to inspect it within the same viewport.
+ *  @beta
+ */
+export declare class FrustumDecorator implements Decorator {
+    private readonly _decoration?;
+    private constructor();
+    /** This will allow the render system to cache and reuse the decorations created by this decorator's decorate() method. */
+    readonly useCachedDecorations = true;
+    decorate(context: DecorateContext): void;
+    private static _instance?;
+    /** Add the decoration to the specified viewport. */
+    static enable(vp: Viewport, options?: FrustumDecorationOptions): void;
+    /** Remove the decoration from the specified viewport. */
+    static disable(): void;
+    static get isEnabled(): boolean;
+}
+/** Enable ("ON"), disable ("OFF"), or toggle ("TOGGLE" or omitted) the [[FrustumDecorator]].
+ * @beta
+ */
+export declare class ToggleFrustumSnapshotTool extends Tool {
+    static toolId: string;
+    static get minArgs(): number;
+    static get maxArgs(): number;
+    run(enable?: boolean, showPreloadFrustum?: boolean, showBackgroundIntersections?: boolean): Promise<boolean>;
+    parseAndRun(...args: string[]): Promise<boolean>;
+}
+/** Enable ("ON"), disable ("OFF"), or toggle ("TOGGLE" or omitted) the selected view frustum decoration.
+ * @beta
+ */
+export declare class ToggleSelectedViewFrustumTool extends Tool {
+    static toolId: string;
+    static get minArgs(): number;
+    static get maxArgs(): number;
+    run(enable?: boolean): Promise<boolean>;
+    parseAndRun(...args: string[]): Promise<boolean>;
+}
+/** Toggle visualization of the selected viewport's shadow frustum in all other viewports.
+ * @beta
+ */
+export declare class ToggleShadowFrustumTool extends Tool {
+    static toolId: string;
+    static get minArgs(): number;
+    static get maxArgs(): number;
+    run(enable?: boolean): Promise<boolean>;
+    parseAndRun(...args: string[]): Promise<boolean>;
+}
+export {};
+//# sourceMappingURL=FrustumDecoration.d.ts.map

package/lib/tools/FrustumDecoration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FrustumDecoration.d.ts","sourceRoot":"","sources":["../../src/tools/FrustumDecoration.ts"],"names":[],"mappings":"AAWA,OAAO,EACQ,eAAe,EAAE,SAAS,EAA0C,IAAI,EAAE,QAAQ,EAChG,MAAM,sBAAsB,CAAC;AAG9B,UAAU,wBAAwB;IAChC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,2BAA2B,CAAC,EAAE,OAAO,CAAC;CACvC;AAwID;;;;;;;GAOG;AACH,qBAAa,gBAAiB,YAAW,SAAS;IAChD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAoB;IAEjD,OAAO;IAIP,0HAA0H;IAC1H,SAAgB,oBAAoB,QAAQ;IAErC,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI;IAK/C,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,CAAmB;IAE5C,oDAAoD;WACtC,MAAM,CAAC,EAAE,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,wBAAwB,GAAG,IAAI;IAM5E,yDAAyD;WAC3C,OAAO,IAAI,IAAI;IAQ7B,WAAkB,SAAS,YAAuD;CACnF;AAED;;GAEG;AACH,qBAAa,yBAA0B,SAAQ,IAAI;IACjD,OAAuB,MAAM,SAA2B;IACxD,WAA2B,OAAO,WAAgB;IAClD,WAA2B,OAAO,WAAgB;IAE5B,GAAG,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,kBAAkB,CAAC,EAAE,OAAO,EAAE,2BAA2B,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAoB5G,WAAW,CAAC,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC;CAgBvE;AA0FD;;GAEG;AACH,qBAAa,6BAA8B,SAAQ,IAAI;IACrD,OAAuB,MAAM,SAA+B;IAC5D,WAA2B,OAAO,WAAgB;IAClD,WAA2B,OAAO,WAAgB;IAE5B,GAAG,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAgBvC,WAAW,CAAC,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC;CAOvE;AAoED;;GAEG;AACH,qBAAa,uBAAwB,SAAQ,IAAI;IAC/C,OAAuB,MAAM,SAAyB;IACtD,WAA2B,OAAO,WAAgB;IAClD,WAA2B,OAAO,WAAgB;IAE5B,GAAG,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAQvC,WAAW,CAAC,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC;CAOvE"}

package/lib/tools/FrustumDecoration.js

@@ -0,0 +1,372 @@
+"use strict";
+/*---------------------------------------------------------------------------------------------
+* Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+* See LICENSE.md in the project root for license terms and full copyright notice.
+*--------------------------------------------------------------------------------------------*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ToggleShadowFrustumTool = exports.ToggleSelectedViewFrustumTool = exports.ToggleFrustumSnapshotTool = exports.FrustumDecorator = void 0;
+/** @packageDocumentation
+ * @module Tools
+ */
+const core_geometry_1 = require("@itwin/core-geometry");
+const core_common_1 = require("@itwin/core-common");
+const core_frontend_1 = require("@itwin/core-frontend");
+const parseToggle_1 = require("./parseToggle");
+/**
+ * Decorates the viewport with a graphical depiction of a Frustum.
+ * This is obviously only useful when drawn inside a viewport using a *different* Frustum.
+ * Options for doing so include:
+ *  - Having more than one viewport, and drawing the frustum of one viewport inside the other viewports; and
+ *  - Allowing the user to take a snapshot of the current frustum, then navigate the view to inspect it within the same viewport.
+ */
+class FrustumDecoration {
+    constructor(vp, view, _options) {
+        this._options = _options;
+        this._worldFrustum = vp.getFrustum(core_frontend_1.CoordSystem.World, false);
+        this._adjustedWorldFrustum = vp.getFrustum(core_frontend_1.CoordSystem.World, true);
+        this._preloadFrustum = vp.viewingSpace.getPreloadFrustum();
+        this._npcFrustum = vp.getFrustum(core_frontend_1.CoordSystem.Npc, true);
+        this._worldToNpcMap = vp.viewingSpace.worldToNpcMap.clone();
+        this._eyePoint = view.camera.getEyePoint().clone();
+        this._focalPlane = vp.worldToNpc(view.getTargetPoint()).z;
+        this._isCameraOn = vp.isCameraOn;
+    }
+    static create(vp, options) {
+        const view = vp.view.isSpatialView() ? vp.view : undefined;
+        return undefined !== view ? new FrustumDecoration(vp, view, options) : undefined;
+    }
+    decorate(context) {
+        const builder = context.createGraphicBuilder(core_frontend_1.GraphicType.WorldDecoration);
+        if (this._isCameraOn)
+            FrustumDecoration.drawEyePositionAndFocalPlane(builder, this._npcFrustum, this._worldToNpcMap, this._eyePoint, this._focalPlane, context.viewport);
+        FrustumDecoration.drawFrustumBox(builder, this._worldFrustum, false, context.viewport); // show original frustum...
+        FrustumDecoration.drawFrustumBox(builder, this._adjustedWorldFrustum, true, context.viewport); // show adjusted frustum...
+        const options = this._options;
+        if (options !== undefined) {
+            if (options.showPreloadFrustum)
+                FrustumDecoration.drawPreloadFrustum(builder, this._preloadFrustum);
+            if (options === null || options === void 0 ? void 0 : options.showBackgroundIntersections) {
+                const backgroundMapGeometry = context.viewport.view.displayStyle.getBackgroundMapGeometry();
+                if (backgroundMapGeometry)
+                    backgroundMapGeometry.addFrustumDecorations(builder, this._adjustedWorldFrustum);
+            }
+        }
+        context.addDecorationFromBuilder(builder);
+    }
+    static drawPreloadFrustum(builder, frustum) {
+        const preloadColor = core_common_1.ColorDef.create(core_common_1.ColorByName.coral);
+        builder.setSymbology(preloadColor, preloadColor, 1, 2);
+        builder.addFrustum(frustum);
+    }
+    static drawFrustumBox(builder, frustum, adjustedBox, vp) {
+        const backPts = this.getPlanePts(frustum.points, false); // back plane
+        const frontPts = this.getPlanePts(frustum.points, true); // front plane
+        const bgColor = vp.view.backgroundColor;
+        const backAndBottomColor = core_common_1.ColorDef.red.adjustedForContrast(bgColor);
+        const frontAndTopLeftColor = core_common_1.ColorDef.blue.adjustedForContrast(bgColor);
+        const frontAndTopRightColor = core_common_1.ColorDef.green.adjustedForContrast(bgColor);
+        const edgeWeight = adjustedBox ? 2 : 1;
+        const edgeStyle = adjustedBox ? core_common_1.LinePixels.Solid : core_common_1.LinePixels.Code2;
+        // Back plane
+        builder.setSymbology(backAndBottomColor, core_common_1.ColorDef.black, edgeWeight, edgeStyle);
+        builder.addLineString(backPts);
+        // Front plane
+        builder.setSymbology(frontAndTopLeftColor, core_common_1.ColorDef.black, edgeWeight, edgeStyle);
+        builder.addLineString(frontPts);
+        // Bottom edge
+        builder.setSymbology(backAndBottomColor, core_common_1.ColorDef.black, edgeWeight, edgeStyle);
+        builder.addLineString(this.getEdgePts(backPts, frontPts, 0));
+        builder.addLineString(this.getEdgePts(backPts, frontPts, 1));
+        // Top edge
+        builder.setSymbology(frontAndTopRightColor, core_common_1.ColorDef.black, edgeWeight, edgeStyle);
+        builder.addLineString(this.getEdgePts(backPts, frontPts, 2));
+        builder.setSymbology(frontAndTopLeftColor, core_common_1.ColorDef.black, edgeWeight, edgeStyle);
+        builder.addLineString(this.getEdgePts(backPts, frontPts, 3));
+    }
+    static getEdgePts(startPts, endPts, index) {
+        return [
+            startPts[index],
+            endPts[index],
+        ];
+    }
+    static getPlanePts(frustPts, front) {
+        const baseIndex = front ? core_common_1.Npc._001 : core_common_1.Npc._000;
+        const planePts = [
+            frustPts[baseIndex + core_common_1.Npc._000],
+            frustPts[baseIndex + core_common_1.Npc._100],
+            frustPts[baseIndex + core_common_1.Npc._110],
+            frustPts[baseIndex + core_common_1.Npc._010],
+        ];
+        planePts.push(planePts[0]);
+        return planePts;
+    }
+    static drawEyePositionAndFocalPlane(builder, npcFrustum, worldToNpcMap, eyePoint, focusPlaneNpc, vp) {
+        // Eye position...
+        const contrastColor = vp.getContrastToBackgroundColor();
+        builder.setSymbology(contrastColor, core_common_1.ColorDef.black, 8);
+        builder.addPointString([eyePoint]);
+        // Focal plane...
+        const focalPtsNpc = FrustumDecoration.getPlanePts(npcFrustum.points, false);
+        const focalPtsWorld = [];
+        for (const npcPt of focalPtsNpc)
+            focalPtsWorld.push(core_geometry_1.Point3d.create(npcPt.x, npcPt.y, focusPlaneNpc));
+        worldToNpcMap.transform1.multiplyPoint3dArrayQuietNormalize(focalPtsWorld);
+        const bgColor = vp.view.backgroundColor;
+        const focalPlaneColor = core_common_1.ColorDef.green.adjustedForContrast(bgColor);
+        const focalTransColor = focalPlaneColor.withTransparency(100);
+        builder.setSymbology(focalPlaneColor, focalTransColor, 2);
+        builder.addLineString(focalPtsWorld);
+        builder.addShape(focalPtsWorld);
+    }
+}
+/**
+ * Decorates the viewport with a graphical depiction of a Frustum.
+ * This is obviously only useful when drawn inside a viewport using a *different* Frustum.
+ * Options for doing so include:
+ *  - Having more than one viewport, and drawing the frustum of one viewport inside the other viewports; and
+ *  - Allowing the user to take a snapshot of the current frustum, then navigate the view to inspect it within the same viewport.
+ *  @beta
+ */
+class FrustumDecorator {
+    constructor(vp, options) {
+        /** This will allow the render system to cache and reuse the decorations created by this decorator's decorate() method. */
+        this.useCachedDecorations = true;
+        this._decoration = FrustumDecoration.create(vp, options);
+    }
+    decorate(context) {
+        if (undefined !== this._decoration)
+            this._decoration.decorate(context);
+    }
+    /** Add the decoration to the specified viewport. */
+    static enable(vp, options) {
+        FrustumDecorator.disable();
+        FrustumDecorator._instance = new FrustumDecorator(vp, options);
+        core_frontend_1.IModelApp.viewManager.addDecorator(FrustumDecorator._instance);
+    }
+    /** Remove the decoration from the specified viewport. */
+    static disable() {
+        const instance = FrustumDecorator._instance;
+        if (undefined !== instance) {
+            core_frontend_1.IModelApp.viewManager.dropDecorator(instance);
+            FrustumDecorator._instance = undefined;
+        }
+    }
+    static get isEnabled() { return undefined !== FrustumDecorator._instance; }
+}
+exports.FrustumDecorator = FrustumDecorator;
+/** Enable ("ON"), disable ("OFF"), or toggle ("TOGGLE" or omitted) the [[FrustumDecorator]].
+ * @beta
+ */
+class ToggleFrustumSnapshotTool extends core_frontend_1.Tool {
+    static get minArgs() { return 0; }
+    static get maxArgs() { return 2; }
+    async run(enable, showPreloadFrustum, showBackgroundIntersections) {
+        const vp = core_frontend_1.IModelApp.viewManager.selectedView;
+        if (undefined === vp)
+            return true;
+        if (undefined === enable)
+            enable = !FrustumDecorator.isEnabled;
+        if (enable !== FrustumDecorator.isEnabled) {
+            if (enable) {
+                FrustumDecorator.enable(vp, { showPreloadFrustum, showBackgroundIntersections });
+                vp.onChangeView.addOnce(() => FrustumDecorator.disable());
+            }
+            else {
+                FrustumDecorator.disable();
+            }
+        }
+        return true;
+    }
+    async parseAndRun(...args) {
+        let showPreload, showBackgroundIntersections, enable;
+        for (const arg of args) {
+            if (arg === "preload")
+                showPreload = true;
+            else if (arg === "background")
+                showBackgroundIntersections = true;
+            else
+                enable = (0, parseToggle_1.parseToggle)(arg);
+        }
+        if (typeof enable !== "string")
+            await this.run(enable, showPreload, showBackgroundIntersections);
+        return true;
+    }
+}
+exports.ToggleFrustumSnapshotTool = ToggleFrustumSnapshotTool;
+ToggleFrustumSnapshotTool.toolId = "ToggleFrustumSnapshot";
+/**
+ * Decorates the viewport with a graphical depiction of a Frustum from the currently selected viewport.
+ * Only useful when more than one spatial viewport is open.
+ */
+class SelectedViewFrustumDecoration {
+    constructor(vp, _options) {
+        this._options = _options;
+        /** This will allow the render system to cache and reuse the decorations created by this decorator's decorate() method. */
+        this.useCachedDecorations = true;
+        this._targetVp = vp;
+        this._removeDecorationListener = core_frontend_1.IModelApp.viewManager.addDecorator(this);
+        this._removeViewChangedListener = vp.onViewChanged.addListener(this.onViewChanged, this); // eslint-disable-line @typescript-eslint/unbound-method
+        core_frontend_1.IModelApp.viewManager.invalidateCachedDecorationsAllViews(this);
+    }
+    stop() {
+        if (this._removeDecorationListener) {
+            this._removeDecorationListener();
+            this._removeDecorationListener = undefined;
+        }
+        if (this._removeViewChangedListener) {
+            this._removeViewChangedListener();
+            this._removeViewChangedListener = undefined;
+        }
+        core_frontend_1.IModelApp.viewManager.invalidateCachedDecorationsAllViews(this);
+    }
+    onViewChanged(targetVp) {
+        if (targetVp !== this._targetVp)
+            return;
+        const decorator = SelectedViewFrustumDecoration._decorator;
+        if (undefined !== decorator) {
+            for (const vp of core_frontend_1.IModelApp.viewManager) {
+                if (vp !== this._targetVp)
+                    vp.invalidateCachedDecorations(decorator);
+            }
+        }
+    }
+    decorate(context) {
+        const vp = context.viewport;
+        if (!this._targetVp.view.isSpatialView() || vp === this._targetVp || !vp.view.isSpatialView())
+            return;
+        const builder = context.createGraphicBuilder(core_frontend_1.GraphicType.WorldDecoration);
+        if (this._targetVp.isCameraOn) {
+            const npcFrustum = this._targetVp.getFrustum(core_frontend_1.CoordSystem.Npc, true);
+            const focalPlane = this._targetVp.worldToNpc(this._targetVp.view.getTargetPoint()).z;
+            FrustumDecoration.drawEyePositionAndFocalPlane(builder, npcFrustum, this._targetVp.viewingSpace.worldToNpcMap, this._targetVp.view.camera.getEyePoint(), focalPlane, context.viewport);
+        }
+        const worldFrustum = this._targetVp.getFrustum(core_frontend_1.CoordSystem.World, false);
+        const adjustedWorldFrustum = this._targetVp.getFrustum(core_frontend_1.CoordSystem.World, true);
+        FrustumDecoration.drawFrustumBox(builder, worldFrustum, false, context.viewport); // show original frustum...
+        FrustumDecoration.drawFrustumBox(builder, adjustedWorldFrustum, true, context.viewport); // show adjusted frustum...
+        if (this._options && this._options.showPreloadFrustum)
+            FrustumDecoration.drawPreloadFrustum(builder, context.viewport.viewingSpace.getPreloadFrustum());
+        context.addDecorationFromBuilder(builder);
+    }
+    // Returns true if decoration becomes enabled.
+    static toggle(vp, enabled) {
+        if (undefined !== enabled) {
+            const alreadyEnabled = undefined !== SelectedViewFrustumDecoration._decorator;
+            if (enabled === alreadyEnabled)
+                return alreadyEnabled;
+        }
+        if (undefined === SelectedViewFrustumDecoration._decorator) {
+            SelectedViewFrustumDecoration._decorator = new SelectedViewFrustumDecoration(vp);
+            return true;
+        }
+        else {
+            SelectedViewFrustumDecoration._decorator.stop();
+            SelectedViewFrustumDecoration._decorator = undefined;
+            return false;
+        }
+    }
+}
+/** Enable ("ON"), disable ("OFF"), or toggle ("TOGGLE" or omitted) the selected view frustum decoration.
+ * @beta
+ */
+class ToggleSelectedViewFrustumTool extends core_frontend_1.Tool {
+    static get minArgs() { return 0; }
+    static get maxArgs() { return 1; }
+    async run(enable) {
+        const vp = core_frontend_1.IModelApp.viewManager.selectedView;
+        if (undefined === vp || !vp.view.isSpatialView())
+            return false;
+        if (SelectedViewFrustumDecoration.toggle(vp, enable)) {
+            const remove = vp.onChangeView.addListener((_vp, prev) => {
+                if (!prev.hasSameCoordinates(vp.view)) {
+                    SelectedViewFrustumDecoration.toggle(vp, false);
+                    remove();
+                }
+            });
+        }
+        return true;
+    }
+    async parseAndRun(...args) {
+        const enable = (0, parseToggle_1.parseToggle)(args[0]);
+        if (typeof enable !== "string")
+            await this.run(enable);
+        return true;
+    }
+}
+exports.ToggleSelectedViewFrustumTool = ToggleSelectedViewFrustumTool;
+ToggleSelectedViewFrustumTool.toolId = "ToggleSelectedViewFrustum";
+class ShadowFrustumDecoration {
+    constructor(vp) {
+        /** This will allow the render system to cache and reuse the decorations created by this decorator's decorate() method. */
+        this.useCachedDecorations = true;
+        this._targetVp = vp;
+        const removeDecorator = core_frontend_1.IModelApp.viewManager.addDecorator(this);
+        const removeOnRender = vp.onRender.addListener((_) => this.onRender());
+        this._cleanup = () => { removeDecorator(); removeOnRender(); };
+        core_frontend_1.IModelApp.viewManager.invalidateCachedDecorationsAllViews(this);
+    }
+    stop() {
+        if (undefined !== this._cleanup) {
+            this._cleanup();
+            this._cleanup = undefined;
+        }
+        core_frontend_1.IModelApp.viewManager.invalidateCachedDecorationsAllViews(this);
+    }
+    onRender() {
+        const decorator = ShadowFrustumDecoration._instance;
+        if (undefined !== decorator) {
+            for (const vp of core_frontend_1.IModelApp.viewManager) {
+                if (vp !== this._targetVp)
+                    vp.invalidateCachedDecorations(decorator);
+            }
+        }
+    }
+    decorate(context) {
+        const frustum = this._targetVp.target.debugControl.shadowFrustum;
+        if (undefined === frustum)
+            return;
+        const thisVp = context.viewport;
+        if (thisVp === this._targetVp || !thisVp.view.isSpatialView())
+            return;
+        const builder = context.createGraphicBuilder(core_frontend_1.GraphicType.WorldDecoration);
+        FrustumDecoration.drawFrustumBox(builder, frustum, false, thisVp);
+        context.addDecorationFromBuilder(builder);
+    }
+    static toggle(vp, enabled) {
+        const instance = ShadowFrustumDecoration._instance;
+        if (undefined !== enabled) {
+            const alreadyEnabled = undefined !== instance;
+            if (enabled === alreadyEnabled)
+                return;
+        }
+        if (undefined === instance) {
+            ShadowFrustumDecoration._instance = new ShadowFrustumDecoration(vp);
+        }
+        else {
+            instance.stop();
+            ShadowFrustumDecoration._instance = undefined;
+        }
+    }
+}
+/** Toggle visualization of the selected viewport's shadow frustum in all other viewports.
+ * @beta
+ */
+class ToggleShadowFrustumTool extends core_frontend_1.Tool {
+    static get minArgs() { return 0; }
+    static get maxArgs() { return 1; }
+    async run(enable) {
+        const vp = core_frontend_1.IModelApp.viewManager.selectedView;
+        if (undefined !== vp && vp.view.isSpatialView())
+            ShadowFrustumDecoration.toggle(vp, enable);
+        return true;
+    }
+    async parseAndRun(...args) {
+        const enable = (0, parseToggle_1.parseToggle)(args[0]);
+        if (typeof enable !== "string")
+            await this.run(enable);
+        return true;
+    }
+}
+exports.ToggleShadowFrustumTool = ToggleShadowFrustumTool;
+ToggleShadowFrustumTool.toolId = "ToggleShadowFrustum";
+//# sourceMappingURL=FrustumDecoration.js.map