.. _using_package:

Using discopygal package
========================
.. sectnum::

In this page it will be explained what the discopygal package contains and
how to use it when writing scripts.

The main abilities of the package are:

#. Create scenes and visualize them
#. Create motion planning algorithms
#. Environment to check and visualize the motion planning algorithms on actual scenes

How to use the package?
-----------------------

Once installed (in virtual environment or directly on regular environment)
the package can be imported from anywhere as a regular package::

    import discopygal

or with the "from" syntax for specific modules::

    from discopygal... import ...

If the package was installed in virtual env don't forget to activate it first::

    pipenv shell

To deactivate::

    exit


If working with an IDE it is also possible to run your scripts from there like
any other script.
Again, if using virtual env configure first the python interpreter in your IDE to be
the right one from the virtual env.
If using pipenv, the python interpreter of the virtual env will be found at:

.. tabs::
    .. tab:: Unix
        ::

            /home/<User name>/.virtualenvs/<virtual env name>/bin/python

    .. tab:: Windows
        ::

            C:\Users\<User name>\.virtualenvs\<virtual env name>\Scripts\python.exe

Components
----------
As can be seen in these docs, the package consists of the following components:

- bindings - Imports from CGALPY that discopygal uses: :doc:`../code/bindings`
- experiments - Utilities for conducting experiments: :doc:`../code/experiments/experiments`
- gui - GUI utilities for visualizations: :doc:`../code/gui/gui`
- geometry_utils - Basic computational geometric functions: :doc:`../code/geometry_utils/geometry_utils`
- solvers_infra - Infrastructure and utilities required for creating a solver for motion planning (like base classes): :doc:`../code/solvers_infra/solvers_infra`
- solvers - Actual motion planning solving algorithms: :doc:`../code/solvers/solvers`

.. _solver:

Creating a solver
-----------------

| One of the main options discopygal offers is an opportunity to write your own motion planning algorithm which is referred as "Solver".
| Discopygal has a basic solver class :class:`discopygal.solvers_infra.Solver.Solver` which every solver must inherit from.
| Therefore, a solver is simply a class that inherits from :class:`~discopygal.solvers_infra.Solver.Solver` and implements a motion planning algorithm.
| In every solver class it is required to implement the following functions:

- :func:`discopygal.solvers_infra.Solver.Solver.load_scene` - The function that gets a scene object and does necessary preprocessing if needed. Call the base function to save the scene in :attr:`scene`
- :func:`discopygal.solvers_infra.Solver.Solver._solve` - The function that solves the loaded scene, plans the motion and returns the robots' paths
- :func:`discopygal.solvers_infra.Solver.Solver.get_arguments` - Return a dict of all needed arguments (parameters) by the solver in the following form

        .. code-block::

            {
                argument_name: (description, default value, type),
                ...
            }

    * | argument_name: The name of the solver's attribute

        .. important::
            Note that the corresponding parameter in the :func:`__init__` function of the solver **must** also have also this name

    *  description: The label that will be seen in the gui
    *  default value: The default value that will be set for this argument
    *  type: The type of the argument
- :func:`discopygal.solvers_infra.Solver.Solver.get_graph` (Optional) - Return all the constructed graph (can be viewed in solver_viewer)
- :func:`discopygal.solvers_infra.Solver.Solver.get_arrangement` (Optional) - Return an arrangement (can be viewed in solver_viewer)

After creating your solver class, you can initialize solver objects from it and use them directly to solve scenes or load them to
:ref:`Solver viewer <solver_viewer>` and use them there.

Check the :class:`~discopygal.solvers_infra.Solver.Solver` class documentation for a list of all the functions it contains.

Examples
~~~~~~~~
| Here are some basic examples to understand how to build a solver class and use it.
| Read all of them since they all together show the various options and ways to use the module.

Empty Solver
++++++++++++
An empty solver that doesn't do anything, it doesn't return any paths and therefore of course doesn't really solve the scene.
It shows the minium functions that need to be implemented to create a valid solver

.. literalinclude:: ../../examples/basic_examples/EmptySolver.py


Basic Solver
++++++++++++

A basic solver the implements :func:`_solve` function in a naive way.

.. collapse:: BasicSolver Class code

    .. literalinclude:: ../../examples/basic_examples/BasicSolver.py
        :caption: BasicSolver.py

|

.. _random_solver:

Random Solver
+++++++++++++
This is an example for a solver that creates randomized paths by picking randomized valid points in the scene,
creating a graph from them by picking random connections (the roadmap) and then searching for the shortest path for each robot
(from it's start point to it's end point)
Of course this also isn't a good solver that produces valid paths (check with the 'Verify paths' button)
but it is possible to draw the paths and run the animation

.. collapse:: Solver Class code

    .. literalinclude:: ../../examples/basic_examples/RandomSolver.py
        :caption: RandomSolver.py

.. collapse:: Use solver in script

    .. literalinclude:: ../../examples/basic_examples/random_solver_example.py
        :caption: random_solver_example.py

.. collapse:: Invoke Solver viewer with solver from command line

    .. code-block::

        solver_viewer -sl RandomSolver -sf RandomSolver.py -sc simple_motion_planning_scene.json

|

.. _scene:

Creating a scene
----------------

| Another main issue is to create a scene.
| There are two ways to do this, the first is to create a json file interactively with :ref:`Scene designer <scene_designer>` and load it and the second is to directly to create a :class:`discopygal.solvers_infra.Scene` object during the script and use it (as was shown in the :ref:`example <example>`).
| Check the :class:`discopygal.solvers_infra.Scene` class documentation to be familiar with the available methods and options.

Discopygal starter
------------------

| Discopygal starter is exactly the same to the regular discopygal except it doesn't contain any pre-written solver.
| All other usage and tools are the same.
| It has the basic abstract :class:`~discopygal.solvers_infra.Solver` class and it is required to implement by yourself solvers that will inherit from this class.
| If using discopygal-starter and discopygal make sure to install them in two different virtual envs or otherwise uninstall the first before installing the second version.