Add mrcal and camera inspection docs (#305)

* Add mrcal and camera inspection docs

* Update calibration.rst

* Flashbang!

* Update calibration.rst

* Address comments

source/docs/calibration/calibration.rst

@@ -82,8 +82,78 @@ Now, we'll capture images of our chessboard from various angles. The most import
 Accessing Calibration Images
 ----------------------------
 
-For advanced users, these calibrations can be later accessed by :ref:`exporting your config directory <docs/additional-resources/config:Directory Structure>` and viewing the camera's config.json file. Furthermore, the most recent snapshots will be saved to the calibImgs directory. The example images below are from `the calibdb website <https://calibdb.net>` -- focus on how the target is oriented, as the same general tips for positioning apply for chessboard targets as for ChArUco.
+Details about a particular calibration can be viewed by clicking on that resolution in the calibrations tab. This tab allows you to download raw calibration data, upload a previous calibration, and inspect details about calculated camera intrinsics.
 
-.. image:: images/calibImgs.png
+.. image:: images/cal-details.png
    :width: 600
    :alt: Captured calibration images
+
+.. note:: More info on what these parameters mean can be found in `OpenCV's docs <https://docs.opencv.org/4.8.0/d4/d94/tutorial_camera_calibration.html>`_
+
+- Fx/Fy: Estimated camera focal length, in mm
+- Fx/Cy: Estimated camera optical center, in pixels. This should be at about the center of the image
+- Distortion: OpenCV camera model distortion coefficients
+- FOV: calculated using estimated focal length and image size. Useful for gut-checking calibration results
+- Mean Err: Mean reprojection error, or distance between expected and observed chessboard cameras for the full calibration dataset
+
+Below these outputs are the snapshots collected for calibration, along with a per-snapshot mean reprojection error. A snapshot with a larger reprojection error might indicate a bad snapshot, due to effects such as motion blur or misidentified chessboard corners.
+
+Calibration images can also be extracted from the downloaded JSON file using `this Python script <https://raw.githubusercontent.com/PhotonVision/photonvision/master/devTools/calibrationUtils.py>`_. This script will unpack calibration images, and also generate a VNL file for use `with mrcal <https://mrcal.secretsauce.net/>`_.
+
+::
+
+  python3 /path/to/calibrationUtils.py path/to/photon_calibration.json /path/to/output/folder
+
+.. image:: images/unpacked-json.png
+   :width: 600
+   :alt: Captured calibration images
+
+
+Investigating Calibration Data with mrcal
+-----------------------------------------
+
+`mrcal <https://mrcal.secretsauce.net/tour.html>`_ is a command-line tool for camera calibration and visualization. PhotonVision has the option to use the mrcal backend during camera calibration to estimate intrinsics. mrcal can also be used post-calibration to inspect snapshots and provide feedback. These steps will closely follow the `mrcal tour <https://mrcal.secretsauce.net/tour-initial-calibration.html>`_ -- I'm aggregating commands and notes here, but the mrcal documentation is much more thorough.
+
+Start by `Installing mrcal <https://mrcal.secretsauce.net/install.html>`_. Note that while mrcal *calibration* using Photon is supported on all platforms, but investigation right now only works on Linux. Some users have also reported luck using `WSL 2 on Windows <https://learn.microsoft.com/en-us/windows/wsl/tutorials/gui-apps>`ap_ as well. You may also need to install ``feedgnuplot``. On Ubuntu systems, these commands should be run from a standalone terminal and *not* the one `built into vscode <https://github.com/ros2/ros2/issues/1406>`_.
+
+Let's run ``calibrationUtils.py`` as described above, and then cd into the output folder. From here, you can follow the mrcal tour, just replacing the VNL filename and camera imager size as necessary. My camera calibration was at 1280x720, so I've set the XY limits to that below.
+
+::
+
+   $ cd /path/to/output/folder
+   $ ls
+   matt@photonvision:~/Documents/Downloads/2024-01-02_lifecam_1280$ ls
+     corners.vnl  img0.png  img10.png  img11.png  img12.png  img13.png  img1.png
+     img2.png  img3.png  img4.png  img5.png  img6.png  img7.png  img8.png
+     img9.png  cameramodel_0.cameramodel
+
+   $ < corners.vnl       \
+     vnl-filter -p x,y | \
+     feedgnuplot --domain --square --set 'xrange [0:1280] noextend' --set 'yrange [720:0] noextend'
+
+.. image:: images/mrcal-coverage.svg
+   :alt: A diagram showing the locations of all detected chessboard corners.
+
+As you can see, we didn't do a fantastic job of covering our whole camera sensor -- there's a big gap across the whole right side, for example. We also only have 14 calibration images. We've also got our "cameramodel" file, which can be used by mrcal to display additional debug info.
+
+Let's inspect our reprojection error residuals. We expect their magnitudes and directions to be random -- if there's patterns in the colors shown, then our calibration probably doesn't fully explain our physical camera sensor.
+
+::
+
+   $ mrcal-show-residuals --magnitudes --set 'cbrange [0:1.5]' ./camera-0.cameramodel
+   $ mrcal-show-residuals --directions --unset key ./camera-0.cameramodel
+
+.. image:: images/residual-magnitudes.svg
+   :alt: A diagram showing residual magnitudes
+
+.. image:: images/residual-directions.svg
+   :alt: A diagram showing residual directions
+
+Clearly we don't have anywhere near enough data to draw any meaningful conclusions (yet). But for fun, let's dig into `camera uncertainty estimation <https://mrcal.secretsauce.net/tour-uncertainty.html>`_. This diagram shows how expected projection error changes due to noise in calibration inputs. Lower projection error across a larger area of the sensor imply a better calibration that more fully covers the whole sensor. For my calibration data, you can tell the projection error isolines (lines of constant expected projection error) are skewed to the left, following my dataset (which was also skewed left).
+
+::
+
+   $ mrcal-show-projection-uncertainty --unset key ./cameramodel_0.cameramodel
+
+.. image:: images/camera-uncertainty.svg
+   :alt: A diagram showing camera uncertainty