2.17.0 Change Notes

UI Changes

Cube Navigation Aid

The enums HitBoxX, HitBoxY, and HitBoxZ used by the CubeNavigationAid have been renamed to CubeNavigationHitBoxX, CubeNavigationHitBoxY, and CubeNavigationHitBoxZ, respectively. The old enums are deprecated.

TimelineComponent and TimelineComponentDataProvider

The incomplete milestones feature was removed from the TimelineComponent and TimelineComponentDataProvider in preparation to move the APIs to @public.

New IModel events

IModels now emit events when their properties change.

• IModel.onProjectExtentsChanged
• IModel.onGlobalOriginChanged
• IModel.onEcefLocationChanged
• IModel.onGeographicCoordinateSystemChanged
• IModel.onRootSubjectChanged
• IModel.onNameChanged

Within IpcApp-based applications, BriefcaseConnections now automatically synchronize their properties in response to such events produced by changes on the backend. For example, if BriefcaseDb.projectExtents is modified, BriefcaseConnection.projectExtents will be updated to match and both the BriefcaseDb and BriefcaseConnection will emit an onProjectExtentsChanged event.

Reality model APIs

Several APIs relating to reality models have been introduced, in some cases replacing previous beta APIs. A reality model can be displayed in a Viewport in one of two ways:

• Adding to the ViewState's ModelSelector the Id of a persistent SpatialModelState containing a URL pointing to a 3d tileset; or
• Attaching to the DisplayStyleState a ContextRealityModel with a URL pointing to a 3d tileset.

The set of ContextRealityModels attached to a display style can be accessed and modified via DisplayStyleSettings.contextRealityModels.

Spatial classification can be applied to a reality model using ContextRealityModel.classifiers or SpatialModelState.classifiers. The SpatialClassifier APIs replace the previous beta APIs in the SpatialClassificationProps namespace.

Portions of a reality model can be masked by other models using ContextRealityModel.planarClipMaskSettings or, for persistent models, DisplayStyleSettings.planarClipMasks.

The color, transparency, locatability, and "emphasized" state of a reality model can be overridden using ContextRealityModel.appearanceOverrides or, for persistent models, DisplayStyleSettings.modelAppearanceOverrides.

A reality model displaying simple building meshes for locations all over the world obtained from OpenStreetMap Buildings can be enabled via DisplayStyleState.setOSMBuildingDisplay.

Popout Widgets

IModelApps, that use AppUi version "2", can now specify if a Widget can support being "popped-out" to a child popup window. The child window runs in the same javascript context as the parent application window. See Child Window Manager for more details.

External textures

The external textures feature is now enabled by default.

Previously, by default the images for textured materials would be embedded in the tile contents. This increased the size of the tile, consumed bandwidth, and imposed other penalties. The external textures feature, however, requires only the Id of the texture element to be included in the tile; the image can then be requested separately. Texture images are cached, so the image need only be requested once no matter how many tiles reference it.

Additionally, if a dimension of the external texture exceeds the client's maximum supported texture size, the image will be downsampled to adhere to that limit before being transmitted to the client.

To disable external textures, pass a TileAdmin to IModelApp.startup with the feature disabled as follows:

  const tileAdminProps: TileAdmin.Props = { enableExternalTextures: false };
  const tileAdmin = TileAdmin.create(tileAdminProps);
  IModelApp.startup({ tileAdmin });

Disabling this feature is not recommended and will incur a performance penalty. The option to disable the feature will likely be removed in the future.

ECClass Ids in changed events

The events TxnManager.onElementsChanged and TxnManager.onModelsChanged now include the Id of each changed entity's ECClass. The OrderedId64Array properties of TxnChangedEntities are deprecated in favor of the new EntityIdAndClassIdIterable properties.

Presentation

Associating content items with given input

Sometimes there's a need to associate content items with given input. For example, when requesting child elements' content based on given parent keys, we may want to know which child element content item is related to which given parent key. That information has been made available through Item.inputKeys attribute. Because getting this information may be somewhat expensive and is needed only occasionally, it's only set when content is requested with ContentFlags.IncludeInputKeys flag.

Custom category nesting

A new requiredSchemas attribute was added to Ruleset, Rule and SubCondition definitions. The attribute allows specifying ECSchema requirements for rules and avoid using them when requirements are not met. See the schema requirements page for more details.

Promoted APIs

The following APIs have been promoted to public. Public APIs are guaranteed to remain stable for the duration of the current major version of a package.

@bentley/bentleyjs-core

• ReadonlySortedArray.findEquivalent and ReadonlySortedArray.indexOfEquivalent for locating an element based on a custom criterion.
• CompressedId64Set.sortAndCompress for conveniently producing a compact representation of a set of Id64Strings.

@bentley/imodeljs-common

• RenderSchedule for defining scripts to visualize changes in an iModel over time.

@bentley/imodeljs-frontend

• LookAndMoveTool for using videogame-like mouse and keyboard controls to navigate a 3d view.
• Viewport.antialiasSamples and ViewManager.setAntialiasingAllViews for applying antialiasing to make viewport images appear smoother.

@bentley/imodeljs-backend package

• TxnManager for managing local changes to a BriefcaseDb. The arguments for the @beta protected static methods called during modifications have been changed to be more consistent and extensible:
• IModelDb.generateElementGraphics for generating RenderGraphics from GeometricElements or arbitrary geometry streams.
• IModelDb.getGeometryContainment for computing the containment of a set of GeometricElements within a ClipVector.
• Element [onInsert, onInserted, onUpdate, onUpdated, onDelete, onDeleted]
• Model [onInsert, onInserted, onUpdate, onUpdated, onDelete, onDeleted]
• ElementAspect [onInsert, onInserted, onUpdate, onUpdated, onDelete, onDeleted]

In addition, new protected static methods were added:

• Element [onChildInsert, onChildInserted, onChildUpdate, onChildUpdated, onChildDelete, onChildDeleted, onChildAdd, onChildAdded, onChildDrop, onChildDropped]

@bentley/webgl-compatibility

• queryRenderCompatibility for querying the client system's compatibility with the iTwin.js rendering system.

Breaking API changes

During the course of routine improvement and stabilization of formerly alpha and beta APIs, some such APIs have changed. No breaking changes have been made to public APIs.

@bentley/imodeljs-common

The following APIs have been replaced:

• DisplayStyleSettings:
  • getModelPlanarClipMask, overrideModelPlanarClipMask, and dropModelPlanarClipMaskOverride: use the get, set, and delete methods, respectively, of DisplayStyleSettings.planarClipMasks.
  • onRealityModelPlanarClipMaskChanged: use DisplayStyleSettings.onPlanarClipMaskChanged for changes to DisplayStyleSettings.planarClipMasks and DisplayStyleSettings.contextRealityModels's onPlanarClipMaskChanged event for ContextRealityModels.
• SpatialClassificationProps namespace: use SpatialClassifier instead.

@bentley/imodeljs-frontend

• Most properties and methods of ContextRealityModelState have moved to its new base class, ContextRealityModel.
• The SpatialClassifiers class has moved to imodeljs-common.
• Viewport.setOSMBuildingDisplay has been replaced by DisplayStyleState.setOSMBuildingDisplay.
• The following DisplayStyleState APIs have been replaced:
  • Methods identifying ContextRealityModels by array index have been replaced with APIs that take a ContextRealityModel object. If your existing code has an array index, you can use it to index into the arrays exposed by DisplayStyleState.contextRealityModelStates and the models property of DisplayStyleSettings.contextRealityModels.
  • getModelAppearanceOverride, overrideModelAppearance, dropModelAppearanceOverride: use the get, set, and delete methods of DisplayStyleSettings.modelAppearanceOverrides.
  • getRealityModelAppearanceOverride, overrideRealityModelAppearance, dropRealityModelAppearanceOverride: use ContextRealityModel.appearanceOverrides.
  • modelAppearanceOverrides: use DisplayStyleSettings.modelAppearanceOverrides.
  • getRealityModelPlanarClipMask, overrideRealityModelPlanarClipMask, dropRealityModelPlanarClipMask: use ContextRealityModel.planarClipMaskSettings.

@bentley/imodeljs-backend

To make it easier to use async APIs while exporting a schema, IModelExportHandler.onExportSchema has been made async and must return a promise. For example, serialization APIs can be async, and previously to have custom async schema serialization, one would have to manually synchronize around their call to IModelExporter.exportSchemas.

IModelTransformer.shouldExportSchema now gets a SchemaKey schema key as argument, instead of a full Schema. If you need to check the full schema, return true in shouldExportSchema and in IModelExportHandler.onExportSchema, you can use the schema object to check and then return early.

Last Updated: 11 June, 2024