|
1 | | -# SWAGGER: Sparse WAypoint Graph Generator for Efficient Routing |
| 1 | +# SWAGGER: Sparse WAypoint Graph Generation for Efficient Routing |
| 2 | + |
| 3 | +[](https://docs.python.org/3/whatsnew/3.10.html) |
| 4 | +[](https://releases.ubuntu.com/22.04/) |
| 5 | +[](https://pre-commit.com/) |
| 6 | + |
| 7 | +A Python package that generates sparse waypoint graphs from occupancy grid maps for route planning. |
| 8 | + |
| 9 | +<img src="docs/images/generation_in_action.gif" alt="Graph Generation in Action" height="300"/> |
| 10 | + |
| 11 | +See [algorithm overview](docs/algorithm.md) for an introduction of the method. |
| 12 | + |
| 13 | + |
| 14 | +## Table of Contents |
| 15 | +- [Algorithm Overview](docs/algorithm.md) |
| 16 | +- [System Requirements](#system-requirements) |
| 17 | +- [Installation](#installation) |
| 18 | + - [Set up the Environment](#set-up-the-environment) |
| 19 | + - [Install Package](#install-package) |
| 20 | +- [Usage](#usage) |
| 21 | + - [Data Prepration](#data-preparation) |
| 22 | + - [Tutorial and Examples](#tutorial-and-examples) |
| 23 | + - [Command Line Interface](#command-line-interface) |
| 24 | + - [Evaluation](#evaluation) |
| 25 | + - [REST API](#rest-api-service) |
| 26 | + - [Containerized Environment](#containerized-environment) |
| 27 | +- [Development](#development) |
| 28 | + - [Testing](#testing) |
| 29 | + - [Linting and Formatting](#linting-and-formatting) |
| 30 | + |
| 31 | + |
| 32 | +## System Requirements |
| 33 | +* Python 3.10 or newer |
| 34 | +* [CUDA 12.5](https://developer.nvidia.com/cuda-12-5-0-download-archive) or newer (including NVIDIA CUDA toolkit) |
| 35 | + |
| 36 | +## Installation |
| 37 | + |
| 38 | +### Set up the Environment |
| 39 | + |
| 40 | +Choose one of the following methods to set up your environment: |
| 41 | + |
| 42 | +1. Using Conda |
| 43 | +```bash |
| 44 | +conda create -n swagger python=3.10 |
| 45 | +conda activate swagger |
| 46 | +``` |
| 47 | + |
| 48 | +2. Using Virtual Environment |
| 49 | +```bash |
| 50 | +python -m venv swagger |
| 51 | +source swagger/bin/activate |
| 52 | +``` |
| 53 | + |
| 54 | + |
| 55 | +Clone the repository: |
| 56 | + |
| 57 | + |
| 58 | + |
| 59 | +```bash |
| 60 | +git clone git@github.com:nvidia-isaac/SWAGGER.git |
| 61 | +cd SWAGGER |
| 62 | +git lfs pull |
| 63 | +``` |
| 64 | + |
| 65 | +### Install Package |
| 66 | +```bash |
| 67 | +sudo apt update && sudo apt install -y libgl1-mesa-glx libglib2.0-0 |
| 68 | +pip install -e . # Install in development mode |
| 69 | +``` |
| 70 | + |
| 71 | +## Usage |
| 72 | + |
| 73 | +### Data Preparation |
| 74 | + |
| 75 | +The following data is required for waypoint graph generation: |
| 76 | + |
| 77 | +* **Occupancy Grid Map**: |
| 78 | + * **Image Format**: A grayscale image where each pixel represents the occupancy probability in a 2D world: |
| 79 | + * 0 (black) = completely occupied |
| 80 | + * 255 (white) = completely free |
| 81 | + * **Occupancy Threshold**: A value that determines which pixels are considered free space. Pixels with values above this threshold will be used for graph generation. |
| 82 | + |
| 83 | +* **Robot Parameters**: |
| 84 | + * **Safety Distance**: The minimum distance (in meters) that graph nodes and edges must maintain from obstacles to ensure safe robot navigation. |
| 85 | + |
| 86 | +* **Coordinate Transform**: Parameters to convert pixel coordinates to real-world coordinates: |
| 87 | + * **Resolution**: The size of each pixel in meters (meters/pixel) |
| 88 | + * **X Offset**: The X coordinate of the bottom-left pixel in the world frame in meters. |
| 89 | + * **Y Offset**: The Y coordinate of the bottom-left pixel in the world frame in meters. |
| 90 | + * **Rotation**: Rotation angle from image frame to world frame in radians. |
| 91 | + |
| 92 | +#### Coordinate Transform |
| 93 | + |
| 94 | +In the image frame: |
| 95 | +- Origin (0,0) is at the top-left corner |
| 96 | +- X-axis points down (rows) |
| 97 | +- Y-axis points right (columns) |
| 98 | + |
| 99 | +When converting from image to world coordinates: |
| 100 | +1. Image coordinates are scaled by the resolution to convert from pixels to meters |
| 101 | +2. Rotation is applied around the origin using the provided rotation angle |
| 102 | +3. X and Y offsets are added to translate the coordinates to the final world position |
| 103 | + |
| 104 | + |
| 105 | + |
| 106 | +### Command Line Interface |
| 107 | +Generate a waypoint graph from an occupancy grid map: |
| 108 | +```bash |
| 109 | +python scripts/generate_graph.py \ |
| 110 | + --map-path <path_to_map.png> \ |
| 111 | + --resolution <meters_per_pixel> \ |
| 112 | + --safety-distance <meters> \ |
| 113 | + --output-dir <output_directory> |
| 114 | +``` |
| 115 | + |
| 116 | +Default parameters: |
| 117 | +- Map: `maps/carter_warehouse_navigation.png` |
| 118 | +- Resolution: 0.05 meters/pixel |
| 119 | +- Safety distance: 0.3 meters |
| 120 | + |
| 121 | +Outputs: |
| 122 | +- `<output_dir>/waypoint_graph.png`: Visualization of the generated graph |
| 123 | +- `<output_dir>/graph.gml`: Graph data in GML format |
| 124 | + |
| 125 | +### Evaluation |
| 126 | + |
| 127 | +To evaluate the graph, see the tutorial on [evaluation](docs/evaluation.md). |
| 128 | + |
| 129 | +### REST API Service |
| 130 | + |
| 131 | +Start the service locally: |
| 132 | +```bash |
| 133 | +python scripts/rest_api.py |
| 134 | +``` |
| 135 | + |
| 136 | +The service will be available at `http://localhost:8000`. Visit `http://localhost:8000/v1/docs` in your browser to view the interactive API documentation. If accessing from a different machine, replace `localhost` with the host name or the IP address of the server running the REST API. For more information about the REST API, check out the [tutorial](docs/tutorial.md#rest-api). |
| 137 | + |
| 138 | +The REST API is also available as a docker compose service. |
| 139 | + |
| 140 | +```bash |
| 141 | +cd docker |
| 142 | +docker compose build swagger |
| 143 | +docker compose up rest-api |
| 144 | +``` |
| 145 | + |
| 146 | +We provide a sample script, `scripts/test_api_client.py`, to demonstrate the usage the REST API service. With the REST API service running in a separate terminal, run the following command in your virtual environment: |
| 147 | +```bash |
| 148 | +python scripts/test_api_client.py --map_path maps/carter_warehouse_navigation.png |
| 149 | +``` |
| 150 | + |
| 151 | + |
| 152 | +### Tutorial |
| 153 | + |
| 154 | +This [tutorial](docs/tutorial.md) provides a comprehensive guide on how to use the SWAGGER library, including graph building, visualization, route finding, parameter tuning, and using both the Python API and REST API interfaces. |
| 155 | + |
| 156 | + |
| 157 | +## Development |
| 158 | + |
| 159 | +### Testing |
| 160 | +```bash |
| 161 | +python -m unittest |
| 162 | +``` |
| 163 | + |
| 164 | +### Linting and Formatting |
| 165 | +This project uses pre-commit hooks for linting and formatting: |
| 166 | +```bash |
| 167 | +pip install pre-commit |
| 168 | +pre-commit install |
| 169 | +pre-commit run --all-files # Run manually |
| 170 | +``` |
0 commit comments