Home

This wiki documents various functionalities implemented in gplanetary_nav. Each section follows a logical order. If you are a first-time user, it is recommended you go through the wiki in that order.

If you haven't done so already, set up the conda environment as it is documented in the repository's README.

1. Dataset configuration

Dataset path setup

This library loads collections of terrain/irradiance maps and related parameters of specific planetary surface regions. We refer to such collections as "datasets". Each dataset is stored in a dedicated directory.

For convenience, we strongly recommended that you save all datasets in a single parent directory. To avoid hard-coded paths in your code, you can save the path to this parent directory in an environment variable (say, GNAV_DATASET_PATH) in the current conda environment:

# (make sure the conda environment is active!)
conda env config vars set GNAV_DATASET_PATH=/path/to/datasets

Deactivate and reactivate the conda environment and verify whether the environment variable now exists (it only exists when the conda environment is active):

echo $GNAV_DATASET_PATH

Sample dataset download

Download two samples datasets (Jezero Crater (Mars) and the Cabeus region (lunar south pole)) that were pre-generated (81 MB total):

# Jezero dataset (Mars), 920 KB
# (compressed / download size: 541 KB)
cd
gdown 1ebTToW8-xR1srLfZ1DXjnZO90rpR7bZE
tar -xzvf JEZ5_sample.tar.gz --directory $GNAV_DATASET_PATH

# Cabeus dataset (lunar south pole), 280 MB
# (compressed / download size: 85 MB)
gdown 1-rH9IGvx0m00xxV5CgBXz7pkeN_0B67F
tar -xzvf CAB240_sample.tar.gz --directory $GNAV_DATASET_PATH

Anatomy of a dataset

All datasets (including those downloaded above) must follow a simple file structure. Refer to the dataset formatting page for more information.

2. Usage guides

Site loader

The site loader is a module that loads specific terrain maps of a dataset. gplanetary_nav can handle different types of maps (elevation, slope, aspect, terrain types, no-go binary maps, and more). For additional information and demonstrations, refer to the site loader guide page.

Planning graph

Harnessing the site loader's ability to combine terrain maps together, a 2D planning graph can be generated at the same spatial resolution as the maps (i.e., 1 vertex/node per pixel). Directed graph edges store information relevant for simple path planning tasks (such as the straight-line Euclidean distance in 3 dimensions between neighbouring vertices, the rover's roll and pitch along the edge (which are dependent on the edge's orientation/heading), traverse duration and energy draw given velocity and power models, and more). Simple optimal path planning tasks (physically shortest path, most energy-efficient path, etc.) can be carried out using specific edge attributes.

Refer to the planning graph guide page for more information.

Solar loader

The solar loader handles irradiance data of a specific dataset. It is mainly used for data inspection, plotting and solar energy generation calculation given a simple rover model. Refer to the solar loader guide page for more information.

3. Creating your own dataset

All datasets must follow the format described in the dataset formatting page.

If you do not want to deal with real orbital maps of a planetary surface, it is possible to generate your own minimal dataset (random elevation, slope, aspect and terrain layers). This process is demonstrated in the site generation demo notebook.