Coastlines (outlines) based on MPAS mesh connectivity info

[andrewdnolan]

This PR add a public API to draw coastlines, following the cartopy.mpl.geoaxes.coastlines method from cartopy. Because we use the mesh connectivity information, the coastlines resolution will be function of the mesh resolution and accurately reflect the coastline resolved by MPAS.

Filled land plotting will be added at a later date.

[andrewdnolan]

Testing:

import cartopy.crs as ccrs
import matplotlib.pyplot as plt

import mosaic

projection = ccrs.PlateCarree()
ds = mosaic.datasets.open_dataset("mpaso.IcoswISC30E3r5")

descriptor = mosaic.Descriptor(ds, projection=projection)

fig, ax = plt.subplots(
    layout="constrained", subplot_kw={"projection": projection}
)

mosaic.coastlines(ax, descriptor, lw=0.5)

plt.show()

[Copilot]

Pull request overview

Adds a public mosaic.coastlines API to draw coastline outlines derived from MPAS
mesh connectivity (mesh-resolution-dependent), and updates culling/contouring
logic to handle newly introduced negative connectivity codes consistently.

Changes:

• Add mosaic.coastlines() and MPASCoastlineGenerator plus tests and docs.
• Update connectivity masking from == -1 to < 0 and adjust contour padding to
  support a new -2 sentinel for projection-boundary culling.
• Refactor spherical projection parametrization into tests/conftest.py and
  relax one global pytest warning filter.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
mosaic/coastlines.py	New coastline plotting API and generator based on mesh connectivity.
mosaic/__init__.py	Exposes coastlines in the public package API.
mosaic/utils.py	Changes culling lookup-table fill value to -2 for projection-boundary culls.
mosaic/descriptor.py	Updates patch construction masks to treat any negative index as invalid.
mosaic/contour.py	Updates boundary detection and mask padding/indexing to handle -2.
tests/test_coastlines.py	Adds tests for coastline kwargs behavior and geometry validity.
tests/conftest.py	Moves supported-projection parametrization into a shared fixture.
tests/test_spherical.py	Uses the shared projection fixture instead of local parametrization.
tests/test_utils.py	Updates test to treat any negative index as invalid padding.
pyproject.toml	Adds a global pytest filter for a NumPy RuntimeWarning.
docs/user_guide/quick_start.md	Updates quick-start example to use mosaic.coastlines().
docs/developers_guide/api.md	Adds coastlines to the generated API docs toctree.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[andrewdnolan]

@xylar I think this just needs a second pair of eyes before it's ready to merged.

Between the unit tests and copilot's review I'm feeling comfortable, but it would be great if you can take a quick look. Doesn't have to be extensive, I know you've juggling a lot of other tasks at the moment.

[xylar]

@andrewdnolan, I ran a similar test to your example in the docs on an EC30to60 mesh and it looks great! I think this is a really good capability.

[andrewdnolan]

@xylar Thanks for taking a look!