Using discopygal tools
======================
.. sectnum::

Discoypgal has two gui main tools:

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

Running the tools
-----------------
| These tools should be executed from the command line.
| The main way to run the tools if using discopygal as a package is to run the created entrypoints as commands.
| This means just execute the commands (after activating virtual env if needed):

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

                solver_viewer
                scene_designer

    .. tab:: Windows
        ::

                solver_viewer.exe
                scene_designer.exe

If developing or using the sources/repo of discopygal it is possible to directly run these tools with python:

    ::

        python tools/solver_viewer/solver_viewer_main.py
        python tools/scene_designer/scene_designer_main.py


| Another option is to run these tools by "double-clicking" on them.
| If using virtual env it will be found at:

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

            /home/<User name>/.virtualenvs/<virtual env name>/bin/solver_viewer
            /home/<User name>/.virtualenvs/<virtual env name>/bin/scene_designer

    .. tab:: Windows
        ::

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

.. _scene_designer:

Scene designer
--------------
A tool that is able to create and edit graphically scenes and save them as json files for future use.
You can create a new scene or load an already existed one and then save it.
Some tips:

- Read the bottom banner of the gui for instructions
- Add points with **right** click

.. _solver_viewer:

Solver viewer
-------------
A tool that enables loading pre-created scenes and solvers,
running the solver to solve the scene and visualize the paths, graphs and motion.
The tool has three parameters:

1. scene -
    The scene to solve as a json file. It is loaded and presented graphically.
2. solver -
    The solver object/class to use to solve the scene. The name of the solver class as a string.
3. solver file -
    An external module that contains additional solvers to upload to the simulation.
    After uploading this file it is possible to select also the solvers in contains besides the default solvers.
    This is the path of the module to upload.

There are several ways to run this tool and pass it its parameters.
Of course it is possible to combine the different methods and pass every parameter individually as you wish.
After setting all parameters it is possible to run the solver and then visualize the paths if is was able to find.

The available ways to use the tool are:

From gui
++++++++
Simply run from command line the command of 'solver_viewer'.


The gui will open and from it, click the buttons to upload scene file, select solver type and
upload solver file (if necessary)

From command line
+++++++++++++++++
It is possible to pass parameters from command line, and it will be loaded at startup.

::

    usage: solver_viewer [-h] [-sc SCENE] [-sl SOLVER] [-sf SOLVER_FILE]

    Solve a 2D scene

    options:
      -h, --help            show this help message and exit
      -sc SCENE, --scene SCENE
                            Path to json scene file
      -sl SOLVER, --solver SOLVER
                            Name of solver to use
      -sf SOLVER_FILE, --solver-file SOLVER_FILE
                            Path of solver file to upload

Run the command::

    solver_viewer -h

to see all options.
All options are optional, an option that isn't set won't be loaded at startup and can be loaded manually afterwards from the gui.
Note that it is possible to already choose in this step a solver from the given solver file.

.. _solver_viewer_script:

From script
+++++++++++
It is possible to invoke the gui from a python script with the function :func:`~discopygal_tools.solver_viewer.solver_viewer_main.start_gui` from file :file:`discopygal_tools.solver_viewer`.

The function receives three parameters, which are all optional (won't set anything at startup if not given)

#. scene - The scene to upload. May be one of following:

    #. :class:`str` that is a path to json file of scene
    #. Object from type :class:`~discopygal.solvers.Scene`
#. solver - The solver to upload. May be one of the following:

    #. A string with the name of one of the loaded solver classes (must also provide a the solver module if isn't built-in)
    #. An object from a class that inherits from :class:`~discopygal.solvers.Solver.Solver`
    #. A class that inherits from :class:`~discopygal.solvers.Solver.Solver`
#. solver file - A :class:`str` that is the path to a module with solvers to upload

Note that it is possible to already choose in this step a solver from the given solver file.

Using this function in a script will be like this::

    from discopygal_tools.solver_viewer import start_gui

    start_gui()