pattacini · Sep 28, 2026 · Sep 25, 2026
@@ -485,15 +485,19 @@ Do all steps above again for the other camera, changing the `--d 0` parameter to
 
 
 ### Calibrating cameras
-Now you need to ensure that the 2 cameras are perfectly aligned with each other. In order to do this, show a black cross to the robot at a specific distance (see pictures below) and adjust the cameras until reaching the correct alignment.
+The current calibration workflow uses `stereoCalib` to estimate the intrinsic parameters of both cameras and their relative pose. It supports the `pinhole` and `fisheye` camera models. Select the model that matches the camera optics in the configuration file before starting the acquisition.
+
+For a pinhole camera use the standard OpenCV model. Its distortion parameters are `k1`, `k2`, `p1`, and `p2`. For a fisheye camera use the OpenCV fisheye model. Its distortion parameters are `k1`, `k2`, `k3`, and `k4`.
+
+Now you need to ensure that the 2 cameras are perfectly aligned with each other. In order to do this, show a chessboard to the robot at a specific distance (see pictures below) and adjust the cameras until reaching the correct alignment.
 
 ![cam-3](./img/cameras-calib-3.png)
 
 ![cam-4](./img/cameras-calib-4.png)
 
 - Run `yarprobotinterface` and wait for robot calibration.
 
-- Run `yarpmanager`, open `Cameras` entity then run the 2 `yarpdev` modules and connect.
+- Run `yarpmanager`, open `Cameras` entity then run the 2 `yarpdev` or `yarprobotinterface` modules (it depends on the camera type) and connect.
 
 - Open and run ONLY the 2 yarpview modules and connect.
 
@@ -504,36 +508,64 @@ $ stereoCalib --from icubEyes.ini
 
 ```
 
+The configuration file must contain a `[STEREO_CALIBRATION_CONFIGURATION]` group. The following is a minimal example:
+
+```ini
+[STEREO_CALIBRATION_CONFIGURATION]
+boardWidth 8
+boardHeight 6
+boardSize 0.09241
+numberOfPairs 30
+cameraModel pinhole
+calibrationMode StereoFull
+syncToleranceMs 20
+syncQueueSize 5
+minCaptureIntervalSeconds 2
+minimumBoardSpanRatio 0.15
+```
+
+`boardWidth` and `boardHeight` are the numbers of inner corners in the chessboard. `boardSize` is the side length of one square in meters. At least 30 valid synchronized pairs are required. Set `cameraModel` to `fisheye` for fisheye calibration. The available calibration modes are `StereoFull`, `MonocularLeft`, `MonocularRight`, and `MonocularBoth`; use `StereoFull` for the normal two-camera procedure.
+
 !!!warning
-    DO NOT open the `StereoCalibration` app directly from yarpmanager otherwise you will not be able to see the result of the calibration process.
+    DO NOT run the `stereoCalib` module directly from yarpmanager otherwise you will not be able to see the result of the calibration process.
 
-- Then type:
+- Then, open another terminal and type:
 
 ```xml
 $ yarp rpc /stereoCalib/cmd
 ```
 
-hen type “start”, a message “Starting Calibration…” will appear.
+Then type `start`. The module reports the collection state and accepts `status`, `stop`, and `help` commands.
 
-Now show the chess to the robot taking care to move it with a different inclination for each acquisition (30 in total). Stay still and just move the chessboard around. The chess needs to fit all the screen and be in landscape view. The system only acquire data if the colored lines appear over the chessboard.
+Now, show the chess to the robot taking care to move it with a different inclination for each acquisition (30 in total). Stay still and just move the chessboard around. The chess needs to fit all the screen and be in landscape view. The system only acquire data if the colored lines appear over the chessboard.
 
-In the terminal of the stereoCalib you should see:
+In the terminal of the stereoCalib, you should see messages for the number of synchronized pairs, the accepted observations, and the reprojection errors. The module writes the result automatically to `outputCalib.ini` in its context. **Do not edit the file while calibration is running**.
 
-```xml 
-  Running Left Camera Calibration... 
-  RMS error reported by calibrateCamera: 0.592978  
-  Running Right Camera Calibration... 
-  RMS error reported by calibrateCamera: 0.147403
-  30 pairs have been successfully detected.
-  Running stereo calibration ...
-  done with RMS error= 0.717102
-  average reprojection err = 0.958607
-  Saving Calibration Results... 
-  ```
+For a pinhole calibration, the generated camera groups have this form:
 
-!!!info
-    To get good parameters you should see errors below 1.
+```ini
+[CAMERA_CALIBRATION_LEFT]
+projection pinhole
+w 640
+h 480
+fx  ...
+fy  ...
+cx  ...
+cy  ...
+k1  ...
+k2  ...
+p1  ...
+p2  ...
+
+[CAMERA_CALIBRATION_RIGHT]
+projection pinhole
+...
+```
+
+For a fisheye calibration, use the same file and replace `projection pinhole` with `projection fisheye`. The distortion entries are then `k1`, `k2`, `k3`, and `k4` instead of `k1`, `k2`, `p1`, and `p2`.
+
+The file also contains a `[STEREO_DISPARITY]` group with `HN`, `R`, and `T`. `HN` is the homogeneous transform from the left camera to the right camera; `R` and `T` are its rotation and translation. The `[CALIBRATION_QUALITY]` group records the monocular and stereo RMS errors, baseline, synchronized pairs, accepted observations, rejected detections, and timestamp statistics. For a good calibration, the reprojection errors should normally be below 1 pixel.
 
-❗ After calibration, you need to MANUALLY copy the calibration data inside the file iCubEyes.ini
+After checking the result, copy `[CAMERA_CALIBRATION_LEFT]`, `[CAMERA_CALIBRATION_RIGHT]` and the `HN` matrix to the camera configuration file used by the robot, for example `icubEyes.ini`.
 
 📚 For additional info look [here](./icub-stereo-calib.md).
@@ -1,28 +1,35 @@
 # Stereo calibration
-In this tutorial we explain how to run the stereo calibration procedure with the stereoCalib module. Before starting the procedure print a chessboard calibration pattern. For convenience, you can find it in `$ICUB_ROOT/app/cameraCalibration/data`.
+In this tutorial, we explain how to run the stereo calibration procedure with the `stereoCalib` module. The current implementation supports both the standard `pinhole` camera model and the `fisheye` camera model. Before starting the procedure print a chessboard calibration pattern. For convenience, you can find it in `$ICUB_ROOT/app/cameraCalibration/data`.
 
-Make sure you have a config file, e.g. cameraCalib.ini, with the following parameters:
+Make sure you have a config file, e.g. icubEyes.ini, with the following parameters:
 
 ```xml
 [STEREO_CALIBRATION_CONFIGURATION]
 boardWidth W
 boardHeight H
 boardSize S
-numberOfImages N
-MonoCalib value
+numberOfPairs N
+cameraModel pinhole|fisheye
+calibrationMode StereoFull
+syncToleranceMs 20
+syncQueueSize 5
+minCaptureIntervalSeconds 2
+minimumBoardSpanRatio 0.15
 ```
 
 - The `boardWidth` W is the number of corners along the width direction of the chessboard pattern (e.g. 8 for the provided pattern).
 - The `boardHeight` H is the number of corners along the height direction of the chessboard pattern (e.g. 6 for the provided pattern).
 - The `boardSize` S specifies the length (in meters) of one side of the squares in the chessboard pattern.
-- The `numberOfImages` N specifies the number of images used for the calibration procedure (usually 20-30).
-- The `MonoCalib` value identifies if the module has to run the stereo calibration (Val=0) or the mono calibration (Val=1). For the mono calibration, connect only the camera that you want to calibrate.
+- The `numberOfPairs` N specifies the number of synchronized stereo pairs used for the calibration procedure. At least 30 valid pairs are required.
+- The `cameraModel` selects `pinhole` or `fisheye` calibration. Use the model that matches the camera optics.
+- The `calibrationMode` selects `StereoFull`, `MonocularLeft`, `MonocularRight`, or `MonocularBoth`. For the normal procedure use `StereoFull`.
+- The synchronization and capture parameters limit the timestamp difference, queue size, time between accepted candidates, and minimum chessboard size. Their defaults are suitable for most setups.
 
-The group [STEREO_CALIBRATION_CONFIGURATION] is the only one used by the module, all the other groups in the config file will be ignored. As default the stereoCalib module uses the iCubEyes.ini located in $ICUB_ROOT/app/cameraCalibration/conf.
+The group `[STEREO_CALIBRATION_CONFIGURATION]` is the only one used by the module, all the other groups in the config file will be ignored. To understand which is the default file used by `stereoCalib` module, you can run `yarp resource --context cameraCalibration --from icubEyes.ini`.
 
-To run the calibration module and all the connections, you can use the stereoCalib.xml.template file provided in: $ICUB_ROOT/app/cameraCalibration/scripts. Additional details on the created ports can be found in the stereoCalib module page. Notice that some ports are for special purposes and are not useful to regular users.
+To run the calibration module and all the connections, you can use the `stereoCalib.xml.template` file provided in: $ICUB_ROOT/app/cameraCalibration/scripts. Additional details on the created ports can be found in the stereoCalib module page. Notice that some ports are for special purposes and are not useful to regular users.
 
-In order to start a calibration procedure open a new terminal and connect to the RPC port:
+In order to start a calibration procedure, open a new terminal and connect to the RPC port:
 
 ```xml
 yarp rpc /stereoCalib/cmd
@@ -34,20 +41,23 @@ The calibration procedure can be started writing the command:
 start
 ```
 
-Show now the chessboard pattern in landscape mode (see examples below). Try to cover the most part of the images and show it in different image positions in order to obtain a complete distortion map. As feedback you should see the detected corners in the two yarpview(s). The procedure continues to acquire images automatically after a short delay between one image and the next one.
+Use `status` to inspect the state and calibration quality, `stop` to stop collection, and `help` to list the commands.
+
+Show now the chessboard pattern in landscape mode (see examples below). Try to cover the most part of the images and show it in different image positions in order to obtain a complete distortion map. As feedback, you should see the detected corners in the two yarpview(s). The procedure continues to acquire images automatically after a short delay between one image and the next one.
 
 |Example of correct calibration image|Example of incorrect calibration image|
 |---|---|
 |![chess-1](./img/chess-1.png) | ![chess-2](./img/chess-2.png)|
 
 The values printed above are related to the average reprojection error of the 3D points to the image plane. To get good parameters you should see errors below 1 pixel.
 
-The parameters will be saved in the output file located in the context of the module (default: $ICUB_ROOT/app/cameraCalibration/conf/outputCalib.ini).
+The parameters are saved automatically in the output file located in the context of the module (default: `$ICUB_ROOT/app/cameraCalibration/conf/outputCalib.ini`). The file is replaced atomically after a successful calibration. Copy or rename it to the file used by the robot, for example `icubEyes.ini`, after checking the result.
 
 An example of output calibration file is:
 
 ```xml
 [CAMERA_CALIBRATION_RIGHT]
+projection pinhole
 w 320
 h 240
 fx 215.483
@@ -60,6 +70,7 @@ p1 -0.00180031
 p2 -0.000303536
 
 [CAMERA_CALIBRATION_LEFT]
+projection pinhole
 w 320
 h 240
 fx 215.622
@@ -77,14 +88,42 @@ QL ( 0.000000	 0.000000	 0.000000	-0.020714	-0.001918	 0.000767	-0.000575	-0.000
 QR ( 0.000000	 0.000000	 0.000000	-0.020714	-0.001918	 0.000767	-0.000575	-0.000021)
 ```
 
-The parameters w and h are the image resolution used during the calibration.
+For fisheye calibration, set `cameraModel fisheye`. The two camera groups then contain `projection fisheye` and use `k1`, `k2`, `k3`, and `k4`:
+
+```ini
+[CAMERA_CALIBRATION_LEFT]
+projection fisheye
+w 640
+h 480
+fx ...
+fy ...
+cx ...
+cy ...
+k1 ...
+k2 ...
+k3 ...
+k4 ...
+```
+
+The parameters `w` and `h` are the image resolution used during the calibration.
 
-The parameters fx and fy are the focal lengths (along the x and y axes respectively) expressed in pixel units.
+The parameters `fx` and `fy` are the focal lengths (along the x and y axes respectively) expressed in pixel units.
 
-The point (cx, cy) is the principal points, and usually is the image center.
+The point `(cx, cy)` is the principal points, and usually is the image center.
 
-The values k1, k2, p1, p2 are the distortion coefficients.
+For pinhole cameras, `k1`, `k2`, `p1`, and `p2` are the distortion coefficients. For fisheye cameras, `k1`, `k2`, `k3`, and `k4` are the fisheye distortion coefficients.
+
+In the `[STEREO_DISPARITY]` group the extrinsic parameters are saved. `HN` is the homogeneous transform from the left camera to the right camera. `R` and `T` contain the same rotation and translation separately. Older files may also contain `QL` and `QR`; these are legacy robot-pose values and are not required by the new calibration writer. The fisheye rectifier requires `HN` with a non-zero translation and both camera calibration groups.
+
+To apply the generated calibration, run one `camCalib` instance per camera:
+
+```sh
+camCalib --context cameraCalibration --from icubEyes.ini \
+	--group CAMERA_CALIBRATION_LEFT --name /icub/camcalib/left
+camCalib --context cameraCalibration --from icubEyes.ini \
+	--group CAMERA_CALIBRATION_RIGHT --name /icub/camcalib/right
+```
 
-In the [STEREO_DISPARITY] group the extrinsic parameters are saved. HN is the rototranslation matrix between the left and the right camera, whereas QL and QR are the torso and head angles used during the calibration procedure.
+Connect each raw camera stream to the corresponding `/in` port and use the `/out` port as the corrected and rectified stream. `camCalib` selects the rectifier from the `projection` key.
 
 Additional information regarding the calibration parameters can be found in the [OpenCV Documentation](http://opencv.jp/opencv-2.2_org/cpp/calib3d_camera_calibration_and_3d_reconstruction.html).