migrate camera_calibration documentation (#937)

camera_calibration/doc/api.rst

@@ -0,0 +1,8 @@
+API Documentation
+=================
+
+.. autoclass:: camera_calibration.calibrator.MonoCalibrator
+    :members:
+
+.. autoclass:: camera_calibration.calibrator.StereoCalibrator
+    :members:

camera_calibration/doc/changes.rst

@@ -0,0 +1,12 @@
+Changelog Notes
+===============
+
+Jazzy Jalisco
+-------------
+There are several major change between ``Iron`` and ``Jazzy``:
+
+ * All components now properly support ``image_transport`` parameter.
+ * All components now properly support remapping the ``camera_info`` topic
+   for an associated ``image`` topic. For instance, if you remap ``image``
+   to ``my/image`` then ``my/camera_info`` will be used. Previously you
+   would have to manually remap the ``camera_info`` topic.

camera_calibration/doc/components.rst

@@ -0,0 +1,52 @@
+Nodes
+=====
+
+This package includes a number of ROS 2 components that can be assembled
+into image processing pipelines.
+See the tutorial :ref:`Launch image_proc Components`.
+
+Alternatively, each component can be run as a standalone node.
+
+camera_calibrator
+-----------------
+``cameracalibrator`` subscribes to ROS raw image topics, and presents a
+calibration window. It can run in both monocular and stereo modes.
+The calibration window shows the current images from the cameras,
+highlighting the checkerboard. When the user presses the **CALIBRATE**
+button, the node computes the camera calibration parameters. When the
+user clicks **COMMIT**, the node uploads these new calibration parameters
+to the camera driver using a service call.
+
+Subscribed Topics
+^^^^^^^^^^^^^^^^^
+ * **image** (sensor_msgs/Image): Raw image topic, for monocular cameras.
+ * **left** (sensor_msgs/Image): Raw left image topic, for stereo cameras.
+ * **right** (sensor_msgs/Image): Raw right image topic, for stereo cameras.
+
+Services Called
+^^^^^^^^^^^^^^^
+ * **camera/set_camera_info** (sensor_msgs/SetCameraInfo): Sets the camera
+   info for a monocular camera.
+ * **left_camera/set_camera_info** (sensor_msgs/SetCameraInfo): Sets the camera
+   info for the left camera of a stereo pair.
+ * **right_camera/set_camera_info** (sensor_msgs/SetCameraInfo): Sets the camera
+   info for the right camera of a stereo pair.
+
+camera_check
+------------
+``cameracheck`` subscribes to ROS rectified image topics and their associated
+camera_info, and prints out an error estimate. It can run in both monocular
+and stereo modes. The program expects to see a standard checkerboard target.
+
+Subscribed Topics
+^^^^^^^^^^^^^^^^^
+ * **monocular/image** (sensor_msgs/Image): Rectified image topic, for
+   monocular camera.
+ * **monocular/camera_info** (sensor_msgs/CameraInfo): Camera info for
+   the monocular camera.
+ * **stereo/left/image** (sensor_msgs/Image): Rectified left image topic,
+   for stereo cameras.
+ * **stereo/right/image** (sensor_msgs/Image): Rectified right image topic,
+   for stereo cameras.
+ * **stereo/camera_info** (sensor_msgs/CameraInfo): Camera info for the
+   stereo pair.

camera_calibration/doc/conf.py

@@ -22,7 +22,13 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', 'sphinx.ext.pngmath']
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.doctest',
+    'sphinx.ext.coverage',
+    'sphinx_rtd_theme',
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -40,12 +46,6 @@
 project = 'camera_calibration'
 copyright = '2009, Willow Garage, Inc.'
 
-# The version info for the project you're documenting, acts as replacement for
-# |version| and |release|, also used in various other places throughout the
-# built documents.
-#
-# The short X.Y version.
-version = '0.1'
 # The full version, including alpha/beta/rc tags.
 release = '0.1.0'
 
@@ -195,7 +195,6 @@
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {
-    'http://docs.python.org/': None,
-    'http://docs.scipy.org/doc/numpy' : None,
-    'http://www.ros.org/doc/api/tf/html/python/' : None
-    }
+    'python': ('http://docs.python.org/', None),
+    'numpy': ('http://docs.scipy.org/doc/numpy', None)
+}

camera_calibration/doc/index.rst

@@ -1,18 +1,138 @@
-camera_calibration
-==================
+Overview
+========
 
-The camera_calibration package contains a user-friendly calibration tool,
-cameracalibrator.  This tool uses the following Python classes, which
-conveniently hide some of the complexities of using OpenCV's calibration
-process and chessboard detection, and the details of constructing a ROS
-CameraInfo message.  These classes are documented here for people who
-need to extend or make a new calibration tool.
+This package uses OpenCV camera calibration, described
+`here <https://docs.opencv.org/4.5.4/d9/d0c/group__calib3d.html>`_.
+For detailed information on the parameters produced by the calibration, see this
+`description <http://docs.ros.org/en/rolling/p/image_pipeline/camera_info.html>`_.
 
-For details on the camera model and camera calibration process, see
-http://docs.opencv.org/master/d9/d0c/group__calib3d.html
+The code API listed for this package is for convenience only.
+This package has no supported code API.
 
-.. autoclass:: camera_calibration.calibrator.MonoCalibrator
-    :members:
+For pinhole type cameras this package names the distortion model as **plumb_bob**
+or **rational_polynomial**, depending on number of parameters used. For fisheye
+type cameras this package uses the **equidistant** distortion model.
 
-.. autoclass:: camera_calibration.calibrator.StereoCalibrator
-    :members:
+Tutorials
+---------
+There are tutorials on how to run the calibration tool for monocular and
+stereo cameras.
+
+Camera Calibrator Usage
+-----------------------
+To run the ``cameracalibrator`` node for a monocular camera using an 8x6
+chessboard with 108mm squares:
+
+.. code-block:: bash
+
+   ros2 run camera_calibration cameracalibrator --size 8x6 --square 0.108 image:=/my_camera/image camera:=/my_camera
+
+When you click on the **Save** button after a succesfull calibration,
+the data (calibration data and images used for calibration) will
+be written to ``/tmp/calibrationdata.tar.gz``.
+
+To run the ``cameracalibrator`` node for a stereo camera:
+
+.. code-block:: bash
+
+    ros2 run camera_calibration cameracalibrator --size 8x6 --square 0.108 right:=/my_stereo/right/image_raw left:=/my_stereo/left/image_raw left_camera:=/my_stereo/left right_camera:=/my_stereo/right
+
+
+``cameracalibrator`` supports the following options:
+
+  Chessboard Options:
+    You must specify one or more chessboards as pairs of --size and
+    --square options.
+
+    -p PATTERN, --pattern=PATTERN
+                        calibration pattern to detect - 'chessboard',
+                        'circles', 'acircles'
+    -s SIZE, --size=SIZE
+                        chessboard size as NxM, counting interior corners
+                        (e.g. a standard chessboard is 7x7)
+    -q SQUARE, --square=SQUARE
+                        chessboard square size in meters
+
+  ROS Communication Options:
+    --approximate=APPROXIMATE
+                        allow specified slop (in seconds) when pairing images
+                        from unsynchronized stereo cameras
+    --no-service-check  disable check for set_camera_info services at startup
+    --queue-size=QUEUE_SIZE
+                        image queue size (default 1, set to 0 for unlimited)
+
+  Calibration Optimizer Options:
+    --fix-principal-point
+                        for pinhole, fix the principal point at the image
+                        center
+    --fix-aspect-ratio  for pinhole, enforce focal lengths (fx, fy) are equal
+    --zero-tangent-dist
+                        for pinhole, set tangential distortion coefficients
+                        (p1, p2) to zero
+    -k NUM_COEFFS, --k-coefficients=NUM_COEFFS
+                        for pinhole, number of radial distortion coefficients
+                        to use (up to 6, default 2)
+    --fisheye-recompute-extrinsicsts
+                        for fisheye, extrinsic will be recomputed after each
+                        iteration of intrinsic optimization
+    --fisheye-fix-skew  for fisheye, skew coefficient (alpha) is set to zero
+                        and stay zero
+    --fisheye-fix-principal-point
+                        for fisheye,fix the principal point at the image
+                        center
+    --fisheye-k-coefficients=NUM_COEFFS
+                        for fisheye, number of radial distortion coefficients
+                        to use fixing to zero the rest (up to 4, default 4)
+    --fisheye-check-conditions
+                        for fisheye, the functions will check validity of
+                        condition number
+    --disable_calib_cb_fast_check
+                        uses the CALIB_CB_FAST_CHECK flag for
+                        findChessboardCorners
+    --max-chessboard-speed=MAX_CHESSBOARD_SPEED
+                        Do not use samples where the calibration pattern is
+                        moving faster                      than this speed in
+                        px/frame. Set to eg. 0.5 for rolling shutter cameras.
+
+Unsynchronized Stereo
+---------------------
+By default, the ``image_pipeline`` assumes that stereo cameras are triggered
+to capture images simultaneously, and that matching image pairs have identical
+timestamps. This is the ideal situation, but requires hardware support.
+
+If your stereo pairs are not (or inexactly) synchronized, enable approximate
+timestamp matching ``--approximate=0.01`` option. This permits a "slop" of
+0.01s between image pairs. If you still don't see a display window, or it
+is sporadically updated, try increasing the slop.
+
+Dual Checkerboards
+------------------
+It is possible to use multiple size checkerboards to calibrate a camera.
+
+To use multiple checkerboards, give multiple ``--size`` and ``--square``
+options for additional boards. Make sure the boards have different
+dimensions, so the calibration system can tell them apart.
+
+Camera Check
+------------
+To run the command-line utility to check the calibration of a monocular camera:
+
+.. code-block:: bash
+
+    ros2 run camera_calibration cameracheck --size 8x6 monocular:=/forearm image:=image_rect
+
+To run the command-line utility to check the calibration of a stereo camera:
+
+.. code-block:: bash
+
+    ros2 run camera_calibration cameracheck --size 8x6 stereo:=/wide_stereo image:=image_rect
+
+.. toctree::
+   :maxdepth: 2
+
+   self
+   components
+   tutorial_mono
+   tutorial_stereo
+   api
+   changes