Main Content

Import Visual Representations of Robot Models

You can import into a virtual world in Simulink® 3D Animation™ robot and robot environment 3-D models that are defined using unified robot description format (.urdf) or simulation description format (.sdf). The URDF file format is an XML file format that defines various model (typically robot) properties. When you import from a URDF file, only the visual representation of the model is imported. This representation typically refers to model component shape files, defined as STL or DAE files. You can import visual properties of the objects present in the URDF or SDF files into corresponding hierarchical structure of Transform nodes containing IndexedFaceSet objects with textures.

URDF and SDF files use Collada DAE and STL formats to define visual properties of scene objects.

To import visual representation of robots, in the 3D World Editor, select Nodes > Import From. Then select STL File, Physical Modeling XML File, URDF File, SDF File, or COLLADA File. From the MATLAB® command line, you can use the vrimport function to import .urdf, .dae, .stl, and .sdf files into a virtual world.

Import a DAE File

The URDF and SDF import supports a subset of the Collada DAE 3D file format (objects that are typically present in URDF and SDF files: geometric shape objects with textures).

This example imports a Collada DAE file, fox.dae, into a scene with predefined grid, gray background, and viewpoint. The fox head is a sphere with 1-m radius, placed at the origin and looking in the direction of VRML +z-axis.

The fox.dae is shipped with the Simulink 3D Animation software. The path is matlabroot/toolbox/sl3d/sl3ddemos/fox.dae.

  1. From the MATLAB Toolstrip, in the Apps tab, in the Simulation Graphics and Reporting section, click 3D World Editor.

  2. In the 3D World Editor, select File > New from Template.

  3. In the file dialog box, select the Grids folder and then select the XZGrid.x3d virtual world file.

  4. Save the virtual world in the current folder. Select File > Save as and name the virtual world file fox_dae.x3d.

  5. Import the DAE model. Select Nodes > Import From > COLLADA File. Select the fox.dae file.

  6. Open the COLLADA_fox_Transform node and set the scale field to 3 for each dimension.

Import a URDF File

In this example, the fox.urdf file refers to fox.dae file. The URDF file transforms the original DAE model so that the fox is translated to the position [4 1 0] and rotated so that it points to the VRML +x-axis direction.

The fox.urdf is shipped with the Simulink 3D Animation software. The path is matlabroot/toolbox/sl3d/sl3ddemos/fox.urdf.

  1. From the MATLAB Toolstrip, in the Apps tab, in the Simulation Graphics and Reporting section, click 3D World Editor.

  2. In the 3D World Editor, select File > New from Template.

  3. In the file dialog box, select the Grids folder and then select the XZGrid.x3d virtual world file.

  4. Save the virtual world in the current folder. Select File > Save as and name the virtual world file fox_urdf.x3d.

  5. Import the URDF model. Select Nodes > Import From > URDF File. Select the fox.urdf file.

  6. Open the URDF_visual_Transform node and set the scale field to 3 for each dimension.

Import an SDF File

SDF is an XML format that describes objects and environments for robot simulators, visualization, and control, originally developed as part of the Gazebo robot simulator. The folder in which the model.sdf file is located defines the SDF model name. This example shows how to import a simple arm link mechanism.

The example assumes that you have

  1. Download the simple_arm model folder (including all its contents) from this Gazebo model site: http://models.gazebosim.org/simple_arm/. To download all the folder contents, download and unpack the model.tar.gz file.

  2. From the MATLAB Toolstrip, in the Apps tab, in the Simulation Graphics and Reporting section, click 3D World Editor.

  3. In the 3D World Editor, select File > New from Template.

  4. In the file dialog box, select the Grids folder and then select the XZGrid.x3d virtual world file.

  5. Save the virtual world in the current folder. Select File > Save as and name the virtual world file simple_arm.x3d.

  6. Import the SDF model. Select Nodes > Import From > SDF File. In the simple_arm folder, select the model.sdf file.

  7. Open the SDF_simple_arm_Transform node and set the scale field to 3 for each dimension.

  8. The import process creates in the model hierarchy some special Transform nodes that make it easier to manipulate models. Each rotational joint in the SDF model is represented with a Transform node with the name starting with axis_. These nodes have rotation axes defined so that the model elements move consistently if you set the rotation angle to a different value.

    Change the rotation angle of a rotational joint node. For example, expand the children node, then the joint_arm_shoulder_pan_joint node, then the children, and finally, the axis_arm_shoulder_pan_joint. For the rotation field, set the fourth element to 1.

    Tip

    If you associate this virtual world with a VR Sink block in a Simulink model, you can use the VR Signal Expander block to set only the rotation angle (the fourth element of the rotation vector) of the axis_xxx Transform node rotation. Leave the first three elements of the vector unchanged. This approach preserves robot consistency with the way model authors defined movement of robot parts.

Define Viewpoint to Make Imported Model Visible

When you import a model, often it does not appear in the initial view of the virtual world. If necessary, create a viewpoint to make the imported model visible when the virtual world opens. If the imported model is not visible:

  1. In the 3D World Editor, select the ROOT node.

  2. Select Nodes > Add > Bindable > Viewpoint.

  3. To observe the imported model, navigate to a suitable location in the scene.

  4. Populate viewpoint properties with current camera settings. In the tree hierarchy pane, right-click the viewpoint and select Copy values from current camera.

  5. Save the virtual world.

Limitations

URDF import transforms robot hierarchy of links and joints into a VRML or X3D hierarchy of transforms. It imports only visualization properties from each link. Joints are represented by transforms that preserve rotation axes of the original revolute joints and axis alignment of prismatic joints.

SDF import transforms the hierarchy of SDF model objects into VRML or X3D hierarchy of transforms the same way as URDF import. It supports a subset of SDF format objects and is limited to visual objects under the Model element hierarchy. Supported Geometry elements are geometric primitives and meshes.

See Also

Functions

Related Topics