Getting Started with DiscoPygal
================================
.. sectnum::

What is DiscoPygal?
-------------------


DiscoPygal is a suite of tools that allow for rapid development and experimentation with motion planning in 2D environment.
It is developed in Tel Aviv University's Computational Geometry Laboratory, under the supervision of Prof. Dan Halperin.

..
    Link to repository: https://bitbucket.org/taucgl/discopygal/
..

Link to page at the lab's website: https://www.cgl.cs.tau.ac.il/projects/discopygal/

How to start?
-------------

#. Install the :ref:`prerequisites <prerequisites>` (depending on your platform)
#. Install Discopygal package :ref:`from whl file <installation>` (other methods are for package developers)
#. Learn how to :ref:`use the package <using_package>` and especially how to:

   #. write a :ref:`Solver <solver>`
   #. create a :ref:`Scene <scene>`
#. | Understand how to combine the solvers with scenes you have created in a python script that uses them.
   | Look at :ref:`this <example>` and :ref:`this <random_solver>` examples to understand how to do it.

#. Read about the two main tools of the package and how to use them:

    #. :ref:`Solver viewer <solver_viewer>`
    #. :ref:`Scene designer <scene_designer>`

.. _prerequisites:

Prerequisites
-------------

Before installing DiscoPygal, depending on your operating system you should install some prerequisites.

General prerequisites
~~~~~~~~~~~~~~~~~~~~~~

For any operating system install the following:

* At least 8GB **RAM** (relevant mostly for VM or WSL)
* C++ compiler (for example gcc for Linux/mac and visual studio for windows, will be explained at the following)
* Python 3.9 (at least) - https://www.python.org/downloads/
* Pipenv:

    Pipenv is not necessary but highly recommended for easy installation.
    You can install it by running the following command in cmd/bash::

                pip install pipenv


Ubuntu
~~~~~~

.. note::
    Tested with Ubuntu 20.04.3

You should run the following command in bash:

.. code-block::

    sudo apt-get install libxcd-xinerama0

macOS
~~~~~

.. note::
    Tested on macOS Big Sur and macOS Monterey, Intel

* You should first install homebrew: https://brew.sh
* .. code-block::

    brew install boost-python3
    brew install cgal

* Install explicitly PyQt5 (For non Apple Silicone users):

    .. code-block::

            pipenv install pyqt5

    NOTE: On Apple Silicone Machines, PyQt5 should be installed as following:
    https://stackoverflow.com/questions/74393139/pipenv-cant-install-pyqt5

Windows
~~~~~~~

.. note::
    Tested on Windows 11

You should install the following:

* Git for windows (https://gitforwindows.org/ )
* Visual Studio or Visual Studio Build Tools (to have C++ compiler):

  | (https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022 )
  | If installing Visual Studio Build Tools choose Desktop development with C++

    .. image:: ../images/vs_tools_installer.png
                :width: 400

    Make sure to choose these components from the sidebar:

    .. image:: ../images/components_to_vs_tools.png
                :width: 250

WSL
~~~

.. note::
    Tested on WSL2 for Ubuntu 20

Run the following:
::

    sudo apt install qt5dxcb-plugin
    sudo apt install python3.11-dev

.. _installation:

Installation
-------------

Before installing, please make sure you have installed all the necessary prerequisites listed above.
Installation can be done from a precompiled wheel or from the sources.

.. warning::

    If encountering any problems check: :ref:`Troubleshooting <troubleshooting>`

Install with pip the whl file::

    pip install <path to .whl file>

This can take up to half an hour!

To uninstall simply run::

    pip uninstall discopygal-taucgl


.. note::
    You may want to install the package in a virtual environment (with pipenv or venv) so the installation won't interfere with the native python packages on your environment.

    (make sure to create the virtual env in the directory you want or create a new one for convenience)

    To activate Pipenv at current directory (also creates a new env if running for the first time)::

        pipenv shell

    Then install the package with the pip command shown before.

    To deactivate pipenv::

        exit

    After installing the discopygal package, when opening a new shell you just need to enter the directory where you have created the virtual env and activate the pipenv shell.
.. commented out
    .. tabs::
        .. tab:: Pipenv

            To activate (creates a new env if at the first time):
            ::

                pipenv shell

            To deactivate:
            ::

                exit
        .. tab:: venv

            To create:
            ::

                python -m venv .

            To activate:
                .. tabs::
                    .. group-tab:: Windows
                        ::

                            .\Scripts\activate

                    .. group-tab:: Linux
                        ::

                            . ./bin/activate

            To deactivate:
                .. tabs::
                    .. group-tab:: Windows
                        ::

                            exit

                    .. group-tab:: Linux
                        ::

                            . ./bin/deactivate

..

Tools
-----

Execute these commands for running them (might need .exe suffix in Windows)::

    solver_viewer
    scene_designer

For more information see: :doc:`using_tools`

.. _example:

Example: Motion planning a simple scene
---------------------------------------

| We present a minimal code sample that generates manually a scene with two robots and a single obstacle, and uses some solver to plan a solution.
| This is a basic example to show how to use the package, create solvers, scenes and solve them.
| Afterwards we again load the scene and the solver we created to solver_viewer gui.
| This example can also be found in the repo at: https://bitbucket.org/taucgl/discopygal/src/master/examples/basic_examples/simple_motion_planning.py

.. literalinclude:: ../../examples/basic_examples/simple_motion_planning.py

.. _troubleshooting:

Troubleshooting
---------------

    #. The user's name installing from must be in english
    #. Run the "pip install" command in verbose mode to see where the problem is::

        pip install --verbose ...
    #. In case there is a timeout in downloading mpfr package with conan from gnu.org:
       In the file::

            C:\Users\<User name>\.conan\data\mpfr\4.1.0\_\_\export\conandata.yml

       replace the url: https://ftp.gnu.org/gnu/mpfr/mpfr-4.1.0.tar.gz (click on the link to check if doesn't work)

       with the url: https://www.mpfr.org/mpfr-4.1.0/mpfr-4.1.0.tar.gz
    #. In case the compilation of cgal-python-bindings crashes try increasing the RAM size on your machine
    #. At any other case of failure during installation delete the .conan directories created under and start again::

        C:\
        C:\Users\<User name>\

    #. On linux, if receiving the following error when invoking the gui tools:

            .. code-block::

              Warning: Ignoring XDG_SESSION_TYPE=wayland on Gnome. Use QT_QPA_PLATFORM=wayland to run on Wayland anyway.
              ...

       Then run the following command and then try to use the tools:

            .. code-block::

                export QT_QPA_PLATFORM=wayland