docs: Hand-Eye calibration guide #479 by MithraGhlm · Pull Request #482 · aica-technology/api

MithraGhlm · 2026-04-21T11:26:12Z

Description

Initial draft of documentation for camera frame calibration guide.
This PR closes the camera frame calibration guide #479

This PR solves the issue by adding two stand-alone guides to the documentation.
The guide for intrinsic camera calibration already exists.
One guide is about the configuration and the process of recognizing STag marker (WIP) and a second one would be dedicated to calibrating the robot.

Review guidelines

Estimated Time of Review: 10 minutes

Feedback Needed

Structure okay?
Level of detail appropriate?

…ocs.

…iny correction to Camera Streamer.

SprGrf

Thanks! First quick review:

MithraGhlm · 2026-04-27T15:08:18Z

@SprGrf Thanks

…bration

MithraGhlm · 2026-04-28T16:31:44Z

Should there be a stand alone guide to introduce the Robot Camera Calibration component?
Or is it better to have it in the same docs page?

SprGrf

Nice! The backbone is here, some first comments I had while reading:

Co-authored-by: Spyros Garyfallidis <spyros@aica.tech>

Co-authored-by: Dominic Reber <71256590+domire8@users.noreply.github.com>

…component

…nent Co-authored-by: Dominic Reber <71256590+domire8@users.noreply.github.com>

…r file

domire8 · 2026-05-06T09:35:37Z

+
+- **ArUco marker:** ArUco markers can be generate online (e.g., from [here](https://calib.io/pages/camera-calibration-pattern-generator)), which permits choosing the dictionary, marker ID, and marker size. It can be then exported as PDF or SVG for printing.
+
+- **STag marker:** STag marker set should be obtained from the [STag project repository](https://github.com/usrl-uofsc/stag_ros) or the generator/reference files linked by the project. The [STag project repository for ROS](https://github.com/usrl-uofsc/stag_ros) is the other place to look for marker-generation assets. In practice, you’ll want to obtain the marker PDF/SVG or generate the markers from the project’s reference generator, then print them at true size.


https://drive.google.com/drive/folders/0ByNTNYCAhWbIV1RqdU9vRnd2Vnc?resourcekey=0-9ipvecbezW8EWUva5GBQTQ

Public google drive where the markers can be downloaded

Since this link was already in the page I mentioned in the guide, I didn't provide it exclusively. But sure, it's better this way.

Follow-up question: is it better to delete the links for the STag project repository and the STag project repository for ROS ? Or keep them and only add the google drive link?

Ah I didn't see that the repo links the drive as well. I think the repo can still be linked, but also see my comment below because the two links go to the same repository. So essentially we probably end up with two links, the drive and the repo

domire8 · 2026-05-06T09:40:08Z

+- **Marker selection**: The name(s) of the marker(s) that we intend to be recognized. If any of these markers enters the camera frame, the `is_any_selected_marker_detected` predicate is set to **True**. This name should always be prepended with the value of `Prefix`.
+- **Marker size**: Determins the side length of a square that specifies the marker in meters.
+- **Library**: This is the ID number of the HD library utilized by STag markers. The allowed numbers are `[11, 13, 15, 17, 19, 21, 23]`.
+- **Error correction**:


This is still missing?

The problem is that there are no upper and lower limits defined for it. If the number is out of an (unspecified) range, the component doesn't work.
I left it out on purpose to get to this issue. (But forgot to put a comment for it. Sorry)

It would be good to figure out what the limits are then. Like that we can also provide more insight what that parameter actually does.

The lower limit in the code is 0, and the upper bound comes from the upstream STag library, in which the rule is:
0 ≤ errorCorrection ≤ (libraryHD - 1) / 2

With the default library value of 15, the maximum valid error correction is 7.

There’s one mismatch though. In the file
aica-technology/dynamic components/source/core_vision_components/extension_descriptions/core_vision_components_pose_detection_stag_bundle_registration.yaml

and the file:

aica-technology/dynamic-components/source/core_vision_components/extension_descriptions/core_vision_components_pose_detection_stag_detector.yaml

a minimum of 1 is indicated, while the code accepts 0.

- display_name: Error correction parameter_name: error_correction description: The error correction tolerance. Lower values are strict, higher values are more permissive default_value: 7 parameter_type: int validation: range: minimum: 1

0 ≤ errorCorrection ≤ (libraryHD - 1) / 2 ah that is a shame that the error bounds depend on the library selection.. This is something we can't validate easily in Studio directly.

You could then open a PR on the relevant description files to set the minimum to 0 and also to set the maximum to (23 - 1) / 2 = 11. You could even improve the component implementation such that a detail ROS log is spit out when the error correction is too high for the given library.

SprGrf · 2026-05-07T13:50:26Z

+2. Publish the transformation with a FrameBroadcaster manually.
+3. Using the calibration file path directly as a `Frame Broadcaster` component parameter to publish the transformations.


I think we could show how to do that here, I am not sure it's described elsewhere.

Co-authored-by: Spyros Garyfallidis <spyros@aica.tech>

…ures added.

…xample

domire8

Could you also apply the formatting by the "prettier" extension? It's possible that you also have to adjust the print width setting for the extension to be 120

MithraGhlm

Upper and Lower limits for Error_correction of STag Detector

domire8 · 2026-05-18T07:41:37Z

+
+If possible, print on a rigid and flat sheet of paper to reduce warping, since fiducial detection is sensitive to distortion. As another solution, you can fix the printed marker on a rigid surface, such as a piece of wood or cardboard.
+
+After printing, measure the marker’s outer dimensions and compare them with the intended size from the generator. This matters because calibration will be wrong if the marker size in the software does not match the physical print.


The second phrase sounds a bit like the print absolutely has to be perfect in order for the rest to work. It's subtle but maybe I would go for something like this:

After printing, measure the marker's outer dimensions since those might still be different from the desired ones. The true physical size will be required below to ensure that the calibration is precise.

domire8 · 2026-05-18T07:48:14Z

+- **Marker selection**: The name(s) of the marker(s) that we intend to be recognized. If any of these markers enters the camera frame, the `is_any_selected_marker_detected` predicate is set to **True**. This name should always be prepended with the value of `Prefix`.
+- **Marker size**: Determins the side length of a square that specifies the marker in meters.
+- **Library**: This is the ID number of the HD library utilized by STag markers. The allowed numbers are `[11, 13, 15, 17, 19, 21, 23]`.
+- **Error correction**:


0 ≤ errorCorrection ≤ (libraryHD - 1) / 2 ah that is a shame that the error bounds depend on the library selection.. This is something we can't validate easily in Studio directly.

You could then open a PR on the relevant description files to set the minimum to 0 and also to set the maximum to (23 - 1) / 2 = 11. You could even improve the component implementation such that a detail ROS log is spit out when the error correction is too high for the given library.

Co-authored-by: Dominic Reber <71256590+domire8@users.noreply.github.com>

…finition enhancements.

domire8

Nice, this is really coming together nicely. As we enter the final stages, could you now please try to format the file fiducial-markers.md?

domire8 · 2026-05-18T10:56:59Z

+
+- **Is a marker bundle detected**: If a registered group of markers is detected by the camera, this parameter will be set to **True**. Otherwise it will remain **False**.
+
+After setting up the proper parameters for Camera Streamer and STag Detector:


I think this could be in it's own section "Running the application" or something like that and we should attach the YAML content too

MithraGhlm added 5 commits April 9, 2026 18:42

hand-eye calibration branch created on relevant order between other d…

4dd39c8

…ocs.

Added the STag detector doc and rearranged the numbers

c23f24a

some text written for the STag marker detector.Related image added. T…

8790c37

…iny correction to Camera Streamer.

The STag detection video added.

a459c04

WIP: initial documentation draft

bd5c193

MithraGhlm requested review from SprGrf and yrh012 as code owners April 21, 2026 11:26

MithraGhlm requested a review from domire8 April 21, 2026 11:26

SprGrf reviewed Apr 21, 2026

View reviewed changes

info for Aruco marker added.

0613b51

MithraGhlm force-pushed the docs/hand-eye-calibration branch from bec2ef4 to 0613b51 Compare April 27, 2026 11:11

MithraGhlm added 3 commits April 27, 2026 15:52

Decoupled the explanation of Marker detection from Hand-Eye calibration

81dbf13

Applied some grammatical, structural, and definitional improvements.

b5952af

canceled the small change made to the text.

413e081

MithraGhlm changed the title ~~docs: Hand-Eye calibration guide #479~~ docs: Marker detection guide #479 Apr 27, 2026

MithraGhlm changed the title ~~docs: Marker detection guide #479~~ docs: Hand-Eye calibration guide #479 Apr 27, 2026

MithraGhlm added 4 commits April 27, 2026 17:23

Renamed the file to show the marker detection process is generic

743eede

The first version of introduction for the robot calibration guide.

a9a0028

added the screenshot of component configuration for the Hand-Eye cali…

c0b4a83

…bration

added calibration workflow.

d904aeb

MithraGhlm added 2 commits April 28, 2026 19:07

one word replaced by a better one.

426fef6

added things that can be done with the acquired calibration info

c4da9af

SprGrf reviewed Apr 29, 2026

View reviewed changes

MithraGhlm and others added 3 commits April 29, 2026 11:49

corrected capital letter which was in the middle of the sentence.

9ce7fec

Co-authored-by: Spyros Garyfallidis <spyros@aica.tech>

adding a small frame to the image

f2e20b7

Co-authored-by: Spyros Garyfallidis <spyros@aica.tech>

Added the missing word, Launcher.

b12fd16

Co-authored-by: Spyros Garyfallidis <spyros@aica.tech>

domire8 reviewed Apr 30, 2026

View reviewed changes

sidebar position modified

4f58281

Co-authored-by: Dominic Reber <71256590+domire8@users.noreply.github.com>

MithraGhlm and others added 6 commits April 30, 2026 14:29

Misspelling corrected

b1d7970

Co-authored-by: Dominic Reber <71256590+domire8@users.noreply.github.com>

reminder to add the camera configuration file to the Camera Streamer …

07e4020

…component

corrected the definition of Rate parameter of the STag Detector compo…

a4fa172

…nent Co-authored-by: Dominic Reber <71256590+domire8@users.noreply.github.com>

the word stag_ replaced by the word Prefix

d529009

small typo corrected

43c9874

adding the explanation of the Marker Size parameter

c59aa4a

domire8 reviewed May 1, 2026

View reviewed changes

Comment thread docs/core/examples/guides/hand-eye-calibration.md

Comment thread docs/core/examples/guides/hand-eye-calibration.md

MithraGhlm added 9 commits May 1, 2026 15:10

moved the robot camera calibration component explanation to the prope…

e22827b

…r file

screenshot of Robot Camera Calibration parameters added

a3bd7fc

app added for the HE calibration

9d55015

the structure of some sentences enhanced

addc15b

added the reminder to turn on the camera attached check

6fea105

added the definition of Bundle file

c07b8c2

added the explanation for obtaining, downloading, and printing markers

a747428

rectified the file that Bundle File was explained in

941b84b

The wrong image removed

5417117

domire8 reviewed May 6, 2026

View reviewed changes

SprGrf reviewed May 7, 2026

View reviewed changes

MithraGhlm and others added 3 commits May 8, 2026 08:41

typo correction

b7b0bfc

Co-authored-by: Spyros Garyfallidis <spyros@aica.tech>

Some typo and font inconsistency corrected. Some definitions and pict…

346be2b

…ures added.

text added to explain the screenshot, HE caliberation configuration e…

9c2edee

…xample

domire8 reviewed May 11, 2026

View reviewed changes

Comment thread docs/core/examples/guides/fiducial-markers.md Outdated

domire8 mentioned this pull request May 11, 2026

Docs/style: Reformatting the Docs #485

Open

1 task

MithraGhlm added 2 commits May 13, 2026 09:17

Links for obtaining fiducial markers corrected

27e362f

screenshots for STag detector predicates added.

f884fe8

MithraGhlm commented May 13, 2026

View reviewed changes

domire8 reviewed May 18, 2026

View reviewed changes

MithraGhlm and others added 2 commits May 18, 2026 10:44

typo correction

f62b7e6

Co-authored-by: Dominic Reber <71256590+domire8@users.noreply.github.com>

some order and structur changes in the body of documentation. Some de…

4ece868

…finition enhancements.

domire8 reviewed May 18, 2026

View reviewed changes


		- ArUco marker: ArUco markers can be generate online (e.g., from [here](https://calib.io/pages/camera-calibration-pattern-generator)), which permits choosing the dictionary, marker ID, and marker size. It can be then exported as PDF or SVG for printing.

		- STag marker: STag marker set should be obtained from the [STag project repository](https://github.com/usrl-uofsc/stag_ros) or the generator/reference files linked by the project. The [STag project repository for ROS](https://github.com/usrl-uofsc/stag_ros) is the other place to look for marker-generation assets. In practice, you’ll want to obtain the marker PDF/SVG or generate the markers from the project’s reference generator, then print them at true size.

		2. Publish the transformation with a FrameBroadcaster manually.
		3. Using the calibration file path directly as a `Frame Broadcaster` component parameter to publish the transformations.


		If possible, print on a rigid and flat sheet of paper to reduce warping, since fiducial detection is sensitive to distortion. As another solution, you can fix the printed marker on a rigid surface, such as a piece of wood or cardboard.

		After printing, measure the marker’s outer dimensions and compare them with the intended size from the generator. This matters because calibration will be wrong if the marker size in the software does not match the physical print.


		- Is a marker bundle detected: If a registered group of markers is detected by the camera, this parameter will be set to True. Otherwise it will remain False.

		After setting up the proper parameters for Camera Streamer and STag Detector:

Conversation

MithraGhlm commented Apr 21, 2026

Description

Review guidelines

Feedback Needed

Uh oh!

SprGrf left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

MithraGhlm commented Apr 27, 2026

Uh oh!

MithraGhlm commented Apr 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

SprGrf left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

domire8 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

MithraGhlm left a comment

MithraGhlm commented Apr 28, 2026 •

edited

Loading