HTML HIO Component

Using the HTML HIO Component

The HTML HIO component (HIO_HTML) allows users to export a HOOPS/3DGS scene-graph to an HTML page. The HTML page uses HTML5 technologies like WebGL to render an interactive 3D object in your browser. Support for standard and mobile browsers is provided with the only requirement being that the browser is HTML5 compliant.

HIO_HTML utilizes the libSC component of HOOPS Communicator. The required libraries are included in this package. If you need to recompile the HIO_HTML component you will need to set the environment variable HCOMMUNICATOR_INSTALL_DIR to point to your HOOPS Communicator install. If you are not a HOOPS Communicator user please contact the HOOPS Support Group and they will provide you with access to the libSC libraries.

The HIO HTML 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 HTML component, perform the following:

Create an hio_plugins directory in your application’s working directory.
Copy all the files found in <hoops>/bin/<platform>/hio_plugins/hio_html to the hio_plugins directory created in the previous step.
Run your application

During startup, when HOOPS/MVO finds the HIO HTML component it will perform the following steps:

Create the appropriate HTML output handler.
Register this handler and the associated file extension with the HIOManager.

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

Example:

#include "HIOManager.h"

HFileOutputResult result = OutputFail;
HOutputHandlerOptions output_options;

output_options.m_pHTMLTemplateFile = "C:\\HOOPS_3DF_2220\\Dev_Tools\\hoops_hio\\hio_templates\\HOOPSCommunicatorTemplate.html";
output_options.m_pHBaseView = m_pHView;
HOutputHandler * handler = HDB::GetHIOManager()->GetOutputHandler("HTML");

if (handler)
        result = handler->FileOutputByKey("c:\\temp\\my_Sample.html", m_pHView->GetModelKey(), &output_options);

Creating Your Own Custom HTML Template

The HTML export creates a totally self-contained HTML file for viewing a model. This means that all the markup, styling, Javascript, images, and model data are contained in a single file which works out of the box in any modern browser with no internet connection required.

About the HOOPS Communicator Template File

The template file is a pre-processed HTML file with all dependencies inlined. Binary dependencies such as images and model data are base64 encoded into the file as well. All this preprocessing is done when the HOOPS Communicator package is built. Browsers can automatically base64 decode binary files such as images. Additional javascript code must be used to base64 decode the model data. This code is included in the standard template and can be leveraged by customers if needed.

Creating a Custom Template File

Aside from ensuring that the contents of hoops_web_viewer.js are included in the page, there are four required steps to create a custom template file. To see a sample template, please see the sample template at the bottom of this page.

Step 1: Insert the data replacement string

Include the replacement string in the file:

<!-- SC_MODEL_DATA -->

The system searches the template file for this string and replaces it with base64 binary encoded data. Ideally this string should be saved in a variable. For example:

var SC_MODEL_DATA = "<!-- SC_MODEL_DATA -->";

<style>.TemplateSteps
{
        font-weight:bold;
        font-size:medium;
        margin-top:12px;
}
</style>

Step 2: Add a container div

There must be a container div in the template in which the viewer will be created:

<div id="viewerContainer" style="width:100%; height:100%;"></div>

Feel free to add your own styling.

Step 3: Decode the base64-encoded data to a Uint8 buffer

Sample code to do this is provided in the minimal template. The _base64ToUint8Array method is a small helper function provided by HOOPS Communicator team:

var binaryModelData = _base64ToUint8Array(SC_MODEL_DATA)

Step 4: Create and start a WebViewer object

Specify your binary decoded data to the web viewer:

var viewer= new Communicator.WebViewer({
        containerId: "viewerContainer",
        buffer: binaryModelData,
});

Look, Feel, and Functionality

Aside from the required elements enumerated above, users are free to add in their own HTML / JS / CSS code to the template. HOOPS Communicator customers may use the entirety of the Communicator API to create their own customized pages.

There are some restrictions for non-Communicator customers. The following classes aren’t available to non-Communicator customers:

Communicator.MeshData
Communicator.MeshInstanceData

The following functions aren’t available to non-Communicator customers:

Communicator.Model.createMesh
Communicator.Model.createMeshInstance

Helpful Hints

It can be challenging to work only in a single template file, especially given the size of the required javascript for the HOOPS WebViewer. There are a number of tools which can take a website and convert it to a self contained file. It would be helpful to design your template using normal separation of HTML, JS, CSS and employ a tool to combine all of it into your final template. We have had good luck using the webpage2html python module.

Sample HTML Template

The sample below shows the minimal HTML Export template. This file is available in the package in the Dev_Tools/hoops_hio/hio_templates directory. It will decode the plaintext data and start the viewer:

<pre>
<html>
<head>
<title>Minimal HTML Export Template</title>

<script>
        //The contents of hoops_web_viewer.js will appear here.
</script>

<script>
        function _base64ToUint8Array(base64) {
                var binary_string =  window.atob(base64);
                var len = binary_string.length;
                var bytes = new Uint8Array( len );
                for (var i = 0; i < len; i++)        {
                        bytes[i] = binary_string.charCodeAt(i);
                }
                return bytes;
        }

        var SC_MODEL_DATA = "<!-- SC_MODEL_DATA -->";

        var hwv = null;
        var ui = null;

        window.onload = function () {
                hwv = new Communicator.WebViewer({
                                containerId: "viewerContainer",
                                buffer: _base64ToUint8Array(SC_MODEL_DATA),
                        });

                window.onresize = function (event) {
                        hwv.resizeCanvas();
                };

                hwv.start();
        }
  </script>

  <style>
          body{
                  margin: 0;
                  padding 0;
          }
        #viewerContainer{
                position:relative;
                width:100%;
                height:100%;
        }
  </style>
</head>
<body>
<div id="viewerContainer"></div>
</body>
</html>
</pre>

Notes About Supported Data

In general, most HOOPS/3DGS scene graph information is exported to HTML. Special cases are noted below:

Visualize	Notes
Text font settings	Supported: name (some limitations), size (some limitations), bold, italic, overline, strikethrough, underline, width scale, transforms, line spacing. Unsupported: extra space, exterior, greeking limit, greeking mode, preference, renderer, rotation (though ‘follow path’ is supported if a text path is given), size tolerance, slant.

Text paths	Text paths are supported, but text will always appear as if ‘rotation = follow path’ is set.

Textures	Only diffuse and environment textures are supported. Multitexturing is not supported. If you require multitexturing, we recommend you composite the textures into a single texture.

NOTE: Animations are not currently supported.