==========================
HOOPS Visualize Web Access
==========================

HOOPS Visualize Web is Tech Soft 3D's web application framework. It gives you the ability to load and stream model files over a network directly into a 3D application window. Using the HOOPS Visualize Web sprocket, you can read all the file formats supported by HOOPS Visualize Desktop or HOOPS Exchange from a remote server.

The HOOPS Visualize Web sprocket is provided as a way for HOOPS Visualize Desktop to render and interact with model files served from a HOOPS Visualize Web server. The HOOPS Visualize Web Stream Cache system enables very large files to be loaded via streaming which would otherwise be infeasible to view.

In order to use the HOOPS Visualize Web sprocket, you must be using the same version as the HOOPS Visualize Web server you're streaming files from. Please see the compatibility chart in the :doc:`release notes </general/release_notes/index>` to find the proper version.

This page assumes basic familiarity with HOOPS Visualize Web. To read more, see the `HOOPS Visualize Web documentation <https://docs.techsoft3d.com/communicator/latest/>`_.


Required DLLs
=============

The sprocket depends on a set of DLLs that are not normally required for %HPS to work. When you are ready to distribute your HOOPS Visualize Web-enabled application, be sure to include these additional DLLs found in the %HPS package:

* *cc_exchange_lib.dll*
* *hc_access.dll*
* *libcrypto-3-x64.dll*
* *libssl-3-x64.dll*
* *v8.dll*
* *v8_libbase.dll*
* *v8_libplatform.dll*
* *websockets.dll*


Loading a Model Over a Network
===============================

There are two ways in which HOOPS Visualize Web data can be loaded: over a network (Stream Cache model, *.sc), or locally (*.scs files) - :ref:`see below <scs_loading>`. Loading a stream cache model is fundamentally different from loading a file from the file system because the file is transferred over the network using a HOOPS Visualize Web server. As such, you will need an accessible HOOPS Visualize Web server in addition to the client application. The general steps needed to get the system running are as follows:

#. Set up the environment. To use the Stream Cache server, it will need to be running and accessible. Know the IP address and port it is using.
#. Include the HOOPS Visualize Web Access libraries in your project. The HOOPS Visualize Desktop-HOOPS Visualize Web integration library must be included as a dependency. C++ users will need to link to the *hps_sprk_hca.lib*. C# users will need to add a reference to the *hps_sprk_hca.dll*. These files are located in the *bin* directory of your HOOPS Visualize Desktop package.
#. Include the header file *sprk_hca.h* in your source (C++ only).
#. Include the Javascript file *hca_access.js* in your path.

All classes that implement the HOOPS Visualize Web sprocket logic are members of the ``HPS::HCA`` namespace. The process of loading a file using this sprocket is similar to the process for other HOOPS Visualize Desktop sprockets:

#. Populate a ``HPS::HCA::NetworkImportOptionsKit`` with data related to your session.
#. Import the file using ``HPS::HCA::File::Import``.
#. Wait on the notifier so you know when the model is finished loading.


Example of loading a stream cache model:

.. tabs::

	.. group-tab:: C++
	
      .. code-block:: cpp

         HPS::HCA::NetworkImportOptionsKit importOptionsKit;
         
         // be sure to include the port number where applicable
         importOptionsKit.SetNetworkPath("http://127.0.0.1:11182");
         importOptionsKit.SetLimitMiB(1024);
         importOptionsKit.SetTarget(myModel);
         importOptionsKit.SetJavascriptPath(jsPath); // path to hc_access.js - this file is distributed with Communicator
         importOptionsKit.SetView(defaultView); // sets the HPS::View to use by default
         
         HPS::HCA::ImportNotifier notifier;
         
         HPS::HCA::File::Import(filename, importOptionsKit, notifier);
         
         notifier.Wait();
         
         HPS::IOResult result = notifier.Status();
         
         if (result == HPS::IOResult::Success)
            success = true;
		   
	.. group-tab:: C#

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00780_hca_load_sc.cs
		   :start-after: //! [load_sc]
		   :end-before: //! [load_sc]
		   
The code above will load a model from a HOOPS Visualize Web server (in this case, a server running on localhost). Notice the use of ``notifier.Wait()``. When loading a model over the network, calling ``Wait()`` will wait only until the import starts streaming data, and will return control to the user while geometry is still being added to the scene. This is because an import over the network is used for very large files, which might never completely load (for example because a memory limit has been set).

The HOOPS Visualize Web Stream Cache server serves a portion of a model's geometry based on camera position and geometry size. This is ideal for very large models, which may be too large to load all at once into memory. Using the streaming server enables a HOOPS Visualize Desktop application to stream data in and out of the HOOPS Visualize Desktop scene graph.


.. _scs_loading:

Loading a Local Model
=====================

Stream cache models can be made available as SCS files, which are a locally-available alternative to the stream cache system. Loading a *.scs* file does not require a server, however, these files cannot be streamed. The entire model is loaded at once, therefore, you will have to more carefully consider the resources available in the execution environment. The process is similar to what is described above, however, instead of using a ``NetworkImportOptionsKit``, you need to use a ``HPS::HCA::ImportOptionsKit``.

.. tabs::

	.. group-tab:: C++
	
      .. code-block:: cpp

         HPS::HCA::ImportOptionsKit importOptionsKit;
   
         // be sure to include the port number where applicable
         importOptionsKit.SetTarget(myModel);
         importOptionsKit.SetJavascriptPath(jsPath); // path to hc_access.js - this file is distributed with Communicator
         importOptionsKit.SetView(defaultView); // sets the HPS::View to use by default
   
         HPS::HCA::ImportNotifier notifier;
   
         HPS::HCA::File::Import(filename, importOptionsKit, notifier);
   
         notifier.Wait();
   
         HPS::IOResult result = notifier.Status();
   
         if (result == HPS::IOResult::Success)
             success = true;
		   
	.. group-tab:: C#

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00780_hca_load_scs.cs
		   :start-after: //! [load_scs]
		   :end-before: //! [load_scs]
		   
The code above will load a HOOPS Visualize Web model from a local source. Notice the use of ``notifier.Wait()``. When loading a model in this way, calling ``Wait()`` will wait for the whole file to be loaded, just like it does for other local file types.


Getting a Reference to the Model
================================

After the model is loaded, you most likely will want a reference to it so that you can interact with it. To do this, simply call ``HCA::ImportNotifier::GetTarget()``, which provides the ``HPS::Model``. From there, you can construct the ``HPS::HCA::Model``.

.. tabs::

	.. group-tab:: C++

      .. code-block:: cpp
	
         Model hpsModel = notifier.GetTarget();
         HCA::Model hcaModel = HCA::Model(hpsModel);
		   
	.. group-tab:: C#

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00780_hca_load_scs.cs
		   :start-after: //! [get_model]
		   :end-before: //! [get_model]
		   
HOOPS Visualize Web models are comprised of a collection of nodes. All model information is addressable via node ID. To query your newly loaded model, start with the ``HCA::Model`` and drill down using ``RequestNodeProperties`` and ``RetrieveNodeProperties``. These functions are designed to work asynchronously, so you may have to account for network latency.

.. tabs::

	.. group-tab:: C++
	
      .. code-block:: cpp

         int64_t myNodeId;
   
         uint32_t myRequestId;
         bool myValid;
   
         hcaModel.ShowRootNode(myNodeId);
   
         // get the properties for the root node ID
         hcaModel.RequestNodeProperties(myNodeId, myRequestId);
   
         HPS::UTF8Array out_keys;
         HPS::UTF8Array out_values;
   
         // since the previous function is asynchronous, we may have to wait
         hcaModel.RetrieveNodeProperties(myRequestId, 1000, myNodeId, myValid, out_keys, out_values);
		   
	.. group-tab:: C#

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00780_hca_load_scs.cs
		   :start-after: //! [get_node_properties]
		   :end-before: //! [get_node_properties]

So far we've only been working with the root node. To get other nodes, use ``ShowNodeChildren`` to recursively walk the node tree:

.. tabs::

	.. group-tab:: C++

      .. code-block:: cpp
	
         HPS::Int64Array out_ids;

         hcaModel.ShowNodeChildren(myNodeId, out_ids);
			   
	.. group-tab:: C#

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00780_hca_load_scs.cs
		   :start-after: //! [show_node_children]
		   :end-before: //! [show_node_children]

For a complete example application, see :ref:`this subsection <prog_guide/0910_hca:MFC HCA Sandbox>` and also the *mfc_hca_sandbox* application, which is distributed with the HOOPS Visualize Desktop solution.


Supported File Types
====================

Before HOOPS Visualize Web can serve models, it is necessary to convert them to its own file formats. These native formats include SC, SCS, and SCZ. They are optimized for streaming, and are tesselated, unlike CAD file formats which are usually B-rep. This conversion can take place ahead of time, or on demand. The three types of files are described below:

SCS files do not require a HOOPS Visualize Web server to access. They can be loaded directly via the HOOPS Visualize Web Sprocket. In this case, the entire SCS file will be loaded into HOOPS Visualize Desktop. This is possible only for models which are small enough to fit in system memory of the client application.

SC files are streamed over the network with a server, and are typically broken into multiple files behind the scenes.

An SCZ file is a single file version of the SC format. Details on all the file types can be found `here <https://docs.techsoft3d.com/communicator/latest/build/prog_guide/viewing/data_model/stream_cache/overview.html>`_.

Other types of models undergo a conversion process before the data is streamed to the client. In the general case, the HOOPS Visualize Web server will use HOOPS Exchange to convert a model from its native format into the Stream Cache format.

The details are all described in the `HOOPS Visualize Web documentation <https://docs.techsoft3d.com/communicator/latest/>`_.


.. _toc_highlighting:

Highlighting
============

Behind the scenes, loading HOOPS Visualize Web models is a fundamentally different process than loading traditional models. It follows that certain operations need to be done in a different way. Highlighting, unhighlighting, isolate, hide, and show are all examples of this. ``HCA::Model`` has its own collection of these function variants. When you need to use them, simply make sure you use those variants instead of the normal ``HPS::HighlightControl`` or ``HPS::ComponentPath`` versions.


MFC HCA Sandbox
===============

The MFC HCA Sandbox is an application provided with the HOOPS Visualize Desktop package which intends to demonstrate how the HOOPS Visualize Web process works. The project source is provided and can be used as a starting point for your own application. Please see the *mfc_hca_sandbox* project in your package.

When you first start the sandbox, you'll notice two buttons on the toolbar called "Connect" and "Options". In order to load a stream cache model, you need to be running (or have access to) a HOOPS Visualize Web server. It's also important that you fill out the options dialog so its values match your environment.

.. image:: images/mfc_hca_sandbox_options.png

The network path will be the URL and port for your HOOPS Visualize Web server. The Javascript path is where the *hc_access.js* file is located (it is provided as part of HOOPS Visualize Web). The network model is the name of the file you want to load. This file needs to be in (or relative to) one of the directories listed in HOOPS Visualize Web's ``Config.js`` file (you can find the setting under the "modelDirs" value). The memory limit corresponds to the value set in ``HPS::HCA::NetworkImportOptionsKit::SetLimitMiB()``.

Loading a *.scs* file doesn't require setting any network options, because *.scs* files are loaded from a local source.

Whichever way you load the model, you can interact with it like any other model:

.. image:: images/mfc_hca_sandbox_loaded_file.png

You will also notice the User Code tab, which is available to execute your own code in the context of the MFC HCA Sandbox.

Once your model is loaded, the model and segment browsers will be populated. Activate them by clicking on their respective icons in the ribbon bar. These browsers have a tree control with nodes that correspond to each part of the model. The segment browser represents the %HPS scene graph - the segments and attributes which make up the data you see on screen. The data in the model browser corresponds to the structure of the model as loaded from its source format. Clicking on any node in either browser will highlight the corresponding part of the model in orange. Similarly, clicking on the model will highlight that part in each browser (to do this, make sure the "Point" selection operator is active).

Finally, there is a statistics window which shows various statistics about the model and how it is rendered, such as number of triangles, memory usage, and the GPU.

.. image:: images/mfc_hca_sandbox_browsers.png

Limitations
===========

Loading multiple files into a scene is not possible at this time. If you need to load a second model, you need to unload the first model by deleting your model segment using ``HPS::Model::Delete``.

Models generally can't be modified and saved directly back to the server. If you need to modify a HOOPS Visualize Web model, we recommend you make your changes, export the model, and get it back to the server independently.

Exchange views are not currently supported.
