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