Only released in EOL distros:  

Package LinksDependencies (8)

Package Summary

Documented

3D pose estimation ROS package using ArUco marker boards.

  • Maintainer: Hamdi Sahloul <sahloul AT race.u-tokyo.ac DOT jp>
  • Author: Hamdi Sahloul <sahloul AT race.u-tokyo.ac DOT jp>, Rafael Muñoz Salinas <rmsalinas AT uco DOT es>, Bence Magyar <bence.magyar AT pal-robotics DOT com>
  • License: BSD
  • Source: git https://github.com/Sahloul/ar_sys.git (branch: groovy-devel)
Package LinksDependencies (8)

Package Summary

Released
Documented

3D pose estimation ROS package using ArUco marker boards.

  • Maintainer status: developed
  • Maintainer: Hamdi Sahloul <sahloul AT race.u-tokyo.ac DOT jp>
  • Author: Hamdi Sahloul <sahloul AT race.u-tokyo.ac DOT jp>, Rafael Muñoz Salinas <rmsalinas AT uco DOT es>, Bence Magyar <bence.magyar AT pal-robotics DOT com>
  • License: BSD
  • Source: git https://github.com/Sahloul/ar_sys.git (branch: hydro-devel)
Package LinksDependencies (8)

Package Summary

Released
Documented

3D pose estimation ROS package using ArUco marker boards.

  • Maintainer status: developed
  • Maintainer: Hamdi Sahloul <sahloul AT race.u-tokyo.ac DOT jp>
  • Author: Hamdi Sahloul <sahloul AT race.u-tokyo.ac DOT jp>, Rafael Muñoz Salinas <rmsalinas AT uco DOT es>, Bence Magyar <bence.magyar AT pal-robotics DOT com>
  • License: BSD
  • Source: git https://github.com/Sahloul/ar_sys.git (branch: indigo-devel)

Contents

  1. Overview
  2. Installing
  3. Usage
  4. Scenarios
    1. Multiple cameras
  5. Nodes
  6. Launch files
  7. Bug Reports & Feature Requests

Overview

3D pose estimation ROS package using ArUco marker boards.

Installing

We are providing binary releases for many platforms, so you might just issue: 

   1 sudo apt-get install ros-indigo-ar-sys

Or equivalent depending on your operating system.

We are providing binary releases for many platforms, so you might just issue: 

   1 sudo apt-get install ros-hydro-ar-sys

Or equivalent depending on your operating system.

Since Groovy is now at its end of life, we don't provide releases for it, but you still can build it from the source. Assuming you know how to create a catkin workspace, you can use git and roslocate to automatically download the repository and set your path: 

   1 cd ~/catkin_ws/src
   2 roslocate uri ar_sys | xargs git clone

and then build the ar_sys package, by running: 

   1 cd ~/catkin_ws
   2 catkin_make

Usage

To use the launchers with full functionality, you might need to build uvc_camera from the source, as we depend on it in the camera capture capabilities.

To start tracking a single board of markers, ensure you pass the proper launcher parameters (see launch files for details) to meet your camera device, calibration URI, pointing to the correct board configuration, and then use: 

   1 roslaunch ar_sys single_board.launch

To track more boards, follow the same as of a single board, but modify the data/multi/boards.yml file to include all your board configuration files, and then launch: 

   1 roslaunch ar_sys multi-boards.launch

Finally, you could have the 3D rviz viewer of your boards by using: 

   1 roslaunch ar_sys system_viewer.launch

This is the very basic usage of the package, and there are more details in the scenarios below.

Scenarios

Multiple cameras

Assuming you have two cameras, and would like to display multiple boards from each camera in one 3D rvix environment. All you need is to execute something like these commands, each in a separate terminal: 

   1 roslaunch ar_sys multi-boards.launch video_namespace:=camera1 camera_frame_id:=camera1 camera_device:=/dev/video0 uid:=1
   2 roslaunch ar_sys multi-boards.launch video_namespace:=camera2 camera_frame_id:=camera2 camera_device:=/dev/video1 uid:=2
   3 roslaunch ar_sys system_viewer.launc

This is the single board version of the above scenario. 

   1 roslaunch ar_sys single_board.launch video_namespace:=camera1 camera_frame_id:=camera1 board_frame_id:=board1 camera_device:=/dev/video0 uid:=1
   2 roslaunch ar_sys single_board.launch video_namespace:=camera2 camera_frame_id:=camera2 board_frame_id:=board2 camera_device:=/dev/video1 uid:=2
   3 roslaunch ar_sys system_viewer.launch

Nodes

single_board

single_board listens to the /camera_info and /image topics and detects the markers board set by its parameters, and then publishes the from-the-camera transform of the board detect on the /transform topic. This is mainly used with system_viewer node to display the coordinates of the board and the camera related to a reference world point using rviz. The single_board node runs with a ~board_config parameter that points to a YAML file containing markers' positions and IDs within the board.

Subscribed Topics

/image (sensor_msgs/Image)
  • rectified image topic
/camera_info (sensor_msgs/CameraInfo)
  • camera info for the camera

Published Topics

/result (sensor_msgs/Image)
  • Shows input /image with augmented information
/debug (sensor_msgs/Image)
  • Shows the internal image resulting from the threshold operation
/position (geometry_msgs/Vector3Stamped)
  • Provides the position information of the detected board
/pose (geometry_msgs/PoseStamped)
  • Provides the position and orientation information of the detected board
/transform (geometry_msgs/TransformStamped)
  • Provides the transformation information from the camera to the detected board

Parameters

~image_is_rectified ([ {bool: bool} ], default: [true])
  • Whether to pass the P[] matrix values received from the /camera_info topic into ArUco core or not.
~marker_size ([ {double: double} ], default: [0.05])
  • The side length of the markers used in constructing the board in meters. It is used in the calculation of the distance between the camera and the marker itself.
~board_config ([ {str: str} ], default: ["boardConfiguration.yml"])
  • The path to the YAML file listing markers which contains number of markers used, and the markers array. Each marker in the array must have an "id" and "corners" keys.
~board_frame ([ {str: str} ], default: [""])
  • The frame ID of the board that get broadcasted in the /transform topic.
~draw_markers ([ {bool: bool} ], default: [false])
  • If true, /result topic will display the IDs and draw rectangles around each marker detected from the /image topic.
~draw_markers_cube ([ {bool: bool} ], default: [false])
  • If true, /result topic will draw cubes above each marker detected from the /image topic.
~draw_markers_axis ([ {bool: bool} ], default: [false])
  • If true, /result topic will draw the XYZ coordinates orientation of each marker detected from the /image topic.

multi_boards

multi_boards listens to the /camera_info and /image topics and detects virtually unlimited boards of markers set by YMAL config file indicated in its parameters, and then publishes the from-the-camera transforms of each board detected on the /transform topic. This is mainly used with system_viewer node to display the coordinates of the camera and each board related to a reference world point using rviz. The multi_boards node runs with a ~boards_config parameter that points to a YAML file containing list of boards.

Subscribed Topics

/image (sensor_msgs/Image)
  • rectified image topic
/camera_info (sensor_msgs/CameraInfo)
  • camera info for the camera

Published Topics

/result (sensor_msgs/Image)
  • Shows input /image with augmented information
/debug (sensor_msgs/Image)
  • Shows the internal image resulting from the threshold operation
/position (geometry_msgs/Vector3Stamped)
  • Provides the position information of each detected board
/pose (geometry_msgs/PoseStamped)
  • Provides the position and orientation information of each detected board
/transform (geometry_msgs/TransformStamped)
  • Provides the transformation information from the camera to each detected board

Parameters

~image_is_rectified ([ {bool: bool} ], default: [true])
  • Whether to pass the P[] matrix values received from the /camera_info topic into ArUco core or not.
~boards_config ([ {str: str} ], default: ["boardsConfiguration.yml"])
  • The path to the YAML file listing boards which contains the boards array. Each board in the array must have an "name", "path" and "marker_size" keys. The name is the equivalent to board_frame from the single_board node while marker_size is obviously the equivalent to marker_size parameter, the path is a relative path to the boards_directory parameter, and it points to a single YML file as of the board_config parameter from the single_board node.
~boards_directory ([ {str: str} ], default: ["./data"])
  • A directory that contains all the boards' YAML configuration files.
~draw_markers ([ {bool: bool} ], default: [false])
  • If true, /result topic will display the IDs and draw rectangles around each marker detected from the /image topic.
~draw_markers_cube ([ {bool: bool} ], default: [false])
  • If true, /result topic will draw cubes above each marker detected from the /image topic.
~draw_markers_axis ([ {bool: bool} ], default: [false])
  • If true, /result topic will draw the XYZ coordinates orientation of each marker detected from the /image topic.

system_viewer

system_viewer listens to the /transform topic and shows together all the boards and cameras coordinates in a single world, and then publishes the visualization markers of each board detected on the /visualization_marker topic. This is mainly used by rviz to display visualized markers, rviz also receives a transforms broadcast of both cameras and boards positions and orientations to visualize it as well. The system_viewer node runs with a ~map_path parameter that points to a YAML file containing list of board names and its positioning configuration.

Subscribed Topics

/transform (geometry_msgs/TransformStamped)
  • Transformation information from each camera to its corresponding detected boards

Published Topics

/visualization_marker (visualization_msgs/Marker)
  • visualize each board received via /transform in a single 3D.

Parameters

~map_path ([ {str: str} ], default: ["map.yml"])
  • The path to the YAML file listing both boards and cameras positioning configuration arrays. Each board is allowed to be of type: fixed, relative, or floating, while cameras can only be fixed or floating. in case of a fixed position, you need to provide the pose (direction/orientation) values in meter and Radian respectively. fixed position is related to the world (0, 0, 0) point while relative position is relating another marker to the current floating board position. Same concept applies to each camera from the cameras array noting the absence of relative positioning system.
~digital_filter_change_rate ([ {double: double} ], default: [0.5])
  • The rate of change in floating cameras, boards, and relative markers position. Zero will disable the system totally, One mean instantaneous change (disabling the filter). If you have more than a single input transform contributing to the averaging of the position of a floating camera, or floating/relative marker, you need to tune the filter value in the range of 0 < digital_filter_change_rate < 1

Launch files

There are many roslaunch parameters that we are employing in the launchers of each node. Here is the details:

single_board.launch

single_board.launch launches the single_board node (see nodes section) with optionally a uvc_camera and image_proc nodes to capture images from your webcam, and a image_view node to display the marker detection results.

Parameters

camera_enable ([ {bool: bool} ], default: [true]) camera_device ([ {str: str} ], default: ["/dev/video0"])
  • The path to the camera device.
camera_info ([ {str: str} ], default: ["file://$(find ar_sys)/camera_info/camera_calibration.yaml"])
  • The URL to the camera calibration file.
camera_frame_id ([ {str: str} ], default: ["camera1"])
  • The frame ID of the camera that get broadcasted in the topics.
camera_width ([ {int: int} ], default: [1280])
  • Width of the camera captured frame.
camera_height ([ {int: int} ], default: [1024])
  • Height of the camera captured frame.
camera_fps ([ {int: int} ], default: [30])
  • How many frame per second shall the camera provides.
result_display ([ {bool: bool} ], default: [true])
  • Shall we display the result image using image_view?
result_autosize ([ {bool: bool} ], default: [true])
  • Shall image_view re-size automatically to the contain the result images.
result_draw_markers ([ {bool: bool} ], default: [false])
  • Redirected to the draw_markers node parameter.
result_draw_markers_cube ([ {bool: bool} ], default: [false])
  • Redirected to the draw_markers_cube node parameter.
result_draw_markers_axis ([ {bool: bool} ], default: [false])
  • Redirected to the draw_markers_cube node parameter.
uid ([ {str: str} ], default: [""])
  • A unique ID to allow multiple launchers, this is useful when you want to use many cameras.
video_namespace ([ {str: str} ], default: ["/camera1"])
  • If the camera_enable:=true, it will manipulate the topics name accordingly, otherwise, it will only prefix both the video_image_topic and video_info_topic parameters.
video_image_topic ([ {str: str} ], default: ["image_rect_color"])
  • The image topic name excluding the video_namespace indicated previously.
video_info_topic ([ {str: str} ], default: ["camera_info"])
  • The camera calibration info topic excluding the video_namespace indicated previously.
video_rectified ([ {bool: bool} ], default: [true])
  • Redirected to the image_is_rectified node parameter.
board_config ([ {str: str} ], default: ["$(find ar_sys)/data/single/board.yml"])
  • Same as board_config node parameter.
board_frame_id ([ {str: str} ], default: ["board1"])
  • Redirected to the board_frame node parameter.
marker_size ([ {double: double} ], default: [0.05])
  • Same as marker_size node parameter.

multi-boards.launch

multi-boards.launch launches the multi_boards node (see nodes section) with optionally a uvc_camera and image_proc nodes to capture images from your webcam, and a image_view node to display the marker detection results.

Parameters

camera_enable ([ {bool: bool} ], default: [true]) camera_device ([ {str: str} ], default: ["/dev/video0"])
  • The path to the camera device.
camera_info ([ {str: str} ], default: ["file://$(find ar_sys)/camera_info/camera_calibration.yaml"])
  • The URL to the camera calibration file.
camera_frame_id ([ {str: str} ], default: ["camera1"])
  • The frame ID of the camera that get broadcasted in the topics.
camera_width ([ {int: int} ], default: [1280])
  • Width of the camera captured frame.
camera_height ([ {int: int} ], default: [1024])
  • Height of the camera captured frame.
camera_fps ([ {int: int} ], default: [30])
  • How many frame per second shall the camera provides.
result_display ([ {bool: bool} ], default: [true])
  • Shall we display the result image using image_view?
result_autosize ([ {bool: bool} ], default: [true])
  • Shall image_view re-size automatically to the contain the result images.
result_draw_markers ([ {bool: bool} ], default: [false])
  • Redirected to the draw_markers node parameter.
result_draw_markers_cube ([ {bool: bool} ], default: [false])
  • Redirected to the draw_markers_cube node parameter.
result_draw_markers_axis ([ {bool: bool} ], default: [false])
  • Redirected to the draw_markers_cube node parameter.
uid ([ {str: str} ], default: [""])
  • A unique ID to allow multiple launchers, this is useful when you want to use many cameras.
video_namespace ([ {str: str} ], default: ["/camera1"])
  • If the camera_enable:=true, it will manipulate the topics name accordingly, otherwise, it will only prefix both the video_image_topic and video_info_topic parameters.
video_image_topic ([ {str: str} ], default: ["image_rect_color"])
  • The image topic name excluding the video_namespace indicated previously.
video_info_topic ([ {str: str} ], default: ["camera_info"])
  • The camera calibration info topic excluding the video_namespace indicated previously.
video_rectified ([ {bool: bool} ], default: [true])
  • Redirected to the image_is_rectified node parameter.
boards_config ([ {str: str} ], default: ["$(find ar_sys)/data/multi/boards.yml"])
  • Same as boards_config node parameter.
boards_directory ([ {str: str} ], default: ["$(find ar_sys)/data/multi"])
  • Same as boards_directory node parameter.

system_viewer.launch

system_viewer.launch launches the system_viewer node (see nodes section) along with a rviz node to display the detected boards and cameras' transforms in a visual way.

Parameters

map_path ([ {str: str} ], default: ["$(find ar_sys)/data/viewer/map.yml"])
  • Same as map_path node parameter.
digital_filter_change_rate ([ {double: double} ], default: [0.5])
  • Same as digital_filter_change_rate node parameter.
rviz_config_path ([ {str: str} ], default: ["$(find ar_sys)/data/viewer/viewer.rviz"])
  • The path to the rviz configuration file. See rviz guide for details.

Bug Reports & Feature Requests

/!\ When asking questions or looking for help running ar_sys, use the ar_sys tag on ROS answers

Use GitHub to report bugs or submit feature requests. [View active issues]
We appreciate the time and effort spent submitting bug reports.

Wiki: ar_sys (last edited 2016-04-22 08:38:38 by Sahloul)

Except where otherwise noted, the ROS wiki is licensed under the
Creative Commons Attribution 3.0