Blank IModelConnection

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

Background

Much of the iTwin.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 BlankConnection.create method can be used to create a valid IModelConnection that is not actually associated with an iModel.

Uses

Many services in the iTwin.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 IModelConnection.isBlank. Note that isOpen will always be false for a BlankConnection, 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: BlankConnection = BlankConnection.create({
    // 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;
  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: 12 June, 2024