In SpatialVelocity, clarify operator +, +=, -, -= documentation. Perhaps create RELATIVE spatial velocity notation and/or methods.

[samzapo]

Original title of this issue: Function frame_F.CalcSpatialVelocity(.., frame_M, frame_E) computes V_MfFo_E not V_MoFo_E as documented.

See the following test: https://gist.github.com/samzapo/d0b0e69a8c57bd5406f21dfdb56b01bb

The linked test indicates that, if a frame M and a frame N are both affixed to a frame P, then V_MoFo_E equals V_NoFo_E, according to multibody::Frame::CalcSpatialVelocity().

The relative spatial velocity of Frame F when measured in Frame M, V_MoFo_E, should be distinct from relative spatial velocity of Frame F when measured in Frame N, V_NoFo_E; instead, they are equal.

Specifically, both values are equal to a spatial velocity V_MfFo_E, that is:

V_MfFo_E = R_EW * (V_WoFo_W - V_WoMo_W.Shift(p_MoFo_W))

Which is equal to neither of the expected quantities.

[sherm1]

@mitiguy Paul can you take a look at this?

[mitiguy]

@sherm1 I am looking at this now.

[amcastro-tri]

Since you are working on this @mitiguy, I'll unassign myself. Please feel free to reach out if I can be of any help.

[mitiguy]

Notes from this morning video conference with Sam Zapolosky, Evan Drumwright, and Jess Moss as well as the slack discussion which also includes Alejandro Castro and Sherm.

Helpful extension to spatial velocity and spatial acceleration monogram notation for: relative spatial and velocity, relative spatial acceleration, relative translational velocity, relative translational acceleration. Monogram notation for spatial velocity (does not change): V_WB_E. Associated words: Frame B's spatial velocity in frame W, expressed in frame E. Monogram notation for relative spatial velocity (proposed): V_W_BAE. Associated words: Frame B's spatial velocity relative to Frame A, measured in frame W, expressed in frame E. Notice the "measured-in" frame appears by itself after the V and the two relative frames follow.
This helps differentiate the relative spatial velocity from a "regular" spatial velocity.

Also proposed are new methods in Frame.h, something like: frameB.CalcRelativeSpatialVelocityInWorld(context, const Frame& relativeToFrameA, frame& expressedFrameE). frameB.CalcRelativeSpatialVelocity(context, const Frame& relativeToFrameA, Frame& measuredInFrameM, frame& expressedFrameE). Simbody has related relative Spatial velocity/acceleration methods here.

Proposed: Broaden/clarify the documentation for the SpatialVelocity operators +, -, -=, +=. Clarify that the SpatialVelocity::operator+ simply performs component wise addition.
Perhaps put a @see to SpatialVeloctiy::ComposeWithMovingFrameVelocity() as that method performs velocity composition which is an addition with an intermediate shift operation. Broaden: The current documentation suggests one particular use case for these spatial operators and informs the user that they must ensure the last SpatialVelocity argument has a specific meaning. This overly restricts these SpatialVelocity operators to a special case. There are multiple ways a + could be used. Perhaps we mention a few without discussing a restriction which the method does not enforce anyway.

Expand unit tests. There seems to be only one unit test for Frame::CalcSpatialVelocity(). It is in multibody/plant/test/frame_kinematics_test.cc. I think we could add more unit tests, e.g., to flush out the issues that we discussed in our video call and in Slack.

Related issue #13754 -- CalcSpatialAcceleration() APIs to mimic CalcSpatialVelocity API.

[SeanCurtis-TRI]

This struck me as a bit surprising. Here's why:

Consider the phrase:

Frame B's spatial velocity in frame W, expressed in frame E.

I'd interpret it to be synonymous with the phrase:

Frame B's spatial velocity relative to frame W, measured in frame W, expressed in frame E.

(In other words. B's spatial velocity in W is the relative velocity of B relative to W, measured in W.)

If everything written so far is correct, I'll now point out the confusion.

The first sentence would be monogrammed as: V_WB_E. The second as V_W_BW_E. Note the reversal of WB to BW. And yet, those two different symbols refer to the same quantity, yes?

[sherm1]

I agree with Sean. Looks like the "associated words" are backwards here?

Monogram notation for relative spatial velocity (proposed): V_W_BA_E. Associated words: Frame B's spatial velocity relative to Frame A, measured in frame W, expressed in frame E.

Should be: "Frame A's spatial velocity relative to Frame B ..." That seems more consistent with V_BA which is A's spatial velocity in B, which is equivalent to V_B_BA, A's velocity relative to B, measured in B.

[mitiguy]

@SeanCurtis-TRI is correct in that:
V_WB_E is the same as V_W_BW_E.
As we probably agree, there is no reason to use V_W_BW_E when V_WB_E suffices.
V_WB_E is explicit, shorter, simpler, clearer, better.

However, in Sean's example the reversal of WB to BW does not refer to the same quantity (which is why an extra underscore is intentionally introduced).
Focusing attention on the WB In V_WB, the W frame is the "measured in frame" and the B frame is the frames being measured.
Focusing attention on the BW in V_W_BW, both B and W are frames being measured. Neither is the "measured-in frame".

There is an analogous situation with translational velocity. Given points Q and P and measured-in frame W and expressed-in frame E. For v_WQ_E, the W frame is the "measured in frame" and Q is a point. For v_W_QP_E, both Q and P are points. Side note: v_WQ_E is the same as v_W_QP_E as long as P is a point fixed on frame W. Only use v_W_QP_E when P is not fixed on frame W.

[SeanCurtis-TRI]

@mitiguy, mistake my concern.

I'm not suggesting that WB refers to the same thing as BW. I'm referring to the fact that V_W_BW_E and V_WB_E refer to the same quantity. And, given that, the fact that WB and BW are reversed in what should otherwise be equivalent statements is odd.

B and W are frames being measured. Neither is the "measured-in frame.

That is not true. In V_W_BW E, W is both being measured and the measured-in frame. Admittedly its measure isn't interesting (the identity), but the frame serves both roles. It's perfectly valid to measure frame F in frame F. So, given you've got two constructs (where one is a strict subset of the other), it's strange to find that promoting an element of the smaller set into the notation of the larger set doesn't just include inclusion of additional symbols which were otherwise implicit, but it requires the reversal of existing symbols.

The problem is, as @sherm1 pointed out, simply one of mapping it to the language.

Now, if your position is that V_WB_E and V_W_BW_E are not equivalent ways of describing the same quantity, then my concern changes. In that case, the language used to describe the notation is in error.

[samzapo]

TL;DR The way measured in frames are currently annotated in drake violates the principle of least astonishment, as there are un-annotated shifts happening behind the scenes when I want to turn a V_WF and a V_WM into a V_MF_W

I don't think a new notation is needed, just a reinterpretation of the current notation. The divergence between my understanding of the monogram notation and what drake uses only occurred now, when I tripped-over V_MF_E . Up until this point, I also believed that relative to and measured in (or just in) were interchangeable.

Moreover, in drake V_MF_E = R_EW *(V_WF - V_WMf) where V_WMf = V_WM.Shift(p_MF_W) Which appears to be incorrect monogram notation, since I would normally expect Frame Mf to make it through to the final quantity for visual debugging purposes (i.e. V_MfF_E). In fact, If I called frame M, a relative to instead of a measured in frame, the monogram notation would become consistent. E.g.:

• "The velocity of Frame F relative to Frame M, expressed in frame E":

V_MF_E = R_EW *(V_WF - V_WM)

• "The velocity of Frame F measured in Frame M, expressed in frame E":

V_MfF_E = R_EW *(V_WF - V_WMf) where V_WMf = V_WM.Shift(p_MF_W)

AKA: "The spatial velocity of Frame F relative to a Frame Mf, affixed to frame M whose origin is instantaneously collocated with the origin of frame F (point Fo) and whose orientation is aligned with Frame M, expressed in Frame E" SPECIAL NOTE: A measured in frame (sometimes just annotated as in) is a special case of relative to where the the relative-to frame origin is collocated with the origin of the target frame, F (e.g. V_MfF_E, V_RsS_E). [insert documentation that is currently in SpatialVelocity::operator-]

[sherm1]

@mitiguy re notation I think it is critical that we don't flip letters around for the same meaning. My thought would be to make sure that V_AB has the same meaning as V_A_AB.

• V_AB = the spatial velocity of B in A (that is, measured and expressed in A)
• V_A_AB = the relative spatial velocity of B and A, measured in A (and still expressed in A)

(those are the same quantities because A's velocity in A is always zero)

Writing that way, the shorter form can be viewed as an abbreviation of the more general relative velocity concept.

[sherm1]

A further note regarding the expressed-in frame if it is not given explicitly:

• we already define V_AB ≡ V_AB_A (expressed-in frame is implicitly the same as the measured-in frame)
• so I think we should define V_F_AB ≡ V_F_AB_F (for consistency since F is the measured-in frame)

(Combined with the above, V_AB is actually short for V_A_AB_A!)

What do you think?

[samzapo]

I think this is a good new notation, as I have just determined that my solution above does not extend to SpatialAccelerations.

Although, I believe V_AB would be short for V_A_AbB_A since:

           ⎡ A ⟶ B ⎤    ⎡ A ⟶ Bo/Ab ⎤                 ⎡ A ⟶ Bo/Ao ⎤
    V_AB = ⎣   V   ⎦A = ⎣   V       ⎦A = V_A_AbBo_A ≠ ⎣   V       ⎦A = V_A_AoBo_A

[mitiguy]

There are many special cases being discussed. Here is a proposal for the general case for: M: "measured-in" frame. F: frame being measured. B: "relative-to" frame. E: "expressed-in" frame.

1. Relative spatial velocity monogram notation is not used unless it is essential, which occurs only when frames M, F, B are distinct.

2. Relative spatial velocity notation, its definition, and the associated words are: V_M_FB_E ≡ V_MB_E − V_MF_E which is the "spatial velocity in M of F relative to B, expressed in E". Note: The relative translational velocity v_M_FoBo_E that underlies the relative spatial velocity V_M_FB_E can be defined in terms of the time-derivative in M of the position vector from Fo to Bo (in agreement with the monogram notation).

[sherm1]

Paul, I like what you wrote above but I think the sign is backwards. When we write V_AB we mean "B's velocity in A". That is B−A if you think of A's velocity in A as zero. So when we write V_M_AB we should mean V_MB − V_MA for consistency. That way V_A_AB and V_AB mean the same thing as they should.

[sherm1]

@samzapo per your comment above I agree except for the ≠

I claim: V_A_AB = V_A_AbB proof: V_AA = V_AAb = 0 V_A_AB = V_AB − V_AA = V_AB V_A_AbB = V_AB − V_AAb = V_AB

[samzapo]

@sherm1 Yes, that's right! Because, in this case, the "relative-to" frame Ab is not rotating in "measured-in" frame A.

[mitiguy]

Opened PR #16415 to enhance documentation and notation for offset frames (need to converge on notation before proceeding with methods in SpatialVelocity and SpatialAcceleration.

[mitiguy]

Updated proposal for relative spatial velocity monogram notation. M: "measured-in" frame. B: "relative-to" frame. C: frame being measured.

V_M_BC ≡ V_MC − V_MB which is "C's spatial velocity relative to B, measured in M." Note: "Co's translational relative velocity relative to Bo, measured in M" is denoted v_M_BoCo can be defined in terms of the time-derivative in M of p_BoCo (the position vector from Bo to Co). Notice the agreement with the left-to-right appearance of BC in the monogram notation and BoCo in the position vector.

Note: "Relative" notation is not used unless it is essential, which occurs only when frames M, B, C are distinct. If B=M, V_M_BC = V_M_MC ≡ V_MC − V_MM = V_MC (relative spatial velocity notation is unnecessary). If B=C, V_M_BC = V_M_CC ≡ V_MC − V_MC = 0 (relative spatial velocity notation is unnecessary). If C=M, V_M_BC = V_M_BM ≡ V_MM − V_MB = −V_MB (relative spatial velocity notation is unnecessary).

The proposal for relative spatial acceleration monogram notation is: A_M_BC ≡ A_MC − A_MB which is "C's spatial acceleration relative to B, measured in M."

The proposal for spatial force is: F_B is the spatial force on a frame B F_B contains a 3-element torque vector 𝜏_B and a 3-element force component f_Bo. F_B represents the replacement of a set of forces on B with a torque *𝜏_B that is equal to to the moment of the set of forces about Bo (frame B's origin) together with a force f_Bo** applied to Bo that is equal to the resultant of the set of forces. The power in a frame W due to this spatial force is calculated as: F_B ⋅ V_WB A similar calculation is used for generalized force (albeit with a Jacobian rather than spatial velocity).

The proposal for an action/reaction spatial force is: F_AB is the spatial force from a frame A on a frame B. F_AB contains a 3-element torque vector 𝜏_AB and a 3-element force component f_AoBo. F_AB represents the replacement of a set of forces from A on B with a torque *𝜏_AB that is equal to to the moment of the set of forces about Bo (frame B's origin) together with a force f_AoBo** applied to Bo that is equal to the resultant of the set of forces. If Ao and Bo are coincident (which is the case for joints such as revolute joints or ball-and-socket joints), then F_BA = -FAB The power in a frame W due to this action/reaction spatial force is calculated via F_AB ⋅ (V_WB - V_WA) = F_AB ⋅ V_W_AB A similar calculation is used for generalized force (albeit with a Jacobian rather than spatial velocity).

[sherm1]

I like the relative velocity notation!

(Side discussion for the force notation) I wonder if the frames should be reversed for consistent ordering in the power computation. Currently you have power in W = F_BC ⋅ V_W_CB. At first glance seems a shame that we have BC and CB in that expression.

[mitiguy]

I look forward to talking to you about the force notation. There are positives and negatives about each (pun intended).

[amcastro-tri]

I still have a couple questions, sorry if too slow:

1. We use this all the time in our code: V_WB = V_WPb + V_PB, where Pb is frame P shifted to Bo and V_PB is the spatial velocity of B measure in P (I am omitting the expressed-in frames here). Is this a particular case of the "relative velocity" notation? because in the relative velocity notation it'd seem the three terms are all measured in the same frame, while here we have V_WB and V_WPb measured in W and V_PB measured in P.

Paul's response: As discussed in an early book by Kane, an "absolute velocity" can always be regarded as a special case of "relative velocity".

Point Bo's translational velocity "relative" to a point Co measured in a frame M can be defined:
v_M_CoBo ≡ DtM(p_CoBo) = v_MBo - v_MCo

If Co is replaced with Mo (any point fixed in M), then the previous equation simplifies to: v_M_MoBo ≡ DtM(p_MoBo) = v_MBo - v_MMo = v_MBo

Bo's translational "absolute" velocity measured in M is defined:
v_MBo ≡ DtM(p_MoBo) where Mo is any point fixed in M.

Similarly, point Bo's translational acceleration "relative" to point Co measured in frame M can be defined:
a_M_CoBo ≡ DtM(DtM(p_CoBo)) = a_MBo - a_MCo

If Co is replaced with Mo (any point fixed in M), then the previous equation simplifies to: a_M_MoBo ≡ DtM(DtM(p_MoBo)) = a_MBo - a_MMo = a_MBo

Bo's translational "absolute" velocity measured in M is defined:
a_MBo ≡ DtM(DtM(p_MoBo)) where Mo is any point fixed in M.

2. I like that I can think v_M_BoCo = DtM(p_BoCo). Similarly I could think of w_M_BC as being the term in DtM(R_BC) = [w_M_BC] x R_BC (with [a] the skew symmetric cross product matrix of vector

Paul's response: A useful property of angular velocity is that "relative" angular velocity can always be simplified to a related "absolute" angular velocity. In mathematical terms: w_M_BC ≡ w_MC - w_MB = w_BC

a). However, can I think in similar terms for the accelerations? should there be any additional bias terms in order to define these "relative accelerations"?

Paul's response: Unfortunately, the nice associations of "relative" and "absolute" velocity do not extend to angular acceleration. For example, in general 3D rotational motion, "relative" angular acceleration cannot be simplified to an "absolute" angular acceleration. In mathematical terms: alpha_M_BC ≡ alpha_MC - alpha_MB = alf_BC + w_MB x w_BC

[mitiguy]

This is now closed due to a multiplicity of PRs, including PR #16415, PR #16691, PR #16699.