#################
XML Assembly Tree
#################

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 the 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 :doc:`output_xml_assemblytree </api_ref/data_import/converter-command-line-options>` argument.


Generating XML data
-------------------

The following will generate an XML file called *my3dModel.xml* based on the model in *my3dModel.CATPart*.

.. code-block:: none

	converter --output_sc "models/my3dmodel" --output_xml_assemblytree "my3dModel.xml" --input "c:\temp\my3dModel.CATPart"


XML Data Format
---------------

Below is a snippet from an XML file generated by HOOPS Converter. Note the flat structure of the file. The developer is responsible for parsing the XML.

.. raw:: html
	
	<!--HC 4.0-->
	<Root>
		<ModelFile Name="_micro engine" ModellerType="3" Unit="1" UnitFromCAD="0" VM="9" Vm="0">
			<ProductOccurence Id="3" Name="HOUSING" PersistentId="2" Layer="65535" Style="65535" Behaviour="1" FilePath="D:\webgl\SampleModelsForInitalDemo\Micro_engine_CV5/housing .CATPart" ModellerType="3" ProductLoadStatus="4" ProductFlag="2" Unit="1" UnitFromCAD="1">
				<PartDefinition Name="HOUSING" PersistentId="2" Layer="65535" Style="65535" Behaviour="1">
					<RepItem SCKey_Mesh="1" Name="MechanicalTool.1" PersistentId="9" Layer="65535" Style="1" Behaviour="1">
						<Transformation RelativeTransfo="1 0 0 0 0 1 0 0 0 0 1 0 0 0 0 1" />
						<UserData Title="CV5FACENAME">
							<UserValue Type="String" Value="EdgeFillet.71396" />
						</UserData>
					</RepItem>
				</PartDefinition>
				<Transformation RelativeTransfo="1 0 0 0 0 1 0 0 0 0 1 0 0 0 0 1" />         
			</ProductOccurence>
			<ProductOccurence Id="2" SCKey_Instance="1" InstanceRef="3" Name="HOUSING(HOUSING.1)" PersistentId="4" Layer="65535" Style="0" Behaviour="1" FilePath="D:\webgl\SampleModelsForInitalDemo\Micro_engine_CV5\_micro engine.CATProduct" ModellerType="3" ProductLoadStatus="0" ProductFlag="0" Unit="1" UnitFromCAD="0">
				<Transformation RelativeTransfo="1 0 -0 0 -0 1 0 0 0 0 1 0 21.5 -0.5 -0.31000000000000227 1" />          
			</ProductOccurence>

Each part of the model is associated with a ``<ProductOccurence>`` tag in the XML. The part name and file path identifiers will already be known to you. You simply need to associate either identifier with the ID generated by HOOPS Converter (represented by the XML ``Id`` attribute). You can use this ID via APIs in the HOOPS Web Viewer to control object properties, the HOOPS Web Viewer also returns this ID when responding to a query or selection event.

We export as much data as possible to the XML file. Here are the definitions of some of the more important tags:

* *Name* - The name of the part or assembly.
* *FilePath* - The location of the file containing this part/assembly.
* *Id* - The ID of the part/assembly.
* *Children* - The IDs of the children of this assembly.
* *InstanceRef* - The ID which defines the instantiated part/assembly.
* *UnitFromCAD* - A boolean indicating if the Unit should be applied to the model.
* *Unit* - A double which indicates the size of 1 unit in millimeters.
* *ModellerType* - A flag which indicates the source of the data.  See table below for more details.
* *ProductFlag* - A flag which indicates if the node represents a configuration, part or assembly.  See table below for more details. (for future use)
* *Layer* - The layer to which this product occurrence is associated with.
* *Behaviour* - Flag that describes the inheritance properties of the graphical data.  Refer to the HOOPS Exchange documentation if you need more information.


Below is the table of values for the ModellerType flag:

.. csv-table::
	:header: "ModellerType", "Description"

	"0", "Unknown"
	"1", "Retired"
	"2", "CatiaV4"
	"3", "CatiaV5"
	"4", "Retired"
	"5", "NX"
	"6", "Parasolid"
	"7", "Retired"
	"8", "Retired"
	"9", "IGES"
	"10", "Retired"
	"11", "VDA-FS"
	"12", "STL"
	"13", "VRML"
	"14", "Retired"
	"15", "ACIS"
	"16", "ProE"
	"17", "Retired"
	"18", "STEP"
	"19", "I-DEAS"
	"20", "JT"
	"21", "Retired"
	"22", "SolidWorks"
	"23", "CGR"
	"24", "PRC"
	"25", "XVL"
	"26", "Retired"
	"27", "Retired"
	"28", "Retired"
	"29", "3DXML"
	"30", "Inventor"
	"31", "Retired"
	"32", "PDF"
	"33", "U3D"
	"34", "IFC"
	"35", "Retired"
	"36", "Retired"
	"37", "Solid Edge"
	"38", "OBJ"
	"39", "Retired"
	"40", "Retired"
	"41", "3DS"
	"42", "Retired"
	"43", "Rhino"
	"44", "XML"
	
Below is the table of values for ProductFlag:

.. csv-table::
	:header: "ProductFlag", "Description"
	
	"0x0001", "Default container, configuration or view"
	"0x0002", "The product occurrence is internal. Only used when the product occurrence has no father."
	"0x0004", "The product occurrence is a container."
	"0x0008", "The product occurrence is a configuration."
	"0x0010", "The product occurrence is a view."
	"0x0100", "The configuration does not include the model data or the model data is not up to date."


Connecting HOOPS Web Viewer
---------------------------

How do you use the ID attribute to show your data in HOOPS Web Viewer? There are many ways to do this, and you are free to choose the one most suitable for your application. A common example use case is as follows:

#. Model file is processed by HOOPS Converter, and the XML integration file is generated
#. Developer parses the XML file and creates a mapping between each part of the model and corresponding external data. He does this by correlating the HOOPS Converter ID with either the part name or model file path.
#. Developer writes logic to retrieve data in response to user interaction in HOOPS Web Viewer. If you're storing your data locally, this could entail looking it up in a data structure. You could also make a call to a remote database or web server.
#. Developer calls the appropriate API functions to display the external data in HOOPS Web Viewer.
