Mise à jour terminée. Pour connaître les apports de la version 13.8.4 par rapport à notre ancienne version vous pouvez lire les "Release Notes" suivantes :

README.md 6.68 KB
Newer Older
VAN TOLL Wouter's avatar
VAN TOLL Wouter committed
UMANS (Unified Microscopic Agent Navigation Simulator)
2 3 4 5


VAN TOLL Wouter's avatar
VAN TOLL Wouter committed
[UMANS](https://project.inria.fr/crowdscience/project/ocsr/umans/) (short for Unified Microscopic Agent Navigation Simulator) is an easy-to-use crowd-simulation engine that models each person in the crowd as an intelligent agent (i.e., the simulation is "microscopic"). UMANS currently focuses on the *local* aspects of navigation.

VAN TOLL Wouter's avatar
VAN TOLL Wouter committed
Many algorithms for microscopic crowd simulation have been developed over the past decades. However, each implementation has its own settings and details that can greatly influence the results. The purpose of UMANS is to reproduce as many existing algorithms as possible via one principle, while unifying as many overall settings as possible. This allows for a more honest and meaningful comparison of simulation algorithms.

VAN TOLL Wouter's avatar
VAN TOLL Wouter committed
10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27
UMANS was previously known as OCSR (Open Crowd Simulation Resources). Some parts of the project may still use this old name. Since 2020, the term "[OCSR](https://project.inria.fr/crowdscience/project/ocsr/)" refers to the collective of open crowd-simulation resources developed at Inria Rennes. These resources include UMANS (a simulation engine) and [ChAOS](https://project.inria.fr/crowdscience/project/ocsr/chaos/) (a visualization application).

UMANS is primarily meant for the scientific community, as a unified tool for experimenting with different navigation algorithms. However, the tool can be used freely by everyone, and it does not require any programming knowledge.

### What can UMANS do?

*  **Run a crowd simulation:** Given a scenario file containing agents and their properties, UMANS can output the trajectories of all agents during a period of time. These trajectories can then be loaded into other applications for visualization or analysis. 
* **Basic visualization:** You can use the *UMANS-GUI* application for a simple 2D visualization of a scenario.
* **Model many kinds of behavior:** A scenario file should define the so-called *policies* that agents use for local navigation. 
Overall, a policy consists of a cost function (possibly with parameters) and an optimization method. 
You can mix and match these elements as you wish. No programming knowledge is required for this.
* **Support new behavior:** If you are a programmer, you can clone the UMANS repository and *add your own cost functions* (and/or optimization methods), to add new types of behavior to the system. Adding new cost functions is easy thanks to the software's architecture.

### What can UMANS *not* do?

* **Global path planning:** The UMANS library deliberately focuses on *local navigation only*, i.e. the local interactions between agents. 
The simulation environment may contain static obstacles, but the agents in UMANS *do not* plan a global path.
* **Fancy visualization:** UMANS focuses on the simulation itself. For nice 3D animations of a crowd, consider using separate programs such as [ChAOS](https://project.inria.fr/crowdscience/project/ocsr/chaos/).

29 30 31 32 33 34 35 36 37 38 39 40 41 42
# Reference

The UMANS software has been described in the following scientific publication: 

> Wouter van Toll, Fabien Grzeskowiak, Axel López, Javad Amirian, Florian Berton, 
> Julien Bruneau, Beatriz Cabrero Daniel, Alberto Jovane, Julien Pettré.
> [*"Generalized Microscopic Crowd Simulation using Costs in Velocity Space"*](https://project.inria.fr/crowdscience/generalized-microscopic-crowd-simulation-using-costs-in-velocity-space-i3d-2020/). 
> In ACM SIGGRAPH Symposium on Interactive 3D Graphics and Games, 2020.

Please cite this publication when referring to UMANS in your work.

VAN TOLL Wouter's avatar
VAN TOLL Wouter committed
# Wiki and documentation

VAN TOLL Wouter's avatar
VAN TOLL Wouter committed
The UMANS repository comes with a [Wiki](https://gitlab.inria.fr/OCSR/UMANS/-/wikis/) that helps you install and use the UMANS software. It contains the following pages:

VAN TOLL Wouter's avatar
VAN TOLL Wouter committed
47 48 49
* [Getting started](https://gitlab.inria.fr/OCSR/UMANS/-/wikis/Getting%20started) - This page explains how to download or compile the UMANS binaries, what their main input and output is, and what to do if you run into problems.
* [Configuration files](https://gitlab.inria.fr/OCSR/UMANS/-/wikis/Configuration%20files) - This page explains the XML files that UMANS takes as input. It describes all options for these input files, so that you can create new scenarios yourself.
* [For developers](https://gitlab.inria.fr/OCSR/UMANS/-/wikis/For%20developers) - This page is for those who want to dive into the C++ code itself. For example, it explains how you can write your own cost functions. 

VAN TOLL Wouter's avatar
VAN TOLL Wouter committed
51 52 53 54
Also, most of the source code of UMANS has been carefully documented in a style compatible with [Doxygen](http://www.doxygen.nl/). 
This documentation is mostly meant for developers who intend to use/extend the UMANS codebase itself. 
The Doxygen documentation also facilitates development in an IDE such as Visual Studio.
If you run the Doxygen program on the UMANS root folder, it wil generate a *html* folder with all documentation pages. 
(This folder is not part of the repository on purpose.)
56 57 58

# Third-party code / licenses

59 60 61 62 63
UMANS relies on the following third-party code:

### Qt
- Website: https://www.qt.io/
- License: Open Source (https://doc.qt.io/Qt-5/opensourcelicense.html)
64 65 66 67 68

### nanoflann (kd-trees)
- Source code: https://github.com/jlblancoc/nanoflann
- License: BSD (https://github.com/jlblancoc/nanoflann/blob/master/COPYING)

69 70 71
### tinyxml (XML parsing)
- Source code: https://github.com/leethomason/tinyxml2
- License: zlib (https://github.com/leethomason/tinyxml2/blob/master/LICENSE.txt)
72 73 74 75

### ORCA (one of the collision-avoidance algorithms in UMANS)
- Source code: https://github.com/snape/RVO2
- License: Apache (https://github.com/snape/RVO2/blob/master/LICENSE)
76 77 78 79
### earcut (Polygon triangulation)
- Source code: https://github.com/mapbox/earcut.hpp
- License: ISC (https://github.com/mapbox/earcut.hpp/blob/master/LICENSE)

81 82
# Copyright statement

UMANS: Unified Microscopic Agent Navigation Simulator

85 86 87 88 89 90
Copyright (C) 2018-2020  Inria Rennes Bretagne Atlantique - Rainbow - Julien Pettré

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
91 92 93

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
95 96 97
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
Fabien Grzeskowiak's avatar
Fabien Grzeskowiak committed
along with this program. If not, see <https://www.gnu.org/licenses/>.
99 100

Contact: crowd_group@inria.fr
101 102 103 104

Website: https://project.inria.fr/crowdscience/

See the file AUTHORS.md for a list of all contributors.