## 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 ] [ -Dreso-
           lution ] [ -Eazimuth/elevation ] [ -Gfill ] [ -Iriver[/pen] ] [ -K ]  [
           -L[f][x]lon0/lat0[/slon]/slat/length[m|n|k][:label:just][+ppen][+ffill]
           ] [ -O ] [ -M[flag] ] [ -Nborder[/pen] ] [ -O ] [ -P ] [ -Q ] [  -Sfill
           ]   [   -T[f|m][x]lon0/lat0/size[/info][:w,e,s,n:][+gint[/mint]]   ]  [
           -U[/dx/dy/][label] ] [ -V ] [ -Wpen ] [ -Xx-shift ]  [  -Yy-shift  ]  [
           -ccopies ] [ -bo[s][n] ]

## DESCRIPTION

           pscoast  plots  grayshaded, colored, or textured land-masses [or water-
           masses] on maps and [optionally] draws coastlines, rivers, and  politi-
           cal  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 reso-
           lutions. If the user selects to paint the land-areas and does not spec-
           ify 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 setting in .gmtdefaults4, but this
                  can be overridden on the command line by appending c, i, or m to
                  the  scale/width  value.   For map height, max dimension, or min
                  dimension, append h, +, or - to the width, respectively.

                  CYLINDRICAL PROJECTIONS:

                  -Jclon0/lat0/scale (Cassini)
                  -Jjlon0/scale (Miller)
                  -Jmscale (Mercator - Greenwich and Equator as origin)
                  -Jmlon0/lat0/scale (Mercator - Give meridian and standard paral-
                  lel)
                  -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 Car-
                  ree))
                  -Jtlon0/scale (TM - Transverse Mercator, with Equator as y = 0)
                  -Jtlon0/lat0/scale (TM - Transverse Mercator, set origin)
                  -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/[slat/]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:

                  -Jp[a]scale[/origin] (polar (theta,r)  coordinates,  optional  a
                  for azimuths and offset theta [0])
                  -Jxx-scale[l|ppow][/y-scale[l|ppow]][d]  (Linear, log, and power
                  scaling)
                  More details can be found in the psbasemap man pages.

           -R     xmin, xmax, ymin, and ymax specify the Region of  interest.  For
                  geographic  regions,  these  limits  correspond  to  west, east,
                  south, and north and you may specify them in decimal degrees  or
                  in  [+-]dd:mm[:ss.xxx][W|E|S|N]  format.  Append r if lower left
                  and upper right map coordinates are given instead of  wesn.  The
                  two  shorthands  -Rg  -Rd  stand  for  global  domain  (0/360 or
                  -180/+180 in longitude respectively, with -90/+90 in  latitude).
                  For  calendar time coordinates you may either give relative time
                  (relative  to  the  selected  TIME_EPOCH  and  in  the  selected
                  TIME_UNIT;  append  t  to  -JX|x),  or absolute time of the form
                  [date]T[clock] (append T to -JX|x). At least  one  of  date  and
                  clock must be present; the T is always required. The date string
                  must be of the form [-]yyyy[-mm[-dd]]  (Gregorian  calendar)  or
                  yyyy[-Www[-d]]  (ISO week calendar), while the clock string must
                  be of the form hh:mm:ss[.xxx]. The use of delimiters  and  their
                  type  and  positions must be as indicated (however, input/output
                  and plotting formats are flexible).

## OPTIONS

           -A     Features with an area smaller than min_area in km^2 or of  hier-
                  archical  level  that  is  lower  than  min_level or higher than
                  max_level will not be plotted [Default is 0/0/4 (all features)].
                  See DATABASE INFORMATION below for more details.

           -B     Sets  map  boundary  annotation  and tickmark intervals; see the
                  psbasemap man page for all the details.

           -C     Set the shade (0-255), color (r/g/b),  or  pattern  (p|Pdpi/pat-
                  tern;  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 resolution drops off by
                  80% between data sets. [Default is l].

           -E     Sets the viewpoint’s  azimuth  and  elevation  (for  perspective
                  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, each in 0-255, h/s/v, with h in 0-360, s, and v in
                  0-1, and set COLOR_MODEL = hsv, or c/m/y/k, each  in  0-100  %).
                  Alternatively,  specify  -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. The 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 Cookbook & Technical  Ref-
                  erence Appendix E for information on individual patterns.

           -I     Draw  rivers. Specify the type of rivers and [optionally] 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 spec-
                  ify x/y position instead.  Scale is calculated at latitude  slat
                  (optionally   supply  longitude  slon  for  oblique  projections
                  [Default is central meridian]), 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]. The default label  equals  the
                  distance  unit  (km,  miles, nautical miles) and is justified on
                  top of the scale [t]. Change this by giving your own label (or -
                  to  keep the default) and justification (l(eft), r(ight), t(op),
                  b(ottom), and u(unit) - using the label as a  unit  appended  to
                  all  distance annotations along the scale). If you want to place
                  a rectangle behind the scale, specify pen and/or fill parameters
                  with the +p and +f modifiers.

           -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  boundary  and
                  [optionally]  append  pen  attributes  [Default  pen: width = 1,
                  color = 0/0/0, texture = solid]. Choose from the list of  bound-
                  aries 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 sys-
                  tem].

           -P     Selects Portrait plotting mode [GMT Default  is  Landscape,  see
                  gmtdefaults to change this].

           -Q     Mark  end  of  existing  clip path. No projection information 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.

           -T     Draws  a  simple map directional rose centered on lon0/lat0. Use
                  -Tx to specify x/y position instead.  The size is  the  diameter
                  of  the rose, and optional label information can be specified to
                  override the default values of W, E, S, and N (Give ::  to  sup-
                  press  all  labels).  The  default  [plain] map rose only labels
                  north. Use -Tf to get a "fancy" rose, and specify what  kind  of
                  rose  you want drawn. The default [1] draws the two principal E-
                  W, N-S orientations, 2 adds the two intermediate NW-SE and NE-SW
                  orientations, while 3 adds the eight minor orientations WNW-ESE,
                  NNW-SSE, NNE-SSW, and ENE-WSW.  For  a  magnetic  compass  rose,
                  specify  -Tm. If given, info must be the two parameters dec/dla-
                  bel, where dec is the magnetic declination and dlabel is a label
                  for  the  magnetic compass needle (specify ’-’ to format a label
                  from dec). Then, both  directions  to  geographic  and  magnetic
                  north  are  plotted  [Default  is geographic only]. If the north
                  label = * then a north star is  plotted  instead  of  the  north
                  label.  Annotation  and  two  levels  of tick intervals for geo-
                  graphic and magnetic directions are 10/5/1 and  30/5/1  degrees,
                  respectively;    override    these    settings    by   appending
                  +gints[/mints].   Color  and  pen  attributes  are  taken   from
                  COLOR_BACKGROUND  and  TICK_PEN, respectively, while label fonts
                  and sizes follow the usual annotation, label,  and  header  font
                  settings.

           -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.).  The  GMT  parameters
                  UNIX_TIME  and  UNIX_TIME_POS can affect the appearance; see the
                  gmtdefaults man page for details.

           -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 abso-
                  lute coordinates; the default (r) will reset plot origin.   Give
                  c to center plot using current page size.

           -c     Specifies the number of plot copies. [Default is 1].

           -bo    Selects binary output. Append s for single precision [Default is
                  double].  Append n for the  number  of  columns  in  the  binary
                  file(s).

## EXAMPLES

           To plot a green Africa with white outline on blue background, with per-
           manent major rivers in thick blue pen, additional major rivers in  thin
           blue  pen,  and  national  borders as dashed lines on a Mercator map at
           scale 0.1 inch/degree, use

           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, run

           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, use

           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 cor-
           recting for crossings between polygons. The area of  each  polygon  has
           been  determined  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 variable). If the desired  file  is
           not  found, it will look for the file coastline.conf in the same direc-
           tory. 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  pro-
           jection  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,
           respectively). This projection is not supported for clipping.
           The political borders are for the most part 1970ies-style  and  do  not
           reflect the recent border rearrangements in Europe. We intend to update
           these as high-resolution data become available to us.
           Some users of pscoast will not be satisfied with what they find for the
           Antarctic  shoreline. In Antarctica, the boundary between ice and ocean
           varies seasonally and interannually. There are some areas of  permanent
           sea  ice. In addition 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 con-
           sistency’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  Monitoring  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,  Lensfield  Road,
           Cambridge CB2 1ER, United Kingdom.

## SEE ALSO

           gmtdefaults(l), gmt(l), grdlandmask(l), psbasemap(l)

    GMT4.0                            1 Oct 2004                        PSCOAST(l)