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