start to port camera_calibration

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/2.4/modules/calib3d/doc/camera_calibration_and_3d_reconstruction.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

camera_calibration/doc/tutorial_mono.rst

@@ -0,0 +1,2 @@
+Tutorial: Monocular Calibration
+===============================

camera_calibration/doc/tutorial_stereo.rst

@@ -0,0 +1,2 @@
+Tutorial: Stereo Calibration
+============================

camera_calibration/package.xml

@@ -36,5 +36,6 @@
 
   <export>
     <build_type>ament_python</build_type>
+    <rosdoc2>rosdoc2.yaml</rosdoc2>
   </export>
 </package>

camera_calibration/rosdoc2.yaml

@@ -0,0 +1,68 @@
+## Default configuration, generated by rosdoc2.
+
+## This 'attic section' self-documents this file's type and version.
+type: 'rosdoc2 config'
+version: 1
+
+---
+
+settings:
+    ## If this is true, a standard index page is generated in the output directory.
+    ## It uses the package information from the 'package.xml' to show details
+    ## about the package, creates a table of contents for the various builders
+    ## that were run, and may contain links to things like build farm jobs for
+    ## this package or links to other versions of this package.
+
+    ## If false, you can still include content that would have been in the index
+    ## into one of your '.rst' files from your Sphinx project, using the
+    ## '.. include::' directive in Sphinx.
+    ## For example, you could include it in a custom 'index.rst' so you can have
+    ## the standard information followed by custom content.
+
+    ## TODO(wjwwood): provide a concrete example of this (relative path?)
+
+    ## If this is not specified explicitly, it defaults to 'true'.
+    generate_package_index: true
+
+    ## This setting is relevant mostly if the standard Python package layout cannot
+    ## be assumed for 'sphinx-apidoc' invocation. The user can provide the path
+    ## (relative to the 'package.xml' file) where the Python modules defined by this
+    ## package are located.
+    python_source: 'src/camera_calibration'
+
+    ## This setting, if true, attempts to run `doxygen` and the `breathe`/`exhale`
+    ## extensions to `sphinx` regardless of build type. This is most useful if the
+    ## user would like to generate C/C++ API documentation for a package that is not
+    ## of the `ament_cmake/cmake` build type.
+    always_run_doxygen: false
+
+    ## This setting, if true, attempts to run `sphinx-apidoc` regardless of build
+    ## type. This is most useful if the user would like to generate Python API
+    ## documentation for a package that is not of the `ament_python` build type.
+    always_run_sphinx_apidoc: false
+
+    # This setting, if provided, will override the build_type of this package
+    # for documentation purposes only. If not provided, documentation will be
+    # generated assuming the build_type in package.xml.
+    # override_build_type: 'ament_python'
+builders:
+    ## Each stanza represents a separate build step, performed by a specific 'builder'.
+    ## The key of each stanza is the builder to use; this must be one of the
+    ## available builders.
+    ## The value of each stanza is a dictionary of settings for the builder that
+    ## outputs to that directory.
+    ## Required keys in the settings dictionary are:
+    ##  * 'output_dir' - determines output subdirectory for builder instance
+    ##                   relative to --output-directory
+    ##  * 'name' - used when referencing the built docs from the index.
+
+    - doxygen: {
+        name: 'camera_calibration Public C/C++ API',
+        output_dir: 'generated/doxygen'
+    }
+    - sphinx: {
+        name: 'camera_calibration',
+        ## This path is relative to output staging.
+        doxygen_xml_directory: 'generated/doxygen/xml',
+        output_dir: ''
+    }