Class MechanismPositionConfig

java.lang.Object
yams.core.mechanisms.config.MechanismPositionConfig
public class MechanismPositionConfig extends Object
A configuration class for specifying the position and visualization properties of a mechanism relative to a robot in a 3D coordinate system. This class allows setting and retrieving details such as the mechanism's position relative to the robot, the robot's maximum dimensions, and the plane in which the mechanism operates.

MechanismPositionConfig is used by SmartPositionalMechanism to drive the built-in Mechanism2d widget in Glass/Shuffleboard. It captures three pieces of information:

  • Robot-relative position a Translation3d that places the mechanism's pivot/root inside the robot frame. When set, the Mechanism2d window is automatically offset so the mechanism appears in the correct position relative to the robot outline.
  • Robot bounding box optional maximum length and height used to size the Mechanism2d canvas. When omitted, the canvas defaults to twice the mechanism's reported length.
  • Movement plane whether the mechanism moves in the XZ (default), YZ, or XY plane of the robot coordinate system. This determines which Translation3d axes are mapped to the 2D canvas X and Y axes.

It also places the mechanism in 3D, for each mechanism's getPose3d(): where it is mounted on the robot, and how it is turned there, optionally on another mechanism, such as an arm on an elevator's carriage.

Example

import static org.wpilib.units.Units.Meters;
import org.wpilib.math.geometry.Translation3d;
import yams.core.mechanisms.config.MechanismPositionConfig;

MechanismPositionConfig posConfig = new MechanismPositionConfig()
    .withRelativePosition(new Translation3d(0.2, 0.0, 0.3)) // 20 cm forward, 30 cm up
    .withMaxRobotLength(Meters.of(0.85))
    .withMaxRobotHeight(Meters.of(1.20))
    .withMovementPlane(MechanismPositionConfig.Plane.XZ);

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static enum 
    MechanismPositionConfig.Plane
    The planes that the mechanism could be on, used for position calculations.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected Optional<org.wpilib.units.measure.Distance>
    maxRobotHeight
    The height of the robot in meters.
    protected Optional<org.wpilib.units.measure.Distance>
    maxRobotLength
    The length of the robot in meters.
    protected org.wpilib.math.geometry.Rotation3d
    mountRotation
    How the mechanism is turned where it is mounted.
    protected Optional<Supplier<org.wpilib.math.geometry.Pose3d>>
    parent
    The pose the mechanism is mounted on, such as another mechanism's, or the robot's origin if empty.
    protected MechanismPositionConfig.Plane
    plane
    The plane that the mechanism is on, used for position calculations.
    protected Optional<org.wpilib.math.geometry.Translation3d>
    robotToMechanism
    The translation from the robot to the mechanism (Optional)

  • Constructor Summary

    Constructors
    Constructor
    Description
    MechanismPositionConfig()
    Create a MechanismPositionConfig with no relative position or robot size limits.

  • Method Summary

    Modifier and Type
    Method
    Description
    org.wpilib.units.measure.Distance
    getMechanismX(org.wpilib.units.measure.Distance length)
    Converts a given distance in the x-direction to a x-coordinate appropriate for visualizing on a Mechanism2d.
    org.wpilib.units.measure.Distance
    getMechanismY(org.wpilib.units.measure.Distance y)
    Gets the distance in the y-direction appropriate for visualizing on a Mechanism2d, defaults to the given distance.
    org.wpilib.math.geometry.Pose3d
    getMountPose()
    Where the mechanism is mounted: its parent's pose, or the robot's origin, moved and turned by its relative position.
    MechanismPositionConfig.Plane
    getMovementPlane()
    Get the plane that the mechanism is on.
    Optional<org.wpilib.math.geometry.Translation3d>
    getRelativePosition()
    Get the relative position of the mechanism to the robot.
    org.wpilib.math.geometry.Pose3d
    getRotatedPose(org.wpilib.units.measure.Angle angle)
    The pose of a part that turns about the axis normal to the movement plane, such as an arm or a pivot, at an angle.
    org.wpilib.math.geometry.Pose3d
    getTranslatedPose(org.wpilib.units.measure.Distance distance, org.wpilib.units.measure.Angle angle)
    The pose of a part that slides along the movement plane, such as an elevator's carriage.
    org.wpilib.units.measure.Distance
    getWindowXDimension(org.wpilib.units.measure.Distance length)
    Returns the x dimension of the window in the Mechanism2d for visualization, either the max robot length if set, or twice the given length.
    org.wpilib.units.measure.Distance
    getWindowYDimension(org.wpilib.units.measure.Distance length)
    Returns the y dimension of the window in the Mechanism2d for visualization, either the max robot height if set, or twice the given length.
    org.wpilib.math.geometry.Rotation3d
    rotationInPlane(org.wpilib.units.measure.Angle angle)
    The rotation of a part turned by an angle about the axis normal to the movement plane.
    MechanismPositionConfig
    withMaxRobotHeight(org.wpilib.units.measure.Distance robotHeight)
    Set the height of the robot for visualization purposes.
    MechanismPositionConfig
    withMaxRobotLength(org.wpilib.units.measure.Distance robotLength)
    Set the length of the robot for visualization purposes.
    MechanismPositionConfig
    withMovementPlane(MechanismPositionConfig.Plane plane)
    Set the plane that the mechanism is on, used for position calculations.
    MechanismPositionConfig
    withParent(Supplier<org.wpilib.math.geometry.Pose3d> parentPose)
    Mount the mechanism on another, such as an arm on an elevator's carriage, so it moves with it.
    MechanismPositionConfig
    withRelativePosition(org.wpilib.math.geometry.Transform3d robotToMechanism)
    Set where the mechanism is mounted, relative to the robot, or to its parent, and how it is turned there.
    MechanismPositionConfig
    withRelativePosition(org.wpilib.math.geometry.Translation3d robotToMechanism)
    Set the position of the SmartPositionalMechanism relative to the robot.

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • robotToMechanism

      protected Optional<org.wpilib.math.geometry.Translation3d> robotToMechanism
      The translation from the robot to the mechanism (Optional)

    • maxRobotLength

      protected Optional<org.wpilib.units.measure.Distance> maxRobotLength
      The length of the robot in meters.

    • maxRobotHeight

      protected Optional<org.wpilib.units.measure.Distance> maxRobotHeight
      The height of the robot in meters.

    • plane

      protected MechanismPositionConfig.Plane plane
      The plane that the mechanism is on, used for position calculations.

    • mountRotation

      protected org.wpilib.math.geometry.Rotation3d mountRotation
      How the mechanism is turned where it is mounted.

    • parent

      protected Optional<Supplier<org.wpilib.math.geometry.Pose3d>> parent
      The pose the mechanism is mounted on, such as another mechanism's, or the robot's origin if empty.

  • Constructor Details

    • MechanismPositionConfig

      public MechanismPositionConfig()
      Create a MechanismPositionConfig with no relative position or robot size limits.

  • Method Details

    • withRelativePosition

      public MechanismPositionConfig withRelativePosition(org.wpilib.math.geometry.Translation3d robotToMechanism)
      Set the position of the SmartPositionalMechanism relative to the robot.
      Parameters:
      robotToMechanism - Pose3d of the SmartPositionalMechanism relative to the robot.
      Returns:
      The SmartPositionalMechanism, for easy chaining.

    • withRelativePosition

      public MechanismPositionConfig withRelativePosition(org.wpilib.math.geometry.Transform3d robotToMechanism)
      Set where the mechanism is mounted, relative to the robot, or to its parent, and how it is turned there. The mechanism's pose is worked out from here: an arm's or pivot's axis, an elevator's carriage at zero height, or a flywheel's axle.
      Parameters:
      robotToMechanism - Transform3d from the robot, or from its parent, to the mechanism.
      Returns:
      The MechanismPositionConfig, for easy chaining.

    • withParent

      public MechanismPositionConfig withParent(Supplier<org.wpilib.math.geometry.Pose3d> parentPose)
      Mount the mechanism on another, such as an arm on an elevator's carriage, so it moves with it. The mechanism's relative position is then from the parent's pose, rather than from the robot.
      Parameters:
      parentPose - The pose the mechanism is mounted on, such as elevator::getPose3d.
      Returns:
      The MechanismPositionConfig, for easy chaining.

    • withMaxRobotLength

      public MechanismPositionConfig withMaxRobotLength(org.wpilib.units.measure.Distance robotLength)
      Set the length of the robot for visualization purposes.
      Parameters:
      robotLength - Length of the robot in meters.
      Returns:
      The SmartPositionalMechanism, for easy chaining.

    • withMaxRobotHeight

      public MechanismPositionConfig withMaxRobotHeight(org.wpilib.units.measure.Distance robotHeight)
      Set the height of the robot for visualization purposes.
      Parameters:
      robotHeight - Height of the robot in meters.
      Returns:
      The SmartPositionalMechanism, for easy chaining.

    • withMovementPlane

      public MechanismPositionConfig withMovementPlane(MechanismPositionConfig.Plane plane)
      Set the plane that the mechanism is on, used for position calculations.
      Parameters:
      plane - The plane that the mechanism is on. Default is X-Z plane.
      Returns:
      The SmartPositionalMechanism, for easy chaining.

    • getMechanismX

      public org.wpilib.units.measure.Distance getMechanismX(org.wpilib.units.measure.Distance length)
      Converts a given distance in the x-direction to a x-coordinate appropriate for visualizing on a Mechanism2d.
      Parameters:
      length - the distance in the x-direction
      Returns:
      the x-coordinate for visualizing on a Mechanism2d

    • getMechanismY

      public org.wpilib.units.measure.Distance getMechanismY(org.wpilib.units.measure.Distance y)
      Gets the distance in the y-direction appropriate for visualizing on a Mechanism2d, defaults to the given distance.
      Parameters:
      y - the default distance in the y-direction
      Returns:
      the y-coordinate for visualizing on a Mechanism2d

    • getWindowXDimension

      public org.wpilib.units.measure.Distance getWindowXDimension(org.wpilib.units.measure.Distance length)
      Returns the x dimension of the window in the Mechanism2d for visualization, either the max robot length if set, or twice the given length.
      Parameters:
      length - the length of the mechanism
      Returns:
      the x dimension of the window in the Mechanism2d

    • getWindowYDimension

      public org.wpilib.units.measure.Distance getWindowYDimension(org.wpilib.units.measure.Distance length)
      Returns the y dimension of the window in the Mechanism2d for visualization, either the max robot height if set, or twice the given length.
      Parameters:
      length - the length of the mechanism
      Returns:
      the y dimension of the window in the Mechanism2d

    • getRelativePosition

      public Optional<org.wpilib.math.geometry.Translation3d> getRelativePosition()
      Get the relative position of the mechanism to the robot.
      Returns:
      Translation3d representing the relative position. Defaults to a zero translation if not set.

    • getMovementPlane

      public MechanismPositionConfig.Plane getMovementPlane()
      Get the plane that the mechanism is on.
      Returns:
      The MechanismPositionConfig.Plane that the mechanism is on.

    • getMountPose

      public org.wpilib.math.geometry.Pose3d getMountPose()
      Where the mechanism is mounted: its parent's pose, or the robot's origin, moved and turned by its relative position.
      Returns:
      The Pose3d the mechanism is mounted at.

    • getRotatedPose

      public org.wpilib.math.geometry.Pose3d getRotatedPose(org.wpilib.units.measure.Angle angle)
      The pose of a part that turns about the axis normal to the movement plane, such as an arm or a pivot, at an angle. At 0 it points along +X in the XZ and XY planes, and along +Y in the YZ plane, and a positive angle turns it toward +Z in the XZ and YZ planes, and toward +Y in the XY plane.
      Parameters:
      angle - The angle it is turned to.
      Returns:
      Its Pose3d: where it is mounted, turned by the angle.

    • getTranslatedPose

      public org.wpilib.math.geometry.Pose3d getTranslatedPose(org.wpilib.units.measure.Distance distance, org.wpilib.units.measure.Angle angle)
      The pose of a part that slides along the movement plane, such as an elevator's carriage.
      Parameters:
      distance - How far it has slid from where it is mounted.
      angle - The direction it slides in, in the movement plane: 0 along +X (+Y in the YZ plane), 90 degrees along +Z (+Y in the XY plane).
      Returns:
      Its Pose3d: where it is mounted, moved by the distance, and not turned.

    • rotationInPlane

      public org.wpilib.math.geometry.Rotation3d rotationInPlane(org.wpilib.units.measure.Angle angle)
      The rotation of a part turned by an angle about the axis normal to the movement plane.
      Parameters:
      angle - The angle.
      Returns:
      The Rotation3d.