Overview
This article is meant to offer guidance on how to work with MicroStation DGN files in Autodesk Platform Services (APS). DGN is one of the formats supported by APS in the Model Derivative service, usually generated from Bentley Systems MicroStation.
We will cover this content related to the visualization of DGN files and how we can parse properties.
- Overview
- Uploading a DGN in OSS
- Translating a DGN file
- Translate and extract linkage data
- Visualize a DGN file in the Viewer
- Find the extracted linked data
- Creating a DGN linkage properties extension
- Selecting objects
- Get Help
It is easy to check how your DGN design file looks in 3D in the browser, uploading it to the generic online tool at viewer.autodesk.com. And for a better experience including customizations with APS, please continue reading.
DGN files on Autodesk Platform Services Viewer
Uploading a DGN in OSS
As part of APS, Data Management API provides a unified and consistent way to access data across Autodesk cloud storage. One of them is the Object Storage Service (OSS), the simpler storage option meant specifically for developer accounts. This allows your application to download and upload raw files in Buckets and be able to translate and visualize them.
In the APS Developer Portal, you will find tutorials in the documentation for this process step by step:
Translating a DGN file
Model derivative is the service that enables us to represent and share designs in different formats, as well as to extract valuable metadata, and DGN is one of the formats supported.
The basics about Model Derivative can be found in the online documentation here. In order to visualize a DGN file in the Viewer, we need to translate and convert it to SFV or SVF2. SFV2 is the latest version of this format, that is optimized for big models where similar geometry is repeated in the CAD file. Because of this optimization, SVF2 format greatly reduces the viewable storage size and speeds up the loading and viewing performance in the browser.
When we want to translate a DGN file to SFV/2, we can follow the tutorials we will find in the documentation:
- Prepare a File for the Viewer
- Extract Metadata From a Source File
- Extract Geometry From a Source File
The tutorial steps can be tested using a Postman or Insomnia collection.
Translate and extract linkage data
When translating to DGN, the geometry, hierarchy of items, properties and metadata are extracted and are available to be queried when translated to SVF/2. But it may happen, that MicroStation third-party plugins, may store extra data information in binary blobs inside the DGN file. This is why the Autodesk translation team released an advanced option specific to DGN files that allows you to extract this binary data, linked to a specific 3D object inside the file and used by third party plugins to store extra metadata directly in DGN files.
Following the model derivative tutorials mentioned above, this option is found in:
POST job documentation, on ‘Request’ description -> ‘Body Structure’ -> ‘Attributes that Apply to SVF or SVF2 Outputs’ -> ‘Case 2 - Input file type is DGN’.
When expanding the advanced options, we find ‘requestedLinkageIDs’, parameter that allows us to extract this third-party linkage data in the resulting SVF or SVF2 file. Please see next Figure.
Model derivate new advanced parameters
Although we will be able to fetch this binary data, the plugin distributor may encode the data in a specific way. That means later we will need to parse it and unencode it. We will also need to know which LinkageID(s) the third party plugin is using, which can be provided by the developer of the plugin. For example, LuArtX builds plugins that store CARF data, and while talking with them we now know they use:
- Linkage ID 1002, used for schema objects (means 2D objects, labels, 2d graphics)
- Linkage ID 1004, reserved for 3d modules and their corresponding 3d objects (i.e.. MEP, conveyor systems…)
- Linkage ID 1008, used for conveyor systems, storing simulation parameters.
At Task 3 from the tutorial, in Step 1, when translating the source file, we will modify the body of the POST request adding the ‘requestedLinkageIDs’ attribute. Note, that linkage data is by default not extracted if you do not specify this attribute. Remember that the POST job end-point url changes depending on the region, US or EMEA.
For our purpose, our BODY Structure in JSON format will look like as follows:
{
"input": {
"urn": "{{ossEncodedSourceFileURN}}"
},
"output": {
"destination": {
"region": "emea"
},
"formats": [
{
"type": "svf2",
"views": [
"2d",
"3d"
],
"advanced": {
"requestedLinkageIDs": [
1002,
1004,
1008
]
}
}
]
}
} The resulted Linkage data is stored in SVF/2 as a new property on the model items where thislinkage data was attached. The name of this new generated property has the name ‘Linkage_<Id Number>’.
Visualize a DGN file in the Viewer
The APS Viewer is a Javascript client that can be integrated in any web page and customized in your custom application. The basics of how to integrate it in a web page are explained in the documentation. The Viewer Essentials documentation includes how to add the Viewer to a HTML page, initialize the Viewer and load a Model. For our case with a translated DGN file, the process is the same as explained in the documentation.
In case we want to get code samples of how this is done using different programming languages, there are tutorials in https://get-started.aps.autodesk.com/. There is a section with the steps and code about how to setup the Viewer with Javascript, C# and .NET.
Find the extracted linked data
Using the ‘requestedLinkageIDs’ as described before, now we will find properties with the label ‘Linkage_xxxx’ ("Linkage_1002", "Linkage_1004"....) when selecting items in the Viewer, and exposing its properties. When the label value is too long, it may be that the label name only shows several characters in the UI of the Panel. Placing the mouse on it will extend the complete name. Consider that this chunk of data may not be human readable, because it has been stored and formatted in a specific way by the developer of the plugin. Once we know how to decode it, then we can easily develop an extension for the Viewer to read, parse and list the stored properties in the APS Viewer.
Linkage blob data in one of the geometry’s elements
The viewer comes with default tools built-in. These are the menu options that we find in the lower part of the UI. These tools are called extensions. An extension is Javascript code that extends or modifies the Viewer’s behavior. Each of these tools can be modified and extended with the Viewer APIs, allowing you to write your own extension. If you are not familiar how to build an extension for the Viewer, you can find the documentation here. And a more detailed step by step tutorial with sample code can be found here.
Viewer Extensions
Creating a DGN linkage properties extension
To show the properties correctly in a customized application where we are knowledgeable about the DGN lineage data, we can create a Viewer extension. In Figure 3, we parse the chunk of data attached to the selected geometry (encoded linkage data blob) and add the new properties or parameters to the property panel extension. The basic property panel is available by default in the Viewer when using the GUI version. While we could simply add this parsing logic in other places of the client-side or server-side code, it is a good practice to encapsulate any new viewer functionality into a viewer extension so that it is easy to share. We could also hide with this extension the Linkage property itself that we show in the Image just for demo purposes and show the properties in categories. Because this is a customizable Viewer extension, you can decide how best to show the data to your users.
A viewer extension is basically a subclass of Autodesk.Viewing.Extension (main.js) that overrides some of its lifecycle methods. Minimally, you need to extend the load and unload functions from the extension.
class DGNLinkageParsingExtension extends Autodesk.Viewing.Extension
If we want to extend the default Property that comeswith the Viewer, we will extend Autodesk.Viewing.Extensions.ViewerPropertyPanel and add our extra functionality. There is documentation about the property panel, and the following blog from the APS Developer Advocacy team explains more about it.
Selecting objects
Let’s remember that the linkage data in the DGN file is usually attached to a group node or item that doesn’t have to be the leaf node in the hierarchy. MicroStation may assemble many nodes or geometry as a group for the selection. By default the APS Viewer will select the leaf nodes of the model hierarchy. If we want to change this behavior, we can change it in the Viewer ‘Settings -> Configuration -> from ‘Leaf object’ to ‘Last object’.
Get Help
Please don’t hesitate to contact us at https://aps.autodesk.com/get-help if you have further questions, recommendations or requests for the use of DGN files.