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

HOOPS Publish Integration

1.0 Using the HOOPS Publish HIO Component

2.0 Supported Data

3.0 Platform Support

4.0 Required Libraries


1.0 Using the HOOPS Publish HIO Component

The HOOPS Publish HIO component (HIO Publish) supports exporting the HOOPS/3DGS scene-graph to the 3D PDF format. It utilizes the HOOPS Publish API to achieve this. Before using this component, developers should become familiar with HOOPS Publish, as well as the general HIO architecture and capabilities covered in section 4.0 of the HOOPS/MVO Programming Guide.

The HIO Publish component is delivered in the form of a .hio file, which gets dynamically loaded by HOOPS Visualize at runtime. To ensure your application can access the HIO Publish component, perform the following:

  1. Create a hio_plugins directory in your application's working directory.
  2. Copy the hiopublish<version>.hio file found in <hoops>/bin/<platform>/hio_plugins/hio_publish to the hio_plugins directory created in the previous step.
  3. Ensure that the HOOPS Publish .dlls are in your application's path.
  4. Run your application

During start-up, when HOOPS/MVO finds the HIO Publish component and HOOPS Publish .dlls, it will perform the following steps:

  1. Create the appropriate 3D-PDF output handler.
  2. Register this handler and the associated file extension with the HIOManager.

Once the HIO Publish component is successfully loaded, your application will be able to export the HOOPS/3DGS scene-graph to 3D PDF files.

Exporting Use Cases

The hio_publish module supports the following export cases, with each approach detailed down below:

  • Basic Export: This involves exporting to a simple 3D-PDF document of fixed size, and with no customizations made to the PDF document.
  • Export via a Template: This involves specifying an existing PDF template, which will serve as the basis for the exported 3D-PDF document.
  • Advanced export using HOOPS Publish: This involves exporting to a PRC model (which represents the 3D data in a 3D-PDF document), and then using the HOOPS Publish APIs to embed the PRC model into a 3D-PDF document that can be fully customized. This approach is appropriate if you require full control over the PDF document properties. See the HOOPS Publish Technical Overview for more details about the level of PDF customization available using HOOPS Publish.

1.1 Basic Export

Basic export involves:

  • setting up the HOutputHandlerOptions structure with a valid HOOPS Publish license key
  • obtaining the HOutputHandler for the 'pdf3d' file type
  • customizing the layout of the '3D Annotation' within the PDF document
  • calling the HOutputHandler::FileOutputByKey method

#include "HIOManager.h"
    
HFileOutputResult result = OutputFail;
HOutputHandlerOptions output_options;

// setup the output options with a HOOPS Publish license key
output_options.m_license = const char* licensekey = "<license_key_string>"; 

// let's have the 3D Annotation automatically activate when the containing PDF page is opened
output_options.m_bActivateOnPageOpen = true;

// change the size of the 3D Annotation
output_options.m_fAnnotLeft = 3.0;
output_options.m_fAnnotRight = 3.0;
output_options.m_fAnnotBottom = 2.0;
output_options.m_fAnnotTop = 2.0;

output_options.m_pHBaseView = myBaseView;

// If we simply exported a 'foo.pdf' file, HOOPS/MVO would by default export a '2d pdf' using it's built in 2D-PDF export support.  
// Since we want to export a 3D-PDF, we must obtain the output handler for the 'pdf3d' file type and utilize it. 
HOutputHandler * handler = HDB::GetHIOManager()->GetOutputHandler("pdf3d");
if (handler)
    result = handler->FileOutputByKey("c:\\temp\\my_3D_PDF_File.pdf", myBaseView->GetModelKey(), &output_options);

You could additionally specify the handle to an existing PRC model, which is what makes up the 3D part of 3D-PDF. Specifying the PRC handle tells the HIO Publish module to directly utilize the existing PRC data and embed it in a 3D-PDF document, rather than traversing the HOOPS scene-graph information. This may be desireable if you are using HOOPS Exchange to bring in native CAD files (After a CAD file is imported witih HOOPS Exchange, you have access to a PRC handle). This approach is achieved by setting the HOutputHandlerOptions::m_pPRCAsmModelFile attribute to the PRC model handle, prior to calling FileOutputByKey:

// Let's assume that m_pPRCAsmModelFile is a pointer to our PRC data.
output_options.m_pPRCAsmModelFile = m_pPRCAsmModelFile;

 

1.2 Export via a Template

HOOPS Publish provides the ability to create a PDF based on an existing PDF 'template' that contains named fields which can be modified/populated via HPDFLayoutManager methods. HOOPS Publish includes a handful of templates, and they can be viewed/edited using Acrobat Professional. You can also create your own template.

Exporting a file based on a template involves:

  • obtaining the HIOUtilityPublish handler
  • calling HIOUtilityPublish::BuildPRCModel to obtain a pointer to the PRC model information
  • using the HPDFLayoutManager object to select an existing PDF template and setup its fields
  • exporting the PDF by calling the HIOUtilityPublish::WritePDFFromTemplate

// Requires the hio_publish directory to be part of the include path
#include "HIOUtilityPublish.h"       

// obtain a pointer to the HIOUtilityPublish output handler
HIOUtilityPublish * handler = (HIOUtilityPublish *)HDB::GetHIOManager()->GetOutputHandler("pdf3d");

if (handler)
{
    HOutputHandlerOptions output_options;

    // setup the output options with a HOOPS Publish license key
    output_options.m_license = const char* licensekey = "<license_key_string>"; 
    
    // specify the HBaseView object
    output_options.View(m_pHView);

    // this method parses the HOOPS Visualize database and returns a pointer to a PRC model
    void *prcmodel = handler->BuildPRCModel(&output_options, m_pHView->GetModelKey());   

    // obtain a layoutManager object
    HPDFLayoutManager layoutManager;
    
    // instruct the layout manager to use a pre-existing PDF template
    layoutManager.SetTemplateName("<my_hoops_publish install_dir>\publish110\\pdf_templates\\Templates\\MultiViews\\MultiViews_A4.pdf"); 
                                    
    // Set the name of the PDF field that will serve as the canvas for the 3D view  
    layoutManager.Set3DFieldName("My3DWindow");                    
          
    // HPDFLayoutManager::AddTextModification method changes the associated text of an existing PDF text field
    layoutManager.AddTextModification("SummaryText", "This is a test");                                            
    
    // HPDFLayoutManager::AddImageModifcation method changes the associated image of an existing PDF image field 
    layoutManager.AddImageModification("Button1", "c:\\temp\\apex.jpg", HJPG, 40, 40);          
    
    // HPDFLayoutManager::AddMiscModification attached Javascript and/or changes visibility of an existing PDF field
    layoutManager.AddMiscModification("DocumentSubHead", 0 ,HInvisible);   
        
    // We now export the PDF using the HIOUtilityPublish::WritePDFFromTemplate method    
    handler->WritePDFFromTemplate("c:\\tempfiles\\test.pdf", prcmodel, &output_options, &layoutManager, 0);
}

 

1.3 Advanced export using HOOPS Publish

This requires first exporting the scene-graph to a PRC model, which has already been covered above. It involves getting the HIOUtilityPublish handler, and calling HIOUtilityPublish::BuildPRCModel to obtain a pointer to the PRC model information.

// Requires the hio_publish directory to be part of the include path
#include "HIOUtilityPublish.h"       

// obtain a pointer to the HIOUtilityPublish output handler
HIOUtilityPublish * handler = (HIOUtilityPublish *)HDB::GetHIOManager()->GetOutputHandler("pdf3d");

if (handler)
{
    HOutputHandlerOptions output_options;

    // setup the output options with a HOOPS Publish license key
    output_options.m_license = const char* licensekey = "<license_key_string>"; 
    
    // specify the HBaseView object
    output_options.View(m_pHView);

    // this method parses the HOOPS Visualize database and returns a pointer to a PRC model
    void *prcmodel = handler->BuildPRCModel(&output_options, m_pHView->GetModelKey());   
}

You would now access HOOPS Publish APIs to create a custom PDF document, and then embed the PRC model inside.

1.4 Reducing File Size

Implicit HOOPS/3DGS Primitives

Certain types of models may contain large amounts of implicit primitives, which can in turn result in large amounts of tesselation information during export. This can cause large 3D-PDF (and PRC) files, an increase in memory usage, and excessive export-time. If you have a scene with a large amount of HOOPS/3DGS cylinders and/or spheres, the following steps can greatly improve export performance and reduce file size:

  1. call HC_Set_Rendering_Options("tessellation=(cylinder=3,sphere=4)"), in the model segment before exporting to 3D-PDF. (The provided values are sample/suggested values.)
  2. when exporting to 3D-PDF, you will need to set the new option HOutputHandlerOptions::m_bPrcCompressTessellation to TRUE

BRep Information

The HOutputHandlerOptions::m_ePrcBrepCompression setting can reduce 3D-PDF file size when exporting PRC BRep data. (Typically this is data that came from a CAD file imported via HOOPS Exchange.) This setting will have no effect if there is only HOOPS/3DGS tessellation data being exported to 3D-PDF or PRC.

2.0 Notes about Supported Data

In general, most HOOPS/3DGS scene graph information is exported to 3D-PDF, with the following exceptions:

  • A subset of the animations types supported by HOOPS/MVO HBhvAnimation will be exported, including object rotation/translation, camera movement, visibility, and segment-switching.
  • Items in the HOOPS/3DGS scene-graph that were inserted as MVO PMI elements will be exported. (These PMI elements could have been programmatically defined by the developer, or may have been created by HOOPS Exchange during its CAD file import logic.)
  • HOOPS/3DGS scene graph text is not currently supported. (Only text that is defined as part of PMI elements is exported.)
  • Any CAD 'views' information that was previously imported using HOOPS Exchange and resides in the PRC model, will be exported to 3D-PDF, provided that HOutputHandlerOptions::m_pPRCAsmModelFile was set to the PRC file handle. (For more information about CAD 'views', please read the HIO Exchange and HOOPS Exchange documentation.)

 

3.0 Platform Support

The HOOPS Publish HIO component is supported under Windows 32-bit/64-bit for Microsoft Visual Studio 2008/2010.

4.0 Required Libraries

For Release v19.34, the HOOPS Publish HIO component requires HOOPS Publish 6.0.

For Release v19.28, the HOOPS Publish HIO component requires HOOPS Publish 5.3.

For Release v19.16, the HOOPS Publish HIO component supports HOOPS Publish 5.0

For Release v19.14, the HOOPS Publish HIO component supports HOOPS Publish 1.10