=====================
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 <http://www.opendesign.com>`_ 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:

#. Create a *hio_plugins* directory in your application's working directory.  
#. 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).
#. Ensure that the DGNdirect libraries are installed on your system and in your path.
#. 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:

#. Load in the necessary DGNdirect libraries. 
#. Create the appropriate input handler.
#. 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 :ref:`Integrating Directly with DGNdirect <prog_guide/hio/HIO_DGNIntegration: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:

.. code-block:: none

	<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 
 
4. Add 'HIO_DGN' to your preprocessor declaration list. 
5. 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.
	
6. 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):

.. code-block:: none

	$(DGN_TEIGHA_DIR)\lib\<platform/version> 
  
7. 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 :doc:`File Input/Output and the I/O Manager </prog_guide/mvo/04_hio_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();
