HOOPS DGN integration

Using the DGN HIO Component

DGN is the file format for Bentley’s Microstation product. Bentley has published the specification of the DGN formation and worked with the Open Design Alliance to create the DGNDirect SDK. This SDK enables developers to read/write valid DGN files. To use this integration, developers are required to license and install DGNdirect on their systems. To gain access to the DGNDirect library you need to join the Open Design Alliance. Details on how you would become a member can be found on their website.

To use the HOOPS/HIO component for DGN, please follow the steps below:

  1. Create a hio_plugins directory in your application’s working directory.

  2. Copy the hio_dgn.hio file found in [hoops]/bin/[platform]/hio_plugins/hio_dgn to the hio_plugins directory created in the previous step (substitute [version] for whatever version of Visualize you are currently working with).

  3. Ensure that the DGNdirect libraries are installed on your system and in your path.

  4. Run your application.

During start-up, when HOOPS/MVO finds the DGNdirect HIO component in your application’s path, it will perform the following steps:

  1. Load in the necessary DGNdirect libraries.

  2. Create the appropriate input handler.

  3. Register this handler and the associated file extensions to the HIOManager.

Once the DGNdirect HIO component is successfully loaded, your application will be able import DGN files without having to recompile HOOPS. To utilize the extensive services available in the DGNdirect libraries, you must compile against the DGNdirect libraries directly and follow the steps described in Integrating Directly with DGNdirect.

Rebuilding the HIO Component

The DGNdirect HIO component was built against a specific version of DGNDirect. The specific version can be found in the HOOPS Visualize release notes compatibility table. If you want your application to run against a version of DGNdirect, we recommend that you rebuild the DGNdirect V2 HIO component with that version of the library. To do so, simply open the hio_dgn_vc[version].vcxproj project located in the <hoops>/Dev_Tools/hoops_hio/hio_dgn/source. Be sure to set the environment variable DGN_TEIGHA_DIR to point to the root of your DGNDirect installation before you begin building. Once the project is built against the correct libraries, an .hio file will be created.

Note that you may face some obstacles building against a different version of the DGNdirect if interfaces are not compatible with the original libraries that the HIO component was built against.

Supported Entities

The following is a list of DGN elements that are supported by HOOPS:

  • Lines

  • Ellipses

  • Shapes

  • Meshes

  • Cell header

  • Feature solid

  • Smart solid

  • Plain solid

  • Surface

  • Cone

  • NURBS curve

  • NURBS surface

  • Text

  • Shared cell

  • Cell Header

  • Line string

  • Arc

  • XRef

The following DGN entities are not supported by HOOPS:

  • Dimension

  • Texture

  • Raster images

No explicit meta data is imported. However, the importer takes cell header label,”cellheader3d_<elmID>”, and applies it to child segments as user options.

DGN Units

When a DGN model is imported into HOOPS, the model units are also imported. This primary units info can be found in the “model_information” segment under the model key as a HOOPS user option called “cad units”. For example, if the user option value is “cad units = Inches”, this means that one unit length of the imported entity is equivalent to one inch. The possible units are as follows:

  • Meters

  • Undefined units

HOOPS Visualize imports and stores additional DGN-specific units information. One such piece of info is called WorkingUnit, which is stored as a User_Option in the ‘model_information/unit_information’ subsegment. The possible values for WorkingUnit are:

  • UnitOfResolution

  • StorageUnit

  • WorldUnit

  • MasterUnit

  • SubUnit

  • UndefinedUnits

Additional subsegments related to the above units information are also created. The segment names (paths) are:

  • model_information/unit_information/storage_unit

  • model_information/unit_information/master_unit

  • model_information/unit_information/sub_unit

In each subsegment above, the following user options are all set:

  • Base (possible values are ‘kMeter’ or ‘kNone’)

  • System (possible values are ‘kCustom’ , ‘kEnglish’ or ‘kMetric’

  • Nominator

  • Denominator

Developers interested in obtaining further details about the original DGN units properties should refer to the DGN format documentation included in the DGNDirect SDK.

Input Handler Options

During import, the DGN HIO component automatically imports a variety of entities for visualization. The DGN file format additionaly includes cell headers which have information about different color and layers. You can bring cell header information into the HOOPS database by setting the HInputHandlerOptions::m_iDGNCellHeaderOption member variable.

HInputHandlerOptions::m_iDGNCellHeaderOption takes one of three enumerated values. If you set the flag to SINGLE_ENTITY_CELLHEADER, Visualize will create one segment for each cell header element regardless of whether the cell header has any children with different colors and levels. This segment will have the color and level of the first child of the cell header. We recommend that you use this option when your cell header’s children have the same color and are on the same level.

If you set HInputHandlerOptions::m_iDGNCellHeaderOption to BREAK_CELLHEADER, Visualize will create one segment for each child of each cell header. A child’s color and level hierarchy will be maintained. As elements of a cell header can be on different levels, the cell header name is set as a user option.

Finally, if you set HInputHandlerOptions::m_iDGNCellHeaderOption to OPT_CELLHEADER, Visualize will import all cell elements into one segment but it will still maintain individual colors. By default, HInputHandlerOptions::m_iDGNCellHeaderOption is set to SINGLE_ENTITY_CELLHEADER.

With the input handler options, you can also control whether layers or entities that are not visible should be imported by setting the HInputHandlerOptions::m_bIgnoreOffLayer and HInputHandlerOptions::m_bIgnoreOffEntity input handler options, respectively.

Additionally, you can control how entities are tesselated in Visualize by setting the HInputHandlerOptions::m_coneFactor and HInputHandlerOptions::m_factorForSmartSolids input handler options.

DGN models often have a location in world space. If you want to preserve their spatial relationships, you can enable the HInputHandlerOptions::m_bDGNRebaselineModel flag.

Integrating Directly with DGNdirect

The DGNdirect HIO component offers the ability to load in DGNdirect visualization information. For application developers who want to leverage the full range of features in DGNdirect libraries, we recommend that you integrate directly with the DGNdirect libraries.

Before proceeding, make sure that the DGNdirect libraries are installed on your system and in your application’s path. Please follow the steps below to enable direct integration with DGNdirect:

  1. Set the DGN_TEIGHA_DIR environment variable to point at the root of your DGNDirect installation.

  2. Add HIOUtilityDGN.h, HIOUtilityDGN.cpp and HDGNHelper.h and HDGNHelper.cpp to your project. These files are located in the Dev_Tools/hoops_hio/hio_dgn/source directory of your HOOPS installation.

  3. Add following directories in your include path:

<HOOPS_DIR>\Dev_Tools\hoops_3dgs\source
<HOOPS_DIR>\Dev_Tools\hoops_mvo\source
<HOOPS_DIR>\Dev_Tools\utility\source
$(DGN_TEIGHA_DIR)\TG\Include
$(DGN_TEIGHA_DIR)\TD\Include
$(DGN_TEIGHA_DIR)\TG\Extensions\ExServices

  1. Add ‘HIO_DGN’ to your preprocessor declaration list.

  2. The DGN Importer has a dependency on the hoops_utils library and so if you have not already done so you should:

    • add [HOOPS]\Dev_Tools\utility\include to your include path

    • add [HOOPS]\Dev_Tools\utility\lib\nt_<platform>_vc<vs_version> to your link path

    • add hoops_utilsstat_md.lib (release) or hoops_utilsstatd_md.lib (debug) to your link dependencies.

  3. Add the following directory to your link path (Note that this path may be different depending on whether you want to link against DLL or static libraries and/or release or debug libraries):

$(DGN_TEIGHA_DIR)\lib\<platform/version>

  1. Add following dependencies to the linker settings: hoops_mvo_mgk.lib, hoops.lib, hoops_utilsstat_md.lib, TG_Db.lib, TG_Dgn7IO.lib, TG_ModelerGeometry.lib, PSToolkit.lib, TD_Alloc.lib, TD_Root.lib, TD_Ge.lib, TD_Gi.lib, TD_Gs.lib, TD_DbRoot.lib, TD_ExamplesCommon.lib, TG_ExamplesCommon.lib, RasterProcessor.lib, WinBitmap.lib, oless.lib, WinOpenGL.lib, Rpcrt4.lib, opengl32.lib, RxRasterServices.lib, ModelerGeometry.lib, glu32.lib, zlib.lib, TD_Br.lib, tinyxml.lib, WinGDI.lib, WinDirectX.lib, TD_BrepRenderer.lib, TD_AcisBuilder.lib, TG_DwgDb.lib, TD_Db.lib, TD_SpatialIndex.lib, sisl.lib

Once you have completed these steps, you do not need to rely on the DGNdirect HIO component anymore. Please remove the associated .hio file from the hio_plugins directory in your application’s working directory. Note that in a direct integration, you must register HIOUtilityDGN via HIOManager::RegisterInputHandler so that the HBaseModel::Read function can recognize that the .dgn file format is supported. For more information on HOOPS/MVO file input/output architecture, please see section File Input/Output and the I/O Manager of the HOOPS/MVO Programming Guide.

The DGNDirect libraries are static. Once you have successfully completed the step above, you should be able to read DGN files into your application with the following code:

// We first must initialise the DGN toolkit.  Note, initialising the DGN toolkit does not need to
// be done if you have already registered the toolkit with the IO Manager and are requesting the HIO
// Manager to supply you with a DGN File I/O object
DgnTkInit(DGN_LIB_VERNO, false);

HC_Open_Segment_By_Key(m_pHView->GetModelKey());
  HIOUtilityDGN dgn_reader;
  HFileInputResult result = dgn_reader.FileInputByKey("c:\\my_models\\BikeFrame.dgn", m_pHView->GetModelKey(), NULL);
HC_Close_Segment();

// Now shut down the DGN Toolkit
DgnTkEnd();