.. _using-tools-solver-viewer: Using The Solver Viewer ============================== The **Solver Viewer** is a graphical tool for loading motion-planning scenes, selecting and configuring solvers, running them, and visualizing the resulting paths and roadmap graphs. It is the primary tool for interacting with and evaluating any solver written for DiscoPygal. This guide covers every panel, toolbar action, and display option so that you can go from a raw scene file to an animated solution in a single session. The toolbar icons shown below come from the Solver Viewer resource folder. .. |icon-open-scene| image:: ../../tools/solver_viewer/resources/open_scene.png :height: 16 .. |icon-open-solver| image:: ../../tools/solver_viewer/resources/open_solver.png :height: 16 .. |icon-solve| image:: ../../tools/solver_viewer/resources/solve.png :height: 16 .. |icon-play| image:: ../../tools/solver_viewer/resources/play.png :height: 16 .. |icon-pause| image:: ../../tools/solver_viewer/resources/pause.png :height: 16 .. |icon-stop| image:: ../../tools/solver_viewer/resources/stop.png :height: 16 .. |icon-paths| image:: ../../tools/solver_viewer/resources/paths.png :height: 16 .. |icon-graph| image:: ../../tools/solver_viewer/resources/graph.png :height: 16 .. |icon-arrangement| image:: ../../tools/solver_viewer/resources/arrangement.png :height: 16 .. |icon-bounding-box| image:: ../../tools/solver_viewer/resources/bounding_box.png :height: 16 .. |icon-grid| image:: ../../tools/solver_viewer/resources/grid.png :height: 16 .. |icon-verify| image:: ../../tools/solver_viewer/resources/verify.png :height: 16 Prerequisites ------------- Complete: #. :doc:`../tutorials/install/prerequisites` #. :doc:`../tutorials/install/installation` #. Build a scene with the :ref:`Scene Designer `, or use one of the bundled example scenes. .. _solver-viewer-launch: Step 1: Launch the Solver Viewer --------------------------------- Activate your virtual environment and start the tool. .. tabs:: .. tab:: Linux / macOS .. code-block:: bash source .venv/bin/activate solver_viewer .. tab:: Windows (PowerShell) .. code-block:: powershell .\.venv\Scripts\Activate.ps1 solver_viewer.exe The window opens with an empty canvas titled **"DiscoPygal Solver Viewer"**. You can also pass a scene and solver directly at launch — see :ref:`solver-viewer-cmdline` below. .. _solver-viewer-concepts: Step 2: Understand What the Viewer Manages ------------------------------------------- The solver viewer works with three kinds of data at runtime. The scene ~~~~~~~~~ A scene is loaded from a JSON file (or passed in as a :class:`~discopygal.solvers_infra.Scene` object from a script). It contains the workspace geometry, robot definitions, and start/goal configurations. The path to the currently loaded scene is shown read-only in the top bar. Once a scene is loaded, its metadata — version, recommended solvers, and description — appears in the properties panel on the right. The solver ~~~~~~~~~~ A solver is a class that inherits from :class:`~discopygal.solvers_infra.Solver.Solver`. Built-in solvers are registered automatically at startup. Additional solvers can be imported from any Python file at any time. When a solver is selected, its configurable parameters appear as labelled text fields in the left-hand panel. The solver's class name is shown in the ``Solver`` label at the top of that panel. The solution ~~~~~~~~~~~~ .. image:: ../images/scene_solution.png :align: center After a solver runs successfully, the viewer holds the computed paths, the roadmap graph, an optional CGAL arrangement, and an optional bounding-box graph. Each of these can be toggled on and off independently in the canvas. .. _solver-viewer-ui: Step 3: Tour the User Interface --------------------------------- Toolbar actions ~~~~~~~~~~~~~~~ |icon-open-scene| **Open Scene** Open a ``.json`` scene file from disk. |icon-open-solver| **Open Solver** Open the solver selection dialog. |icon-solve| **Solve** Run the selected solver on the loaded scene. |icon-play| |icon-pause| **Play / Pause** Start the path animation, or pause it if it is already running. The icon toggles between a play arrow and a pause symbol. |icon-stop| **Stop** Stop any running animation or solver thread and reset robots to their start positions. Turns red while a solver is executing. |icon-paths| **Show Paths** Toggle the computed paths drawn as coloured line segments on the canvas. |icon-graph| **Show Graph** Toggle the solver's roadmap graph overlay. |icon-arrangement| **Show Arrangement** Open a separate window displaying the CGAL arrangement, if the solver provides one. |icon-bounding-box| **Show Bounding Box** Toggle the solver's bounding-box graph as a grey wireframe overlay. |icon-grid| **Grid** Toggle a reference grid over the canvas. |icon-verify| **Verify** Check that the loaded paths are valid for the current scene. **About** Open the about dialog. solver settings ~~~~~~~~~~~~~~~ .. image:: ../images/scene_settings.png :align: center When a solver is selected, its parameters are generated dynamically in the left-hand panel as a scrollable list of labelled text fields. Each field shows the parameter's description and its current value. Edit any field before clicking **Solve** to override the default. The panel is scrollable when a solver has many parameters. scene metadata ~~~~~~~~~~~~~~ After a scene is loaded, the right-hand panel shows three read-only fields drawn directly from the scene's JSON metadata: +-------------------+-------------------------------------------------------+ | Field | Content | +===================+=======================================================+ | ``version`` | The DiscoPygal version that created the scene. | +-------------------+-------------------------------------------------------+ | ``solvers`` | Solver class names recommended for this scene. | +-------------------+-------------------------------------------------------+ | ``scene details`` | Human-readable description of the scene. | +-------------------+-------------------------------------------------------+ Log panel ~~~~~~~~~ A text area at the bottom of the window receives all messages written by the solver via its ``log()`` method, including progress updates and the total calculation time reported at the end of every run. Choose Robots panel ~~~~~~~~~~~~~~~~~~~~ Clicking the **Choose Robots** button reveals a scrollable list of checkboxes, one per robot in the loaded scene. This panel is hidden until a scene is loaded. See :ref:`solver-viewer-robots` for details. Speed slider ~~~~~~~~~~~~ The horizontal slider below the toolbar controls animation playback speed. Moving it takes effect immediately, adjusting the duration of every remaining animation step proportionally — even while the animation is playing. Canvas ~~~~~~ The large central area renders the scene, overlays, and animated robots. Moving the mouse over the canvas shows the current scene coordinates in a small floating label. Double-clicking also updates the coordinate display. .. _solver-viewer-load-scene: Step 4: Load a Scene --------------------- Click **Open Scene** in the toolbar, or use *File → Open Scene*, and select a ``.json`` scene file. The viewer clears any existing scene, paths, and graph overlays, then draws the new scene on the canvas. The scene path appears in the read-only bar at the top of the window and the metadata panel on the right is populated. If the file cannot be found, or if its JSON is malformed, an error dialog describes the problem and the canvas is left empty. A scene can also be passed at launch or from a script — see :ref:`solver-viewer-cmdline` and :ref:`solver-viewer-script`. .. _solver-viewer-load-solver: Step 5: Load and Configure a Solver ------------------------------------- Click **Open Solver** in the toolbar, or use *File → Open Solver*, to open the solver dialog. It contains two controls: * A **dropdown list** pre-populated with every built-in and previously imported solver class. Select a solver from the list and click **Select**. * A **Browse** button that opens a file picker. Choose a ``.py`` file containing one or more solver classes. The file is imported immediately, any new solvers are registered, and the dropdown updates to include them. A confirmation dialog reports how many solvers were imported. After selecting a solver, the left-hand panel updates to show that solver's parameters as editable text fields. Adjust any field as needed before running. .. _solver-viewer-solve: Step 6: Run the Solver ----------------------- Click **Solve** in the toolbar. The solver runs in a background thread so the GUI remains responsive throughout. While running: * All toolbar buttons except **Stop** are disabled. * The **Stop** button turns red. * Progress messages from the solver appear in the log panel in real time. When the solver finishes, the toolbar re-enables and the log panel reports the total calculation time. If an exception occurs inside the solver, the error and traceback are written to the log panel and the run is aborted cleanly. To cancel a running solver at any time, click **Stop**. The thread is terminated, the toolbar re-enables, and robots are reset to their start positions. .. _solver-viewer-animate: Step 7: Play the Animation --------------------------- Once paths are available, click **Play** to animate the robots along their computed routes. All robots move in parallel, each advancing one path edge at a time. The **Play** button icon switches to a pause symbol while the animation runs. * Click **Play** again to pause mid-animation. The icon reverts to a play arrow. * Click **Play** once more to resume from the current position. * Click **Stop** to end the animation and reset all robots to their start positions. * Drag the speed slider left or right at any time to slow down or speed up the remaining steps. When the animation completes naturally, the play button resets automatically. Animation speed is calculated per edge: the duration of each step is proportional to the Euclidean distance between the source and target positions, divided by the current slider value. Path points that carry a ``speed`` data field use that value as an additional multiplier. .. _solver-viewer-overlays: Step 8: Use the Visual Overlays --------------------------------- Show Paths ~~~~~~~~~~ Click **Show Paths** to draw the computed paths directly on the canvas as coloured line segments. Each robot's path is drawn in that robot's own colour (taken from the ``color`` field in the robot's data). Click the button again to remove the overlay. The overlay respects the robot checkboxes described in :ref:`solver-viewer-robots`. Show Graph ~~~~~~~~~~ Click **Show Graph** to overlay the solver's roadmap graph on the canvas. Each edge is drawn in the colour stored in the graph's edge data, defaulting to red when no colour is specified. Vertex connection points are rendered as small red discs. Click the button again to clear the graph overlay. The overlay also respects the robot checkboxes. Show Arrangement ~~~~~~~~~~~~~~~~ If the solver provides a CGAL arrangement via :func:`~discopygal.solvers_infra.Solver.Solver.get_arrangement`, clicking **Show Arrangement** opens a separate window to display it. Faces with data value ``>= 0`` are coloured green; faces with data value ``< 0`` are coloured red. The button has no effect if the solver does not expose an arrangement. Show Bounding Box ~~~~~~~~~~~~~~~~~ If the solver provides a bounding-box graph via :func:`~discopygal.solvers_infra.Solver.Solver.get_bounding_box_graph`, clicking **Show Bounding Box** overlays it as a semi-transparent grey wireframe. Click again to remove it. Grid ~~~~ Click **Grid** to toggle a reference grid over the canvas. The grid spacing adapts automatically to the current zoom level. This is a display-only aid and does not affect the scene or solver. .. _solver-viewer-robots: Step 9: Filter by Robot ------------------------ When a scene contains multiple robots, a **Choose Robots** button becomes available in the toolbar. Clicking it shows or hides a panel listing one checkbox per robot, labelled *Robot 0*, *Robot 1*, and so on. All checkboxes are checked by default. Unchecking a robot hides its contribution from both the graph overlay and the path overlay. The canvas updates immediately: if the graph or paths are currently displayed, they are redrawn with the updated selection. Re-checking a robot restores it without requiring another solve. Click **Choose Robots** again (the button label changes to **Hide** while the panel is open) to collapse the panel. .. _solver-viewer-verify: Step 10: Verify the Paths -------------------------- Click **Verify** in the toolbar after a solve to run a collision and validity check on the computed paths against the current scene. A message box reports either success or the specific reason the paths are invalid. This is useful when developing a new solver to confirm that the returned paths are geometrically correct before optimising for performance. .. _solver-viewer-cmdline: Command-line usage ------------------ You can supply a scene and solver at startup so the viewer opens ready to run:: solver_viewer --help The full list of options:: solver_viewer [-h] [-sc SCENE] [-sl SOLVER] [-sf SOLVER_FILE] optional arguments: -sc SCENE, --scene SCENE Path to a JSON scene file -sl SOLVER, --solver SOLVER Name of the solver class to load -sf SOLVER_FILE, --solver-file SOLVER_FILE Path to a Python file containing additional solvers All parameters are optional. Anything not supplied on the command line can be loaded from within the GUI after launch. .. _solver-viewer-script: Script usage ------------ You can launch the solver viewer from a Python script and pre-load a scene and/or solver:: from discopygal_tools.solver_viewer import start_gui from discopygal.solvers_infra import Scene # Bare launch — load everything from the GUI start_gui() # Pre-load a scene file and a built-in solver by name start_gui(scene="my_scene.json", solver="PRM") # Pre-load a Scene object and a solver class from discopygal.solvers import PRM scene = Scene.from_file("my_scene.json") start_gui(scene=scene, solver=PRM) # Pre-load a solver instance with custom parameters solver = PRM(num_landmarks=500, k=15) start_gui(scene="my_scene.json", solver=solver) # Import extra solvers from a file before the GUI opens start_gui(scene="my_scene.json", solver_file="my_solvers.py") The ``solver`` argument accepts three forms: * A **string** matching a registered solver class name (e.g. ``"PRM"``). * A **class** that inherits from :class:`~discopygal.solvers_infra.Solver.Solver`. * A **solver instance** already constructed with the desired parameters. If the solver name is not recognised, an error dialog lists the valid solver names and the GUI opens without a pre-selected solver. What to Read Next ----------------- * :doc:`tutorial_first_solver` – implement your first custom solver class. * :ref:`using-tools-scene-designer` – full reference for the scene designer.