System Model Data Structure

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.
appearance .base .body	dil dil{NB}	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.
gc gc.body gc.point	int[npt] rn[d×npt]	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.

'box', [p1; p2] — draw a box aligned with the local coordinate axes. p1 and p2 are row vectors giving the coordinates of any two diametrically opposite vertices of the box.
'cyl', [p1; p2], r — draw a cylinder of radius r. p1 and p2 are row vectors giving the coordinates of the centres of the two end faces of the cylinder.
'sphere', c, r — draw a sphere of radius r centred on the point c. If a secondary current colour has been specified, then this drawing instruction creates a two-tone sphere. Otherwise, it creates a sphere in a single colour.
'colour', rgb — change the current colour. The argument is either a 1×3 vector specifying a colour in RGB format (three real numbers in the range 0 to 1), or a 2×3 matrix specifying a primary and a secondary colour. At present, only the 'sphere' drawing instruction makes use of the secondary colour. Showmotion chooses an initial colour for each body according to its body number, resulting in a default colouring scheme that is adequate for basic viewing purposes. There is therefore no need to specify colours of your own unless you wish to deviate from the default colour scheme. Tip: the default colours all have intensities of 80% or less, and are not fully saturated. Thus, if you use extreme RGB values, like [1 0 0], the result will be noticably bright and lurid compared with the defaults. Therefore, reserve the use of such colours for things that need to be especially bright and prominent.
'facets', N — change the current level of facetting. The argument is an integer greater than 2, specifying the number of triangles to appear arount the rim of a cylinder or the equator of a sphere. (In the case of a sphere, the actual number used is N rounded up to the next multiple of 4.) The initial value of N is 24. Be aware that the number of triangles in a sphere grows quadratically with N. If you set N=1000 then your spheres will look flawlessly smooth, and they will take forever to draw.
'vertices', V — specify a list of vertices for use in subsequent 'line' and 'triangles' drawing instructions. V is an N×3 matrix, N>=2, specifying the coordinates of N vertices. V supercedes any previous list of vertices, and remains in force until it too is superceded, or until the end of the (sub-)list in which V appears. V(i,:) defines vertex number i.
'line', V or 'line', vlist — draw a polyline. V is an N×3 matrix, N>=2, specifying directly the coordinates of a list of N vertices, whereas vlist is a list of vertex numbers referring to entries in the current vertex list, as defined by 'vertices'. In both cases, the specified vertices are joined together by straight line segments. The only difference between the two forms is the source of the vertex data.
'triangles', T — draw a set of triangles. T is an N×3 matrix of vertex numbers such that each row defines one triangle. (So this drawing instruction requires a current vertices list that defines at least three vertices.) A triangle is deemed to have two faces: a front face and a back face. The former reflects light, and is intended to be seen. The latter ought to be invisible, but Matlab draws it as visible but unlit. To make your triangles face the right way, use the following rule: list the vertices in counter-clockwise order, as viewed from the front face.
'tiles', [x0 x1; y0 y1; z0 z1], size — draw a rectangular surface with a chequer-board pattern of square tiles. The surface is parallel to any two of the three coordinate axes. This is a special drawing instruction that is allowed only in the base, and is intended for drawing a tiled floor. The first argument is a 3×2 matrix containing three ordered pairs. Any two of these must define strictly-positive ranges (i.e., second number bigger than first). These two ranges identify the two axes that are parallel to the floor, and also the location and extent of the floor in those two directions. The first element of the third ordered pair specifies the third coordinate of the floor rectangle; and the second element must be either equal to or less than the first, and controls whether the floor faces in the positive direction (equal) or negative direction (less than) of the third axis. For example, 'tiles', [1 2; 3 4; −1 −1], 0.4 creates a floor rectangle extending from 1 to 2 in the x direction, from 3 to 4 in the y direction, located at −1 in the z direction, and facing in the positive z direction. The tile size is 0.4, so the floor contains four whole tiles, four half tiles and one quarter tile. A floor made with this drawing instruction is always grey, regardless of the current colour.

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.

body — the body number of the body to track. If this field is either absent or set to zero, then you get a fixed camera. Otherwise, camera.body must be an integer in the range 1...NB specifying the body number of the body to track.
trackpoint — a 3D vector giving the coordinates, expressed in the relevant body coordinate system, of the point to be tracked. If trackpoint is not specified then it defaults to [0 0 0].
direction — a 3D vector, expressed in base coordinates, pointing into the camera (i.e., the opposite of the camera's viewing direction). If this field is omitted, then ShowMotion selects one of two possible default values, depending on whether it thinks the Y axis or the Z axis ought to be pointing up.
up — a 3D vector, expressed in base coordinates, pointing up. This field serves two purposes. Firstly, it defines a direction that must be pointing up in the initial view provided by the camera. Secondly, it defines the orientation of the horizontal plane used by the tracking camera (i.e., the horizontal plane is defined to be the plane normal to the up vector). If this field is not specified, then showmotion chooses up=[0 1 0] for planar robots with gravity pointing in the −Y direction, and up=[0 0 1] for all other cases.
zoom — a scalar indicating a zoom factor relative to the default view. Showmotion's default initial view is calculated to show every moving body in the model. If you want things to appear bigger or smaller than this, then set zoom to a value greater than or less than 1, as appropriate. If omitted, this field defaults to 1.
locus — a 2D vector in normalized window coordinates indicating where in the window the tracked point is to appear. The coordinates must be in the range −1 to +1, with [0,0] indicating the centre of the window, and other coordinates covering the largest square that will fit in the window. If this field is present, then ShowMotion makes trackpoint appear at the specified location in the window, even if the camera is not a tracking camera. If this field is not specified then the camera points at the centre of the bounding box containing all of the drawing instructions for the moving bodies.

Page last modified: June 2012
Author: Roy Featherstone