aruco_eye
This is the repository of the aruco_eye metapackage. It is a ROS wrapper of the ArUco library (ArUco: a minimal library for Augmented Reality applications based on OpenCV http://www.uco.es/investiga/grupos/ava/node/26), adding extra functionalities very useful for Robotics.
Table of contents
Disclaimer
You are using this software at your own risk. The authors decline any responsibility for personal injuries and/or property damage.
Repository information
Packages
This repository is formed by a five ROS packages:
- aruco_lib: original ArUco library (see http://sourceforge.net/projects/aruco/ and http://www.uco.es/investiga/grupos/ava/node/26 ) with catkin elements (CMakeLists.txt and package.xml)
- aruco_eye_core: C++ (and ROS-independent) wrapper of the ArUco library with additional functionalities.
- aruco_eye_msgs: messages
- aruco_eye_srvs: services
- aruco_eye_ros: ROS-dependent wrapper of the ArUco library with additional functionalities.
And one ROS metapackage:
Libraries and executables generated by this repository
This repository generates:
- Libraries: several
- Executables: two, aruco_eye_ros_detector and aruco_eye_ros_display
Repository Branches
This repository has the following branches:
- Master: Catkin version of the package.
Repository requirements and dependencies
System Requirements and Compatibility
This package is running under:
- Ubuntu: 14.04 and above
- ROS: Indigo and above with Catkin
This package has been tested under:
- Ubuntu: 14.04
- ROS: Indigo and Jade with Catkin
Dependencies
Additional System Dependencies
This metapackage requires:
- OpenCV 2.0 and above
- Boosts
ROS Dependencies
This metapackage depends on the following ROS packages:
Extra ROS Dependencies
This metapackage depends on the following extra ROS packages:
Installation Instructions
Pre-requirements
Install all the system and ROS dependencies (for example, using rosdep install, or apt-get, or directly from source).
Installation steps
- Create your ROS catkin workspace as usual.
- Inside your workspace, download the extra ROS package pugixml:
git clone https://github.com/joselusl/pugixml ./
- Inside your workspace, download the aruco_eye repository:
git clone https://github.com/joselusl/aruco_eye ./
- Compile your ROS catkin workspace as usual.
Running Instructions
The package aruco_eye_ros included in this repository generates two ROS nodes that can be executed:
aruco_eye_ros_detector
This node processes the given images searching for ArUco visual markers, publishing them in a ROS topic.
ROS Launcher
The package aruco_eye_ros includes a launcher called aruco_eye_ros_detector.launch.
ROS Topics
Subscribed topics:
- camera/image_raw [sensor_msgs/Image]: The images where the ArUco visual markers are going to be detected.
- camera/camera_info [sensor_msgs/CameraInfo]: The calibration info of the camera.
Published topics:
- aruco_eye/aruco_observation [aruco_eye_msgs/MarkerList]: The list of the detected visual markers with all its information.
- tf [tf2_msgs/TFMessage]: The tf information of the detected and reconstructed visual markers.
ROS Parameters
Configurable ROS parameters:
- aruco_list_file [type=string, default=$(find aruco_eye_ros)/config/arUcoList.xml]: the path to the ArUco list configuration file. See below for more information.
- camera_calibration_file [type=string, default=]: the path to the camera calibration file. If nothing is used here, it uses the information given by the camera/camera_info topic.
- aruco_detector_frame_name [type=string, default=aruco_detector]: the name of the aruco detector frame.
- aruco_marker_child_base_name [type=string, default=aruco_marker_]: the base name for the visual markers frame.
- image_topic_name [type=string, default=camera/image_raw]: the topic name of the images.
- camera_info_topic_name [type=string, default=camera/camera_info]: the topic name of the camera calibration.
- aruco_list_topic_name [type=string, default=aruco_eye/aruco_observation]: the topic name for the list of detected visual markers.
ROS Services
None.
Additional Configurations in files
There are two configuration files. An example can be find in aruco_eye_ros/config:
-
camera.yml: camera configuration file in YAML format. File type generated by OpenCV. For more information, please refer to: http://www.uco.es/investiga/grupos/ava/node/26
-
arUcoList.xml: ArUco list configuration file in XML format. It has the information of the ArUco visual markers that want to be detected. Please open the example file in aruco_eye_core/config/arUcoList.xml for basic information. Please, be sure that the format is correct, otherwise the node will not work.
aruco_eye_ros_display
This node allows the visualization of the detected ArUco visual markers by the node aruco_eye_ros_detector.
ROS Launcher
The package aruco_eye_ros includes a launcher called aruco_eye_ros_display.launch.
ROS Topics
Subscribed topics:
- camera/image_raw [sensor_msgs/Image]: The images where the ArUco visual markers are going to be detected.
- camera/camera_info [sensor_msgs/CameraInfo]: The calibration info of the camera.
- aruco_eye/aruco_observation [aruco_eye_msgs/MarkerList]: The list of the detected visual markers with all its information.
Published topics:
- aruco_eye/aruco_observation_image/image_raw [sensor_msgs/Image]: The image with the drawed ArUco Visual Markers.
ROS Parameters
Configurable ROS Parameters:
- display_output_image_window_name [type=string, default=arUco_display_window]: the name of the OpenCV local window to display the visual markers.
- flag_display_output_image [type=boolean, default=True]: flag to enable or disable the display of the drawed markers using an OpenCV local window
- display_output_image_service_name [type=string, default=aruco_eye/enable_display_output_image]: service name to enable or disable the display of the drawed markers using an OpenCV local window.
- camera_calibration_file [type=string, default=]: See above.
- camera_info_topic_name [type=string, default=camera/camera_info]: See above.
- image_topic_name [type=string, default=camera/image_raw]: See above.
- aruco_list_topic_name [type=string, default=aruco_eye/aruco_observation]: See above.
- output_image_topic_name [type=string, default=aruco_eye/aruco_observation_image/image_raw]: topic name of the image with the drawed ArUco Visual Markers.
ROS Services
Services served:
- aruco_eye/enable_display_output_image [aruco_eye_srvs/SetBool]: to enable or disable the display of the drawed markers using an OpenCV local window.
Additional Configurations
There is one configuration file. An example can be find in aruco_eye_ros/config:
Documentation
For more information related to the ArUco library or camera calibration, please refer to: http://www.uco.es/investiga/grupos/ava/node/26.
It exists another similar package called aruco (see http://wiki.ros.org/aruco and https://github.com/pal-robotics/aruco_ros) with the following limitations compared to aruco_eye:
- It is just a wrapper of the ArUco library with few examples and it does not implement a complete solution. The metapackage aruco_eye implements a complete solution for robotics.
- The detection and the drawing is done by the same node, what can be a problem in robotics, for example, when processing onboard and having a ground station for visualization. In aruco_eye is solved by splitting the detection and 3D reconstruction node (aruco_eye_ros_detector node) and the drawind and visualization (aruco_eye_ros_display node),
- It is hard to implement a big number of visual markers with different sizes. In aruco_eye is solved using an XML config file.
This repository is the continuation of the work done by Jose Luis Sanchez-Lopez to use the ArUco library in ROS, initied in January 2013. The first version was splitted in the following repositories (already outdated and deprecated) and its dependencies:
Unfortunately this repository has no more extra documentation.
If this repository gets the interest of the community, we will continue adding information depending on the questions made by its users.
License
All distributed software are subject to the 3-clause BSD license. See the LICENSE file.
Please, refer to http://www.uco.es/investiga/grupos/ava/node/26 to check the license of the ArUco library (BSD).
Contributors
Authors / Maintainers / Past contributors
List of people that have contributed:
- Jose Luis Sanchez-Lopez (jl.sanchez@upm.es): Main Author, Maintainaince, Debugging, Testing and Documentation.
Contact information
Questions, suggestions, requests, ... whatever. Feel free to contact me (Jose Luis Sanchez-Lopez - jl.sanchez@upm.es).
New contributors
You are very welcome to contribute to this repository by opening a pull request via Github.
Acknowledgments
Special thanks to:
