54 (ORCA) formulation for multi-agent simulation in three dimensions. <b>RVO2-3D Library</b>
55 automatically uses parallelism for computing the motion of the agents if your machine
56 has multiple processors and your compiler supports <a href="http://www.openmp.org/">
57 OpenMP</a>.
58
59 Please follow the following steps to install and use <b>RVO2-3D Library</b>.
60
61 - \subpage whatsnew
62 - \subpage building
63 - \subpage using
64 - \subpage params
65
66 See the documentation of the RVO::RVOSimulator class for an exhaustive list of
67 public functions of <b>RVO2-3D Library</b>.
68
69 <b>RVO2-3D Library</b>, accompanying example code, and this documentation is
70 released for educational, research, and non-profit purposes under the following
71 \subpage terms "terms and conditions".
72
73
74 \page whatsnew What Is New in RVO2-3D Library
75
76 \section localca Three Dimensions
77
78 In contrast to RVO2 Library, <b>RVO2-3D Library</b> operates in 3D workspaces. It uses
79 a three dimensional implementation of <a href="http://gamma.cs.unc.edu/CA/">Optimal
80 Reciprocal Collision Avoidance</a> (ORCA) for local collision avoidance. <b>RVO2-3D
81 Library</b> does not replace RVO2 Library; for 2D applications, RVO2 Library should
82 be used.
83
84 \section structure Structure of RVO2-3D Library
85
86 The structure of <b>RVO2-3D Library</b> is similar to that of RVO2 Library.
87 Users familiar with RVO2 Library should find little trouble in using <b>RVO2-3D
88 Library</b>. <b>RVO2-3D Library</b> currently does not support static obstacles.
89
90 \page building Building RVO2-3D Library
91
92 We assume that you have downloaded <b>RVO2-3D Library</b> and unpacked the ZIP
93 archive to a path <tt>$RVO_ROOT</tt>.
94
95 \section xcode Apple Xcode 4.x
96
97 Open <tt>$RVO_ROOT/RVO.xcodeproj</tt> and select the <tt>Static Library</tt> scheme. A static library <tt>libRVO.a</tt> will be built in the default build directory.
98
99 \section cmake CMake
100
101 Create and switch to your chosen build directory, e.g. <tt>$RVO_ROOT/build</tt>.
102 Run <tt>cmake</tt> inside the build directory on the source directory, e.g.
103 <tt>cmake $RVO_ROOT/src</tt>. Build files for the default generator for your
104 platform will be generated in the build directory.
105
106 \section make GNU Make
107
108 Switch to the source directory <tt>$RVO_ROOT/src</tt> and run <tt>make</tt>.
109 Public header files (<tt>API.h</tt>, <tt>RVO.h</tt>, <tt>RVOSimulator.h</tt>, and <tt>Vector3.h</tt>) will be copied to the <tt>$RVO_ROOT/include</tt> directory and a static library <tt>libRVO.a</tt> will be compiled into the
110 <tt>$RVO_ROOT/lib</tt> directory.
111
112 \section visual Microsoft Visual Studio 2010
113
114 Open <tt>$RVO_ROOT/RVO.sln</tt> and select the <tt>RVOStatic</tt> project and a
115 configuration (<tt>Debug</tt> or <tt>Release</tt>). Public header files (<tt>API.h</tt>, <tt>RVO.h</tt>, <tt>RVOSimulator.h</tt>, and <tt>Vector3.h</tt>) will be copied to the <tt>$RVO_ROOT/include</tt> directory and a static library, e.g. <tt>RVO.lib</tt>, will be compiled into the
116 <tt>$RVO_ROOT/lib</tt> directory.
117
118
119 \page using Using RVO2-3D Library
120
121 \section structure Structure
122
123 A program performing an <b>RVO2-3D Library</b> simulation has the following global
124 structure.
125
126 \code
127 #include <RVO.h>
128
129 std::vector<RVO::Vector3> goals;
130
131 int main()
132 {
133 // Create a new simulator instance.
134 RVO::RVOSimulator* sim = new RVO::RVOSimulator();
135
136 // Set up the scenario.
137 setupScenario(sim);
138
139 // Perform (and manipulate) the simulation.
140 do {
141 updateVisualization(sim);
142 setPreferredVelocities(sim);
143 sim->doStep();
144 } while (!reachedGoal(sim));
145
146 delete sim;
147 }
148 \endcode
149
150 In order to use <b>RVO2-3D Library</b>, the user needs to include RVO.h. The first
151 step is then to create an instance of RVO::RVOSimulator. Then, the process
152 consists of two stages. The first stage is specifying the simulation scenario
153 and its parameters. In the above example program, this is done in the method
154 setupScenario(...), which we will discuss below. The second stage is the actual
155 performing of the simulation.
156
157 In the above example program, simulation steps are taken until all
158 the agents have reached some predefined goals. Prior to each simulation step,
159 we set the preferred velocity for each agent, i.e. the
160 velocity the agent would have taken if there were no other agents around, in the
161 method setPreferredVelocities(...). The simulator computes the actual velocities
162 of the agents and attempts to follow the preferred velocities as closely as
163 possible while guaranteeing collision avoidance at the same time. During the
164 simulation, the user may want to retrieve information from the simulation for
165 instance to visualize the simulation. In the above example program, this is done
166 in the method updateVisualization(...), which we will discuss below. It is also
167 possible to manipulate the simulation during the simulation, for instance by
168 changing positions, radii, velocities, etc. of the agents.
169
170 \section spec Setting up the Simulation Scenario
171
172 A scenario that is to be simulated can be set up as follows. A scenario consists
173 of a set of agents that can be manually specified. Agents may be added anytime
174 before or during the simulation. The user may also want to define goal positions
175 of the agents, or a roadmap to guide the agents around obstacles. This is not done
176 in <b>RVO2-3D Library</b>, but needs to be taken care of in the user's external
177 application.
178
179 The following example creates a scenario with eight agents exchanging positions.
180
181 \code
182 void setupScenario(RVO::RVOSimulator* sim) {
183 // Specify global time step of the simulation.
184 sim->setTimeStep(0.25f);
185
186 // Specify default parameters for agents that are subsequently added.