Example - Model Editing

Purpose

In this example, you will add a body and an actuator to an existing OpenSim model by editing its xml file. You can find the model file (arm26.osim) in the models folder under your OpenSim installation directory.

You will need to download an XML editor to work through this example. Some free options include:

notepad++ (http://notepad-plus.sourceforge.net/uk/site.htm)
XMLMarker (http://symbolclick.com/download.htm)

You can also download a pdf of this page by clicking on the Tools link in the top right corner and selecting "Export to PDF".

Connecting an Additional Segment to the Model

Open Model File in XML. Use an XML editor (e.g., Notepad++) to open the OpenSim model file (e.g., arm26.osim). When collapsed to the 3^rd level (e.g., Alt+3 in Notepad++), your model file should look like the figure below.
In Notepad ++ if the model file does not have the markup or ability to collapse levels, you may need to set the Language to XML (Menu Bar > Language > XML)

Explore the Model. The Model tag has eight main sets named: BodySet, ConstraintSet, ForceSet, MarkerSet, ContactGeometrySet, ControllerSet, ProbeSet, and ComponentSet.

worddav1d1ebadb970d79102731244c2e45019f.png [imported from a Word document]

Explore the Body Set. The BodySet tag has three Body objects named ground, r_humerus, and r_ulna_radius_hand.

worddavf399bd90e3480a8db55fa6722883fb0d.png [imported from a Word document]

Save a copy of the Model File. From the XML editor, save a copy of the OpenSim model file (arm26_with_bucket.osim).
Add New Body. Add a new Body named bucket immediately below the Body named r_ulna_radius_hand.

worddavf9d84c6971a433064cb5ebd629b42b4d.png [imported from a Word document]

<Body name="bucket">
 
</Body>

Specify Mass Properties. Add tags and enter values for the mass, mass_center, inertia_xx, inertia_yy, inertia_zz, interia_xy, inertia_xz, and inertia_yz for the bucket as seen below:

worddav2eefa3c3adec40f1de1d59c77d0a769e.png [imported from a Word document]

<mass>1.0</mass>
<mass_center> 0.0 -0.1 0.0</mass_center>
<inertia_xx>0.0024</inertia_xx>
<inertia_yy>0.0028</inertia_yy>
<inertia_zz>0.0224</inertia_zz>
<inertia_xy>0.0</inertia_xy>
<inertia_xz>0.0</inertia_xz>
<inertia_yz>0.0</inertia_yz>

Specify Joint. Add tags and names for the PinJoint and parent_body, and tags and values for location_in_parent, orientation_in_parent, location, and orientation as seen below:

<Joint>
	<PinJoint name="r_handle">
		<parent_body> r_ulna_radius_hand </parent_body>
        <location_in_parent> 0.031    -0.31    0.07    </location_in_parent>
        <orientation_in_parent>    0.0    0.0    0.0    </orientation_in_parent>
        <location> 0.0    0.0    0.0    </location>
        <orientation> 0.0    0.0    0.0    </orientation>
	</PinJoint>
</Joint>

The location_in_parent and orientation_in_parent tags define the position and orientation of the joint with respect to the parent body origin. In the above example, the vector from the parent body r_ulna_radius_hand to the joint r_handle is [0.031 -0.031 0.07] and the orientation of the joint (in a zero pose) is exactly the same as the orientation of the parent body (in a zero pose). The location_in_parent and orientation_in_parent vectors should be given in the coordinate frame of the parent body. In most cases, the location_in_parent and orientation_in_parent tags are all that's required to specify the new joint (in which case, the child body origin, e.g., bucket, would be located at the joint center of r_handle). Additionally, the local location and orientation offset of the joint center with respect to the child body origin can be specified using the location and orientation tags. The above description of joints in OpenSim is illustrated here: JointReferenceFrames.jpg

Specify Generalized Coordinate. Add a tag and name for the Coordinate, and add tags and values for motion type, default_value, default_speed_value, initial_value, range, clamped, and locked as seen below:
Place the code within the PinJoint tags, immediately following the orientation tag

worddava155480bbf5fed1467977dd1fd046fe3.png [imported from a Word document]

<!--Generalized coordinates parameterizing this joint-->
<CoordinateSet name="">
	<objects>
    	<Coordinate name="r_handle_rot">
        	<!--Coordinate can describe rotational, translational, or coupled values.  Defaults to rotational-->
            <motion_type> rotational </motion_type>
            <default_value> 0.0 </default_value>
            <default_speed_value> 0.0 </default_speed_value>
            <initial_value> 0.0 </initial_value>
            <range> -3.14159265 3.14159265 </range>
            <clamped> false </clamped>
            <locked> false </locked>
            <prescribed_function/>
         </Coordinate>
	</objects>
    <groups/>
</CoordinateSet>

Specify Geometry File. Add a tag for VisibleObject and add the appropriate tags for GeometrySet and other properties as seen below:
Place code after the Joint definition, but still within the body tags

image2012-3-15 11:56:50.png

<VisibleObject name="">
	<!--Set of geometry files and associated attributes, allow .vtp, .stl, .obj-->
    <GeometrySet>
		<!--Three scale factors for display purposes: scaleX, scaleY, scaleZ-->
    	<scale_factors>1 1 1</scale_factors>
    	<!--transform relative to owner specified as 3 rotations (rad) followed by 3 translations rX rY rZ tx ty tz-->
    	<transform>0 0 0 0 0 0</transform>
    	<!--Whether to show a coordinate frame-->
    	<show_axes>false</show_axes> <!--Display Pref. 0:Hide 1:Wire 3:Flat 4:Shaded. Can be overridden for individual geometries-->
    	<display_preference>4</display_preference>
    </GeometrySet>
                        
</VisibleObject>
<WrapObjectSet/>

Specify DisplayGeometry including Geometry_File in the GeometrySet

<objects>
	<DisplayGeometry>
    	<!--Name of geometry file .vtp, .stl, .obj-->
        <geometry_file>bucket.vtp</geometry_file>
        <!--Color used to display the geometry when visible-->
        <color>1 1 1</color>
        <!--Name of texture file .jpg, .bmp-->
        <texture_file></texture_file>
        <!--in body transform specified as 3 rotations (rad) followed by 3 translations rX rY rZ tx ty tz-->
        <transform>0 0 0 0 0 0</transform>
        <!--Three scale factors for display purposes: scaleX scaleY scaleZ-->
        <scale_factors>1 1 1</scale_factors>
        <!--Display Pref. 0:Hide 1:Wire 3:Flat 4:Shaded-->
        <display_preference>4</display_preference>
        <!--Display opacity between 0.0 and 1.0-->
        <opacity>1</opacity>
	</DisplayGeometry>
</objects>

Save Model File. From the XML editor, save the OpenSim model file (e.g., arm26_with_bucket.osim). Now open your new model in OpenSim to see the bucket!

Adding an Additional Actuator

Explore the ForceSet. The ForceSet tag has six Thelen2003Muscle objects named TRIlong, TRIlat, TRImed, BIClong, BICshort, and BRA.

worddava340771a504fc0c1691e55dd43866385.png [imported from a Word document]

Add New Actuator. Add a CoordinateActuator object named r_handle_rot_force immediately below the Thelen2003Muscle named BRA. Associate this CoordinateActuator with the r_handle_rot coordinate and specify an optimal_force of 1000.

image2012-3-15 11:53:47.png

<CoordinateActuator name="handle_motor">
	<isDisabled>false</isDisabled>
	<!--Minimum allowed value for control signal. Used primarily when solving for control values-->
	<min_control>-infinity</min_control>
	<!--Maximum allowed value for control signal. Used primarily when solving for control values-->
	<max_control>infinity</max_control>
	<coordinate>r_handle_rot</coordinate>
	<optimal_force>1</optimal_force>
</CoordinateActuator>

Save Model File. From the XML editor, save the OpenSim model file (e.g., arm26_with_bucket.osim).

Return to the list of Examples and Tutorials