Actin  Version 5.5.5
Software for Robotics Simulation and Control
Motion Constraints

What is a Motion Constraint?

In order to control a manipulator in Actin, motion constraints can be associated with links of the manipulators or robots. The user can control the desired placement of the end effector using the mouse and dragger, the jogging interface, or using the manipulation director.

A motion constraint is a way to constrain the motion of a link of a manipulator. The base class used for this is EcEndEffector. A link can have any number of constraints as long as it is not overconstrained. When the simulation is running, the control system will move the manipulator's joints to achieve the desired positions and velocities, while obeying all active motion constraints (in addition to joint velocity limits and position limits). Motion constraints are typically used to constrain the motion of an end effector such as a gripper or other tool. In most cases the terms "Motion Constraint" and "End Effector" can be used interchangably.

In most cases the terms "Motion Constraint" and "End Effector" can be used interchangably

Using the end effector control plugin (a default Actin Viewer plugin), it is possible to create and modify motion constraints. It can also be used to command one motion constraint at a time to go to any arbitrary position and orientation in space. The motion constraint dragger is what the viewer uses to specify the desired placement of an end-effector. The motion of the manipulator to achive the desired placement depends entirely on how the constraints are configured. The figure below shows the dragger (with red, green, and blue axes and rings, which correspond to the X, Y, and Z axes, respectively).

Dragger is shown with the red, green, blue axes

What is a Motion Constraint Set?

A motion constraint set (EcEndEffectorSet) stores any number of motion constraints for a manipulator. When a motion constraint set is "active" for a manipulator the motion constraints within the set will be obeyed by the control system. A manipulator can have multiple motion constraint sets, and the active set for a manipulator can be swtiched at runtime. This is useful to allow the nature of the control to change with the task at hand. for example, an arm with a tool changer may need a frame constraint (EcFrameEndEffector) to position and attach with a tool (a drill), but a free spin in Z constraint (EcFreeSpinInZEndEffector) for when the arm needs to position the drill. Having a motion constraint set for each type of task.

What is the Joint Control Motion Constraint Set?

There is a special motion constraint set with a special index (EcVelocityController::JOINT_CONTROL_INDEX) that handles coordinated joint level motions. Actin handles this differently because sometimes joint level motion is requred for reasons such as: jogging, motions where linear motion is not requred, and path planning motions. Typically the motion constraint set contains a EcCoordinatedJointEndEffector, as well as others as requried. The EcCoordinatedJointEndEffector is usually configured to control all the driven joints of the robot or mechanism. For a robot arm it is usually each revolute joint. However for a Stewart Table, only the piston joints are configured (the ball joint component joints are ignored or configured with seperate motion constraints).

What is a Tool Offset?

Motion constraints are by default controlled from the link's primary frame (EcPrimaryFrame). Many motion constraints support an internal offset to control the constraint from a known position on the link which is typically the tool mounting position on the last link. Tool offsets are an offset on top of that that is stored in the EcPositionController (in a vector). These offsets can be used by any constraint on the manipulator. A common configuration is a tool offset for each tool that the robot might have attached. Tool offsets can change at runtime and can be updated using this plugin or through a Tool Offset Direction".

Welder tool offset

Select Active Motion Constraint

Before you can move the dragger, you need to first enter guide mode by clicking the Guide Mode button.

Guide Mode

When you enter the guide mode, the active motion constraint should show a dragger at it's current desired placement. To edit the motion constraints, open the "Motion Constraints" dialog from Edit->Advanced->Motion Constraints... or from the arrow next to the guide mode toolbar button. This dialog allows you to add, remove or modify a motion constraint.


Show/Edit Motion Constraints

For the typical manipulator, there is a constraint added to the final link (typically a wrist roll). This constrains the movement of the end of arm tooling.

Dragger is shown with the red, green, blue axes

The "Edit Motion Constraints" dialog is used to create and edit motion constraints and motion constraint sets for each manipulator. The left side of the dialog shows a tree with each manipulator (only those with the control system turned on), which can have multiple motion constraint sets, each of which can contain multiple motion constraints. The joint control motion constraint set is the last one listed under each manipulator. Only one constraint can be driven by the dragger at any given point of time. All the constraints specified in the active motion constraint set are applied at any time.

The "Show Hidden Motion Constraints" option displays all the constraints including any hidden constraints.

Show hidden constraints

To select which motion constraint is actively being controlled by the dragger in guide mode, select a motion constraint from the tree and either click the button in the bottom right, or right click on the constraint and select to "set active".

Set Constraint as Active

Edit Motion Constraint dialog

Controlling Motion Constraints Using the Dragger

Once a position motion constraint (frame, point etc.) is selected and if simulation is running, it's possible to move the dragger by dragging with either the left or right mouse buttons clicked and held anywhere in the render window. Holding down the left mouse button will allow you to change the position of the Guide Frame and the right mouse button allows you to rotate the Guide Frame. You can move the Dragger in and out of render window using the mouse scroll wheel, middle mouse button while dragging up/down, or left+right mouse buttons while dragging up/down. To show the dragger dialog, click the arrow next to the guide mode button, and select to "Show Dragger Dialog".

Show dragger dialog

This will render the dragger dialog. Here you can numerically set the dragger position and orientation by editing the combo boxes. If "Update on release" is not checked, then values will update as the dragger is moved in the render window. If the box is checked, then the value will not update until the mouse is released. If the "Alignment" box is checked, then the dragger will align with the system coordinate frame, as opposed to the corresponding link coordinate frame.

Dragger dialog

To edit a motion constraint or motion constraint set, you can open the Edit Motion Constraint dialog by pressing the down-arrow button on the right of the Guide mode button. This will drop down the Motion Constraints... menu item. Select it to bring up the Edit motion constraints dialog.

Edit Motion Constraints

Another way to select the active motion constraint is to use the mouse picking process. Move the mouse so the cursor hovers above the link whose motion constraint you would like to control. Then, right-clicking on it will bring up one of the two context menus shown below, depending on whether there is an existing motion constraint attached to the selected link.

(a) link with existing motion constraint

(b) link without motion constraint

If there is already a motion constraint attached to the selected link, the context menu in (a) will appear and let you set it as the active one, edit it, or remove it. If there is no motion constraint for that link, then you have an option to add one to that link.

Edit and Add Motion Constraints

Edit Motion Constraint

By selecting a motion constraint, or by selecting "Edit Motion Constraint" from the context menu in (a), you can edit the properties of the selected motion constraint.


This interface allows the user to select which link the motion constraint is associated with, and the type of motion constraint There are different types of motion constraints such as pointEndEffector, frameEndEffector, freeSpinInZEndEffector etc... Each type of constraint has certain attributes that could be set by the user. For example, the user can set the position offset, or the maximum linear velocity and acceleration for a pointEndEffector. Depending on the type of motion constraint, the position control system will run to satisfy the desired constraint. For a point motion constraint (pointEndEffector), the simulation will move the link to a specific position in space. For a frame motion constraint (frameEndEffector), it will move to a given position and orientation.

Edit Motion Constraint dialog

Motion constraints can be defined in the system coordinate frame, or relative to the coordinate frame of a link in the same manipulator. To make a constraint relative to another link on the manipulator, check the Relative To Link check box, which will render a combo box that will allow for the selection of the link desired to be the relative link.

Relative to link

Add Motion Constraint

There are two ways to add a motion constraint to a link. The first method is to select a motion constraint set and click the add button in the Edit Motion Constraint dialog. Pressing the add button will add a constraint (default pointEndEffector constraint) to that motion constraint set. You can then select the newly created constraint to edit the type of constraint, which link it's associated with, and its parameters. Alternatively, you can select Attach Motion Constraint from the context menu in (b). Simply move the mouse to hover above the desired link and right-click the mouse to bring up the context menu. This will add a motion constraint to the currently active motion constraint set. Selecting the Attach Motion Constraint will bring up the Add Motion Constraint dialog, which looks just like the Edit Motion Constraint dialog. Change the constraint's parameters as desired and press the OK button to add the motion constraint to the active motion constraint set. Or press the Cancel button if you change your mind and cancel the add process.

Add Motion Constraint

Remove Motion Constraint

A motion constraint associated with a link can be removed by either Right clicking on the link for which a constraint has to be removed and select the "Remove Motion Constraint" option, shown in (a), or from the Edit Motion Constraint dialog (above). Select the motion constraint from the motion constraint set on the left and click on the Remove button (or use the context menu).

Remove Motion Constraint

Tool Offsets

The Tool Offset Manager is used to edit the vector of tool offsets that can be applied to motion constraints. To show this dialog, click the Edit -> Tool Offsets button, or the button under guide mode. This is also availiable from within the motion constraint editor.

Edit Tool Offsets

To manage the tool offsets, first select which manipulator position controller to edit. Then you are able to add and remove offsets using the "+ Add" and "x Delete" buttons. To edit the transformation of the tool offset, select it from the drop down list and make changes in the dialog below it.


To apply a tool offset to a motion constraint, the constraint must check the box "Use External Offset" and have an index specified to select which element of the tool offset vector to use. This offset will be applied on top of any base end effector offset which might also exist.

Enable the Tool Offset for the Motion Constraint

Types of Motion Constraints

Actin supports many types of motion constraints in order to achieve the desired motions for many types of applications. This list is not exhaustive.

  1. Point End Effector (EcPointEndEffector): This constraint is used to constrain the position of the link.
  2. Frame End Effector (EcFrameEndEffector): This constraint is used to constrain the position and orientation of the link.
  3. Free Spin in Z (EcFreeSpinInZEndEffector): This constraint is used to constrain the position and the roll and pitch of the link (a frameEndEffector without Z rotation).
  4. Linear Constraint End Effector (EcLinearConstraintEndEffector): This constraint is used to constrain the angle of a joint or multiple joints.
  5. One DOF Gripper End Effector (EcOneDofGripperEndEffector): This constraint is used to constrain the angle of a joint or multiple joints, most useful for constraining a gripper.
  6. Coordinated Joint End Effector (EcCoordinatedJointEndEffector): This constraint is used to constrain the angles of multiple joints.
  7. General Spatial End Effector (EcGeneralSpatialEndEffector): This constraint is used to construct a general constraint that can range from 1 to 6 degrees of freedom.
  8. X End Effector (EcXEndEffector): This constraint is used to constrain link motion only in the X direction.
  9. XY End Effector (EcXyEndEffector): This constraint is used to constrain link motion in the XY plane.
  10. Look At End Effector (EcLookAtEndEffector): This constraint is used to constrain a link (X Axis) pointed to a specific position.

Editing Motion Constraints Parameters

Motion constriants have a number of parameters which are configurable. Different constraint types have different parameters, but some of them are common to many types.

Frame Offset: X, Y, Z offset from the primary frame of the link where the constraint will be controlled from. Tool offsets are applied to this offset.

Frame Angle: Roll, Pitch, Yaw offset from the primary frame of the link where the constraint will be controlled from. Tool offsets are applied to this offset.

Max Linear Velocity: Maximum linear velocity (velocity is relative to system nominally, or relative to link when configured when configured relative).

Max Angular Velocity: Maximum angular velocity (velocity is relative to system nominally, or relative to link when configured when configured relative).

Max Linear Acceleration: Maximum linear acceleration.

Max Angular Acceleration: Maximum angular acceleration.

Velocity Profile Type: Trapezoidal (default), THREEHALVES, or PROPORTIONAL

Is Hard Constraint: Motion constraint is hard (motion will stop if unachievable), or soft (uses soft constraint handler )

Allow Changing Desired Placement: Motion constraint can either be movable (default) or can be fixed. Thi si useful for hidden constaints like ball joints (pointEndEffector) and 4 bar linkages (xyEndEffectors)

Is Editable: Determines if the constraints are hidden to the user or not.

Example Configurations

Below are some common examples of how a motion constraint can be applied to a task.

Typical Constraint Setups

A typical robot arm will be configured with motion constraint sets for a variety of tasks.

Frame motion constraint

The joint control motion constaint will contain all of the joints of the arm.

Joint control motion constraint

The gripper in this case has a oneDofGripper motion constaint to handle open/close, and a linear constraint to handle the redundancy caused by the "under articulated" nature of this gripper.

Gripper motion constraint

More Advanced Constraint Setups

A closed kinematic chain model such as a Stewart Table is more complicated. At first glance, the configuration is simple, with a point or frame at the table to constrain the motion.

Point EE for Stewart Table

This model has hidden relative point constriants to close the kinematic chain at 5 of the 6 pistons. The other piston has 3 virtual joints between it and the table top.

Showing hidden point constraints

These 5 hidden relative point constraints also exist in the Joint control motion constraint set. and the coordinateJointEndEffector has had all but the driven 6 piston joints removed from it. This allows the user or program to control either the table top pose or the piston positions.

Joint control set configuration

A model with an arm and positioner (merged as one manipulator) can use multiple constraints on the same link. One of which is a free spin in Z constraint that is relative to the rotary table of the positioner (the part is attached to it).

Free spin in Z

the second constraint on the same link is a general spatial constraint, that constrains the Angular X and Y in the system frame. This is used to keep the welder oriented vertically.

General Spatial Constraint