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)