Added ar_track_alvar_example

examples/README.md

@@ -4,3 +4,5 @@ How to use the ZED ROS node with other ROS packages
 * `zed_nodelet_example`: shows how to use the nodelet intraprocess communication to generate a virtual laser scan using the [depthimage_to_laserscan](http://wiki.ros.org/depthimage_to_laserscan) package
 
 * `zed_rtabmap_example`: shows how to use the ZED with the RTABMap package to generate a 3D map with the [rtabmap_ros](http://wiki.ros.org/rtabmap_ros) package
+
+* `zed_ar_track_alvar_example`: shows how to use the ZED with the [ar_track_alvar](http://wiki.ros.org/ar_track_alvar) package to detect and track the position of AR tags

examples/zed_ar_track_alvar_example/CMakeLists.txt

@@ -0,0 +1,20 @@
+cmake_minimum_required(VERSION 2.8.7)
+
+project(zed_ar_track_alvar_example)
+
+find_package(catkin REQUIRED)
+
+catkin_package()
+
+###############################################################################
+#Add all files in subdirectories of the project in
+# a dummy_target so qtcreator have access to all files
+FILE(GLOB_RECURSE extra_files ${CMAKE_SOURCE_DIR}/*)
+add_custom_target(dummy_${PROJECT_NAME} SOURCES ${extra_files})
+
+###############################################################################
+# INSTALL
+
+install(DIRECTORY
+  launch
+  DESTINATION ${CATKIN_PACKAGE_SHARE_DESTINATION})

examples/zed_ar_track_alvar_example/README.md

@@ -0,0 +1,85 @@
+# Stereolabs ZED Camera - Alvar AR tag example
+
+This package shows how to use the ZED Wrapper with [ar_track_alvar](http://wiki.ros.org/ar_track_alvar) to detect AR markers and localize them in the space.
+
+The [ar_track_alvar](http://wiki.ros.org/ar_track_alvar) package is a ROS wrapper for [Alvar](http://virtual.vtt.fi/virtual/proj2/multimedia/index.html), an open source AR tag tracking library.
+
+## Install the ar_track_alvar package
+
+Open a terminal and launch
+
+    $ sudo apt install ros-kinetic-ar-track-alvar
+
+## Run the program
+
+To launch the example, open a terminal and launch:
+
+    $ roslaunch zed_ar_track_alvar_example zed_ar_track_alvar.launch
+
+The launch file automatically starts the `zed_wrapper` node, the `ar_track_alvar` node and `RVIZ` with a preconfigured view:
+
+![Example of indoor 3D mapping](images/ar_track_alvar.png)
+
+* the `Left Image` view shows the RGB stream from the left camera of the ZED.
+* the `Left Camera` view shows the "world" as seen by the left camera. The `TF` and the `Tags` are selected to be shown in 3D projection
+* the 3D view shows the ZED camera localized in the space and the position of the `Tags` as coloured markers.
+
+*Note* It is important to subscribe the `/zed/pose` topic to be able to localize the camera in the space.
+
+*Note* the tags used in the example are available following this [link](images/markers0to8.png)
+
+## The launch file explained
+
+To use the ZED wrapper with the `ar_track_alvar` node we need to correctly set the following ar_track_alvar parameters:
+
+- `camera_image` -> the name of the topic that provides camera frames for detecting the AR tags.
+- `camera_info` -> the name of the topic of camera parameters used to correctly localize the tag in the 3D world
+- `output_frame` -> the name of the TF frame associated to the camera position
+
+It is important that the `zed_wrapper` node and the `ar_track_alvar` node use the same values for these three parameters to be able to correctly communicate.
+
+The values associated to the above parameters are the following:
+
+```
+    <arg name="cam_image_topic"         default="rgb/image_rect_color" />
+    <arg name="cam_info_topic"       	default="rgb/camera_info" />
+    <arg name="camera_frame"            default="zed_left_camera_frame" />
+```
+
+The corresponding parameters of the ZED node are the following:
+
+- `cam_image_topic` -> `rgb_topic`
+- `cam_info_topic` -> `rgb_info_topic`
+- `camera_frame` -> `left_camera_frame`
+
+The corresponding parameters of the `rtabmap_ros` node are the following:
+
+- `cam_image_topic` -> `camera_image`
+- `cam_info_topic` -> `camera_info`
+- `camera_frame` -> `output_frame`
+
+It is also important to set the correct `marker_size` in centimeters. Better if the real size of the markers is measured after printing them:
+
+    <arg name="marker_size" default="5.0" />
+
+Other parameters that can be tuned:           
+* `max_new_marker_error` -> A threshold determining when new markers can be detected under uncertainty
+* `max_track_error` -> A threshold determining how much tracking error can be observed before an tag is considered to have disappeared
+
+Their values in the launch file:
+
+    <arg name="max_new_marker_error" default="0.08" />   
+    <arg name="max_track_error" default="0.2" />
+
+## Markers
+
+Following two examples of markers with ID numbers from 0 to 17:
+
+![Markers 0-8](images/markers0to8.png)
+![Markers 9-17](images/markers9to17.png)
+
+
+
+
+
+

examples/zed_ar_track_alvar_example/launch/zed_ar_track_alvar.launch

@@ -0,0 +1,71 @@
+<?xml version="1.0"?>
+<!--
+Copyright (c) 2018, STEREOLABS.
+
+All rights reserved.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+-->
+<launch>
+    <arg name="zed_namespace"		    	default="zed" />
+
+    <arg name="svo_file"              	default="" /> <!-- <arg name="svo_file" default="path/to/svo/file.svo"> -->
+
+    <arg name="camera_model"         	default="1" />
+    <arg name="serial_number"        	default="0" />
+    <arg name="verbose"              	default="true" />
+    <arg name="resolution"           	default="2" /> <!--0=RESOLUTION_HD2K, 1=RESOLUTION_HD1080, 2=RESOLUTION_HD720, 3=RESOLUTION_VGA -->
+    <arg name="frame_rate"           	default="30" />
+    <!-- RESOLUTION_HD2K   -> 2208*1242, available framerates: 15 fps.
+       RESOLUTION_HD1080 -> 1920*1080, available framerates: 15, 30 fps.
+       RESOLUTION_HD720  -> 1280*720,  available framerates: 15, 30, 60 fps.
+       RESOLUTION_VGA    -> 672*376,   available framerates: 15, 30, 60, 100 fps. -->
+
+    <arg name="cam_image_topic"         default="rgb/image_rect_color" />
+    <arg name="cam_info_topic"       	default="rgb/camera_info" />
+    <arg name="camera_frame"            default="zed_left_camera_frame" />
+
+    <group ns="$(arg zed_namespace)">
+        <!-- Pre configured RVIZ -->
+        <node name="rviz" pkg="rviz" type="rviz" args="-d $(find zed_ar_track_alvar_example)/rviz/zed_ar_track_alvar_example.rviz" output="screen"/>
+
+        <!-- ZED Wrapper Node-->
+        <include file="$(find zed_wrapper)/launch/zed_camera.launch">
+          <arg name="svo_file"            	value="$(arg svo_file)" />
+          <arg name="camera_model"        	value="$(arg camera_model)" />
+          <arg name="serial_number"       	value="$(arg serial_number)" />
+          <arg name="resolution"          	value="$(arg resolution)" />
+          <arg name="frame_rate"          	value="$(arg frame_rate)" />
+          <arg name="verbose"             	value="$(arg verbose)" />
+
+          <arg name="rgb_topic"                 value="$(arg cam_image_topic)" />
+          <arg name="rgb_info_topic"       	value="$(arg cam_info_topic)" />
+          <arg name="left_camera_frame"         value="$(arg camera_frame)" />
+        </include>
+
+        <!-- ar_track_alvar Node -->
+        <arg name="marker_size" default="5.0" />
+        <arg name="max_new_marker_error" default="0.08" />
+        <arg name="max_track_error" default="0.2" />
+
+        <node name="ar_track_alvar" pkg="ar_track_alvar" type="individualMarkersNoKinect" respawn="false" output="screen">
+                <param name="marker_size"           type="double" value="$(arg marker_size)" />
+                <param name="max_new_marker_error"  type="double" value="$(arg max_new_marker_error)" />
+                <param name="max_track_error"       type="double" value="$(arg max_track_error)" />
+                <param name="output_frame"          type="string" value="$(arg camera_frame)" />
+
+                <remap from="camera_image"  to="$(arg cam_image_topic)" />
+                <remap from="camera_info"   to="$(arg cam_info_topic)" />
+        </node>
+    </group>
+</launch>

examples/zed_ar_track_alvar_example/package.xml

@@ -0,0 +1,17 @@
+<?xml version="1.0"?>
+<package format="2">
+  <name>zed_ar_track_alvar_example</name>
+  <version>2.6.0</version>
+  <description>
+    "zed_ar_track_alvar_example" is a ROS package to show how to use the ROS wrapper with <a href="http://wiki.ros.org/ar_track_alvar">"ar_track_alvar"</a>
+  </description>
+
+  <maintainer email="[email protected]">STEREOLABS</maintainer>
+  <license>MIT</license>
+
+  <buildtool_depend>catkin</buildtool_depend>  
+
+  <exec_depend>ar_track_alvar</exec_depend>
+  <exec_depend>ar_track_alvar_msgs</exec_depend>
+  <exec_depend>zed_wrapper</exec_depend>
+</package>