Blank IModelConnection

A Blank IModelConnection is an IModelConnection that is not connected to an IModelDb backend.

Background

Much of the iModel.js frontend package is designed to communicate with a backend serving an iModel through an IModelConnection via various RPC interfaces (e.g. IModelReadRpcInterface). However, there are some cases where it is useful create Viewports without an iModel. The IModelConnection.createBlank method can be used to create a valid IModelConnection that is not connected to a backend.

Uses

Many services in the iModel.js frontend package display information from sources other than an iModel. If you wish to open a viewport to show just that type of information, use a blank IModelConnection. For example:

• reality meshes (e.g. ContextCapture models)
• point clouds
• background maps
• terrain data
• markers
• decorations

Restrictions

A blank IModelConnection can be used for creating Viewports that show graphics from sources other than an iModel, but remember that they do not have a backend. Therefore, it is not legal to attempt RPC requests against a blank IModelConnection. Most such operations will simply return nothing, but some will throw an exception. For example, all of the various forms of ECSQL queries will throw errors if attempted with a blank IModelConnection.

You can test whether an IModelConnection is blank, by using either IModelConnection.isOpen or IModelConnection.isBlank. isOpen will be false for a blank connection, and isBlank will be true [N.B. The distinction is that isOpen will also return false for an IModelConnection that was originally opened against a backend but subsequently closed.]

Example

To open a new blank connection, you can do something like this:

  // create a new blank connection centered on Exton PA
  public openBlankConnection() {
    const exton = IModelConnection.createBlank({
      // call this connection "Exton PA"
      name: "Exton PA",
      // put the center of the connection near Exton, Pennsylvania (Bentley's HQ)
      location: Cartographic.fromDegrees(-75.686694, 40.065757, 0),
      // create the area-of-interest to be 2000 x 2000 x 200 meters, centered around 0,0.0
      extents: new Range3d(-1000, -1000, -100, 1000, 1000, 100),
    });
    return exton;
  }

then, to create a blank spatial view to show data from sources other than iModels, do something like this:

  // create a new spatial view initialized to show the project extents from top view. Model and
  // category selectors are empty, so this is useful for showing backgroundMaps, reality models, terrain, etc.
  public createBlankView(iModel: IModelConnection): SpatialViewState {
    const ext = iModel.projectExtents;

    // start with a new "blank" spatial view to show the extents of the project, from top view
    const blankView = SpatialViewState.createBlank(iModel, ext.low, ext.high.minus(ext.low));

    // turn on the background map
    const style = blankView.displayStyle as DisplayStyle3dState;
    const viewFlags = style.viewFlags;
    viewFlags.backgroundMap = true;
    style.viewFlags = viewFlags; // call to accessor to get the json properties to reflect the changes to ViewFlags

    style.backgroundColor = ColorDef.white;

    // turn on the ground and skybox in the environment
    const env = style.environment;
    env.ground.display = true;
    env.sky.display = true;
    style.environment = env; // call to accessor to get the json properties to reflect the changes

    return blankView;
  }

Last Updated: 13 June, 2024