• Technical Overview
  • Release Notes
  • Reference Manual
  • HOOPS Visualize
TechSoft3d

HOOPS RealDWG Integration

1.0 Using the RealDWG HIO Component

  • 1.1 Supported Platforms and Versions
  • 1.2 Rebuilding the HIO Component

2.0 Unsupported Entities

  • 2.1 DWG Units
  • 2.2 DWG Font Handling

3.0 Integrating Directly with RealDWG

4.0 Mapping Between HOOPS/3dGS and DWG Entities

5.0 Limitations


NOTE: As of HOOPS Visualize v19.37, the original RealDWG HIO component has been refactored into a more robust interface called HIO DWG2. The content on this page refers to HIO DWG2. If you need to use the original interface for legacy reasons, documentation can be found here.

1.0 Using the RealDWG HIO Component

The RealDWG libraries are the only native DWG/DXF read/write libraries supplied by Autodesk. To use this integration, developers are required to license the RealDWG Toolkit. Please contact a Tech Soft 3D representative for licensing details.

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

  1. Create a hio_plugins directory in your application's working directory.
  2. Copy the hio_dwg.hio file found in /bin/<platform>/hio_plugins/hio_dwg to the hio_plugins directory created in the previous step.
  3. Ensure that the RealDWG SDK is installed on your system and in your path.
  4. Run your application.

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

  1. Load in the necessary RealDWG libraries.
  2. Create the appropriate input handler.
  3. Register this handler and the associated file extensions to the HIOManager.

To utilize the extensive services available in the RealDWG toolkit, you must compile against the RealDWG libraries directly and follow the steps described in 4.0 Integrating Directly with RealDWG.

1.1 Supported Platforms and Versions

The RealDWG integration is supported for Windows only. For users of RealDWG 2013, Visual Studio 2010 is the supported compiler. For users of RealDWG 2012, Visual Studio 2008 is the supported compiler. The project file for RealDWG 2013 is hio_dwg2_vc<version>.

1.2 Rebuilding the HIO Component

The RealDWG HIO component was built against against a specific version of RealDWG. If you want your application to run against another version of RealDWG, we recommend that you rebuild the RealDWG HIO component with that version of the library. To do so, simply open the hio_dwg_vc<version>.vcproj project located in the <hoops>/Dev_Tools/hoops_hio/hio_dwg/source. Be sure to set the RealDWG environment variable to point to the root of your RealDWG installation before you begin building. The environment variable has the form:

REALDWG_20XX_SDK_DIR - for 32 bit systems

or

REALDWG_20XX_SDK_DIR_X64 - for 64 bit systems

...where XX corresponds to the version of RealDWG you are using. For example, if you are using RealDWG 2013 on a 64 bit machine, the environment variable would be REALDWG_2013_SDK_DIR_X64. When built, the project will create a .hio file and place it in <hoops_dir>/bin/<platform>/hio_plugins/hio_dwg2_2013. The name of the .hio file will be hiodwg2_2013_<version><d_flag>.hio. Copy this file to the hio_plugins directory.

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


2.0 Unsupported Entities

All entities found in RealDWG are supported by HOOPS Visualize except for:

  • AcDbWipeOut
  • Custom Line Pattern

2.1 DWG Units

When a RealDWG model is imported into HOOPS Visualize, the model units are also imported. As of HOOPS Visualize version 19.01, this information can be found in the "model_information" segment under the model key as a Visualize 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:

  • Inches
  • Feet
  • Miles
  • Millimeters
  • Centimeters
  • Meters
  • Kilometers
  • Microinches
  • Mils
  • Yards
  • Angstrom
  • Nanometers
  • Microns
  • Decimeters
  • Dekameters
  • Hectometers
  • Gigameters
  • Astronomical
  • Light Years
  • Parsecs
  • Undefined Units

For backward compatibility with HOOPS Visualize versions prior to 19.01, the DWG units information is also stored in a segment underneath the model key, called "info", and is stored in the "dwg_unit" User_Option.

2.2 DWG Font Handling

During the import of a DWG that contains text, any fonts specified in the DWG file must be on the system because fonts can not be embedded in a DWG file. If the importer does not find the given font, the text will be drawn with the default HOOPS Visualize font. This behavior can be modified using Set_Text_Font.


3.0 Integrating Directly with RealDWG

The RealDWG HIO component allows developers to easily import visualization information into the Visualize database. However, DWG files also contain more than just visualization information. If your application needs to access/manipulate the extensive information found in DWG files and/or utilize the full range of the RealDWG library services, you will require a tighter integration than what the RealDWG HIO component can provide.

  1. Install the RealDWG toolkit on your system.
  2. Set the environment variable appropriately based on your version of RealDWG as mentioned in section 1.2. It should point to the root of your RealDWG installation. For this example, REALDWG_2013_SDK_DIR_X64 is used.
  3. Add files HIOUtilityDWG.h/.cpp and HDWGHelper.h/.cpp to your project. These files are located in the Dev_Tools/hoops_hio/hio_dwg/source directory of your HOOPS Visualize installation.
  4. Add the following directory paths to your additional include folders' list $(REALDWG_2013_SDK_DIR_X64)/include.
  5. Add HOOPS_DWG_IO to your preprocessor declarations.
  6. Add $(REALDWG_2013_SDK_DIR_X64)/lib to your additional linker directories.
  7. Add the following files as additional dependencies:
    • rcexelib.obj
    • acgiapi.lib
    • acdb17.lib
    • acge17.lib
    • rxapi.lib
    • acismobj17.lib
    • odbc32.lib
    • odbccp32.lib
    • urlmon.lib
    • wininet.lib
  8. Ensure that the $(REALDWG_2013_SDK_DIR_X64) is included on your path.

Once you have completed the above steps, you do not need to rely on the RealDWG 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 HIOUtilityDWG via HIOManager::RegisterInputHandler so that the HBaseModel::Read function can recognize that the .dwg file format is supported. For more information on HOOPS/MVO file input/output architecture, please see section 4.0 File Input/Output and the I/O Manager of the HOOPS/MVO Programming Guide.

Now you can begin working with HIOUtilityDWG class which is HOOPS/MVO's input handler for RealDWG. The code sample below shows how to instanciate the input handlers and import a DWG file.

HIOUtilityDWG dwg_reader;
HFileInputResult result = dwg_reader.FileInputByKey("c:\\temp\\myFile.dwg", m_pHView->GetModelKey(), NULL);


4.0 Mapping Between HOOPS/3dGS and DWG Entities

Each DWG entity has a unique handle associated with it. The handle is unique within the database, and is the same session after session. The handle is represented by an unsigned 64-bit integer. Handles exhibit the following relationships:

  • One DWG handle corresponds to one or more HOOPS Visualize keys.
  • One Visualize key corresponds to only one DWG handle.
  • Two different DWG handles cannot refer to the same Visualize key.

When associating handles to keys, keep the following in mind:

  • every time a piece of Visualize geometry is inserted, it is opened by key, and a user option containing the DWG handle identifier this piece of geometry belongs to is set on it.
  • a segment called "handles" is created during import and placed directly under the MVO model segment.
  • as geometry is read in, a reference to it is placed in a subsegment of the "handles" segment, named after the DWG handle the geometry belongs to.

To relate a DWG handle to a HOOPS Visualize key, you would do the following:

Case A - You have a HOOPS Visualize key and wants to obtain the related DWG handle:

  1. Open geometry by key
  2. Use Show_One_User_Data to read the data stored at index 0
  3. The data returned by Show_One_User_Data will contain the DWG handle.

Example:

Adesk::UInt64 handle;
HC_Open_Geometry(key);
HC_Show_One_User_Data(0, &handle, sizeof(handle);
HC_Close_Geometry();

Case B - You have a DWG handle and want to obtain the related HOOPS Visualize key(s):

  1. Open the "handles" segment and search for the segment whose name matches the DWG handle.
  2. Search the segment for reference geometry, and obtain its original key

Using a hash to improve speed

Starting with Visualize 19.33, the developer has the option to query DWG handles in an optimized way. The process described in the previous section will always work, however, for large scene graphs, the processing time can be long. Using the HIO connector to associate DWG handles to Visualize keys is faster because it uses a hash lookup instead of searching the segment tree. There is a performance penalty, however, when the hash is generated.

This is how to obtain a connector:

HInputHandler * handler = HDB::GetHIOManager()->GetInputHandler("dwg");
handler->FileInputByKey("filename.dwg", view->GetModelKey(), options);
HIOConnector * connector = HDB::GetHIOManager()->CreateConnector("dwg"); 

All the associated functions (see list, below) have an optional parameter at the end. Passing the model key as that parameter causes the hash to be generated (or regenerated, if the geometry has been modified). Therefore, the first time you use this hash, you should always pass the model key.

The DWG connector can use the following functions:

  1. HC_KEY GetHoopsEntity(void * pKernelEntity, HC_KEY modelKey = INVALID_KEY);

    This function returns a HOOPS Visualize key associated with a DWG handle. Causes hash to be regenerated.

    Sample usage:

    unsigned int handle = 570;
    HC_KEY key = connector->GetHoopsEntity((void *)handle, view->GetModelKey()); 
    

  2. void * GetKernelEntity(HC_KEY key, HC_KEY modelKey = INVALID_KEY);

    This function returns a DWG handle associated with a HOOPS Visualize key. Causes hash to be regenerated.
    Sample usage:

    void * kernelEntity = connector->GetKernelEntity(key); 
    

  3. bool GetHoopsEntities(void * pKernelEntity, vlist_s *ret_HoopsKeysList, HC_KEY modelKey = INVALID_KEY);

    Same as GetHoopsEntity, but is used in the case when a DWG handle is associated with more than one Visualize key. Causes hash to be regenerated.
    Sample usage:

    vlist_s * hoopsKeyList = new_vlist(malloc, free);
    connector->GetHoopsEntities((void *)myHandle, hoopsKeyList);
    void * item  = vlist_nth_item(hoopsKeyList, 0);
    void * item2 = vlist_nth_item(hoopsKeyList, 1);
    

  4. bool GetKernelEntities(HC_KEY key, vlist_s *ret_KernelEntitiesList, HC_KEY modelKey = INVALID_KEY);

    Same as GetKernelEntity

  5. void AddConnection(HC_KEY key, void* pKernelEntity, HC_KEY modelKey = INVALID_KEY);

    Adds a connection between a key and a handle. Does not cause the has to be regenerated.

Layers and Layouts

Layers are treated as attribute containers. Whatever attributes are in the layer are applied to the geometry with a HOOPS Visualize style. This means that you can open the layer segment and override the attributes. If the geometry has attributes set on it explicitly, then the explicit attributes override the layer attributes. There's a case when the attributes of geometry are inherited from the block reference. Those attributes cannot be overridden by the layer. The layers can be found in the segment "layer table". The layers are URI encoded, to allow unicode characters in the segment names, and are prefixed with an underscore '_' character.

Layouts can be found in the "layouts" segment. The layouts are also URI encoded and prefixed with an underscore. Each layout has user options, "extents_min" and "extents_max" set defining the extents in 2D space. Each layout also sets the heuristic "exclude bounding" and sets the visibility to "off" except for the currently active/visible layout. The currently active/visible layout does not set visibility and does not set the exclude bounding heuristic. Iterating the visibility of the layouts is done by finding the layout that does not set the visibility, then setting the visibility to off, setting the exclude bounding heuristic, then moving on to the next layout segment and unsetting the visibility and unsetting the heuristics.

Object Enablers

HIO DWG2 allows developers to use object enablers starting with Visualize v19.33. Using object enablers, customers can load DWG files which contain custom entities defined in their own .dbx files.

The only requirement for this to work is that the developer must place the .dbx files and associated DLLs into the same folder as the HIO DLL, so that they can be loaded when DWG2 starts up.

5.0 Limitations

Dimensions, annotations, and layouts

It is possible for a DWG file to be stored with uninitialized annotations and layouts. These uninitialized structures don't always exist in the DWG file. In this situation, RealDWG returns them as null pointers. Using its own internal logic, AutoCAD is able to load the uninitialized structures from null pointers, however, Visualize cannot. Therefore, we do not support uninitialized annotations or layouts.

Viewports

Viewports within layouts can be in an 'active' or 'inactive' state. RealDWG doesn't provide any mechanism to find which viewports are active.

Rendering

Although we make every effort to duplicate the rendering results of any file loaded using RealDWG, Visualize cannot exactly match AutoCAD in all cases when it comes time to actually draw. AutoCAD uses its own proprietary rendering engine that handles geometry in its own way. Some examples of differences we have noticed include:

  • tessellation values
  • line weights and line styles
  • font handling