##########################
Frequently Asked Questions
##########################

.. program:: converter


.. admonition:: Where can I get a new license for HOOPS Communicator?
	
	Please review our :doc:`License key </overview/license>` page for details.
	

.. admonition:: The start_server.bat/sh fails to run, and/or convert_file.bat/sh results in a "cannot open file" error.

	Please ensure you run these scripts with admin privileges, and any output directories have write privileges.


.. admonition:: Is the Stream Cache file format backward compatible?

	The Stream Cache format is backward-compatible starting with HOOPS Communicator 2016 SP2.


.. admonition:: What are the file extensions for Communicator/Stream Cache files?

	There are two primary file types generated by Communicator. An *.scs* file is a compressed and standalone file containing all of the 3D model data. It is not streamable by the server and will be loaded by the viewer directly via an http request. An *.scz* file is a single file containing all model data in a streamable form. Its a single file version of a stream cache directory.
	

.. admonition:: Will the node IDs always be the same between loads of the viewer?

	Yes, but loading multiple models in the same scene requires accounting for a shift in node IDs. Here's how to do this: 
	
	After you've loaded your first model, you'll want to keep track of the shift before loading a new model. These two lines show how to capture the shift amount from the viewer:
	
		.. literalinclude:: /../../applications/client/docs/AssemblyTree.ts
			   :start-after: //! [Shift_Node_IDs]
			   :end-before: //! [Shift_Node_IDs]

	Now anywhere you need the persistent node ID you would do something like this:

		.. literalinclude:: /../../applications/client/docs/AssemblyTree.ts
			   :start-after: //! [Select_Shifted_Node_IDs]
			   :end-before: //! [Select_Shifted_Node_IDs]

	This will always allow you to get back to the persistent ID for retrieving associated application level data. For more information, see the :doc:`/prog_guide/data_import/authoring/libsc-assembly-tree-node-ids` page.
	

.. admonition:: What's the difference between a PartId and a NodeId?

	In the Communicator documentation, you may notice that certain functions contain parameters with specific types - for example, the function :js:meth:`Communicator.Model.getNodeLineColor(partId, lineIndex) <Communicator.Model.getNodeLineColor>` takes a :ref:`Communicator.PartId` as a parameter!

	But for many users, Communicator is a Javascript API, so why are there types listed in the documentation? The object types found in parameters and return values in the Communicator API Reference documentation are extracted from strongly typed objects in Communicator's TypeScript source. Communicator's Web Viewer API is available in both TypeScript and Javascript.

	In Javascript, both the :ref:`Communicator.PartId` and :ref:`Communicator.NodeId` translate to a generic Javascript ``number`` value type (by "value type" we simply mean that variables in Javascript do not have types, but their values do).

	Nevertheless, even for Javascript users it's still helpful to know the expected type of object for each parameter, and so the documentation preserves the original TypeScript signatures to let users know the expected type of assembly tree node the function expects as a parameter.

	To further clarify, let's walk through a usage scenario. Say, for example, we're using the :doc:`SelectionManager </api_ref/viewing/classes/Communicator.SelectionManager>` in the Web Viewer and we select a part of the model with a mouse click.

	If we then call ``myViewerInstance.selectionManager.getFirst().getNodeId()``, and pass the return value (a ``NodeId``) as the first parameter for :ref:`getNodeLineColor(partId, lineIndex) <api_ref/viewing/classes/Communicator.Model.getNodeLineColor>`, would it be valid to pass a :ref:`Communicator.NodeId` value for the :ref:`Communicator.PartId` parameter? 

	In TypeScript, because the Communicator API defines a :ref:`Communicator.PartId` as a type of :ref:`Communicator.NodeId`, in our hypothetical call to ``getNodeLineColor(partId, lineIndex)`` there will be no type compatibility issues with passing the value of ``myViewerInstance.selectionManager.getFirst().getNodeId()`` for the :ref:`Communicator.PartId` parameter. 

	In terms of API behavior for both TypeScript and Javascript users, as long as the :ref:`Communicator.NodeType` of the Node in question is indeed a Part (and not a PMI, CADView, Sheet, or other :ref:`Communicator.NodeType`), then the function will behave as expected.

	To query a Node in order to find out its type, call ``getNodeType()``.
	

.. admonition:: How do I access the attributes/properties of a CAD file in HC?

	First you have to make sure to add this option to the `converter.exe` command line:
	
	:doc:`--sc_export_attributes "true" </api_ref/data_import/converter-command-line-options>`
	
	Then, you can access the attributes via the XML file saved during conversion and/or in the web client like so:

	.. literalinclude:: /../../applications/client/docs/AssemblyTree.ts
		   :start-after: //! [Get_Attributes]
		   :end-before: //! [Get_Attributes]

	You can also access the attributes as you perform the translation to Stream Cache. Use the above-mentioned flag to export the attributes, and specify :option:`--output_xml_assemblytree "file.xml"`.
        You'll then be able to parse the XML file and get the attributes and other info about the model.
		

.. admonition:: I'm trying SSR and it's not working due to a GL_INVALID_VALUE error -- what does that mean?

	.. code-block:: cpp
	
		warning: SMAA disabled due to GL error: GL_INVALID_VALUE
		GL_INVALID_VALUE
		GL_INVALID_VALUE
		GL_INVALID_VALUE
		GL_INVALID_VALUE
		
	This usually means that you're trying to run on a VM without a GPU or proper 3D acceleration, or on a machine that has poor integrated graphics. Sometimes an update to the drivers can fix the problem if it has to do with integrated graphics. Oftentimes, there is nothing you can do about this except upgrade run HC on a better machine.


.. admonition:: If I'm using the SCS workflow/loading, do I need to run the server?

	No, but you lose a lot of functionality by going with the SCS workflow, including the streaming mechanism.

	
.. admonition:: What does the "BAD_STREAM_VERSION" message in the Communicator server logs mean?

	If you're seeing the following error message, you most likely have an old version of the web viewer JavaScript either cached in your browser or in your web application that you are trying to use with a newer version of HOOPS Communicator::

		<OPEN_MODEL_FAILED reason="BAD_STREAM_VERSION" expected="66" actual="59">

	Upgrading to the latest version of the web viewer JavaScript should fix this error.


.. admonition:: How does HC handle units?

	A :doc:`PRC file </prog_guide/viewing/data_model/stream_cache/sc-and-prc>` can have multiple units for different subassemblies, which is something HC keeps track of and resolves. You can query the unit multiplier from the model object which is the same for the whole model using ``myModel.getUnitMultiplier();``.

	For more information about units, please see the :doc:`Working with Units </prog_guide/data_import/authoring/data-import-units>` section.

	
.. admonition:: When I start my web application the default viewer just displays a spinner in the bottom left and never does anything else.

	This means there was some kind of error in your JavaScript or error contacting the Service Broker that wasn't handled. Open the debugger in your web browser and have a look at the console output. There is usually an error that will start you down the correct debugging path.

	
.. admonition:: I'm seeing the error "Web page was not allowed to create a WebGL context" in the web browser debug console.

	.. code-block:: cpp
	
		Could not create canvas: Web page was not allowed to create a WebGL context.
		
	This usually means that the machine doesn't have a sufficient graphics card/GPU to run 3D graphics apps in the browser. Often times we'll see this when a user is trying to access HC from a VM or when they are accessing a machine via Microsoft Remote Desktop. RDP disables 3D acceleration (although in some cases it seems not to) so it causes issues.

	A good test is to try this link and see if WebGL works: http://webglsamples.org/aquarium/aquarium.html
	This will help you determine if the problem is HC specific or not.

	
.. admonition:: I'm seeing a "no status file" error in the web viewer when I try to load it.

	This indicates there is an issue with your stream cache directory. It's usually one of the following:

	* The root file in your stream cache is corrupt/damaged/not there
	* The stream cache directory is not accessible from your viewing instances
	* The stream cache directory does not exist
	* The stream cache directory was not specified correctly in your settings file


.. admonition:: Is animation supported in HC?

	Yes. During the 2021 release cycle, an :doc:`HOOPS Web Viewer Animation API </prog_guide/viewing/animation>` was added.

	
.. admonition:: In libconverter on Linux, how do I fix the following 'undefined reference' error?

	``undefined reference to 'Communicator::Importer::Init(Communicator::Converter*, std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> >, int)'``
	
	As of HOOPS Communicator 2019, we use GCC 6.3.1 (specifically, the version from devtoolset-6 6.1 on CentOS 6.9) with -std=c++11. Please note that we are not using the C++11 ABI that is used by default by GCC 5 and later, so code that calls functions in :doc:`libconverter </api_ref/data_import/libconverter/classes>` (and probably any other code that interacts with that code) needs to be compiled with the ``-D_GLIBCXX_USE_CXX11_ABI=0`` flag. Using this flag is likely the solution to the error listed above.
