From d27eaf3c191db9d52dd54b6cdd2270bd13daa6e0 Mon Sep 17 00:00:00 2001 From: Phil Elson Date: Wed, 21 Feb 2018 06:37:53 +0000 Subject: [PATCH 1/5] Prepared the what's new for v0.16. --- docs/source/_static/layout.css | 15 +++- docs/source/matplotlib/feature_interface.rst | 29 +++++-- docs/source/whats_new.rst | 81 +++++++++++++++++++- lib/cartopy/examples/feature_creation.py | 10 +++ 4 files changed, 126 insertions(+), 9 deletions(-) diff --git a/docs/source/_static/layout.css b/docs/source/_static/layout.css index 2bbbff593..62713193c 100644 --- a/docs/source/_static/layout.css +++ b/docs/source/_static/layout.css @@ -4,7 +4,20 @@ pre {max-width: 70em;} -div.section dl, div.section ul { max-width: 80em;} + +div.section dl, div.section ul { + max-width: 80em; +} + +div.section { + /* Paragraph sections (e.g. in what's new) */ + padding-bottom: 1em; +} + +dl.class { + /* Sphinx documented classes. */ + padding-bottom: 1.5em; +} div.figure { padding-left: 5em; } diff --git a/docs/source/matplotlib/feature_interface.rst b/docs/source/matplotlib/feature_interface.rst index 664855d62..d4f8c0791 100644 --- a/docs/source/matplotlib/feature_interface.rst +++ b/docs/source/matplotlib/feature_interface.rst @@ -21,9 +21,12 @@ Natural Earth or GSHHS shapefiles. .. autoclass:: ShapelyFeature .. autoclass:: NaturalEarthFeature + :members: with_scale .. autoclass:: GSHHSFeature +.. autoclass:: WFSFeature + ---------- To simplify some very common cases, some pre-defined Features exist as :mod:`cartopy.feature` @@ -34,17 +37,29 @@ such as :func:`GeoAxes.add_feature `: ======================================= ================================================== Name Description ======================================= ================================================== -.. py:data:: cartopy.feature.BORDERS Country boundaries. -.. py:data:: cartopy.feature.COASTLINE Coastline, including major islands. -.. py:data:: cartopy.feature.LAKES Natural and artificial lakes. -.. py:data:: cartopy.feature.LAND Land polygons, including major islands. -.. py:data:: cartopy.feature.OCEAN Ocean polygons. -.. py:data:: cartopy.feature.RIVERS Single-line drainages, including lake centerlines. +.. py:data:: BORDERS Country boundaries. + +.. py:data:: COASTLINE Coastline, including major islands. + +.. py:data:: LAKES Natural and artificial lakes. + +.. py:data:: LAND Land polygons, including major islands. + +.. py:data:: OCEAN Ocean polygons. + +.. py:data:: RIVERS Single-line drainages, including lake centerlines. + +.. py:data:: STATES Internal, first-order administrative boundaries + (limited to the United States at this scale). + Natural Earth have first-order admin boundaries + for most countries at 10m scale which may be + accessed with + ``cartopy.feature.STATES.with_scale('10m')`` ======================================= ================================================== .. note:: - Any Natural Earth dataset can easily be used by creating an + Any Natural Earth dataset can be used by creating an instance of :class:`cartopy.feature.NaturalEarthFeature`. For example:: diff --git a/docs/source/whats_new.rst b/docs/source/whats_new.rst index c2b46e3b7..a857db59a 100644 --- a/docs/source/whats_new.rst +++ b/docs/source/whats_new.rst @@ -2,7 +2,7 @@ What's New in cartopy 0.16 ========================== :Release: 0.16.0 -:Date: ??? 2018 +:Date: 21st Feb 2018 Features -------- @@ -12,6 +12,85 @@ Features and has already made significant contributions to the Matplotlib interface, extended projections, and helped modernise the development infrastructure. +* The :ref:`gnomonic-projection` was brought up-to-date to include the + ``central_longitude`` argument. (:pull:`855`) + +* Ryan May improved the formulation of the boundary ellipse for the + :class:`~cartopy.crs.Geostationary` projection and added the + ``sweep_angle_axis`` keyword argument. (:pull:`890`, :pull:`897`) + +* Elliott Sales de Andrade made a number of micro-optimisations to the + matplotlib interface, fixed a number of documentation issues with + python 3 and added matplotlib 2.0 & 2.1 compatibility. (:pull:`886`, + :pull:`901`, :pull:`780`, :pull:`773`, :pull:`977`) + +* Tick padding was added to the to gridliner. + :data:`cartopy.mpl.gridliner.Gridliner.xpadding` and + :data:`~cartopy.mpl.gridliner.Gridliner.ypadding` relate. (:pull:`783`) + +* Ryan May added the :meth:`~cartopy.feature.NaturalEarthFeature.with_scale` + method to the NaturalEarthFeature class. + For example, it is now possible to access higher resolution land features + with ``cartopy.feature.LAND.with_scale('50m')``. In addition to this, + :data:`cartopy.feature.STATES` was added to easily access administrative + area boundaries that were previously only accessible by manually + constructing :class:`~cartopy.feature.NaturalEarthFeature` instances + (as is done in the :ref:`sphx_glr_gallery_feature_creation.py` example). + (:pull:`898`) + +* Daryl Herzmann and Robert Redl improved cartopy's internal conversion + between shapely objects and matplotlib Paths. (:pull:`885` & :pull:`1021`) + +* Åsmund Steen Skjæveland fixed :meth:`cartopy.mpl.geoaxes.GeoAxes.tissot` + to use the documented units of kilometres, where before it had been using + metres. (:pull:`904`) + +* Andrew Dawson wrote a new tutorial for the user guide: + :ref:`understanding_transform`. (:pull:`914`) + +.. figure:: _images/understanding_transform-6.png + :target: tutorials/understanding_transform.html + :align: center + +* Daniel Kirkham and Daryl Herzmann made significant improvements to the + stability of polygon transformation. The changes reduce the frequency + of messages such as + ``Unidentified problem with geometry, linestring being re-added`` and + ``Self-intersection at or near point `` occuring. + (:pull:`974` and :pull:`903`) + +* Chris Holdgraf and Corinne Bosley worked collaboratively to bring + `sphinx-gallery `_ to the + cartopy docs. (:pull:`969`) + +* Ray Bell neatened up many of the examples to explicitly pass the coordinate + system when calling :meth:`~cartopy.mpl.geoaxes.GeoAxes.set_extent`. + (:pull:`975`) + +* Ryan May changed the default zorder of LAND and OCEAN to -1, thus fixing + an issue with LAND/OCEAN appearing above some data elements such as + vectors. (:pull:`916`) + +* Kevin Donkers added the 60 UTM projections example to the gallery + in :pull:`954`: + +.. figure:: gallery/images/sphx_glr_utm_all_zones_001.png + :target: gallery/utm_all_zones.html + :align: center + +* Andrey Kiselev added support for reading shapes with a third (Z) dimension. + (:pull:`958`) + +* Corinne Bosley standardised the docstring format for improved readability + and visual consistency. (:pull:`987`) + +* Cartopy now no longer enables :func:`shapely.speedups` at cartopy import + time. (:pull:`990`) + +* Mahé Perrette and Ryan May collaborated to improve the + :class:`~cartopy.crs.Stereographic` projection. (:pull:`929`) + + What's New in cartopy 0.15 ========================== diff --git a/lib/cartopy/examples/feature_creation.py b/lib/cartopy/examples/feature_creation.py index 98592ae58..c31074026 100644 --- a/lib/cartopy/examples/feature_creation.py +++ b/lib/cartopy/examples/feature_creation.py @@ -2,6 +2,16 @@ Feature Creation ---------------- +This example manually instantiates a +:class:`cartopy.feature.NaturalEarthFeature` to access administrative +boundaries (states and provinces). + +Note that this example is intended to illustrate the ability to construct +Natural Earth features that cartopy does not necessarily know about +*a priori*. +In this instance however, it would be possible to make use of the +pre-defined :data:`cartopy.feature.STATES` constant. + """ __tags__ = ['Lines and polygons'] From 1746a47a82d1b4adbcde5543803e663752697d91 Mon Sep 17 00:00:00 2001 From: Phil Elson Date: Wed, 21 Feb 2018 16:49:15 +0000 Subject: [PATCH 2/5] Review of what's new from Elliott. --- docs/source/matplotlib/feature_interface.rst | 31 ++++++++++---------- docs/source/whats_new.rst | 10 +++---- 2 files changed, 20 insertions(+), 21 deletions(-) diff --git a/docs/source/matplotlib/feature_interface.rst b/docs/source/matplotlib/feature_interface.rst index d4f8c0791..39798a0ce 100644 --- a/docs/source/matplotlib/feature_interface.rst +++ b/docs/source/matplotlib/feature_interface.rst @@ -34,28 +34,27 @@ constants. The pre-defined Features are all small-scale (1:110m) `Natural Earth `_ datasets, and can be added with methods such as :func:`GeoAxes.add_feature `: -======================================= ================================================== -Name Description -======================================= ================================================== -.. py:data:: BORDERS Country boundaries. +======================= ================================================================ +Name Description +======================= ================================================================ +.. py:data:: BORDERS Country boundaries. -.. py:data:: COASTLINE Coastline, including major islands. +.. py:data:: COASTLINE Coastline, including major islands. -.. py:data:: LAKES Natural and artificial lakes. +.. py:data:: LAKES Natural and artificial lakes. -.. py:data:: LAND Land polygons, including major islands. +.. py:data:: LAND Land polygons, including major islands. -.. py:data:: OCEAN Ocean polygons. +.. py:data:: OCEAN Ocean polygons. -.. py:data:: RIVERS Single-line drainages, including lake centerlines. +.. py:data:: RIVERS Single-line drainages, including lake centerlines. -.. py:data:: STATES Internal, first-order administrative boundaries - (limited to the United States at this scale). - Natural Earth have first-order admin boundaries - for most countries at 10m scale which may be - accessed with - ``cartopy.feature.STATES.with_scale('10m')`` -======================================= ================================================== +.. py:data:: STATES Internal, first-order administrative boundaries (limited to the + United States at this scale). + Natural Earth have first-order admin boundaries for most + countries at the 1:10,000,000 scale; these may be + accessed with ``cartopy.feature.STATES.with_scale('10m')`` +======================= ================================================================ .. note:: diff --git a/docs/source/whats_new.rst b/docs/source/whats_new.rst index a857db59a..7785df501 100644 --- a/docs/source/whats_new.rst +++ b/docs/source/whats_new.rst @@ -20,11 +20,11 @@ Features ``sweep_angle_axis`` keyword argument. (:pull:`890`, :pull:`897`) * Elliott Sales de Andrade made a number of micro-optimisations to the - matplotlib interface, fixed a number of documentation issues with - python 3 and added matplotlib 2.0 & 2.1 compatibility. (:pull:`886`, + Matplotlib interface, fixed a number of documentation issues with + Python 3 and added Matplotlib 2.0 & 2.1 compatibility. (:pull:`886`, :pull:`901`, :pull:`780`, :pull:`773`, :pull:`977`) -* Tick padding was added to the to gridliner. +* Tick padding was added to the gridliner. :data:`cartopy.mpl.gridliner.Gridliner.xpadding` and :data:`~cartopy.mpl.gridliner.Gridliner.ypadding` relate. (:pull:`783`) @@ -39,7 +39,7 @@ Features (:pull:`898`) * Daryl Herzmann and Robert Redl improved cartopy's internal conversion - between shapely objects and matplotlib Paths. (:pull:`885` & :pull:`1021`) + between shapely objects and Matplotlib Paths. (:pull:`885` & :pull:`1021`) * Åsmund Steen Skjæveland fixed :meth:`cartopy.mpl.geoaxes.GeoAxes.tissot` to use the documented units of kilometres, where before it had been using @@ -56,7 +56,7 @@ Features stability of polygon transformation. The changes reduce the frequency of messages such as ``Unidentified problem with geometry, linestring being re-added`` and - ``Self-intersection at or near point `` occuring. + ``Self-intersection at or near point `` occurring. (:pull:`974` and :pull:`903`) * Chris Holdgraf and Corinne Bosley worked collaboratively to bring From f64153091c7e7d7e9d0e9425ca4e9a3f799f1d6b Mon Sep 17 00:00:00 2001 From: Phil Elson Date: Wed, 21 Feb 2018 18:59:20 +0000 Subject: [PATCH 3/5] Fixed always_circular_stereo example which was broken by #916. --- lib/cartopy/mpl/geoaxes.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/cartopy/mpl/geoaxes.py b/lib/cartopy/mpl/geoaxes.py index 94f237f77..5bd3de368 100644 --- a/lib/cartopy/mpl/geoaxes.py +++ b/lib/cartopy/mpl/geoaxes.py @@ -1292,10 +1292,10 @@ def set_boundary(self, path, transform=None, use_as_clip_path=True): if self.background_patch is None: background = mpatches.PathPatch(path, edgecolor='none', - facecolor='white', zorder=-1, + facecolor='white', zorder=-2, clip_on=False, transform=transform) else: - background = mpatches.PathPatch(path, zorder=-1, clip_on=False) + background = mpatches.PathPatch(path, zorder=-2, clip_on=False) background.update_from(self.background_patch) self.background_patch.remove() background.set_transform(transform) From 7da6255bf042e30be4ca163a517bacfc57ba0355 Mon Sep 17 00:00:00 2001 From: Phil Elson Date: Wed, 21 Feb 2018 19:16:23 +0000 Subject: [PATCH 4/5] Added appropriate annotations to all examples in the gallery. --- lib/cartopy/examples/always_circular_stereo.py | 11 ++++++++--- lib/cartopy/examples/favicon.py | 6 ++++-- lib/cartopy/examples/features.py | 3 +++ lib/cartopy/examples/global_map.py | 3 +++ lib/cartopy/examples/hurricane_katrina.py | 3 +++ lib/cartopy/examples/logo.py | 6 ++++-- lib/cartopy/examples/rotated_pole.py | 2 +- lib/cartopy/examples/un_flag.py | 3 +++ lib/cartopy/examples/waves.py | 6 ++++-- 9 files changed, 33 insertions(+), 10 deletions(-) diff --git a/lib/cartopy/examples/always_circular_stereo.py b/lib/cartopy/examples/always_circular_stereo.py index 3e586287b..318731d8f 100644 --- a/lib/cartopy/examples/always_circular_stereo.py +++ b/lib/cartopy/examples/always_circular_stereo.py @@ -1,8 +1,13 @@ """ -Keep Boundary Circular ----------------------- +Custom Boundary Shape +--------------------- -Setting the boundary of an image to be circular. +This example demonstrates how a custom shape geometry may be used +instead of the projection's default boundary. + +In this instance, we define the boundary as a circle in axes coordinates. +This means that no matter the extent of the map itself, the boundary will +always be a circle. """ __tags__ = ['Lines and polygons'] diff --git a/lib/cartopy/examples/favicon.py b/lib/cartopy/examples/favicon.py index 155e0ad93..9d1553c88 100644 --- a/lib/cartopy/examples/favicon.py +++ b/lib/cartopy/examples/favicon.py @@ -1,6 +1,8 @@ """ -Favicon -------- +Cartopy Favicon +--------------- + +The actual code to generate cartopy's favicon. """ import cartopy.crs as ccrs diff --git a/lib/cartopy/examples/features.py b/lib/cartopy/examples/features.py index 968a2da52..7bc5dc1b0 100644 --- a/lib/cartopy/examples/features.py +++ b/lib/cartopy/examples/features.py @@ -2,6 +2,9 @@ Features -------- +A demonstration of some of the built-in Natural Earth features found +in cartopy. + """ __tags__ = ['Lines and polygons'] diff --git a/lib/cartopy/examples/global_map.py b/lib/cartopy/examples/global_map.py index 6d7835e32..db3874ffa 100644 --- a/lib/cartopy/examples/global_map.py +++ b/lib/cartopy/examples/global_map.py @@ -2,6 +2,9 @@ Global Map ---------- +An example of a simple map that compares Geodetic and Plate Carree lines +between two locations. + """ __tags__ = ['Lines and polygons'] diff --git a/lib/cartopy/examples/hurricane_katrina.py b/lib/cartopy/examples/hurricane_katrina.py index 97f0ef32c..c28ff1de6 100644 --- a/lib/cartopy/examples/hurricane_katrina.py +++ b/lib/cartopy/examples/hurricane_katrina.py @@ -2,6 +2,9 @@ Hurricane Katrina ----------------- +This example uses the power of Shapely to illustrate states that are likely to +have been significantly impacted by Hurricane Katrine. + """ __tags__ = ['Lines and polygons'] diff --git a/lib/cartopy/examples/logo.py b/lib/cartopy/examples/logo.py index 6134d0240..40d0485e2 100644 --- a/lib/cartopy/examples/logo.py +++ b/lib/cartopy/examples/logo.py @@ -1,6 +1,8 @@ """ -Logo ----- +Cartopy Logo +------------ + +The actual code to produce cartopy's logo. """ import cartopy.crs as ccrs diff --git a/lib/cartopy/examples/rotated_pole.py b/lib/cartopy/examples/rotated_pole.py index cf5a3da67..21f393ee9 100644 --- a/lib/cartopy/examples/rotated_pole.py +++ b/lib/cartopy/examples/rotated_pole.py @@ -2,7 +2,7 @@ Rotated pole boxes ------------------ -This example demonstrates the way a box is warped when it is defined +A demonstration of the way a box is warped when it is defined in a rotated pole coordinate system. Try changing the ``box_top`` to ``44``, ``46`` and ``75`` to see the effect diff --git a/lib/cartopy/examples/un_flag.py b/lib/cartopy/examples/un_flag.py index d4a9f3a5a..95bde45ef 100644 --- a/lib/cartopy/examples/un_flag.py +++ b/lib/cartopy/examples/un_flag.py @@ -2,6 +2,9 @@ UN Flag ------- +A demonstration of the power of Matplotlib combined with cartopy's Azimuthal +Equidistant projection to reproduce the UN flag. + """ import cartopy.crs as ccrs import cartopy.feature as cfeature diff --git a/lib/cartopy/examples/waves.py b/lib/cartopy/examples/waves.py index d3439a9e2..c9bfd5bfd 100644 --- a/lib/cartopy/examples/waves.py +++ b/lib/cartopy/examples/waves.py @@ -1,6 +1,8 @@ """ -Waves ------ +Filled contours +--------------- + +An example of contourf on manufactured data. """ __tags__ = ['Scalar data'] From 08c8608a302371f67ccb5f54b454b2b3d4d35647 Mon Sep 17 00:00:00 2001 From: Phil Elson Date: Wed, 21 Feb 2018 19:27:57 +0000 Subject: [PATCH 5/5] Updated the year in the docs. --- docs/source/_templates/layout.html | 2 +- lib/cartopy/examples/hurricane_katrina.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/_templates/layout.html b/docs/source/_templates/layout.html index bbcd3627a..1d8ab96c4 100644 --- a/docs/source/_templates/layout.html +++ b/docs/source/_templates/layout.html @@ -40,7 +40,7 @@

Documentation licensed under the Open Government Licence

{%- if show_copyright %} - © British Crown Copyright 2011 - 2017, Met Office + © British Crown Copyright 2011 - 2018, Met Office {%- endif %} {%- if last_updated %} {% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %} diff --git a/lib/cartopy/examples/hurricane_katrina.py b/lib/cartopy/examples/hurricane_katrina.py index c28ff1de6..1f83e31f5 100644 --- a/lib/cartopy/examples/hurricane_katrina.py +++ b/lib/cartopy/examples/hurricane_katrina.py @@ -3,7 +3,7 @@ ----------------- This example uses the power of Shapely to illustrate states that are likely to -have been significantly impacted by Hurricane Katrine. +have been significantly impacted by Hurricane Katrina. """ __tags__ = ['Lines and polygons']