Using discopygal package
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
1. 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:
/home/<User name>/.virtualenvs/<virtual env name>/bin/python
C:\Users\<User name>\.virtualenvs\<virtual env name>\Scripts\python.exe
2. Components
As can be seen in these docs, the package consists of the following components:
bindings - Imports from CGALPY that discopygal uses: CGALPY Bindings
experiments - Utilities for making experiments: Experiments Module
gui - GUI utilities for visualizations: GUI Documentation
geometry_utils - Basic computational geometric functions: Geometry Utilities
solvers - Motion planning solving algorithms: Solvers Documentation
3. Creating a solver
discopygal.solvers.Solver
which every solver must inherit from.Solver
and implements a motion planning algorithm.discopygal.solvers.Solver.load_scene()
- The function that gets a scene object and does necessary preprocessing if needed. Call the base function to save the scene inscene
discopygal.solvers.Solver.solve()
- The function that solves the loaded scene, plans the motion and returns the robots’ pathsdiscopygal.solvers.Solver.get_arguments()
- Return a dict of all needed arguments (parameters) by the solver in the following form{ argument_name: (description, default value, type), ... }
- argument_name: The name of the solver’s attribute
Important
Note that the corresponding parameter in the
__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
discopygal.solvers.Solver.get_graph()
(Optional) - Return all the constructed graph (can be viewed in solver_viewer)discopygal.solvers.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 Solver viewer and use them there.
Check the Solver
class documentation for a list of all the functions it contains.
3.1. Examples
Here are some basic examples to understand how to build a solver class and use it:
3.1.1. 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
from discopygal.solvers import Solver
class EmptySolver(Solver):
def solve(self):
self.log("Solving...")
return None
def load_scene(self, scene):
pass
@staticmethod
def get_arguments():
return {}
3.1.2. 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
Solver Class code
import random
import networkx as nx
from discopygal.solvers import Solver, Robot, Path, PathPoint, PathCollection
from discopygal.geometry_utils.bounding_boxes import calc_scene_bounding_box
from discopygal.geometry_utils.collision_detection import ObjectCollisionDetection
from discopygal.bindings import *
class RandomSolver(Solver):
def __init__(self, num_landmarks, num_connections):
super().__init__()
# Initializing properties of solver
self.num_landmarks = num_landmarks
self.num_connections = num_connections
self._collision_detection = {}
self._start = None
self._end = None
self._roadmap = None
def _sample_random_point(self):
# Randomize a point inside the boundaries of the scene
x = random.uniform(self._x_min, self._x_max)
y = random.uniform(self._y_min, self._y_max)
return Point_2(FT(x), FT(y))
def _create_random_point(self, robots):
point = self._sample_random_point()
# Set a point that for all robots it won't collide with an obstacle
is_valid_point = False
while not is_valid_point:
point = self._sample_random_point()
is_valid_point = all([self._collision_detection[robot].is_point_valid(point) for robot in robots])
return point
def _create_random_roadmap(self, robots):
roadmap = nx.Graph()
# Add random points
for _ in range(self.num_landmarks):
point = self._create_random_point(robots)
roadmap.add_node(point)
# Add random connections
for _ in range(self.num_connections):
v, u = random.sample(roadmap.nodes, 2)
roadmap.add_edge(v, u, weight=1)
for robot in robots:
# Add starting point of robot to the graph
roadmap.add_node(robot.start)
# Connect start to a random point
roadmap.add_edge(robot.start, *random.sample(roadmap.nodes, 1), weight=1)
# Add ending point of robot to the graph
roadmap.add_node(robot.end)
# Connect to end to a random point
roadmap.add_edge(robot.end, *random.sample(roadmap.nodes, 1), weight=1)
return roadmap
def load_scene(self, scene):
super().load_scene(scene)
self._x_min, self._x_max, self._y_min, self._y_max = calc_scene_bounding_box(self.scene)
# Build collision detection for each robot
for robot in self.scene.robots:
self._collision_detection[robot] = ObjectCollisionDetection(scene.obstacles, robot)
def get_graph(self):
return self._roadmap
def solve(self):
self.log("Solving...")
self._roadmap = self._create_random_roadmap(self.scene.robots)
path_collection = PathCollection() # Initialize PathCollection (stores the path for each robot)
for i, robot in enumerate(self.scene.robots):
self.log(f"Robot {i}")
# Check if there is a possible path for the robot in the graph
if not nx.algorithms.has_path(self._roadmap, robot.start, robot.end):
self.log(f"No path found for robot {i}")
return PathCollection()
# Get the shortest path for the robot
found_path = nx.algorithms.shortest_path(self._roadmap, robot.start, robot.end)
points = [PathPoint(point) for point in found_path] # Convert all points to PathPoints (to make a path out of them)
path = Path(points) # Make a path from all PathPoints
path_collection.add_robot_path(robot, path) # Add the current path for the current robot to the path collection
self.log("Successfully found a path for all robots")
return path_collection
@staticmethod
def get_arguments():
# Returns the configurable properties of the solver (presented in gui)
# in format of: 'property_name': (Description, Default value, Type)
return {
'num_landmarks': ('Number of points', 5, int),
'num_connections': ('Number of connections', 5, int),
}
Use solver in script
import json
from discopygal.solvers import Scene
from discopygal.solvers.verify_paths import verify_paths
from discopygal_tools.solver_viewer import start_gui
from RandomSolver import RandomSolver
with open('basic_scene.json', 'r') as fp:
scene = Scene.from_dict(json.load(fp))
# "Solve" the scene (find paths for the robots)
solver = RandomSolver(num_landmarks=10, num_connections=10)
solver.load_scene(scene)
path_collection = solver.solve() # Returns a PathCollection object
# Print the points of the paths
for i, (robot, path) in enumerate(path_collection.paths.items()):
print("Path for robot {}:".format(i))
for j, point in enumerate(path.points):
print(f'\t Point {j:2}: ', point.location) # point is of type PathPoint, point.location is CGALPY.Ker.Point_2
print()
result, reason = verify_paths(scene, path_collection)
print(f"Are paths valid: {result}\t{reason}")
# Optional - Open solver_viewer with our solver and scene
# Option 1 - Use solve object we made:
print("First gui")
start_gui(scene, solver)
# Option 2 - Use solver's class type to create a new one:
print("Second gui")
start_gui(scene, RandomSolver)
# Option 3 - Use solver's class name to create a new one (must pass solver's module):
print("Third gui")
start_gui(scene, "RandomSolver", "RandomSolver.py")
# Option 4 - Passing the path to the scene json file
print("Fourth gui")
start_gui("basic_scene.json", solver)
Invoke Solver viewer with solver from command line
solver_viewer -sl RandomSolver -sf RandomSolver.py -sc simple_motion_planning_scene.json
4. Creating a scene
discopygal.solvers.Scene
object during the script and use it (as was shown in the example).discopygal.solvers.Scene
class documentation to be familiar with the available methods and options.5. Discopygal starter
Solver
class and it is required to implement by yourself solvers that will inherit from this class.