==================
HTML HIO Component
==================

.. only:: standard

	The Visualize API offers two methods for exporting to an HTML file, one through the ``HIO_HTML`` plugin and the other through :doc:`HIO_Publish </prog_guide/hio/HIO_Publish>`. This section covers ``HIO_HTML``, and instructions for using :doc:`HIO_Publish </prog_guide/hio/HIO_Publish>` HTML export can be found :ref:`here <prog_guide/hio/HIO_Publish:HTML export using HOOPS Publish and HOOPS Exchange>`.
	

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.


.. only:: standard

	**NOTE:** If you are a HOOPS Exchange user and the data originated in HOOPS Exchange, then it is recommended that you use the HIO_Publish module to export HTML. This will ensure that all the CAD information such as Model Tree, B-rep, Views, PMI, and metadata are included.

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 :ref:`sample template <prog_guide/hio/HIO_HTML:Sample HTML 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:

.. csv-table::
	:header: "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.
