Commit e56c4a52 authored by VAN TOLL Wouter's avatar VAN TOLL Wouter

Update README.md

parent 130d74c0
......@@ -3,19 +3,28 @@ UMANS (Unified Microscopic Agent Navigation Simulator)
![](doc/UMANS-Logo-Transparent-Medium.png)
UMANS (short for Unified Microscopic Agent Navigation Simulator) is an agent-based
crowd-simulation engine that focuses on the local (a.k.a. "microscopic") aspects of navigation.
[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.
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.
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.
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" refers to the collective of open crowd-simulation resources developed at Inria Rennes.
These resources include UMANS (a simulation engine) and ChAOS (a visualization application).
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/).
# Reference
......@@ -31,62 +40,18 @@ The UMANS software has been described in the following scientific publication:
Please cite this publication when referring to UMANS in your work.
# Getting started
UMANS has three main applications that you can use:
- ***UMANS-ConsoleApplication***: A command-line-only program that can run a crowd-simulation scenario and save the results.
If you run this program without any arguments, it will print more detailed usage instructions.
- ***UMANS-GUI***: A demo program with a (Qt) GUI, in which you can view a simulation and edit it with basic mouse and keyboard interaction.
- ***UMANS-Library***: A dynamic library (a DLL on Windows, or an .so file on Linux) with an API that can be integrated into other software.
To obtain these programs, you have two options: download the pre-built binaries, or compile the code yourself.
### Option 1: Download the binaries
For downloadable pre-built binaries of UMANS,
please visit the [Releases](https://gitlab.inria.fr/OCSR/UMANS/-/releases) page of this repository.
### Option 2: Compile the code
To compile the UMANS codebase on your machine, perform the following steps:
1. Clone or download the code from [our GitLab repository](https://gitlab.inria.fr/OCSR/UMANS/).
2. Download and install [Qt](https://www.qt.io/) (optional) and [CMake](https://cmake.org/) (required).
(Qt is only needed if you want to compile the *UMANS-GUI* application.)
3. Use CMake to turn the codebase into a programming project for your IDE/compiler of choice.
(You can also disable the UMANS-GUI project here. If you disable it, you do not need a Qt installation.)
4. Compile the code in your IDE/compiler.
This should build the three applications mentioned before.
### Input and output
The main **input** of a UMANS simulation is an **XML file** that describes agents, their start and goal positions,
their navigation behavior, and optionally obstacles.
Many working examples can be found in the [*examples*](https://gitlab.inria.fr/OCSR/UMANS/-/tree/master/examples) folder.
The main **output** of a UMANS simulation (or at least of the *UMANS-ConsoleApplication* program)
is a **folder with CSV files**, where each file contains the trajectory of one agent in the crowd.
You can plot these trajectories in a tool of choice.
You can also consider using the [ChAOS](https://gitlab.inria.fr/OCSR/ChAOS/) software
to visualize the results with animated 3D characters.
The *UMANS-ConsoleApplication* program simply converts input (XML) to output (CSV).
By contrast, *UMANS-GUI* and *UMANS-Library* are meant for interactive purposes, so they do not produce any output files by default.
# Documentation
### For end users
# Wiki and documentation
For general users of UMANS, we are creating a [Wiki](https://gitlab.inria.fr/OCSR/UMANS/-/wikis/home)
with basic information on how to use the software. We will extend this wiki over time.
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:
### For programmers
* [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.
For those interested in using/extending the UMANS source code,
most of the codebase has been carefully documented in a style compatible with [Doxygen](http://www.doxygen.nl/).
This facilitates development in an IDE such as Visual Studio.
If you run Doxygen on the UMANS root folder, it wil generate a *html* folder with documentation.
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.)
# Third-party code / licenses
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment