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/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][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
       specify fill of water-areas then the latter will be transparent  (i.e.,
       earlier  graphics drawn in those areas will not be overwritten).  Like-
       wise, 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 .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 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]]  (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  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 tickmark intervals; see the psbasemap man page
              for 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.

       -G     Set fill of positive wiggles. [Default  is  black]  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 Cookbook &  Technical
              Reference 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
              specify x/y position instead.  Scale is calculated  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  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.

       -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.

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

       -O     Selects Overlay plot mode [Default initializes a new  plot  sys-
              tem].


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, 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/62/68 -Jm1c -B5 -Gp100/28 -W1p  > 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 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  alter-
       nate 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 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 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)



VERSION                              DATE                           PSCOAST(l)

Man(1) output converted with man2html