Map Layers widget – Referencing GIS data to an iModel

The Map Layers widget allows to manage the display of the Base Layer and ArcGIS, WMS and WMTS layers.

  

Referencing GIS data to the iModel essentially publishes it as raster layers in the view. Use any GIS server (ESRI, open source MapServer, GeoServer, etc.) to compose your map. Then, simply add new connections to the service, through the Map Layers widget and access your GIS data.

Supported Coordinate systems

The Map Layers widget supports two coordinate systems. Make sure the GIS Data to attach is published in one of the following coordinate systems.

• EPSG:3857
• EPSG:4326

When adding a layer, a validation is made on the GIS data coordinate system. If the coordinate system is not supported, the attachment will fail.

Benefits

One of the main benefits of referencing is that the existing complex symbology defined in a GIS system, is automatically accessible, without the need of recreating it.

Another major advantage is accessing live data. This way, the information that is displayed in Design Review is always true and up to date.

This option has some limitations. For example, it is not possible to select an element in the view and see the properties attached to it, unless the server is configured to support non-graphical query operations. If the server is configured in that way and that the “Locatable” option is turned ON in the settings panel, it will be possible to over the cursor on a tile and the associated properties will be displayed in a tooltip as below:

Base layer

Essentially, a Base layer shows geographic information displayed in the background. It provides context for additional layers that overlay on top of the base layer.

The Base layer is available if and only if the iModel is georeferenced. If not, the iModel will be displayed with the background color defined in the viewer presentation options and an information message displayed in the Map Layers widget:

The following Bing services are available in the list:

• Solid Fill Color – The globe is displayed with the color that is defined in the viewer Presentation options’ panel
• Bing Maps: Aerial Imagery – The globe is displayed with the Bing aerial imagery
• Bing Maps: Aerial Imagery with Labels – The globe is displayed with the Bing aerial imagery plus the labels that give more contextual information
• Bing Maps: Streets – The globe is displayed with a road map

These layers above are present in the list as default, out of the box. The user doesn’t have to add them manually.

The visibility of the layer can be changed by toggling ON and OFF.

The transparency of the Base Layer can be modified by using the slider bar.

Background and Overlay layers

The user can add layers in the Background section and/or Overlay section. He can drag a layer from one section to the other, as well as ordering the layers within a section.

Background section – The layers added into this section will be displayed over the Bing layer but behind the iModel.

Overlay section – The layers added into this section will be displayed on top of all layers, including the iModel.

More Options on the layers

Click on the “More” menu at the right-hand side of the layer name to see more options to apply to the layer.

Zoom to layer

Selecting the “Zoom to layer” option fits the selected layer in the view.

Detach

Selecting the “Detach” option removes the selected layer from the view.

Transparency slider

Moving the slider changes the transparency of the selected layer. The transparency is applied on the layer once the data button is released.

 Add new layer

To add a new layer, click on the “Add Layer” button or on the “+” sign.

Attach New Layer dialog

Type

Select the type of service. The Background and Overlay sections allow to reference three types of GIS data:

• ArcGIS Map Service*
• WMS
• WMTS

* ArcGIS Identity (OAuth2) authentication protocol has been implemented in the Map Layers widget API. For more information on this topic, please follow the link below:
ArcGIS MapServer -ArcGIS Identity (OAuth2)

Name

Type a name. Use a name that is relevant so that any user who wants to attach the layer can easily know which layer he is attaching.

 URL

Type or copy the URL of the server to attach.

IMPORTANT NOTE: The resource must be served over HTTPS. Insecure resource will return error at attchment.

Here are some examples of URL that should be used:

Username & Password

These fields are displayed only when the specified URL requires a basic authentication.

Type the credentials to connect to the server. 

For ArcGIS Map Server layers that require ArcGIS Identity authentication (OAuth2), please refer to a previous section in this document.

Store on iTwinSettings

When this option is toggled on, the layer is stored on the iTwin settings. Thus, all iModels from a given iTwin will be able to attach the layer.

Store on Model Settings

When this option is toggled on, the layer is stored for the current iModel only. Thus, the layer will not be available for attachment to other iModels contained in the project.

Reorder the layers

You can move the layers from the background section to the overlay section, and vis versa, by using the drag and drop functionality. The layers can also be reorder within a section, the same way.

Edit or Delete a layer

Edit or Delete a layer

It is possible to edit a layer definition or delete a layer from the list simply by clicking on the “Edit” or “Delete” icon.

When clicking on Edit, only the name can be edited. If you want to edit the URL, the layer must be deleted and recreated.

Turning OFF all layers

All the layers from the Map Layers dialog, including the Base layer, can be turned ON and OFF by clicking on the toggle on the upper right side of the dialog.

Settings dialog

Different settings are available in the Map Layers Settings panel.

Transparency

Use the slider to apply transparency on all layers from the Map Layers widget.

Locatable

Toggle ON this option to see the information and coordinates of the location pointed by the cursor on the Bing layer.

Mask by Models

Toggle ON this option to mask the map layers contained in the view. The iModel and the reality data serve as clipping element. This can be useful when the iModel contains elements located under the ground. Enabling the mask allows to see the underground portion of an iModel. When turned off, the map layers block the view.

See this video for more clarity.

Override Mask Transparency

By default, the mask will be applied with the same transparency value as the clipping element. For example, if the clipping element has a transparency of 50%, the same value will be applied to the mask. Each element has its own transparency value. It is sometimes required to override the Mask transparency and apply the same value globally. Use the Override Mask Transparency to apply a mask transparency value globally.

Use the slidder to set the value.

Elevation Offset (m)

Use this option to adjust the Map layers elevation to align with the iModel whenever necessary.

Allow Model Under Map

Use this option to allow the display of the underground section of the iModel under the map layers.

By default, the map layers are displayed in the background, completely behind the iModel and reality data, so that the user sees the model in its entirety, even the parts that should be displayed under the ground. 

See this video for more clarity.

Terrain

The Terrain section contains options related to the display of the Cesium terrain layer.

Toggle ON the "Enable" option to activate the Cesium terrain layer and have a 3D view of the terrain surrounding the area of the iModel.

Model Height (m)

Use this option to adjust the terrain elevation so that it fits the model elevation.

Apply Elevation Correction

Sometimes the iModel is not displayed at the right elevation in Design Review. Most of the time this happens when the input design file was created with the wrong vertical datum; Ellipsoid instead of Geoid. So when the user turns ON the Cesium terrain, the elevation is incorrect. Another case is when the user has drawn his design at the right location but on a random elevation.
To correct the elevation

• None - Use this option when no correction is required. This is the default option.
• Geoid Separation - Use this option when the iModel has been created with the wrong vertical datum (Ellipsoid instead of Geoid).
• Terrain Elevation - Use this option to apply a correction with the Terrain Elevation. You can play with the Model Height option to adjust the elevation with more accuracy. 

Exaggeration 

Use this option to exaggerate the elevation of the Cesium terrain. 

General information on the types of services supported in the Map Layers widget and CORS policy

OGC WMS server and OGC WMTS server

Open Geospatial WMS Service and WMTS Service can also be attached to the iModel, through the Map Layers widget.

Note that WMTS is a complement to the WMS. As compared to the WMS, the main advantage of the WMTS is that it offers better performances in the publishing of cartographic data, as the tiles are stored in a cache.  On the other hand, the WMTS is not recommended when the data is updated frequently, as the cache will have to be regenerated again and again.

General information - CORS (Cross-Origin Resources Sharing) Policy

For security reasons, many servers are configured to let specific client’s site to connect to them and access their resources. It is most possible that when you attach a layer and the server is not configured properly to let you in, you will end up with a CORS error sent by the browser. To solve this, the remote web services need to have the "Access-Control-Allow-Origin" Header to be configured for the following origin values:

Origins	URLs
Bentley CONNECT Portal	https://connect-imodelweb.bentley.com
iTwin Design Review Hub	https://review.itwin.bentley.com
iTwin Hub	https://itwin.bentley.com
SYNCHRO Control	https://construction.bentley.com/

Also, if authentication is required, the ‘Access-Control-Request-Headers’ needs to be configured to accept the ‘Authorization’ value.

For more information on the CORS policy, please contact your IT team.