Add gallery of areas to documentation

[gerritholl]

Feature Request

Is your feature request related to a problem? Please describe.

When browsing built-in areas to choose some for a quick visualisation, it is difficult to visualise what area and projection the areas correspond to from name and parameters alone.

Describe the solution you'd like

It would be nice to have a gallery in the documentation, with a small sample image and/or a larger map with an outline drawn on it, corresponding to the region covered by each area definition.

Describe any changes to existing user workflow

None.

Additional context

There seems to be very little on areas in the satpy documentation. That's probably because AreaDefinition is a pyresample class, but since areas.yaml is distributed with satpy and not with pyresample, it rather belongs here.

[djhoese]

Great idea! This would probably go well with some of the work that was being done during the PCW to create a notebook visualization of AreaDefinitions using the geoviews library. I think it was Luca and Dario that were working on it (I don't know their github usernames) and I think they had a much more involved use case for the tool so I'm not sure the status of it.

The other obvious solution would be to do coastlines with pycoast and make a plain black and white image. This is probably simple enough that it could even be added to the documentation creation...maybe (might be too much for readthedocs).

[gerritholl]

Apparently, there exists some code in satpy already that can help with this, but it's hidden out of the main source tree in the utils/ directory:

satpy/utils/coord2area_def.py

Lines 147 to 159 in 3128bf5

	from PIL import Image
	from pycoast import ContourWriterAGG
	img = Image.new('RGB', (xsize, ysize))
	area_def = (proj4_string, area_extent)
	cw = ContourWriterAGG(args.shapes)
	cw.add_coastlines(img, (proj4_string, area_extent),
	resolution='l', width=0.5)
	cw.add_grid(img, area_def, (10.0, 10.0), (2.0, 2.0), write_text=False, outline='white', outline_opacity=175,
	width=1.0, minor_outline='white', minor_outline_opacity=175, minor_width=0.2, minor_is_tick=False)
	img.show()

but it doesn't seem to have an interface to output such an image for a pre-existing AreaDefinition.

[gerritholl]

There's also functionality in pytroll-schedule to plot areas or swaths on a map.

[BENR0]

I really like this idea too. For the documentation of our working group, which also contains an areas file with custom areas, I wrote a script which creates a rst file with name, description, extent and an overview plot for each area in the file. This is how it looks like in the documentation:

[djhoese]

@BENR0 Does your drawing code look the same as what was posted above?

[BENR0]

@djhoese no. I use cartopy and just add border and coastline features.