Actin®  Version 5.1.0
Software for Robotics Simulation and Control
ActinViewer Quickstart

Overview

Energid’s ActinViewer serves as both a useful tool and an introduction to the Actin toolkit, as it is built using the toolkit and all the capabilities of ActinViewer are available through the toolkit. The ActinViewer can be used to both simulate the motion of robots and to directly control the robotic hardware. It has many powerful features that allow for real time end-effector or joint level control of robotic systems. This chapter is intended to be a complete guide for AcinViewer. ActinViewer is built on top of the Actin toolkit. Qt libaries are used in its graphical user interface so it is cross-platform, and ActinViewer has been tested to run on Windows, Mac, and many variants of Linux. The figure below shows ActinViewer in action with a system of many manipulators including a 14 DOF bi handed manipulator on a rail, a 7 DOF arm and a 6 DOF arm. The initial configuration is as shown in the figure below. This interface can be customized and will change as additional plugins are loaded.

actinViewerQuickstart_image1.png
A system with many manipulators used to demonstrate ActinViewer features.

File Options

The following options are related to file operations.

File Open

To open an Actin model file, select Open from the File menu or press Ctrl+O. This will bring up a File Open dialog. You can also open another file format and ActinViewer will convert that file into an Actin file format. The list of supported file formats is given in the table below.

File formats supported by ActinViewer.
Supported format File extensions
Energid *.ecx; *.ecz
Xml *.xml; *.xml.gz
3DS *.3ds
ASE *.ase
CFG *.cfg
DTED *.dted
SDTED *.sdted
S3DS *.s3ds
SASE *.sase
Tecplot *.stec
VRML97 *.wrl
OpenSceneGraph *.osg; *.ive; *.zip
OpenFlight *.flt
VEC *.vec
STL *.stl
Wavefront *.obj

Another way to open a file is to drag a file from Windows Explorer (or equivalent program under Linux) and drop it inside ActinViewer. The drag-and-drop mechanism only allows supported file formats (determined by the file extension) to be dropped and opened in ActinViewer.

File Merge

The merge operation allows another Actin model to merge with the currently open model. This allows you to combine two or more Actin models together to create a new model. With an open model, simply select Merge from the File menu. This will bring up a File Open dialog so you can select the file to merge. An example of the merge operation of two Actin models is illustrated in the figure below.

actinViewerQuickstart_image2.png
Merge operation with two Actin models.

Loading or Saving System State

The system state (placement and configuration of the manipulators and objects) can be saved and loaded from file. The first option is “Load State…” This will bring up a dialog that allows the user to load a state saved in a file into the simulation. This will cause all the manipulators in the system to move to the loaded state. The second option is “Save State …” This allows the user to save the current state of the system so that it can be loaded later.

Save Operations

Save ( Ctrl + S )

This option saves the currently open Actin model into the same file. If the model is not an Actin model, then it will bring up a dialog to let the user save the model as an Actin model in a new file.

Save As..

Save the simulation as a new file or change the file extension.

Mouse Interaction Modes

Mouse interaction is an important part of ActinViewer. ActinViewer can be placed into one of three different mouse interaction modes, Eyepoint, Guide, or Center of Interest (COI).

View Mode

To change the view of the model using the mouse, click on the button to enter View Mode.

actinViewerQuickstart_image3.png

View Mode

View Mode allows you to move your point of view around the object. Pressing the left mouse button and dragging changes the rotation about the center of interest. Using one of the following combinations will increase or decrease the eyepoint distance from the center of interest – scroll wheel, middle mouse button while dragging up/down, or left+right mouse buttons while dragging up/down.

Holding the Ctrl key makes the viewer behave like in COI mode.

Note
The eyepoint is always looking and rotating about the center of interest.

Guide Mode

Guide mode places a guide frame at the active motion constraint. When holding Shift, a dragger appears at the guide frame. This dragger is used to 'guide' a selected motion constraint to a desired position and orientation within the scene. Clicking and dragging with the mouse moves the active constraint in the viewer plane when Shift is held. otherwise, the view is changed.

actinViewerQuickstart_image4.png

Guide Mode (hold shift to use the dragger)

dragger2.png
Dragger

Think of this dragger frame as a constraint which sets desired position for the link at which the constraint is set (typically the last link). You can move the position and orientation of the dragger by clicking and dragging the mouse. Dragging with the left mouse button changes the translation of the dragger. Dragging with the right mouse button changes the orientation. Clicking on the dragger itself will constrain the motion of the dragger along whever axis or ring is dragged. Scrolling the mouse wheel moves the dragger towards and away from the screen. Holding the X key will constrain the movement to the x axis of the viewer plane, and Y will constrain the movement to the y axis of the viewer plane. The robot model will not try and move unless the simulation is running. Run the simulation by clicking play and the robot should follow the guide frame.

Using the Dragger

If you dont have one selected When you first enter guide mode, the Edit Motion Constraint dialog box will be displayed to select an active motion constraint (end-effector). More detail on the Select End-Effector dialog can be found in the next section when we discuss controlling motion constraints. To select a different constraint, use the pull-down menu just to the right of the guide button icon.

This mode lets you translate (left mouse button) and rotate (right mouse button) as well as zoom in and out (scroll wheel / middle mouse button).

Holding the Shift key shows the dragger at the active constraint. Releasing makes the viewer behave like in view mode.

Note
Your motion depends on the types of constraints being used. If you are using a point motion contraint, then rotating the guide frame (orientation) will have no effect on the placement. Motion constraint movement only occurs while the simulation is running. Press the Play button on the Simulation toolbar to start or continue the simulation.

Center of Interest (COI) Mode

actinViewerQuickstart_image6.png

Center of Interest Mode

Sometimes it is desirable to focus on one particular area over another. Moving the COI allows one to more easily manipulate the eyepoint around this location. The COI is denoted by a reddish-orange sphere within the scene. The left mouse button will translate the COI along the X and Y axes, while the middle mouse wheel / button will translate along the Z axis.

Pressing the Shift key makes the viewer behave like view mode.

Guide to Motion Constraint Sets (End Effector Sets)

Motion constraint sets are used to conveniently apply multiple constraints on the same manipulator (robot). On Cyton robot, the most commonly desired motion constraint is located on the Wrist Roll link. If we wanted to constrain its position and orientation we would use a frame motion constraint (frame end effector), and if we wanted to just constrain its position we would use a point end effector. So we don't have to edit the motion constraint each time we wish to switch between them, we create a motion constraint set for each configuration. Out of the box, the cyton.ecz model should include 3 motion constraint sets, "Point EE", "Frame EE", and "Joint control end-effector set". The last one is used internally by the software when you use the sliders in the numerical configuration of manipulators dialog. There are a number of different ways to switch between them. One way is through the position control system dialog. To get there navigate in the menu bar to Edit -> Position Control System -> Control System Parameters. A dialog will appear and in the bottom right corner is a menu to switch between, create, delete, and rename motion constraint sets.

Note
"Motion Constraint" and "End-Effector" or "Motion Constraint Set" and "End Effector Set" are equivalent. "Motion Constraint" is a new terminology which replaces previous "End Effector" or "End Effector Constraint" term.

controlSysMotionConstSets.png
Control system dialog

Alternatively, a quicker way to switch between motion constraint sets is to use the active control parameters toolbar below.

activeControlParam.png

Here you can change between active motion constraint sets, as well as other parameters.

activeControlPointMotionConst.png
activeControlFrameMotionConst.png
Active control parameters

The third and fastest way to switch between motion constraint sets is using the S key on the keyboard. Pressing the S key will instantly switch to the next motion constraint set, with the exception of the special "Joint control end-effector set" which you cannot control with the dragger.

Numerical Configuration of Manipulators

The manipulator configuration dialog allows for joint level and end effector level control numerically. This dialog will appear after clicking the slider icon in the toolbar. From the Joints tab, you can move each joint individually using the slider bars, or by inputting the joint position numerically in the Joint Position column (when the simulation is not running). This can be seen below.

manipConfigJoints_.png
Numerical configuration of joints

From the Motion Constraints tab, you can numerically edit the pose of the end effectors on the manipulator to change the constraint. This can be seen below.

manipConfigMotionConstraints.png
Numerical configuration of Manipulators

Information Overlays

In ActinViewer, you can display some information visually by overlaying it on to the robots in the system. In this section, a model of the 6-DOF UR-10 manipulator will be used for illustration purposes.

actinViewerQuickstart_image7.png
UR-10 manipulator with no overlay.

Bounding Volumes

actinViewerQuickstart_image8.png

Pressing the Bounding Volumes button on the toolbar shows the bounding volumes of all links of all manipulators in the system. Bounding volumes are displayed in a transparent green color. Bounding volumes can be of any shape but the most common is the capsule. Bounding volumes are used in collision reasoning to speed up distance calculations.

actinViewerQuickstart_image9.png
UR-10 manipulator with bounding volumes.

Mass Property Ellipsoids

actinViewerQuickstart_image10.png

Pressing the Mass Property Ellipsoids button will overlay the mass property ellipsoids onto the links of manipulators. This is a great visualization tool to help verify whether the mass properties (inertia matrices) are reasonable.

actinViewerQuickstart_image11.png
UR-10 manipulator with mass property ellipsoids.

Show Frames

actinViewerQuickstart_image12.png

Sometimes it is very insightful to be able to see all the frames (primary and D-H) of the robot. Clicking on the Show Frames button will show all those frames as well as the world coordinate frame. The world coordinate frame is typically designated by the frame with the longest axes. For all frames, the red, green, and blue axes represent the X, Y, and Z axes, respectively. The primary frame and the D-H frame of a link can occasionally coincide so they will appear as one frame. This is the case for all links of the UR-10 manipulator as shown below.

actinViewerQuickstart_image13.png
UR-10 manipulator with primary and D-H frames.

Naturally, these information overlays can be turned on/off independent of one anther and therefore can be combined as shown in the figure below.

actinViewerQuickstart_image14.png
UR-10 manipulator with all information overlays.

Running Simulation

A key purpose of ActinViewer is to let the user run robot simulations, either dynamic or kinematic. To start a simulation, the user simply presses the play button. The simulation will keep running. At this point, the user can select an active motion constraint and control it using the mouse. This process is detailed in the End Effector Control Page. The pause button allows the user to pause the simulation. To resume the simulation, simply press the play button again. To stop and reset the simulation, press the stop button. This will bring the simulation back to the initial state.

Guide to Plugins

The ActinViewer is based off of the powerful Actin toolkit and handles all the complex robot control mathematics including position, velocity, acceleration control, as well as the complex forward and inverse kinematics involved in joint and end effector control. The software includes a multitude of different plugins for many different purposes. Many of the core viewer functionalities are in fact plugins to the viewer, including the manipulator configuration plugin (slider bars), end effector control plugin (dragger), and hardware plugins that actually command the hardware from the viewer.

The viewer includes plugins to add keyboard shortcuts, interface with joysticks, game controllers, and 3D mice, create primitive 3D shapes, program sequences of actions or movements, control the robot over the network, and modify the views of the environment and model. These plugins have the extension .ecp, and can be found in the bin directory of your installation location. They can be loaded from the menu bar under Plugins -> Load Plugin when the simulation is stopped.

Interface

Menu Bar

File: Contains options relating to the ecz/xml file in use, including opening, saving, saving images, merging files, and exiting the viewer. Edit: Contains options relating to viewer preferences, editing the joint configuration, control system parameters, configuring Cyton hardware, and manipulations depending on what plugins are loaded. View: Contains options relating to viewing toolbar elements, status bar, dragger, and plugins such as the environment info plugin. Simulation: Contains options to start, stop, and pause the simulation. Plugins: Contains options to load and unload the plugins Help: Contains options to provide help, as well as example code.

Toolbar

Open: Open a simulation file.

open.png

Save: Save a simulation file, defaults to saving all the plugins that are loaded as well.

save.png

Run Simulation: Run the simulation.

play.png

Pause Simulation: Pause the simulation.

pause.png

Stop Simulation: Stop the simulation.

stop.png

View Mode: Enter view mode, which allows you to manipulate the view of the model.

viewMode.png

Guide Mode: Enter guide mode, which allows you to manipulate the model by its active motion constraint.

guideMode.png

Show Center of Interest: Shows the center of interest, and allows manipulation of the view in relation to it.

COIMode.png

Numerical Configuration of Manipulators: Brings up the numerical configuration of manipulators dialog, where you can move each joint with a slider and move end effectors (set motion constraints) numerically.

manipConfig.png

Shortcut Keys

F5 Start the simulation.

F6 Stop the simulation.

X Holding "X" will constrain the movement to the x axis of the viewer plane.

Y Holding "Y" will constrain the movement to the y axis of the viewer plane.

E Pressing "E" switches active motion constraint of a given manipulator (only between Point, Frame, and other multiple degree of motion constraints).

M Pressing "M" switches active manipulator (robot or primitive shape) to the next manipulator with a multiple degree of motion constraint.

S Pressing "S" switches active motion constraint set.

D Pressing "D" switches active control descriptor (can be configured for collision detection /avoidance).

F Pressing "F" switches active control method.

W Pressing "W" adds a waypoint to the active waypoint sequence, a joint frame to the active joint frame sequence, or starts/stops recording a path to the active path action.

P Pressing "P" adds a calibration point at the current simulated location in the multipoint calibration gui.

Shift Holding shift changes mouse behavior to move the dragger (instead of the view), when in guide mode.

Space Bar Pressing the space bar resets the 3D view to the default position and orientation

Ctrl + V Switch to view mode

Ctrl + G Switch to guide mode

Ctrl + S Save file

Ctrl + O Open file

Created by Energid Technologies www.energid.com
Copyright © 2016 Energid. All trademarks mentioned in this document are property of their respective owners.