Statistics
| Branch: | Revision:

root / rgbdslam / README @ 9240aaa3

History | View | Annotate | Download (6.48 KB)

1
PREAMBLE
2

    
3
This release of RGBDSLAM succeeds our entry at the ROS 3D contest
4
(see http://www.ros.org/wiki/openni/Contests/ROS%203D). 
5

    
6
There have been many changes, mainly
7
- Performance improvments w.r.t accuracy and robustness of registration
8
- Performance improvments w.r.t computation time
9
- A more convenient user interface with internal visualization
10
- Convenience features, e.g., saving to pcd/ply file, node deletion and many more
11
- Use of g2o as SLAM Backend (formerly hogman)
12
- The ability to run without graphics card/X-Server
13

    
14

    
15
INSTALLATION
16

    
17
The following instructions assume you have ROS Diamondback installed in the
18
Desktop-Full configuration.  Otherwise please refer to
19
http://www.ros.org/wiki/ROS/Installation for instructions how to install ROS.
20
RGBDSLAM has been developed and tested on Ubuntu only.
21

    
22

    
23
Install openni-kinect. On ubuntu use the package manager: 
24
$ sudo aptitude install ros-diamondback-openni-kinect
25

    
26
Checkout g2o somewhere in your $ROS_PACKAGE_PATH:
27
$ svn co https://code.ros.org/svn/ros-pkg/stacks/vslam/trunk/g2o
28

    
29
To make g2o and install its system dependencies use
30
rosmake --rosdep-install
31
If that fails to resolve the system dependencies use (on ubuntu) 
32
$ sudo aptitude install libsuitesparse-dev libcsparse2.2.3 
33

    
34
Checkout the RGBDSLAM source code somewhere in your $ROS_PACKAGE_PATH
35
$ svn co https://svn.openslam.org/data/svn/rgbdslam/trunk rgbdslam
36

    
37
Compile rgbdslam and dependencies: 
38
$ rosmake --rosdep-install rgbdslam
39

    
40
Optionally, you might want to install perception_pcl_addons (debian package:
41
ros-diamondback-perception-pcl-addons) which includes pcd_viewer, a viewer for
42
the file format used by RGBDSLAM to store registered point clouds. If you
43
want to process the point cloud you can save to a ply file and use meshlab 
44
(debian-package: meshlab).
45

    
46

    
47
USAGE with GUI
48

    
49
To start RGBDSLAM launch
50
  roslaunch rgbdslam kinect+rgbdslam.launch
51

    
52
Alternatively you can start the openni nodes and RGBDSLAM separately, e.g.:
53
  roslaunch openni_camera openni_node.launch 
54
  rosrun rgbdslam rgbdslam
55

    
56
To capture models either press space to start recording a continuous stream
57
or press enter to record a single frame. To reduce data redundancy, sequential
58
frames from (almost) the same position are not included in the final model.
59
The 3D visualization always shows the globally optimized model. Neighbouring
60
points are triangulated except at missing values and depth jumps.
61

    
62
USAGE without GUI
63

    
64
The RosUI is an alternative to the Grapical_UI to run the rgbdslam headless, for example on the PR2.
65
rgbdslam can then be used via service-calls.
66
The possible calls are:
67
- /rgbdslam/ros_ui {reset, quick_save, save_all, save_individual, save_trajectory, send_all, delete_frame}
68
- /rgbdslam/ros_ui_b {pause, record} {true, false}
69
- /rgbdslam/ros_ui_f {set_max} {float}
70

    
71
To start the rgbdslam headless use the rgbdslam_headless.launch:
72
	roslaunch rgbdslam rgbdslam_headless.launch
73
capture single frames via:
74
	rosservice call /rgbdslam/ros_ui frame
75
capture a stream of data:
76
	rosservice call /rgbdslam/ros_ui_b pause false
77
send point clouds with computed transformations (e.g., to rviz or octomap_server):
78
	rosservice call /rgbdslam/ros_ui send_all
79
save the date using one of the following:
80
all pointclouds in one file quicksave.pcd in rgbdslam/bin-directory:
81
	rosservice call /rgbdslam/ros_ui save_all
82
every pointcloud in its own file in rgbdslam/bin-directory:
83
	rosservice call /rgbdslam/ros_ui save_individual
84

    
85
/rgbdslam/ros_ui:
86
	-reset	resets the graph, delets all nodes (refreshes only when capturing new images)
87
	-quick_save, save_all	saves all pointclouds in one file quicksave.pcd in rgbdslam/bin-directory
88
	-save_individual	saves every scan in its own file in rgbdslam/bin-directory
89
	-send_all	sends all pointclouds to /rgbdslam/transformed_cloud (can be visualized with rviz)
90
	-delete_frame	delete the last frame from the graph (refreshes only when capturing new images)
91
	
92
/rgbdslam/ros_ui_b:
93
	-pause	pauses or resumes the capturing of images
94
	-record	pauses or stops the recording of bag-files, can be found in the rgbdslam/bin-directory
95
	
96
/rgbdslam/ros_ui_f:
97
	-set_max	filters out all datapoints further away than this value (in cm, only for saving to files)
98

    
99
FURTHER HELP 
100

    
101
Here are some known issues:
102
1. If you have issues compiling, make sure you removed any older version 
103
   of RGBDSLAM from your $ROS_PACKAGE_PATH 
104
2. RGBDSLAM needs Diamondback. Make sure that neither your $PATH nor 
105
   $ROS_PACKAGE_PATH contains "boxturtle", "cturtle" or "unstable".
106
3. If you are located in Germany and get errors loading the saved ply files 
107
   into meshlab, try switching to U.S. locale or replace the decimal point with
108
   a comma in your .ply file
109
4. To speed up compile times consider to use "export ROS_PARALLEL_JOBS=-j<#cpus>"
110
   before rosmake, but you should have lots of memory as gcc may take up to
111
   2GB for four parallel jobs.
112

    
113
If you have questions regarding installation or usage of RGBDSLAM please refer
114
to http://answers.ros.org/questions/?tags=RGBDSLAM
115
For further questions, suggestions or to submit patches, please contact
116
Felix Endres (endres@informatik.uni-freiburg.de)
117

    
118
Apart from this manual, detailed code documentation can be created using
119
rosdoc ("rosrun rosdoc rosdoc rgbdslam"), which will create a "doc" folder
120
in your current directory.
121

    
122

    
123
EXPERIMENTAL FEATURES
124

    
125
The following features can be activated in CMakeLists.txt, but are highly
126
experimental and therefore neither guaranteed to work nor supported in case 
127
they do not.
128

    
129
  SIFTGPU:
130
  SiftGPU uses (in our case) CUDA, which needs a new NVidia GPU (see
131
  http://www.nvidia.com/object/cuda_gpus.html).  For installing the development
132
  drivers and the CUDA SDK you can use the following tutorial:
133
  http://sublimated.wordpress.com/2011/03/25/installing-cuda-4-0-rc-on-ubuntu-10-10-64-bit/
134
  or for ubuntu 10.04:
135
  http://ubuntuforums.org/showthread.php?t=1625433 (tested on Ubuntu 10.04 x64)
136
  To use SiftGPU you should install "libdevil-dev".
137
  
138
  Additional compiling information can be changed in
139
  external/siftgpu/linux/makefile.
140

    
141
  GICP
142
  Generalized ICP can be activated for refining the registration. For more
143
  information see http://stanford.edu/~avsegal/generalized_icp.html
144

    
145

    
146
LICENSE INFORMATION
147

    
148
This software is distributed in the hope that it will be useful, but WITHOUT
149
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
150
FOR A PARTICULAR PURPOSE.  The authors allow the users to use and modify the
151
source code for their own research. Any commercial application, redistribution,
152
etc has to be arranged between users and authors individually.
153

    
154
RGBDSLAM is licenced under GPL v.3.