Metadata-Version: 2.1
Name: scenebuilder
Version: 0.2.1
Summary: A simple GUI to create 2D scenes with obstacles and drone paths for multi-agent path planning algorithms
Author: Adrian del Ser
Author-email: adrian.delser@gmail.com
Requires-Python: >=3.11
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Dist: matplotlib (>=3.8.0,<4.0.0)
Requires-Dist: numpy (>=1.26.1,<2.0.0)
Description-Content-Type: text/markdown

# SceneBuilder

## Overview

**SceneBuilder** is a Python package that provides a Matplotlib-based GUI for designing 2D test environments in a 10x10m grid for use in multiagent path planning algorithms. Users can draw polygons to represent obstacles and arrows to indicate the starting and ending points of each agent's path.

<!-- ![Scene Example 1](/assets/scene1.png){width=10 height=10} -->
<p align="center">
  <img src="/assets/scene1.png" alt="First Image" width="40%" />
  <img src="/assets/scene2.png" alt="Second Image" width="40%" />
</p>

## Installation

To install SceneBuilder, run the following command:

```bash
pip install scenebuilder
```

This command installs SceneBuilder along with numpy and matplotlib, ensuring that everything needed to run the GUI is properly set up.

## Prerequisites

SceneBuilder's prerequisites are defined in the pyproject.toml file and include Matplotlib and numpy.

## Quick Start Guide

### Using Command-Line Options

You can use SceneBuilder directly from the command line with the following option:

- `-l`, `--load`: Specify a JSON file path to load an existing scene.

Example usage:

```bash
scenebuilder --load path/to/scene.json
scenebuilder -l     path/to/scene.geojson
```

### In Code

To use SceneBuilder in code, you need to create an instance of the `SceneBuilder` class and invoke the `draw_scene()` method. Below is a simple example to get you started:

```python
from scenebuilder import SceneBuilder

# Create an instance of the SceneBuilder
scene = SceneBuilder()

# Open the GUI to draw a scene
scene.draw_scene()
```

Load in an existing compatible json file for modification:

```python
scene.load_scene("path/to/your_file.json")
scene.draw_scene()
```

## Features

- **Draw Obstacles**: Click within the GUI to place vertices of polygons that represent obstacles. Press Tab to complete an obstacle.
- **Add new obstacle vertices**: To add new vertices, click somewhere on the polygon's perimeter and drag to move the vertex to its desired location.
- **Set Drone Paths**: Click once to place the starting point, and again to place the goal of an agent/drone. An arrow will automatically be drawn from start to goal.
- **Move or adjust existing obstacles/drones**: Obstacles and drones can be moved by clicking and dragging. Drone start and goal points, as well as existing obstacle vertices can be moved in the same way.
- **Switch between Obstacle and Drone Modes**: Press b to switch to building/obstacle mode. Press d to switch to drone/agent mode. Alternatively click the Switch button on the bottom left of the gui.
- **Delete obstacles**: Select the obstacle and press delete or backspace. NOTE this is not yet available for drones.
- **Clear temporary points**: To clear building vertices prior to completing the building, or to remove a drone's starting point before placing the goal, press 'esc' or 'escape'.
- **Undo drone/obstacle placement**: To remove the last obstacle or drone that was placed, press ctrl+z.
- **Reset Scene**: To reset the scene to a blank canvas, click the Reset button in the gui.

## Saving Scenes

Once you have created a scene, you can save it to a JSON or GeoJSON file by clicking the 'Save' button in the GUI. You will then be prompted to select whether you want to use our basic JSON format or GeoGSON.

**_Unless otherwise specified, the file is saved as "scenebuilder.json" in the current working directory._**

## Contributing

Contributions to SceneBuilder are welcome! If you have suggestions for improvements or new features, feel free to create an issue or pull request on our GitHub repository.

