Actin  Version 5.5.5
Software for Robotics Simulation and Control
Shapes and Bounding Volumes

The Shape Primitive Plugin provides a way to add visible 3D shapes to links, add bounding volumes, and configure their geometry and properties through a graphical user interface. Using this plugin, you can add shape primitives as new manipulators to the system. These primitives currently include box, capsule, circular lozenge, cone, cylinder, lozenge, sphere, and triangular lozenge. Some of which can be seen below. The shape properties, including color and size, can be configured through this interface.

Some shapes currently supported

You can access the plugin interface by clicking the Edit -> Bounding Volumes and Shapes option in the menu bar. The figure below shows a 7-DOF Cyton model in the viewer. The right side of the viewer is a dialog for managing shape primitives.

Cyton model with dialog for managing shape primitives

Select the desired manipulator from the drop-down box at the top. The "Links:" table lists all the links in the selected manipulator. Clicking on a link will display the shape or shapes (if more than one shape) representing the geometry of that link in the "Shape" table. If the shape is not one of the supported shape primitives, it will be disabled (grayed out), which is the case in this example since the shape is a polygon physical extent (generated from CAD) and not a primitive. In addition, the "Shape Attributes" table is disabled if the shape is not supported.

Adding Shape Primitives

We can add an object into the scene by clicking on the Edit -> Add Shape to System... menu item. This will display the add new shape dialog which allows you to select which shape primitive to be added as a new manipulator as well as the label (name). In this example, a capsule is chosen with the label of "Obstacle." In the table on the right side of the dialog, you can specify the initial shape attributes (size and appearance). There is a check box to initialize the manipulator as "fixed base" or not (this can be changed later in the control system, and in the joint configuration dialog).

Dialog for adding a shape primitive as a manipulator

Clicking the OK button will add the capsule in the scene and update the dialog accordingly by switching to the new manipulator. Note that the newly added capsule is selected and enabled and its attributes are displayed in the "Shape Attributes" table. The newly created manipulator as seen below can then be re-positioned by changing its Base Location in the Manipulator Configuration dialog or by using the dragger in the context menu.

Shape created with above parameters

Editing Shape Attributes

Edit Shape Color

The default color of the added shape is grey but can be configured in the "Shape Attributes" table as well. You can configure the ambient, diffuse, and specular colors as well as the shininess. Clicking on one of the color values will bring up a color dialog for you to choose a desired color. In this case we select the diffuse color of the capsule.

Color Picker

Selecting the blue color will change the diffuse color of the shape.

Cyton model and a newly edited capsule as obstacle

Adding Shapes to Existing Shapes

You can create more complex objects than simple primitives by combining multiple primitives into a shape union. For example, you can add to the obstacle by adding a lozenge. To add a shape into a union, you starts by clicking the '+' button in the Shapes area (above the Shapes table). It will bring up the new shape dialog shown below. You can then select a shape primitive type (lozenge) to be added and click OK.


The new shape is added to the manipulator, and can be seen in the Shapes table. You can then configure the size and location and color to the desired value.


You can also add shapes to the underlying link geomtery using the same method. Below we can see 2 capsules added to the gripper finger as some form of tooling.


Moving the Shape In the Manipulator

To move the shape in the manipulator, go to the dragger tab, and enable the dragger using the checkbox. then click and drag the dragger to move the shape. you can also enter the transformation values into the dragger widget to position the shape.


Edit Geometry

To change the geomtery of a shape, change the values in the shape attributes table. The properties to change vary depending on the shape. for example, the sphere only has a radius, while the lozenge has a radius, width, and height.


Editing Bounding Volumes

In addition to being able to add and configure shapes, this tool is capable of configuring bounding volumes as long as they are shape primitives. By default, a capsule bounding volume is automatically created for each link. These dimensions are tuned in the model before being packaged in the installer. These bounding volumes should be sized in such a way to cover all the parts of the link and therefore large enough to detect safe collision distances. Selecting the "Bounding Volumes" radio button will enter the bounding volume mode. The bounding volumes will then be rendered, and the selected bounding volume will be outlined in red as shown below. In this mode, the bounding volume shapes will be displayed in the shapes table instead of the link shapes. You can then edit the size, location, and color of the bounding volume shape in the same manner as the link shape primitives.

Cyton model with bounding volumes

With this plugin it is also possible to save out and load the bounding volumes.

Copy and Paste

The ability to copy and paste a shape provides a convenient way to create bounding volumes or shape objects with identical or similar shapes. To copy a shape, you can simply click on the Copy button.


You can then paste the shape on the same link or a different one, by clicking the Paste button.


The shape will be copied and pasted to the desired link. This feature significantly reduces the time it takes to set up bounding volumes for parts (links) with same or similar geometries, e.g. wheels of a rover or modules of a modular robot arm.