Coverage for pyguymer3/geo/_add_global_axis.py: 4%
24 statements
« prev ^ index » next coverage.py v7.10.3, created at 2025-08-16 08:31 +0000
1#!/usr/bin/env python3
3# Define function ...
4def _add_global_axis(
5 fg,
6 /,
7 *,
8 add_coastlines = True,
9 add_gridlines = True,
10 coastlines_edgecolor = "black",
11 coastlines_facecolor = "none",
12 coastlines_levels = None,
13 coastlines_linestyle = "solid",
14 coastlines_linewidth = 0.5,
15 coastlines_resolution = "i",
16 coastlines_zorder = 1.5,
17 debug = __debug__,
18 fov = None,
19 gridlines_int = None,
20 gridlines_linecolor = "black",
21 gridlines_linestyle = ":",
22 gridlines_linewidth = 0.5,
23 gridlines_zorder = 2.0,
24 gs = None,
25 index = None,
26 ncols = None,
27 nrows = None,
28 onlyValid = False,
29 repair = False,
30):
31 """Add a global Robinson axis
33 Parameters
34 ----------
35 fg : matplotlib.figure.Figure
36 the figure to add the axis to
37 add_coastlines : bool, optional
38 add coastline boundaries
39 add_gridlines : bool, optional
40 add gridlines of longitude and latitude
41 coastlines_edgecolor : str, optional
42 the colour of the edges of the coastline Polygons
43 coastlines_facecolor : str, optional
44 the colour of the faces of the coastline Polygons
45 coastlines_levels : list of int, optional
46 the levels of the coastline boundaries (if None then default to
47 ``[1, 6]``)
48 coastlines_linestyle : str, optional
49 the linestyle to draw the coastline boundaries with
50 coastlines_linewidth : float, optional
51 the linewidth to draw the coastline boundaries with
52 coastlines_resolution : str, optional
53 the resolution of the coastline boundaries
54 coastlines_zorder : float, optional
55 the zorder to draw the coastline boundaries with (the default value has
56 been chosen to match the value that it ends up being if the coastline
57 boundaries are not drawn with the zorder keyword specified -- obtained
58 by manual inspection on 5/Dec/2023)
59 debug : bool, optional
60 print debug messages
61 fov : None or shapely.geometry.polygon.Polygon, optional
62 clip the plotted shapes to the provided field-of-view to work around
63 occaisional MatPlotLib or Cartopy plotting errors when shapes much
64 larger than the field-of-view are plotted
65 gridlines_int : int, optional
66 the interval between gridlines, best results if ``90 % gridlines_int == 0``;
67 the default will be 45° (in degrees)
68 gridlines_linecolor : str, optional
69 the colour of the gridlines
70 gridlines_linestyle : str, optional
71 the style of the gridlines
72 gridlines_linewidth : float, optional
73 the width of the gridlines
74 gridlines_zorder : float, optional
75 the zorder to draw the gridlines with (the default value has been chosen
76 to match the value that it ends up being if the gridlines are not drawn
77 with the zorder keyword specified -- obtained by manual inspection on
78 5/Dec/2023)
79 gs : matplotlib.gridspec.SubplotSpec, optional
80 the subset of a gridspec to locate the axis
81 index : int or tuple of int, optional
82 the index of the axis in the array of axes
83 ncols : int, optional
84 the number of columns in the array of axes
85 nrows : int, optional
86 the number of rows in the array of axes
87 onlyValid : bool, optional
88 only return valid Polygons (checks for validity can take a while, if
89 being called often)
90 repair : bool, optional
91 attempt to repair invalid Polygons
93 Returns
94 -------
95 ax : cartopy.mpl.geoaxes.GeoAxesSubplot
96 the axis
98 Notes
99 -----
100 There are two arguments relating to the `Global Self-Consistent Hierarchical
101 High-Resolution Geography dataset <https://www.ngdc.noaa.gov/mgg/shorelines/>`_ :
103 * *coastlines_levels*; and
104 * *coastlines_resolution*.
106 There are six levels to choose from:
108 * boundary between land and ocean (1);
109 * boundary between lake and land (2);
110 * boundary between island-in-lake and lake (3);
111 * boundary between pond-in-island and island-in-lake (4);
112 * boundary between Antarctica ice and ocean (5); and
113 * boundary between Antarctica grounding-line and ocean (6).
115 There are five resolutions to choose from:
117 * crude ("c");
118 * low ("l");
119 * intermediate ("i");
120 * high ("h"); and
121 * full ("f").
123 Copyright 2017 Thomas Guymer [1]_
125 References
126 ----------
127 .. [1] PyGuymer3, https://github.com/Guymer/PyGuymer3
128 """
130 # Import standard modules ...
131 import pathlib
133 # Import special modules ...
134 try:
135 import cartopy
136 cartopy.config.update(
137 {
138 "cache_dir" : pathlib.PosixPath("~/.local/share/cartopy_cache").expanduser(),
139 }
140 )
141 except:
142 raise Exception("\"cartopy\" is not installed; run \"pip install --user Cartopy\"") from None
144 # Import sub-functions ...
145 from ._add_coastlines import _add_coastlines
146 from ._add_horizontal_gridlines import _add_horizontal_gridlines
147 from ._add_vertical_gridlines import _add_vertical_gridlines
149 # **************************************************************************
151 # Check inputs ...
152 if gridlines_int is None:
153 gridlines_int = 45 # [°]
155 # Check where the axis should be created ...
156 if gs is not None:
157 # Create axis ...
158 ax = fg.add_subplot(
159 gs,
160 projection = cartopy.crs.Robinson(),
161 )
162 elif nrows is not None and ncols is not None and index is not None:
163 # Create axis ...
164 ax = fg.add_subplot(
165 nrows,
166 ncols,
167 index,
168 projection = cartopy.crs.Robinson(),
169 )
170 else:
171 # Create axis ...
172 ax = fg.add_subplot(
173 projection = cartopy.crs.Robinson(),
174 )
176 # Configure axis ...
177 ax.set_global()
179 # Check if the user wants to add coastline boundaries ...
180 if add_coastlines:
181 # Add coastline boundaries ...
182 _add_coastlines(
183 ax,
184 debug = debug,
185 edgecolor = coastlines_edgecolor,
186 facecolor = coastlines_facecolor,
187 fov = fov,
188 levels = coastlines_levels,
189 linestyle = coastlines_linestyle,
190 linewidth = coastlines_linewidth,
191 onlyValid = onlyValid,
192 repair = repair,
193 resolution = coastlines_resolution,
194 zorder = coastlines_zorder,
195 )
197 # Check if the user wants to add gridlines ...
198 if add_gridlines:
199 # Add gridlines ...
200 _add_horizontal_gridlines(
201 ax,
202 color = gridlines_linecolor,
203 linestyle = gridlines_linestyle,
204 linewidth = gridlines_linewidth,
205 locs = range( -90, +90 + gridlines_int, gridlines_int),
206 ngrid = -1,
207 npoint = 3601,
208 zorder = gridlines_zorder,
209 )
210 _add_vertical_gridlines(
211 ax,
212 color = gridlines_linecolor,
213 linestyle = gridlines_linestyle,
214 linewidth = gridlines_linewidth,
215 locs = range(-180, +180 + gridlines_int, gridlines_int),
216 ngrid = -1,
217 npoint = 1801,
218 zorder = gridlines_zorder,
219 )
221 # Return answer ...
222 return ax