RVOSimulator.h
Go to the documentation of this file.
1 /*
2  * RVOSimulator.h
3  * RVO2-3D Library
4  *
5  * Copyright 2008 University of North Carolina at Chapel Hill
6  *
7  * Licensed under the Apache License, Version 2.0 (the "License");
8  * you may not use this file except in compliance with the License.
9  * You may obtain a copy of the License at
10  *
11  * http://www.apache.org/licenses/LICENSE-2.0
12  *
13  * Unless required by applicable law or agreed to in writing, software
14  * distributed under the License is distributed on an "AS IS" BASIS,
15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16  * See the License for the specific language governing permissions and
17  * limitations under the License.
18  *
19  * Please send all bug reports to <geom@cs.unc.edu>.
20  *
21  * The authors may be contacted via:
22  *
23  * Jur van den Berg, Stephen J. Guy, Jamie Snape, Ming C. Lin, Dinesh Manocha
24  * Dept. of Computer Science
25  * 201 S. Columbia St.
26  * Frederick P. Brooks, Jr. Computer Science Bldg.
27  * Chapel Hill, N.C. 27599-3175
28  * United States of America
29  *
30  * <http://gamma.cs.unc.edu/RVO2/>
31  */
32 
33 /**
34  * \file RVOSimulator.h
35  * \brief Contains the RVOSimulator class.
36  */
37 #ifndef RVO_RVO_SIMULATOR_H_
38 #define RVO_RVO_SIMULATOR_H_
39 
40 #include "API.h"
41 
42 #include <cstddef>
43 #include <limits>
44 #include <vector>
45 
46 #include "Vector3.h"
47 
48 namespace RVO {
49  class Agent;
50  class KdTree;
51 
52  /**
53  * \brief Error value.
54  *
55  * A value equal to the largest unsigned integer, which is returned in case of an error by functions in RVO::RVOSimulator.
56  */
57  const size_t RVO_ERROR = std::numeric_limits<size_t>::max();
58 
59  /**
60  * \brief Defines a plane.
61  */
62  class Plane {
63  public:
64  /**
65  * \brief A point on the plane.
66  */
68 
69  /**
70  * \brief The normal to the plane.
71  */
73  };
74 
75  /**
76  * \brief Defines the simulation.
77  *
78  * The main class of the library that contains all simulation functionality.
79  */
80  class RVOSimulator {
81  public:
82  /**
83  * \brief Constructs a simulator instance.
84  */
85  RVO_API RVOSimulator();
86 
87  /**
88  * \brief Constructs a simulator instance and sets the default properties for any new agent that is added.
89  * \param timeStep The time step of the simulation. Must be positive.
90  * \param neighborDist The default maximum distance (center point to center point) to other agents a new agent takes into account in the navigation. The larger this number, the longer he running time of the simulation. If the number is too low, the simulation will not be safe. Must be non-negative.
91  * \param maxNeighbors The default maximum number of other agents a new agent takes into account in the navigation. The larger this number, the longer the running time of the simulation. If the number is too low, the simulation will not be safe.
92  * \param timeHorizon The default minimum amount of time for which a new agent's velocities that are computed by the simulation are safe with respect to other agents. The larger this number, the sooner an agent will respond to the presence of other agents, but the less freedom the agent has in choosing its velocities. Must be positive.
93  * \param radius The default radius of a new agent. Must be non-negative.
94  * \param maxSpeed The default maximum speed of a new agent. Must be non-negative.
95  * \param velocity The default initial three-dimensional linear velocity of a new agent (optional).
96  */
97  RVO_API RVOSimulator(float timeStep, float neighborDist, size_t maxNeighbors, float timeHorizon, float radius, float maxSpeed, const Vector3 &velocity = Vector3());
98 
99  /**
100  * \brief Destroys this simulator instance.
101  */
102  RVO_API ~RVOSimulator();
103 
104  /**
105  * \brief Adds a new agent with default properties to the simulation.
106  * \param position The three-dimensional starting position of this agent.
107  * \return The number of the agent, or RVO::RVO_ERROR when the agent defaults have not been set.
108  */
109  RVO_API size_t addAgent(const Vector3 &position);
110 
111  /**
112  * \brief Adds a new agent to the simulation.
113  * \param position The three-dimensional starting position of this agent.
114  * \param neighborDist The maximum distance (center point to center point) to other agents this agent takes into account in the navigation. The larger this number, the longer the running time of the simulation. If the number is too low, the simulation will not be safe. Must be non-negative.
115  * \param maxNeighbors The maximum number of other agents this agent takes into account in the navigation. The larger this number, the longer the running time of the simulation. If the number is too low, the simulation will not be safe.
116  * \param timeHorizon The minimum amount of time for which this agent's velocities that are computed by the simulation are safe with respect to other agents. The larger this number, the sooner this agent will respond to the presence of other agents, but the less freedom this agent has in choosing its velocities. Must be positive.
117  * \param radius The radius of this agent. Must be non-negative.
118  * \param maxSpeed The maximum speed of this agent. Must be non-negative.
119  * \param velocity The initial three-dimensional linear velocity of this agent (optional).
120  * \return The number of the agent.
121  */
122  RVO_API size_t addAgent(const Vector3 &position, float neighborDist, size_t maxNeighbors, float timeHorizon, float radius, float maxSpeed, const Vector3 &velocity = Vector3());
123 
124  /**
125  * \brief Lets the simulator perform a simulation step and updates the three-dimensional position and three-dimensional velocity of each agent.
126  */
127  RVO_API void doStep();
128 
129  /**
130  * \brief Returns the specified agent neighbor of the specified agent.
131  * \param agentNo The number of the agent whose agent neighbor is to be retrieved.
132  * \param neighborNo The number of the agent neighbor to be retrieved.
133  * \return The number of the neighboring agent.
134  */
135  RVO_API size_t getAgentAgentNeighbor(size_t agentNo, size_t neighborNo) const;
136 
137  /**
138  * \brief Returns the maximum neighbor count of a specified agent.
139  * \param agentNo The number of the agent whose maximum neighbor count is to be retrieved.
140  * \return The present maximum neighbor count of the agent.
141  */
142  RVO_API size_t getAgentMaxNeighbors(size_t agentNo) const;
143 
144  /**
145  * \brief Returns the maximum speed of a specified agent.
146  * \param agentNo The number of the agent whose maximum speed is to be retrieved.
147  * \return The present maximum speed of the agent.
148  */
149  RVO_API float getAgentMaxSpeed(size_t agentNo) const;
150 
151  /**
152  * \brief Returns the maximum neighbor distance of a specified agent.
153  * \param agentNo The number of the agent whose maximum neighbor distance is to be retrieved.
154  * \return The present maximum neighbor distance of the agent.
155  */
156  RVO_API float getAgentNeighborDist(size_t agentNo) const;
157 
158  /**
159  * \brief Returns the count of agent neighbors taken into account to compute the current velocity for the specified agent.
160  * \param agentNo The number of the agent whose count of agent neighbors is to be retrieved.
161  * \return The count of agent neighbors taken into account to compute the current velocity for the specified agent.
162  */
163  RVO_API size_t getAgentNumAgentNeighbors(size_t agentNo) const;
164 
165  /**
166  * \brief Returns the count of ORCA constraints used to compute the current velocity for the specified agent.
167  * \param agentNo The number of the agent whose count of ORCA constraints is to be retrieved.
168  * \return The count of ORCA constraints used to compute the current velocity for the specified agent.
169  */
170  RVO_API size_t getAgentNumORCAPlanes(size_t agentNo) const;
171 
172  /**
173  * \brief Returns the specified ORCA constraint of the specified agent.
174  * \param agentNo The number of the agent whose ORCA constraint is to be retrieved.
175  * \param planeNo The number of the ORCA constraint to be retrieved.
176  * \return A plane representing the specified ORCA constraint.
177  * \note The halfspace to which the normal of the plane points is the region of permissible velocities with respect to the specified ORCA constraint.
178  */
179  RVO_API const Plane &getAgentORCAPlane(size_t agentNo, size_t planeNo) const;
180 
181  /**
182  * \brief Returns the three-dimensional position of a specified agent.
183  * \param agentNo The number of the agent whose three-dimensional position is to be retrieved.
184  * \return The present three-dimensional position of the (center of the) agent.
185  */
186  RVO_API const Vector3 &getAgentPosition(size_t agentNo) const;
187 
188  /**
189  * \brief Returns the three-dimensional preferred velocity of a specified agent.
190  * \param agentNo The number of the agent whose three-dimensional preferred velocity is to be retrieved.
191  * \return The present three-dimensional preferred velocity of the agent.
192  */
193  RVO_API const Vector3 &getAgentPrefVelocity(size_t agentNo) const;
194 
195  /**
196  * \brief Returns the radius of a specified agent.
197  * \param agentNo The number of the agent whose radius is to be retrieved.
198  * \return The present radius of the agent.
199  */
200  RVO_API float getAgentRadius(size_t agentNo) const;
201 
202  /**
203  * \brief Returns the time horizon of a specified agent.
204  * \param agentNo The number of the agent whose time horizon is to be retrieved.
205  * \return The present time horizon of the agent.
206  */
207  RVO_API float getAgentTimeHorizon(size_t agentNo) const;
208 
209  /**
210  * \brief Returns the three-dimensional linear velocity of a specified agent.
211  * \param agentNo The number of the agent whose three-dimensional linear velocity is to be retrieved.
212  * \return The present three-dimensional linear velocity of the agent.
213  */
214  RVO_API const Vector3 &getAgentVelocity(size_t agentNo) const;
215 
216  /**
217  * \brief Returns the global time of the simulation.
218  * \return The present global time of the simulation (zero initially).
219  */
220  RVO_API float getGlobalTime() const;
221 
222  /**
223  * \brief Returns the count of agents in the simulation.
224  * \return The count of agents in the simulation.
225  */
226  RVO_API size_t getNumAgents() const;
227 
228  /**
229  * \brief Returns the time step of the simulation.
230  * \return The present time step of the simulation.
231  */
232  RVO_API float getTimeStep() const;
233 
234  /**
235  * \brief Removes an agent from the simulation.
236  * \param agentNo The number of the agent that is to be removed.
237  * \note After the removal of the agent, the agent that previously had number getNumAgents() - 1 will now have number agentNo.
238  */
239  RVO_API void removeAgent(size_t agentNo);
240 
241  /**
242  * \brief Sets the default properties for any new agent that is added.
243  * \param neighborDist The default maximum distance (center point to center point) to other agents a new agent takes into account in the navigation. The larger this number, the longer he running time of the simulation. If the number is too low, the simulation will not be safe. Must be non-negative.
244  * \param maxNeighbors The default maximum number of other agents a new agent takes into account in the navigation. The larger this number, the longer the running time of the simulation. If the number is too low, the simulation will not be safe.
245  * \param timeHorizon The default minimum amount of time for which a new agent's velocities that are computed by the simulation are safe with respect to other agents. The larger this number, the sooner an agent will respond to the presence of other agents, but the less freedom the agent has in choosing its velocities. Must be positive.
246  * \param radius The default radius of a new agent. Must be non-negative.
247  * \param maxSpeed The default maximum speed of a new agent. Must be non-negative.
248  * \param velocity The default initial three-dimensional linear velocity of a new agent (optional).
249  */
250  RVO_API void setAgentDefaults(float neighborDist, size_t maxNeighbors, float timeHorizon, float radius, float maxSpeed, const Vector3 &velocity = Vector3());
251 
252  /**
253  * \brief Sets the maximum neighbor count of a specified agent.
254  * \param agentNo The number of the agent whose maximum neighbor count is to be modified.
255  * \param maxNeighbors The replacement maximum neighbor count.
256  */
257  RVO_API void setAgentMaxNeighbors(size_t agentNo, size_t maxNeighbors);
258 
259  /**
260  * \brief Sets the maximum speed of a specified agent.
261  * \param agentNo The number of the agent whose maximum speed is to be modified.
262  * \param maxSpeed The replacement maximum speed. Must be non-negative.
263  */
264  RVO_API void setAgentMaxSpeed(size_t agentNo, float maxSpeed);
265 
266  /**
267  * \brief Sets the maximum neighbor distance of a specified agent.
268  * \param agentNo The number of the agent whose maximum neighbor distance is to be modified.
269  * \param neighborDist The replacement maximum neighbor distance. Must be non-negative.
270  */
271  RVO_API void setAgentNeighborDist(size_t agentNo, float neighborDist);
272 
273  /**
274  * \brief Sets the three-dimensional position of a specified agent.
275  * \param agentNo The number of the agent whose three-dimensional position is to be modified.
276  * \param position The replacement of the three-dimensional position.
277  */
278  RVO_API void setAgentPosition(size_t agentNo, const Vector3 &position);
279 
280  /**
281  * \brief Sets the three-dimensional preferred velocity of a specified agent.
282  * \param agentNo The number of the agent whose three-dimensional preferred velocity is to be modified.
283  * \param prefVelocity The replacement of the three-dimensional preferred velocity.
284  */
285  RVO_API void setAgentPrefVelocity(size_t agentNo, const Vector3 &prefVelocity);
286 
287  /**
288  * \brief Sets the radius of a specified agent.
289  * \param agentNo The number of the agent whose radius is to be modified.
290  * \param radius The replacement radius. Must be non-negative.
291  */
292  RVO_API void setAgentRadius(size_t agentNo, float radius);
293 
294  /**
295  * \brief Sets the time horizon of a specified agent with respect to other agents.
296  * \param agentNo The number of the agent whose time horizon is to be modified.
297  * \param timeHorizon The replacement time horizon with respect to other agents. Must be positive.
298  */
299  RVO_API void setAgentTimeHorizon(size_t agentNo, float timeHorizon);
300 
301  /**
302  * \brief Sets the three-dimensional linear velocity of a specified agent.
303  * \param agentNo The number of the agent whose three-dimensional linear velocity is to be modified.
304  * \param velocity The replacement three-dimensional linear velocity.
305  */
306  RVO_API void setAgentVelocity(size_t agentNo, const Vector3 &velocity);
307 
308  /**
309  * \brief Sets the time step of the simulation.
310  * \param timeStep The time step of the simulation. Must be positive.
311  */
312  RVO_API void setTimeStep(float timeStep);
313 
314  private:
315  Agent *defaultAgent_;
316  KdTree *kdTree_;
317  float globalTime_;
318  float timeStep_;
319  std::vector<Agent *> agents_;
320 
321  friend class Agent;
322  friend class KdTree;
323  };
324 }
325 
326 #endif
RVO_API void setAgentRadius(size_t agentNo, float radius)
Sets the radius of a specified agent.
RVO_API size_t getAgentAgentNeighbor(size_t agentNo, size_t neighborNo) const
Returns the specified agent neighbor of the specified agent.
RVO_API size_t getAgentNumAgentNeighbors(size_t agentNo) const
Returns the count of agent neighbors taken into account to compute the current velocity for the speci...
RVO_API void setAgentDefaults(float neighborDist, size_t maxNeighbors, float timeHorizon, float radius, float maxSpeed, const Vector3 &velocity=Vector3())
Sets the default properties for any new agent that is added.
RVO_API const Vector3 & getAgentVelocity(size_t agentNo) const
Returns the three-dimensional linear velocity of a specified agent.
RVO_API void setAgentMaxNeighbors(size_t agentNo, size_t maxNeighbors)
Sets the maximum neighbor count of a specified agent.
Defines a plane.
Definition: RVOSimulator.h:62
RVO_API void setAgentPosition(size_t agentNo, const Vector3 &position)
Sets the three-dimensional position of a specified agent.
RVO_API size_t getNumAgents() const
Returns the count of agents in the simulation.
RVO_API float getAgentTimeHorizon(size_t agentNo) const
Returns the time horizon of a specified agent.
Vector3 normal
The normal to the plane.
Definition: RVOSimulator.h:72
RVO_API float getAgentRadius(size_t agentNo) const
Returns the radius of a specified agent.
RVO_API size_t getAgentNumORCAPlanes(size_t agentNo) const
Returns the count of ORCA constraints used to compute the current velocity for the specified agent...
RVO_API void setAgentMaxSpeed(size_t agentNo, float maxSpeed)
Sets the maximum speed of a specified agent.
RVO_API size_t addAgent(const Vector3 &position, float neighborDist, size_t maxNeighbors, float timeHorizon, float radius, float maxSpeed, const Vector3 &velocity=Vector3())
Adds a new agent to the simulation.
const size_t RVO_ERROR
Error value.
Definition: RVOSimulator.h:57
RVO_API void doStep()
Lets the simulator perform a simulation step and updates the three-dimensional position and three-dim...
RVO_API size_t getAgentMaxNeighbors(size_t agentNo) const
Returns the maximum neighbor count of a specified agent.
RVO_API size_t addAgent(const Vector3 &position)
Adds a new agent with default properties to the simulation.
RVO_API RVOSimulator()
Constructs a simulator instance.
friend class KdTree
Definition: RVOSimulator.h:322
Vector3 point
A point on the plane.
Definition: RVOSimulator.h:67
RVO_API RVOSimulator(float timeStep, float neighborDist, size_t maxNeighbors, float timeHorizon, float radius, float maxSpeed, const Vector3 &velocity=Vector3())
Constructs a simulator instance and sets the default properties for any new agent that is added...
RVO_API Vector3()
Constructs and initializes a three-dimensional vector instance to zero.
Definition: Vector3.h:55
RVO_API ~RVOSimulator()
Destroys this simulator instance.
RVO_API void setAgentTimeHorizon(size_t agentNo, float timeHorizon)
Sets the time horizon of a specified agent with respect to other agents.
RVO_API const Plane & getAgentORCAPlane(size_t agentNo, size_t planeNo) const
Returns the specified ORCA constraint of the specified agent.
RVO_API void setTimeStep(float timeStep)
Sets the time step of the simulation.
RVO_API void setAgentPrefVelocity(size_t agentNo, const Vector3 &prefVelocity)
Sets the three-dimensional preferred velocity of a specified agent.
RVO_API const Vector3 & getAgentPrefVelocity(size_t agentNo) const
Returns the three-dimensional preferred velocity of a specified agent.
Defines the simulation.
Definition: RVOSimulator.h:80
RVO_API void removeAgent(size_t agentNo)
Removes an agent from the simulation.
RVO_API void setAgentVelocity(size_t agentNo, const Vector3 &velocity)
Sets the three-dimensional linear velocity of a specified agent.
RVO_API float getTimeStep() const
Returns the time step of the simulation.
RVO_API void setAgentNeighborDist(size_t agentNo, float neighborDist)
Sets the maximum neighbor distance of a specified agent.
RVO_API float getGlobalTime() const
Returns the global time of the simulation.
RVO_API float getAgentMaxSpeed(size_t agentNo) const
Returns the maximum speed of a specified agent.
RVO_API const Vector3 & getAgentPosition(size_t agentNo) const
Returns the three-dimensional position of a specified agent.
Defines a three-dimensional vector.
Definition: Vector3.h:50
RVO_API float getAgentNeighborDist(size_t agentNo) const
Returns the maximum neighbor distance of a specified agent.