The System Model Data Structure

Spatial_v2 uses a system model data structure that can describe a general fixed-base kinematic tree based either on spatial-vector arithmetic or on planar-vector arithmetic.  A mixture of the two is not allowed.  A spatial model (i.e., one based on spatial-vector arithmetic) may contain revolute, prismatic and helical joints; whereas a planar model may contain revolute and prismatic joints only.  Joint types are identified by type codes, and there are separate codes for spatial-arithmetic joints and planar-arithmetic joints.  One must use the correct type of joint for the given underlying arithmetic.

Optionally, a user-defined function can be added to the data structure, which defines arbitrary constraints on the joint position variables.  This function can be used to incorporate into the system model the effects of closed kinematic loops, gearing between joints, and the kinematics of unsupported joint types.  Furthermore, as massless bodies are allowed (provided the joint-space inertia matrix remains nonsingular), it is possible to emulate cylindrical, planar, spherical and 6-DoF joints using appropriate chains of revolute and prismatic joints interconnected with massless bodies.  Planar and 6-DoF emulations, in particular, support the modelling of floating-base planar and spatial rigid-body systems.

Field Type Description
NB int the number of bodies in the tree, excluding the fixed base.  NB is also the number of joints.
parent int[NB] parent(i) is the body number of the parent of body i in the tree.  The fixed base is defined to be body number 0; and the remaining bodies are numbered from 1 to NB in any order such that each body has a higher number than its parent (so parent(i) < i for all i).  Joint i connects from body parent(i) to body i.
jtype jd{NB} jtype{i} contains either the joint type code or the joint-descriptor data structure for joint i.  Joint type codes are strings, and joint descriptors are data structures containing a field called code and an optional second field called pars, the former containing the joint type code and the latter any parameters that are needed by that type of joint.  A complete listing of joint type codes appears with the documentation for jcalc.
Xtree xfm{NB} Xtree{i} is the coordinate transform from the coordinate system of body parent(i) to the coordinate system of the predecessor frame of joint i (which is embedded in body parent(i)).  The product of this transform with the joint transform for joint i, as calculated by jcalc, is the transform from body parent(i) coordinates to body i coordinates.
I spI{NB} I{i} is the spatial or planar (as appropriate) inertia of body i, expressed in body i coordinates.
gravity rn[d] This is an optional field specifying the gravitational acceleration vector in base (body 0) coordinates.  d is either 2 or 3, depending on whether the underlying arithmetic is planar or spatial.  If this field is omitted then a default value of [0;0;−9.81] is used in spatial models, and [0;0] in planar models.
gamma_q @fh This field is optional.  If present, it must contain the Matlab function handle of a function that imposes kinematic constraints on the joint variables.  For a description of how this function works, and how to write your own, see Describing Constraints with gamma_q.
This is an optional field containing drawing instructions for use by showmotion.  If this field is present, then appearance.body is a cell array such that appearance.body{i} contains the drawing instruction list for body i, and appearance.base is a field containing the drawing instruction list for the base (body 0).  (appearance.base can be omitted if there are no drawing instructions for the base.)  A drawing instruction list is permitted to be empty, in which case the affected body is invisible.  A detailed description of drawing instructions appears below.
camera   This is an optional field containing data that affects how showmotion views this model.  It is a structure with several fields, and is described in detail below.
This is an optional field that is used in connection with the Simulink ground contact model.  It contains a list of body numbers and the coordinates of a set of points.  npt is the number of points in the ground-contact model; and d is either 2 or 3, depending on whether the underlying arithmetic is planar or spatial.  Point number i is fixed in body gc.body(i), and gc.point(:,i) contains the coordinates of that point expressed in the local coordinate system of body i.  There are no restrictions on the number of points in the model, or the number of points in any one body, or the order in which points can be listed.
codes appearing in the 'Type' column:  int: integer-valued number;  rn: real number;  jd: type-code string or joint-descriptor data structure;  xfm: spatial (6×6) or planar (3×3) coordinate transform;  spI: spatial (6×6) or planar (3×3) inertia matrix;  @fh: Matlab function handle;  dil: drawing instruction list;  [...]: array of specified dimension;  {...}: cell array of specified dimension

Drawing Instructions

The appearance of a body is specified by a drawing instructions list, which is a cell array containing, in any order, zero or more drawing instructions, and zero or more drawing instructions lists.  Thus, according to this definition, {} is a valid drawing instructions list, and so is {{},{{}}}, although neither contains any drawing instructions.  A drawing instruction is a sequence of either two or three elements in a drawing instructions list.  The first element is a string identifying the type of drawing instruction, and the rest are numeric arguments.

Drawing instructions can be divided into two groups: those that create something visible, and those that alter the graphics context.  The latter is a data structure containing three items: the current colour, the current level of facetting (which controls the number of triangles used to make a sphere or a cylinder), and the current vertex list.  The graphics context behaves as follows: (1) whenever a component of the graphics context is changed by a drawing instruction, the new value remains in effect until it is changed again by another drawing instruction, or until the end of the list or sublist in which it appeared; (2) whenever a sublist is encountered, it inherits the graphics context of its enclosing list, but any changes made within it remain local to the sublist.  For example, if B denotes the drawing instruction to draw a box, and Cr, Cg and Cb denote the drawing instructions to set the current colour to red, green or blue, respectively, then the list {Cr,B,{B,Cg,B,Cb,B},B} draws a red box, another red box, a green box, a blue box, and one more red box.

The complete list of drawing instructions is set out below.  Note that drawing instructions are always 3D, regardless of whether the model is based on spatial or planar arithmetic.  Note, also, that vectors appearing in the drawing instructions are always row vectors.  For a practical demonstration of drawing instructions, see gfxExample.

Camera Data Structure

Showmotion supports two kinds of camera: a fixed camera, which does not move of its own accord, and a tracking camera, which automatically translates in the horizontal plane in order to follow the horizontal coordinates of a specified point in a specified body as it moves.  Tracking cameras are useful for mobile robots, vehicles, and the like.  By default, showmotion gives you a fixed camera with a default initial view.  If you want a tracking camera, or a different initial view, then you specify it in the fields of the camera data structure, as listed below.  Every field is optional, and all vectors can be in either row or column format.  Note that showmotion's camera is always a 3D camera, regardless of whether the model's underlying arithmetic is spatial or planar.

Page last modified:  June 2012
Author:  Roy Featherstone