
\section{How To include objects in a XML simulation}
If you have the same object appearing several times in your simulation, you may find convenient to be able to describe it only once, and then, only include this description. But you may need to specify parameters of this object, or apply basic transformations (translation, rotation, scale).


\subsection{Include an object}
\par
The basic command to include an object to your scene is:
\begin{verbatim}
<include name="YourObjectName" href="PathToYourXMLFile/YourFile.xml" />  
\end{verbatim}
This will load the content of the xml file you specified in { \bf href} under a new node called { \bf YourObjectName}.
\par
Now, you may want to modify some parameters of this special object. Simply add the name of the parameter followed by its value. When you main scene will be loaded, it will replace all the occurrences of this parameter by the value you wrote. {\bf Remember:} in the object description must appear all the parameters your want to modify! The only parameter that can't be modified is {\bf type}, specify the nature of a component.
\begin{verbatim}
<include name="YourObjectName1" href="PathToYourXMLFile/Object.xml" color="red"/>  
<include name="YourObjectName2" href="PathToYourXMLFile/Object.xml" color="blue"/>  
\end{verbatim}
Two entities of the same object will be created under two different nodes, {\bf YourObjectName1} and {\bf YourObjectName2}. In Object.xml, the visual model has a default value for the parameter {\bf color}. Then, when you will launch your scene, the first object will appear in red, and the second in blue, but at the same position.
\par
To apply some basic transformations, translation, rotation, scale, simply specify in you Object.xml default values for translation, rotation and scale. Then, you will be able to include your object specifying new configurations.\\
In Object.xml, typically express:
 \begin{itemize}
   \item the MechanicalObjects :
\begin{verbatim}
<Object type="MechanicalObject" 
        dx="0" dy="0" dz="0" rx="0" ry="0" rz="0" scale="1.0"/>
\end{verbatim}
   \item  the VisualModels
   
\begin{verbatim}
<Object type="OglModel" fileMesh="YouMesh.obj" 
        color="white" 
        dx="0" dy="0" dz="0" rx="0" ry="0" rz="0" scale="1.0"/>
\end{verbatim}

 \end{itemize}

Now, to include two object from the same file description, with a different color (or other parameter) and different position, orientation, and scale
\begin{verbatim}
<include name="YourObjectName1" href="PathToYourXMLFile/Object.xml" 
         color="red" dx="1" ry="90" scale="0.5"/>  
<include name="YourObjectName2" href="PathToYourXMLFile/Object.xml" 
         color="blue" />  
\end{verbatim}
This will translate the red object along the X axis, and do a 90 degrees rotation along the Y axis, reducing its scale with a factor 0.5.
The blue object will be loaded with no modifications.
\par
A problem may appear if several parameters have the same name, and you only want to modify a special one. For instance, you have two VisualModels in your { \bf Object.xml} with the parameter color. 

\begin{verbatim}
<Object type="OglModel" name="visual1" fileMesh="YouMesh1.obj" 
        color="white" />
        ...
<Object type="OglModel" name="visual2" fileMesh="YouMesh2.obj" 
        color="white" />
\end{verbatim}
When you will include it, you want { \bf visual1} to be red, and { \bf visual2} to be blue. Simply specify before the name of the parameter, the name of the component followed by two { \bf \_ }:
\begin{verbatim}
<include name="YourObjectName1" href="PathToYourXMLFile/Object.xml" 
         visual1__color="red"  />  
<include name="YourObjectName2" href="PathToYourXMLFile/Object.xml" 
         visual2__color="blue" />  
\end{verbatim}

\subsection{Including a set of components}
The restriction of this mechanism if that the loaded file will be placed under a node. If you simply want to load one, or several components, that you would like to place inside the current node, you have to specify one keyword.
In you XML description of the components, specify as the name of the root node { \bf Group }. When this file will be loaded, the contents will be directly placed inside the current node.
One benefit would be to describe the components needed to perform the collision detection and response only one, in a { \bf Group } XML file, and simply include it at the beginning of the scene files.
\begin{verbatim}
<Node name="Group">
        <Object type="CollisionPipeline" name="DefaultCollisionPipeline" depth="6"/>
        <Object type="BruteForceDetection" name="Detection" />
        <Object type="MinProximityIntersection" name="Proximity" 
                alarmDistance="0.3" contactDistance="0.2" />
        <Object type="CollisionResponse" name="Response" response="default" />
        <Object type="CollisionGroup" name="collisionGroup" />
</Node>
\end{verbatim}

And to include it, just use the same mechanism but { \bf WITHOUT} specifying a name.
\begin{verbatim}
<include href="PathToYourXMLFile/Components.xml" />
\end{verbatim}

If you decide that you want to place these components under a new node, simply specify a name, this will overwrite the keyword { \bf Group}.
\begin{verbatim}
<include href="PathToYourXMLFile/Components.xml" name="UnderNode"/>
\end{verbatim}

\subsection{Commented examples}
The scene { \bf Sofa/examples/Demos/chainHybrid.scn} has been created using the include mechanism. We described several kind of Torus, and they are included defining a new position, and orientation.
The scene { \bf Sofa/examples/Components/forcefield/StiffSpringForceField.scn} is using the { \bf Group} keyword to only include a special component.
The include mechanism is highly used for the topologies. To have dynamic topologies, several components are needed, a TopologyContainer, a TopologyModifier, a TopologyAlgorithms, a GeometryAlgorithms. We have already created these set of components for the EdgeSetTopology, ManifoldEdgeSetTopology, QuadSetTopology, TriangleSetTopology, HexahedronSetTopology, PointSetTopology, TetrahedronSetTopology. Several examples in {\bf Sofa/examples/Components/topology} are using them.
