Main MRPT website > C++ reference
MRPT logo
CParticleFilter.h
Go to the documentation of this file.
1 /* +---------------------------------------------------------------------------+
2  | The Mobile Robot Programming Toolkit (MRPT) |
3  | |
4  | http://www.mrpt.org/ |
5  | |
6  | Copyright (c) 2005-2013, Individual contributors, see AUTHORS file |
7  | Copyright (c) 2005-2013, MAPIR group, University of Malaga |
8  | Copyright (c) 2012-2013, University of Almeria |
9  | All rights reserved. |
10  | |
11  | Redistribution and use in source and binary forms, with or without |
12  | modification, are permitted provided that the following conditions are |
13  | met: |
14  | * Redistributions of source code must retain the above copyright |
15  | notice, this list of conditions and the following disclaimer. |
16  | * Redistributions in binary form must reproduce the above copyright |
17  | notice, this list of conditions and the following disclaimer in the |
18  | documentation and/or other materials provided with the distribution. |
19  | * Neither the name of the copyright holders nor the |
20  | names of its contributors may be used to endorse or promote products |
21  | derived from this software without specific prior written permission.|
22  | |
23  | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS |
24  | 'AS IS' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED |
25  | TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR|
26  | PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE |
27  | FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL|
28  | DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR|
29  | SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) |
30  | HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, |
31  | STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN |
32  | ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE |
33  | POSSIBILITY OF SUCH DAMAGE. |
34  +---------------------------------------------------------------------------+ */
35 #ifndef CPARTICLEFILTER_H
36 #define CPARTICLEFILTER_H
37 
38 #include <mrpt/utils/utils_defs.h>
41 
42 namespace mrpt
43 {
44  namespace slam
45  {
46  class CActionCollection;
47  class CSensoryFrame;
48  }
49 
50  /** The namespace for Bayesian filtering algorithm: different particle filters and Kalman filter algorithms. \ingroup mrpt_base_grp
51  */
52  namespace bayes
53  {
55 
56  /** This class acts as a common interface to the different interfaces (see CParticleFilter::TParticleFilterAlgorithm) any bayes::CParticleFilterCapable class can implement: it is the invoker of particle filter algorithms.
57  * The particle filter is executed on a probability density function (PDF) described by a CParticleFilterCapable object, passed in the constructor or alternatively through the CParticleFilter::executeOn method.<br>
58  *
59  * For a complete example and further details, see the <a href="http://www.mrpt.org/Particle_Filter_Tutorial" >Particle Filter tutorial</a>.
60  *
61  * The basic SIR algorithm (pfStandardProposal) consists of:
62  * - Execute a prediction with the given "action".
63  * - Update the weights of the particles using the likelihood of the "observation".
64  * - Normalize weights.
65  * - Perform resampling if the ESS is below the threshold options.BETA.
66  *
67  * \ingroup mrpt_base_grp
68  * \sa mrpt::poses::CPoseParticlesPDF
69  */
71  {
72  public:
73 
74  /** Defines different types of particle filter algorithms.
75  * The defined SIR implementations are:
76  * - pfStandardProposal: Standard proposal distribution + weights according to likelihood function.
77  * - pfAuxiliaryPFStandard: An auxiliary PF using the standard proposal distribution.
78  * - pfOptimalProposal: Use the optimal proposal distribution (where available!, usually this will perform approximations)
79  * - pfAuxiliaryPFOptimal: Use the optimal proposal and a auxiliary particle filter (see <a href="http://www.mrpt.org/Paper:An_Optimal_Filtering_Algorithm_for_Non-Parametric_Observation_Models_in_Robot_Localization_(ICRA_2008)" >paper</a>).
80  *
81  * See the theoretical discussion in <a href="http://www.mrpt.org/Resampling_Schemes" >resampling schemes</a>.
82  */
84  {
85  pfStandardProposal = 0,
88  pfAuxiliaryPFOptimal
89  };
90 
91  /** Defines the different resampling algorithms.
92  * The implemented resampling methods are:
93  * - prMultinomial (Default): Uses standard select with replacement (draws M random uniform numbers)
94  * - prResidual: The residual or "remainder" method.
95  * - prStratified: The stratified resampling, where a uniform sample is drawn for each of M subdivisions of the range (0,1].
96  * - prSystematic: A single uniform sample is drawn in the range (0,1/M].
97  *
98  * See the theoretical discussion in <a href="http://www.mrpt.org/Resampling_Schemes" >resampling schemes</a>.
99  */
101  {
102  prMultinomial = 0,
105  prSystematic
106  };
107 
108  /** The configuration of a particle filter.
109  */
111  {
112  public:
113  /** Initilization of default parameters
114  */
116 
117  /** See mrpt::utils::CLoadableOptions
118  */
119  void loadFromConfigFile(
120  const mrpt::utils::CConfigFileBase &source,
121  const std::string &section);
122 
123  /** See mrpt::utils::CLoadableOptions
124  */
125  void dumpToTextStream(mrpt::utils::CStream &out) const;
126 
127  /** A flag that indicates whether the CParticleFilterCapable object should perform adative sample size (default=false).
128  */
130 
131  /** The resampling of particles will be performed when ESS (in range [0,1]) < BETA (default is 0.5)
132  */
133  double BETA;
134 
135  /** The initial number of particles in the filter (it can change only if adaptiveSampleSize=true) (default=1)
136  */
137  unsigned int sampleSize;
138 
139  /** In the algorithm "CParticleFilter::pfAuxiliaryPFOptimal" (and in "CParticleFilter::pfAuxiliaryPFStandard" only if pfAuxFilterStandard_FirstStageWeightsMonteCarlo = true) the number of samples for searching the maximum likelihood value and also to estimate the "first stage weights" (see papers!) (default=100)
140  */
142 
143  /** An optional step to "smooth" dramatic changes in the observation model to affect the variance of the particle weights, eg weight*=likelihood^powFactor (default=1 = no effects).
144  */
145  double powFactor;
146 
147  /** The PF algorithm to use (default=pfStandardProposal) See TParticleFilterAlgorithm for the posibilities.
148  */
150 
151  /** The resampling algorithm to use (default=prMultinomial).
152  */
154 
155 
156  /** Only for PF_algorithm=pfAuxiliaryPFOptimal: If a given particle has a max_likelihood (from the a-priori estimate) below the maximum from all the samples - max_loglikelihood_dyn_range, then the particle is directly discarded.
157  * This is done to assure that the rejection sampling doesn't get stuck in an infinite loop trying to get an acceptable sample.
158  * Default = 15 (in logarithmic likelihood)
159  */
161 
162  /** Only for PF_algorithm==pfAuxiliaryPFStandard:
163  * If false, the APF will predict the first stage weights just at the mean of the prior of the next time step.
164  * If true, these weights will be estimated as described in the papers for the "pfAuxiliaryPFOptimal" method, i.e. through a monte carlo simulation.
165  * In that case, "pfAuxFilterOptimal_MaximumSearchSamples" is the number of MC samples used.
166  */
168 
169  bool verbose; //!< Enable extra messages for each PF iteration (Default=false)
170 
171  /** (Default=false) In the algorithm "CParticleFilter::pfAuxiliaryPFOptimal", if set to true, do not perform rejection sampling, but just the most-likely (ML) particle found in the preliminary weight-determination stage.
172  */
174  };
175 
176 
177  /** Statistics for being returned from the "execute" method.
178  */
180  {
181  TParticleFilterStats() : ESS_beforeResample(0), weightsVariance_beforeResample (0) { }
184  };
185 
186  /** Default constructor.
187  * After creating the PF object, set the options in CParticleFilter::m_options, then execute steps through CParticleFilter::executeOn.
188  */
189  CParticleFilter( );
190 
191  virtual ~CParticleFilter() {}
192 
193  /** Executes a complete prediction + update step of the selected particle filtering algorithm.
194  * The member CParticleFilter::m_options must be set before calling this to settle the algorithm parameters.
195  *
196  * \param obj The object representing the probability distribution function (PDF) which apply the particle filter algorithm to.
197  * \param action A pointer to an action in the form of a CActionCollection, or NULL if there is no action.
198  * \param observation A pointer to observations in the form of a CSensoryFrame, or NULL if there is no observation.
199  * \param stats An output structure for gathering statistics of the particle filter execution, or set to NULL if you do not need it (see CParticleFilter::TParticleFilterStats).
200  *
201  * \sa CParticleFilterCapable, executeOn
202  */
203  void executeOn(
205  const mrpt::slam::CActionCollection *action,
206  const mrpt::slam::CSensoryFrame *observation,
207  TParticleFilterStats *stats = NULL);
208 
209 
210  /** The options to be used in the PF, must be set before executing any step of the particle filter.
211  */
213 
214  }; // End of class def.
215 
216  } // end namespace
217 } // end namespace
218 #endif
unsigned int pfAuxFilterOptimal_MaximumSearchSamples
In the algorithm "CParticleFilter::pfAuxiliaryPFOptimal" (and in "CParticleFilter::pfAuxiliaryPFStand...
Statistics for being returned from the "execute" method.
Declares a class for storing a collection of robot actions.
This class allows loading and storing values and vectors of different types from a configuration text...
This base class is used to provide a unified interface to files,memory buffers,..Please see the deriv...
Definition: CStream.h:62
TParticleResamplingAlgorithm
Defines the different resampling algorithms.
TParticleResamplingAlgorithm resamplingMethod
The resampling algorithm to use (default=prMultinomial).
This virtual class defines the interface that any particles based PDF class must implement in order t...
This class acts as a common interface to the different interfaces (see CParticleFilter::TParticleFilt...
bool pfAuxFilterStandard_FirstStageWeightsMonteCarlo
Only for PF_algorithm==pfAuxiliaryPFStandard: If false, the APF will predict the first stage weights ...
double BETA
The resampling of particles will be performed when ESS (in range [0,1]) < BETA (default is 0...
This is the global namespace for all Mobile Robot Programming Toolkit (MRPT) libraries.
TParticleFilterAlgorithm
Defines different types of particle filter algorithms.
bool verbose
Enable extra messages for each PF iteration (Default=false)
double max_loglikelihood_dyn_range
Only for PF_algorithm=pfAuxiliaryPFOptimal: If a given particle has a max_likelihood (from the a-prio...
Declares a class for storing a "sensory frame", a set of "observations" taken by the robot approximat...
Definition: CSensoryFrame.h:80
double powFactor
An optional step to "smooth" dramatic changes in the observation model to affect the variance of the ...
The configuration of a particle filter.
unsigned int sampleSize
The initial number of particles in the filter (it can change only if adaptiveSampleSize=true) (defaul...
bool pfAuxFilterOptimal_MLE
(Default=false) In the algorithm "CParticleFilter::pfAuxiliaryPFOptimal", if set to true...
CParticleFilter::TParticleFilterOptions m_options
The options to be used in the PF, must be set before executing any step of the particle filter...
This base class provides a common printf-like method to send debug information to std::cout...
TParticleFilterAlgorithm PF_algorithm
The PF algorithm to use (default=pfStandardProposal) See TParticleFilterAlgorithm for the posibilitie...
This is a virtual base class for sets of options than can be loaded from and/or saved to configuratio...
bool adaptiveSampleSize
A flag that indicates whether the CParticleFilterCapable object should perform adative sample size (d...



Page generated by Doxygen 1.8.14 for MRPT 1.0.2 SVN: at lun oct 28 00:52:41 CET 2019 Hosted on:
SourceForge.net Logo