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 RVO3D_RVO_SIMULATOR_H_
38#define RVO3D_RVO_SIMULATOR_H_
39
40#include <cstddef>
41#include <limits>
42#include <vector>
43
44#include "Vector3.h"
45
46namespace RVO3D {
47 class Agent3D;
48 class KdTree3D;
49
50 /**
51 * \brief Error value.
52 *
53 * A value equal to the largest unsigned integer, which is returned in case of an error by functions in RVO3D::RVOSimulator.
54 */
55 const size_t RVO3D_ERROR = std::numeric_limits<size_t>::max();
56
57 /**
58 * \brief Defines a plane.
59 */
60 class Plane {
61 public:
62 /**
63 * \brief A point on the plane.
64 */
65 Vector3 point;
66
67 /**
68 * \brief The normal to the plane.
69 */
70 Vector3 normal;
71 };
72
73 /**
74 * \brief Defines the simulation.
75 *
76 * The main class of the library that contains all simulation functionality.
77 */
78 class RVOSimulator3D {
79 public:
80 /**
81 * \brief Constructs a simulator instance.
82 */
83 RVOSimulator3D();
84
85 /**
86 * \brief Constructs a simulator instance and sets the default properties for any new agent that is added.
87 * \param timeStep The time step of the simulation. Must be positive.
88 * \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.
89 * \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.
90 * \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.
91 * \param radius The default radius of a new agent. Must be non-negative.
92 * \param maxSpeed The default maximum speed of a new agent. Must be non-negative.
93 * \param velocity The default initial three-dimensional linear velocity of a new agent (optional).
94 */
95 RVOSimulator3D(float timeStep, float neighborDist, size_t maxNeighbors, float timeHorizon, float radius, float maxSpeed, const Vector3 &velocity = Vector3());
96
97 /**
98 * \brief Destroys this simulator instance.
99 */
100 ~RVOSimulator3D();
101
102 /**
103 * \brief Adds a new agent with default properties to the simulation.
104 * \param position The three-dimensional starting position of this agent.
105 * \return The number of the agent, or RVO3D::RVO3D_ERROR when the agent defaults have not been set.
106 */
107 size_t addAgent(const Vector3 &position);
108
109 /**
110 * \brief Adds a new agent to the simulation.
111 * \param position The three-dimensional starting position of this agent.
112 * \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.
113 * \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.
114 * \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.
115 * \param radius The radius of this agent. Must be non-negative.
116 * \param maxSpeed The maximum speed of this agent. Must be non-negative.
117 * \param velocity The initial three-dimensional linear velocity of this agent (optional).
118 * \return The number of the agent.
119 */
120 size_t addAgent(const Vector3 &position, float neighborDist, size_t maxNeighbors, float timeHorizon, float radius, float maxSpeed, const Vector3 &velocity = Vector3());
121
122 /**
123 * \brief Lets the simulator perform a simulation step and updates the three-dimensional position and three-dimensional velocity of each agent.
124 */
125 void doStep();
126
127 /**
128 * \brief Returns the specified agent neighbor of the specified agent.
129 * \param agentNo The number of the agent whose agent neighbor is to be retrieved.
130 * \param neighborNo The number of the agent neighbor to be retrieved.
131 * \return The number of the neighboring agent.
132 */
133 size_t getAgentAgentNeighbor(size_t agentNo, size_t neighborNo) const;
134
135 /**
136 * \brief Returns the maximum neighbor count of a specified agent.
137 * \param agentNo The number of the agent whose maximum neighbor count is to be retrieved.
138 * \return The present maximum neighbor count of the agent.
139 */
140 size_t getAgentMaxNeighbors(size_t agentNo) const;
141
142 /**
143 * \brief Returns the maximum speed of a specified agent.
144 * \param agentNo The number of the agent whose maximum speed is to be retrieved.
145 * \return The present maximum speed of the agent.
146 */
147 float getAgentMaxSpeed(size_t agentNo) const;
148
149 /**
150 * \brief Returns the maximum neighbor distance of a specified agent.
151 * \param agentNo The number of the agent whose maximum neighbor distance is to be retrieved.
152 * \return The present maximum neighbor distance of the agent.
153 */
154 float getAgentNeighborDist(size_t agentNo) const;
155
156 /**
157 * \brief Returns the count of agent neighbors taken into account to compute the current velocity for the specified agent.
158 * \param agentNo The number of the agent whose count of agent neighbors is to be retrieved.
159 * \return The count of agent neighbors taken into account to compute the current velocity for the specified agent.
160 */
161 size_t getAgentNumAgentNeighbors(size_t agentNo) const;
162
163 /**
164 * \brief Returns the count of ORCA constraints used to compute the current velocity for the specified agent.
165 * \param agentNo The number of the agent whose count of ORCA constraints is to be retrieved.
166 * \return The count of ORCA constraints used to compute the current velocity for the specified agent.
167 */
168 size_t getAgentNumORCAPlanes(size_t agentNo) const;
169
170 /**
171 * \brief Returns the specified ORCA constraint of the specified agent.
172 * \param agentNo The number of the agent whose ORCA constraint is to be retrieved.
173 * \param planeNo The number of the ORCA constraint to be retrieved.
174 * \return A plane representing the specified ORCA constraint.
175 * \note The halfspace to which the normal of the plane points is the region of permissible velocities with respect to the specified ORCA constraint.
176 */
177 const Plane &getAgentORCAPlane(size_t agentNo, size_t planeNo) const;
178
179 /**
180 * \brief Returns the three-dimensional position of a specified agent.
181 * \param agentNo The number of the agent whose three-dimensional position is to be retrieved.
182 * \return The present three-dimensional position of the (center of the) agent.
183 */
184 const Vector3 &getAgentPosition(size_t agentNo) const;
185
186 /**
187 * \brief Returns the three-dimensional preferred velocity of a specified agent.
188 * \param agentNo The number of the agent whose three-dimensional preferred velocity is to be retrieved.
189 * \return The present three-dimensional preferred velocity of the agent.
190 */
191 const Vector3 &getAgentPrefVelocity(size_t agentNo) const;
192
193 /**
194 * \brief Returns the radius of a specified agent.
195 * \param agentNo The number of the agent whose radius is to be retrieved.
196 * \return The present radius of the agent.
197 */
198 float getAgentRadius(size_t agentNo) const;
199
200 /**
201 * \brief Returns the time horizon of a specified agent.
202 * \param agentNo The number of the agent whose time horizon is to be retrieved.
203 * \return The present time horizon of the agent.
204 */
205 float getAgentTimeHorizon(size_t agentNo) const;
206
207 /**
208 * \brief Returns the three-dimensional linear velocity of a specified agent.
209 * \param agentNo The number of the agent whose three-dimensional linear velocity is to be retrieved.
210 * \return The present three-dimensional linear velocity of the agent.
211 */
212 const Vector3 &getAgentVelocity(size_t agentNo) const;
213
214 /**
215 * \brief Returns the global time of the simulation.
216 * \return The present global time of the simulation (zero initially).
217 */
218 float getGlobalTime() const;
219
220 /**
221 * \brief Returns the count of agents in the simulation.
222 * \return The count of agents in the simulation.
223 */
224 size_t getNumAgents() const;
225
226 /**
227 * \brief Returns the time step of the simulation.
228 * \return The present time step of the simulation.
229 */
230 float getTimeStep() const;
231
232 /**
233 * \brief Removes an agent from the simulation.
234 * \param agentNo The number of the agent that is to be removed.
235 * \note After the removal of the agent, the agent that previously had number getNumAgents() - 1 will now have number agentNo.
236 */
237 void removeAgent(size_t agentNo);
238
239 /**
240 * \brief Sets the default properties for any new agent that is added.
241 * \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.
242 * \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.
243 * \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.
244 * \param radius The default radius of a new agent. Must be non-negative.
245 * \param maxSpeed The default maximum speed of a new agent. Must be non-negative.
246 * \param velocity The default initial three-dimensional linear velocity of a new agent (optional).
247 */
248 void setAgentDefaults(float neighborDist, size_t maxNeighbors, float timeHorizon, float radius, float maxSpeed, const Vector3 &velocity = Vector3());
249
250 /**
251 * \brief Sets the maximum neighbor count of a specified agent.
252 * \param agentNo The number of the agent whose maximum neighbor count is to be modified.
253 * \param maxNeighbors The replacement maximum neighbor count.
254 */
255 void setAgentMaxNeighbors(size_t agentNo, size_t maxNeighbors);
256
257 /**
258 * \brief Sets the maximum speed of a specified agent.
259 * \param agentNo The number of the agent whose maximum speed is to be modified.
260 * \param maxSpeed The replacement maximum speed. Must be non-negative.
261 */
262 void setAgentMaxSpeed(size_t agentNo, float maxSpeed);
263
264 /**
265 * \brief Sets the maximum neighbor distance of a specified agent.
266 * \param agentNo The number of the agent whose maximum neighbor distance is to be modified.
267 * \param neighborDist The replacement maximum neighbor distance. Must be non-negative.
268 */
269 void setAgentNeighborDist(size_t agentNo, float neighborDist);
270
271 /**
272 * \brief Sets the three-dimensional position of a specified agent.
273 * \param agentNo The number of the agent whose three-dimensional position is to be modified.
274 * \param position The replacement of the three-dimensional position.
275 */
276 void setAgentPosition(size_t agentNo, const Vector3 &position);
277
278 /**
279 * \brief Sets the three-dimensional preferred velocity of a specified agent.
280 * \param agentNo The number of the agent whose three-dimensional preferred velocity is to be modified.
281 * \param prefVelocity The replacement of the three-dimensional preferred velocity.
282 */
283 void setAgentPrefVelocity(size_t agentNo, const Vector3 &prefVelocity);
284
285 /**
286 * \brief Sets the radius of a specified agent.
287 * \param agentNo The number of the agent whose radius is to be modified.
288 * \param radius The replacement radius. Must be non-negative.
289 */
290 void setAgentRadius(size_t agentNo, float radius);
291
292 /**
293 * \brief Sets the time horizon of a specified agent with respect to other agents.
294 * \param agentNo The number of the agent whose time horizon is to be modified.
295 * \param timeHorizon The replacement time horizon with respect to other agents. Must be positive.
296 */
297 void setAgentTimeHorizon(size_t agentNo, float timeHorizon);
298
299 /**
300 * \brief Sets the three-dimensional linear velocity of a specified agent.
301 * \param agentNo The number of the agent whose three-dimensional linear velocity is to be modified.
302 * \param velocity The replacement three-dimensional linear velocity.
303 */
304 void setAgentVelocity(size_t agentNo, const Vector3 &velocity);
305
306 /**
307 * \brief Sets the time step of the simulation.
308 * \param timeStep The time step of the simulation. Must be positive.
309 */
310 void setTimeStep(float timeStep);
311
312 public:
313 Agent3D *defaultAgent_;
314 KdTree3D *kdTree_;
315 float globalTime_;
316 float timeStep_;
317 std::vector<Agent3D *> agents_;
318
319 friend class Agent3D;
320 friend class KdTree3D;
321 };
322}
323
324#endif
325