diff --git a/apriltag/src/main/java/edu/wpi/first/apriltag/AprilTagFieldLayout.java b/apriltag/src/main/java/edu/wpi/first/apriltag/AprilTagFieldLayout.java index aed1cb7376..eaca3cffeb 100644 --- a/apriltag/src/main/java/edu/wpi/first/apriltag/AprilTagFieldLayout.java +++ b/apriltag/src/main/java/edu/wpi/first/apriltag/AprilTagFieldLayout.java @@ -31,13 +31,13 @@ import java.util.Optional; * list of all AprilTags contained within a layout. Each AprilTag serializes to a JSON object * containing an ID and a Pose3d. The "field" object is a descriptor of the size of the field in * meters with "width" and "length" values. This is to account for arbitrary field sizes when - * mirroring the poses. + * transforming the poses. * - *

Pose3ds are assumed to be measured from the blue alliance right side of the field, when the - * blue alliance is at the left. Pose3ds will automatically be returned as passed in when calling - * {@link AprilTagFieldLayout#getTagPose(int)}. You can call {@link #setOrigin(OriginPosition)} to - * mirror the poses returned from {@link AprilTagFieldLayout#getTagPose(int)} to be correct relative - * to a custom frame. + *

Pose3ds are assumed to be measured from the bottom-left corner of the field, when the blue + * alliance is at the left. By default, Pose3ds will be returned as declared when calling {@link + * AprilTagFieldLayout#getTagPose(int)}. {@link #setOrigin(OriginPosition)} can be used to transform + * the poses returned from {@link AprilTagFieldLayout#getTagPose(int)} to be correct relative to a + * different coordinate frame. */ @JsonIgnoreProperties(ignoreUnknown = true) @JsonAutoDetect(getterVisibility = JsonAutoDetect.Visibility.NONE) @@ -82,8 +82,8 @@ public class AprilTagFieldLayout { * Construct a new AprilTagFieldLayout from a list of {@link AprilTag} objects. * * @param apriltags List of {@link AprilTag}. - * @param fieldLength Length of the field in meters. - * @param fieldWidth Width of the field in meters. + * @param fieldLength Length of the field the layout is representing in meters. + * @param fieldWidth Width of the field the layout is representing in meters. */ public AprilTagFieldLayout(List apriltags, double fieldLength, double fieldWidth) { this(apriltags, new FieldDimensions(fieldLength, fieldWidth)); @@ -101,23 +101,28 @@ public class AprilTagFieldLayout { setOrigin(OriginPosition.kBlueAllianceWallRightSide); } + /** + * Returns a List of the {@link AprilTag AprilTags} used in this layout. + * + * @return The {@link AprilTag AprilTags} used in this layout. + */ @JsonProperty("tags") public List getTags() { return new ArrayList<>(m_apriltags.values()); } /** - * Sets the origin based on a pre-known enumeration of positions. The position is calculated from - * values in the configuration file. + * Sets the origin based on a predefined enumeration of coordinate frame origins. The origins are + * calculated from the field dimensions. * - *

This changes the {@link #getTagPose(int)} method to return the correct pose for your - * alliance. + *

This transforms the Pose3ds returned by {@link #getTagPose(int)} to return the correct pose + * relative to a predefined coordinate frame. * - * @param position The predefined position + * @param origin The predefined origin */ @JsonIgnore - public void setOrigin(OriginPosition position) { - switch (position) { + public void setOrigin(OriginPosition origin) { + switch (origin) { case kBlueAllianceWallRightSide: setOrigin(new Pose3d()); break; @@ -135,8 +140,8 @@ public class AprilTagFieldLayout { /** * Sets the origin for tag pose transformation. * - *

This changes the {@link #getTagPose(int)} method to return the correct pose for your - * alliance. + *

This transforms the Pose3ds returned by {@link #getTagPose(int)} to return the correct pose + * relative to the provided origin. * * @param origin The new origin for tag transformations */ diff --git a/apriltag/src/main/native/cpp/AprilTagFieldLayout.cpp b/apriltag/src/main/native/cpp/AprilTagFieldLayout.cpp index 6ed49c63b0..22ac3ccbef 100644 --- a/apriltag/src/main/native/cpp/AprilTagFieldLayout.cpp +++ b/apriltag/src/main/native/cpp/AprilTagFieldLayout.cpp @@ -42,8 +42,8 @@ AprilTagFieldLayout::AprilTagFieldLayout(std::vector apriltags, } } -void AprilTagFieldLayout::SetOrigin(OriginPosition position) { - switch (position) { +void AprilTagFieldLayout::SetOrigin(OriginPosition origin) { + switch (origin) { case OriginPosition::kBlueAllianceWallRightSide: SetOrigin(Pose3d{}); break; diff --git a/apriltag/src/main/native/include/frc/apriltag/AprilTagFieldLayout.h b/apriltag/src/main/native/include/frc/apriltag/AprilTagFieldLayout.h index aab33443ec..1fe0b2adec 100644 --- a/apriltag/src/main/native/include/frc/apriltag/AprilTagFieldLayout.h +++ b/apriltag/src/main/native/include/frc/apriltag/AprilTagFieldLayout.h @@ -29,13 +29,14 @@ namespace frc { * AprilTag serializes to a JSON object containing an ID and a Pose3d. The * "field" object is a descriptor of the size of the field in meters with * "width" and "length" values. This is to account for arbitrary field sizes - * when mirroring the poses. + * when transforming the poses. * * Pose3ds are assumed to be measured from the bottom-left corner of the field, - * when the blue alliance is at the left. Pose3ds will automatically be returned - * as passed in when calling GetTagPose(int). Setting an alliance color via - * SetAlliance(DriverStation::Alliance) will mirror the poses returned from - * GetTagPose(int) to be correct relative to the other alliance. + * when the blue alliance is at the left. By default, Pose3ds will be returned + * as declared when calling GetTagPose(int). + * SetOrigin(AprilTagFieldLayout::OriginPosition) can be used to transform the + * poses returned by GetTagPose(int) to be correct relative to a different + * coordinate frame. */ class WPILIB_DLLEXPORT AprilTagFieldLayout { public: @@ -57,30 +58,30 @@ class WPILIB_DLLEXPORT AprilTagFieldLayout { * Construct a new AprilTagFieldLayout from a vector of AprilTag objects. * * @param apriltags Vector of AprilTags. - * @param fieldLength Length of field the layout of representing. + * @param fieldLength Length of field the layout is representing. * @param fieldWidth Width of field the layout is representing. */ AprilTagFieldLayout(std::vector apriltags, units::meter_t fieldLength, units::meter_t fieldWidth); /** - * Sets the origin based on a pre-known enumeration of positions. The position - * is calculated from values in the configuration file. + * Sets the origin based on a predefined enumeration of coordinate frame + * origins. The origins are calculated from the field dimensions. * - * This changes the GetTagPose(int) method to return the correct pose for your - * alliance. + * This transforms the Pose3ds returned by GetTagPose(int) to return the + * correct pose relative to a predefined coordinate frame. * - * @param alliance The alliance to mirror poses for. + * @param origin The predefined origin */ - void SetOrigin(OriginPosition position); + void SetOrigin(OriginPosition origin); /** * Sets the origin for tag pose transformation. * - * This changes the GetTagPose(int) method to return the correct pose for your - * alliance. + * This tranforms the Pose3ds returned by GetTagPose(int) to return the + * correct pose relative to the provided origin. * - * @param alliance The alliance to mirror poses for. + * @param origin The new origin for tag transformations */ void SetOrigin(const Pose3d& origin); diff --git a/apriltag/src/test/java/edu/wpi/first/apriltag/AprilTagPoseMirroringTest.java b/apriltag/src/test/java/edu/wpi/first/apriltag/AprilTagPoseSetOriginTest.java similarity index 96% rename from apriltag/src/test/java/edu/wpi/first/apriltag/AprilTagPoseMirroringTest.java rename to apriltag/src/test/java/edu/wpi/first/apriltag/AprilTagPoseSetOriginTest.java index e40a81fcfe..999fe8717d 100644 --- a/apriltag/src/test/java/edu/wpi/first/apriltag/AprilTagPoseMirroringTest.java +++ b/apriltag/src/test/java/edu/wpi/first/apriltag/AprilTagPoseSetOriginTest.java @@ -13,9 +13,9 @@ import edu.wpi.first.math.util.Units; import java.util.List; import org.junit.jupiter.api.Test; -class AprilTagPoseMirroringTest { +class AprilTagPoseSetOriginTest { @Test - void poseMirroring() { + void transformationMatches() { var layout = new AprilTagFieldLayout( List.of( diff --git a/apriltag/src/test/native/cpp/AprilTagPoseMirroringTest.cpp b/apriltag/src/test/native/cpp/AprilTagPoseSetOriginTest.cpp similarity index 94% rename from apriltag/src/test/native/cpp/AprilTagPoseMirroringTest.cpp rename to apriltag/src/test/native/cpp/AprilTagPoseSetOriginTest.cpp index 6efde2b317..38496495b2 100644 --- a/apriltag/src/test/native/cpp/AprilTagPoseMirroringTest.cpp +++ b/apriltag/src/test/native/cpp/AprilTagPoseSetOriginTest.cpp @@ -13,7 +13,7 @@ using namespace frc; -TEST(AprilTagPoseMirroringTest, MirroringMatches) { +TEST(AprilTagPoseSetOriginTest, TransformationMatches) { auto layout = AprilTagFieldLayout{ std::vector{ AprilTag{1,