[apriltag] Improve AprilTag docs (wpilibsuite#5895)

apriltag/src/main/java/edu/wpi/first/apriltag/AprilTagDetection.java

@@ -95,7 +95,7 @@ public double getCenterY() {
 
   /**
    * Gets a corner of the tag in image pixel coordinates. These always wrap counter-clock wise
-   * around the tag.
+   * around the tag. Index 0 is the bottom left corner.
    *
    * @param ndx Corner index (range is 0-3, inclusive)
    * @return Corner point X coordinate
@@ -106,7 +106,7 @@ public double getCornerX(int ndx) {
 
   /**
    * Gets a corner of the tag in image pixel coordinates. These always wrap counter-clock wise
-   * around the tag.
+   * around the tag. Index 0 is the bottom left corner.
    *
    * @param ndx Corner index (range is 0-3, inclusive)
    * @return Corner point Y coordinate
@@ -117,7 +117,8 @@ public double getCornerY(int ndx) {
 
   /**
    * Gets the corners of the tag in image pixel coordinates. These always wrap counter-clock wise
-   * around the tag.
+   * around the tag. The first set of corner coordinates are the coordinates for the bottom left
+   * corner.
    *
    * @return Corner point array (X and Y for each corner in order)
    */

apriltag/src/main/java/edu/wpi/first/apriltag/AprilTagDetector.java

@@ -244,7 +244,7 @@ public void addFamily(String fam) {
    * Adds a family of tags to be detected.
    *
    * @param fam Family name, e.g. "tag16h5"
-   * @param bitsCorrected maximum number of bits to correct
+   * @param bitsCorrected Maximum number of bits to correct
    * @throws IllegalArgumentException if family name not recognized
    */
   public void addFamily(String fam, int bitsCorrected) {
@@ -270,6 +270,8 @@ public void clearFamilies() {
   /**
    * Detect tags from an 8-bit image.
    *
+   * <p>The image must be grayscale.
+   *
    * @param img 8-bit OpenCV Mat image
    * @return Results (array of AprilTagDetection)
    */

apriltag/src/main/java/edu/wpi/first/apriltag/jni/AprilTagJNI.java

@@ -44,31 +44,119 @@ public static void setExtractOnStaticLoad(boolean load) {
     }
   }
 
+  /**
+   * Constructs an AprilTag detector engine.
+   *
+   * @return The detector engine handle
+   */
   public static native long createDetector();
 
+  /**
+   * Destroys an AprilTag detector engine.
+   *
+   * @param det The detector engine handle
+   */
   public static native void destroyDetector(long det);
 
+  /**
+   * Sets the detector engine configuration.
+   *
+   * @param det The detector engine handle
+   * @param config A configuration
+   */
   public static native void setDetectorConfig(long det, AprilTagDetector.Config config);
 
+  /**
+   * Gets the detector engine configuration.
+   *
+   * @param det The detector engine handle
+   * @return The configuration
+   */
   public static native AprilTagDetector.Config getDetectorConfig(long det);
 
+  /**
+   * Sets the detector engine quad threshold parameters.
+   *
+   * @param det The detector engine handle
+   * @param params Quad threshold parameters
+   */
   public static native void setDetectorQTP(
       long det, AprilTagDetector.QuadThresholdParameters params);
 
+  /**
+   * Gets the detector engine quad threshold parameters.
+   *
+   * @param det The detector engine handle
+   * @return Quad threshold parameters
+   */
   public static native AprilTagDetector.QuadThresholdParameters getDetectorQTP(long det);
 
+  /**
+   * Adds a family of tags to be detected by the detector engine.
+   *
+   * @param det The detector engine handle
+   * @param fam Family name, e.g. "tag16h5"
+   * @param bitsCorrected Maximum number of bits to correct
+   * @return False if family can't be found
+   */
   public static native boolean addFamily(long det, String fam, int bitsCorrected);
 
+  /**
+   * Removes a family of tags from the detector.
+   *
+   * @param det The detector engine handle
+   * @param fam Family name, e.g. "tag16h5"
+   */
   public static native void removeFamily(long det, String fam);
 
+  /**
+   * Unregister all families.
+   *
+   * @param det The detector engine handle
+   */
   public static native void clearFamilies(long det);
 
+  /**
+   * Detect tags from an 8-bit image.
+   *
+   * @param det The detector engine handle
+   * @param width The width of the image
+   * @param height The height of the image
+   * @param stride The number of bytes between image rows (often the same as width)
+   * @param bufAddr The address of the image buffer
+   * @return The results (array of AprilTagDetection)
+   */
   public static native AprilTagDetection[] detect(
       long det, int width, int height, int stride, long bufAddr);
 
+  /**
+   * Estimates the pose of the tag using the homography method described in [1].
+   *
+   * @param homography Homography 3x3 matrix data
+   * @param tagSize The tag size, in meters
+   * @param fx The camera horizontal focal length, in pixels
+   * @param fy The camera vertical focal length, in pixels
+   * @param cx The camera horizontal focal center, in pixels
+   * @param cy The camera vertical focal center, in pixels
+   * @return Pose estimate
+   */
   public static native Transform3d estimatePoseHomography(
       double[] homography, double tagSize, double fx, double fy, double cx, double cy);
 
+  /**
+   * Estimates the pose of the tag. This returns one or two possible poses for the tag, along with
+   * the object-space error of each.
+   *
+   * @param homography Homography 3x3 matrix data
+   * @param corners Corner point array (X and Y for each corner in order)
+   * @param tagSize The tag size, in meters
+   * @param fx The camera horizontal focal length, in pixels
+   * @param fy The camera vertical focal length, in pixels
+   * @param cx The camera horizontal focal center, in pixels
+   * @param cy The camera vertical focal center, in pixels
+   * @param nIters Number of iterations
+   * @return Initial and (possibly) second pose estimates
+   */
   public static native AprilTagPoseEstimate estimatePoseOrthogonalIteration(
       double[] homography,
       double[] corners,
@@ -79,6 +167,20 @@ public static native AprilTagPoseEstimate estimatePoseOrthogonalIteration(
       double cy,
       int nIters);
 
+  /**
+   * Estimates tag pose. This method is an easier to use interface to
+   * EstimatePoseOrthogonalIteration(), running 50 iterations and returning the pose with the lower
+   * object-space error.
+   *
+   * @param homography Homography 3x3 matrix data
+   * @param corners Corner point array (X and Y for each corner in order)
+   * @param tagSize The tag size, in meters
+   * @param fx The camera horizontal focal length, in pixels
+   * @param fy The camera vertical focal length, in pixels
+   * @param cx The camera horizontal focal center, in pixels
+   * @param cy The camera vertical focal center, in pixels
+   * @return Pose estimate
+   */
   public static native Transform3d estimatePose(
       double[] homography,
       double[] corners,

apriltag/src/main/native/include/frc/apriltag/AprilTagDetection.h

@@ -93,7 +93,7 @@ class WPILIB_DLLEXPORT AprilTagDetection final {
 
   /**
    * Gets a corner of the tag in image pixel coordinates. These always
-   * wrap counter-clock wise around the tag.
+   * wrap counter-clock wise around the tag. Index 0 is the bottom left corner.
    *
    * @param ndx Corner index (range is 0-3, inclusive)
    * @return Corner point
@@ -104,7 +104,8 @@ class WPILIB_DLLEXPORT AprilTagDetection final {
 
   /**
    * Gets the corners of the tag in image pixel coordinates. These always
-   * wrap counter-clock wise around the tag.
+   * wrap counter-clock wise around the tag. The first set of corner coordinates
+   * are the coordinates for the bottom left corner.
    *
    * @param cornersBuf Corner point array (X and Y for each corner in order)
    * @return Corner point array (copy of cornersBuf span)

apriltag/src/main/native/include/frc/apriltag/AprilTagDetector.h

@@ -205,7 +205,7 @@ class WPILIB_DLLEXPORT AprilTagDetector {
    * Adds a family of tags to be detected.
    *
    * @param fam Family name, e.g. "tag16h5"
-   * @param bitsCorrected
+   * @param bitsCorrected Maximum number of bits to correct
    * @return False if family can't be found
    */
   bool AddFamily(std::string_view fam, int bitsCorrected = 2);
@@ -226,6 +226,7 @@ class WPILIB_DLLEXPORT AprilTagDetector {
 
   /**
    * Detect tags from an 8-bit image.
+   * The image must be grayscale.
    *
    * @param width width of the image
    * @param height height of the image
@@ -237,6 +238,7 @@ class WPILIB_DLLEXPORT AprilTagDetector {
 
   /**
    * Detect tags from an 8-bit image.
+   * The image must be grayscale.
    *
    * @param width width of the image
    * @param height height of the image