HOOPS DWF Integration

1.0 Using the DWF HIO Component

2.0 Import Notes

3.0 Output Handler Options

4.0 Embedding Meta-data within your DWF

5.0 Integrating with the DWF Classes

6.0 Platform Support

7.0 Required Libraries


1.0 Using the DWF HIO Component

The Design Web Format (DWF) is a popular file format from Autodesk. It allows users to share design data without requiring a full seat of the design authoring application. Developers can import DWF data into the HOOPS scene-graph, or export from the scene-graph to a DWF file. This is achieved by using DWF-specific classes provided with your HOOPS/3DF package and downloading the latest version of the DWF SDK from the Autodesk Developer Area.

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

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

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

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

Once the DWF HIO component is successfully loaded, your application will be able import DWF files without having to recompile HOOPS. To utilize the extensive services available in the DWF toolkit, you must compile against the DWF libraries directly and follow the steps described in 5.0 Integrating with the DWF Classes. If you are interested in importing DWF files into your application, please contact a Tech Soft 3D representative for more information.

DWF files can contain both 2D and 3D subfiles. The DWF HIO component provides import/export support for both formats. The 3D-DWF data is actualy heavily based on the HOOPS Stream File (HSF) format, which in turn is essentially a binary archive of the HOOPS/3DGS scene-graph. This should be kept in mind when importing/export 3D-DWF data.

1.1 Rebuilding the HIO Component

The DWF HIO component was built against a specific version of DWF. If you want your application to run against another version of DWF, we recommend that you rebuild the DWF HIO component with that version of the library. To do so, simply open the hio_dwf_vc<version>.vcproj project located in the <hoops>/Dev_Tools/hoops_hio/hio_dwf/source. Be sure to set the environment variable DWF_SDK_DIR to point to the root of your DWF 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 DWF if interfaces are not compatible with the original libraries that the HIO component was built against.

2.0 Import Notes

2.1 2D-DWF scene-graph

  • All layer segments live under the segment "layers"
    • There's a non-layer segment for geometry that does not reside in a layer
  • Layer segments are named
    • The name is encoded as a URI (percent encoded)
    • The name of the segment is the layer name, if available
    • If a layer name is not available, it is named with H_FORMAT_TEXT("layer #%06d", number);
      • Use HC_QShow_Existence to see if a layer exists
      • Use HC_Begin_Contents_Search in the "layers" segment to list the layers
  • Each layer has a User_Options attribute with the name like so
    • layer name = uri-encoded-layer-name
  • The segment tree under each layer is sorted by attribute
    • There is a segment path, named by the attributes, which defines the attribute state
      • For example, "layer #000001/edge line weight 1.0 oru/color 1 0 0/etc..."
  • URLs and object IDs are set directly on the geometry as User_Options
    • the url user options are formatted like so:
      • url = (uri-encoded-url1, uri-encoded-url2, ...)
    • the link_info segment now has one segment per URL.
      • Each of these segments contains geometry references to all geometries which belong to the URL (In the future, this may be enhanced to include the path and attributes for each linked reference)
      • Beginning with Visualize version 19.35, DWF models can export multiple distinct links with the exact same name. In the case where multiple links have the same name, instead of placing the data in the segment given by the link name, subsegments [1, 2, ...] will be created below the link name segment to store the data. The link name segment will also now contain the user option "multiple links = on".
      • There are two User_Options set in each URL segment: min and max
        • Each are three ints/float representing the bounds of the URL. For example, "min = (1, -2.5, 0), max = (5.5, 2.5, 0)"
  • Draw order relies on the z-values
    • Each layer has a translation matrix defining the draw order.
    • Each layer has a priority set defining the draw order which would be honored by the "HSRA = priority" Rendering_Option
    • The z-range is 1/3rd of the diagonal of the 2D drawing (not including the background and non-layer segments)
  • 2D Drawings
    • all have background "paper"
      • you can disable the background paper by deleting or hiding the "background" segment
    • The camera is changed to look down the -z axis, and y axis is up
    • The camera projection is set to orthographic
    • The pan operator is set
  • Obtaining correct measurements
    • A DWF file will usually contain at least one viewport. Each viewport may use a different measurement scale. All geometry within a viewport is grouped together in the same segment. The viewport segment will have the name of the viewport, and be located under the parent layer segment. Each viewport segment will contain two user options, as follows:
      1. "viewport units" – this specifies what measurement units this viewport uses (i.e. millimeters, inches, etc.)
      2. "measurement scale" – this number is used to scale the measurements in world coordinates to the the DWF measurements.
      The workflow to obtain correct measurement would thus be:
      1. Use an operator to measure the distance between two points in world space
      2. Figure out in which viewport the points reside (one way to do this would be through a selection)
      3. Divide the distance in world coordinates by the measurement scale of the viewport. In the example below, the viewport units are inches and the measurement scale is 47370962.467. The measured distance is 2.32909e+008. Therefore, the correct measurement is:
        2.32909e+008 / 47370962.467 = 4.9 inches

2.2 DWF Units

When a DWF model is imported into HOOPS, the model units are also imported. This information 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:

  • Inches
  • Feet
  • Millimeters
  • Centimeters
  • Meters
  • Undefined Units

 

3.0 Output Handler Options

The HOOPS DWF exporter relies on a number of output settings. The most important one is whether to create a 2D or 3D DWF. You can specify which output you want to export by setting the HOutputHandlerOptions::m_b3dOutput flag and passing it to the HBaseModel::WriteWithOptions method. If the output is a 2D DWF, then the page size will be 8.5" by 11.0". If you want to output a 3D DWF, you will need to determine the camera settings as well.

3.1 Setting The Camera for 3D DWFs

When you are exporting 3D DWF, the camera which is defined at export time will be saved with the model. Since camera setting are found in HBaseView, you must supply a pointer to your HBaseView object via HOutputHandlerOptions::m_pHBaseView in your call to the HBaseModel::WriteWithOptions method.

To ensure that the pre-set camera available from the DWF Viewer works as expected, you will need to orient your data according to the DWF setup. Specifically, the DWF Viewer assumes a right-handed coordinate system, where the front view is defined as looking down the z-axis in the negative direction, with the Y-axis pointing up.

4.0 Embedding Meta-data within your DWF

In HOOPS, you can identify a specific segement as a node to the DWF Viewer's model browerser by setting that a suer option of node on that segment. When it is laster selected in the model browser, that segment and all its children will be highlighted in the 3D window. Furthermore, if you set additional "name= value" pairs as a user options on that same segment, these will be displayed in the Properties window.

5.0 Integrating with the DWF Classes

Note:

DWF classes cannot be integrated directly into a HOOPS-based application which is also using HOOPS/Stream module. The reason for this is there are two stream components - one is HOOPS/Stream and other is Autodesk's copy of HOOPS stream which is part of DWF Toolkit (known as W3DTOOLKIT). These two have same class names, but slightly different implementations and they cannot coexist in one application.

In this section, we outline the steps involved in directly integrating between your HOOPS-based application and the DWF classes. Once you have downloaded and installed the DWF Toolkit, please follow the steps below:

  1. Set the DWF_SDK_DIR environment variable to point at the root of your DWF Installation
  2. Add HIOUtilityDwfExport.h and .cpp to your project. These files are located in the Dev_Tools/hoops_hio/hio_dwf/hoops_dwf/source directory of your HOOPS installation. Refer to hio_dwf<import/export>_vc90.vcproj in Dev_Tools/hoops_hio/hio_dwf/hoops_dwf/source directory.

  3. Add following directories in your include path:
    • $(DWF_SDK_DIR)\develop\global\bin\<debug/release">\vc9.0
    • $(HOOPS_INSTALL_DIR)\Dev_Tools\hoops_hio\hio_dwf\hoops_dwf\source
  4. Add the following directories to your link path:
    • $(DWF_SDK_DIR)\develop\global\lib\shared\<"debug/release">\vc9.0
  5. Add following dependencies to the linker settings:
    • (debug/release) dwfcore_wt.1.6.0.lib dwftk_wt.7.6.0.lib whiptk_wt.7.12.601.lib w3dtk_wt.1.6.1555.lib

Once you have completed the above steps, you do not need to rely on the DWF 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 HIOUtilityDwfExport via HIOManager::RegisterOutputHandler so that the HBaseModel::Write function can recognize that the .dwf 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.

Once you have these settings you should now be able to export DWF files from your application with code similar to this:

HOutputHandlerOptions options;
options.m_pHBaseView = m_pHView;
options.m_b3dOutput = false;
HOutputHandler * extra_handler = HDB::GetHIOManager()->GetOutputHandler("dwf");
if (extra_handler)
{
HFileOutputResult result = extra_handler->FileOutputByKey(L"c:/testing_dwf.dwf", m_pHView->GetModelKey(), &options);
}

6.0 Platform Support

Our integration is supported on 32-bit and 64-bit Microsoft Visual Studio 2008 and 2010.

7.0 Required Libraries

For Release 19.16, the HIO_DWF component requires DWF 7.7.

For Release 19.00, the HIO_DWF component requires DWF 7.6.