|
| 1 | +""" |
| 2 | +coast - Plot land and water. |
| 3 | +""" |
| 4 | + |
| 5 | +from pygmt.clib import Session |
| 6 | +from pygmt.exceptions import GMTInvalidInput |
| 7 | +from pygmt.helpers import ( |
| 8 | + args_in_kwargs, |
| 9 | + build_arg_string, |
| 10 | + fmt_docstring, |
| 11 | + kwargs_to_strings, |
| 12 | + use_alias, |
| 13 | +) |
| 14 | + |
| 15 | + |
| 16 | +@fmt_docstring |
| 17 | +@use_alias( |
| 18 | + R="region", |
| 19 | + J="projection", |
| 20 | + A="area_thresh", |
| 21 | + C="lakes", |
| 22 | + B="frame", |
| 23 | + D="resolution", |
| 24 | + E="dcw", |
| 25 | + I="rivers", |
| 26 | + L="map_scale", |
| 27 | + N="borders", |
| 28 | + W="shorelines", |
| 29 | + G="land", |
| 30 | + S="water", |
| 31 | + U="timestamp", |
| 32 | + V="verbose", |
| 33 | + X="xshift", |
| 34 | + Y="yshift", |
| 35 | + p="perspective", |
| 36 | + t="transparency", |
| 37 | +) |
| 38 | +@kwargs_to_strings(R="sequence", p="sequence") |
| 39 | +def coast(self, **kwargs): |
| 40 | + r""" |
| 41 | + Plot continents, shorelines, rivers, and borders on maps |
| 42 | +
|
| 43 | + Plots grayshaded, colored, or textured land-masses [or water-masses] on |
| 44 | + maps and [optionally] draws coastlines, rivers, and political |
| 45 | + boundaries. Alternatively, it can (1) issue clip paths that will |
| 46 | + contain all land or all water areas, or (2) dump the data to an ASCII |
| 47 | + table. The data files come in 5 different resolutions: (**f**)ull, |
| 48 | + (**h**)igh, (**i**)ntermediate, (**l**)ow, and (**c**)rude. The full |
| 49 | + resolution files amount to more than 55 Mb of data and provide great |
| 50 | + detail; for maps of larger geographical extent it is more economical to |
| 51 | + use one of the other resolutions. If the user selects to paint the |
| 52 | + land-areas and does not specify fill of water-areas then the latter |
| 53 | + will be transparent (i.e., earlier graphics drawn in those areas will |
| 54 | + not be overwritten). Likewise, if the water-areas are painted and no |
| 55 | + land fill is set then the land-areas will be transparent. |
| 56 | +
|
| 57 | + A map projection must be supplied. |
| 58 | +
|
| 59 | + Full option list at :gmt-docs:`coast.html` |
| 60 | +
|
| 61 | + {aliases} |
| 62 | +
|
| 63 | + Parameters |
| 64 | + ---------- |
| 65 | + {J} |
| 66 | + {R} |
| 67 | + area_thresh : int, float, or str |
| 68 | + *min_area*\ [/*min_level*/*max_level*][**+ag**\|\ **i**\ |
| 69 | + \|\ **s**\|\ **S**][**+r**\|\ **l**][**+p**\ |
| 70 | + *percent*]. |
| 71 | + Features with an area smaller than min_area in km^2 or of |
| 72 | + hierarchical level that is lower than min_level or higher than |
| 73 | + max_level will not be plotted. |
| 74 | + {B} |
| 75 | + lakes : str or list |
| 76 | + *fill*\ [**+l**\|\ **+r**]. |
| 77 | + Set the shade, color, or pattern for lakes and river-lakes. The |
| 78 | + default is the fill chosen for wet areas set by the ``water`` |
| 79 | + argument. Optionally, specify separate fills by appending |
| 80 | + **+l** for lakes or **+r** for river-lakes, and passing multiple |
| 81 | + strings in a list. |
| 82 | + resolution : str |
| 83 | + **f**\|\ **h**\|\ **i**\|\ **l**\|\ **c**. |
| 84 | + Selects the resolution of the data set to: (**f**\ )ull, |
| 85 | + (**h**\ )igh, (**i**\ )ntermediate, (**l**\ )ow, |
| 86 | + and (**c**\ )rude. |
| 87 | + land : str |
| 88 | + Select filling or clipping of “dry” areas. |
| 89 | + rivers : int or str or list |
| 90 | + *river*\ [/*pen*]. |
| 91 | + Draw rivers. Specify the type of rivers and [optionally] append |
| 92 | + pen attributes [Default pen: width = default, color = black, |
| 93 | + style = solid]. |
| 94 | +
|
| 95 | + Choose from the list of river types below; pass a list to |
| 96 | + ``rivers`` to use multiple arguments. |
| 97 | +
|
| 98 | + 0 = Double-lined rivers (river-lakes) |
| 99 | +
|
| 100 | + 1 = Permanent major rivers |
| 101 | +
|
| 102 | + 2 = Additional major rivers |
| 103 | +
|
| 104 | + 3 = Additional rivers |
| 105 | +
|
| 106 | + 4 = Minor rivers |
| 107 | +
|
| 108 | + 5 = Intermittent rivers - major |
| 109 | +
|
| 110 | + 6 = Intermittent rivers - additional |
| 111 | +
|
| 112 | + 7 = Intermittent rivers - minor |
| 113 | +
|
| 114 | + 8 = Major canals |
| 115 | +
|
| 116 | + 9 = Minor canals |
| 117 | +
|
| 118 | + 10 = Irrigation canals |
| 119 | +
|
| 120 | + You can also choose from several preconfigured river groups: |
| 121 | +
|
| 122 | + a = All rivers and canals (0-10) |
| 123 | +
|
| 124 | + A = All rivers and canals except river-lakes (1-10) |
| 125 | +
|
| 126 | + r = All permanent rivers (0-4) |
| 127 | +
|
| 128 | + R = All permanent rivers except river-lakes (1-4) |
| 129 | +
|
| 130 | + i = All intermittent rivers (5-7) |
| 131 | +
|
| 132 | + c = All canals (8-10) |
| 133 | + map_scale : str |
| 134 | + [**g**\|\ **j**\|\ **J**\|\ **n**\|\ **x**]\ *refpoint*. |
| 135 | + Draws a simple map scale centered on the reference point specified. |
| 136 | + borders : int or str or list |
| 137 | + *border*\ [/*pen*]. |
| 138 | + Draw political boundaries. Specify the type of boundary and |
| 139 | + [optionally] append pen attributes [Default pen: width = default, |
| 140 | + color = black, style = solid]. |
| 141 | +
|
| 142 | + Choose from the list of boundaries below. Pass a list to |
| 143 | + ``borders`` to use multiple arguments. |
| 144 | +
|
| 145 | + 1 = National boundaries |
| 146 | +
|
| 147 | + 2 = State boundaries within the Americas |
| 148 | +
|
| 149 | + 3 = Marine boundaries |
| 150 | +
|
| 151 | + a = All boundaries (1-3) |
| 152 | + water : str |
| 153 | + Select filling or clipping of “wet” areas. |
| 154 | + {U} |
| 155 | + shorelines : int or str or list |
| 156 | + [*level*\ /]\ *pen*. |
| 157 | + Draw shorelines [Default is no shorelines]. Append pen attributes |
| 158 | + [Defaults: width = default, color = black, style = solid] which |
| 159 | + apply to all four levels. To set the pen for a single level, |
| 160 | + pass a string with *level*\ /*pen*\ , where level is |
| 161 | + 1-4 and represent coastline, lakeshore, island-in-lake shore, and |
| 162 | + lake-in-island-in-lake shore. Pass a list of *level*\ /*pen* |
| 163 | + strings to ``shorelines`` to set multiple levels. When specific |
| 164 | + level pens are set, those not listed will not be drawn. |
| 165 | + dcw : str or list |
| 166 | + *code1,code2,…*\ [**+l**\|\ **L**\ ][**+g**\ *fill*\ ] |
| 167 | + [**+p**\ *pen*\ ][**+z**]. |
| 168 | + Select painting or dumping country polygons from the |
| 169 | + `Digital Chart of the World |
| 170 | + <https://en.wikipedia.org/wiki/Digital_Chart_of_the_World>`__. |
| 171 | + Append one or more comma-separated countries using the 2-character |
| 172 | + `ISO 3166-1 alpha-2 convention |
| 173 | + <https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2>`__. |
| 174 | + To select a state of a country (if available), append |
| 175 | + .\ *state*, (e.g, US.TX for Texas). To specify a whole continent, |
| 176 | + prepend **=** to any of the continent codes (e.g. =EU for Europe). |
| 177 | + Append **+p**\ *pen* to draw polygon outlines |
| 178 | + (default is no outline) and **+g**\ *fill* to fill them |
| 179 | + (default is no fill). Append **+l**\|\ **+L** to *=continent* to |
| 180 | + only list countries in that continent; repeat if more than one |
| 181 | + continent is requested. Append **+z** to place the country code in |
| 182 | + the segment headers via **-Z**\ *code* settings.To apply different |
| 183 | + settings to different countries, pass a list of string arguments. |
| 184 | + {XY} |
| 185 | + {p} |
| 186 | + {t} |
| 187 | + {V} |
| 188 | + """ |
| 189 | + kwargs = self._preprocess(**kwargs) # pylint: disable=protected-access |
| 190 | + if not args_in_kwargs(args=["C", "G", "S", "I", "N", "Q", "W"], kwargs=kwargs): |
| 191 | + raise GMTInvalidInput( |
| 192 | + """At least one of the following arguments must be specified: |
| 193 | + lakes, land, water, rivers, borders, Q, or shorelines""" |
| 194 | + ) |
| 195 | + with Session() as lib: |
| 196 | + lib.call_module("coast", build_arg_string(kwargs)) |
0 commit comments