diff --git a/.gitignore b/.gitignore index 7f4cc4b2..e00bf172 100644 --- a/.gitignore +++ b/.gitignore @@ -2,11 +2,9 @@ /lib/ /bin/ /outside/ -/doc /Debug /Release /Testing -/doc/html /figs /figs_bot /inputfiles diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..621ffdd9 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,4 @@ +sphinx==4.2.0 +sphinx_rtd_theme==1.0.0 +readthedocs-sphinx-search==0.1.1 +myst-parser==0.17.0 diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 00000000..f3be3362 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,48 @@ +# Configuration file for the Sphinx documentation builder. + +# -- Project information + +project = 'JPSreport' +copyright = '2022, Forschungszentrum Juelich GmbH, IAS-7' +author = 'JuPedSim Development Team' + +release = '0.9.4' +version = '0.9.4' + +# -- General configuration + +extensions = [ + 'sphinx.ext.duration', + 'sphinx.ext.doctest', + 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary', + 'sphinx.ext.intersphinx', + 'sphinx.ext.autosectionlabel', + 'myst_parser', +] + +intersphinx_mapping = { + 'python': ('https://docs.python.org/3/', None), + 'sphinx': ('https://www.sphinx-doc.org/en/master/', None), +} +intersphinx_disabled_domains = ['std'] + +templates_path = ['_templates'] + +# -- Options for HTML output + +html_theme = 'sphinx_rtd_theme' + +# -- Options for EPUB output +epub_show_urls = 'footnote' + +html_static_path = ['_static'] +html_logo = "images/jupedsim_small.png" + +html_theme_options = { + 'navigation_depth': -1, + 'logo_only': True, + 'style_nav_header_background': 'white', + 'collapse_navigation': False, + 'titles_only': False +} diff --git a/docs/source/images/Figue4-4-3.png b/docs/source/images/Figue4-4-3.png new file mode 100644 index 00000000..cb4666f2 Binary files /dev/null and b/docs/source/images/Figue4-4-3.png differ diff --git a/docs/source/images/Rooms.png b/docs/source/images/Rooms.png new file mode 100644 index 00000000..611426b0 Binary files /dev/null and b/docs/source/images/Rooms.png differ diff --git a/docs/source/images/avatar-icon.png b/docs/source/images/avatar-icon.png new file mode 100644 index 00000000..76486ce3 Binary files /dev/null and b/docs/source/images/avatar-icon.png differ diff --git a/docs/source/images/favicon-16x16.png b/docs/source/images/favicon-16x16.png new file mode 100644 index 00000000..1e24a11f Binary files /dev/null and b/docs/source/images/favicon-16x16.png differ diff --git a/docs/source/images/jpsreport_Method_A.png b/docs/source/images/jpsreport_Method_A.png new file mode 100644 index 00000000..493d854e Binary files /dev/null and b/docs/source/images/jpsreport_Method_A.png differ diff --git a/docs/source/images/jpsreport_Method_B.png b/docs/source/images/jpsreport_Method_B.png new file mode 100644 index 00000000..072020f6 Binary files /dev/null and b/docs/source/images/jpsreport_Method_B.png differ diff --git a/docs/source/images/jpsreport_Method_C.png b/docs/source/images/jpsreport_Method_C.png new file mode 100644 index 00000000..a5032023 Binary files /dev/null and b/docs/source/images/jpsreport_Method_C.png differ diff --git a/docs/source/images/jpsreport_Method_D.png b/docs/source/images/jpsreport_Method_D.png new file mode 100644 index 00000000..1d91d83c Binary files /dev/null and b/docs/source/images/jpsreport_Method_D.png differ diff --git a/docs/source/images/jupedsim_small.png b/docs/source/images/jupedsim_small.png new file mode 100644 index 00000000..46f2732e Binary files /dev/null and b/docs/source/images/jupedsim_small.png differ diff --git a/docs/source/images/notebook1.png b/docs/source/images/notebook1.png new file mode 100644 index 00000000..8666650d Binary files /dev/null and b/docs/source/images/notebook1.png differ diff --git a/docs/source/images/notebook2.png b/docs/source/images/notebook2.png new file mode 100644 index 00000000..9d270e56 Binary files /dev/null and b/docs/source/images/notebook2.png differ diff --git a/docs/source/images/notebook3.png b/docs/source/images/notebook3.png new file mode 100644 index 00000000..28720b29 Binary files /dev/null and b/docs/source/images/notebook3.png differ diff --git a/docs/source/images/usage_JPSreport_scaled.png b/docs/source/images/usage_JPSreport_scaled.png new file mode 100644 index 00000000..18218f20 Binary files /dev/null and b/docs/source/images/usage_JPSreport_scaled.png differ diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 00000000..bace7293 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,21 @@ +============================================== +JPSreport +============================================== +|DOI| + +``JPSreport`` is a command line module to analyze trajectories of pedestrians. + +Analyze pedestrian trajectories +=============================== + +1. On how to install ``JPSreport`` on your machine look at: :ref:`Installing JPSreport` +2. If you have ``JPSreport`` installed see :ref:`Getting started with JPSreport` on how to configure the analysis. +3. For a more detailed look at the provided analysis methods look at: :ref:`Measurement methods` + +.. |DOI| image:: https://zenodo.org/badge/109670242.svg + :target: https://zenodo.org/badge/latestdoi/109670242 + +.. toctree:: + install + usage + methods diff --git a/docs/source/install.rst b/docs/source/install.rst new file mode 100644 index 00000000..b39e9e90 --- /dev/null +++ b/docs/source/install.rst @@ -0,0 +1,192 @@ +.. _install: +==================== +Installing JPSreport +==================== + +Download installer +================== + +Release +------- + +- Windows installer: +- MacOS installer: + + +Nightly build +------------- + +- Windows installer: +- MacOS installer: + + +Build from source +================= +It should be possible to build on all major platforms however, we only test a few: + +Right now, we ensure a working Build for: + +- Windows 10 +- MacOS BigSur +- Ubuntu 20.04 + +Get the code +------------ +In order to compile JPSreport, you need to download the source code via: + +.. code:: bash + + git clone https://github.com/JuPedSim/jpscore.git + +Build Options +------------- +We support only a few settings. For a list of build options, please see [CMakeLists.txt] directly. + + +General Information +------------------- +All of the following descriptions assume the following layout on disk: + +:: + + . + ├── jpsreport <- code repository + ├── jpsreport-build <- build folder + └── jpsreport-deps <- install location of library dependencies + + +Build on Windows +---------------- + +System Requirements +^^^^^^^^^^^^^^^^^^^ +- Visual Studio +- vcpkg (see https://vcpkg.io/en/getting-started.html) + +Library Dependencies +^^^^^^^^^^^^^^^^^^^^ +On Windows dependencies are installed with ``vcpkg``, get it from vcpkg.io. +``vcpkg`` will automatically download and install the dependencies listen in ``vcpkg.json`` if used with CMake. + + +Compiling +^^^^^^^^^ +To call the CMake configuration and to install the needed dependencies, call + +.. code:: bash + + cmake -DCMAKE_BUILD_TYPE=Debug -DCMAKE_TOOLCHAIN_FILE=/scripts/buildsystems/vcpkg.cmake + + +To finally compile the source code, use + +.. code:: bash + + cmake --build . --config Debug + + +Build on Linux +---------------- + +System Requirements +^^^^^^^^^^^^^^^^^^^ + +Builds are only tested on the latest Ubuntu LTS version (at this time 20.04). +To compile from source you will need a couple of system dependencies. + +- C++17 capable compiler (default GCC will do) +- wget + +Recommended: + +- ninja + +Library Dependencies +^^^^^^^^^^^^^^^^^^^^ +On Linux and MacOS all dependencies are built from source, they are either part of the source tree and do not need any special attention or they are built with ``scripts/setup-deps.sh``. +To compile dependencies invoke the script and specify the install path: + +.. code:: bash + + ./scripts/setup-deps.sh --install-path ~/jpsreport-deps + + +The output created in ``~jpsreport-deps`` now contains an install tree of all required library dependencies. + +.. warning:: + If you do not specify an install path the script tries to install into ``/usr/local``. + +Compiling +^^^^^^^^^ +Now that you have all library dependencies, you need to generate build files with CMake and compile. + +.. code:: bash + + mkdir jpsreport-build + cd jpsreport-build + cmake -GNinja -DCMAKE_BUILD_TYPE=Debug -DCMAKE_PREFIX_PATH= + ninja + +Alternatively you can generate a make based build with: + +.. code:: bash + + mkdir jpsreport-build + cd jpsreport-build + cmake -DCMAKE_BUILD_TYPE=Debug -DCMAKE_PREFIX_PATH= + make -j$(nproc) + +You will find the ``jpsreport`` executable in ``jpsreport-build/bin`` after the build. + +Build on MacOS +---------------- + +System Requirements +^^^^^^^^^^^^^^^^^^^ + +- AppleClang/XCode command line tools +- wget + +Recommended: + +- ninja + +Library Dependencies +^^^^^^^^^^^^^^^^^^^^ + +On Linux and MacOS all dependencies are built from source, they are either part of the source tree and do not need any special attention or they are built with ``scripts/setup-deps.sh``. +To compile dependencies invoke the script and specify the install path: + +.. code:: bash + + ./scripts/setup-deps.sh --install-path ~/jpsreport-deps + + +The output created in ``~jpsreport-deps`` now contains an install tree of all required library dependencies. + +.. warning:: + If you do not specify an install path the script tries to install into ``/usr/local``. + + +Compiling +^^^^^^^^^ + +Now that you have all library dependencies, you need to generate build files with CMake and compile. + +.. code:: bash + + mkdir jpsreport-build + cd jpsreport-build + cmake -GNinja -DCMAKE_BUILD_TYPE=Debug -DCMAKE_PREFIX_PATH= + ninja + +Alternatively you can generate a make based build with: + +.. code:: bash + + mkdir jpsreport-build + cd jpsreport-build + cmake -DCMAKE_BUILD_TYPE=Debug -DCMAKE_PREFIX_PATH= + make -j$(nproc) + +You will find the ``jpsreport`` executable in ``jpsreport-build/bin`` after the build. diff --git a/docs/source/methods.rst b/docs/source/methods.rst new file mode 100644 index 00000000..94c3ed33 --- /dev/null +++ b/docs/source/methods.rst @@ -0,0 +1,134 @@ +.. _methods: +==================== +Measurement methods +==================== + +.. _method_A: +Method A +======== + +.. figure:: images/jpsreport_Method_A.png + :alt: Method A: Illustration of the measurement line. + + Method A: Illustration of the measurement line. + +A reference line is taken and studied over a fixed period of time :math:`\Delta {t}`. +Using this method we can obtain the pedestrian flow :math:`J` and the velocity :math:`v_i` of each pedestrian passing the reference line directly. \ +Thus, the flow over time :math:`\langle J \rangle_{\Delta t}` and the time mean velocity :math:`\langle v \rangle_{\Delta t}` can be calculated as + +.. math:: + + \langle J \rangle_{\Delta t}=\frac{N^{\Delta t}}{t_N^{\Delta t} - t_1^{\Delta t}}\qquad \text{and} \qquad \langle v \rangle_{\Delta t}=\frac{1}{N^{\Delta t}}\sum_{i=1}^{N^{\Delta t}} v_i(t), + +where :math:`N^{\Delta t}` is the number of persons passing the reference line during the time interval :math:`\Delta {t}`. + +:math:`t_N^{\Delta {t}}` and :math:`t_1^{\Delta {t}}` are the times when the first and last pedestrians pass the location in :math:`\Delta {t}`. + +.. note:: + This time period can be different from :math:`\Delta {t}`. + +The time mean velocity :math:`\langle v \rangle_{\Delta t}` is defined as the mean value of the instantaneous velocities :math:`N^{\Delta t}` pedestrians. + +:math:`v_i(t)` is calculated by use of the displacement of pedestrian :math:`i` in a small time interval :math:`\Delta t^\prime` around :math:`t`: + +.. math:: + + v_i(t)=\frac{\vec{x_i}(t+\Delta t^\prime/2)-\vec{x_i}(t-\Delta t^\prime/2))}{\Delta t^\prime}. + + +.. _method_B: +Method B +======== + +The spatial mean velocity and density are calculated by taking a segment :math:`\Delta x` in a corridor as the measurement area. + +.. figure:: images/jpsreport_Method_B.png + :alt: Method B: Illustration of the measurement interval. + + Method B: Illustration of the measurement interval. + +The velocity :math:`\langle v \rangle_i` of each person is defined as the length :math:`\Delta x` of the measurement area divided by the time they need to cross the area: + +.. math:: + + \langle v \rangle_i=\frac{\Delta x}{t_\text{out}-t_\text{in}}, + +where :math:`t_\text{in}`and :math:`t_\text{out}` are the times a person enters and exits the measurement area, respectively. +The density :math:`\rho_i` for each person :math:`i` is calculated as: + +.. math:: + + \langle \rho \rangle_i=\frac{1}{t_\text{out}-t_\text{in}}\cdot\int_{t_\text{in}}^{t_\text{out}} \frac{N^\prime(t)}{b_\text{cor}\cdot\Delta x}dt, + +where :math:`b_\text{cor}` is the width of the measurement area while :math:`N^\prime(t)` is the number of person in this area at a time :math:`t`. + + +.. _method_C: +Method C +======== + +.. figure:: images/jpsreport_Method_C.png + :alt: Method C: Illustration of the measurement area + + Method C: Illustration of the measurement area + +The density :math:`\langle \rho \rangle_{\Delta x}` is defined as the number of pedestrians divided by the area of the measurement section: + +.. math:: + + \langle \rho \rangle_{\Delta x}=\frac{N}{b_\text{cor}\cdot\Delta x}. + +The spatial mean velocity is the average of the instantaneous velocities :math:`v_i(t)` for all pedestrians in the measurement area at time :math:`t`: + +.. math:: + + \langle v \rangle_{\Delta x}=\frac{1}{N}\sum_{i=1}^{N}{v_i(t)}. + + +.. _method_D: +Method D +======== + +At any time the positions of the pedestrians can be represented as a set +of points, from which the Voronoi diagram can be generated. + +The Voronoi cell area, :math:`A_i`, for each person :math:`i` can be obtained. + +.. figure:: images/jpsreport_Method_D.png + :alt: Method D: Illustration of the Voronoi diagrams + + Method D: Illustration of the Voronoi diagrams + +Then, the density and velocity distribution of the space :math:`\rho_{xy}` and :math:`v_{xy}` can be defined as + +.. math:: + + \rho_{xy} = 1/A_i \quad \text{and} \quad v_{xy}={v_i(t)}\qquad \mbox{if} (x,y) \in A_i, + +where :math:`v_i(t)` is the instantaneous velocity of each person. + +The **Voronoi density** for the measurement area is defined as: + +.. math:: + + \langle \rho \rangle_v=\frac{\iint{\rho_{xy}dxdy}}{b_\text{cor}\cdot\Delta x}. + +For a given trajectory :math:`\vec{x_i}(t)`, the velocity :math:`v_i(t)` is calculated by use of the displacement of pedestrian :math:`i` in a small time interval :math:`\Delta t^\prime` around :math:`t`: + +.. math:: + + v_i(t)=\frac{\vec{x_i}(t+\Delta t^\prime/2)-\vec{x_i}(t-\Delta t^\prime/2))}{\Delta t^\prime}. + +For calculating the mean velocity in the measurement area two approaches +can be applied. + +1. The **Voronoi velocity** is defined as: + +.. math:: \langle v \rangle_v=\frac{\iint{v_{xy}dxdy}}{b_\text{cor}\cdot\Delta x}. + +2. The **Arithmetic velocity** is the average of the instantaneous + velocities :math:`v_i(t)` for all pedestrians :math:`N` who have an intersection with the measurement area at the time :math:`t`: + +.. math:: + + \langle v \rangle_{\Delta x}=\frac{1}{N_{(x,y) \in A_i}}\sum_{i=1}^{N_{(x,y) \in A_i}}{v_i(t)}. diff --git a/docs/source/profiles.rst b/docs/source/profiles.rst new file mode 100644 index 00000000..75c5597b --- /dev/null +++ b/docs/source/profiles.rst @@ -0,0 +1,53 @@ +================ +Density profiles +================ + +{%include note.html content=“this tutorial needs links to data”%} + +Here is an example extracted from a T-Junction experiment: + +.. figure:: %7B%7B%20site.baseurl%20%7D%7D/images/Figue4-4-3.png + :alt: T-junction + + T-junction + +Run jpsreport +============= + +| In order to calculate the profiles it is mandatory to use `method + D `__ or `method + I `__. +| M oreover, Set the parameter ``enabled`` of profiles to ``true``. +| Set the resolution of the profile by initializing the two parameters + ``grid_size_x``\ and ``grid_size_y``, e.g.: + +.. code:: xml + + + + + +(optional) Steady state +======================= + +Determine the steady state of the experiment in the whole measurement +region. In the folder script there is a script to fulfill this task +semi-manually. + +Produce the profiles +==================== + +Run the python script ``_Plot_profiles.py``, which is in the scripts +folder in ``jpsreport``. + +Results +======= + +Possible output of ``jpsreport`` includes data for plotting fundamental +diagrams, Voronoi diagrams and profiles of pedestrians etc. in a given +geometry. All the output data, e.g. density and speed, are stored in +different folders as plain text in ASCII format. + +After a successful analysis additional folder named ``Output`` will be +created in the same directory as the used ini-file. It contains the basic +data including plain text. diff --git a/docs/source/usage.rst b/docs/source/usage.rst new file mode 100644 index 00000000..008a9184 --- /dev/null +++ b/docs/source/usage.rst @@ -0,0 +1,392 @@ +.. _usage: +================================ +Getting started with jpsreport +================================ + +``jpsreport`` is a command line module to analyze trajectories of pedestrians. +In the terminal, pass an ini-file file as argument. + +The following pictures summarizes the input and output files of ``jpsreport`` + +.. figure:: images/usage_JPSreport_scaled.png + :alt: Definition of input and output files of jpsreport + + Definition of input and output files of jpsreport + +Three input files are required to run ``jpsreport``: + +- A :ref:`Configuration/ini-file`: This ini-file gives some + information related to each measurement method. e. g. the location of + measurement areas, the chosen measurement method, etc. This file + should be in ``.xml`` format. +- A :ref:`Trajectory file`: Pedestrian’s 3D + position information over time. Only ``.txt`` format is supported. + The file must contain the data sorted by time/frames. +- A :ref:`Geometry file`: Geometry for a certain + trajectory data. This file should be in ``.xml`` format. + +Usage +===== + +To start an analysis, run ``jpsreport`` in a terminal. +It is suggested to redirect the output of the analysis to a file, to persist any warnings which may occur during the analysis. +This can be done by: + +.. code:: bash + + ./jpsreport > log_example.txt + + + +Configuration/ini-file +====================== + +In the configuration/ini-file, the following sections should be defined: + +Header +------ + +.. code:: xml + + + + + +Geometry +-------- + +indicates the file name corresponding to the trajectory files to +analyze. + +.. code:: xml + + + +The location can be either absolute path or relative path to the +location of the inifile. A path is considered absolute if it starts with +“/” (Linux system) or contains “:” (Windows system). + +.. code:: xml + + + +Output +------ + +indicates the location of the output files based on the location of +inifile or the absolute path. + +.. code:: xml + + + +A path is considered absolute if it starts with “/” (Linux system) or +contains “:” (Windows system). + +Trajectories +------------ + +indicates the location and the name of the trajectory files that will be +analyzed. The format of trajectory files should be ``.txt``. + +The supported unit of the trajectories is ``m``. Two other sub-options +``file`` and ``path`` can be supplied. If only ``path`` is given, then +all files with the corresponding format in the given folder will be +considered as the upcoming trajectories and ``JPSreport`` will try to +load them one by one. If ``path``\ is not defined, the trajectory files +must be located in the same directory as the inifile. If both ``file`` +and ``path`` are given, then only the given trajectories will be +considered (several ``file`` tags can be given at the same time). + +The location can be either absolute path or relative path to the +location of the inifile. A path is considered absolute if it starts with +“/” (Linux system) or contains “:” (Windows system). + +For example: + +.. code:: xml + + + + + + + + +.. warning:: + + To avoid issues when creating the output files, to not define path information in ``file`` as in + + .. code:: xml + + + + + + . + + +Measurement area +---------------- + +Indicates the types and location of the measurement areas you plan to +use for analysis. Mainly two kind of measurement areas can be defined: + +- ``area_B``: a 2D area and can be polygon (**the orientation of its + points is clockwise**) +- ``area_L``: a reference segment line defined by two points. + +``area_L`` is only used in method A, while ``area_B`` is used for method +B, method C and method D. Several measurement areas can be given and +distinguished with different ``id``. Measurement areas must be defined +within one room according to the geometry file. They should not spread +over several rooms or cross with walls. + +The parameter ``zPos`` is used to indicate the position of measurement +area in z axis. ``zPos`` is useful for geometry with several stories. + +{%include note.html content=“The option ``length_in_movement_direction`` +is only used in method B and the value will be ignored in other methods. +If not given in method_B, the effective distance between entrance point +to the measurement area and the exit point from the measurement area +will be used.”%} + +.. code:: xml + + + + + + + + + + + + + + + + + + + + +Velocity +-------- + +precises the method for calculating the instantaneous velocity :math:v_i(t) of pedestrian :math:i at time :math:t from trajectories: + +.. math:: + + v_i(t) = \frac{X(t+\frac{frame\_step}{2}) - X(t-\frac{frame\_step}{2})}{frame\_step}. + + +.. code:: xml + + + +Possible parameters are + +- ``frame_step`` gives the size of time interval for calculating the velocity. The default value is 10. +- ``set_movement_direction`` indicates in which direction the velocity will be projected. The value of ``set_movement_direction`` can be: + + - ``None``, which means that you don’t consider the movement direction and calculate the velocity by the real distance. This is the default value. + - Any real number from ``0`` to ``360`` which represents the angular information of the direction in the coordination system. Note that the axis can be represented either by ``X+``, ``Y+``, ``X-``, ``Y-`` or by 0, 90, 180, 270. + - ``SeeTraj``. For complex trajectories with several times of direction change, you can indicate the detailed direction using the angular information in the trajectory file (By adding a new column in ``.txt`` file with the indicator ``VD``). +- ``ignore_backward_movement`` indicates whether you want to ignore the movement opposite to the direction from ``set_movement_direction``. The default value is ``false``. + +Methods +------- + +Indicates the parameters related to each measurement method. +Four different methods ``method_A`` to ``method_D`` are integrated in the current version of ``JPSreport`` and can be chosen for the analysis. +They are used to analyze the movement of pedestrians for the steady state. +Additionally, ``Method_D`` can be used for time-series analysis of individual data. + ++-----------------------+-----------------------+------------------------------------------------------------------------------------+ +| Method | measurement area | output data | ++=======================+=======================+====================================================================================+ +| *A* | |Method A| | :math:`\langle v \rangle_{\Delta t}` and :math:`\langle J \rangle_{\Delta t}` | ++-----------------------+-----------------------+------------------------------------------------------------------------------------+ +| *B* | |Method B| | :math:`\langle v \rangle_i` and :math:`\langle \rho \rangle_i` | ++-----------------------+-----------------------+------------------------------------------------------------------------------------+ +| *C* | |Method C| | :math:`\langle v \rangle_{\Delta x}` and :math:`\langle \rho \rangle_{\Delta x}` | ++-----------------------+-----------------------+------------------------------------------------------------------------------------+ +| *D* | |Method D| | :math:`\langle v \rangle_v` and :math:`\langle \rho \rangle_v` | ++-----------------------+-----------------------+------------------------------------------------------------------------------------+ + + + +Further information relating to each method can be found in `Pedestrian +fundamental diagrams: Comparative analysis of experiments in different +geometries `_. + +Method A +"""""""" + +For definition see :ref:`Method A `. +Method A is used to analyze the steady state. + +.. code:: xml + + + + + + +Possible parameters are: + + - ``id`` specifies the location of the reference line. + - ``frame_interval`` specifies the size of time interval (in *frame*) for calculating flow rate. + +Possible output data are: + + - ``/Fundamental_Diagram/FlowVelocity/``: + + - ``Flow_NT_traj_``: containing Frame, time and cumulative pedestrians + - ``FDFlowVelocity_traj_`` + +Method B +"""""""" + +For definition see :ref:`Method B `. +Method B is used to analyze the steady state. + +.. code:: xml + + + + + +This method can only be used to analyze one directional (or part of one directional) pedestrian movement in corridors. +The speed is defined by the length of the measurement area ``length_in_movement_direction`` and the time a pedestrian stays in the area. + +Possible parameters are: + + - ``measurement_area`` given by an ``id`` number. Note that the measurement area for method_B should be rectangle based on the definition of the method. + +Possible output data are: + + - ``/Fundamental_Diagram/TinTout/``: output file ``FDTinTout_traj_`` with mean density and velocity of each pedestrians: PersID, :math:`\rho_i` and :math:`v_i`. + +Method C +"""""""" + +For definition see :ref:`Method C `. +Method C is used to analyze the steady state. + +.. code:: xml + + + + + +Possible parameters are: + +- ``id`` indicates the size and location of the measurement_area. + Several measurement areas can be set in one inifile. + +Possible output data are: + + - ``/Fundamental_Diagram/Classical_Voronoi/``: output file ``rho_v_Classic_traj_`` with mean density and velocity of over time (frame, :math:`rho(t)`, :math:`v(t)`). + +Method D +"""""""" + +For definition see :ref:`Method D `. +Method D is used to analyze velocity and density in the steady state as well as for time-series analysis. + +.. code:: xml + + + + + + + + + + + +Possible parameters are: + +- For each ``measurement_area``, several id numbers can be set in one ini-file. + +- ``start_frame`` and ``stop_frame`` give the starting and ending frame for data analysis. + The default values of these two parameters are ``None``. + If you plan to analysis the whole run from beginning to the end, set both of ``start_frame`` and ``stop_frame`` as ``None``; + If ``start_frame =None`` but ``stop_frame`` is not, then analysis will be performed from beginning of the trajectory to the ``stop_frame``. + If ``start_frame`` is not ``None`` but ``stop_frame = None``, it will analyze from the ``start_frame`` to the end of the movement. + +- ``local_IFD`` determines whether or not to output the data for individual fundamental diagram in the given measurement area, + which is based on the Voronoi density :math:\rho_i, velocity :math:v_i, position (:math:`x_i`, :math:`y_i`, :math:`z_i`) + and Voronoi polygon of each pedestrian :math:i in a given measurement area but not mean value over space. + If ``true`` the related data will be written in the folder ``./Output/Fundamental_Diagram/IndividualFD/``. + +- ``one_dimensional`` should be used when pedestrians move on a line `single-file experiment `. + +- ``cut_by_circle`` determines whether to cut each cell by circle or not. + Two options ``radius`` of the circle and the number of ``edges`` have to be supplied for approximating the circle if ``enabled`` is ``true``. + +- ``profiles`` indicates whether to calculate the profiles over time and space. + If ``enabled`` is true, the resolution which is decided by the parameters ``grid_size_x`` and ``grid_size_x`` should be set. + ``start_frame`` and ``stop_frame`` can be used to specify the time range for the analysis. + +- ``global_IFD`` indicates a global measurement area encompassing the entire geometry for which individual data (IFD) are calculated. \ + This parameter is set to ``false`` by default. + ``start_frame`` and ``stop_frame`` can be used to specify the time range for the analysis. + +- ``use_blind_points`` allows to calculate Voronoi cells in measurement areas even if less than four pedestrians are present. + This is realized with the help of blind points are automatically defined outside the geometry. + This parameter is set to ``true`` by default. + +- ``vel_calculation`` indicates the approach that is used for the velocity calculation. + By default the ``Voronoi`` approach is chosen but it can be changed to ``Arithmetic`` if needed. + See :ref:`Method D ` for details. + +Possible output data are: + +- ``/Fundamental_Diagram/Classical_Voronoi/``: + + - ``rho_v_Voronoi_[velocity_calculation_type]_[filename.txt]_id_[local_measurement_area_id].dat``: + with mean density and velocity over time (frame, :math:\rho_i, :math:v_i ) + + +- ``/Fundamental_Diagram/IndividualFD/``: + - ``IFD_local_[filename.txt]_id_[local_measurement_area_id].dat`` contains data for each pedestrian :math:i + (in the measurement area) about individual Voronoi density :math:\rho_i, + individual velocity :math:v_i , + position (:math:`x_i`, :math:`y_i`, :math:`z_i`), + Voronoi polygon of the pedestrian and + the intersection of the Voronoi polygon with the measurement area. + + - ``IFD_global_[filename.txt].dat`` contains data for each pedestrian :math:i + about individual Voronoi density :math:\rho_i, + individual velocity :math:v_i , + position (:math:`x_i`, :math:`y_i`, :math:`z_i`), + Voronoi polygon of the pedestrian. + +- ``./Output/Fundamental_Diagram/Classical_Voronoi/field/``: + - ``Profile_rho_Voronoi_[filename.txt]_[frame]`` contains the profile data for density for one frame. + + - ``Profile_v_[velocity_calculation_type]_[filename.txt]_[frame]`` contains the profile data for velocity for one frame. + - the output folder ``./Output/Fundamental_Diagram/Classical_Voronoi/VoronoiCell/`` contains the data for plotting the Voronoi cells. + +.. |Method A| image:: images/jpsreport_Method_A.png +.. |Method B| image:: images/jpsreport_Method_B.png +.. |Method C| image:: images/jpsreport_Method_C.png +.. |Method D| image:: images/jpsreport_Method_D.png + +Trajectory-file +=============== + +Trajectory files which can be analyzed with ``JPSreport`` need a specific format. +It is the same format which is generated by simulations with ``jpscore``, see `JupedSim documentation `_ for more information. + +Geometry-file +============== + +As ``JPSreport`` is part of JuPedSim the same geometry model is used for the analysis, on how to create such geometries see `JupedSim documentation `_.