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