Dataset formatting guide

The primary role of gplanetary-nav is to load and query orbital mapping (terrain, irradiance, etc.) datasets in support of global-scale planetary navigation. Below we describe how to format the data before using it with our library.

The top directory containing all of data for a specific site is referred to as the site directory in the documentation and the code. Here's an example site directory structure:

/CAB240_sample      # directory name is the name of the dataset
|
|   settings.yaml   # metadata & site loader instructions
|
|   dem.tif         # elevation model, in meters above a datum
|   slope.tif       # slope magnitude map
|   aspect.tif      # slope azimuth map (or aspect)
|
|   nogo_human.tif  # a binary obstacle map (integers, 0=free and 1=obstacle)
|   nogo_roi.tif    # another binary obstacle map (0=free and 1=obstacle)
|
|   mosaic.tif      # surface imagery, which is possibly in color
|
└───irradiance/     # If irradiance maps are included
    |   times.csv   # time table for all irradiance maps
    └───maps/       # irradiance maps, same shape as the terrain maps
        |   Clr_SOL_IRRAD_MP2029001T00_00_00000povmap.tif
        |   Clr_SOL_IRRAD_MP2029001T06_00_00000povmap.tif
        |   ...

All data maps/rasters need to be expressed as GeoTIFFs (.tif) in the same UTM coordinate reference system. All terrain-related data are located in the dataset's root directory while all irradiance-related data, if any, are located in the irradiance subdirectory.

This is a rather complete example with a lot of maps. For basic path planning purposes, only a fraction of these maps is necessary. The different types of layers supported are documented in the site loader page, and path planning details are discussed in the planning graph guide page.

The settings.yaml file contains site metadata and instructions regarding which terrain maps to load. Here's an example settings.yaml file, configured to load a few of the maps listed above:

# Coordinates of the current site, only for ephemeris queries, if needed
# We use astroquery's HorizonsClass conventions
# https://astroquery.readthedocs.io/en/latest/jplhorizons/jplhorizons.html
center_longitude: -77.5031
center_latitude: 18.4386
reference_body: Mars  # Mars, Moon, Earth tested

layers:
    # Elevation w.r.t. some datum, values must be meters
    dem:
        fpath: dem.tif
        min_val: null   # minimum elevation, in meters
        max_val: null   # maximum elevation, in meters

    # Slope magnitude
    slope:
        fpath: slope.tif
        units: deg      # raster units ('deg' or 'rad' allowed)
        max_val: 30     # maximum slope in raster units

    # Slope orientation ("aspect")
    aspect:
        fpath: aspect.tif
        units: deg      # raster units ('deg' or 'rad' allowed)

    # Additional layer types are supported, they are documented later

    # Name of all integer no-go rasters, if any (0=free, 1=obstacle)
    nogo:
        - nogo_human.tif
        - nogo_roi.tif
    
    # Any other raster to load. Must have the same UTM coordinate reference
    # system as the above maps, but could have a different resolution, extent,
    # and could be color (i.e. have 3 channels, like R, G, B)
    other:
        - mosaic.tif

# No-go processing parameters
nogo_processing:

    # Kernel dimensions for a binary dilation operation
    inflation_kernel_dim: null # null, 3, 5, etc.

    # Whether clusters/islands of free space surrounded by no-go regions
    # are also no-go
    free_island_is_nogo: True

    # Free pixels with touching corners are in the same cluster/island
    islands_corners_connect: False

    # Whether pixels along the map border are no-go
    border_is_nogo: True

By convention, the maps that are not in the "other" list (dem, slope, aspect, nogo_human, ...) are expected to contain a single band with the same plotting extent, resolution, and thus have the same dimensions (map height/width in pixels). For example, the pixel located at, say, (10,10) on the dem should overlap with the pixel at (10,10) on the other non-raw maps. The maps listed under "other" should have the same coordinate reference system as the other maps but they can have a different resolution or plotting extent; they are mainly used for visualization/plotting purposes.

The maps listed under the "nogo" category are integer-valued binary rasters indicating obstacle regions (1) and free space (0). When loaded, all no-go maps are combined into a single obstacle map using a pixel-wise OR operation.

A no-go map can be named anuthing except "nogo.tif". The reason is explained in the site loader page.

The irradiance maps in irradiance/maps/ are expected to have the same dimensions (shape), resolution and plotting extent as the terrain maps outside of the "other" list. Each map represents the solar flux (W/m^2) hitting the rover at a given moment. Pixels storing negative values (or values equal to nodata as defined in the GeoTIFF metadata) are assumed to be invalid. It is also assumed that the time interval between consecutive maps is roughly similar for the whole dataset.

This irradiance map representation is approximately equivalent to having a rover equipped with panels on an actuated pan-tilt platform, or solar panels evenly distributed about the rover's central vertical axis. This assumption allows us to compute solar power without knowledge of the rover's heading/azimuth, as explained later.

Lastly, irradiance/times.csv is a time table associating each irradiance map file name to the corresponding date, time and UNIX timestamp in seconds (all in UTC). Our library expects the following file format:

fname,UTC_date_yyyy-mm-dd,UTC_time_HH-MM-SS,unix_timestamp_s
Clr_SOL_IRRAD_MP2029001T00_00_00000povmap.tif,2029-01-01,00-00-00,1861920000
Clr_SOL_IRRAD_MP2029001T06_00_00000povmap.tif,2029-01-01,06-00-00,1861941600

Important: The first row of times.csv needs to be these exact headers.