update documents

README.md

@@ -1,17 +1,23 @@
 # sensor_calibration
 
+[![Build and Test](https://github.com/gezp/sensor_calibration/actions/workflows/ci.yml/badge.svg?branch=humble)](https://github.com/gezp/sensor_calibration/actions/workflows/ci.yml)
+
 该项目基于ROS2平台实现了部分传感器标定功能，主要以学习为目的，面向初学者学习入门，因此代码侧重于可读性，及扩展性，尽可能将代码进行解耦，并遵循ROS2的项目规范，以及代码风格。
 
 本项目主要面向以下场景的传感器标定：
 
 * 传感器内参标定（sensor_intrinsics）
 * 传感器到传感器之间的外参标定（sensor2sensor）
 
+标定文件的存储形式：
+
+* 采用YAML文件，数据格式详见[Calibration File Format](doc/calibration_file_format.md)文档
+
 ## Quick start
 
 环境要求
 
-- ROS版本: `Humble`
+* ROS版本: `Humble`
 
 下载源码及安装依赖
 
@@ -49,5 +55,6 @@ sensor2sensor外参标定
 
 本项目参考了许多其它类似项目，并参考并引用了部分代码，这里向以下项目的作者表示感谢！
 
-- https://github.com/PJLab-ADG/SensorsCalibration
-- https://github.com/tier4/CalibrationTools
+* https://github.com/PJLab-ADG/SensorsCalibration
+* https://github.com/tier4/CalibrationTools
+* https://github.com/ethz-asl/kalibr

camera_intrinsic_calibration/README.md

@@ -0,0 +1,41 @@
+# camera_intrinsic_calibration
+
+这个包提供了相机内参标定的工具，目前已经实现的`calibrator`有：
+
+* `pinhole_calibrator` ：标定`pinhole_radtan`相机模型，适用于镜头畸变较小的相机。
+  * 目前仅支持棋盘格标定板。
+* `fisheye_calibrator` (TODO)
+
+## Quick Start
+
+创建数据存放文件夹
+
+```bash
+mkdir ~/calibration_data
+```
+
+准备demo数据
+
+* 使用[SensorsCalibratio](https://github.com/PJLab-ADG/SensorsCalibration)的数据，从Github上下载仓库，复制其中的`camera_intrinsic/intrinsic_calib/data`目录到本地的`~/calibration_data/SensorsCalibration/camera_intrinsic`中即可。
+
+运行标定demo程序
+
+```bash
+ros2 launch camera_intrinsic_calibration demo.launch.py 
+```
+
+* 默认情况下需要使用GUI客户端启动标定流程，如果想要标定程序自动开启标定流程并保存结果，并不使用GUI，可设置`calibration_node`的参数`autostart`为`True`。
+* 标定的配置文件为`config/calibrator.yaml`，可以修改标定板的配置，相机的图像尺寸，误差阈值等参数。
+* 标定结果保存在`~/calibration_data/esult.yaml`中。
+
+运行标定GUI客户端
+
+```bash
+ros2 run camera_intrinsic_calibration calibration_client.py
+```
+
+* 基于Qt的图形化界面，可以查看标定过程的标定信息，以及控制标定程序的流程。
+
+## Reference
+
+* https://github.com/PJLab-ADG/SensorsCalibration/tree/master/camera_intrinsic/intrinsic_calib

doc/calibration_file_format.md

@@ -0,0 +1,73 @@
+# Calibration File Format
+
+该项目的标定结果采用yaml文件形式进行存储，目前支持的标定结果类型有：
+
+* 相机内参
+* 传感器与传感器之间的外参
+
+其中内参以传感器的`frame_id`作为命名空间，传感器外参保存在`sensor_pair_transoforms`列表中，`sensor_pair_transoforms`中的元素为一对传感器的外参。样例如下：
+
+```yaml
+camera1:
+    camera_model: pinhole_radtan
+    intrinsics: [461.629, 460.152, 362.680, 246.049]
+    distortion_coeffs: [-0.27695497, 0.06712482, 0.00087538, 0.00011556, 0.0]
+sensor_pair_transforms:
+    transform1:
+        frame_id: camera1
+        child_frame_id: lidar1
+        translation: [0.07008565, -0.01771023, 0.00399246]
+        rotation: [0.0 ,0.0 ,0.0 ,1.0] # x,y,z,w
+    transform2:
+        frame_id: lidar1
+        child_frame_id: lidar2
+        translation: [0.07008565, -0.01771023, 0.00399246]
+        rotation: [0.0 ,0.0 ,0.0 ,1.0] # x,y,z,w
+```
+
+## 传感器外参说明
+
+传感器的外参包括以下四个量
+
+* frame_id：传感器的frame id
+* child_frame_id：另一个传感器的frame id
+* translation：外参坐标变换中的平移部分
+* rotation：外参坐标变换中的旋转部分，采用四元数表示，顺序为`[x,y,z,w]`
+
+这里标定出的坐标变换表示为 $T_\text{frame id - child frame id}$，等价以下两种说法：
+
+* 在`frame_id`传感器坐标系下，`child_frame_id`的位姿。
+* `child_frame_id`坐标系到`frame_id`坐标系下的位姿变换。
+
+## 相机内参说明
+
+相机内参包括以下三个量
+
+* camera_model：采用的相机模型，为一个字符串
+* intrinsics：相机内参系数，为一个float数组
+* distortion_coeffs：畸变参数系数，为一个float数组
+
+由于不同的相机模型，其内参系数和畸变参数的组成及含义也不同，目前仅支持以下几种相机模型:
+
+* `pinhole_radtan `，`pinhole_equidistant `，`omni_radtan`
+
+> 这里的相机模型可能与其它资料的定义不同，这里等价于某些资料中的相机模型+畸变模型。
+
+`pinhole_radtan` (简写为`pinhole`)相机模型参数说明：
+
+* intrinsics: $[f_x, f_y, c_x, c_y]$
+* distortion_coeffs: $[k_1, k_2, p_1, p_2, k_3]$ ，其中k为径向畸变参数，p为切向畸变参数。
+* 参考：https://docs.opencv.org/4.x/d9/d0c/group__calib3d.html
+
+`pinhole_equidistant` (简写为`fisheye`)相机模型参数说明：
+
+* intrinsics: $[f_x, f_y, c_x, c_y]$
+* distortion_coeffs: $[\theta_1, \theta_2, \theta_3, \theta_4]$ 
+* 参考：https://docs.opencv.org/4.x/db/d58/group__calib3d__fisheye.html
+
+`omni_radtan` (简写为`omni`或`omnidir`)相机模型参数说明：
+
+* intrinsics: $[\xi, f_x, f_y, c_x, c_y]$
+* distortion_coeffs: $[k_1, k_2, p_1, p_2, k_3]$ ，其中k为径向畸变参数，p为切向畸变参数。
+* 参考：https://docs.opencv.org/4.x/dd/d12/tutorial_omnidir_calib_main.html
+