@itwin/core-frontend

/** @packageDocumentation * @module Views */ import { BeEvent, Id64Arg, Id64String } from "@itwin/core-bentley"; import { Angle, ClipVector, LowAndHighXY, LowAndHighXYZ, Map4d, Matrix3d, Point2d, Point3d, Range3d, Transform, Vector3d, XAndY, XYAndZ, XYZ } from "@itwin/core-geometry"; import { AnalysisStyle, AxisAlignedBox3d, Camera, Cartographic, ColorDef, FeatureAppearance, Frustum, GlobeMode, GridOrientationType, HydrateViewStateRequestProps, HydrateViewStateResponseProps, RenderSchedule, SubCategoryOverride, ViewDefinition2dProps, ViewDefinition3dProps, ViewDefinitionProps, ViewDetails, ViewDetails3d, ViewFlags, ViewStateProps } from "@itwin/core-common"; import { AuxCoordSystemState } from "./AuxCoordSys"; import { CategorySelectorState } from "./CategorySelectorState"; import { DisplayStyle2dState, DisplayStyle3dState, DisplayStyleState } from "./DisplayStyleState"; import { DrawingViewState } from "./DrawingViewState"; import { ElementState } from "./EntityState"; import { IModelConnection } from "./IModelConnection"; import { GeometricModel2dState, GeometricModelState } from "./ModelState"; import { RenderClipVolume } from "./render/RenderClipVolume"; import { RenderMemory } from "./render/RenderMemory"; import { SheetViewState } from "./SheetViewState"; import { SpatialViewState } from "./SpatialViewState"; import { StandardViewId } from "./StandardView"; import { DisclosedTileTreeSet, TileTreeReference } from "./tile/internal"; import { MarginOptions, OnViewExtentsError } from "./ViewAnimation"; import { DecorateContext, SceneContext } from "./ViewContext"; import { GlobalLocation } from "./ViewGlobalLocation"; import { Viewport } from "./Viewport"; import { ViewPose, ViewPose2d, ViewPose3d } from "./ViewPose"; import { ViewStatus } from "./ViewStatus"; import { _scheduleScriptReference } from "./common/internal/Symbols"; /** Describes the largest and smallest values allowed for the extents of a [[ViewState]]. * Attempts to exceed these limits in any dimension will fail, preserving the previous extents. * @public * @extensions */ export interface ExtentLimits { /** The smallest allowed extent in any dimension. */ min: number; /** The largest allowed extent in any dimension. */ max: number; } /** A [Transform]($core-geometry) supplied by a [[ModelDisplayTransformProvider]] to be applied to a model when displaying it in a [[Viewport]]. * @beta */ export interface ModelDisplayTransform { /** The transform to be applied to the model. */ transform: Transform; /** If `true`, [[transform]] is pre-multiplied with (i.e., appled before) the model's base transform. * Otherwise, the display transform will instead be post-multiplied with (i.e., applied after) the base transform. */ premultiply?: boolean; } /** Interface adopted by an object that wants to apply a [[ModelDisplayTransform]] to one or more models within a [[Viewport]]. * @see [[ViewState.modelDisplayTransformProvider]] to get or set the transform provider for a view. * @see [[ViewState.computeDisplayTransform]] to compute a full display transform for a model or an element within it, which may include a transform supplied by a ModelDisplayTransformProvider. * @beta */ export interface ModelDisplayTransformProvider { /** Return the transform to be applied to the specified model, if any. */ getModelDisplayTransform(modelId: Id64String): ModelDisplayTransform | undefined; } /** Arguments supplied to [[ViewState.computeDisplayTransform]]. * @beta */ export interface ComputeDisplayTransformArgs { /** The Id of the model for which to compute the display transform. */ modelId: Id64String; /** The Id of a specific element belonging to the model identified by [[modelId]] for which to compute the display transform. */ elementId?: Id64String; /** The point in time, expressed in [Unix seconds](https://en.wikipedia.org/wiki/Unix_time), at which to evaluate the display transform. * Defaults to the [DisplayStyleSettings.timePoint]($common) specified by the view's display style. */ timePoint?: number; /** The element Id of the [ViewAttachment]($backend) through which the element or model is drawn. * @beta */ viewAttachmentId?: Id64String; /** True if the element or model was drawn through a [[SpatialViewState]] attached to a [SectionDrawing]($backend). * @beta */ inSectionDrawingAttachment?: boolean; /** If supplied, [[ViewState.computeDisplayTransform]] will modify and return this Transform to hold the result instead of allocating a new Transform. * @note If [[ViewState.computeDisplayTransform]] returns `undefined`, this Transform will be unmodified. */ output?: Transform; } /** Arguments to [[ViewState3d.lookAt]] for either a perspective or orthographic view * @public */ export interface LookAtArgs { /** The new location of the camera/eye. */ readonly eyePoint: XYAndZ; /** A vector that orients the camera's "up" (view y). This vector must not be parallel to the view direction. */ readonly upVector: Vector3d; /** The new size (width and height) of the view rectangle on the focus plane centered on the targetPoint. If undefined, the existing size is unchanged. */ readonly newExtents?: XAndY; /** The distance from the eyePoint to the front plane. If undefined, the existing front distance is used. */ readonly frontDistance?: number; /** The distance from the eyePoint to the back plane. If undefined, the existing back distance is used. */ readonly backDistance?: number; /** Used for providing onExtentsError. */ readonly opts?: OnViewExtentsError; } /** Arguments to [[ViewState3d.lookAt]] to set up a perspective view * @public */ export interface LookAtPerspectiveArgs extends LookAtArgs { /** The new location to which the camera should point. This becomes the center of the view on the focus plane. */ readonly targetPoint: XYAndZ; readonly viewDirection?: never; readonly lensAngle?: never; } /** Arguments to [[ViewState3d.lookAt]] to set up an orthographic view * @public */ export interface LookAtOrthoArgs extends LookAtArgs { /** The direction in which the view should look. */ readonly viewDirection: XYAndZ; readonly targetPoint?: never; readonly lensAngle?: never; } /** Arguments to [[ViewState3d.lookAt]] to set up an perspective view using a (field-of-view) lens angle. * @public */ export interface LookAtUsingLensAngle extends LookAtArgs { /** The new location to which the camera should point. This becomes the center of the view on the focus plane. */ readonly targetPoint: XYAndZ; /** The angle that defines the field-of-view for the camera. Must be between .0001 and pi. */ readonly lensAngle: Angle; readonly viewDirection?: never; } /** Arguments to [[ViewState.attachToViewport]]. * @note The [[Viewport]] has a dependency upon and control over the [[ViewState]]. Do not use `attachToViewport` to introduce a dependency in * the opposite direction. * @public */ export type AttachToViewportArgs = Viewport; /** Arguments to [[ViewState.getAttachmentViewport]]. * @internal */ export interface GetAttachmentViewportArgs { viewAttachmentId?: Id64String; inSectionDrawingAttachment?: boolean; } /** The front-end state of a [[ViewDefinition]] element. * A ViewState is typically associated with a [[Viewport]] to display the contents of the view on the screen. A ViewState being displayed by a Viewport is considered to be * "attached" to that viewport; a "detached" viewport is not being displayed by any viewport. Because the Viewport modifies the state of its attached ViewState, a ViewState * can only be attached to one Viewport at a time. Technically, two Viewports can display two different ViewStates that both use the same [[DisplayStyleState]], but this is * discouraged - changes made to the style by one Viewport will affect the contents of the other Viewport. * * @see [Views]($docs/learning/frontend/Views.md) * @public * @extensions */ export declare abstract class ViewState extends ElementState { static get className(): string; private _auxCoordSystem?; private _extentLimits?; private _modelDisplayTransformProvider?; description?: string; isPrivate?: boolean; private readonly _gridDecorator; private _categorySelector; private _displayStyle; private readonly _unregisterCategorySelectorListeners; /** An event raised when the set of categories viewed by this view changes, *only* if the view is attached to a [[Viewport]]. */ readonly onViewedCategoriesChanged: BeEvent<() => void>; /** An event raised just before assignment to the [[displayStyle]] property, *only* if the view is attached to a [[Viewport]]. * @see [[DisplayStyleSettings]] for events raised when properties of the display style change. */ readonly onDisplayStyleChanged: BeEvent<(newStyle: DisplayStyleState) => void>; /** Event raised just before assignment to the [[modelDisplayTransformProvider]] property, *only* if the view is attached to a [[Viewport]]. * @beta */ readonly onModelDisplayTransformProviderChanged: BeEvent<(newProvider: ModelDisplayTransformProvider | undefined) => void>; /** Selects the categories that are display by this ViewState. */ get categorySelector(): CategorySelectorState; set categorySelector(selector: CategorySelectorState); /** The style that controls how the contents of the view are displayed. */ get displayStyle(): DisplayStyleState; set displayStyle(style: DisplayStyleState); /** @internal */ protected constructor(props: ViewDefinitionProps, iModel: IModelConnection, categoryOrClone: CategorySelectorState, displayStyle: DisplayStyleState); /** Create a new ViewState object from a set of properties. Generally this is called internally by [[IModelConnection.Views.load]] after the properties * have been read from an iModel. But, it can also be used to create a ViewState in memory, from scratch or from properties stored elsewhere. */ static createFromProps(_props: ViewStateProps, _iModel: IModelConnection): ViewState | undefined; /** Serialize this ViewState as a set of properties that can be used to recreate it via [[ViewState.createFromProps]]. */ toProps(): ViewStateProps; /** Flags controlling various aspects of this view's [[DisplayStyleState]]. * @see [DisplayStyleSettings.viewFlags]($common) */ get viewFlags(): ViewFlags; set viewFlags(flags: ViewFlags); /** See [DisplayStyleSettings.analysisStyle]($common). */ get analysisStyle(): AnalysisStyle | undefined; /** The [RenderSchedule.Script]($common) that animates the contents of the view, if any. * @see [[DisplayStyleState.scheduleScript]]. */ get scheduleScript(): RenderSchedule.Script | undefined; /** @internal */ get [_scheduleScriptReference](): RenderSchedule.ScriptReference | undefined; /** Get the globe projection mode. * @internal */ get globeMode(): GlobeMode; /** Determine whether this ViewState exactly matches another. */ equals(other: this): boolean; /** Convert to JSON representation. */ toJSON(): ViewDefinitionProps; /** * Populates the hydrateRequest object stored on the ViewState with: * not loaded categoryIds based off of the ViewStates categorySelector. * Auxiliary coordinate system id if valid. */ protected preload(hydrateRequest: HydrateViewStateRequestProps): void; /** Asynchronously load any required data for this ViewState from the backend. * FINAL, No subclass should override load. If additional load behavior is needed, see preload and postload. * @note callers should await the Promise returned by this method before using this ViewState. * @see [Views]($docs/learning/frontend/Views.md) */ load(): Promise<void>; protected postload(hydrateResponse: HydrateViewStateResponseProps): Promise<void>; /** Returns true if all [[TileTree]]s required by this view have been loaded. * Note that the map tile trees associated to the viewport rather than the view, to check the * map tiles as well call [[Viewport.areAreAllTileTreesLoaded]]. */ get areAllTileTreesLoaded(): boolean; /** Get the name of the [[ViewDefinition]] from which this ViewState originated. */ get name(): string; /** Get this view's background color. */ get backgroundColor(): ColorDef; /** Query the symbology overrides applied to geometry belonging to a specific subcategory when rendered using this ViewState. * @param id The Id of the subcategory. * @return The symbology overrides applied to all geometry belonging to the specified subcategory, or undefined if no such overrides exist. */ getSubCategoryOverride(id: Id64String): SubCategoryOverride | undefined; /** Query the symbology overrides applied to a model when rendered using this ViewState. * @param id The Id of the model. * @return The symbology overrides applied to the model, or undefined if no such overrides exist. */ getModelAppearanceOverride(id: Id64String): FeatureAppearance | undefined; /** @internal */ isSubCategoryVisible(id: Id64String): boolean; /** Provides access to optional detail settings for this view. */ abstract get details(): ViewDetails; /** Returns true if this ViewState is-a [[ViewState3d]] */ abstract is3d(): this is ViewState3d; /** Returns true if this ViewState is-a [[ViewState2d]] */ is2d(): this is ViewState2d; /** Returns true if this ViewState is-a [[SpatialViewState]] */ abstract isSpatialView(): this is SpatialViewState; /** Returns true if this ViewState is-a [[DrawingViewState]] */ abstract isDrawingView(): this is DrawingViewState; /** Returns true if this ViewState is-a [[SheetViewState]] */ isSheetView(): this is SheetViewState; /** Returns true if [[ViewTool]]s are allowed to operate in three dimensions on this view. */ abstract allow3dManipulations(): boolean; /** @internal */ abstract createAuxCoordSystem(acsName: string): AuxCoordSystemState; /** Get the extents of this view in [[CoordSystem.World]] coordinates. */ abstract getViewedExtents(): AxisAlignedBox3d; /** Compute a range in [[CoordSystem.World]] coordinates that tightly encloses the contents of this view. * @see [[FitViewTool]]. */ abstract computeFitRange(): Range3d; /** Returns true if this view displays the contents of a [[Model]] specified by Id. */ abstract viewsModel(modelId: Id64String): boolean; /** Get the origin of this view in [[CoordSystem.World]] coordinates. */ abstract getOrigin(): Point3d; /** Get the extents of this view in [[CoordSystem.World]] coordinates. */ abstract getExtents(): Vector3d; /** Get the 3x3 ortho-normal Matrix3d for this view. */ abstract getRotation(): Matrix3d; /** Set the origin of this view in [[CoordSystem.World]] coordinates. */ abstract setOrigin(viewOrg: XYAndZ): void; /** Set the extents of this view in [[CoordSystem.World]] coordinates. */ abstract setExtents(viewDelta: Vector3d): void; /** set the center of this view to a new position. */ setCenter(center: Point3d): void; /** Change the rotation of the view. * @note viewRot must be ortho-normal. For 2d views, only the rotation angle about the z axis is used. */ abstract setRotation(viewRot: Matrix3d): void; /** Execute a function on each viewed model */ abstract forEachModel(func: (model: GeometricModelState) => void): void; /** @internal */ abstract getModelTreeRefs(): Iterable<TileTreeReference>; /** Execute a function against each [[TileTreeReference]] associated with this view. * This may include tile trees not associated with any [[GeometricModelState]] - e.g., context reality data. * @note This method is inefficient (iteration cannot be aborted) and awkward (callback cannot be async nor return a value). Prefer to iterate using [[getTileTreeRefs]]. * @deprecated in 5.0 - will not be removed until after 2026-06-13. Use [[getTileTreeRefs]] instead. */ forEachTileTreeRef(func: (treeRef: TileTreeReference) => void): void; getTileTreeRefs(): Iterable<TileTreeReference>; /** Disclose *all* TileTrees currently in use by this view. This set may include trees not reported by [[forEachTileTreeRef]] - e.g., those used by view attachments, map-draped terrain, etc. * @internal */ discloseTileTrees(trees: DisclosedTileTreeSet): void; /** Discloses graphics memory consumed by viewed tile trees and other consumers like view attachments. * @internal */ collectStatistics(stats: RenderMemory.Statistics): void; /** Discloses graphics memory consumed by any consumers *other* than viewed tile trees, like view attachments. * @internal */ collectNonTileTreeStatistics(_stats: RenderMemory.Statistics): void; /** Capture a copy of this view's viewed volume. * @see [[applyPose]] to apply the pose to this or another view. * @public * @extensions */ abstract savePose(): ViewPose; /** Apply a pose to this view to change the viewed volume. * @see [[savePose]] to capture the view's pose. * @public * @extensions */ abstract applyPose(props: ViewPose): this; /** @internal */ createScene(context: SceneContext): void; /** Add view-specific decorations. The base implementation draws the grid. Subclasses must invoke super.decorate() * @internal */ decorate(context: DecorateContext): void; /** @internal */ static getStandardViewMatrix(id: StandardViewId): Matrix3d; /** Orient this view to one of the [[StandardView]] rotations. */ setStandardRotation(id: StandardViewId): void; /** Orient this view to one of the [[StandardView]] rotations, if the the view is not viewing the project then the * standard rotation is relative to the global position rather than the project. */ setStandardGlobalRotation(id: StandardViewId): void; /** Get the target point of the view. If there is no camera, center is returned. */ getTargetPoint(result?: Point3d): Point3d; /** Get the point at the geometric center of the view. */ getCenter(result?: Point3d): Point3d; /** @internal */ drawGrid(context: DecorateContext): void; /** @internal */ computeWorldToNpc(viewRot?: Matrix3d, inOrigin?: Point3d, delta?: Vector3d, enforceFrontToBackRatio?: boolean): { map: Map4d | undefined; frustFraction: number; }; /** Calculate the world coordinate Frustum from the parameters of this ViewState. * @param result Optional Frustum to hold result. If undefined a new Frustum is created. * @returns The 8-point Frustum with the corners of this ViewState, or undefined if the parameters are invalid. */ calculateFrustum(result?: Frustum): Frustum | undefined; calculateFocusCorners(): Point3d[]; /** Initialize the origin, extents, and rotation from an existing Frustum * This function is commonly used in the implementation of [[ViewTool]]s as follows: * 1. Obtain the ViewState's initial frustum. * 2. Modify the frustum based on user input. * 3. Update the ViewState to match the modified frustum. * @param frustum the input Frustum. * @param opts for providing onExtentsError * @return Success if the frustum was successfully updated, or an appropriate error code. */ setupFromFrustum(inFrustum: Frustum, opts?: OnViewExtentsError): ViewStatus; /** Get or set the largest and smallest values allowed for the extents for this ViewState * The default limits vary based on the type of view: * - Spatial and drawing view extents cannot exceed the diameter of the earth. * - Sheet view extents cannot exceed ten times the paper size of the sheet. * Explicitly setting the extent limits overrides the default limits. * @see [[resetExtentLimits]] to restore the default limits. */ get extentLimits(): ExtentLimits; set extentLimits(limits: ExtentLimits); /** Resets the largest and smallest values allowed for the extents of this ViewState to their default values. * @see [[extentLimits]]. */ resetExtentLimits(): void; /** Returns the default extent limits for this ViewState. These limits are used if the [[extentLimits]] have not been explicitly overridden. */ abstract get defaultExtentLimits(): ExtentLimits; setDisplayStyle(style: DisplayStyleState): void; /** Adjust the y dimension of this ViewState so that its aspect ratio matches the supplied value. * @internal */ fixAspectRatio(windowAspect: number): void; /** @internal */ outputStatusMessage(status: ViewStatus): ViewStatus; /** @internal */ adjustViewDelta(delta: Vector3d, origin: XYZ, rot: Matrix3d, aspect?: number, opts?: OnViewExtentsError): ViewStatus; /** Adjust the aspect ratio of this ViewState so it matches the supplied value. The adjustment is accomplished by increasing one dimension * and leaving the other unchanged, depending on the ratio of this ViewState's current aspect ratio to the supplied one. This means the result * always shows everything in the current volume, plus potentially more. * @note The *automatic* adjustment that happens when ViewStates are used in Viewports **always** adjusts the Y axis (making * it potentially smaller). That's so that process can be reversible if the view's aspect ratio changes repeatedly (as happens when panels slide in/out, etc.) */ adjustAspectRatio(aspect: number): void; /** Set the CategorySelector for this view. */ setCategorySelector(categories: CategorySelectorState): void; /** get the auxiliary coordinate system state object for this ViewState. */ get auxiliaryCoordinateSystem(): AuxCoordSystemState; /** Get the Id of the auxiliary coordinate system for this ViewState */ getAuxiliaryCoordinateSystemId(): Id64String; /** Set or clear the AuxiliaryCoordinateSystem for this view. * @param acs the new AuxiliaryCoordinateSystem for this view. If undefined, no AuxiliaryCoordinateSystem will be used. */ setAuxiliaryCoordinateSystem(acs?: AuxCoordSystemState): void; /** Determine whether the specified Category is displayed in this view */ viewsCategory(id: Id64String): boolean; /** Get the aspect ratio (width/height) of this view */ getAspectRatio(): number; /** Get the aspect ratio skew (x/y, usually 1.0) that is used to exaggerate the y axis of the view. */ getAspectRatioSkew(): number; /** Set the aspect ratio skew (x/y) for this view. To remove aspect ratio skew, pass 1.0 for val. */ setAspectRatioSkew(val: number): void; /** Get the unit vector that points in the view X (left-to-right) direction. * @param result optional Vector3d to be used for output. If undefined, a new object is created. */ getXVector(result?: Vector3d): Vector3d; /** Get the unit vector that points in the view Y (bottom-to-top) direction. * @param result optional Vector3d to be used for output. If undefined, a new object is created. */ getYVector(result?: Vector3d): Vector3d; /** Get the unit vector that points in the view Z (front-to-back) direction. * @param result optional Vector3d to be used for output. If undefined, a new object is created. */ getZVector(result?: Vector3d): Vector3d; /** Set or clear the clipping volume for this view. * @param clip the new clipping volume. If undefined, clipping is removed from view. * @note The ViewState takes ownership of the supplied ClipVector - it should not be modified after passing it to this function. */ setViewClip(clip?: ClipVector): void; /** Get the clipping volume for this view, if defined * @note Do *not* modify the returned ClipVector. If you wish to change the ClipVector, clone the returned ClipVector, modify it as desired, and pass the clone to [[setViewClip]]. */ getViewClip(): ClipVector | undefined; /** Set the grid settings for this view */ setGridSettings(orientation: GridOrientationType, spacing: Point2d, gridsPerRef: number): void; /** Populate the given origin and rotation with information from the grid settings from the grid orientation. */ getGridSettings(vp: Viewport, origin: Point3d, rMatrix: Matrix3d, orientation: GridOrientationType): void; /** Get the grid settings for this view */ getGridOrientation(): GridOrientationType; getGridsPerRef(): number; getGridSpacing(): XAndY; /** Change the volume that this view displays, keeping its current rotation. * @param volume The new volume, in world-coordinates, for the view. The resulting view will show all of worldVolume, by fitting a * view-axis-aligned bounding box around it. For views that are not aligned with the world coordinate system, this will sometimes * result in a much larger volume than worldVolume. * @param aspect The X/Y aspect ratio of the view into which the result will be displayed. If the aspect ratio of the volume does not * match aspect, the shorter axis is lengthened and the volume is centered. If aspect is undefined, no adjustment is made. * @param options for providing MarginPercent and onExtentsError * @note for 2d views, only the X and Y values of volume are used. */ lookAtVolume(volume: LowAndHighXYZ | LowAndHighXY, aspect?: number, options?: MarginOptions & OnViewExtentsError): void; /** Look at a volume of space defined by a range in view local coordinates, keeping its current rotation. * @param volume The new volume, in view-aligned coordinates. The resulting view will show all of the volume. * @param aspect The X/Y aspect ratio of the view into which the result will be displayed. If the aspect ratio of the volume does not * match aspect, the shorter axis is lengthened and the volume is centered. If aspect is undefined, no adjustment is made. * @param options for providing MarginPercent and onExtentsError * @see lookAtVolume */ lookAtViewAlignedVolume(volume: Range3d, aspect?: number, options?: MarginOptions & OnViewExtentsError): void; /** Set the rotation of this ViewState to the supplied rotation, by rotating it about a point. * @param rotation The new rotation matrix for this ViewState. * @param point The point to rotate about. If undefined, use the [[getTargetPoint]]. */ setRotationAboutPoint(rotation: Matrix3d, point?: Point3d): void; /** Intended strictly as a temporary solution for interactive editing applications, until official support for such apps is implemented. * Invalidates tile trees for all specified models (or all viewed models, if none specified), causing subsequent requests for tiles to make new requests to back-end for updated tiles. * Returns true if any tile tree was invalidated. * @internal */ refreshForModifiedModels(modelIds: Id64Arg | undefined): boolean; /** Determine whether this ViewState has the same coordinate system as another one. * They must be from the same iModel, and view a model in common. */ hasSameCoordinates(other: ViewState): boolean; /** Compute the vector in the "up" direction of a specific point in world space. * This is typically a unit Z vector. However, if the point is outside of the iModel's project extents and using ellipsoid [[globeMode]], an up-vector * will be computed relative to the surface of the ellipsoid at that point. */ getUpVector(point: Point3d): Vector3d; /** Return true if the view is looking at the current iModel project extents or * false if the viewed area do does not include more than one percent of the project. */ getIsViewingProject(): boolean; /** If the view is not of the project as determined by [[getIsViewingProject]] then return * the rotation from a global reference frame to world coordinates. The global reference frame includes * Y vector towards true north, X parallel to the equator and Z perpendicular to the ellipsoid surface */ getGlobeRotation(): Matrix3d | undefined; /** A value that represents the global scope of the view -- a value greater than one indicates that the scope of this view is global (viewing most of Earth). */ get globalScopeFactor(): number; private _maxGlobalScopeFactor; /** The maximum global scope is not persistent, but maintained as highest global scope factor. This can be used to determine * if the view is of a limited area or if it has ever viewed the entire globe and therefore may be assumed to view it again * and therefore may warrant resources for displaying the globe, such as an expanded viewing frustum and preloading globe map tiles. * A value greater than one indicates that the viewport has been used to view globally at least once. * @internal */ get maxGlobalScopeFactor(): number; protected _updateMaxGlobalScopeFactor(): void; /** Return elevation applied to model when displayed. This is strictly relevant to plan projection models. * @internal */ getModelElevation(_modelId: Id64String): number; /** An object that can provide per-model transforms to be applied at display time. * @note The transform is used for display purposes only. Operations upon geometry within the model may not take the display transform into account. * @see [[computeDisplayTransform]] to compute a full display transform for a model or an element within it, which may include a transform supplied by this provider. * @beta */ get modelDisplayTransformProvider(): ModelDisplayTransformProvider | undefined; set modelDisplayTransformProvider(provider: ModelDisplayTransformProvider | undefined); /** Compute the transform applied to a model or element at display time, if any. * The display transform may be constructed from any combination of the following: * - [PlanProjectionSettings.elevation]($common) applied to plan projection models by [DisplayStyle3dSettings.planProjectionSettings]($common); * - A per-model transform supplied by this view's [[modelDisplayTransformProvider]]; and/or * - A transform applied to an element by an [RenderSchedule.ElementTimeline]($common) defined by this view's [[scheduleScript]]. * - A transform from the coordinate space of a [ViewAttachment]($backend)'s view to that of the [[SheetViewState]] in which it is displayed. * - A transform from the coordinate space of a [[SpatialViewState]] to that of the [[DrawingViewState]] in which it is displayed, where the spatial view is attached via a [SectionDrawing]($backend). * @param args A description of how to compute the transform. * @returns The computed transform, or `undefined` if no display transform is to be applied. * @beta */ computeDisplayTransform(args: ComputeDisplayTransformArgs): Transform | undefined; /** Invoked when this view becomes the view displayed by the specified [[Viewport]]. * A ViewState can be attached to at most **one** Viewport at any given time. * This method is invoked automatically by the viewport - there is generally no reason for applications to invoke it directly. * @note If you override this method you **must** call `super.attachToViewport`. * @throws Error if the view is already attached to any Viewport. * @see [[detachFromViewport]] from the inverse operation. */ attachToViewport(_args: AttachToViewportArgs): void; private registerCategorySelectorListeners; /** Invoked when this view, previously attached to the specified [[Viewport]] via [[attachToViewport]], is no longer the view displayed by that Viewport. * This method is invoked automatically by the viewport - there is generally no reason for applications to invoke it directly. * @note If you override this method you **must** call `super.detachFromViewport`. * @throws Error if the view is not attached to any Viewport. */ detachFromViewport(): void; private unregisterCategorySelectorListeners; /** Returns whether this view is currently being displayed by a [[Viewport]]. * @public */ get isAttachedToViewport(): boolean; /** Returns an iterator over additional Viewports used to construct this view's scene. e.g., those used for ViewAttachments and section drawings. * This exists chiefly for display-performance-test-app to determine when all tiles required for the view have been loaded. * @internal */ get secondaryViewports(): Iterable<Viewport>; /** Find the viewport that renders the contents of the view attachment with the specified element Id into this view. * @internal */ getAttachmentViewport(_args: GetAttachmentViewportArgs): Viewport | undefined; } /** Defines the state of a view of 3d models. * @see [ViewState Parameters]($docs/learning/frontend/views#viewstate-parameters) * @public * @extensions */ export declare abstract class ViewState3d extends ViewState { private readonly _details; private readonly _modelClips; private _environmentDecorations?; static get className(): string; /** True if the camera is valid. */ protected _cameraOn: boolean; /** The lower left back corner of the view frustum. */ readonly origin: Point3d; /** The extent of the view frustum. */ readonly extents: Vector3d; /** Rotation of the view frustum. */ readonly rotation: Matrix3d; /** The camera used for this view. */ readonly camera: Camera; /** Minimum distance for front plane */ forceMinFrontDist: number; /** Provides access to optional detail settings for this view. */ get details(): ViewDetails3d; allow3dManipulations(): boolean; /** Set whether [[ViewTool]]s are allowed to operate in 3 dimensions on this view. */ setAllow3dManipulations(allow: boolean): void; constructor(props: ViewDefinition3dProps, iModel: IModelConnection, categories: CategorySelectorState, displayStyle: DisplayStyle3dState); private updateModelClips; /** @internal */ getModelClip(modelId: Id64String): RenderClipVolume | undefined; /** Capture a copy of the viewed volume and camera parameters. */ savePose(): ViewPose3d; /** See [[ViewState.applyPose]]. */ applyPose(val: ViewPose): this; toJSON(): ViewDefinition3dProps; /** See [[ViewState.is3d]]. */ is3d(): this is ViewState3d; /** @internal */ isDrawingView(): this is DrawingViewState; get isCameraOn(): boolean; private static _minGlobeEyeHeight; private static _scratchGlobeCarto; get isGlobalView(): boolean; /** A value that represents the global scope of the view -- a value greater than one indicates that the scope of this view is global. * @see [[isGlobalView]]. */ get globalScopeFactor(): number; /** A value representing the degree to which a view is viewing the globe as opposed to a specific location * a value of zero or less indicates that the view is not global, a value between zero and one represent a semi * global view. Values greater than one indicate a global view. * * A Global view is arbitrarily designated as a camera view with the camera height greater than one fourth of the globe * radius or an orthographic view with view diagonal greater than one fourth of the globe radius. */ globalViewTransition(): number; getCartographicHeight(point: XYAndZ): number | undefined; getEyeCartographicHeight(): number | undefined; isEyePointGlobalView(eyePoint: XYAndZ): boolean; /** Look at a global location, placing the camera's eye at the specified eye height above a viewed location. * If location is defined, its center position will be viewed using the specified eye height. * If location also has an area specified, the eye height will be adjusted to view the specified location based on that area. * Otherwise, this function views a point on the earth as if the current eye point was placed on the earth. If the eyePoint parameter is defined, instead this point will be placed on the earth and viewed. * Specify pitchAngleRadians to tilt the final view; this defaults to 0. * Returns the distance from original eye point to new eye point. * @public */ lookAtGlobalLocation(eyeHeight: number, pitchAngleRadians?: number, location?: GlobalLocation, eyePoint?: Point3d): number; /** Look at a global location, placing the camera's eye at the specified eye height above a viewed location using the GCS. * If location is defined, its center position will be viewed using the specified eye height. * If location also has an area specified, the eye height will be adjusted to view the specified location based on that area. * Otherwise, this function views a point on the earth as if the current eye point was placed on the earth. If the eyePoint parameter is defined, instead this point will be placed on the earth and viewed. * Specify pitchAngleRadians to tilt the final view; this defaults to 0. * Returns the distance from original eye point to new eye point. * @public */ lookAtGlobalLocationFromGcs(eyeHeight: number, pitchAngleRadians?: number, location?: GlobalLocation, eyePoint?: Point3d): Promise<number>; private finishLookAtGlobalLocation; /** Convert a point in spatial coordinates to a cartographic coordinate. */ rootToCartographic(root: XYAndZ, result?: Cartographic): Cartographic | undefined; /** Convert a cartographic coordinate to a point in spatial coordinates. */ cartographicToRoot(cartographic: Cartographic, result?: Point3d): Point3d | undefined; /** 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. */ rootToCartographicFromGcs(root: XYAndZ, result?: Cartographic): Promise<Cartographic | undefined>; /** 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. */ rootToCartographicUsingGcs(root: XYAndZ[]): Promise<Cartographic[] | undefined>; /** 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. */ cartographicToRootFromGcs(cartographic: Cartographic, result?: Point3d): Promise<Point3d | undefined>; /** 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. */ cartographicToRootUsingGcs(cartographic: Cartographic[]): Promise<Point3d[] | undefined>; setupFromFrustum(frustum: Frustum, opts?: OnViewExtentsError): ViewStatus; protected static calculateMaxDepth(delta: Vector3d, zVec: Vector3d): number; getOrigin(): Point3d; getExtents(): Vector3d; getRotation(): Matrix3d; setOrigin(origin: XYAndZ): void; setExtents(extents: XYAndZ): void; setRotation(rot: Matrix3d): void; /** @internal */ protected enableCamera(): void; supportsCamera(): boolean; minimumFrontDistance(): number; isEyePointAbove(elevation: number): boolean; /** The style that controls how the contents of the view are displayed. */ get displayStyle(): DisplayStyle3dState; set displayStyle(style: DisplayStyle3dState); /** The style that controls how the contents of the view are displayed. * @see [[ViewState3d.displayStyle]]. */ getDisplayStyle3d(): DisplayStyle3dState; /** Turn the camera off for this view. After this call, the camera parameters in this view definition are ignored and views that use it will * display with an orthographic (infinite focal length) projection of the view volume from the view direction. * @note To turn the camera back on, call #lookAt */ turnCameraOff(): void; /** Determine whether the camera is valid for this view */ get isCameraValid(): boolean; /** Calculate the lens angle formed by the current delta and focus distance */ calcLensAngle(): Angle; /** Get the target point of the view. If there is no camera, view center is returned. */ getTargetPoint(result?: Point3d): Point3d; /** Setup view state for either perspective or orthographic view. * @returns A [[ViewStatus]] indicating whether the camera was successfully positioned. * @note If the aspect ratio of viewDelta does not match the aspect ratio of a Viewport into which this view is displayed, it will be * adjusted when the [[Viewport]] is synchronized from this view. */ lookAt(args: LookAtPerspectiveArgs | LookAtOrthoArgs | LookAtUsingLensAngle): ViewStatus; /** Change the focus distance for this ViewState3d. Preserves the content of the view. * @internal */ changeFocusDistance(newDist: number): ViewStatus; /** Change the focus distance for this ViewState3d to be defined by the the supplied point, if it is in front of the camera. * Preserves the content of the view. * @internal */ changeFocusFromPoint(pt: Point3d): ViewStatus; /** Move the camera relative to its current location by a distance in camera coordinates. * @param distance to move camera. Length is in world units, direction relative to current camera orientation. * @returns Status indicating whether the camera was successfully positioned. See values at [[ViewStatus]] for possible errors. */ moveCameraLocal(distance: Vector3d): ViewStatus; /** Move the camera relative to its current location by a distance in world coordinates. * @param distance in world units. * @returns Status indicating whether the camera was successfully positioned. See values at [[ViewStatus]] for possible errors. */ moveCameraWorld(distance: Vector3d): ViewStatus; /** Rotate the camera from its current location about an axis relative to its current orientation. * @param angle The angle to rotate the camera. * @param axis The axis about which to rotate the camera. The axis is a direction relative to the current camera orientation. * @param aboutPt The point, in world coordinates, about which the camera is rotated. If aboutPt is undefined, the camera rotates in place * (i.e. about the current eyePoint). * @note Even though the axis is relative to the current camera orientation, the aboutPt is in world coordinates, \b not relative to the camera. * @returns Status indicating whether the camera was successfully positioned. See values at [[ViewStatus]] for possible errors. */ rotateCameraLocal(angle: Angle, axis: Vector3d, aboutPt?: Point3d): ViewStatus; /** Rotate the camera from its current location about an axis in world coordinates. * @param angle The angle to rotate the camera. * @param axis The world-based axis (direction) about which to rotate the camera. * @param aboutPt The point, in world coordinates, about which the camera is rotated. If aboutPt is undefined, the camera rotates in place * (i.e. about the current eyePoint). * @returns Status indicating whether the camera was successfully positioned. See values at [[ViewStatus]] for possible errors. */ rotateCameraWorld(angle: Angle, axis: Vector3d, aboutPt?: Point3d): ViewStatus; /** Move camera about the global ellipsoid. This rotates the camera position about the center of the global ellipsoid maintaining the current height. * @param fromPoint Point to pan from. * @param point Point to point to. * @returns Status indicating whether the camera was successfully positioned. See values at [[ViewStatus]] for possible errors. */ moveCameraGlobal(fromPoint: Point3d, toPoint: Point3d): ViewStatus; /** Get the distance from the eyePoint to the front plane for this view. */ getFrontDistance(): number; /** Get the distance from the eyePoint to the back plane for this view. */ getBackDistance(): number; /** Place the eyepoint of the camera so it is aligned with the center of the view. This removes any 1-point perspective skewing that may be * present in the current view. * @param backDistance If defined, the new the distance from the eyepoint to the back plane. Otherwise the distance from the * current eyepoint is used. */ centerEyePoint(backDistance?: number): void; /** Center the focus distance of the camera halfway between the front plane and the back plane, keeping the eyepoint, * lens angle, rotation, back distance, and front distance unchanged. * @note The focus distance, origin, and delta values are modified, but the view encloses the same volume and appears visually unchanged. */ centerFocusDistance(): void; /** Ensure the focus plane lies between the front and back planes. If not, center it. */ verifyFocusPlane(): void; /** Get the current location of the eyePoint for camera in this view. */ getEyePoint(): Point3d; /** Get the lens angle for this view. */ getLensAngle(): Angle; /** Set the lens angle for this view. * @param angle The new lens angle in radians. Must be greater than 0 and less than pi. * @note This does not change the view's current field-of-view. Instead, it changes the lens that will be used if the view * is subsequently modified and the lens angle is used to position the eyepoint. * @note To change the field-of-view (i.e. "zoom") of a view, pass a new viewDelta to #lookAt */ setLensAngle(angle: Angle): void; /** Change the location of the eyePoint for the camera in this view. * @param pt The new eyepoint. * @note This method is generally for internal use only. Moving the eyePoint arbitrarily can result in skewed or illegal perspectives. * The most common method for user-level camera positioning is #lookAt. */ setEyePoint(pt: XYAndZ): void; /** Set the focus distance for this view. * @note Changing the focus distance changes the plane on which the delta.x and delta.y values lie. So, changing focus distance * without making corresponding changes to delta.x and delta.y essentially changes the lens angle, causing a "zoom" effect */ setFocusDistance(dist: number): void; /** Get the distance from the eyePoint to the focus plane for this view. */ getFocusDistance(): number; /** Obtain an "eye" point for this view. If the camera is on, this simply returns [[Camera.getEyePoint]]. * Otherwise, a pseudo-eye-point is computed from the view direction and a lens angle of PI/2. */ getEyeOrOrthographicViewPoint(): Point3d; createAuxCoordSystem(acsName: string): AuxCoordSystemState; decorate(context: DecorateContext): void; /** Returns the ground elevation taken from the environment added with the global z position of this imodel. */ getGroundElevation(): number; /** Return the ground extents, which will originate either from the viewport frustum or the extents of the imodel. */ getGroundExtents(vp?: Viewport): AxisAlignedBox3d; /** @internal */ getModelElevation(modelId: Id64String): number; /** If the background map is displayed, return the point on the globe in directly front of the eye (or in center of view if camera off) * This is generally a better target point for orthographic views than the view center which can be far from the area of interest. * @public */ getEarthFocalPoint(): Point3d | undefined; /** * For a geoLocated project, align the view with the global ellipsoid by rotating * around the supplied target point such that the view axis points toward the * globe center. If the viewing height is below the global transition threshold. * @param target The rotation target or pivot point. This point will remain stationary in the view. * @param transition If this is defined and true then the rotation is scaled by the [[ViewState.globalViewTransition]] This * will cause a smooth transition as a view is zoomed out from a specific location to a more global representation. * @public */ alignToGlobe(target: Point3d, transition?: boolean): ViewStatus; /** See [[ViewState.attachToViewport]]. */ attachToViewport(args: AttachToViewportArgs): void; /** See [[ViewState.detachFromViewport]]. */ detachFromViewport(): void; } /** Defines the state of a view of a single 2d model. * @public * @extensions */ export declare abstract class ViewState2d extends ViewState { private readonly _details; static get className(): string; readonly origin: Point2d; readonly delta: Point2d; readonly angle: Angle; protected _baseModelId: Id64String; get baseModelId(): Id64String; /** @internal */ protected _treeRe