Actin  Version 5.5.5
Software for Robotics Simulation and Control
Actin System Modeling

Robotics Concepts

Some general robotics concepts to be familiar with when using Actin.

What is a Manipulator?

A manipulator is constructed from links using a tree structure.


Each joints adds 1 degree of freedom (DOF)


The number of joints, the range of motion of each joint, and the geometry of each link define the how the manipulator can move, as well as the manipulator's available workspace. Joints are typically revolute or prismatic, but custom joint types are possible.

Some examples of manipulators are

this pan-tilt module has 2 DOF
this scara robot has 4 DOF
this delta robot has 3 DOF
this robot arm has 6 DOF
the robot arm and rail combine to have 7 DOF

What is an End Effector?

An End Effector is a tool manipulated by a robot and used to perform some task. Commonly, this End Effector is manipulated in 6 degrees of freedom in space: X, Y, Z, Roll (rotation about X), Pitch (rotation about Y), and Yaw (rotation about Z). This is commonly referred to as a pose or coordinate system transformation. A typical manipulator control problem is to control the position, orientation and velocity of the end effector.


What is Kinematics?

Actin motion control solves both forward kinematics and inverse kinematics for a manipulator.

Forward Kinematics is the problem of calculating the end effector position/velocity given a set of joint positions and velocities. Inverse Kinematics is the opposite problem. Inverse Kinematics is the problem of calculating the joint positions/velocities to move the end effector in to the desired position/velocity.

What is Kinematic Redundancy?

Kinematic redundancy complicates the inverse kinematics problem. This occurs when there are more joint degrees of freedom than end effector degrees of freedom. This means that there are infinitely many joint position/velocity solutions for a given end effector position/velocity. This complication means that the inverse kinematics problem requires finding an optimal solution for the motion for a given application.

Actin System Modeling

The Actin "model" generally used/embedded for control is defined in the EcSystemControlExecutive class. This stores both a EcStatedSystem, as well as an EcPositionControlSystem.

Simplified Model

The EcStatedSystem stores all the physical parameters of the manipulators, how they are configured, and where they are in the "world". We break this into system (EcManipulatorSystem), state (EcManipulatorSystemState), and configuration (EcManipulatorSystemConfiguration).



The EcStatedSystem class stores the system. The system is composed of any number of manipulators (EcIndividualManipulator), each of which can have any number of links (EcManipulatorLink).

Actin uses the EcIndividualManipulator class to model articulated mechanisms like robot arms, articulated tooling like grippers, as well as non articulated tooling, parts, fixtures, and environments.



The links store a number of properties that describe their physical shape, how they move, and other information .


Links are indexed starting at the first link after the base link. The base link has a special index EcIndividualManipulator::BASEINDEX. So a simple chain would be EcIndividualManipulator::BASEINDEX, 0, 1, 2, ...

DH Parameters

Each link stores their own DH parameters (EcLinkKinematics), which define how the joint articulates relative to it's parent link. Actin supports multiple forms of DH parameters including:

Paul's Notation

Translation along Z

Rotation about Z

Translation along X

Rotation about X


Craig's Notation

Translation along X

Rotation about X

Translation along Z

Rotation about Z


Primary Frame

Each link has one Primary Frame, where the bounding volumes, pysical extents, mass properties, Named Frames, and EcEndEfectors are defined relative to. These are often configured manually at the base link of a manipulator (to make base "mounting" easier), as well as the last link of each chain (to make tool "mounting" easier).


Bounding Volumes

Bounding volumes are used for distance calculation and collision detection. Shapes must be convex and are typically simple (sphere, capsule, lozenge, etc.). Closed-form solutions are used for distance calculations between simple shapes while GJK (Gilbert-Johnson-Keerthi) algorithm is used to compute distances between convex polyhedra.


Generally, choose the fewest number of shapes that will tightly fit your part/link geometry. Some shapes are more expensive than others:


  • Spheres
  • Half Space (plane)
  • Lozenges
  • Capsules


  • Boxes
  • Ellipsoids
  • Tetrahedrons
  • Cones

Physical Extents

Each link may also store a physical extent used to provide an appearance (shape) of the link. Also referred to as the "visible layer". These can be full color 3D meshes, or Actin's primitive 3D convex shapes. Typically bounding volumes encapsulate the physical extent. If Actin's primitive 3D shapes are part of the physical extents, and no bounding volumes are specified, these shapes are used for collision detection. The meshes use the classes EcPolyPhysicalExtent or EcTriPhysicalExtent.

in this image, both Meshes and primitive shapes are shown

Mass Properties

Each link may store mass properties, in the form of EcRigidBodyMassProperties. This class stores the Mass, the first moment (center of mass), and the second moment (describes how the mass is distributed across the link).


Named Frames

EcNamedFrames are stored on each link, as a map between strings (names) and EcCoordinateSystemTransformation. These are useful as reference coordinates for attachments, sensor positioning, camera positioning, and constraint positioning. These EcCoordinateSystemTransformation are all defined relative to the Primary Frame of the link.

Here is a EcNamedFrame that might be used to attach a tool

Child Links

Each link stores a EcManipulatorLinkVector of their own child links.


The Actin "state" (EcManipulatorSystemState) describes the state of the system at a given time. This state can change at every timestep, and stores the positions (EcPositionState) and velocities (EcVelocityState) of each manipulator.

Position State

The EcPositionState class stores the position of the base link (primary frame), as well as the joint positions for each joint.

Velocity State

The EcVelocityState class stores the velocity of the base link (primary frame), as well as the joint velocities for each joint.

  • Base frame velocity: EcGeneralVelocity
  • Joint velocities: EcXmlRealVector


The Actin "configuration" (EcManipulatorSystemConfiguration) describes the configuration of a system. This configuration includes attachments as well as collision exclusions. The configuration can change at runtime, but are not typically changing quickly (each timestep).


Attachments are stored in the EcManipulatorSystemConfiguration's EcManipulatorAttachmentMap. This describes attachments among multiple manipulators. For example, a vacuum gripper is attached to a robot, or a robot attached to some part of the environment like a table. In these examples, if the arm moves, then the gripper will move with it. If the table that the arm is attached to moves, then the robot base will move with it.


Attachments can be used to dynamically change scene by attaching or detaching manipulators. Frequently, Attachments are used to model grasping. When the gripper picks up an object/product, then it is attached to the gripper. This allows the kinematics (including collision detection) to take the attached object into account. This is useful for preventing collision between the robot payload and the environment.

When attaching a manipulator to a link:

  • Can attach multiple manipulators to the same link
  • Cannot attach the same manipulator to multiple links
  • Cannot attach to cause a circular chain

Collision Exclusions

Actin uses primitive shapes for detecting collision between manipulators or links. Collision Exclusion Maps are used to configure which manipulator and link combinations are included or excluded in collision detection calculations.

EcManipulatorSelfCollisionMap : By default, collisions between links in the same manipulator are not checked, they must be explicitly specified.

EcSystemCollisionExclusionMap : By default, collisions between different manipulators are checked, they must be explicitly excluded.

When attachment is set, collision exclusion typically needs to be set as well.

EcManipulatorSelfCollisionMap is stored in the EcIndividualManipulator, and is part of the system.