Drake C++ Documentation

We are interested in representing physical quantities like position, orientation, inertia, and spatial velocity.

For discussion here, let \(Q\) stand for an arbitrary physical quantity; we'll replace it with specific quantity symbols later. For computation with vector quantities, we must choose a basis in which to express the individual numerical elements. A basis is a set of independent direction vectors that spans a space of interest; for example, the x,y,z axes of a coordinate frame span 3D space. To express a vector quantity in a particular basis means to form the dot product of that vector with each of the basis vectors in turn, yielding a single scalar each time. We call those scalars the measure numbers of the vector in that basis.

Any suitable basis may be chosen for computation; that choice does not change the meaning of a physical quantity but is simply an agreed-upon convention for writing down that quantity numerically. The chosen basis is called the expressed-in basis; however, since our Cartesian bases are always the axes of a coordinate frame, we more commonly refer to it as the expressed-in frame. (See Frames and Bodies for more information about frames in Drake.)

Let the frame providing a basis be frame \(F\). In typeset equations we use bracket notation \([Q]_F\) to denote that quantity \(Q\) is being expressed in \(F\)'s basis \(F_x,F_y,F_z\). In code or comments, we translate this to monogram notation, described in detail below. Here monogram notation would be Q_F (Q would be replaced by the actual quantity). As a simple example, a vector \(r\) expressed in frame \(W\) would be \([r]_W\) or r_W in code. For the remainder of this documentation, we will generally use the default font for single-letter variables because formatting them with \(\LaTeX\) or code font makes the source hard to read and write, and the result does not add any clarity to the documentation. So in this document and in most of Drake's Doxygen-formatted documentation, \(F\)≡F≡F. Individual Drake programmers are allowed to be fussier about single-letter typography but we don't require it; readers should not infer any meaning to the font choice. We are more careful about the font for more complex symbols and equations.

Physical quantities in general may be characterized by

Quantities involving mass properties may have an additional "taken about" point; relative velocities and accelerations may need an additional frame; we'll discuss those elsewhere.

(Note that a physical quantity does not have an expressed-in frame; that is necessary only for numerical computation.)

Particular physical quantities may not have all of these characteristics. If all are present, a generic physical quantity would look like this:


where R is the reference, T is the target, and i is the index. In monogram notation, this would be Qi_RT. (We call this "monogram" notation because the most important symbol–the quantity type–is listed first, like the large last-name initial on a monogrammed shirt.) If an expressed-in frame F must be specified we combine this with the bracket notation described above and write


or Qi_RT_F in code. For a real example, the angular velocity of body B (the target) in body A (the reference) is written \(^Aω^B\) (monogram: w_AB). If that vector is to be expressed numerically in the world frame W, we write \([^Aω^B]_W\) (monogram: w_AB_W). Monogram notation includes some defaults that are commonly used to simplify symbols when the meaning is clear. In particular if the reference symbol has an obvious frame, that basis is the default for the expressed-in frame. For example, w_AB can be used instead of w_AB_A (you can think of that as "no need to repeat the '_A' twice"). Other defaults will be noted as they are introduced.

Please note that this compact notation is not intended as a substitute for clear comments in code. Instead it is intended as an unambiguous specification that can be used to compare code with the theory it implements. It also provides a means to avoid many common bugs because verification can be achieved by rote pattern matching of symbols. The notation is often best used in conjunction with some preliminary comments, including reminders about the meanings of less-common symbols, and reference links to this background documentation.

Next we discuss the kinds of quantities we need to account for and present their typeset and code representations.

Next topic: Frames and Bodies