## 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] ] [ -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., earlier 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 cm/degree, 1:xxxxx, or width
               in cm (upper case modifier).

               CYLINDRICAL PROJECTIONS:

               -Jclon0/lat0/scale (Cassini)
               -Jjlon0/scale (Miller)
               -Jmscale (Mercator - Greenwich and Equator as origin)
               -Jmlon0/lat0/scale (Mercator - Give meridian and standard
               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 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/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 (Linear projection for polar (theta,r) coordinates)
               -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 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), 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 position in cm 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
               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 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 in cm [Default is (-2c/-2c)].
               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) cm  [Default is
               (a2.5c,a2.5c) for new plots, (0,0) for overlays].  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 background, with
          permanent 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.25 cm/degree, try

          pscoast -R-30/30/-40/40 -Jm0.25c -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), unit size 1.25 cm, on a
          Mercator map at scale 1 cm/degree, try

          pscoast -R-30/-10/60/65 -Jm1c -B5 -Gp0.5/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.25 cm/degree, try

          pscoast -R-30/30/-40/40 -Jm0.25c -B5 -Gc -P -K > africa.ps
          grdimage -Jm0.25c 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 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.

## 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,
          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 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
          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, gmt, grdlandmask, psbasemap