Actin®  Version 5.1.0
Software for Robotics Simulation and Control
Simulation Builder Guide

Simulation Builder

Structure

The Simulation Buider provides a scripting interface for creating a simulation scene in Actin. One can construct a single manipulator using the Manipulator Builder or combine multiple manipulators using Scene Builder. In both cases, the EcSimulationBuilderContainer class needs to be constructed. Inside the container class either manipulator builder loader or scene builder loader needs to be called and the "allLoaderSimulationBuilder.ecp" plugin needs to be loaded.

The manipulator builder and the scene builder have two commond components:

  • a manipulator data vector (manipulatorDataVector),
  • a point of view data (povData).

For a Manipulator Builder, the manipulator data vector contains a Manipulator Data Collection implemented by EcSbManipulatorCollectionData Class. For a Scene Builder, the manipulator data vector contains several Manipulator Data implemented by EcSbManipulatorData class. The structure of Manipulator Builder is given in the following example,

1 <simulationBuilderContainer>
2 
3  <allLoaderManipulatorBuilder library="allLoaderSimulationBuilder.ecp">
4 
5  <manipulatorDataVector>
6  <manipulatorCollectionData> ... </manipulatorCollectionData>
7  </manipulatorDataVector>
8 
9  <povDataFlag>...</povDataFlag>
10  <povData> ... </povData>
11 
12  </allLoaderManipulatorBuilder>
13 
14 </simulationBuilderContainer>

The structure of Scene Builder is given in the following example,

1 <simulationBuilderContainer>
2 
3  <allLoaderSceneBuilder library="allLoaderSimulationBuilder.ecp">
4 
5  <manipulatorDataVector>
6  <manipulatorData> ... </manipulatorData>
7  ...
8  <manipulatorData> ... </manipulatorData>
9  </manipulatorDataVector>
10 
11  <povDataFlag>...</povDataFlag>
12  <povData>...</povData>
13 
14  </allLoaderSceneBuilder>
15 
16 </simulationBuilderContainer>

Point of View

The povDataFlag is a boolean variable controls whether the point of view data (povData) specified inside the povData tag will be loaded when entering the simulation scene. The povData tag control the initial visualization parameters for the simulation. It contains four components:

Point of View Attributes.
Attribute Tag Description
centerofInterest Center of the view
eyePoint Position of the eye
fieldOfView Angle of view
up an vector constrain the possible rotation of the view

The visualization parameters of a simulation scene can be specified using the following example

1 <povDataFlag>1</povDataFlag>
2 <povData>
3  <centerOfInterest x="0" y="0" z="0.3"/>
4  <eyePoint x="0" y="10" z="0.3"/>
5  <fieldOfView> 0.2 </fieldOfView>
6  <up x="0" y="0" z="1"/>
7 </povData>

Manipulator Builder

Manipulator Data Collection

The manipulator Builder is a scripting interface for creating a single robot, manipulator, and environmental object. The .ecx file extension is used to denote a manipulator builder script. The structure of a script for creating a manipulator using XML is shown in the following example:

1 <simulationBuilderContainer>
2 <allLoaderManipulatorBuilder library="allLoaderSimulationBuilder.ecp">
3 
4  <manipulatorDataVector>
5  <manipulatorCollectionData>
6 
7  <physicalExtent>
8  <filename>...</filename>
9  <scaleFactor>...</scaleFactor>
10  </physicalExtent>
11 
12  <position>
13  <orientation .../>
14  <translation .../>
15  </position>
16 
17  <links>
18  <element>...</element>
19  ...
20  <element>...</element>
21  </links>
22 
23  <endEffectorSet>...</endEffectorSet>
24 
25  </manipulatorCollectionData>
26  </manipulatorDataVector>
27 
28  <povDataFlag> ... </povDataFlag>
29  <povData> ... </povData>
30 
31 </allLoaderManipulatorBuilder>
32 </simulationBuilderContainer>

The physicalExtent attribute specifies the base of the manipulator and the position attribute describe the coordinate and orientation this base in the simulation scene. The attribute scaleFactor tag will be introduced in Links section. Every element inside the links attribute describe a individual link of the manipulator. The endEffectorSet attribute describe the Motion Constraints of the manipulator.

Links

The links attribute is the key in assembling a manipulator using script. A links attribute contains several elements and each element describe one link in the manipulator. The structure of links attribute is shown in the following example:

1 <links>
2  <element>
3 
4  <physicalExtent>
5  <filename>...</filename>
6  <scaleFactor>...</scaleFactor>
7  </physicalExtent>
8 
9  <kinematics>
10  <parentLabel>...</parentLabel>
11 
12  <dh>
13  <jointType>...</jointType>
14  <dhType>...</dhType>
15  <a>...</a>
16  <alpha>...</alpha>
17  <d>...</d>
18  <theta>...</theta>
19  </dh>
20  </kinematics>
21 
22  <jointActuator>
23  <jointAngle>...</jointAngle>
24  <jointLowerLimit>...</jointLowerLimit>
25  <jointUpperLimit>...</jointUpperLimit>
26  </jointActuator>
27 
28  </element>
29  ...
30  <element>...</element>
31 </links>

Physical Extent

In addition to the filename attribute, the physicalExtent attribute also include a scaleFactor attribute, this attribute is used to scale the model generated by the solidWorks.

Note
This attribute is often used to convert the SolidWorks generated model to standard unit (m-kg-s).

A link model can be generated by SolidWorks using two methods: SolidWorks converter or export as STL file. If the converter is used, the unit conversion is conducted automatically during the model conversion. On the other hand, if the STL file is generated, the unit conversion need to be specified in XML using scaleFactor attribute.

Note
For example, if the model is built in SolidWorks using mm, and the model is exported by STL file, then a scaleFactor of 0.001 need to be used to convert the unit from mm to m.

Links Kinematic and Actuator

The kinematics attribute describe kinematic properties of the element. The parentLabel describe the label of its parent link, which is the link the element is linked to. The dh attribute specified the Denavit-Hartenberg parameters of the joint with respect to the element's precursory frame. In Actin, a link can have three different kinds of frame, a DH Frame which is created when SolidWorks part is created, a Prime Frame based on which the geometric properties of the link are defined and multiple Named Frame which are user specified.

Note
By default, the primal frame coincides with the DH frame. If the model is generated by STL file, then there is only one frame, the DH frame, associated to a model.

In Actin, a primal frame of an element is defined based on its DH frame and named frames are defined based on the primal frame. The Precursor Frame of an element can be primal frame or one of the named frame of its parent link. Therefore, the dh parameters, specified in the XML file, define the transformation from an elment's Precursory Frame to its DH Frame. Mathematically, the kinematic chain of the manipulator is defined as follows,

\( \mathbf T_{DH_{i-1}}^{DH_{i}} = \mathbf T_{DH_{i-1}}^{P_{i}}\mathbf T_{P_{i}}^{DH_{i}} \)

The precursory transformation of the 0th link is the identity transformation and the \(DH_i, P_i\) denote the DH frame and precursory frame of ith link. In each element the transformation \( \mathbf T_{P_{i}}^{DH_{i}}\) is specified through the dh parameters.

Note
If the model is generated by STL file, the precursory frame is not supported and \( \mathbf T_{DH_{i-1}}^{P_{i}} = \mathbf I \).

Actin supports five conventions of representing homogeneous transformation, Craig, Paul, General Craig and General Paul. With General prefix, i.e. for cases General Paul and General Craig, the precursory transformation is taken into account when performing the homogeneous transformation. That is to say, the dh paramters specifies the homogeneous transformation \(\mathbf T_{P_{i}}^{DH_{i}}\). On the other hand, the homogeneous transformation is directly specified by the four DH parameters for the no prefix cases. The detailed definitions of Paul and Craig types of DH parameters in Actin are given by

\( \mathbf T_{P_{i}}^{DH_{i}} = \mathbf T_{Paul} = Rot_{z,\theta_i}Trans_{z,d_i}Trans_{x,a_i}Rot_{x,\alpha_i} \)

\( \mathbf T_{P_{i}}^{DH_{i}} = \mathbf T_{Craig} = Rot_{x,\alpha_i}Trans_{x,a_i}Trans_{z,d_i}Rot_{z,\theta_i} \)

The complete descriptions of the four conventions mentioned above are listed in the following table

Actin DH Parameters Conventions.
Convention DH Specified Transformation
Paul \( \mathbf T_{DH_{i-1}}^{DH_{i}} = \mathbf T_{Paul} \)
Craig \( \mathbf T_{DH_{i-1}}^{DH_{i}} = \mathbf T_{Craig} \)
General Paul \( \mathbf T_{DH_{i-1}}^{DH_{i}} = \mathbf T_{DH_{i-1}}^{P_{i}}\mathbf T_{Paul} \)
General Craig \( \mathbf T_{DH_{i-1}}^{DH_{i}} = \mathbf T_{DH_{i-1}}^{P_{i}}\mathbf T_{Craig} \)
Kinematic_Chain.png
Diagram of Kinematic Chain.

Inside the dh attribute, either rotational or prismatic joint can be specified by the jointType attribute. The default dhType is generalPaul, user can also choose paul, craig or generalCraig type of dh parameter. The a, alpha, d and theta are real number that initialize the transformation matrix. The jointActuator attribute initialize the joint angle and specifies the upper and lower limits of the actuator.

Example

The following script show a complete example of assembling a UR5 manipulator using XML file and the example files can be downloaded from UR5 Model. The following figures shows the parts that used to assemble the UR5 Manipulator.

Manipulator_Parts.png
Diagram of UR5 Manipulator Parts.
1 <simulationBuilderContainer>
2 <allLoaderManipulatorBuilder library="allLoaderSimulationBuilder.ecp">
3 
4  <manipulatorDataVector>
5  <manipulatorCollectionData>
6 
7  <physicalExtent>
8  <filename>UR5.ecz</filename>
9  </physicalExtent>
10 
11  <position>
12  <orientation q0="1" q1="0" q2="0" q3="0"/>
13  <translation x="0" y="0" z="0"/>
14  </position>
15 
16  <links>
17 
18  <element>
19  <physicalExtent>
20  <filename>Base.ecz</filename>
21  </physicalExtent>
22  <kinematics>
23  <parentLabel>UR5</parentLabel>
24  <dh>
25  <jointType>rotational</jointType>
26  <dhType>generalPaul</dhType>
27  <a>0</a>
28  <alpha>1.5707963267948966</alpha>
29  <d>0.089159</d>
30  <theta>0</theta>
31  </dh>
32  </kinematics>
33  <jointActuator>
34  <jointAngle> 0 </jointAngle>
35  <jointLowerLimit> -6.2657320146596431811560498588741 </jointLowerLimit>
36  <jointUpperLimit> 6.2657320146596431811560498588741 </jointUpperLimit>
37  </jointActuator>
38  </element>
39 
40  <element>
41  <physicalExtent>
42  <filename>Shoulder.ecz</filename>
43  </physicalExtent>
44  <kinematics>
45  <parentLabel>Base</parentLabel>
46  <dh>
47  <jointType>rotational</jointType>
48  <dhType>generalPaul</dhType>
49  <a>-0.42500</a>
50  <alpha>0</alpha>
51  <d>0</d>
52  <theta>0</theta>
53  </dh>
54  </kinematics>
55  <jointActuator>
56  <jointAngle> 0 </jointAngle>
57  <jointLowerLimit> -6.2657320146596431811560498588741 </jointLowerLimit>
58  <jointUpperLimit> 6.2657320146596431811560498588741 </jointUpperLimit>
59  </jointActuator>
60  </element>
61 
62  <element>
63  <physicalExtent>
64  <filename>Elbow.ecz</filename>
65  </physicalExtent>
66  <kinematics>
67  <parentLabel>Shoulder</parentLabel>
68  <dh>
69  <jointType>rotational</jointType>
70  <dhType>generalPaul</dhType>
71  <a>-0.39225</a>
72  <alpha>0</alpha>
73  <d>0</d>
74  <theta>0</theta>
75  </dh>
76  </kinematics>
77  <jointActuator>
78  <jointAngle> 0 </jointAngle>
79  <jointLowerLimit> -6.2657320146596431811560498588741 </jointLowerLimit>
80  <jointUpperLimit> 6.2657320146596431811560498588741 </jointUpperLimit>
81  </jointActuator>
82  </element>
83 
84  <element>
85  <physicalExtent>
86  <filename>Wrist1.ecz</filename>
87  </physicalExtent>
88  <kinematics>
89  <parentLabel>Elbow</parentLabel>
90  <dh>
91  <jointType>rotational</jointType>
92  <dhType>generalPaul</dhType>
93  <a>0</a>
94  <alpha>1.570796327</alpha>
95  <d>0.10915</d>
96  <theta>0</theta>
97  </dh>
98  </kinematics>
99  <jointActuator>
100  <jointAngle> 0 </jointAngle>
101  <jointLowerLimit> -6.2657320146596431811560498588741 </jointLowerLimit>
102  <jointUpperLimit> 6.2657320146596431811560498588741 </jointUpperLimit>
103  </jointActuator>
104  </element>
105 
106  <element>
107  <physicalExtent>
108  <filename>Wrist2.ecz</filename>
109  </physicalExtent>
110  <kinematics>
111  <parentLabel>Wrist1</parentLabel>
112  <dh>
113  <jointType>rotational</jointType>
114  <dhType>generalPaul</dhType>
115  <a>0</a>
116  <alpha>-1.570796327</alpha>
117  <d>0.09465</d>
118  <theta>0</theta>
119  </dh>
120  </kinematics>
121  <jointActuator>
122  <jointAngle> 0 </jointAngle>
123  <jointLowerLimit> -6.2657320146596431811560498588741 </jointLowerLimit>
124  <jointUpperLimit> 6.2657320146596431811560498588741 </jointUpperLimit>
125  </jointActuator>
126  </element>
127 
128  <element>
129  <physicalExtent>
130  <filename>Wrist3.ecz</filename>
131  </physicalExtent>
132  <kinematics>
133  <parentLabel>Wrist2</parentLabel>
134  <dh>
135  <jointType>rotational</jointType>
136  <dhType>generalPaul</dhType>
137  <a>0</a>
138  <alpha>0</alpha>
139  <d>0.0823</d>
140  <theta>0</theta>
141  </dh>
142  </kinematics>
143  <jointActuator>
144  <jointAngle> 0 </jointAngle>
145  <jointLowerLimit> -6.2657320146596431811560498588741 </jointLowerLimit>
146  <jointUpperLimit> 6.2657320146596431811560498588741 </jointUpperLimit>
147  </jointActuator>
148  </element>
149 
150  </links>
151 
152  <endEffectorSet>
153  <endEffectors size="1">
154  <pointEndEffector>
155  <errorWeight>1</errorWeight>
156  <externalOffsetIndex>0</externalOffsetIndex>
157  <isEditable>1</isEditable>
158  <isHardConstraint>1</isHardConstraint>
159  <linkIdentifier>Wrist3</linkIdentifier>
160  <point x="0" y="0" z="0.01" />
161  <pointMotionFilter>
162  <accelerationThreshold>150</accelerationThreshold>
163  <decelerationThreshold>150</decelerationThreshold>
164  <exponent>0</exponent>
165  <filteringMode>trapezoidal</filteringMode>
166  <linearGain>200</linearGain>
167  <threshold>2.5</threshold>
168  </pointMotionFilter>
169  <useExternalOffset>1</useExternalOffset>
170  </pointEndEffector>
171  </endEffectors>
172  </endEffectorSet>
173 
174  </manipulatorCollectionData>
175  </manipulatorDataVector>
176 
177  <povDataFlag>1</povDataFlag>
178  <povData>
179  <centerOfInterest x="0" y="0" z="0.3"/>
180  <eyePoint x="0" y="10" z="0.3"/>
181  <fieldOfView> 0.2 </fieldOfView>
182  <up x="0" y="0" z="1"/>
183  </povData>
184 
185 </allLoaderManipulatorBuilder>
186 </simulationBuilderContainer>

After loading this file in the ActinViewer, the complete manipulator is shown in the follwing figure,

Manipulator.png
The UR5 Manipulator Assembled from Parts.

Scene Builder

Structure

The Scene Builder is a scripting interface for creating a simulation environment "scene" from multiple robots, manipulators, and environmental objects. The .ecx file extension is used to denote a scene builder script. In other words, a simulation scene is constructed based on existing robots, manipulators and environment objects, etc. The structure of a scene builder script is shown in the following example,

1 <simulationBuilderContainer>
2  <allLoaderSceneBuilder library="allLoaderSimulationBuilder.ecp">
3  <manipulatorDataVector>
4  <manipulatorData>...</manipulatorData>
5  ...
6  <manipulatorData>...</manipulatorData>
7  </manipulatorDataVector>
8 
9  <povDataFlag> ... </povDataFlag>
10  <povData> ... </povData>
11  </allLoaderSceneBuilder>
12 </simulationBuilderContainer>

Instead of using manipulator builder loader, the scene builder loader is used. Inside the manipulator data vector, multiple manipulator data is included and each data represents one manipulator, robot or enviroment object.

Manipulator Data

A manipulator data describe the file that store the manipulator and the position of the manipulator in the simulation scene. A complete example is shown in the following script.

1 <simulationBuilderContainer>
2  <allLoaderSceneBuilder library="allLoaderSimulationBuilder.ecp">
3  <manipulatorDataVector>
4  <manipulatorData>
5  <filename>manipulatorBuilderPa10.ecx</filename>
6  <position>
7  <translation x="0.5" y="0" z="0"/>
8  <orientation q0="1" q1="0" q2="0" q3="0"/>
9  </position>
10  </manipulatorData>
11  <manipulatorData>
12  <filename>manipulatorBuilderPa10.ecx</filename>
13  <position>
14  <translation x="-0.5" y="0" z="0"/>
15  <orientation q0="1" q1="0" q2="0" q3="0"/>
16  </position>
17  </manipulatorData>
18  </manipulatorDataVector>
19  <povDataFlag>1</povDataFlag>
20  <povData>
21  <centerOfInterest x="0" y="0" z="0"/>
22  <eyePoint x="0" y="10" z="0"/>
23  <fieldOfView> 0.2 </fieldOfView>
24  <up x="0" y="0" z="1"/>
25  </povData>
26  </allLoaderSceneBuilder>
27 </simulationBuilderContainer>
Created by Energid Technologies www.energid.com
Copyright © 2016 Energid. All trademarks mentioned in this document are property of their respective owners.