WhyCon

A precise, efficient and low-cost localization system

WhyCon is a version of a vision-based localization system that can be used with low-cost web cameras, and achieves millimiter precision with very high performance. The system is capable of efficient real-time detection and precise position estimation of several circular markers in a video stream. It can be used both off-line, as a source of ground-truth for robotics experiments, or on-line as a component of robotic systems that require real-time, precise position estimation. WhyCon is meant as an alternative to widely used and expensive localization systems. It is fully open-source. WhyCon-orig is WhyCon's original, minimalistic version that was supposed to be ROS and openCV independent.

WhyCon example application (video)	Scenario description
	-precise docking to a charging station (EU project STRANDS), -fitness evaluation for self-evolving robots (EU proj. SYMBRION), -relative localization of UAV-UGV formations (CZ-USA project COLOS), -energy source localization in (EU proj REPLICATOR), -robotic swarm localization (EU proj HAZCEPT).

The WhyCon system was developed as a joint project between the University of Buenos Aires, Czech Technical University and University of Lincoln, UK. The main contributors were Matias Nitsche, Tom Krajnik and Jan Faigl. Further contributors are Peter Lightbody and Jiří Ulrich. Each of these contributors maintains a slightly different version of WhyCon.

WhyCon version	Application	Main features	Maintainer
WhyCon/WhyCode	general	actively maintained, ROS	Jiri Ulrich
WhyCon-orig	general	2D, 3D, ROS, lightweight, autocalibration	Tom Krajnik
WhyCon-ROS	general	2D, ROS	Matias Nitsche
SwarmCon	μ-swarms	2D, individual IDs, autocalibration	Tom Krajnik
Caspa-WhyCon	UAVs	embedded, open HW-SW solution	Jan Faigl
Social-card	HRI	ROS, allows to command a robot	Tom Krajnik

Where is it described ?

WhyCon was first presented on International Conference on Advanced Robotics 2013 [2], later in the Journal of Intelligent and Robotics Systems [1] and finally at the Workshop on Open Source Aerial Robotics during the International Conference on Intelligent Robotic Systems, 2015 [3]. Its early version was also presented at the International Conference of Robotics and Automation, 2013 [4]. An extension of the system, which used a necklace code to add ID's to the tags, achieved a best paper award at the SAC 2017 conference [5]. If you decide to use this software for your research, please cite WhyCon using the one of the references provided below.

---

Setting up WhyCon in ROS

Quick setup for initial testing

0. Have ROS Noetic and appropriate camera driver installed. Also have a calibrated camera with distortion model "plumb bob".
1. Make sure your camera is running, e.g., run roslaunch usb_cam_test.launch of the usb_cam package:

roslaunch usb_cam usb_cam-test.launch

0. Check the required libraries
1. Download the code from GitHub into a catkin workspace.
2. Compile the code - just type catkin_make in workspace directory.
3. Source setup script in package directory into shell enviroment e.g. source devel/setup.bash
4. Download, resize and print one circular pattern - you have the pattern also in the id/test.pdf file.
5. Run code by roslaunch and remap subsribed camera topics either on start up through arguments, e.g.,

roslaunch whycon whycon-test.launch cam_info:=/usb_cam/camera_info cam_raw:=/usb_cam/image_raw

or rewrite file whycon.launch so default values of tags arg called cam_info and cam_raw will match topics camera_info and image_raw. Then it's just

roslaunch whycon whycon-test.launch

0. If using patterns with encoded ID keep the option identify turned on in rqt_reconfigure and if without ID, then turn it off!!!
1. You can dynamically change the parameters in rqt_reconfigure.

Generating tags with ID

1. see whycode-gen
2. Run ./whycon-id-gen followed by a number of bits and it will create tags in the working directory.
3. Other program parameters are specified in help ./whycon-id-gen -h
4. Number of ID bits has to be then passed to whycon on start up. The default value can be set in the launch file.

roslaunch whycon whycon.launch [...] id_bits:=...

5. Other ID parameters are treated the same way. ID samples as id_samples:=... and Hamming distance as hamming_dist:=...

Setting up the coordinate system

1. If you have resized the markers (their default size is 122mm), then adjust their diameter in the rqt_reconfigure.
2. Print additional four circular markers and place to the corners of your (reclangular) operational space.
3. Position and fixate your camera so that it has all four circles in it's field of view.
4. Run whycon and modify the dimensions of the operation space in the rqt_reconfigure - the system will now assume that the four markers are at positions [0,0],[fieldLength,0], [0,fieldWidth],[fieldLength,fieldWidth].
5. Start autocalibration or manual calibration through GUI or through rosservice tool.

GUI key binding

• see rqt-whycon-ros

Topics

Published

1. /whycon_ros/markers - you can find its header files in msg folder
   • Header header
   • whycon_ros/Marker[] markers
     • float32 u # camera coordinate
     • float32 v # camera coordinate
     • int32 size # size of the segment in pixels
     • int8 id # ID of pattern
     • geometry_msgs/Pose position # position with quaternion as orientation
     • geometry_msgs/Vector3 rotation # vector of Euler angles - pitch, roll, yaw

Subscribed

1. /<camera>/camera_info - camera matrix and distortion coeffs
2. /<camera>/image_raw - raw image data without correction

Some additional remarks

1. At this point, you can start experimenting with the syste by adding whatever features you might think useful.
2. We have tried to comment the code so an experienced programmer should be able to alter the system accordingly. However, if you have any questions regarding the code, feel free to contact Tom Krajnik or Jiří Ulrich
3. If you use this localization system for your research, please don't forget to cite at least one relevant paper below.

License

The code is avaiable only for academic, educational, research, and non-profit useage. In any other case or when You are not sure, please, contact us!

Dependencies

• OpenCV
• ROS basic packages (see package.xml)

References

1. J. Ulrich, A. Alsayed et al.: Towards fast fiducial marker with full 6 DOF pose estimation. Symposium on Applied Computing, 2022. [bibtex].
2. J. Ulrich: Fiducial marker-based multiple camera localisation system. Master's thesis. Czech Technical University in Prague, 2022. [bibtex].
3. K. Zampachu: Visual analysis of beehive queen behaviour. Bachelor's thesis. Czech Technical University in Prague, 2022. [bibtex].
4. J. Ulrich: Fiducial Marker Detection for Vision-Based Mobile Robot Localisation. Bachelor's thesis. Czech Technical University in Prague, 2020. [bibtex].
5. T. Krajník, M. Nitsche et al.: A Practical Multirobot Localization System. Journal of Intelligent and Robotic Systems (JINT), 2014.
6. P. Lightbody, T. Krajník et al.: An Efficient Visual Fiducial Localisation System. Applied Computing Review, 2017.
7. T. Krajník, M. Nitsche et al.: External localization system for mobile robotics. International Conference on Advanced Robotics (ICAR), 2013.
8. J. Faigl, T. Krajník et al.: Low-cost embedded system for relative localization in robotic swarms. International Conference on Robotics and Automation (ICRA), 2013.
9. M. Nitsche, T. Krajník et al.: WhyCon: An Efficent, Marker-based Localization System. IROS Workshop on Open Source Aerial Robotics, 2015.

Acknowledgements

The development of this work is currently supported by the EU FET Open programme under grant agreement No.964492 project RoboRoyale. The development of this work was supported by the Czech Science Foundation project 17-27006Y STRoLL. In the past, the work was supported by EU within its Seventh Framework Programme project ICT-600623 STRANDS. The Czech Republic and Argentina have given support through projects 7AMB12AR022, ARC/11/11 and 13-18316P.