Features

• One function, cplt.create(), to build a complete map from just an extent – coastlines, land/ ocean colors, ticks, and borders included by default.

• Built-in bathymetry download and plotting (contours, shaded contours, or continuous depth shading), and ocean current quiver plots from xarray datasets. Large extents are automatically tiled to stay under the server’s request-size limits.

• Supported on two interchangeable mapping engines, Cartopy and Basemap – the same code works under either, including plotting your own data directly on the returned axes.

• Nicely spaced, DMS- or decimal-degree-labeled ticks computed automatically from your map extent.

Quickstart

import cool_maps.plot as cplt

# Gulf of Mexico
extent = [-99, -79, 18, 31]

fig, ax = cplt.create(extent, bathymetry=True)

See the full tutorial (also available as a runnable notebook at notebooks/tutorial.ipynb) for a complete walkthrough covering projections, coastline resolution, colors, ticks, bathymetry, overlaying your own data, currents, and choosing between engines.

Selecting a map engine

The plotting helpers support both Cartopy (the default) and Basemap. Cartopy remains the default engine, but you can select Basemap after installing it:

>>> import cool_maps.plot as cplt
>>> cplt.set_engine('basemap')

You can also set COOL_MAPS_ENGINE=basemap in your environment before importing cool_maps.plot, or pass engine= to any individual call without touching the global default:

>>> cplt.create(extent, engine="basemap")

When switching engines you can keep using the same Cartopy CRS objects in calls such as cplt.create(..., proj=ccrs.Mercator()). The Basemap backend will translate a handful of common projections automatically; if a CRS cannot be converted, pass the Basemap projection name or keyword dictionary instead (for example proj={'projection': 'lcc', 'lon_0': -74, 'lat_0': 39}).

For a Cartopy-free workflow you can use the shared projection keywords provided by cool_maps:

>>> cplt.create(extent, proj="mercator")

Behind the scenes the string is mapped to the appropriate Cartopy CRS or Basemap projection depending on the active engine.

Axes returned by create() remember which engine they were built with, so you never need to pass engine= to add_features/add_bathymetry/add_currents/add_ticks yourself – it’s inferred from the axes. You can also plot directly on the returned axes with ax.scatter/ax.plot/ax.contour/ ax.contourf/ax.pcolormesh/ax.quiver/ax.fill using plain lon/lat data; cool_maps injects the right transform= (Cartopy) or latlon=True (Basemap) for you, so the exact same plotting code works under either engine:

>>> fig, ax = cplt.create(extent, engine="basemap")  # or "cartopy"
>>> ax.scatter(lon, lat, c=values)  # no transform=/latlon= needed, regardless of engine

Installation

$ conda install -c conda-forge cool_maps

$ conda install -c conda-forge basemap basemap-data-hires

$ pip install cool_maps[basemap]

$ git clone git://github.com/rucool/cool_maps

$ curl -OJL https://github.com/rucool/cool_maps/tarball/master

$ cd ~/cool_maps

$ python setup.py install

$ pip install .

Documentation

• Full docs, tutorial, and API reference: https://cool-maps.readthedocs.io/en/latest/

• Runnable tutorial notebook: notebooks/tutorial.ipynb

• Cartopy/Basemap parity deep-dive and performance comparison: notebooks/dual_backend_demo.ipynb

License

MIT license – see LICENSE for details.

0.0.6 (2022-09-21)

• Create conda build for conda-forge

• Add Sphinx documentation

0.0.3 (2022-07-20)

• Create conda build

0.0.2 (2022-07-19)

• Initial commit to GitHub