Addition of Overlay's to save_datasets() Documentation

[KziolkowskiWx]

Feature Request

Would like to see the addition of how to add custom overlay's to the SatPy documentation. This includes how to add custom shape files to overlays using save_datasets().

I have written some code that has worked and that can be used in the documentation:

`

from satpy import Scene, MultiScene, config, find_files_and_readers
def main():
    border_color = (51,182,233)
    files = find_files_and_readers(base_dir='/path/to/files/',
                                    reader='abi_l1b',
                                    start_time=(2023, 7, 23, 0, 40),
                                    end_time=(2023, 7, 23, 0, 50))

    scn = Scene(reader='abi_l1b', filenames=files)
    scn.load(['name_of_your_product'],generate=False)
    new_scn = scn.resample('area_to_resample_to', cache_dir='/path/to/satpy/cache/directory/')
    #Get the file start time and make a label
    file_time = scn.start_time
    label = 'GOES-East Visible IR Sandwich'+"\nValid: {:%Y-%m-%d %H:%M UTC}".format(file_time)
    new_scn.save_datasets(writer='simple_image', 
                            filename='/path/to/save/image/to/' + '{name}_{start_time:%Y%m%d_%H%M%S}.jpeg',
                            fill_value=0,
                            decorate=textbox(label), overlay=overlay(border_color))

    #functions to organize overlays

    def textbox(label):
        """
        A decorator to add a textbox to add the type of satellite product along with a timestamp.

        label = Label for the satellite product
        eg.
        label="Airmass"
        or
        label="Visible IR Sandwich\nNight Microphysics"
        """
        decorate_dict = {
            "decorate": [
                {"text": {
                    "txt": label,
                    "align": {
                        "top_bottom": "top",
                        "left_right": "left"},
                    "font": '/path/to/fonts/DejaVuSans.ttf', #usually located in /usr/share/fonts/truetype
                    "font_size": 150,
                    "height": 170,
                    "bg": "white",
                    "bg_opacity": 200,
                    "line": "black"}}
                ]}
        
        return decorate_dict

    def overlay(border_color):
        """
        Overlays of polygons for political boundaries and lakes. 

        border_color= Provide the color of the border in either RGB (R,G,B) or string

        e.g.

        border_color=(51,182,233) #Sky Blue
        or
        border_color="white"

        Based off of PyCoast --> https://pycoast.readthedocs.io/en/latest/
        """
        overlaydict = {
                "coast_dir": "/path/to//pycoast_files", #read install instructions for pycoast
                #reference to dict keys for shapefile overlay can be found at https://github.com/pytroll/pycoast/blob/240ff445f01d138d1874c869c6b53920e4a2471e/pycoast/cw_base.py#L1288
                #Level indicates what level of data is shown. Is done by a numerical code 1-XX. 
                #Coding can be found @ https://www.soest.hawaii.edu/pwessel/gshhg/ 
                #e.g. level 2 borders will show international borders, provinces and states in the americas. 
                'overlays': {'shapefiles': {"filename":"/path/to/shapefile/", "outline": border_color, 'width': 10},
                            'borders': {"level": 2, "outline": border_color, "width": 10},
                            'coasts': {"level": 1, "outline": border_color, "width": 10}}
                }
        return overlaydict

if __name__ == "__main__":
    main()

`

Sample Image

I would also like to see this documentation added to Multiscene's save_animiation().

@djhoese