1 /*********************************************************************
2 * Software License Agreement (BSD License)
3 *
4 *  Copyright (c) 2010, Rice University
5 *  All rights reserved.
6 *
7 *  Redistribution and use in source and binary forms, with or without
8 *  modification, are permitted provided that the following conditions
9 *  are met:
10 *
11 *   * Redistributions of source code must retain the above copyright
12 *     notice, this list of conditions and the following disclaimer.
13 *   * Redistributions in binary form must reproduce the above
14 *     copyright notice, this list of conditions and the following
15 *     disclaimer in the documentation and/or other materials provided
16 *     with the distribution.
17 *   * Neither the name of the Rice University nor the names of its
18 *     contributors may be used to endorse or promote products derived
19 *     from this software without specific prior written permission.
20 *
21 *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
22 *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
23 *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
24 *  FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
25 *  COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
26 *  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
27 *  BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
28 *  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
29 *  CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30 *  LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
31 *  ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
32 *  POSSIBILITY OF SUCH DAMAGE.
33 *********************************************************************/
34 
35 /* Author: Ioan Sucan */
36 
37 #ifndef OMPL_BASE_VALID_STATE_SAMPLER_
38 #define OMPL_BASE_VALID_STATE_SAMPLER_
39 
40 #include "ompl/base/State.h"
41 #include "ompl/util/ClassForward.h"
42 #include "ompl/base/GenericParam.h"
43 #include <string>
44 
45 namespace ompl
46 {
47     namespace base
48     {
49         /// @cond IGNORE
50         OMPL_CLASS_FORWARD(SpaceInformation);
51         /// @endcond
52 
53         /// @cond IGNORE
54         /** \brief Forward declaration of ompl::base::ValidStateSampler */
55         OMPL_CLASS_FORWARD(ValidStateSampler);
56         /// @endcond
57 
58         /** \class ompl::base::ValidStateSamplerPtr
59             \brief A shared pointer wrapper for ompl::base::ValidStateSampler */
60 
61         /** \brief Abstract definition of a state sampler. */
62         class ValidStateSampler
63         {
64         public:
65             // non-copyable
66             ValidStateSampler(const ValidStateSampler &) = delete;
67             ValidStateSampler &operator=(const ValidStateSampler &) = delete;
68 
69             /** \brief Constructor */
70             ValidStateSampler(const SpaceInformation *si);
71 
72             virtual ~ValidStateSampler();
73 
74             /** \brief Get the name of the sampler */
getName()75             const std::string &getName() const
76             {
77                 return name_;
78             }
79 
80             /** \brief Set the name of the sampler */
setName(const std::string & name)81             void setName(const std::string &name)
82             {
83                 name_ = name;
84             }
85 
86             /** \brief Sample a state. Return false in case of failure */
87             virtual bool sample(State *state) = 0;
88 
89             /** \brief Sample a state near another, within specified distance. Return false, in case of failure.
90                 \note The memory for \e near must be disjoint from the memory for \e state */
91             virtual bool sampleNear(State *state, const State *near, double distance) = 0;
92 
93             /** \brief Finding a valid sample usually requires
94                 performing multiple attempts. This call allows setting
95                 the number of such attempts. */
setNrAttempts(unsigned int attempts)96             void setNrAttempts(unsigned int attempts)
97             {
98                 attempts_ = attempts;
99             }
100 
101             /** \brief Get the number of attempts to be performed by the sampling routine */
getNrAttempts()102             unsigned int getNrAttempts() const
103             {
104                 return attempts_;
105             }
106 
107             /** \brief Get the parameters for the valid state sampler */
params()108             ParamSet &params()
109             {
110                 return params_;
111             }
112 
113             /** \brief Get the parameters for the valid state sampler */
params()114             const ParamSet &params() const
115             {
116                 return params_;
117             }
118 
119         protected:
120             /** \brief The state space this sampler samples */
121             const SpaceInformation *si_;
122 
123             /** \brief Number of attempts to find a valid sample */
124             unsigned int attempts_;
125 
126             /** \brief The name of the sampler */
127             std::string name_;
128 
129             /** \brief The parameters for this instance of the valid state sampler */
130             ParamSet params_;
131         };
132 
133         /** \brief Definition of a function that can allocate a valid state sampler */
134         using ValidStateSamplerAllocator = std::function<ValidStateSamplerPtr(const SpaceInformation *)>;
135     }
136 }
137 
138 #endif
139