Skip to main content

Body Objects

Body objects are the basic building blocks for QuIRK dynamics solutions. They represent rigid bodies. QuIRK has functions to generate a number of pre-defined rigid bodies, but a body object can be fully generalized with an arbitrary inertia matrix.

The Body Constructor

To create a default body, type

>> body
ans = 
                  QuIRK: 1 x 1 x 1 m sphbody
         ,-       Located at [0  0  0] m
        (  *)      Attitude   [0  0  0  1]
         `-       Mass        1 kg
                   Datatype    double

The default body is an ellipsoid, measuring 1 meter along each axis, located at the origin in Cartesian coordinates, and with a quaternion attitude of [0 0 0 1]T. Besides the cutesy cartoon, this output gives you a quick look at the properties of a body. The following conventions apply:

  • The body size always appears as the full width along the body x axis, y axis, and then z axis.
  • The location of a body is the position of both its center of mass and its geometric center.
  • The location of a body is in the inertial frame of reference.
  • All units are metric MKS. (Though any self-consistent system of units should work, MKS is the best example and QuIRK displays units in that system.)

Bodies are a subclass of the Matlab handle class, which means that the variable name of a body and the body object itself are more closely related than is usually the case for Matlab objects. For example, if you assign the body to a variable and then copy that variable, like this:

>> B = body;
>> C = B;

Then referring to, deleting, or modifying body "C" will also affect body "B." In other words, the assignment statement C = B creates a copy of the reference to the body, without creating a copy of the body itself, which only exists once. Both B and C point to the same object in memory.

QuIRK, of course, handles more interesting bodies than the default sphere at the origin. The constructor takes as arguments (1) a center-of-mass position vector, (2) a quaternion attitude, and (3) a list of property/value pairs. For example, create a cube located with its center at the point [1 2 3]T with its body axes aligned to the inertial axes by entering:

>> B = body([1 2 3], [0 0 0 1], 'shape', 'cube')
B = 
         _____    QuIRK: 1 x 1 x 1 m boxbody
        /\\\\\\    Located at [1  2  3] m
       /  \\\\\\   Attitude   [0  0  0  1]
       \  /####/   Mass        1 kg
        \/####/    Datatype    double

The body function takes a center-of-mass position as the first argument and quaternion attitude as the second argument. You do not have to be careful about whether they are row or column matrices. If you do not specify a body shape, it will default to a sphere, the default size of any body is 111 m, and the default mass is 1 kg.

Back to top

Body Options

When you first create a body, you can specify a number of options that control the physical properties and appearance of the body. Enter options as property/value pairs. Here is the full list of body options. Give the constructor properties as strings, or use the shortcut abbreviations shown (they are not case-sensitive).

Color Colorspec Color of the body when drawn with any QuIRK graphics command
Data Any user-defined data
Shape String 'sphere'
Geometric shape of the body for graphics and for automatic generation of inertia matrices (a cylinder's axis lies along body z)
Size String 'LWH' or [L W H] in meters Physical size of the body
Time Double Seconds Time value for calculations (this property is mostly unused)
Mass Double Kilograms Mass of the body
Inertia 33 Double kg m2 Inertia matrix of the body, overwriting any automatically generated inertia from the shape property
Velocity 31 Double m/s Initial velocity vector of the body
Omega 31 Double rad/s Initial angular velocity of the body (will overwrite qdot0 if omega comes last)
Force Function handle Newtons Force function acting at the body center of mass, as a function of position, attitude, velocity, angular velocity, and time: f(rqvωt)
Torque Function handle N m Torque function acting about the body center of mass, as a function of position, attitude, velocity, angular velocity, and time: τ(rqvωt)

Important note: Specifying the 'shape' property after a custom inertia matrix in the argument list will override the custom inertia with a precalculated matrix for the specified shape.

You can obtain a list of all the body properties that you may later access of modify by entering the commands get(body) or set(body).

Back to top

Drawing Bodies

Knowing the size, shape, vector position, and quaternion attitude of a body is useful, and theoretically tells us all we need, but a visual representation is generally a good idea. The draw command places a graphic representation of a body in the active figure window.

>> draw(B);


>> B.draw;

both produce a figure like this one:


By default, using the draw command on a body in the multibody dynamics package will create axes with default axis settings as if you had typed, at the command line,

>> axis equal
>> axis tight

There are optional properties to draw that can change this behavior, or automatically light the graphics object. Other options override the color and opacity of the body. Draw also accepts any Matlab surfaceplot property. For a more exciting view of this body, you can use draw('Lit', true) (or issue the Matlab command light) and click the rotate button on the figure toolbar to orbit the camera view around the body. You can now use any axis- and figure-manipulating commands you like.

When many bodies are drawn in the figure, a useful command for bodies is ghost, which acts like draw but produces a translucent graphic, allowing you to see through the bodies. If you ever have need to uniquely identify a body, you can also use the highlight command to make a body stand out from the others. The same command removes this highlighting.

Back to top

Modifying Bodies

Once a body has been created, you can modify its properties using the standard Matlab "set" interface, or subscript the body object with the "." operator. For example, to change a body's attitude and mass, you can type either

>> B.att = [0.8147 0.9058 0.1270 0.9134];
>> B.mass = 5;


>> set(B, 'att', [0.8147 0.9058 0.1270 0.9134], 'mass', 5);

If there is a graphic of the body in any figure window, then the graphic will automatically update with any changes. For example, the cube from before will look, after those commands have been entered (and a light object added), like this:


You can turn this live-update behavior off when you call the draw command by setting the 'snap' option to true. This is useful for creating multiple plots of the same bodies, such as in figure-window subplots to show snapshots of a system at various points in time.

Body sizes can be modified by setting the properties sx, sy, and sz. A useful command for quickly modifying bodies is resize, which lets you change the size of a body with the same 'LWH' shortcut syntax as in the constructor. Note: Be aware that if you have solved a multibody system, changing the shape, inertia, mass, position, or other solution-influencing properties of any body in that system will cause the solution to be lost. In most cases, QuIRK will print a warning when this happens.

The data property of body objects is for any user-defined data, such as names, tags, or any other data value. QuIRK does not access or modify this property, so you can do whatever you want with it.

Back to top



  • Joseph Shoer

Download QuIRK

Requires MATLAB 2009 or later