Commit 4a1ed70a authored by VAN TOLL Wouter's avatar VAN TOLL Wouter

Updated README.md with more usage instructions.

parent 916678ca
......@@ -33,7 +33,23 @@ Please cite this publication when referring to UMANS in your work.
# Getting started
To start using UMANS, perform the following steps:
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).
......@@ -42,21 +58,36 @@ To start using UMANS, perform the following steps:
(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 several applications (see the [Main projects](#main-projects) section).
5. If you have compiled the UMANS-GUI program, run it and see an example simulation in action!
6. Test the UMANS console application by running it from the command line, with the desired arguments.
If you run the program without any arguments, it will print more detailed usage instructions.
7. Inspect the CSV files that the application has produced as output.
Each CSV file contains the trajectory of one agent in the crowd.
You could consider using the [ChAOS](https://gitlab.inria.fr/OCSR/ChAOS/) software to visualize the crowd in 3D.
# Main projects
### 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
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.
In the source code of UMANS, the simulation engine itself is contained in a static library named *Engine*.
This library is used by three main applications:
### For programmers
- *UMANS-ConsoleApplication*: A command-line-only program that can run a crowd-simulation scenario and report the results in various ways.
- *UMANS-Library*: A dynamic library with an API that can be integrated into other software (e.g. as a DLL).
- *UMANS-GUI*: A demo program with a (Qt) GUI, in which users can change the simulation with basic mouse and keyboard interaction.
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.
(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