NAME

       pscoast  -  To plot land-masses, water-masses, coastlines, borders, and
       rivers


SYNOPSIS

       pscoast -Jparameters -Rwest/east/south/north[r] [  -Amin_area[min_level
       [  -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 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 .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 spec-
              ify 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 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 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 Antarc-
       tic  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)



GMT3.4.6                          1 Jan 2005                        PSCOAST(l)

Man(1) output converted with man2html