##################
The model XML file
##################

.. program:: converter

In this chapter, we will discuss the Converter utility in HOOPS Communicator and discuss how we can generate additional information and data by specifying additional options. 

* Converter overview
* Generating the XML file
* Parsing the XML output
* Linking IDs to application data

---------------------

Use Converter to generate files
===============================

As shown in the Getting Started guide, the Converter utility inside HOOPS Communicator can be used to convert your native models into stream cache. However, Converter can control and generate additional data outputs depending on additional command line parameters. A full list of command line parameters can be found :doc:`here </api_ref/data_import/converter-command-line-options>`.

In addition to generating stream cache files, HOOPS Converter can parse a model file, assign unique IDs to each part, and build an XML file based on that data. You can then correlate these model parts with your external data and incorporate it into HOOPS Web Viewer using those unique IDs. The XML file is generated during the conversion process if HOOPS Converter is passed the :option:`--output_xml_assemblytree` option.

In the *data/xml* subdirectory, you will find several converted models in XML form. You can use Converter to convert any supported models to SCS, and additionally, generate the XML assembly tree file and thumbnail image. Ensure that you are not only running this command from the tutorial directory, but that you are also replacing the {license-key} variable with your own. To convert the Moto model for example, your command would look similar to the following: 

.. code-block:: none

   ..\..\authoring\converter\bin\<platform>\converter.exe --output_scs "moto" --output_xml_assemblytree ".\data\xml\moto.xml" --input "..\..\authoring\converter\example\_data\Moto\_MOTO_X.asm" --license "{license-key}" --output_png ".\data\thumbnails\moto.png" --png_camera_explicit "-100,50,-300,-100,50,0,0,1,0,1500,1500,orthographic" --png_transparent_background 1

Note that we provided additional options for how the thumbnail image was generated. These options are not required, but they are included to customize the appearance of our thumbnail in our application. Here, we provided a particular camera position to snap the thumbnail, and made the thumbnail background transparent.


Inspect the output of the XML
=============================

If we inspect the XML output, we can see that the model structure has been broken down by XML tags and that each of these parts has a particular ID. There is a lot of additional data contained in these files, but the tag we are concerned with is the ``<BodyInstance>`` tag and associated IDs.

.. code-block:: xml

	<ProductOccurence Id="16" Name="HEAD_TUBE" ExchangeId="" LayerId="65535" Style="65535" Behaviour="1" FilePath="..\_data\Moto\head_tube.prt.1" InstanceRef="41" IsPart="true">
		<BodyInstance Id="43" Name="HEAD_TUBE" ExchangeId="" LayerId="65535" Behaviour="1" MeshInstanceKey="1 1" BodyRef="42"/>
	</ProductOccurence>
	<ProductOccurence Id="41" Name="" ExchangeId="" Behaviour="1" FilePath="..\_data\Moto\head_tube.prt.1" IsPart="true">
		<PartDefinition Id="40" Name="" ExchangeId="" Behaviour="1" FilePath="..\_data\Moto\head_tube.prt.1">
			<Body Id="42" Name="HEAD_TUBE" ExchangeId="" LayerId="65535" Style="1" Behaviour="1">
			<PhysicalProperties CenterOfGravity="-391.0351815832648867 400.1200154829452345 1.131901695573741858e-05" Surface="43980.409501" Volume="44003.966599"/>
			</Body>
		</PartDefinition>
	</ProductOccurence>

The ``<BodyInstance>`` tags indicate selectable geometry that will be rendered in the scene. We will want to query any associated data with these rendered parts. We can parse the XML and use the ``ID`` and ``Name`` attributes of each ``<BodyInstance>`` to link additional data to that ID. For large files, it is recommended you write a parsing utility to help distill this data, but in this exercise, we have parsed and set up our "database" information for you.

Rather than going through the motions of setting up a SQL-like database, we will use JSON objects containing our model data to emulate the process of querying and attaching this data to your application. In the *.\data\database* subdirectory, you will find the provided JSON files for each provided model. The JSON file is an array of objects, each containing the parsed ID from the XML file, and additional part information.

.. code-block:: none

	{
	    "NodeData": [
	        {
	            "ID": 43,
	            "Manufacturer": "Kane Co.",
	            "Location": "Warehouse 1",
	            "Price": 100.00,
	            "Stock": 327,
	            "Reserved": 23
	        },

	...

Here, we are attaching model information like Manufacturer, Storage Location, Price, and Stock information. This is information that we are associating to the part via the parsed XML ID. When we set up our viewing application, we can query this data and use the ID to link it to the correct part in the scene.

To further break it down using the example snippets above, when we click on the "HEAD_TUBE" part in our scene, HOOPS Communicator knows the assigned ID for this part (43). Using that ID, we query that database for that ID, and when it is found, we return the additional data associated with that ID.
