Solar loader guide
Here we demonstrate the ability of gplanetary_nav to load solar irradiance data and perform basic calculations. We use the "CAB240_sample" dataset (refer to the download instructions in the wiki's home page) as an example. This dataset contains solar irradiance maps (at a spatial resolution of 240m/pixel) of a specific area in the Cabeus region at the lunar south pole.
As explained in the dataset formatting guide, the (georeferenced) irradiance maps of a dataset are expected to be located in an irradiance/maps/ subfolder. They must match the dimensions (shape), resolution and plotting extent of the terrain maps. A single map represents the solar flux (W/m^2) hitting the rover at a given instant. 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.
gplanetary_nav assumes that the irradiance data provided by a specific map remains constant from the timestamp of this map until the timestamp of the following map:
For every solar irradiance query made by a trajectory planner, it would be inefficient to constantly load entire irradiance maps to look up the irradiance conditions at a single pixel at a given time. Also, if there are a lot of irradiance maps in the dataset, loading them all would require a lot of memory.
Instead, gplanetary_nav provides a tool to pre-calculate irradiance time series (i.e., an irradiance vs time function) at every map pixel and store each time series in a dedicated .csv file (one file for each pixel). Only the free pixels (i.e. those that are in free space according to the nogo terrain maps) are processed.
To access this data quickly and keep memory usage to a minimum, a timestamp-irradiance pair is stored in the .csv files only for times when the irradiance conditions at that pixel change. It's a simple and lossless compression of the irradiance data.
Assuming the gplanetary-nav conda environment is running, this preprocessing step can be carried out with the create_pixel_intervals() function:
>>> from gplanetary_nav.solar.preprocessing import create_pixel_intervals
>>> help(create_pixel_intervals)
# create_pixel_intervals(
# dirpath: pathlib.Path, num_cpus: int = 1, create_nogo: bool = True,
# use_site_nogo: bool = True) -> None
# Create pixel-wise irradiance timeseries for a dataset containing
# irradiance maps.
# Args:
# dirpath: absolute path to a dataset directory
# num_cpus: num of cpus to use for the timeseries initialization.
# Default 1
# create_nogo: create an nogo_irradiance.tif raster in the dataset's
# root directory to identify pixels where irradiance data isn't
# available (any pixel containing either a negative irradiance or
# a 'nodata' value as described in the geotiff metadata). This is
# carried out using only the first irradiance map, so it is assumed
# that all valid pixels on the first map also contain valid values
# on all other maps.
# use_site_nogo: create timeseries for pixels outside of the site layers
# no-go areas (in its current configuration as described in the
# dataset's settings.yaml file). Useful if the irradiance maps are
# large, but it means that a new set of irradiance timeseries needs
# to be calculated whenever the site layers are adjusted/changed.The new pixel-specific files will be saved in an irradiance/pixel_intervals/ subdirectory. Note that the number of files created can be high, so there are incentives in providing no-go maps as accurate as possible.
If the create_nogo option is enabled when the irradiance intervals are created, a nogo_irradiance.tif raster will be saved in the dataset's root directory. Add it to the dataset's settings.yaml nogo list if it is needed for planning purposes.
The SolarLoader class handles all solar irradiance-related queries, from irradiance map plotting to solar energy generation estimation at specific pixels. Refer to the solar loader demo for complete demonstrations of all the functionalities of this class. At the bottom, demonstrations of the Ephemeris class (to calculate solar azimuth and elevation values) are also included.