automatic commit
[pom.git] / README.txt
1
2 INTRODUCTION
3 ------------
4
5   The Probabilistic Occupancy Map is a procedure which estimates the
6   marginal probabilities of presence of individuals at every location
7   in an area of interest under a simple appearance model, given binary
8   images corresponding to the result of a background-subtraction from
9   different viewpoints.
10
11   The appearance model is parametrized by a family of rectangles which
12   approximate the silhouettes of individuals standing at every
13   location of interest, from every point of view.
14
15 INSTALLATION AND TEST
16 ---------------------
17
18   This program should compile by typing `make' on any standard
19   GNU/Linux system, as long as the libpng is installed with its header
20   files.
21
22   To run a simple test on the images provided in the archive just type
23
24     ./pom test.pom
25
26   It will generate several result files in the /tmp directory.
27
28   If the program is not provided with a filename, it will process the
29   standard input, but will not make any output.
30
31 CONFIGURATION FILE
32 ------------------
33
34   The configuration file contains the following keywords
35
36   ROOM <view width> <view height> <number of cameras> <number of locations>
37
38     Defines the input image size, the number of cameras and the number
39     of locations in the area of interest.
40
41   RECTANGLE <camera number> <location number> notvisible|<xmin> <ymin> <xmax> <ymax>
42
43     Defines the parameters of a certain rectangle, standing for an
44     individual at a certain location viewed from a certain camera. All
45     non-specified rectangles are "not visible" by default.
46
47   INPUT_VIEW_FORMAT <input image filename format>
48
49     Specifies the filenames of the input images produced by the
50     background subtraction. The immobile parts should be black (0, 0,
51     0) and the moving ones white (255, 255, 255). See FILENAME FORMAT
52     below.
53
54   RESULT_VIEW_FORMAT <result image filename format>
55
56     Specifies the filenames of the result images. See FILENAME FORMAT
57     below.
58
59   RESULT_FORMAT <result filename format>
60
61     Specifies the filenames of the result probability files, which
62     contains one marginal probability per line, hence as many lines as
63     there are locations of interest. See FILENAME FORMAT below.
64
65   CONVERGENCE_VIEW_FORMAT <convergence file name format>
66
67     Specifies the filenames of the images for individual iteration
68     during the convergence of the algorithm. Use with care, since tens
69     of images will be produced for every single frame.  See FILENAME
70     FORMAT below.
71
72   PRIOR
73
74     Sets the prior probability of presence (common to all
75     locations). Default is 0.01.
76
77   SIGMA_IMAGE_DENSITY
78
79     Sets the variance of the distance between the image produced by
80     the background subtraction and the ideal synthetic image. Default
81     is 0.01.
82
83   MAX_NB_SOLVER_ITERATIONS
84
85     Sets a bound on the number of iterations. Default is 100.
86
87   PROBA_IGNORED
88
89     Sets the probability of absence ignored by the solver to speed up
90     the convergence (use with care, it can produce false
91     positive). Default is 1.0
92
93   The file test.pom provided in the archive gives an example. Lines
94   starting with "#" are ignored.
95
96 FILENAME FORMAT
97 ---------------
98
99   Every filename format in the configuration file is a string with the
100   following three "conversion specifications":
101
102   %c camera number
103
104   %f frame number
105
106   %i iteration number
107
108   Some of these fields may be meaningless, depending with the
109   context. For instance the iteration number is defined only for
110   CONVERGENCE_VIEW_FORMAT.
111
112 REFERENCES
113 ----------
114
115   For more information about the POM algorithm, please check the
116   section V and appendix A of:
117
118     François Fleuret, Jérôme Berclaz, Richard Lengagne and Pascal Fua,
119     "Multi-Camera People Tracking with a Probabilistic Occupancy Map",
120     IEEE Transactions on Pattern Analysis and Machine Intelligence
121     (TPAMI), 2007, to be published.
122
123   This distributed version of the software is slightly slower than the
124   one described in the article, for which many values such as the
125   image size were hard-coded in the source to let the compiler
126   optimize the code.
127
128 LICENSE
129 -------
130
131   This source code is available under the terms of the version 3 of
132   the GNU General Public License as published by the Free Software
133   Foundation. In short: If you distribute a software that uses POM,
134   you have to distribute it under GPL version 3, hence with the source
135   code. Another option is to contact us to purchase a commercial
136   license.
137
138 CONTACT
139 -------
140
141   Please mail pom@epfl.ch for bug reports, comments and questions.