NOTE: As of HOOPS Visualize v20.00, 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.
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:
During start-up, when HOOPS/MVO finds the RealDWG HIO component in your application's path, it will perform the following steps:
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.
RealDWG 2013 and 2014 integration is supported for Windows 32 and 64 bit operating systems using Visual Studio 2010 only. The project file for RealDWG 2013 is hio_dwg2_vc10. The project file for RealDWG 2014 is hio_dwg2_2014_vc10. If you want to use RealDWG 2014, you have to build the project (see 1.2 Rebuilding the HIO Component).
The RealDWG HIO component was built 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. However 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.
The following instructions pertain to RealDWG 2014, but may be used for other recent versions. In order to build the hio_dwg2_2014_vc10 project, you will need to have the following environment variables set up:
REALDWG_2014_SDK_DIR - pointing to the installation dir of 32bit RealDWG
or
REALDWG_2014_SDK_DIR_X64 - pointing to the installation dir of 64bit RealDWG
When built, the project will create a .hio file and place it in <hoops_dir>/bin/<platform>/hio_plugins/hio_dwg2_2014
The name of the .hio file will be hiodwg2_2014_<version><d_flag>.hio. Copy this file to the hio_plugins directory.
All entities found in RealDWG are supported by HOOPS Visualize except for:
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:
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.
During the im-port 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 can be modified using Set_Text_Font.
The ReadDWG HIO component does not import custom AutoCAD fonts (.shx), since RealDWG does not provide any APIs to decode such fonts. DWG text that is specified to use such fonts will also be drawn with the default HOOPS Visualize font.
Within HOOPS/MVO, a variety of input options available to facilitate the importing process. For instance, you can determine how DWG visualization information is represented in the HOOPS Visualize scene graph with options like HInputHandlerOptions::m_Deviation and HInputHandlerOptions::m_numIsolines.
The HInputHandlerOptions::m_Deviation is the maximum allowable difference in world space between the true mathematical surface being imported and the tesselated surface that will be rendered in HOOPS Visualize. For instance, if the deviation is set to 1.0, the surfaces in HOOPS Visualize would be comparatively more tesselated than if the deviation was the default value of 10.0. Specifying a value for HInputHandlerOptions::m_numIsolines option lets you determine the number of isolines for surfaces like cylinders, spheres and tori. Setting this option to zero will suppress isolines.
In addition to settings that help determine the representation of your visualization data, there are also options for importing metadata. When the HInputHandlerOptions::m_bImportMetadata flag is set to true, the xdata, including entity, layer and group names, found in your DWG file are imported as user options attached to the associated segment. Some DWG files have large amounts of xdata. Consequently, you might want to load only the metadata that is relevant to your application. To do this, you can populate the HInputHandlerOptions::m_listRegAppNames with a list of registered application names. Thus, only metadata associated with these registered applications are imported. Note that HInputHandlerOptions::m_listRegAppNames is only applicable when HInputHandlerOptions::m_bImportMetadata is true.
For some users, information of interest in a RealDWG is the handle id information associated with every database-resident DWG entity. These handle ids are persistent from session to session. To import handle ids, set the HInputHandlerOptions::m_bAttachDWGHandles flag to true. This will tell HOOPS Visualize to import the handle ids as user options and attach them to the associated segment.
Along with metadata information and handle ids, wireframe representations for BREP solids can also be imported. To do this, set the HInputHandlerOptions::m_bImportWireframeForBrep flag to true. The default value for this flag is false.
In RealDWG, models often come with one or more layouts. This information could be useful or even crucial when importing to HOOPS Visualize. To enable the importation of layouts, set the HInputHandlerOptions::m_bImportAllLayouts to true. When this flag is enabled, HOOPS Visualize imports all Model_Space and Paper_Space layouts. Model_Space will have visibility enabled while all other layouts will have visibility set to off. If you have only interested in importing a limited number of layouts, you can list them in HInputHandlerOptions::m_listDWGLayouts. HOOPS Visualize will then only import those layouts. Note that if you have HInputHandlerOptions::m_bImportAllLayouts enabled, this will override your HInputHandlerOptions::m_listDWGLayouts list.
When a DWG file is imported into the HOOPS Visualize database, the DWG file is opened using the RealDWG toolkit. As the DWG file is being read, Visualize imports the data into its database. For DWG files with a large number of SOLID3D entities, simultaneously reading and importing can consume a significant amount of memory causing your application to appear unresponsive to user interaction. For this situation, HOOPS Visualize offers the HInputHandlerOptions::m_bInputViaHSF option. When this flag is set to true, Visualize imports DWG files in the following way:
Whenever there is an xref, a new hsf file is created. As a result, there is a one to one mapping between the DWG files and the HSF files. HOOPS Visualize will attempt to remove any cyclical references and resolve missing locations for any xrefs that are found.
When there is a request to import a DWG file, and HOOPS Visualize finds that the file has already been imported via HSF, it will compare the timestamp of the HSF file with the DWG file. If the HSF file's timestamp is later, HOOPS Visualize will forego re-importation. To force reimportation of a DWG file, set the HInputHandlerOptions::m_bForceReimport flag to true.
The HOOPS RealDWG imported implements the progress and error importing interfaces. Thus, during importation, you can poll using HInputHandler::GetInputProgress to get the current progress information or register as a callback to get this information via HInputHandler::SetInputProgressNoticeCallback.
The following code sample shows how you can set options for the HIOUtilityDWG input handler.
HInputHandlerOptions dwg_input_options; dwg_input_options.m_pExtendedData = (void*) p_dwg_textures_dir; //Importing DWG information into an HSF file before loading it into the Visualize database dwg_input_options.m_bInputViaHSF = true; //Setting the amount of tesselation for imported surfaces dwg_input_options.m_Deviation = 10; dwg_input_options.m_bImportMetadata = true; //Creating a list of registered applications for metadata importation. char* XDataNames[] = { "CPM", "CPD1", "CPD2", "CPD3", "CPD4", "CPD5", "CPD6" }; for(int x = 0;x<_countof(XDataNames);x++) vlist_add_last(dwg_input_options.m_listRegAppNames,(void*)XDataNames[x]); dwg_input_options.m_pHBaseView = view; view->GetModel()->Read(FileName, 0, true, &dwg_input_options);
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 or manipulate the extensive information found in DWG files or utilize the full range of the RealDWG library services, you will require a tighter integration than what the RealDWG HIO component can provide - you need to integrate directory with RealDWG. To do so, follow these steps:
Before you begin integrating directly with the RealDWG libraries, we recommend that you ensure that have licensed and installed the RealDWG Toolkit on your system. To proceed with the integration, follow the steps below:
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 next section demonstrates how to instantiate the input handler and import a DWG file.
The process for importing a DWG file is similar to the process for importing other file types through the HIO interface. For example, to import DWG data into the model segment, you could use the following code:
HInputHandler * dwg_handler = HDB::GetHIOManager()->GetInputHandler("dwg"); if (dwg_handler) { // import DWG file into model segment HFileIOResult result = dwg_handler->FileInputByKey("filename.dwg", m_pHView->GetModelKey(), NULL); if (result == HIO_OK) // file loaded OK else // handle error } else // handle error
Although it is possible to recompile the HIO RealDWG input handler, you can only have one RealDWG handler in your application. If you compile a second handler, you should delete the old one - otherwise, the behavior is undefined.
Upon import, the HIO RealDWG component will create the following scene graph:
In the insertion segment, there's a user option called "importer version". If the value is 2, DWG2 was used to load this file. Additionally, there is a value indicating the HOOPS Visualize version, as well as a value for the file loading time in seconds.
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:
When associating handles to keys, keep the following in mind:
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:
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):
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:
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());
This function returns a DWG handle associated with a HOOPS Visualize key. Causes hash to be regenerated.
Sample usage:
void * kernelEntity = connector->GetKernelEntity(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);
Same as GetKernelEntity
Adds a connection between a key and a handle. Does not cause the has to be regenerated.
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.
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.
Each DWG entity may can have associated XDATA. The DWG standard calls metadata XDATA. Metadata can be of any type. If a DWG file contains metadata, HOOPS Visualize will create a subsegment under the main DWG model segment called xdata. The xdata segment will contain subsegments that correspond to metadata stored in the file. The name of each subsegment corresponds to the value of the DWG entity handle to which the metadata applies. The image below shows an example segment tree showing the xdata segment and subsegments which contain metadata.
The subsegment 0x00000074 indicates the metadata in this segment belongs to DWG entity with the same handle value. In this case, USER DATA indicates that there are two types of metadata present for this entity. These types are 1000 and 1001. The child segment "restype XXXX" contains the metadata values themselves. For an example of how to read metadata from an XDATA segment tree, see the code sample in get_xdata.cpp.
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 within layouts can be in an 'active' or 'inactive' state. RealDWG doesn't provide any mechanism to find which viewports are active.
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:
Occassionally, RealDWG will incorrectly read a linetype. For example, a line may appear continuous when it really should appear dashed. This is a confirmed bug in RealDWG recognized by Autodesk. The bug happens because the DWG libraries will cull details in order to optimize a drawing when the view distance is sufficiently far. However, when loading a file, RealDWG incorrectly provides the culled version of the entity instead of the actual verion.