## 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)