Module org.dyn4j
Package org.dyn4j.dynamics.joint

Class PrismaticJoint<T extends PhysicsBody>

  • Type Parameters:
    T - the PhysicsBody type
    All Implemented Interfaces:
    DataContainer, Joint<T>, LinearLimitsJoint, LinearMotorJoint, LinearSpringJoint, PairedBodyJoint<T>, Shiftable, Ownable
    public class PrismaticJoint<T extends PhysicsBody>
extends AbstractPairedBodyJoint<T>
implements LinearLimitsJoint, LinearMotorJoint, LinearSpringJoint, PairedBodyJoint<T>, Joint<T>, Shiftable, DataContainer, Ownable
    Implementation of a prismatic joint.

    A prismatic joint constrains the linear motion of two bodies along an axis and prevents relative rotation. The whole system can rotate and translate freely.

    The initial relative rotation of the bodies will remain unchanged unless updated by calling setReferenceAngle(double) method. The bodies are not required to be aligned in any particular way.

    The world space axis is fixed to the first body. This means that when the first body rotates, the axis will rotate with it. The axis represents the allowed linear motion between the bodies.

    The world space anchor point can be any point but is typically a point on the axis of allowed motion, usually the world center of either of the joined bodies. The anchor point is used to track the separation of the bodies from the allowed axis of motion when drift occurs in the velocity solver.

    This joint also supports a linear spring, but is disabled by default. By default the frequency and damping ratio are set to 8.0 and 0.0 respectively. You can enable/disable the various spring-damper features using setSpringEnabled(boolean), setSpringDamperEnabled(boolean), setMaximumSpringForceEnabled(boolean) methods. As with all spring -damper enabled joints, the spring must be enabled for the damper to be applied. Also note that when the damper is disabled, the spring still experiences "damping" aka energy loss - this is a side effect of the solver and intended behavior.

    This joint has an added spring feature called the rest offset. Similar to the rest distance in the distance joint, but only applied when the spring is enabled. When you build the joint, the default distance between the two bodies is their initial distance. You can use the setSpringRestOffset(double) to raise or lower the distance between the bodies when the spring is active.

    The joint also supports upper and lower limits. The limits represent the maximum displacement from the anchor point along the given axis. This means that the limits are typically negative for the lower limit and positive for the upper limit. The limits are solved relative to the given axis's direction. The limits can be enabled separately using setLowerLimitEnabled(boolean) and setUpperLimitEnabled(boolean). This also means that the limits are relative to the initial starting position of the bodies.

    This joint also supports a motor. The motor is a linear motor along the axis. The motor speed can be positive or negative to indicate motion along or opposite the axis direction. The maximum motor force must be greater than zero for the motor to apply any motion. The motor must be enabled using setMotorEnabled(boolean).

    NOTE: The spring-damper and motor can be enabled at the same time, but since they operate on the same degree of freedom, the feature that has the highest maximum force will win. It's recommended to only use one or the other.

    NOTE: In versions of dyn4j before 5.0.0, the body arguments in the constructor were reversed. It was changed to accept the frame first, then the wheel to make things more natural.

    Since:
    1.0.0
    Version:
    5.0.0
    Author:
    William Bittle
    See Also:
    Documentation, Prismatic Constraint

    • Field Detail

      • localAnchor1

        protected final Vector2 localAnchor1
        The local anchor point on the first PhysicsBody

      • localAnchor2

        protected final Vector2 localAnchor2
        The local anchor point on the second PhysicsBody

      • xAxis

        protected final Vector2 xAxis
        The axis representing the allowed line of motion

      • yAxis

        protected final Vector2 yAxis
        The perpendicular axis of the line of motion

      • referenceAngle

        protected double referenceAngle
        The initial angle between the two PhysicsBodys

      • upperLimitEnabled

        protected boolean upperLimitEnabled
        True if the upper limit is enabled

      • lowerLimitEnabled

        protected boolean lowerLimitEnabled
        True if the lower limit is enabled

      • upperLimit

        protected double upperLimit
        the upper limit in meters

      • lowerLimit

        protected double lowerLimit
        the lower limit in meters

      • motorEnabled

        protected boolean motorEnabled
        Whether the motor is enabled or not

      • motorSpeed

        protected double motorSpeed
        The target velocity in meters / second

      • maximumMotorForceEnabled

        protected boolean maximumMotorForceEnabled
        True if the motor force should be limited

      • maximumMotorForce

        protected double maximumMotorForce
        The maximum force the motor can apply in newtons

      • springEnabled

        protected boolean springEnabled
        True if the spring is enabled

      • springDamperEnabled

        protected boolean springDamperEnabled
        True if the spring-damper is enabled

      • springMode

        protected int springMode
        The spring mode (frequency or stiffness)

      • springFrequency

        protected double springFrequency
        The oscillation frequency in hz

      • springStiffness

        protected double springStiffness
        The stiffness of the spring

      • springDampingRatio

        protected double springDampingRatio
        The damping ratio

      • springMaximumForceEnabled

        protected boolean springMaximumForceEnabled
        True if the spring maximum force is enabled

      • springMaximumForce

        protected double springMaximumForce
        The maximum force the spring will apply

      • springRestOffset

        protected double springRestOffset
        The rest offset of the spring

    • Constructor Detail

      • PrismaticJoint

        public PrismaticJoint​(T body1,
                      T body2,
                      Vector2 anchor,
                      Vector2 axis)
        Minimal constructor.
        Parameters:
        body1 - the first PhysicsBody
        body2 - the second PhysicsBody
        anchor - the anchor point in world coordinates
        axis - the axis of allowed motion
        Throws:
        NullPointerException - if body1, body2, anchor or axis is null
        IllegalArgumentException - if body1 == body2 or axis is the zero vector

    • Method Detail

      • initializeConstraints

        public void initializeConstraints​(TimeStep step,
                                  Settings settings)
        Description copied from interface: Joint
        Performs any initialization of the velocity and position constraints.
        Specified by:
        initializeConstraints in interface Joint<T extends PhysicsBody>
        Parameters:
        step - the time step information
        settings - the current world settings

      • solveVelocityConstraints

        public void solveVelocityConstraints​(TimeStep step,
                                     Settings settings)
        Description copied from interface: Joint
        Solves the velocity constraints.
        Specified by:
        solveVelocityConstraints in interface Joint<T extends PhysicsBody>
        Parameters:
        step - the time step information
        settings - the current world settings

      • solvePositionConstraints

        public boolean solvePositionConstraints​(TimeStep step,
                                        Settings settings)
        Description copied from interface: Joint
        Solves the position constraints.
        Specified by:
        solvePositionConstraints in interface Joint<T extends PhysicsBody>
        Parameters:
        step - the time step information
        settings - the current world settings
        Returns:
        boolean true if the position constraints were solved

      • updateSpringCoefficients

        protected void updateSpringCoefficients()
        Computes the spring coefficients from the current state of the joint.

        This method is intended to set the springStiffness OR springFrequency and damping for use during constraint solving.

      • getAnchor1

        public Vector2 getAnchor1()
        The original anchor point on body1 in world space.
        Returns:
        Vector2

      • getAnchor2

        public Vector2 getAnchor2()
        The original anchor point on body2 in world space.
        Returns:
        Vector2

      • getReactionForce

        public Vector2 getReactionForce​(double invdt)
        Description copied from interface: Joint
        Returns the force applied to the PhysicsBodys in order to satisfy the constraint in newtons.
        Specified by:
        getReactionForce in interface Joint<T extends PhysicsBody>
        Parameters:
        invdt - the inverse delta time
        Returns:
        Vector2

      • getReactionTorque

        public double getReactionTorque​(double invdt)
        Description copied from interface: Joint
        Returns the torque applied to the PhysicsBodys in order to satisfy the constraint in newton-meters.
        Specified by:
        getReactionTorque in interface Joint<T extends PhysicsBody>
        Parameters:
        invdt - the inverse delta time
        Returns:
        double

      • shift

        public void shift​(Vector2 shift)
        Description copied from interface: Shiftable
        Translates the object to match the given coordinate shift.
        Specified by:
        shift in interface Shiftable
        Parameters:
        shift - the amount to shift along the x and y axes

      • getLinearSpeed

        public double getLinearSpeed()
        Returns the current joint speed.

        Renamed from getJointSpeed in 5.0.0

        Returns:
        double
        Since:
        5.0.0

      • getLinearTranslation

        public double getLinearTranslation()
        Returns the current joint translation.

        Renamed from getJointTranslation in 5.0.0

        Returns:
        double
        Since:
        5.0.0

      • setMotorEnabled

        public void setMotorEnabled​(boolean motorEnabled)
        Description copied from interface: LinearMotorJoint
        Enables or disables the motor.
        Specified by:
        setMotorEnabled in interface LinearMotorJoint
        Parameters:
        motorEnabled - true if the motor should be enabled

      • getMotorSpeed

        public double getMotorSpeed()
        Description copied from interface: LinearMotorJoint
        Returns the target motor speed in meters / second.
        Specified by:
        getMotorSpeed in interface LinearMotorJoint
        Returns:
        double

      • getMaximumMotorForce

        public double getMaximumMotorForce()
        Description copied from interface: LinearMotorJoint
        Returns the maximum force the motor can apply to the joint to achieve the target speed.
        Specified by:
        getMaximumMotorForce in interface LinearMotorJoint
        Returns:
        double

      • setMaximumMotorForceEnabled

        public void setMaximumMotorForceEnabled​(boolean enabled)
        Description copied from interface: LinearMotorJoint
        Sets whether the maximum motor force is enabled.
        Specified by:
        setMaximumMotorForceEnabled in interface LinearMotorJoint
        Parameters:
        enabled - true if the maximum motor force should be enabled

      • getMotorForce

        public double getMotorForce​(double invdt)
        Description copied from interface: LinearMotorJoint
        Returns the applied motor force.
        Specified by:
        getMotorForce in interface LinearMotorJoint
        Parameters:
        invdt - the inverse delta time
        Returns:
        double

      • setSpringDampingRatio

        public void setSpringDampingRatio​(double dampingRatio)
        Description copied from interface: LinearSpringJoint
        Sets the damping ratio.

        Larger values reduce the oscillation of the spring.

        Specified by:
        setSpringDampingRatio in interface LinearSpringJoint
        Parameters:
        dampingRatio - the damping ratio; in the range (0, 1]

      • setSpringFrequency

        public void setSpringFrequency​(double frequency)
        Description copied from interface: LinearSpringJoint
        Sets the spring frequency.

        Larger values increase the stiffness of the spring.

        Calling this method puts the spring into fixed frequency mode. In this mode, the spring stiffness is computed based on the frequency.

        Specified by:
        setSpringFrequency in interface LinearSpringJoint
        Parameters:
        frequency - the spring frequency in hz; must be greater than zero

      • setSpringStiffness

        public void setSpringStiffness​(double stiffness)
        Description copied from interface: LinearSpringJoint
        Sets the spring stiffness.

        Larger values increase the stiffness of the spring.

        Calling this method puts the spring into fixed stiffness mode. In this mode, the spring frequency is computed based on the stiffness.

        Specified by:
        setSpringStiffness in interface LinearSpringJoint
        Parameters:
        stiffness - the spring stiffness (k); must be greater than zero

      • setMaximumSpringForce

        public void setMaximumSpringForce​(double maximum)
        Description copied from interface: LinearSpringJoint
        Sets the maximum force the spring can apply.
        Specified by:
        setMaximumSpringForce in interface LinearSpringJoint
        Parameters:
        maximum - the maximum force

      • setMaximumSpringForceEnabled

        public void setMaximumSpringForceEnabled​(boolean enabled)
        Description copied from interface: LinearSpringJoint
        Sets whether the spring force is limited to the maximum.
        Specified by:
        setMaximumSpringForceEnabled in interface LinearSpringJoint
        Parameters:
        enabled - true if the spring force should be limited

      • setSpringEnabled

        public void setSpringEnabled​(boolean enabled)
        Description copied from interface: LinearSpringJoint
        Sets whether the spring is enabled or not.
        Specified by:
        setSpringEnabled in interface LinearSpringJoint
        Parameters:
        enabled - true if the spring should be enabled

      • getSpringForce

        public double getSpringForce​(double invdt)
        Description copied from interface: LinearSpringJoint
        Returns the force in netwons applied by the spring in the last timestep.
        Specified by:
        getSpringForce in interface LinearSpringJoint
        Parameters:
        invdt - the inverse delta time
        Returns:
        double

      • setSpringRestOffset

        public void setSpringRestOffset​(double offset)
        Set's the spring rest offset.

        This can be any value and is used to offset the spring's rest distance. This is only applicable when the spring is enabled.

        Parameters:
        offset - the offset
        Since:
        5.0.0

      • getSpringRestOffset

        public double getSpringRestOffset()
        Returns the spring's rest offset.
        Returns:
        double
        Since:
        5.0.0

      • setUpperLimit

        public void setUpperLimit​(double upperLimit)
        Description copied from interface: LinearLimitsJoint
        Sets the upper limit in meters.
        Specified by:
        setUpperLimit in interface LinearLimitsJoint
        Parameters:
        upperLimit - the upper limit in meters

      • setUpperLimitEnabled

        public void setUpperLimitEnabled​(boolean flag)
        Description copied from interface: LinearLimitsJoint
        Sets whether the upper limit is enabled.
        Specified by:
        setUpperLimitEnabled in interface LinearLimitsJoint
        Parameters:
        flag - true if the upper limit should be enabled

      • isUpperLimitEnabled

        public boolean isUpperLimitEnabled()
        Description copied from interface: LinearLimitsJoint
        Returns true if the upper limit is enabled.
        Specified by:
        isUpperLimitEnabled in interface LinearLimitsJoint
        Returns:
        boolean true if the upper limit is enabled

      • setLowerLimit

        public void setLowerLimit​(double lowerLimit)
        Description copied from interface: LinearLimitsJoint
        Sets the lower limit in meters.
        Specified by:
        setLowerLimit in interface LinearLimitsJoint
        Parameters:
        lowerLimit - the lower limit in meters

      • setLowerLimitEnabled

        public void setLowerLimitEnabled​(boolean flag)
        Description copied from interface: LinearLimitsJoint
        Sets whether the lower limit is enabled.
        Specified by:
        setLowerLimitEnabled in interface LinearLimitsJoint
        Parameters:
        flag - true if the lower limit should be enabled

      • isLowerLimitEnabled

        public boolean isLowerLimitEnabled()
        Description copied from interface: LinearLimitsJoint
        Returns true if the lower limit is enabled.
        Specified by:
        isLowerLimitEnabled in interface LinearLimitsJoint
        Returns:
        boolean true if the lower limit is enabled

      • setLimits

        public void setLimits​(double lowerLimit,
                      double upperLimit)
        Description copied from interface: LinearLimitsJoint
        Sets both the lower and upper limits.
        Specified by:
        setLimits in interface LinearLimitsJoint
        Parameters:
        lowerLimit - the lower limit in meters
        upperLimit - the upper limit in meters

      • setLimitsEnabled

        public void setLimitsEnabled​(double lowerLimit,
                             double upperLimit)
        Description copied from interface: LinearLimitsJoint
        Sets both the lower and upper limits and enables both.
        Specified by:
        setLimitsEnabled in interface LinearLimitsJoint
        Parameters:
        lowerLimit - the lower limit in meters
        upperLimit - the upper limit in meters

      • setLimitsEnabled

        public void setLimitsEnabled​(boolean flag)
        Description copied from interface: LinearLimitsJoint
        Enables or disables both the lower and upper limits.
        Specified by:
        setLimitsEnabled in interface LinearLimitsJoint
        Parameters:
        flag - true if both limits should be enabled

      • setLimits

        public void setLimits​(double limit)
        Description copied from interface: LinearLimitsJoint
        Sets both the lower and upper limits to the given limit.
        Specified by:
        setLimits in interface LinearLimitsJoint
        Parameters:
        limit - the desired limit in meters

      • setLimitsEnabled

        public void setLimitsEnabled​(double limit)
        Description copied from interface: LinearLimitsJoint
        Sets both the lower and upper limits to the given limit and enables both.
        Specified by:
        setLimitsEnabled in interface LinearLimitsJoint
        Parameters:
        limit - the desired limit in meters

      • getAxis

        public Vector2 getAxis()
        Returns the axis in which the joint is allowed move along in world coordinates.
        Returns:
        Vector2
        Since:
        3.0.0

      • getReferenceAngle

        public double getReferenceAngle()
        Returns the reference angle.

        The reference angle is the angle calculated when the joint was created from the two joined bodies. The reference angle is the angular difference between the bodies.

        Returns:
        double
        Since:
        3.0.1

      • setReferenceAngle

        public void setReferenceAngle​(double angle)
        Sets the reference angle.

        This method can be used to set the reference angle to override the computed reference angle from the constructor. This is useful in recreating the joint from a current state.

        This can also be used to override the initial angle between the bodies.

        Parameters:
        angle - the reference angle
        Since:
        3.0.1
        See Also:
        getReferenceAngle()