3.1.0 Change Notes

Upgrade Note - peer dependency changes

• The core-backend package has changed it's peer dependency on ecschema-metadata to optional. So it is no longer necessary to list ecschema-metadata as a dependency unless you use the IModelSchemaLoader.
• The package ecschema-metadata now has core-quantity as a peer dependency.

So if you are upgrading from 2.x or 3.0 and depend on core-backend you must either add core-quantity or remove ecschema-metadata.

Simplified material creation

RenderSystem.createMaterial presents an awkward API requiring the instantiation of several related objects to create even a simple RenderMaterial. It also requires an IModelConnection. It has been deprecated in favor of RenderSystem.createRenderMaterial, which accepts a single CreateRenderMaterialArgs object concisely specifying only the properties of interest to the caller. For example, the following:

  const params = new RenderMaterial.Params();
  params.alpha = 0.5;
  params.diffuseColor = ColorDef.blue;
  params.diffuse = 0.4;

  const mapParams = new TextureMapping.Params({ textureWeight: 0.25 });
  params.textureMapping = new TextureMapping(texture, mapParams);
  const material = IModelApp.renderSystem.createMaterial(params, iModel);

Can now be expressed as follows (note no IModelConnection is required):

  const material = IModelApp.renderSystem.createRenderMaterial({
    alpha: 0.5,
    diffuse: { color: ColorDef.blue, weight: 0.4 },
    textureMapping: { texture, weight: 0.25 },
  });

Model map layers

Previously, map layers defined by a MapLayerSettings were limited to imagery generated by tile servers, but many iModels contain planar spatial models representing GIS data or aerial photography, similar to that obtained from tile imagery services. Now, the imagery for a map layer can also be obtained from such a model by specifying its model Id in a ModelMapLayerSettings. The model's geometry will be projected onto the terrain surface, and display of categories within the layer can be controlled by the view's category selector.

In the image below, a planar GIS model is displayed as an ordinary model in the scene - note how it does not align correctly with the 3d terrain:

When displayed instead as a map layer, the same GIS model is correctly draped onto the 3d terrain:

MapLayerSettings now serves as a base class for ImageMapLayerSettings and ModelMapLayerSettings, with respective JSON representations ImageMapLayerProps and ModelMapLayerProps.

Obtain geometry from terrain and reality models

• TileGeometryCollector, which specifies the level of detail, spatial volume, and other criteria for determining which tile meshes to obtain; and
• GeometryTileTreeReference, a TileTreeReference that can supply Polyface for its tiles.

A GeometryTileTreeReference can be obtained from an existing TileTreeReference via TileTreeReference.createGeometryTreeReference. You can then supply a TileGeometryCollector to GeometryTileTreeReference.collectTileGeometry to collect the polyfaces. Because tile contents are downloaded asynchronously, you will need to repeat this process over successive frames until TileGeometryCollector.isAllGeometryLoaded evaluates true.

display-test-app provides an example tool that uses these APIs to allow the user to drape line strings onto terrain and reality models.

Draco compression

Draco compression can significantly reduce the sizes of meshes and point clouds. iTwin.js has been enhanced to correctly decompress reality models, point clouds, and glTF models that contain draco-encoded data, reducing download time and bandwidth usage.

Floating content views in AppUI

Font Workspaces

It is now possible to store and load fonts from a Font Workspace. See Fonts for more details.

Promote QuantityFormatter from beta to public

The QuantityFormatter, accessed via IModelApp.quantityFormatter, is now public and provides a set of APIs to format and parse standard quantity types. For more documentation and samples see Quantity Formatting.

New SchemaUnitProvider

It is now possible to retrieve Units from schemas stored in IModels. The new SchemaUnitProvider can now be created and used by the QuantityFormatter or any method in the core-quantity package that requires a UnitsProvider. Below is an example, extracted from ui-test-app, that demonstrates how to register the IModel-specific UnitsProvider as the IModelConnection is created. This new provider will provide access to a wide variety of Units that were not available in the standalone BasicUnitsProvider.

    // Provide the QuantityFormatter with the iModelConnection so it can find the unit definitions defined in the iModel
    const schemaLocater = new ECSchemaRpcLocater(iModelConnection);
    await IModelApp.quantityFormatter.setUnitsProvider (new SchemaUnitProvider(schemaLocater));

IMPORTANT: the core-quantity package is not a peer dependency of the ecschema-metadata package

AppUI Updates

WidgetState changes

The property WidgetDef.state will now return WidgetState.Closed if the widget is in a panel that is collapsed, or the panel size is 0 or undefined. When WidgetState.Open is passed to the method WidgetDef.setWidgetState the containing panel will also open if it is in a collapsed state.