Add support for planar periodic meshes

[andrewdnolan]

This PR adds support for planar periodic meshes, by streamlining and abstracting the spherical wrapping functionality so that it works to both planar and spherical meshes. For this to work, I've added getter/setter methods for the period attributes that handle the planar periodic / spherical meshes details appropriately. This has also dramatically simplified the spherical wrapping procedure, which was unduly complicated (and insufficient) previously. Testing of new the spherical wrapping for vertex patches has revealed a bug in #12, which produces invalid geometries for vertices along culled boundaries. When these invalid geometries intersect the map projection boundary, cartopy struggles with them resulting in the patches spanning the entire plot area. This bug is fixed as part of this PR. Finally, for testing purposes this PR also adds a small planar periodic mesh to the datasets database.

Fixes #15.

[andrewdnolan]

Planar Periodic Testing

import mosaic
import matplotlib.pyplot as plt

def test_periodic(descriptor, ds, loc):
    fig, ax = plt.subplots()

    mosaic.polypcolor(ax, descriptor, ds.indexToCellID * 0.0, ec='k', cmap='binary')
    mosaic.polypcolor(ax, descriptor, ds[f"indexTo{loc}ID"], alpha=0.5, ec='tab:orange')

    ax.scatter(ds[f"x{loc}"], ds[f"y{loc}"], color="tab:blue")

    ax.set_title(f"{loc} Patches")


ds = mosaic.datasets.open_dataset("doubly_periodic_4x4")

descriptor = mosaic.Descriptor(ds)

for loc in ["Cell", "Edge", "Vertex"]:
    test_periodic(descriptor, ds, loc)

plt.show()

Cell patches:

Edges patches:

Vertex patches

[andrewdnolan]

@xylar I think this is ready for review. I've worked out all the lingering issue in vertex patch creation and am now including vertex patches in the unit tests. I've also updated the documentation to include information about the periodic mesh support and list of the projection we currently support.

Unit tests cover a lot of functionality for spherical plotting. There's a test for making sure no figure rendering hangs and there's also a test which manually converts patches to shapely geometries and check that they are all valid. Both test loop over the supported projections and three patch location, with all tests passing.

I still need to remove the in development warning from the readme / docs, but I think I'll do that as part of the PR for releasing v1.0.0.

I also ran some local tests with the Humboldt mesh that had been run the mesh converter and everything still looks good for the vertex patches.

[xylar]

This is just a review by inspection of the code. Everything looks excellent to me. The new tests seem quite thorough, and the treatment of periodic boundaries looks reasonable.

[andrewdnolan]

@xylar Thanks for looking through! I'm going to merge and move forward with releasing v1.0.0.