Clean things up

Author: mcm001

src/main/java/org/photonvision/mrcal/MrCalJNI.java

@@ -28,6 +28,13 @@
 import org.opencv.core.MatOfPoint2f;
 
 public class MrCalJNI {
+    public static enum CameraLensModel {
+        LENSMODEL_OPENCV5,
+        LENSMODEL_OPENCV8,
+        LENSMODEL_STEREOGRAPHIC,
+        LENSMODEL_SPLINED_STEREOGRAPHIC;
+    }
+
     public static class MrCalResult {
         public boolean success;
         public double[] intrinsics;
@@ -121,6 +128,29 @@ public String toString() {
         }
     }
 
+    /**
+     * Performs camera calibration using [mrcal](https://mrcal.secretsauce.net/formulation.html)
+     *
+     * @param observations_board a packed double array containing all observations across all frames.
+     *     The array is structured as a flattened list where each observation consists of 3
+     *     consecutive doubles: [x, y, level] for each corner of each board in each frame. Structure:
+     *     For N frames, each observing a boardWidth×boardHeight checkerboard, the array has length N
+     *     × boardWidth × boardHeight × 3. The level value (0-based) represents detection quality and
+     *     will be converted to a weight using weight = 0.5^level. A negative level indicates the
+     *     corner was not detected (will be marked as an outlier).
+     * @param boardWidth the number of internal corners in the horizontal direction of the calibration
+     *     board
+     * @param boardHeight the number of internal corners in the vertical direction of the calibration
+     *     board
+     * @param boardSpacing the physical distance (in arbitrary but consistent units) between adjacent
+     *     corners on the calibration board. PhotonVision uses meters.
+     * @param imageWidth the width in pixels of the images used for calibration
+     * @param imageHeight the height in pixels of the images used for calibration
+     * @param focalLen an initial guess for the focal length in pixels, used to seed the optimization
+     * @return an {@link MrCalResult} object containing the calibration results, including optimized
+     *     intrinsics, board poses, RMS error, per-observation residuals, detected outliers, and a
+     *     boolean mask indicating which corners were actually used in the final optimization
+     */
     public static native MrCalResult mrcal_calibrate_camera(
             double[] observations_board,
             int boardWidth,
@@ -130,8 +160,34 @@ public static native MrCalResult mrcal_calibrate_camera(
             int imageHeight,
             double focalLen);
 
+    /**
+     * Applies mrcal lens distortion correction to undistort pixel coordinates.
+     *
+     * <p>This method takes distorted pixel coordinates and applies the inverse of mrcal's lens
+     * distortion model to produce undistorted (corrected) coordinates. The input coordinates are
+     * unprojected through the specified lens model to 3D ray vectors, then reprojected through a
+     * pinhole model.
+     *
+     * @param dstMat a pointer to a cv::Mat containing distorted pixel coordinates (passed as a long
+     *     representing the memory address). Must be a CV_64FC2 continuous matrix where each row
+     *     contains one (x, y) coordinate pair. The matrix is modified in-place with the undistorted
+     *     coordinates as output.
+     * @param cameraMat a pointer to the camera calibration matrix cv::Mat (3×3, opencv format).
+     * @param distCoeffsMat a pointer to the distortion coefficients cv::Mat. The interpretation of
+     *     these coefficients depends on the specified lens model.
+     * @param lensModelOrdinal the ordinal value of the {@link CameraLensModel} enum indicating which
+     *     lens distortion model to use for undistortion
+     * @param order the spline interpolation order to use when warping pixels, if the lensmodel is
+     *     splined. Unused otherwise
+     * @param Nx the number of control points in the x-direction for the distortion spline model.
+     *     Unused otherwise
+     * @param Ny the number of control points in the y-direction for the distortion spline model.
+     *     Unused otherwise
+     * @param fov_x_deg the horizontal field of view in degrees used for certain lens model, if
+     *     splined. Unused otherwise calculations
+     * @return true if the undistortion was successful, false otherwise
+     */
     public static native boolean undistort_mrcal(
-            long srcMat,
             long dstMat,
             long cameraMat,
             long distCoeffsMat,
@@ -141,6 +197,44 @@ public static native boolean undistort_mrcal(
             int Ny,
             int fov_x_deg);
 
+    /**
+     * Computes projection uncertainty for camera calibration across a grid of image points.
+     *
+     * <p>This method evaluates the uncertainty in 3D point projection due to calibration error. It
+     * computes uncertainty at a regular grid of points across the image plane.
+     *
+     * @param observations_board a packed double array containing calibration observations with the
+     *     same structure as used in {@link #mrcal_calibrate_camera}. For N frames observing a
+     *     boardWidth×boardHeight checkerboard, the array has length N × boardWidth × boardHeight × 3,
+     *     where each triplet is [x, y, level].
+     * @param intrinsics a double array containing the camera intrinsic parameters. The exact content
+     *     and length depend on the lens distortion model being used, but typically includes focal
+     *     length, principal point, and distortion coefficients.
+     * @param rt_ref_frames a packed double array containing the poses (rotations and translations) of
+     *     the calibration board relative to the camera for each frame. The array is structured as N
+     *     consecutive 6-element groups, where each group represents one frame's pose: [rx, ry, rz,
+     *     tx, ty, tz]. The rotation components (rx, ry, rz) form a rotation vector (axis-angle
+     *     representation), and (tx, ty, tz) represent the translation. Total array length is N × 6,
+     *     where N is the number of observed frames.
+     * @param boardWidth the number of internal corners in the horizontal direction of the calibration
+     *     board
+     * @param boardHeight the number of internal corners in the vertical direction of the calibration
+     *     board
+     * @param boardSpacing the physical distance between adjacent corners on the calibration board
+     *     (must match the value used in calibration). PhotonVision uses meters.
+     * @param imageWidth the width in pixels of the camera imager at this particular VideoMode
+     * @param imageHeight the height in pixels of the camera imager at this particular VideoMode
+     * @param sampleGridWidth the number of sample points in the horizontal direction for uncertainty
+     *     computation
+     * @param sampleGridHeight the number of sample points in the vertical direction for uncertainty
+     *     computation
+     * @param warpX the x-component of lens distortion warp, or zero if no warp was estimated.
+     * @param warpY the y-component of lens distortion warp
+     * @return a packed double array containing uncertainty values at each sampled grid point. The
+     *     array is structured as a sequence of 3D points (mrcal_point3_t), representing [u, v,
+     *     uncertainty] for each point we sampled. Total array length is sampleGridWidth ×
+     *     sampleGridHeight × 3. Returns null if computation fails.
+     */
     public static native double[] compute_uncertainty(
             double[] observations_board,
             double[] intrinsics,
@@ -155,7 +249,14 @@ public static native double[] compute_uncertainty(
             double warpX,
             double warpY);
 
-    public static double[] makeObservations(
+    /**
+     * Convert a list of board-pixel-corners and detection levels for each snapshot of a chessboard
+     * boardWidth x boardHeight to a packed double[] suitable to pass to
+     * MrCalJni::mrcal_calibrate_camera. Levels will be converted to weights using weight = 0.5^level,
+     * as explained
+     * [here](https://github.com/dkogan/mrcal/blob/7cd9ac4c854a4b244a35f554c9ebd0464d59e9ff/mrcal-calibrate-cameras#L152)
+     */
+    private static double[] makeObservations(
             List<MatOfPoint2f> board_corners,
             List<MatOfFloat> board_corner_levels,
             int boardWidth,
@@ -192,6 +293,23 @@ public static double[] makeObservations(
         return observations;
     }
 
+    /**
+     * High-level wrapper for camera calibration using mrcal.
+     *
+     * <p>Converts detected chessboard corners and their detection levels into a packed double array,
+     * then calls {@link #mrcal_calibrate_camera} to perform calibration. Each corner's detection
+     * level is converted to a weight (0.5^level), and negative levels indicate undetected corners.
+     *
+     * @param board_corners List of detected chessboard corners for each frame
+     * @param board_corner_levels List of detection levels for each corner in each frame. Point weight is calculated as weight = 0.5^level. Negative weight will ignore this observation
+     * @param boardWidth Number of internal corners horizontally
+     * @param boardHeight Number of internal corners vertically
+     * @param boardSpacing Physical spacing between corners (meters)
+     * @param imageWidth Image width in pixels
+     * @param imageHeight Image height in pixels
+     * @param focalLen Initial guess for focal length (pixels)
+     * @return Calibration result with optimized intrinsics, poses, and error metrics
+     */
     public static MrCalResult calibrateCamera(
             List<MatOfPoint2f> board_corners,
             List<MatOfFloat> board_corner_levels,

src/mrcal_jni.cpp

@@ -273,16 +273,15 @@ Java_org_photonvision_mrcal_MrCalJNI_mrcal_1calibrate_1camera
 /*
  * Class:     org_photonvision_mrcal_MrCalJNI_undistort
  * Method:    1mrcal
- * Signature: (JJJJIIIII)Z
+ * Signature: (JJJIIIII)Z
  */
 JNIEXPORT jboolean JNICALL
 Java_org_photonvision_mrcal_MrCalJNI_undistort_1mrcal
-  (JNIEnv *, jclass, jlong srcMat, jlong dstMat, jlong camMat, jlong distCoeffs,
+  (JNIEnv *, jclass, jlong dstMat, jlong camMat, jlong distCoeffs,
    jint lensModelOrdinal, jint order, jint Nx, jint Ny, jint fov_x_deg)
 {
   return undistort_mrcal(
-      reinterpret_cast<cv::Mat *>(srcMat), reinterpret_cast<cv::Mat *>(dstMat),
-      reinterpret_cast<cv::Mat *>(camMat),
+      reinterpret_cast<cv::Mat *>(dstMat), reinterpret_cast<cv::Mat *>(camMat),
       reinterpret_cast<cv::Mat *>(distCoeffs),
       static_cast<CameraLensModel>(lensModelOrdinal),
       static_cast<uint16_t>(order), static_cast<uint16_t>(Nx),

src/mrcal_wrapper.cpp

@@ -501,7 +501,7 @@ std::unique_ptr<mrcal_result> mrcal_main(
   return result;
 }
 
-bool undistort_mrcal(const cv::Mat *src, cv::Mat *dst, const cv::Mat *cameraMat,
+bool undistort_mrcal(cv::Mat *dst, const cv::Mat *cameraMat,
                      const cv::Mat *distCoeffs, CameraLensModel lensModel,
                      // Extra stuff for splined stereographic models
                      uint16_t order, uint16_t Nx, uint16_t Ny,
@@ -536,15 +536,15 @@ bool undistort_mrcal(const cv::Mat *src, cv::Mat *dst, const cv::Mat *cameraMat,
     return false;
   }
 
-  if (!(dst->cols == 2 && dst->cols == 2)) {
+  if (!(dst->cols == 2)) {
     std::cerr << "Bad input array size\n";
     return false;
   }
-  if (!(dst->type() == CV_64FC2 && dst->type() == CV_64FC2)) {
+  if (!(dst->type() == CV_64FC2)) {
     std::cerr << "Bad input type -- need CV_64F\n";
     return false;
   }
-  if (!(dst->isContinuous() && dst->isContinuous())) {
+  if (!(dst->isContinuous())) {
     std::cerr << "Bad input array -- need continuous\n";
     return false;
   }

src/mrcal_wrapper.h

@@ -88,7 +88,7 @@ enum class CameraLensModel {
   LENSMODEL_SPLINED_STEREOGRAPHIC
 };
 
-bool undistort_mrcal(const cv::Mat *src, cv::Mat *dst, const cv::Mat *cameraMat,
+bool undistort_mrcal(cv::Mat *dst, const cv::Mat *cameraMat,
                      const cv::Mat *distCoeffs, CameraLensModel lensModel,
                      // Extra stuff for splined stereographic models
                      uint16_t order, uint16_t Nx, uint16_t Ny,