whycon 1.0.1

Python wrapper for Whycon (Whycode), precise, efficient and low-cost localization system

pywhycon

Python wrapper for Whycon.

Whycon is 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.

Dependencies

• OpenCV
• Whycon Core library - see bellow
• pkconfig - only for module building
• pybind11 - only for module building
• numpy

Install

You have to install the package from your active python environment.

Depending on your environment, you may need to enter something like

conda activate _your_python_environment_name_

or

workon _your_python_environment_name_.

Makefile

Compile and linking module to ./bin/whycon.so.

(It also compiles the Whycon Core library.)

make

setup.py

./setup.py install

(It calls the make [see above] and installs the whycon package in the current python environment.)

Pip

pip install whycon

Examples

Examples are in the usecases directory in the repo on GitHub.

show_help.py

It only tests that the module was installed successfully. It prints the help message of the module.

camera_test.py

Turn on the USB webcam and see what it sees. If Whycon-markers are found in the image, they will be highlighted and their found properties will be written to the console.

autocalibration_test.py

Automatic calibration of space transformation parameters by monitoring four WhyCon markers arranged in a square (with the configured length of its side).

web_camera.py

Auxiliary object, camera abstraction. (Searches for the first unshaded camera.)

window.py

Auxiliary object, Screen window abstraction.

Whycon core library as a submodule

The Whycon core library is a git submodule of this repository.

If you do not have a whycon_core directory in the root directory, enter

git submodule init
git submodule update

Whycon Core library

The package (pywhycon) is a wrapper of the Whycon core library.

For citations of articles, contacts to the original author, please see these pages. You will also find citations of projects that contributed to the development of the Whycon.

---

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.

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. Each of these contributors maintains a slightly different version of WhyCon.

History of the repo

There are many implementations of this idea on GitHub. Because they come from the scientific environment, they are at different stages of development and with different modifications. The goal of this implementation is to enable the development of the core of this idea as an independent library that can be used by other projects.

The basis for this library is the implementation from https://github.com/jiriUlr/whycon-ros.

There is a fully functional reproduction of individual marks in the image, as well as their identification (WhyCode).

Other significant implementations

WhyCon version	Application	Main features	Maintainer
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 in this bibtex file.

---

Dependencies

• opencv

How to build and install

####In general To see a current variable setting of Makefile you can call make info

If you want to set a parameter, you can do it as follows make info USE_OPENCV_FROM_PYTHON=1 (make USE_OPENCV_FROM_PYTHON=1)

####OpenCv and other (Python for example) Unfortunately, the current implementation is dependent on OpenCV. If you expect to use the library with another application/library (such as Python), you need to use the same version of the OpenCV library.

If the variable USE_OPENCV_FROM_PYTHON = 1 (default is 0) the makefile tries to find OpenCV, which is in the appropriate version of Python.

If you use a virtual Python environment, you must activate it during the compilation.

(For example conda activate <your enviroment> or source venv/bin/activate , ...)

####Compilation and linking

make

or (for Python, inside of Python enviroment )

make USE_OPENCV_FROM_PYTHON=1

Install

sudo make install

Uninstall

sudo make uninstall

Projects that produce this library

• Python wrapper for whycon (vision-based localization system)

To Do List

• Transfer hidden parameters from code to configurations.
• Add tests.
• Remove the dependency on opencv (used mainly for coordinate transformation).

References

1. T. Krajník, M. Nitsche et al.: A Practical Multirobot Localization System. Journal of Intelligent and Robotic Systems (JINT), 2014. [bibtex].
2. T. Krajník, M. Nitsche et al.: External localization system for mobile robotics. International Conference on Advanced Robotics (ICAR), 2013. [bibtex].
3. M. Nitsche, T. Krajník et al.: WhyCon: An Efficent, Marker-based Localization System. IROS Workshop on Open Source Aerial Robotics, 2015. [bibtex].
4. 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. [bibtex].
5. P. Lightbody, T. Krajník et al.: A versatile high-performance visual fiducial marker detection system with scalable identity encoding.Symposium on Applied Computing, 2017.[bibtex].

Acknowledgements

The development of this work is currently 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. We sincerely acknowledge Jean Pierre Moreau for his excellent libraries for numerical analysis that we use in our project.