Repository navigation
Twist as displacement vs velocity: document both, and decide Twist3 * SpatialVelocity and Twist/SpatialVelocity conversion #257
Description
Background
Twist2 and Twist3 hold an element of se(2) / se(3) as a vector [v, ω]. In robotics a "twist" is used in two ways that share the same vector, the same layout and the same algebra, but have different physical meaning:
| Displacement (screw) | Velocity | |
|---|---|---|
What S is |
the log of a pose; often a unit screw axis times a magnitude | an instantaneous rate, with units m/s and rad/s |
| Pose from it | exp(S), or exp(S * theta) for a unit S |
exp(S * dt) over a time dt |
| Used in | RVC (§2.3.2.3), Modern Robotics (Lynch & Park), product-of-exponentials kinematics | ROS geometry_msgs/Twist, differential kinematics |
The class is currently written for the first reading (unit(), pitch, line(), exp(theta)), but nothing in the docs says so, and users arriving from ROS reasonably expect the second.
SpatialVelocity already exists in spatialvector.py as part of the Featherstone family (velocity, acceleration, force, momentum). It uses the same translational-first layout as Twist3 (see the module note), and it is the right home for the velocity reading, because force and momentum are dual to motion and transform with the coadjoint (see #207).
What is not proposed
- Renaming
Twist2/Twist3, or adding a second twist-like class. The algebra is identical, so that would duplicate it, andTwistis the term used in RVC and RTB.
Why it matters in practice
Most operations are the same under both readings. The ones that describe the screw axis are invariant to scaling the twist, so they hold for both: pitch, line() (Plücker coordinates scale but the line does not) and pole. pole was the one place that silently assumed |ω| = 1, which #249 fixes. The ones that depend on magnitude (theta, exp(S * k)) are an angle in one reading and a rate in the other.
The interpretation also leaks into behaviour in one place, which is the first question below.
Proposed
A docs-only change so the class docstrings describe both usages, say which properties are scale-invariant, and point to SpatialVelocity.
Open questions
1. What should Twist3 * SpatialVelocity (and the other SpatialVector types) mean?
Since #210, it computes Ad(exp(S)) · v via SpatialVector.__rmul__. That is the displacement reading: the twist acts as the pose exp(S), the same as SE3 * v. Under the velocity reading the natural action of one velocity on another is the Lie bracket ad(S) · v, which SpatialVelocity @ already provides, and exp(S) would carry an implicit dt = 1.
Options:
- (a) Keep it, and document
*as the finite-displacement action. - (b) Keep it, and also make the bracket route easy to find from
Twist3. - (c) Make
*require anSE3and have the user writeS.SE3() * v, so the choice is explicit.
2. Should there be explicit conversion between Twist3 and SpatialVelocity (and Twist2 where it applies)?
The layouts match, so it is trivial, and it would make the relationship discoverable. Things to decide: constructors (SpatialVelocity(twist) / Twist3(velocity)) versus named methods, and whether a conversion should say anything about dt or the frame, since SpatialVelocity here carries no frame tag.
Related
- Fix SpatialForce/SpatialMomentum SE(3) transform to use the coadjoint (Ad^-T) #207, fix: Twist3 * SpatialVector raised ValueError instead of dispatching #210: spatial vector transforms and
Twist3 * SpatialVector - Keep twist poles invariant under angular speed scaling #249:
polemade invariant to scaling the twist - Featherstone, Rigid Body Dynamics Algorithms; Murray, Li & Sastry, A Mathematical Introduction to Robotic Manipulation
Activity
antonsoo commentedon Oct 15, 2026
The trajectory check for #248 starts with the log of a measured pose increment. Dividing that vector by the sampling interval gives a rate; multiplying by the interval in
expmust recover the same increment. The #249 checks then apply nonzero signed scales and require the same pole. These make useful paired examples for the two readings without normalizing away magnitude.Documenting
*as the existing finite-displacement action and linking to the bracket would preserve behavior while making the implicit unit step clear. A conversion betweenTwist3andSpatialVelocitycan copy the[v, w]components; it should not integrate over time or change frames implicitly. The caller still needs an explicitdtwhen turning a rate into a displacement.