ArtiSynth supplies a number of basic joints and connectors in the package artisynth.core.mechmodels, the most common of which are described here.
Many of the descriptions are associated with a demonstration model, named XXXJointDemo, where XXX is the joint type. These demos are located in the package artisynth.demos.mech, and can be loaded by selecting All demos > mech > XXXJointDemo from the Models menu. When run, they can be interactively controlled, using either the pull tool (see the section “Pull Manipulation” in the ArtiSynth User Interface Guide), or the interactive control panel. The control panel allows the adjustment of coordinate values and ranges (if supported), some of the render properties, and the different compliance and damping properties (Section 3.3.7). One can inspect the source code for each demo in its .java file located in the folder <ARTISYNTH_HOME>/src/artisynth/demos/mech.
The HingeJoint (Figure 3.12) 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.
Index | type/name | description |
---|---|---|
0 | bilateral | restricts translation along |
1 | bilateral | restricts translation along |
2 | bilateral | restricts translation along |
3 | bilateral | restricts rotation about |
4 | bilateral | restricts rotation about |
5 | unilataral | enforces limits on |
0 | counter-clockwise rotation of about the axis |
The SliderJoint (Figure 3.13) 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.
Index | type/name | description |
---|---|---|
0 | bilateral | restricts translation along |
1 | bilateral | restricts translation along |
2 | bilateral | restricts rotation about |
3 | bilateral | restricts rotation about |
4 | bilateral | restricts rotation about |
5 | unilataral | enforces limits on the coordinate |
0 | translation of along the axis |
The CylindricalJoint (Figure 3.14) 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.
Index | type/name | description |
---|---|---|
0 | bilateral | restricts translation along |
1 | bilateral | restricts translation along |
2 | bilateral | restricts rotation about |
3 | bilateral | restricts rotation about |
4 | unilataral | enforces limits on the coordinate |
5 | unilataral | enforces limits on the coordinate |
0 | translation of along the axis | |
1 | rotation of about the axis |
The SlottedHingeJoint (Figure 3.15) 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.24) |
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.
Index | type/name | description |
---|---|---|
0 | bilateral | restricts translation along |
1 | bilateral | restricts translation along |
2 | bilateral | restricts rotation about |
3 | bilateral | restricts rotation about |
4 | unilataral | enforces limits on the coordinate |
5 | unilataral | enforces limits on the coordinate |
0 | translation of along the axis | |
1 | rotation of about the axis |
Index | type/name | description |
---|---|---|
0 | bilateral | restricts translation along |
1 | bilateral | restricts translation along |
2 | bilateral | restricts translation along |
3 | bilateral | restricts rotation about the final axis of C |
4 | unilataral | enforces limits on the roll coordinate |
5 | unilataral | enforces limits on the pitch coordinate |
0 | (roll) | first rotation of about the axis of D |
1 | (pitch) | second rotation of about the rotated axis |
The UniversalJoint (Figure 3.16) 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.17) 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.18) 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 .
Index | type/name | description |
---|---|---|
0 | bilateral | restricts translation along |
1 | bilateral | restricts translation along |
2 | bilateral | restricts translation along |
3 | unilataral | enforces limits on the roll coordinate |
4 | unilataral | enforces limits on the pitch coordinate |
5 | unilataral | enforces limits on the yaw coordinate |
0 | (roll) | first rotation of about the axis of D |
1 | (pitch) | second rotation of about the rotated axis |
2 | (yaw) | third rotation of about the final axis |
The SphericalJoint (Figure 3.19) 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.25) |
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.26) |
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.
Index | type/name | description |
---|---|---|
0 | bilateral | restricts translation along |
1 | bilateral | restricts translation along |
2 | bilateral | restricts translation along |
3 | unilataral | enforces either the “tilt” or “rotation” limits |
The PlanarJoint (Figure 3.20) 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 grey 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.
Index | type/name | description |
---|---|---|
0 | bilateral | restricts translation along |
1 | bilateral | restricts rotation about |
2 | bilateral | restricts rotation about |
3 | unilataral | enforces limits on the coordinate |
3 | unilataral | enforces limits on the coordinate |
5 | unilataral | enforces limits on the coordinate |
0 | translation of along the axis of D | |
1 | translation of along the axis of D | |
2 | rotation of about the axis of D |
Index | type/name | description |
---|---|---|
0 | bilateral | restricts translation along |
1 | bilateral | restricts rotation about |
2 | bilateral | restricts rotation about |
3 | bilateral | restricts rotation about |
4 | unilataral | enforces limits on the coordinate |
5 | unilataral | enforces limits on the coordinate |
0 | translation of along the axis of D | |
1 | translation of along the axis of D |
The PlanarTranslationJoint (Figure 3.21) 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.
The SolidJoint is a 0 DOF joint that rigidly constrains C to D. It implements six constraints and no coordinates (Table 3.10) 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.8).
Index | type/name | description |
---|---|---|
0 | bilateral | restricts translation along |
1 | bilateral | restricts translation along |
2 | bilateral | restricts translation along |
3 | bilateral | restricts rotation about |
4 | bilateral | restricts rotation about |
5 | bilateral | restricts rotation about |
Index | type/name | description |
---|---|---|
0 | bilateral or unilateral | restricts translation along |
The PlanarConnector (Figure 3.22) 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.11).
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 grey 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.
Index | type/name | description |
---|---|---|
0 | bilateral or unilateral | restricts translation normal to the surface |
The SegmentedPlanarConnector (Figure 3.23) 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.23, 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.12).
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.27) |
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.