HOOPS Exchange Integration

Using the HOOPS Exchange HIO Component

The HOOPS Exchange HIO component (HIO Exchange) supports both import and export capabilities. For import, it utilizes the capabilities of HOOPS Exchange to access assembly, tessellation, and PMI information from many MCAD formats and bring it into the HOOPS/3DGS scene-graph. A full list of the supported HOOPS Exchange formats is detailed here. Before reviewing the specifics of this component, developers should become familiar with the general HIO architecture and capabilities, covered in this section of the HOOPS/MVO Programming Guide.

For export, the component supports exporting the HOOPS/3DGS scene graph information to IGES, STEP, Parasolid, and STL. (The scene-graph can also be exported to the PRC format, which is the native 3D representation used within PDF. Exporting to a 3D PDF requires a license to the HOOPS Publish product.)

The HIO Exchange component is delivered in the form of a .hio file, which gets dynamically loaded by the HOOPS/MVO file import logic. To ensure your application can access the hio_exchange component, perform the following:

Windows:

  • Create a hio_plugins directory in your application's working directory.
  • Copy the hioexchange<version>.hio file found in <hoops>/bin/<platform>/hio_plugins/hio_exchange to the hio_plugins directory created in the previous step.

Linux:

  • Copy the hioexchange<version>.hio file found in <hoops>/bin/<platform> into your application's working directory.

Additionally, ensure the HOOPS Exchange DLLs are in your environment path. During start-up, when HOOPS/MVO finds the HIO Exchange component and HOOPS Exchange DLLs, it will perform the following steps:

  1. Create the appropriate input and output handler.
  2. Register the handler and its associated file extensions with the HIOManager.

Once the hio_exchange component is successfully loaded, your application will be able to import any of the files supported by HOOPS Exchange. To utilize the extensive HOOPS Exchange API services, you must compile against HOOPS Exchange directly.

Importing Examples

Reading a file involves setting up the HInputHandlerOptions structure with a valid HOOPS Exchange license key and HBaseView object, and then loading the model into the desired HOOPS Visualize scene-graph segment by calling HBaseModel::Read. The following shows how you would import a CATIA file:

#include "HIOManager.h"
HFileInputResult result = InputOK;
HInputHandlerOptions input_options;
// set up the input options with a HOOPS Exchange license key and an HBaseView object
// NOTE: if the license key has already been included via an initial call to HC_Define_System_Options at startup, it does not need to be included here
input_options.m_license = const char* licensekey = "<license_key_string>";
input_options.m_pHBaseView = my_view;
// open up the desired HOOPS/MVO model segment and read the file
HC_Open_Segment_By_Key(<my model key>);
result = HBaseModel::Read("c:\\temp\\myFile.CATProduct", view, true, &input_options);
HC_Close_Segment();
/*
After reading, a handle to the PRC data is accessible via the HInputHandlerOptions structure, and you can directly query assembly,
topology and PMI information using the HOOPS Exchange API. This PRC data handle would also be used to export to a 3D-PDF if there
is an active license for HOOPS Publish. Refer to the HOOPS Publish HIO connector docs for more information.
*/
m_pPRCAsmModelFile = input_options.m_pPRCAsmModelFile;

Important: If you're loading DWG files, the above method will not work if you have HIO_DWG compiled because Visualize defaults to using HIO_DWG as the importer for DWG files. To force Exchange to handle import of a DWG file, use the HInputHandler method instead, with "dwg_with_prc" (or for DXF files, use "dxf_with_prc") as the parameter for GetInputHandler():

HInputHandler * dwg_handler = HDB::GetHIOManager()->GetInputHandler("dwg_with_prc");
if (dwg_handler != nullptr)
{
char texture_directory[] = "/path/to/textures";
opts.m_pExtendedData = (void *)texture_directory;
// import DWG file into model segment
HFileIOResult result = dwg_handler->FileInputByKey("filename.dwg", m_pHView->GetModelKey(), &opts);
if (result == HIO_OK)
{
// file loaded OK
}
else {
// handle error
}
}
else {
// handle error
}

(This method can be used for all file types, not just DWG.)

Tessellation Options

The following example demonstrates how to use the HTessellationSettings class to customize level-of-detail (LOD) and other tessellation settings when using HOOPS Exchange to import a CAD file and generate tessellation:

HTessellationSettings tessellation;
options.m_pHBaseView = my_view;
options.m_pExtendedData = &tessellation;
HInputHandler * handler = HDB::GetHIOManager()->GetInputHandler(my_CAD_file_extension);
if (handler == nullptr)
{
// something went wrong
}
HFileInputResult result;
HC_Open_Segment_By_Key(my_view->GetModelKey()); {
HC_KEY predefined_key = HC_Open_Segment("predefined");
{
HC_Insert_Distant_Light(-1, 0, 1.5);
tessellation.m_TessLod = HTessellationSettings::HTessellationLOD::TessLODExtraLow;
result = handler->FileInputByKey(your_filename, predefined_key, &options);
if (result != HIO_OK)
{
// something went wrong
}
} HC_Close_Segment();
HC_KEY custom_key = HC_Open_Segment("custom");
{
HC_Insert_Distant_Light(-1, 0, 1.5);
options.m_pPRCAsmModelFile = nullptr;
tessellation.m_TessLod = HTessellationSettings::HTessellationLOD::TessLODUserDefined;
tessellation.m_dChordHeightRatio = 50;
tessellation.m_dAngleToleranceDeg = 40;
tessellation.m_bUseHeightInsteadOfRatio = false;
result = handler->FileInputByKey(filename, custom_key, &options);
if (result != HIO_OK)
{
// something went wrong
}
} HC_Close_Segment();
} HC_Close_Segment();

This example shows two separate methods for generating tessellation, each storing the desired tessellation settings in the HInputHandlerOptions::m_pExtendedData field that will be passed as part of the options object to FileInputByKey().

The first approach simply assigns the HTessellationSettings::m_TessLod option to the predefined setting HTessellationSettings::HTessellationLOD::TessLODExtraLow.

The second example demonstrates how to directly manipulate tessellation settings to better customize results using the option HTessellationSettings::HTessellationLOD::TessLODUserDefined , which allows users to define their own custom values for tessellation-specific settings such as HTessellationSettings::m_dChordHeightRatio.

Obtaining and Selecting Configurations

Several of the CAD file formats supported by HOOPS Exchange have a concept of multiple model 'configurations' which can be stored in the file. Each configuration may have a list of 'views', described below. HOOPS Exchange is able to access the list of configurations at load time, and this info can in turn be accessed in HIO Exchange by defining a load-time callback using HInputHandlerOptions::m_pPRCMultiModelSelectionCallback. This method will provide your callback with the number of configurations, and let you pass back the configuration that you've selected for loading. (You would typically provide the list of configurations in a GUI pulldown dialog, and use the configuration selected by the user as the 'out_config_selection').

The callback is specified in the HInputHandlerOptions used to control file input:

input_options.m_pPRCMultiModelSelectionCallback = MultiModelSelectionCallback;

 

Controlling Import of Hidden Objects

If HInputHandlerOptions::m_bPRCImportHiddenObjects is set to true, representation items marked as 'hidden' will be imported but have their visibility turned off. If set to false, representation items marked as hidden will be skipped and not imported

Exporting Example

You can write files in formats supported by HOOPS Exchange from your HOOPS 3DF-based application using code similar to this:

#include "HIOManager.h"
HFileOutputResult result = OutputFail;
HOutputHandlerOptions output_options;
/* Let's assume that m_pPRCAsmModelFile is a pointer to a PRC model that was either constructed by your application code, or returned from HOOPS Exchange. We pass in the handle to the PRC data via the
HOutputHandlerOptions::m_pExtendedData attribute.*/
output_options.m_pExtendedData = m_pPRCAsmModelFile;
result = pSolidModel->WriteWithOptions("c:\\temp\\myFile.iges", my_view, &output_options);

Supported Data

HOOPS Exchange first maps all incoming CAD data to the neutral 'PRC' format, which in turn is then mapped to the HOOPS/3DGS scene-graph. Here are some key notes on supported graphical primitives and attributes:

  • All analytics (polycylinders, NURBS surfaces, spheres, ellipses, circles) will be turned into shells via Generate_Shell_From_Geometry. Furthermore, all curves will be turned into polylines.

  • Color interpolation is supported via textures. However, color interpolation will always be turned on with such models.
  • Images and simple diffuse textures are supported. However, any texture that has an automatic texture map will appear untextured. Environment maps are supported but secondary diffuse textures and bump maps are not.
  • Subwindows are not currently supported.
  • Heuristics and rendering options are not currently supported. This means that "mask transform" and "screen range" settings are ignored.

It is important to note that the HIO Exchange component ignores b-rep data and asks HOOPS Exchange to provide all data in tessellated form.

Views

A view consists of a group of information in the original CAD file, and displays a particular state of the model. This typically includes a camera, set of cutting planes, lights, PMI, background color, and 'linked items' which are references to model objects along with specific visibility and position information.

The HIO_Exchange module provides support for querying the view information from the PRC data, and mapping it to HOOPS/MVO MarkupManager layers. Each view is associated with a markup 'layer'. Refer to the Markup Manager Programming Guide for more details on how to query the list of MarkupManager 'layers' and open (activate) a layer.

The view information stored in the MarkupManager layers should not be edited, as it is quite specific to the particular CAD-View. If you wish to have additional markups, they should be added to newly created MarkupManager layers.

Mapping Between HOOPS/3DGS and HOOPS Exchange Entities

It is important for developers to be able to map between objects within their HOOPS/3DGS database and the corresponding entities within HOOPS Exchange. Recall that HOOPS Exchange maps CAD data to the PRC data format.

The HIOConnector supports this data mapping functionality. When you call HIOConnector::GetKernelEntity and pass a HOOPS key, the HIOConnector will return a pointer to the corresponding PRC entity. Similarly, if you provide a pointer to a PRC entity when calling HIOConnector::GetHoopsEntity, the HIOConnector will return the key(s) of object(s) within the HOOPS/3DGS database which are used to represent the PRC entity.

Here is some sample code which sets up and utilizes the HIOConnector capabilities. Note that we create a new HIOConnector object and pass its handle into the HInputHandlerOptions class. After input is complete, the HIOConnector class will encapsulate the mapping information.

#include "HIOManager.h"
HFileInputResult result = InputOK;
HInputHandlerOptions input_options;
HIOConnector *connector = new HIOConnector;
// setup the input options with a HOOPS Exchange license key and an HBaseView object
input_options.m_license = const char* licensekey = "<license_key_string>";
input_options.m_pHBaseView = my_view;
input_options.m_pConnector = connector;
// open up the desired HOOPS/MVO model segment and read the file
HC_Open_Segment_By_Key(<my model key>);
result = HBaseModel::Read("c:\\temp\\myFile.CATProduct", view, true, &input_options);
HC_Close_Segment();
my_view->FitSegment(modelkey);
my_view->Update();
HC_Open_Segment_By_Key(<my model key>);
HC_Begin_Contents_Search("...", "shells");
char temp[256];
HC_KEY key;
while (HC_Find_Contents(temp, &key))
{
void *prc_entity = connector->GetKernelEntity(key);
HC_KEY newkey = connector->GetHoopsEntity(prc_entity);
if (newkey == key)
AfxMessageBox(_T("Same Roundtripped Key"));
}
HC_End_Contents_Search();
HC_Close_Segment();

Once a PRC entity is obtained via the HIOConnector::GetKernelEntity method, we can use various HOOPS Exchange methods to further query the PRC data, including traversing up the PRC topology:

// Get PRC topology entity from the HOOPS key via HIO_Connector:
A3DEntity* pEntity = (A3DEntity *)connector->GetKernelEntity(hoops_key);
// Get "OwnersManager" for PRC entity
A3DTopoItemOwnersManagerGet(pEntity, m_pTopologyOwnersManager));
// Use OwnersManager to retrieve the item's "owner"
A3DTopoItemOwner* pTopoItemEdgeOwner = NULL;
A3DTopoItemOwnersGet(m_pTopologyOwnersManager, pEntity, pTopoItemEdgeOwner);

Tessellation Settings for HIO_Exchange. In the HOOPS/MVO component, a new class HTessellationSettings can be used in conjunction with HIO_Exchange to customize a variety of output settings for tessellation, such as triangle size. Please see the API Reference for full details.

top_level:2 prog_guide:4