From c29b9d3ac6f7138c4335d4684642ac9f77cd64a3 Mon Sep 17 00:00:00 2001 From: Michael Ferguson Date: Sat, 2 Nov 2024 12:19:09 -0400 Subject: [PATCH] document things --- README.md | 84 ++++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 65 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 370ec67d..731184a9 100644 --- a/README.md +++ b/README.md @@ -207,10 +207,13 @@ robot_calibration: For each calibration step, there are several parameters: - * ``models`` - Models define how to reproject points. The basic model is a + * ``models`` - List of model names. Each model will then be defined in a + parameter block defined by the name. Models define how to reproject + observation points into the fixed frame. The basic model is a kinematic chain. Additional models can reproject through a kinematic - chain and then a sensor, such as a 3d camera. For IK chains, ``frame`` parameter - is the tip of the IK chain. The "models" parameter is a list of model names. + chain and then a sensor, such as a 3d camera. Once loaded, models + will be used by the error blocks to compute the reprojection errors + between different sensor observations. * ``free_params`` - Defines the names of single-value free parameters. These can be the names of a joint for which the joint offset should be calculated, camera parameters such as focal lengths or the driver offsets for @@ -227,10 +230,10 @@ For each calibration step, there are several parameters: ``free_frames``. X, Y, Z offsets are in meters. ROLL, PITCH, YAW are in radians. This is most frequently used for setting the initial estimate of the checkerboard position, see details below. - * ``error_blocks`` - List of error block names, which are then defined under their - own namespaces. + * ``error_blocks`` - List of error block names, which are then defined + under their own namespaces. -For each model, the type must be specified. The type should be one of: +For each model, the `type` must be specified. The type should be one of: * ``chain3d`` - Represents a kinematic chain from the `base_link` to the `frame` parameter (which in MoveIt/KDL terms is usually referred to as the `tip`). @@ -241,27 +244,70 @@ For each model, the type must be specified. The type should be one of: used and any of the pinhole parameters are free parameters is only valid if the physical sensor actually uses the CameraInfo for 3d projection (this is generally true for the Primesense/Astra sensors). + * ``camera2d`` - Similar to `camera3d`, but for a 2d finder. Currently only + works with the output of the ``CheckerboardFinder2d``. -For each error block, the type must be specified. The type should be one of: +For each error block, the ``type`` must be specified. In addition to the +``type`` parameter, each block will have additional parameters: - * chain3d_to_chain3d - This error block can compute the difference in - reprojection between two 3D "sensors" which tell us the position of + * ``chain3d_to_chain3d`` - The most commonly used error block type. + This error block can compute the difference in reprojection + between two 3D "sensors" which tell us the position of certain features of interest. Sensors might be a 3D camera or an arm - which is holding a checkerboard. Was previously called "camera3d_to_arm". - * chain3d_to_mesh - This error block can compute the closeness between + which is holding a checkerboard. Was previously called "camera3d_to_arm": + * `model_a` - First `chain3d` or `camera3d` model to use in computing + reprojection error. + * `model_b` - Second `chain3d` or `camera3d` model to use in computing + reprojection error. + * ``chain3d_to_camera2d``- Currently only used for the `CheckerboardFinder2d`: + * `model_2d` - `camera2d` model to use in computing reprojection error. + * `model_3d` - `chain3d` or `camera3d` model to use in computing + reprojection error. + * `scale` - Scalar to multiply summed error by - note that error computed + in this block is in *pixel* space, rather than *metric* space like most + other error blocks. + * ``chain3d_to_mesh`` - This error block type can compute the closeness between projected 3d points and a mesh. The mesh must be part of the robot body. - This is commonly used to align the robot sensor with the base of the robot. - * chain3d_to_plane - This error block can compute the difference between - projected 3d points and a desired plane. The most common use case is making - sure that the ground plane a robot sees is really on the ground. - * plane_to_plane - This error block is able to compute the difference + This is commonly used to align the robot sensor with the base of the robot, + using points that were found by the `RobotFinder` plugin: + * `model` - `chain3d` or `camera3d` model to use in computing reprojection + error. + * `link_name` -Name of the link in the URDF for which mesh to use. + * ``chain3d_to_plane`` - This error block can be used to compare projected + points to a plane. Each observation point is reprojected, then the sum + of distance to plane for each point is computed. The most common use case + is making sure that the ground plane a robot sees is really on the ground: + * `model` - The `camera3d` model for reprojection. + * `a`, `b`, `c`, `d` - Parameters for the desired plane equation, in the + form `ax + by + cz + d = 0`. + * `scale` - Since the error computed is a distance from the plane over + many points, scaling the error relative to other error blocks is often + required. + * ``plane_to_plane`` - This error block is able to compute the difference between two planes. For instance, 3d cameras may not have the resolution to actually see a checkerboard, but we can align important axis by - making sure that a wall seen by both cameras is aligned. - * outrageous - Sometimes, the calibration is ill-defined in certain dimensions, + making sure that a wall seen by both cameras is aligned. For each observation, + the points are assumed to form a plane: + * `model_a` - First `chain3d` or `camera3d` model to use in computing + reprojection error. + * `model_b` - Second `chain3d` or `camera3d` model to use in computing + reprojection error. + * `normal_scale` - The normal error is computed as the difference between + the two plane normals and then multiplied by this scalar. + * `offset_scale` - The offset error is computed as the distance from + the centroid of the first plane to the second plane and then + multiplied by this scalar. + * ``outrageous`` - Sometimes, the calibration is ill-defined in certain dimensions, and we would like to avoid one of the free parameters from becoming absurd. An outrageous error block can be used to limit a particular - parameter. + parameter: + * `param` - Free parameter to monitor. + * `joint_scale` - If `param` is a joint name, multiply the free param value + by this scalar. + * `position_scale` - If `param` is a free frame, multiply the metric distance + in X, Y, Z by this scalar. + * `rotation_scale` - If `param` is a free frame, multiply the angular distance + of the free parameter value by this scalar. #### Checkerboard Configuration