Statistics
| Branch: | Revision:

root / rgbdslam / gicp / README @ 9240aaa3

History | View | Annotate | Download (7.74 KB)

1
LICENSE
2
=======
3
  Generalized-ICP Copyright (c) 2009 Aleksandr Segal; avsegal@cs.stanford.edu.
4
  All rights reserved.
5

    
6
  Redistribution and use in source and binary forms, with 
7
  or without modification, are permitted provided that the 
8
  following conditions are met:
9

    
10
* Redistributions of source code must retain the above 
11
  copyright notice, this list of conditions and the 
12
  following disclaimer.
13
* Redistributions in binary form must reproduce the above
14
  copyright notice, this list of conditions and the 
15
  following disclaimer in the documentation and/or other
16
  materials provided with the distribution.
17
* The names of the contributors may not be used to endorse
18
  or promote products derived from this software
19
  without specific prior written permission.
20

    
21
  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
22
  CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED
23
  WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
24
  WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
25
  PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
26
  COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, 
27
  INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 
28
  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 
29
  PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
30
  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
31
  CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 
32
  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE 
33
  OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
34
  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
35
  DAMAGE.
36

    
37

    
38
ABOUT
39
=====
40
This is a reference implementation of Generalized-ICP, a scanmatching approach based on the ICP algorithm. You can find specific details in the original paper:
41
     Generalized-ICP, Aleksandr V. Segal, Dirk Haehnel, and Sebastian Thrun. In Robotics: Science and Systems 2009.
42
This reference implementation uses the plane-to-plane approach described in the paper; to adapt this code to other models within the framework, you will have to dig through the code a bit and set up your own 'matrices' (check out the paper/code if interested in this).
43

    
44

    
45
ACKNOWLEDGMENTS
46
================
47
This version is implemented with the help of some external code:
48
    Mike Montemerlo's dgc_transform_t struct and associated library was originally written for the Stanford Driving software.
49
    GSL library can be found at: http://www.gnu.org/software/gsl/
50
    ANN library: http://www.cs.umd.edu/~mount/ANN/ respectively.
51
    plot_gaussian_ellipsoid.m by Gautam Vallabha.
52

    
53
Overall, Dirk Haehnel and Sebastian Thrun have helped a lot in this project.
54

    
55

    
56
COMPILATION INSTRUCTIONS
57
========================
58
1. Compile the ANN library
59
   go to gicp/ann_1.1.1/ and run "make <ARCH>"
60

    
61
2. Compile the GICP library and test code
62
   go to gicp/ and run "make".
63
   If this doesn't work, you make have to modify the Makefile to get the linking to work on your system. This may involve changing the LFLAGS and CXXFLAGS variables to be consistent with your library installations.
64

    
65

    
66

    
67
USAGE INSTRUCTIONS
68
==================
69
After compiling the library, you should run a test or two to make sure it works. The test_gicp program is provided for this. Running ./test_gicp --help will give usage information. The parameters and usage are described in more detail below:
70

    
71
test_gicp runs gicp to align two input scans. scan2 is used as a base, and scan1 is aligned to it. There are a couple of basic parameters to the algorithm which can be changed from the command line. 
72

    
73

    
74
scan1, scan2 -- These are the filenames of the two scans, assumed to be tab-deliminated ascii
75

    
76
t_base 	     -- The provides a base transformation which is applied to scan1 before any matching happens. You can use this to specify the initial alignment. I.e. t_base should specify the transformation which initially best aligns scan1 to scan2. The .tfm file format is a text file which specifies rotations for each axis, followed by translation. The rotations are applied in the order that they are specified, and the translation is done after all rotations. t_base should specify the filename of a .tfm file.
77

    
78
debug	     -- Set to true (or 1) to enable debug out and information. Set to false (or 0) to hide intermediate output. Defaults to true.
79

    
80
epsilon	     -- This is the epsilon constant mentioned in the Generalized-ICP paper (see RSS '09). It controls the ratio between cost along a surface and cost along the surface normal. Setting epsilon=1. makes the algorithm equivalent to standard ICP (i.e. euclidean distance). Setting it to 0 will break everything and cause NaNs everywhere. The ideal value seems to be the lowest possible which does not cause numerical instability. In practice 1e-3 works well and is used as the default value. I don't think there is a need to adjust it more finely then 1e-4, 5e-4, 1e-3, 5e-3, etc. but it's possible you may.
81

    
82
d_max	     -- Controls the maximum matching distance threshold. In any given iteration, point correspondences which are more then this distance apart will be ignored. It is important to note that the correspondences are computed and filtered using standard euclidean distance.
83

    
84

    
85

    
86
VISUALIZATION
87
=============
88
There is a matlab directory provided which contains some simple code to visualize the debugging output of test_gicp. After running test_gicp in a directory with debugging output enabled, you can use the plot_convergence command in matlab to show how the algorithm converged. There are a couple options for this which are important when dealing with large files. The following documentation is copied from the top of plot_convergence.m:
89

    
90
   % plot_convergence plots the convergence of the icp algorithm based on
91
   % debugging output from the c++ program test_gicp. test_gicp outputs both
92
   % pointclouds, a sequence of transformations (one for each iteration),
93
   % the final correspondence, and the corresponding weight matrices. Running
94
   % plot_convergence will plot this information.
95
   % dir -- base directory were debug output was saved (directory test_gicp was run in)
96
   % show_corresp -- set to 1 to plot final correspondences
97
   % show_metrics -- set to 1 to plot final weight matrix ellipsoids (slow)
98
   % skip1 -- draws every skip1 point in pointcloud1
99
   % skip2 -- draws every skip2 point in pointcloud2
100
   % the default values for show_corresp, show_metrics, skip1, skip2 are
101
   % 0,0,1,1 respecively.
102

    
103
running "plot_convergence('../');" from gicp/matlab should visualize the output of thr last run of test_gicp from the gicp/ directory.
104

    
105

    
106
SAMPLE COMMANDS
107
===============
108
Here are some sample to get you started:
109
# default parameters
110
./test_gicp data/car/car0.ascii data/car/car1.ascii --t_base data/sample_base.tfm 
111

    
112
# simulates standard ICP
113
./test_gicp data/car/car0.ascii data/car/car1.ascii --t_base data/sample_base.tfm --epsilon 1.
114

    
115

    
116
# default parameters
117
./test_gicp data/outdoor/outdoor0\[300x541\].ascii data/outdoor/outdoor2\[300x541\].ascii --t_base data/sample_base.tfm
118

    
119
# simulates standard ICP
120
this simulates standard ICP on the same data:
121
./test_gicp data/outdoor/outdoor0\[300x541\].ascii data/outdoor/outdoor2\[300x541\].ascii --t_base data/sample_base.tfm --epsilon 1.
122

    
123

    
124

    
125
OUTPUT
126
======
127
final output will be formatted like this:
128

    
129
t_base:
130
   1.000    0.000    0.000    0.000 
131
   0.000    1.000    0.000    0.000 
132
   0.000    0.000    1.000    0.000 
133
   0.000    0.000    0.000    1.000 
134
t0:
135
   1.000    0.000    0.000    0.000 
136
   0.000    1.000    0.000    0.000 
137
   0.000    0.000    1.000    0.000 
138
   0.000    0.000    0.000    1.000 
139
t1:
140
   0.707   -0.707    0.000   -2.854 
141
   0.707    0.707   -0.000   -3.142 
142
   0.000    0.000    1.000   -0.513 
143
   0.000    0.000    0.000    1.000 
144

    
145

    
146
t_base is the base transformation read as input (or defaults to identity)
147
t0 is the initial value of the transformation before optimization
148
t1 is the final converged value.
149

    
150
based on this output, scan2 ~= t1(t_base(scan1))