1PSCOAST(1) Generic Mapping Tools PSCOAST(1)
2
6 pscoast - To plot land-masses, water-masses, coastlines, borders, and
7 rivers
8
10 pscoast -Jparameters -Rwest/east/south/north[r] [
11 -Amin_area[/min_level/max_level][+r|l][ppercent] ] [ -B[p|s]parameters
12 ] [ -C[l|r/]fill ] [ -Dresolution[+] ] [
13 -Eazim/elev[+wlon/lat[/z]][+vx0/y0] ] [ -Gfill|c ] [ -Iriver[/pen] ] [
14 -Jz|Zparameters ] [ -K ] [
15 -L[f][x]lon0/lat0[/slon]/slat/length[m|n|k][+lla‐
16 bel][+jjust][+ppen][+ffill][+u] ] ] [ -O ] [ -Nborder[/pen] ] [ -O ] [
17 -P ] [ -Q ] [ -Sfill|c ] [
18 -T[f|m][x]lon0/lat0/size[/info][:w,e,s,n:][+gint[/mint]] ] [
19 -U[just/dx/dy/][c|label] ] [ -V ] [ -W[level/]pen ] [ -X[a|c|r][x-
20 shift[u]] ] [ -Y[a|c|r][y-shift[u]] ] [ -Zzlevel ] [ -ccopies ] [
21 -bo[s|S|d|D[ncol]|c[var1/...]] ] [ -m[flag] ]
22
24 pscoast plots grayshaded, colored, or textured land-masses [or water-
25 masses] on maps and [optionally] draws coastlines, rivers, and politi‐
26 cal boundaries. Alternatively, it can (1) issue clip paths that will
27 contain all land or all water areas, or (2) dump the data to an ASCII
28 table. The data files come in 5 different resolutions: (f)ull, (h)igh,
29 (i)ntermediate, (l)ow, and (c)rude. The full resolution files amount
30 to more than 55 Mb of data and provide great detail; for maps of larger
31 geographical extent it is more economical to use one of the other reso‐
32 lutions. If the user selects to paint the land-areas and does not
33 specify fill of water-areas then the latter will be transparent (i.e.,
34 earlier graphics drawn in those areas will not be overwritten). Like‐
35 wise, if the water-areas are painted and no land fill is set then the
36 land-areas will be transparent. A map projection must be supplied.
37 The PostScript code is written to standard output.
38 -J Selects the map projection. Scale is UNIT/degree, 1:xxxxx, or
40 width in UNIT (upper case modifier). UNIT is cm, inch, or m,
41 depending on the MEASURE_UNIT setting in .gmtdefaults4, but this
42 can be overridden on the command line by appending c, i, or m to
43 the scale/width value. When central meridian is optional,
44 default is center of longitude range on -R option. Default
45 standard parallel is the equator. For map height, max dimen‐
46 sion, or min dimension, append h, +, or - to the width, respec‐
47 tively.
48 More details can be found in the psbasemap man pages.
49 CYLINDRICAL PROJECTIONS:
51 -Jclon0/lat0/scale (Cassini)
53 -Jcyl_stere/[lon0/[lat0/]]scale (Cylindrical Stereographic)
54 -Jj[lon0/]scale (Miller)
55 -Jm[lon0/[lat0/]]scale (Mercator)
56 -Jmlon0/lat0/scale (Mercator - Give meridian and standard paral‐
57 lel)
58 -Jo[a]lon0/lat0/azimuth/scale (Oblique Mercator - point and
59 azimuth)
60 -Jo[b]lon0/lat0/lon1/lat1/scale (Oblique Mercator - two points)
61 -Joclon0/lat0/lonp/latp/scale (Oblique Mercator - point and
62 pole)
63 -Jq[lon0/[lat0/]]scale (Cylindrical Equidistant)
64 -Jtlon0/[lat0/]scale (TM - Transverse Mercator)
65 -Juzone/scale (UTM - Universal Transverse Mercator)
66 -Jy[lon0/[lat0/]]scale (Cylindrical Equal-Area)
67 CONIC PROJECTIONS:
69 -Jblon0/lat0/lat1/lat2/scale (Albers)
71 -Jdlon0/lat0/lat1/lat2/scale (Conic Equidistant)
72 -Jllon0/lat0/lat1/lat2/scale (Lambert Conic Conformal)
73 -Jpoly/[lon0/[lat0/]]scale ((American) Polyconic)
74 AZIMUTHAL PROJECTIONS:
76 -Jalon0/lat0[/horizon]/scale (Lambert Azimuthal Equal-Area)
78 -Jelon0/lat0[/horizon]/scale (Azimuthal Equidistant)
79 -Jflon0/lat0[/horizon]/scale (Gnomonic)
80 -Jglon0/lat0[/horizon]/scale (Orthographic)
81 -Jglon0/lat0/altitude/azimuth/tilt/twist/Width/Height/scale
82 (General Perspective).
83 -Jslon0/lat0[/horizon]/scale (General Stereographic)
84 MISCELLANEOUS PROJECTIONS:
86 -Jh[lon0/]scale (Hammer)
88 -Ji[lon0/]scale (Sinusoidal)
89 -Jkf[lon0/]scale (Eckert IV)
90 -Jk[s][lon0/]scale (Eckert VI)
91 -Jn[lon0/]scale (Robinson)
92 -Jr[lon0/]scale (Winkel Tripel)
93 -Jv[lon0/]scale (Van der Grinten)
94 -Jw[lon0/]scale (Mollweide)
95 NON-GEOGRAPHICAL PROJECTIONS:
97 -Jp[a]scale[/origin][r|z] (Polar coordinates (theta,r))
99 -Jxx-scale[d|l|ppow|t|T][/y-scale[d|l|ppow|t|T]] (Linear, log,
100 and power scaling)
101 -R west, east, south, and north specify the Region of interest, and
103 you may specify them in decimal degrees or in
104 [+-]dd:mm[:ss.xxx][W|E|S|N] format. Append r if lower left and
105 upper right map coordinates are given instead of w/e/s/n. The
106 two shorthands -Rg and -Rd stand for global domain (0/360 and
107 -180/+180 in longitude respectively, with -90/+90 in latitude).
108 Alternatively, specify the name of an existing grid file and the
109 -R settings (and grid spacing, if applicable) are copied from
110 the grid.
111
113 No space between the option flag and the associated arguments.
114 -A Features with an area smaller than min_area in km^2 or of hier‐
116 archical level that is lower than min_level or higher than
117 max_level will not be plotted [Default is 0/0/4 (all features)].
118 Level 2 (lakes) contains regular lakes and wide river bodies
119 which we normally include as lakes; append +r to just get river-
120 lakes or +l to just get regular lakes (requires GSHHS 2.0.1 or
121 higher). Finally, append +ppercent to exclude polygons whose
122 percentage area of the corresponding full-resolution feature is
123 less than percent (requires GSHHS 2.0 or higher). See GSHHS
124 INFORMATION below for more details.
125 -B Sets map boundary annotation and tickmark intervals; see the
127 psbasemap man page for all the details.
128 -C Set the shade, color, or pattern for lakes and river-lakes
130 [Default is the fill chosen for "wet" areas (-S)]. Optionally,
131 specify separate fills by prepending l/ for lakes and r/ for
132 river-lakes, repeating the -C option as needed. (See SPECIFYING
133 FILL below).
134 -D Selects the resolution of the data set to use ((f)ull, (h)igh,
136 (i)ntermediate, (l)ow, and (c)rude). The resolution drops off
137 by 80% between data sets [Default is l]. Append + to automati‐
138 cally select a lower resolution should the one requested not be
139 available [abort if not found].
140 -E Sets the viewpoint's azimuth and elevation (for perspective
142 view) [180/90]. For frames used for animation, you may want to
143 append + to fix the center of your data domain (or specify a
144 particular world coordinate point with +wlon0/lat[/z]) which
145 will project to the center of your page size (or specify the
146 coordinates of the projected veiw point with +vx0/y0).
147 -G Select filling or clipping of "dry" areas. Append the shade,
149 color, or pattern (see SPECIFYING FILL below); or use -Gc for
150 clipping [Default is no fill].
151 -I Draw rivers. Specify the type of rivers and [optionally] append
153 pen attributes [Default pen: width = 0.25p, color = black, tex‐
154 ture = solid]. (See SPECIFYING PENS below).
155 Choose from the list of river types below. Repeat option -I as
156 often as necessary.
157 1 = Permanent major rivers
158 2 = Additional major rivers
159 3 = Additional rivers
160 4 = Minor rivers
161 5 = Intermittent rivers - major
162 6 = Intermittent rivers - additional
163 7 = Intermittent rivers - minor
164 8 = Major canals
165 9 = Minor canals
166 10 = Irrigation canals
167 a = All rivers and canals (1-10)
168 r = All permanent rivers (1-4)
169 i = All intermittent rivers (5-7)
170 c = All canals (8-10)
171 -Jz Sets the vertical scaling (for 3-D maps). Same syntax as -Jx.
173 -K More PostScript code will be appended later [Default terminates
175 the plot system].
176 -L Draws a simple map scale centered on lon0/lat0. Use -Lx to
178 specify x/y position instead. Scale is calculated at latitude
179 slat (optionally supply longitude slon for oblique projections
180 [Default is central meridian]), length is in km [miles if m is
181 appended; nautical miles if n is appended]. Use -Lf to get a
182 "fancy" scale [Default is plain]. Append +l to select the
183 default label which equals the distance unit (km, miles, nauti‐
184 cal miles) and is justified on top of the scale [t]. Change
185 this by giving your own label (append +llabel). Change label
186 justification with +jjustification (choose among l(eft),
187 r(ight), t(op), and b(ottom)). Apply +u to append the unit to
188 all distance annotations along the scale. If you want to place
189 a rectangle behind the scale, specify suitable +ppen and/or
190 +ffill parameters. (See SPECIFYING PENS and SPECIFYING FILL
191 below).
192 -N Draw political boundaries. Specify the type of boundary and
194 [optionally] append pen attributes [Default pen: width = 0.25p,
195 color = black, texture = solid]. (See SPECIFYING PENS below).
196 (See SPECIFYING PENS below).
197 Choose from the list of boundaries below. Repeat option -N as
198 often as necessary.
199 1 = National boundaries
200 2 = State boundaries within the Americas
201 3 = Marine boundaries
202 a = All boundaries (1-3)
203 -O Selects Overlay plot mode [Default initializes a new plot sys‐
205 tem].
206 -P Selects Portrait plotting mode [Default is Landscape, see gmtde‐
208 faults to change this].
209 -Q Mark end of existing clip path. No projection information is
211 needed. However, you must supply -Xa and -Ya settings if you
212 are using absolute positioning.
213 -S Select filling or clipping of "wet" areas. Append the shade,
215 color, or pattern (see SPECIFYING FILL below); or use -Sc for
216 clipping [Default is no fill].
217 -T Draws a simple map directional rose centered on lon0/lat0. Use
219 -Tx to specify x/y position instead. The size is the diameter
220 of the rose, and optional label information can be specified to
221 override the default values of W, E, S, and N (Give :: to sup‐
222 press all labels). The default [plain] map rose only labels
223 north. Use -Tf to get a "fancy" rose, and specify in info what
224 you want drawn. The default [1] draws the two principal E-W, N-
225 S orientations, 2 adds the two intermediate NW-SE and NE-SW ori‐
226 entations, while 3 adds the eight minor orientations WNW-ESE,
227 NNW-SSE, NNE-SSW, and ENE-WSW. For a magnetic compass rose,
228 specify -Tm. If given, info must be the two parameters dec/dla‐
229 bel, where dec is the magnetic declination and dlabel is a label
230 for the magnetic compass needle (specify - to format a label
231 from dec). Then, both directions to geographic and magnetic
232 north are plotted [Default is geographic only]. If the north
233 label is * then a north star is plotted instead of the north
234 label. Annotation and two levels of tick intervals for geo‐
235 graphic and magnetic directions are 10/5/1 and 30/5/1 degrees,
236 respectively; override these settings by appending
237 +gints[/mints]. Color and pen attributes are taken from
238 COLOR_BACKGROUND and TICK_PEN, respectively, while label fonts
239 and sizes follow the usual annotation, label, and header font
240 settings.
241 -U Draw Unix System time stamp on plot. By adding just/dx/dy/, the
243 user may specify the justification of the stamp and where the
244 stamp should fall on the page relative to lower left corner of
245 the plot. For example, BL/0/0 will align the lower left corner
246 of the time stamp with the lower left corner of the plot.
247 Optionally, append a label, or c (which will plot the command
248 string.). The GMT parameters UNIX_TIME, UNIX_TIME_POS, and
249 UNIX_TIME_FORMAT can affect the appearance; see the gmtdefaults
250 man page for details. The time string will be in the locale set
251 by the environment variable TZ (generally local time).
252 -V Selects verbose mode, which will send progress reports to stderr
254 [Default runs "silently"].
255 -W Draw shorelines [Default is no shorelines]. Append pen
257 attributes [Defaults: width = 0.25p, color = black, texture =
258 solid] which apply to all four levels. To set the pen for each
259 level differently, prepend level/, where level is 1-4 and repre‐
260 sent coastline, lakeshore, island-in-lake shore, and lake-in-
261 island-in-lake shore. Repeat -W as needed. When specific level
262 pens are set, those not listed will not be drawn [Default draws
263 all levels; but see -A]. (See SPECIFYING PENS below).
264 -X -Y Shift plot origin relative to the current origin by (x-shift,y-
266 shift) and optionally append the length unit (c, i, m, p). You
267 can prepend a to shift the origin back to the original position
268 after plotting, or prepend r [Default] to reset the current
269 origin to the new location. If -O is used then the default (x-
270 shift,y-shift) is (0,0), otherwise it is (r1i, r1i) or (r2.5c,
271 r2.5c). Alternatively, give c to align the center coordinate (x
272 or y) of the plot with the center of the page based on current
273 page size.
274 -Z For 3-D projections: Sets the z-level of the coastlines [0].
276 -bo Selects binary output. Append s for single precision [Default
278 is d (double)]. Uppercase S or D will force byte-swapping.
279 Optionally, append ncol, the number of desired columns in your
280 binary output file.
281 -c Specifies the number of plot copies. [Default is 1].
283 -m Dumps a single multisegment ASCII (or binary, see -bo) file to
285 standard output. No plotting occurs. Specify any combination
286 of -W, -I, -N. Optionally, you may append the flag character
287 that is written at the start of each segment header ['>'].
288 SPECIFYING PENS
290 pen The attributes of lines and symbol outlines as defined by pen is
291 a comma delimetered list of width, color and texture, each of
292 which is optional. width can be indicated as a measure (points,
293 centimeters, inches) or as faint, thin[ner|nest], thick[er|est],
294 fat[ter|test], or obese. color specifies a gray shade or color
295 (see SPECIFYING COLOR below). texture is a combination of
296 dashes `-' and dots `.'.
297 SPECIFYING FILL
299 fill The attribute fill specifies the solid shade or solid color (see
300 SPECIFYING COLOR below) or the pattern used for filling poly‐
301 gons. Patterns are specified as pdpi/pattern, where pattern
302 gives the number of the built-in pattern (1-90) or the name of a
303 Sun 1-, 8-, or 24-bit raster file. The dpi sets the resolution
304 of the image. For 1-bit rasters: use Pdpi/pattern for inverse
305 video, or append :Fcolor[B[color]] to specify fore- and back‐
306 ground colors (use color = - for transparency). See GMT Cook‐
307 book & Technical Reference Appendix E for information on indi‐
308 vidual patterns.
309 SPECIFYING COLOR
311 color The color of lines, areas and patterns can be specified by a
312 valid color name; by a gray shade (in the range 0-255); by a
313 decimal color code (r/g/b, each in range 0-255; h-s-v, ranges
314 0-360, 0-1, 0-1; or c/m/y/k, each in range 0-1); or by a hexa‐
315 decimal color code (#rrggbb, as used in HTML). See the gmtcol‐
316 ors manpage for more information and a full list of color names.
317
319 To plot a green Africa with white outline on blue background, with per‐
320 manent major rivers in thick blue pen, additional major rivers in thin
321 blue pen, and national borders as dashed lines on a Mercator map at
322 scale 0.1 inch/degree, use
323 pscoast -R-30/30/-40/40 -Jm0.1i -B5 -I1/1p,blue -I2/0.25p,blue
325 -N1/0.25p,- -W0.25p,white -Ggreen -Sblue -P > africa.ps
326 To plot Iceland using the lava pattern (# 28) at 100 dots per inch, on
328 a Mercator map at scale 1 cm/degree, run
329 pscoast -R-30/-10/60/65 -Jm1c -B5 -Gp100/28 > iceland.ps
331 To initiate a clip path for Africa so that the subsequent colorimage of
333 gridded topography is only seen over land, using a Mercator map at
334 scale 0.1 inch/degree, use
335 pscoast -R-30/30/-40/40 -Jm0.1i -B5 -Gc -P -K > africa.ps
337 grdimage -Jm0.1i etopo5.grd -Ccolors.cpt -O -K >> africa.ps
338 pscoast -Q -O >> africa.ps
339 pscoast will first look for coastline files in directory
341 $GMT_SHAREDIR/coast If the desired file is not found, it will look for
342 the file $GMT_SHAREDIR/coastline.conf. This file may contain any num‐
343 ber of records that each holds the full pathname of an alternative
344 directory. Comment lines (#) and blank lines are allowed. The desired
345 file is then sought for in the alternate directories.
346
348 The coastline database is GSHHS which is compiled from two sources:
349 World Vector Shorelines (WVS) and CIA World Data Bank II (WDBII). In
350 particular, all level-1 polygons (ocean-land boundary) are derived from
351 the more accurate WVS while all higher level polygons (level 2-4, rep‐
352 resenting land/lake, lake/island-in-lake, and island-in-lake/lake-in-
353 island-in-lake boundaries) are taken from WDBII. Much processing has
354 taken place to convert WVS and WDBII data into usable form for GMT:
355 assembling closed polygons from line segments, checking for duplicates,
356 and correcting for crossings between polygons. The area of each poly‐
357 gon has been determined so that the user may choose not to draw fea‐
358 tures smaller than a minimum area (see -A); one may also limit the
359 highest hierarchical level of polygons to be included (4 is the maxi‐
360 mum). The 4 lower-resolution databases were derived from the full res‐
361 olution database using the Douglas-Peucker line-simplification algo‐
362 rithm. The classification of rivers and borders follow that of the
363 WDBII. See the GMT Cookbook and Technical Reference Appendix K for
364 further details.
365
367 The options to fill (-C -G -S) may not always work if the Azimuthal
368 equidistant projection is chosen (-Je|E). If the antipole of the pro‐
369 jection is in the oceans it will most likely work. If not, try to
370 avoid using projection center coordinates that are even multiples of
371 the coastline bin size (1, 2, 5, 10, and 20 degrees for f, h, i, l, c,
372 respectively). This projection is not supported for clipping.
373 The political borders are for the most part 1970s-style but have been
374 updated to reflect more recent border rearrangements in Europe and
375 elsewhere. Let us know if you find something out of date.
376 Some users of pscoast will not be satisfied with what they find for the
377 Antarctic shoreline. In Antarctica, the boundary between ice and ocean
378 varies seasonally and inter-annually. There are some areas of perma‐
379 nent sea ice. In addition to these time-varying ice-ocean boundaries,
380 there are also ice grounding lines where ice goes from floating on the
381 sea to sitting on land, and lines delimiting areas of rock outcrop.
382 For consistency's sake, we have used the World Vector Shoreline
383 throughout the world in pscoast, as described in the GMT Cookbook Ap‐
384 pendix K. Users who need specific boundaries in Antarctica should get
385 the Antarctic Digital Database, prepared by the British Antarctic Sur‐
386 vey, Scott Polar Research Institute, World Conservation Monitoring Cen‐
387 tre, under the auspices of the Scientific Committee on Antarctic
388 Research. This data base contains various kinds of limiting lines for
389 Antarctica and is available on CD-ROM. It is published by the Scien‐
390 tific Committee on Antarctic Research, Scott Polar Research Institute,
391 Lensfield Road, Cambridge CB2 1ER, United Kingdom.
392
394 gmtcolors(5), gmtdefaults(1), GMT(1), grdlandmask(1), psbasemap(1)
395GMT 4.5.6 10 Mar 2011 PSCOAST(1)