NAME
pscoast - To plot land-masses, water-masses, coastlines,
borders, and rivers
SYNOPSIS
pscoast -Jparameters -Rwest/east/south/north[r] [
-Amin_area[min_level//max_level] ] [ -Btickinfo ] [ -Cfill ]
[ -Dresolution ] [ -Eazimuth/elevation ] [ -Gfill ] [
-Iriver[/pen] ] [ -K ] [
-L[f][x]lon0/lat0/slat/length[m|n|k] ] [ -M[flag] ] [
-Nborder[/pen] ] [ -O ] [ -P ] [ -Q ] [ -Sfill ] [
-U[/dx/dy/][label] ] [ -V ] [ -Wpen ] [ -Xx-shift ] [ -Yy-
shift ] [ -ccopies ] [ -bo[s] ]
DESCRIPTION
pscoast plots grayshaded, colored, or textured land-masses
[or water-masses] on maps and [optionally] draws coastlines,
rivers, and political boundaries. Alternatively, it can (1)
issue clip paths that will contain all land or all water
areas, or (2) dump the data to an ASCII table. The
datafiles come in 5 different resolutions: (f)ull, (h)igh,
(i)ntermediate, (l)ow, and (c)rude. The full resolution
files amount to more than 55 Mb of data and provide great
detail; for maps of larger geographical extent it is more
economical to use one of the other resolutions. If the user
selects to paint the land-areas and does not specify fill of
water-areas then the latter will be transparent (i.e., ear-
lier graphics drawn in those areas will not be overwritten).
Likewise, if the water-areas are painted and no land fill is
set then the land-areas will be transparent. The PostScript
code is written to standard output.
No space between the option flag and the associated
arguments. Use upper case for the option flags and lower
case for modifiers.
-J Selects the map projection. Scale is UNIT/degree,
1:xxxxx, or width in UNIT (upper case modifier). UNIT
is cm, inch, or m, depending on the MEASURE_UNIT set-
ting in .gmtdefaults, but this can be overridden on the
command line by appending the c, i, or m to the
scale/width value.
CYLINDRICAL PROJECTIONS:
-Jclon0/lat0/scale (Cassini)
-Jjlon0/scale (Miller)
-Jmscale (Mercator - Greenwich and Equator as origin)
-Jmlon0/lat0/scale (Mercator - Give meridian and stan-
dard parallel)
-Joalon0/lat0/azimuth/scale (Oblique Mercator - point
and azimuth)
-Joblon0/lat0/lon1/lat1/scale (Oblique Mercator - two
points)
-Joclon0/lat0/lonp/latp/scale (Oblique Mercator - point
and pole)
-Jqlon0/scale (Equidistant Cylindrical Projection
(Plate Carree))
-Jtlon0/scale (TM - Transverse Mercator, with Equator
as y = 0)
-Jtlon0/lat0/scale (TM - Transverse Mercator, set ori-
gin)
-Juzone/scale (UTM - Universal Transverse Mercator)
-Jylon0/lats/scale (Basic Cylindrical Projection)
AZIMUTHAL PROJECTIONS:
-Jalon0/lat0/scale (Lambert).
-Jelon0/lat0/scale (Equidistant).
-Jflon0/lat0/horizon/scale (Gnomonic).
-Jglon0/lat0/scale (Orthographic).
-Jslon0/lat0/scale (General Stereographic)
CONIC PROJECTIONS:
-Jblon0/lat0/lat1/lat2/scale (Albers)
-Jdlon0/lat0/lat1/lat2/scale (Equidistant)
-Jllon0/lat0/lat1/lat2/scale (Lambert)
MISCELLANEOUS PROJECTIONS:
-Jhlon0/scale (Hammer)
-Jilon0/scale (Sinusoidal)
-Jk[f|s]lon0/scale (Eckert IV (f) and VI (s))
-Jnlon0/scale (Robinson)
-Jrlon0/scale (Winkel Tripel)
-Jvlon0/scale (Van der Grinten)
-Jwlon0/scale (Mollweide)
NON-GEOGRAPHICAL PROJECTIONS:
-Jpscale[/origin] (polar (theta,r) coordinates, option-
ally offset theta [0])
-Jxx-scale[l|ppow][/y-scale[l|ppow]] (Linear, log, and
power scaling)
More details can be found in the psbasemap manpages.
-R west, east, south, and north specify the Region of
interest. To specify boundaries in degrees and minutes
[and seconds], use the dd:mm[:ss] format. Append r if
lower left and upper right map coordinates are given
instead of wesn.
OPTIONS
-A Features with an area smaller than min_area in km^2 or
of hierarchical level that is lower than min_level or
higher than max_level will not be plotted [Default is
0/4 (all features)]. See DATABASE INFORMATION below for
more details.
-B Sets map boundary tickmark intervals. See psbasemap for
details.
-C Set the shade (0-255), color (r/g/b), or pattern
(p|Pdpi/pattern; see -G) for lakes [Default is the
fill chosen for "wet" areas (-S)].
-D Selects the resolution of the data set to use ((f)ull,
(h)igh, (i)ntermediate, (l)ow, and (c)rude). The reso-
lution drops off by 80% between data sets. [Default is
l].
-E Sets the viewpoint's azimuth and elevation (for per-
spective view) [180/90]
-G Select painting or clipping of "dry" areas. Append a
shade, color, pattern, or c for clipping. Specify the
shade (0-255) or color (r/g/b), or -Gpdpi/pattern,
where pattern gives the number of the built-in pattern
(1-90) OR the name of a Sun 1-, 8-, or 24-bit raster
file. dpi sets the resolution of the image. For 1-bit
rasters: use -GP for inverse video, or append
:Fr/g/b[B[r/g/b]] to specify fore- and background
colors (use r/g/b = - for transparency). See GMT Cook-
book & Technical Reference Appendix E for information
on individual patterns.
-I Draw rivers. Specify the type of rivers and [option-
ally] append pen attributes [Default pen: width = 1,
color = 0/0/0, texture = solid]. Choose from the list
of river types below. Repeat option -I as often as
necessary.
1 = Permanent major rivers
2 = Additional major rivers
3 = Additional rivers
4 = Minor rivers
5 = Intermittent rivers - major
6 = Intermittent rivers - additional
7 = Intermittent rivers - minor
8 = Major canals
9 = Minor canals
10 = Irrigation canals
a = All rivers and canals (1-10)
r = All permanent rivers (1-4)
i = All intermittent rivers (5-7)
c = All canals (8-10)
-K More PostScript code will be appended later [Default
terminates the plot system].
-L Draws a simple map scale centered on lon0/lat0. Use
-Lx to specify x/y position instead. Scale is calcu-
lated at latitude slat, length is in km [miles if m is
appended; nautical miles if n is appended]. Use -Lf to
get a "fancy" scale [Default is plain].
-M Dumps a single multisegment ASCII (or binary, see -bo)
file to standard output. No plotting occurs. Specify
any combination of -W, -I, -N. Optionally, you may
append the flag character that is written at the start
of each segment header ['>'].
-N Draw political boundaries. Specify the type of boun-
dary and [optionally] append pen attributes [Default
pen: width = 1, color = 0/0/0, texture = solid].
Choose from the list of boundaries below. Repeat
option -N as often as necessary.
1 = National boundaries
2 = State boundaries within the Americas
3 = Marine boundaries
a = All boundaries (1-3)
-O Selects Overlay plot mode [Default initializes a new
plot system].
-P Selects Portrait plotting mode [GMT Default is
Landscape, see gmtdefaults to change this].
-Q Mark end of existing clip path. No projection informa-
tion is needed.
-S Select painting or clipping of "wet" areas. Append the
shade (0-255), color (r/g/b), pattern (see -G), or c
for clipping.
-U Draw Unix System time stamp on plot. User may specify
where the lower left corner of the stamp should fall on
the page relative to lower left corner of plot.
Optionally, append a label, or c (which will plot the
command string.)
-V Selects verbose mode, which will send progress reports
to stderr [Default runs "silently"].
-W Draw coastlines. [Default is no coastlines]. Append
pen attributes [Defaults: width = 1, color = 0/0/0,
texture = solid].
-X -Y
Shift origin of plot by (x-shift,y-shift). Prepend a
for absolute coordinates; the default (r) will reset
plot origin.
-c Specifies the number of plot copies. [Default is 1]
-bo Selects binary output. Append s for single precision
[Default is double].
EXAMPLES
To plot a green Africa with white outline on blue back-
ground, with permanent major rivers in thick blue pen, addi-
tional major rivers in thin blue pen, and national borders
as dashed lines on a Mercator map at scale 0.1 inch/degree,
try
pscoast -R-30/30/-40/40 -Jm0.1i -B5 -I1/1p/0/0/255
-I2/0.25p/0/0/255 -N1/0.25tap -W0.25p/255/255/255 -G0/255/0
-S0/0/255 -P > africa.ps
To plot Iceland using the lava pattern (# 28) at 100 dots
per inch, on a Mercator map at scale 1 cm/degree, try
pscoast -R-30/-10/60/65 -Jm1c -B5 -Gp100/28 > iceland.ps
To initiate a clip path for Africa so that the subsequent
colorimage of gridded topography is only seen over land,
using a Mercator map at scale 0.1 inch/degree, try
pscoast -R-30/30/-40/40 -Jm0.1i -B5 -Gc -P -K > africa.ps
grdimage -Jm0.1i etopo5.grd -Ccolors.cpt -O -K >> africa.ps
pscoast -Q -O >> africa.ps
DATABASE INFORMATION
The coastline database is compiled from two sources: World
Vector Shorelines (WVS) and CIA World Data Bank II (WDBII).
In particular, all level-1 polygons (ocean-land boundary)
are derived from the more accurate WVS while all higher
level polygons (level 2-4, representing land/lake,
lake/island-in-lake, and island-in-lake/lake-in-island-in-
lake boundaries) are taken from WDBII. Much processing has
taken place to convert WVS and WDBII data into usable form
for GMT: assembling closed polygons from line segments,
checking for duplicates, and correcting for crossings
between polygons. The area of each polygon has been deter-
mined so that the user may choose not to draw features
smaller than a minimum area (see -A); one may also limit the
highest hierarchical level of polygons to be included (4 is
the maximum). The 4 lower-resolution databases were derived
from the full resolution database using the Douglas-Peucker
line-simplification algorithm. The classification of rivers
and borders follow that of the WDBII. See the GMT Cookbook
and Technical Reference Appendix K for further details.
pscoast will first look for coastline files in directory
$GMTHOME/share (where $GMTHOME is an environmental vari-
able). If the desired file is not found, it will look for
the file coastline.conf in the same directory. This file
may contain any number of records that each holds the full
pathname of an alternative directory. Comment lines (#) and
blank lines are allowed. The desired file is then sought
for in the alternate directories.
BUGS
The options to fill (-C -G -S) may not always work if the
Azimuthal equidistant projection is chosen (-Je|E). If the
antipole of the projection is in the oceans it will most
likely work. If not, try to avoid using projection center
coordinates that are even multiples of the coastline bin
size (1, 2, 5, 10, and 20 degrees for f, h, i, l, c, respec-
tively). This projection is not supported for clipping.
The political borders are for the most part 1970ies-style
and do not reflect the recent border rearrangments in
Europe. We intend to update these as high-resolution data
become avaiable to us.
Some users of pscoast will not be satisfied with what they
find for the Antarctic shoreline. In Antarctica, the boun-
dary between ice and ocean varies seasonally and interannu-
ally. There are some areas of permanent sea ice. In addi-
tion to these time-varying ice-ocean boundaries, there are
also ice grounding lines where ice goes from floating on the
sea to sitting on land, and lines delimiting areas of rock
outcrop. For consistency's sake, we have used the World
Vector Shoreline throughout the world in pscoast, as
described in the GMT cookbook Appendix K. Users who need
specific boundaries in Antarctica should get the Antarctic
Digital Database, prepared by the British Antarctic Survey,
Scott Polar Research Institute, World Conservation Monitor-
ing Centre, under the auspices of the Scientific Committee
on Antarctic Research. This data base contains various
kinds of limiting lines for Antarctica and is available on
CD-ROM. It is published by the Scientific Committee on
Antarctic Research, Scott Polar Research Institute, Lens-
field Road, Cambridge CB2 1ER, United Kingdom.
SEE ALSO
gmtdefaults(l), gmt(l), grdlandmask(l), psbasemap(l)