Coverage for pyguymer3/geo/add_axis.py: 17%
6 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_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 configureAgain = False,
18 debug = __debug__,
19 dist = 1.0e99,
20 eps = 1.0e-12,
21 fov = None,
22 gridlines_int = None,
23 gridlines_linecolor = "black",
24 gridlines_linestyle = ":",
25 gridlines_linewidth = 0.5,
26 gridlines_zorder = 2.0,
27 gs = None,
28 index = None,
29 lat = None,
30 lon = None,
31 ncols = None,
32 nIter = 100,
33 nrows = None,
34 onlyValid = False,
35 prefix = ".",
36 ramLimit = 1073741824,
37 repair = False,
38 satellite_height = False,
39 tol = 1.0e-10,
40):
41 """Add either a global Robinson axis or an Orthographic axis centred above a
42 point with optionally a field-of-view based on a circle around the point on
43 the surface of the Earth
45 Parameters
46 ----------
47 fg : matplotlib.figure.Figure
48 the figure to add the axis to
49 add_coastlines : bool, optional
50 add coastline boundaries
51 add_gridlines : bool, optional
52 add gridlines of longitude and latitude
53 coastlines_edgecolor : str, optional
54 the colour of the edges of the coastline Polygons
55 coastlines_facecolor : str, optional
56 the colour of the faces of the coastline Polygons
57 coastlines_levels : list of int, optional
58 the levels of the coastline boundaries (if None then default to
59 ``[1, 6]``)
60 coastlines_linestyle : str, optional
61 the linestyle to draw the coastline boundaries with
62 coastlines_linewidth : float, optional
63 the linewidth to draw the coastline boundaries with
64 coastlines_resolution : str, optional
65 the resolution of the coastline boundaries
66 coastlines_zorder : float, optional
67 the zorder to draw the coastline boundaries with (the default value has
68 been chosen to match the value that it ends up being if the coastline
69 boundaries are not drawn with the zorder keyword specified -- obtained
70 by manual inspection on 5/Dec/2023)
71 configureAgain : bool, optional
72 configure the axis a second time (this is a hack to make narrow
73 field-of-view top-down axes work correctly with OpenStreetMap tiles)
74 debug : bool, optional
75 print debug messages and draw the circle on the axis
76 dist : float, optional
77 the radius of the circle around the point, if larger than the Earth then
78 make the axis of global extent (in metres)
79 eps : float, optional
80 the tolerance of the Vincenty formula iterations
81 fov : None or shapely.geometry.polygon.Polygon, optional
82 clip the plotted shapes to the provided field-of-view to work around
83 occaisional MatPlotLib or Cartopy plotting errors when shapes much
84 larger than the field-of-view are plotted
85 gridlines_int : int, optional
86 the interval between gridlines, best results if ``90 % gridlines_int == 0``;
87 if the axis is of global extent then the default will be 45° else it
88 will be 1° (in degrees)
89 gridlines_linecolor : str, optional
90 the colour of the gridlines
91 gridlines_linestyle : str, optional
92 the style of the gridlines
93 gridlines_linewidth : float, optional
94 the width of the gridlines
95 gridlines_zorder : float, optional
96 the zorder to draw the gridlines with (the default value has been chosen
97 to match the value that it ends up being if the gridlines are not drawn
98 with the zorder keyword specified -- obtained by manual inspection on
99 5/Dec/2023)
100 gs : matplotlib.gridspec.SubplotSpec, optional
101 the subset of a gridspec to locate the axis
102 index : int or tuple of int, optional
103 the index of the axis in the array of axes
104 lat : float, optional
105 the latitude of the point (in degrees)
106 lon : float, optional
107 the longitude of the point (in degrees)
108 ncols : int, optional
109 the number of columns in the array of axes
110 nIter : int, optional
111 the maximum number of iterations (particularly the Vincenty formula)
112 nrows : int, optional
113 the number of rows in the array of axes
114 onlyValid : bool, optional
115 only return valid Polygons (checks for validity can take a while, if
116 being called often)
117 prefix : str, optional
118 change the name of the output debugging CSVs
119 ramLimit : int, optional
120 the maximum RAM usage of each "large" array (in bytes)
121 repair : bool, optional
122 attempt to repair invalid Polygons
123 satellite_height : bool, optional
124 if a distance is provided then use a "NearsidePerspective" projection at
125 an altitude which has the same field-of-view as the distance
126 tol : float, optional
127 the Euclidean distance that defines two points as being the same (in
128 degrees)
130 Returns
131 -------
132 ax : cartopy.mpl.geoaxes.GeoAxesSubplot
133 the axis
135 Notes
136 -----
137 There are two arguments relating to the `Global Self-Consistent Hierarchical
138 High-Resolution Geography dataset <https://www.ngdc.noaa.gov/mgg/shorelines/>`_ :
140 * *coastlines_levels*; and
141 * *coastlines_resolution*.
143 There are six levels to choose from:
145 * boundary between land and ocean (1);
146 * boundary between lake and land (2);
147 * boundary between island-in-lake and lake (3);
148 * boundary between pond-in-island and island-in-lake (4);
149 * boundary between Antarctica ice and ocean (5); and
150 * boundary between Antarctica grounding-line and ocean (6).
152 There are five resolutions to choose from:
154 * crude ("c");
155 * low ("l");
156 * intermediate ("i");
157 * high ("h"); and
158 * full ("f").
160 Copyright 2017 Thomas Guymer [1]_
162 References
163 ----------
164 .. [1] PyGuymer3, https://github.com/Guymer/PyGuymer3
165 """
167 # Import sub-functions ...
168 from ._add_global_axis import _add_global_axis
169 from ._add_topDown_axis import _add_topDown_axis
171 # **************************************************************************
173 # Check what projection should be used ...
174 if lon is not None and lat is not None:
175 # Return answer ...
176 return _add_topDown_axis(
177 fg,
178 lon,
179 lat,
180 add_coastlines = add_coastlines,
181 add_gridlines = add_gridlines,
182 coastlines_edgecolor = coastlines_edgecolor,
183 coastlines_facecolor = coastlines_facecolor,
184 coastlines_levels = coastlines_levels,
185 coastlines_linestyle = coastlines_linestyle,
186 coastlines_linewidth = coastlines_linewidth,
187 coastlines_resolution = coastlines_resolution,
188 coastlines_zorder = coastlines_zorder,
189 configureAgain = configureAgain,
190 debug = debug,
191 dist = dist,
192 eps = eps,
193 fov = fov,
194 gridlines_int = gridlines_int,
195 gridlines_linecolor = gridlines_linecolor,
196 gridlines_linestyle = gridlines_linestyle,
197 gridlines_linewidth = gridlines_linewidth,
198 gridlines_zorder = gridlines_zorder,
199 gs = gs,
200 index = index,
201 ncols = ncols,
202 nIter = nIter,
203 nrows = nrows,
204 onlyValid = onlyValid,
205 prefix = prefix,
206 ramLimit = ramLimit,
207 repair = repair,
208 satellite_height = satellite_height,
209 tol = tol,
210 )
212 # Return answer ...
213 return _add_global_axis(
214 fg,
215 add_coastlines = add_coastlines,
216 add_gridlines = add_gridlines,
217 coastlines_edgecolor = coastlines_edgecolor,
218 coastlines_facecolor = coastlines_facecolor,
219 coastlines_levels = coastlines_levels,
220 coastlines_linestyle = coastlines_linestyle,
221 coastlines_linewidth = coastlines_linewidth,
222 coastlines_resolution = coastlines_resolution,
223 coastlines_zorder = coastlines_zorder,
224 debug = debug,
225 fov = fov,
226 gridlines_int = gridlines_int,
227 gridlines_linecolor = gridlines_linecolor,
228 gridlines_linestyle = gridlines_linestyle,
229 gridlines_linewidth = gridlines_linewidth,
230 gridlines_zorder = gridlines_zorder,
231 gs = gs,
232 index = index,
233 ncols = ncols,
234 nrows = nrows,
235 onlyValid = onlyValid,
236 repair = repair,
237 )