3.4 Joint components

The HingeJoint (Figure 3.13) is a 1 DOF joint that constrains motion between frames C and D to a simple rotation about the axis of D. It implements six constraints and one coordinate (Table 3.1), to which the joint transform is related by

The value and ranges for are exported by the properties theta and thetaRange, and the coordinate index is defined by the constant THETA_IDX. For rendering, the properties shaftLength and shaftRadius control the size of a shaft drawn about the rotation axis, using the faceColor rendering property. A demo is provided by
artisynth.demos.mech.HingeJointDemo.

In addition to the standard constructors described in Section 3.3.3,

creates a hinge joint with a specified origin and axis direction for frame D (in world coordinates), and frames C and D coincident.

The SliderJoint (Figure 3.14) is a 1 DOF joint that constrains motion between frames C and D to a simple translation along the axis of D. It implements six constraints and one coordinate (Table 3.2), to which the joint transform is related by

The value and ranges for are exported by the properties z and zRange, and the coordinate index is defined by the constant Z_IDX. For rendering, the properties shaftLength and shaftRadius control the size of a shaft drawn about the sliding axis, using the faceColor rendering property. A demo is provided by artisynth.demos.mech.SliderJointDemo.

In addition to the standard constructors described in Section 3.3.3,

creates a slider joint with a specified origin and axis direction for frame D (in world coordinates), and frames C and D coincident.

The CylindricalJoint (Figure 3.15) is a 2 DOF joint that constrains motion between frames C and D to translation and rotation along and about the axis of D. It implements six constraints and two coordinates and (Table 3.3), to which the joint transform is related by

The value and ranges for and are exported by the properties z, theta, zRange and thetaRange, and the coordinate indices are defined by the constants Z_IDX and THETA_IDX. For rendering, the properties shaftLength and shaftRadius control the size of a shaft drawn about the sliding/rotation axis, using the faceColor rendering property. A demo is provided by artisynth.demos.mech.CylindricalJointDemo.

In addition to the standard constructors described in Section 3.3.3,

creates a cylindrical joint with a specified origin and axis direction for frame D (in world coordinates), and frames C and D coincident.

The SlottedHingeJoint (Figure 3.16) is a 2 DOF joint that constrains motion between frames C and D to translation along the axis and rotation about the axis of D. It implements six constraints and two coordinates and (Table 3.4), to which the joint transform is related by

(3.25)

The value and ranges for and are exported by the properties x, theta, xRange and thetaRange, and the coordinate indices are defined by the constants X_IDX and THETA_IDX. For rendering, the properties shaftLength and shaftRadius control the size of a shaft drawn about the rotation axis, while slotWidth and slotDepth control the width and depth of a slot drawn along the sliding () axis; both are drawn using the faceColor rendering property. When rendering the slot, its bounds along the axis are set to xRange by default. However, this may be too large, particularly if xRange is unbounded. As an alternate, the property slotRange will be used instead if its range (i.e., the upper bound minus the lower bound) exceeds 0. A demo of SlottedHingeJoint is provided by artisynth.demos.mech.SlottedHingeJointDemo.

In addition to the standard constructors described in Section 3.3.3,

creates a slotted hinge joint with a specified origin and axis direction for frame D (in world coordinates), and frames C and D coincident.

The UniversalJoint (Figure 3.17) is a 2 DOF joint that allows C two rotational degrees of freedom with respect to D: a roll rotation about D’s axis, followed by a pitch rotation about the rotated axis. It implements six constraints and the two coordinates and (Table 3.5), to which the joint transform is related by

where

The value and ranges for and are exported by the properties roll, pitch, rollRange and pitchRange, and the coordinate indices are defined by the constants ROLL_IDX and PITCH_IDX. For rendering, the properties shaftLength and shaftRadius control the size of shafts drawn about the roll and pitch axes, while jointRadius specifies the radius of a ball drawn around the origin of D; both are drawn using the faceColor rendering property. A demo is provided by artisynth.demos.mech.UniversalJointDemo.

The SkewedUniversalJoint (Figure 3.18) is a version of the universal joint in which the pitch axis is skewed relative to its nominal direction by an angle . More precisely, let and be the and axes of C after the initial roll rotation. For a regular universal joint, the pitch axis is , whereas for a skewed universal joint it is rotated by clockwise about . The joint still has 2 DOF, but the space of allowed rotations is reduced.

The constraints and the coordinates are the same as for the universal joint, although the relationship between is now more complicated. With , , , and defined as for the universal joint, is given by

where

Rendering is controlled using the properties shaftLength, shaftRadius and jointRadius in the same way as for the UniversalJoint. A demo is provided by calling artisynth.demos.mech.UniversalJointDemo with the model arguments -skew <angDeg>, where <angDeg> is the desired skew angle in degrees.

Constructors for skewed universal joints take the standard forms described in Section 3.3.3, with an additional argument at the end indicating the skew angle:

In addition, the constructor

creates a skewed universal joint specifying the origin of frame D together with the directions of the roll and pitch axes (in world coordinates). Frames C and D are coincident and the skew angle is inferred from the angle between the axes.

The GimbalJoint (Figure 3.19) is a 3 DOF spherical joint that anchors the origins of C and D together but otherwise allows C complete rotational freedom. The rotational degrees of freedom are parameterized by three roll-pitch-yaw angles, denoted by , which define a rotation about D’s axis, followed by a second rotation about the rotated axis, followed by a third rotation about the final axis. It implements six constraints and the three coordinates (Table 3.6), to which the joint transform is related by

where

The value and ranges for are exported by the properties roll, pitch, yaw, rollRange, pitchRange, and yawRange, and the coordinate indices are defined by the constants ROLL_IDX, PITCH_IDX, and YAW_IDX. For rendering, the property jointRadius specifies the radius of a ball drawn around the origin of D, using the faceColor rendering property. A demo is provided by artisynth.demos.mech.GimbalJointDemo.

In addition to the standard constructors described in Section 3.3.3,

creates a gimbal joint with a specified origin for frame D (in world coordinates), and frames C and D coincident and world aligned.

The constraints implementing GimbalJoint are designed so that it is immune to gimbal lock, in which a degree of freedom is lost when . However, the coordinate values themselves are not immune to this singularity, and neither are the unilateral constraints which enforce limits on their values. Therefore, if coordinate limits are implemented, the joint should be deployed so as try and avoid pitch values near .

The SphericalJoint (Figure 3.20) is a 3 DOF spherical joint that, like GimbalJoint, anchors the origins of C and D together but otherwise allows C complete rotational freedom. SphericalJoint does not implement any coordinates, and so is conceptually more like a ball joint. However, it does provide two choices for limiting its rotation:

• •

  A limit on the tilt angle between the axes of D and C, such that

  (3.26)

  This is intended to emulate the limit imposed by a ball joint socket.

• •

  A limit on the total rotation, defined as follows: Let be the axis-angle representation of the rotation matrix of , normalized such that and , and let be a three-vector giving maximum rotation angles with , , and components. Then is constrained by

  (3.27)

  where denotes the element-wise product. If the components of are set to a uniform value , this simplifies to .

These limits can be enabled by setting the joint’s properties isTiltLimited and isRotationLimited, respectively, where enabling one disables the other. The limit values and are managed using the properties maxTilt and maxRotation, and setting either automatically enables tilt or rotation limiting, as appropriate. Finally, the tilt angle can be queried using the (read-only) tilt property. For rendering, the property jointRadius specifies the radius of a ball drawn around the origin of D, using the faceColor rendering property. A demo of the SphericalJoint is provided by artisynth.demos.mech.SphericalJointDemo.

In addition to the standard constructors described in Section 3.3.3,

creates a spherical joint with a specified origin for frame D (in world coordinates), and frames C and D coincident and world aligned.

One should use the rotation limit with some caution, as the orientations which it prohibits can be somewhat hard to predict, particularly when has non-uniform values.

The PlanarJoint (Figure 3.21) is a 3 DOF joint that constrains C to translation in the - plane and rotation about the axis of D. It implements six constraints and three coordinates , and (Table 3.8), to which the joint transform is related by

The value and ranges for , and are exported by the properties x, y, theta, xRange, yRange and thetaRange, and the coordinate indices are defined by the constants X_IDX, Y_IDX and THETA_IDX. A planar joint can be rendered as a square centered on the origin of D, using face rendering properties and with a size given by the planeSize property. For example,

will cause joint to be drawn as a light gray square with size 5.0. The default value of planeSize is 0, so drawing the plane is disabled by default. Also, the default faceStyle rendering property for PlanarConnector is set to FRONT_AND_BACK, so that the plane (when drawn) can be seen from both sides. A shaft about the rotation axis can also be drawn, as controlled by the properties shaftLength and shaftRadius and using the faceColor rendering property. A demo is provided by artisynth.demos.mech.PlanarJointDemo.

In addition to the standard constructors described in Section 3.3.3,

creates a planar joint with a specified origin and axis direction for frame D (in world coordinates), and frames C and D coincident.

The PlanarTranslationJoint (Figure 3.22) is a 2 DOF joint that is the same as the planar joint without rotation: C is restricted to translation in the - plane of D. It implements six constraints and two coordinates and (Table 3.9), to which the joint transform is related by

The value and ranges for and are exported by the properties x, y, xRange and yRange, and the coordinate indices are defined by the constants X_IDX and Y_IDX. A planar translation joint can be rendered as a square centered on the origin of D, using face rendering properties and with a size given by the planeSize property, in the same way as described for PlanarJoint. A demo is provided by artisynth.demos.mech.PlanarJointDemo.

In addition to the standard constructors described in Section 3.3.3,

creates a planar translation joint with a specified origin and axis direction for frame D (in world coordinates), and frames C and D coincident.

The EllipsoidJoint is a 4 DOF joint that provides similar functionality to the ellipsoidal and scapulothoracic joints available in OpenSim. It allows the origin of C to slide around on the surface of an ellipsoid centered on the origin of D, together with two additional rotational degrees of freedom.

The joint kinematics is easiest to describe in terms of an intermediate frame S whose origin lies on the ellipsoid surface, with its position controlled by two coordinates: a longitude angle , and a latitude angle (Figure 3.23, left). Frame C has the same origin as S, with two additional coordinates, and which allow it to rotate about S (Figure 3.23, middle). If the transform from S to D and the (rotational-only) transform from C to S are given by

then is given by

The six constraints and four coordinates of the ellipsoidal joint are described in table 3.10.

For frame S, if , and are the ellipsoid semi-axis lengths for the , , and axes, and , , , and are the cosines and sines of and , we can show that

For the orientation of S, the axis of S is parallel to the surface normal and the axis is parallel to the tangent direction imparted by the latitudinal velocity . That means and axes are parallel to the direction vectors and given by

(3.28)

The columns of are then given by the normalized values of , , and , respectively.

The rotation is formed by a rotation about the axis, followed by a rotation of about the new axis. Letting , , , and be the cosines and sines of and , we then have

If desired, the rotation can instead be performed about a modified axis that makes an angle with respect to in the - plane. is controlled by the joint’s alpha property (default value ) and corresponds to the “winging” angle of the OpenSim scapulothoracic joint. If , takes the more complex form

where , , , and are the cosines and sines of and , respectively.

Within an EllipsoidJoint, the values and ranges for , , and are exported by the properties longitude, latitude, theta, phi, longitudeRange, latitudeRange, thetaRange, and phiRange, and the coordinate indices are defined by the constants LONGITUDE_IDX, LATITUDE_IDX, THETA_IDX, and PHI_IDX. For rendering, the property drawEllipsoid specifies whether the ellipsoid surface should be drawn; if true, it will be drawn using the joint’s face rendering properties. A demo is provided by artisynth.demos.mech.EllipsoidJointDemo.

Ellipsoid joints can be created with the following constructors:

The first of these creates a joint that is not attached to any bodies; attachment can be done later using one of the setBodies() methods. Its semi-axis lengths are given by A, B, and C, its angle is given by alpha, and the argument openSimCompatible, if true, makes the joint kinematics compatible with OpenSim (Section 3.4.11.1). The second constructor creates a joint and then attaches it to rigid bodies rbodyA and rbodyB, with the specified and transformations. The third constructor creates a joint and attaches it to connectable bodies cbodyA and cbodyB, with the locations of the C and D frames specified in world coordinates by TCW and TDW.

Unlike in many joints, is not the identity when the joint coordinates are all . That is because the origin of C must lie on the ellipsoid surface, and since D is at the center of the ellipsoid, can never be the identity. In particular, when all coordinate values are 0, but .

The SolidJoint is a 0 DOF joint that rigidly constrains C to D. It implements six constraints and no coordinates (Table 3.11) and the resulting is the identity.

There aren’t normally many uses for solid joints. If one wishes to create a complex rigid body by joining together a variety of shapes, this can be done more efficiently by making these shapes mesh components of a single rigid body (Section 3.2.9).

The PlanarConnector (Figure 3.24) is a 5 DOF connector that attaches the origin of C to the - plane of D. C is completely free to rotate, and to translate within the - plane. Only motion in the direction is restricted. PlanarConnector implements one constraint and has no coordinates (Table 3.12).

A PlanarConnector constrains a point on body A (located at the origin of C) to move within a plane on body B. Several planar connectors can be employed to constrain body motions in more complicated ways, although one must be careful to avoid overconstraining the system. The connector can also be configured to function unilaterally, via its unilateral property, in which case the point is constrained to lie in the half-space defined by with respect to D. Several unilateral PlanarConnectors can therefore be used to implement a cheap and approximate collision mechanism with fixed collision points.

When set to function unilaterally, overconstraining the system is not an issue because of the way in which ArtiSynth solves unilateral constraints.

A planar connector can be rendered as a square centered on the origin of D, using face rendering properties and with a size given by the planeSize property. The point attached to A can also be rendered using point rendering properties. For example,

will cause connector to be drawn as a light gray square with size 5, and for the point on body A to be drawn as a blue sphere with radius 0.1. The default value of planeSize is 0, so drawing the plane is disabled by default. Also, the default faceStyle rendering property for PlanarConnector is set to FRONT_AND_BACK, so that the plane (when drawn) can be seen from both sides.

Constructors for the PlanarConnector include

where pCA gives the connection point of body A with respect to frame A, TDB gives the transform from frame D to frame B, and TDW gives the transform from frame D to world.

The SegmentedPlanarConnector (Figure 3.25) is a 5 DOF connector that generalizes PlanarConnector to a piecewise linear surface, to which the origin of is constrained while is otherwise completely free to rotate. The surface is specified by a sequence of 2D points defining a piecewise linear curve in the - plane of D (Figure 3.25, left). This curve does not need to be a function; the segment nearest to C is the one used to enforce the constraint at any given time. The surface has infinite extent and is extrapolated beyond the first and last segments. It implements one constraint and has no coordinates (Table 3.13).

By appropriate choice of segments, a SegmentedPlanarConnector can approximate any surface defined by a curve in the - plane. As with PlanarConnector, it can also be configured as unilateral, constraining the origin of to lie on the side of the surface defined by the normal vectors of each segment . If and are the points in the - plane defining the -th segment, and is the axis unit vector, then is given by

(3.30)

The properties controlling the rendering of a segmented planar connector are the same as for a planar connector, with each of the individual plane segments drawn as a rectangle whose length along the axis is controlled by planeSize.

Constructors for a SegmentedPlanarConnector are analogous to those used for PlanarConnector,

where segs is an additional argument of type double[] giving the 2D coordinates defining the segments in the - plane.

ArtiSynth maintains three legacy joint for compatibility with earlier software:

• •

  RevoluteJoint is identical to the HingeJoint, except that its coordinate is oriented clockwise about the axis instead of counter-clockwise. Rendering is also done differently, with shafts about the rotation axis drawn using line rendering properties.

• •

  RollPitchJoint is identical to the UniversalJoint, except that its roll-pitch coordinates are computed with respect to the rotation from frame D to C, instead of the rotation from frame C to D. Rendering is also done differently, with shafts along the roll and pitch axes drawn using line rendering properties, and the ball around the origin of D drawn using point rendering properties.

• •

  SphericalRpyJoint is identical to the GimbalJoint, except that its roll-pitch-yaw coordinates are computed with respect to the rotation from frame D to C, instead of the rotation from frame C to D. Rendering is also done differently, with the ball around the origin of D drawn using point rendering properties.