docs: fiducial markers guide 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>

MithraGhlm

Upper and Lower limits for Error_correction of STag Detector

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?

MithraGhlm · 2026-05-20T08:14:23Z

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?

I am using Prettier. I also changed the print width to 120. Isn't it working as intended?

domire8 · 2026-05-28T11:40:05Z

I am using Prettier. I also changed the print width to 120. Isn't it working as intended?

Well no, most lines are still way longer than 120 characters

…ration documentation.

domire8

I have a few last nitpicks for the fiducial markers guide.

In order to proceed here, please

revert the changes from the ur-hardware-interface.md file, you can do that in #485
Remove the hand-eye-calibration guide from this PR. We'll make a separate PR for it.
Format the fiducial-markers.md file such that no lines are longer than 120 characters

MithraGhlm · 2026-06-10T11:33:59Z

I am using Prettier. I also changed the print width to 120. Isn't it working as intended?

Well no, most lines are still way longer than 120 characters

I added "prettier.proseWrap": "always",
seems like without this, Prettier often preserves existing line breaks and may ignore printWidth.

MithraGhlm · 2026-06-10T11:49:55Z

In order to proceed here, please

revert the changes from the ur-hardware-interface.md file, you can do that in Docs/style: Reformatting the Docs #485

Why should they be reverted?
The changes are not big, just some tiny modifications, such as Bolding of some words, made to make the formatting look more in sync across different pages. Does it cause any problem?

domire8 · 2026-06-10T12:44:38Z

The changes are not big, just some tiny modifications, such as Bolding of some words, made to make the formatting look more in sync across different pages. Does it cause any problem?

Unless we have actual guidelines how we want to improve style and formatting, there is no need increasing the scope of this PR to files that are unrelated to hand-eye calibration. It's good practice to keep scopes of PRs narrow.

I'm not against the changes alltogether, but this is not the place to do it. A reformatting PR would be more appropriate

MithraGhlm · 2026-06-10T13:57:10Z

In order to proceed here, please

Remove the hand-eye-calibration guide from this PR. We'll make a separate PR for it.

Before I change anything there, do you want the existing review comments be preserved or is it acceptable to move it to a new branch and create a fresh PR?

This is what I want to do: (Since the name of this PR is already HE calibration, I'll move the Fiducial Markers to a new PR)

Make a new branch for Fiducial Markers
Delete the fiducial-markers.md file and all media related to it

So the existing PR would be only for HE calibration.

Then I'll open a new PR for the Fiducial Markers and rebase on main.

Is this workflow accepted?

MithraGhlm · 2026-06-10T14:14:01Z

Unless we have actual guidelines how we want to improve style and formatting, there is no need increasing the scope of this PR to files that are unrelated to hand-eye calibration. It's good practice to keep scopes of PRs narrow.

I'm not against the changes alltogether, but this is not the place to do it. A reformatting PR would be more appropriate

As you correctly commented once on the #485 (This PR contains all commits from #482, could you untangle this?), I untangled #482 from #485.
The initial problem was due to me forgetting to switch to main before making the new branch. But then I rebased it on the main and the problem was resolved. Now #482 and #485 are 2 different PRs.

So I don't understand what you mean by: increasing the scope of this PR to files that are unrelated to hand-eye calibration. It's good practice to keep scopes of PRs narrow.

Since we don't have any specific guidelines yet, how about just merging the small changes and closing #485, instead of reverting it?

domire8 · 2026-06-11T07:26:05Z

All 4 of my previous review comments are still unresolved

domire8

Just two last formatting nitpicks. Otherwise all good!

domire8 · 2026-06-12T11:17:55Z

+- **Is any marker detected**: This predicate will be set to **True** if any marker is detected in the camera frame, even
+  though its name is not indicated in the 'Marker Selection' parameter. As you can see in the screenshot below, the
+  marker name specified in the `Marker selection` parameter is stag_1, but the marker recognized in the camera frame is
+  stag_0, yet `Is any marker detected` predicate is set to **True**.
+
+<div class="text--center">
+  <img src={stagMarkerNumOne} alt="Is any marker detected at all" style={{ borderRadius: "8px" }}/>
+</div>
+
+- **Is any selected marker detected**: If one or more marker names are indicated in the `Marker selection` parameter,
+  and if any of them appears in the camera frame, this predicate with be set to **True**. If the names of none of the
+  markers present in the camera frame is indicated as a parameter, this predicate will remain **False**. In the
+  screenshot below the name of the marker appearing in the camera frame matches the name indicated in the
+  `Marker selection` parameter.
+
+<div class="text--center">
+  <img src={stagMarkerNumZero} alt="Is any of the selected markers detected" style={{ borderRadius: "8px" }}/>
+</div>
+
+- **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**.


Suggested change

- **Is any marker detected**: This predicate will be set to **True** if any marker is detected in the camera frame, even

though its name is not indicated in the 'Marker Selection' parameter. As you can see in the screenshot below, the

marker name specified in the `Marker selection` parameter is stag_1, but the marker recognized in the camera frame is

stag_0, yet `Is any marker detected` predicate is set to **True**.

<div class="text--center">

<img src={stagMarkerNumOne} alt="Is any marker detected at all" style={{ borderRadius: "8px" }}/>

</div>

- **Is any selected marker detected**: If one or more marker names are indicated in the `Marker selection` parameter,

and if any of them appears in the camera frame, this predicate with be set to **True**. If the names of none of the

markers present in the camera frame is indicated as a parameter, this predicate will remain **False**. In the

screenshot below the name of the marker appearing in the camera frame matches the name indicated in the

`Marker selection` parameter.

<div class="text--center">

<img src={stagMarkerNumZero} alt="Is any of the selected markers detected" style={{ borderRadius: "8px" }}/>

</div>

- **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**.

- **Is any marker detected**: This predicate will be set to **True** if any marker is detected in the camera frame, even

though its name is not indicated in the 'Marker Selection' parameter. As you can see in the screenshot below, the

marker name specified in the `Marker selection` parameter is stag_1, but the marker recognized in the camera frame is

stag_0, yet `Is any marker detected` predicate is set to **True**.

<div class="text--center">

<img src={stagMarkerNumOne} alt="Is any marker detected at all" style={{ borderRadius: "8px" }}/>

</div>

- **Is any selected marker detected**: If one or more marker names are indicated in the `Marker selection` parameter,

and if any of them appears in the camera frame, this predicate with be set to **True**. If the names of none of the

markers present in the camera frame is indicated as a parameter, this predicate will remain **False**. In the

screenshot below the name of the marker appearing in the camera frame matches the name indicated in the

`Marker selection` parameter.

<div class="text--center">

<img src={stagMarkerNumZero} alt="Is any of the selected markers detected" style={{ borderRadius: "8px" }}/>

</div>

- **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**.

purely a formatting change here. By adding the indents before the image <div> elements, the images will have the same width as the enumeration.

So the image being aligned with the text is the preferred format over the image being aligned with the bullet points?
Great. Got it :)

Should other images be also shifted a tab to the right, or it only applies to those who are next to the bullet points?

I think the ones in enumerations only is better. The main point is that the images should look like they are part of the enumeration, not that they interrupt the alignment of the enumerations.

domire8

Alright looks good now! Good work with this 👍

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 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

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

added the yaml file for the STag Detector

a9118c4

Explanation for the Frame Broadcaster component added to the HE calib…

50f36a1

…ration documentation.

domire8 reviewed Jun 5, 2026

View reviewed changes

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

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

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

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

Print Width corrected, set to 120

1f0f3d8

MithraGhlm changed the title ~~docs: Hand-Eye calibration guide #479~~ docs: Fiducial Markers #479 Jun 10, 2026

MithraGhlm changed the title ~~docs: Fiducial Markers #479~~ docs: Hand-Eye calibration guide #479 Jun 10, 2026

MithraGhlm added 2 commits June 10, 2026 18:21

Unintended changes to ur-harware-interface.md file reverted.

7cd986b

Removed hand-eye calibration guide to be placed in a separate PR

83d2982

MithraGhlm changed the title ~~docs: Hand-Eye calibration guide #479~~ docs: fiducial markers guide #479 Jun 10, 2026

MithraGhlm changed the title ~~docs: fiducial markers guide #479~~ docs/ fiducial markers guide #479 Jun 10, 2026

reordered imports which were jumbled by the extension

b9375b2

domire8 changed the title ~~docs/ fiducial markers guide #479~~ docs: fiducial markers guide Jun 11, 2026

MithraGhlm added 2 commits June 12, 2026 10:52

stag detector parameters definition correction

f906b18

formatted again just to be sure

62b6ae3

domire8 reviewed Jun 12, 2026

View reviewed changes

some formatting nitpicks

b5f63c3

domire8 approved these changes Jun 15, 2026

View reviewed changes

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!

MithraGhlm 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!

domire8 May 18, 2026

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 commented May 20, 2026

Uh oh!

domire8 commented May 28, 2026

Uh oh!

domire8 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

MithraGhlm commented Jun 10, 2026

Uh oh!

domire8 commented Jun 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

MithraGhlm commented Jun 10, 2026

MithraGhlm commented Apr 28, 2026 •

edited

Loading

MithraGhlm commented Jun 10, 2026 •

edited

Loading

domire8 commented Jun 10, 2026 •

edited

Loading

domire8 commented Jun 11, 2026 •

edited

Loading

domire8 Jun 12, 2026 •

edited

Loading

MithraGhlm Jun 12, 2026 •

edited

Loading

domire8 Jun 15, 2026 •

edited

Loading