Geometry
EasyStack’s geometry classes describe positions, orientations, and movement in a two-dimensional space. They provide the calculations needed to represent where a robot is, define target locations, work with movement vectors, and update a position estimate as the robot moves.
Before using these classes, choose a consistent coordinate system and distance unit. For example, you can use meters for distances, with positive X pointing forward and positive Y pointing left in the robot’s local coordinate system. Positive rotations are counterclockwise. Keep these conventions consistent with your drivetrain, sensors, and localization system.
The classes work together, with each one representing a different part of the robot’s geometry:
| Class | What you use it for |
|---|---|
| Translation2d | Representing a position or displacement using X and Y coordinates. |
| Rotation2d | Representing an angle or heading. |
| Pose2d | Combining a position and heading into a complete robot pose. |
| Transform2d | Describing a change from one pose to another. |
| Twist2d | Describing local movement that includes translation and rotation along an arc. |
| Vector2d | Performing calculations with directions, velocities, and other vector quantities. |
Start with Translation2d when you need to describe a location, such as the robot’s starting position or a target point on the field. Provide its X and Y coordinates using your chosen distance unit. You can then calculate the distance between points, add displacements, rotate coordinates around the origin, or interpolate between two positions.
Use Rotation2d to describe which direction the robot is facing. You can create a rotation from radians, degrees, or full rotations using the corresponding factory methods. The single-value constructor accepts radians. When reading an angle, choose between the stored value and the wrapped angle depending on whether you need to preserve the original number of rotations or work with an equivalent direction.
Once you have a position and orientation, combine them into a Pose2d. This is the class you would normally use to store the robot’s estimated location on the field or define a destination with a desired heading. A pose stores the values you provide; it does not read sensors or track the robot automatically. Your localization code must calculate and supply updated poses.
When you need to describe a movement relative to an existing pose, use Transform2d. Its translation is expressed in the starting pose’s coordinate system. For example, applying a forward displacement to a robot facing sideways moves it along its own forward direction. You can also create a transform from two poses, combine consecutive transforms, or invert a transform to describe the reverse change.
For movement that combines translation and rotation during the same interval, use Twist2d. Supply the local displacement components through dx and dy, and the angular displacement in radians through dtheta. Apply the twist with Pose2d.exp() to calculate an updated pose that accounts for the curved motion. Your odometry code is responsible for deriving those displacements from measurements. You can also use Pose2d.log() to calculate a twist connecting two poses.
Use Vector2d when working with quantities such as movement directions or chassis velocities. It supports vector addition, scaling, rotation, normalization, projection, and magnitude limiting. For example, you can rotate a requested velocity into another coordinate frame or limit its magnitude while preserving its direction. Choose units based on what the vector represents, and use a nonnegative limit when calling clampNorm().
All six classes are immutable. Operations such as adding, rotating, or scaling return a result rather than modifying the original object. As a user, you must save or pass that returned value wherever you need the updated geometry.
For a typical robot application, begin with Translation2d, Rotation2d, and Pose2d to describe positions and headings. Add Transform2d for relative changes, Twist2d for motion integration, and Vector2d for movement calculations as your application needs them.
Last updated 2026-11-16