Improve documentation concerning estimated pose

[Lecrapouille]

This is not an issue but a hybrid pull request. I cannot make a pull request because this both impact comments in the code and changes inside the wiki.

Update a comment in the code

This structure has no comments.

https://github.com/AprilRobotics/apriltag/blob/df4aee5b511d2176e82bf9585469c5543e741486/apriltag_pose.h#L23

Here what I suggest adding:

/**
 * This struct holds the transformation from the camera optical frame to
 * the April tag frame. The pose refers to the position of the tag within
 * the camera frame.
 *
 * If you want to get the camera pose with respect to the April tag frame
 * you have to apply the inverse of this transformation.
 */
typedef struct {
    matd_t* R; // Rotation matrix 3x3 of doubles.
    matd_t* t; // Translation matrix 3x1 of doubles.
} apriltag_pose_t;

Update the wiki

I give the md file that includes 2 figures of coordinates

AprilTag-User-Guide.md

Figures are PNG but made with Draw.io so the "drawio code" is embedded in the PNG so you can open it with drawio to edit it. The markdown file:

• I linked an issue for giving an example of OpenCv's Pnp solver
• I added a section concerning apriltag_pose_t and camera pose. @christian-rauch @mkrogius please review it since I'm little rusty with transfer matrices.

[christian-rauch]

You can send a PR which adds the comments to the apriltag_pose_t struct anyway. Not sure about the wiki. Someone else has to add those changes as you cannot send a PR to the wiki git (https://github.com/AprilRobotics/apriltag.wiki.git).

Apart from this, I find the two figures confusing. First of all, the coordinate axis colours do not match. The X, Y, Z axes should correspond to the colours red, green, blue. We are also using the OpenCV convention with Z pointing forwards and X and Y like in the image frame. Then, showing a figure with multiple tags on a cube with a single coordinate frame is confusing. I would propose showing a single tag with the same orientation as in the example tags in the apriltag-imgs repo with only a single coordinate frame.

[Lecrapouille]

@christian-rauch

• yes I can create a PR for the comment.
• The X, Y, Z axes should correspond to the colors red, green, blue. lol my bad this is what I wanted to respect (XYZ => RGB) but I totally failed for the camera, good catch :)
• multiple tags on a cube yes I did not found a flat and rotated April. I'll redo

[Lecrapouille]

Here second attempt with pull request.

If the wiki is too problematic, what about creating a pull request to add markdown files back to the doc folder ?

AprilTag-User-Guide(1).md coord.drawio.txt

[christian-rauch]

Are you sure this is the correct camera coordinate system? This looks like the OpenGL camera (projection) coordinate system. Shouldn't Z point forward and Y down?

The rest is just nitpicking: The tag looks like you just cropped it out of the box from the image above. This is clearly visible :-) and does not look nice. Also, the coordinate axes' colours are desaturated and do not have a nice contrast against the tag image. E.g. the green and blue look similar against the tag background.

In any case, you will need @mkrogius to update the wiki as, AFAIK, you cannot open a PR for the wiki. Alternatively, we could move the documentation directly to the repo, e.g. inside a doc folder, and link it from the main README.md on the repo start page. This will also make it easier discoverable.

[Lecrapouille]

Arf, yes I c... again the axis. I definitely do not know to draw :( The coordinate system has the origin at the camera center. The z-axis points from the camera center out the camera lens. Ok so tag and camera have the same coordinate? Thanks for your patience. I fix my previous comment and close this ticket to let a better drawer make a better figure.