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[/slon]/slat/length[m|n|k][:label:just][+ppen][+ffill]
       ] [ -O ] [ -M[flag] ] [ -Nborder[/pen] ] [ -O ] [ -P ] [ -Q ] [  -Sfill
       ]   [   -T[f|m][x]lon0/lat0/size[/info][:w,e,s,n:][+gint[/mint]]   ]  [
       -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 .gmtdefaults4, but this
              can be overridden on the command line by appending c, i, or m to
              the  scale/width  value.   For map height, max dimension, or min
              dimension, append h, +, or - to the width, respectively.

              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]][d]  (Linear, log, and power
              scaling)
              More details can be found in the psbasemap man pages.

       -R     xmin, xmax, ymin, and ymax specify the Region of  interest.  For
              geographic  regions,  these  limits  correspond  to  west, east,
              south, and north and you may specify them in decimal degrees  or
              in  [+-]dd:mm[:ss.xxx][W|E|S|N]  format.  Append r if lower left
              and upper right map coordinates are given instead of  wesn.  The
              two  shorthands  -Rg  -Rd  stand  for  global  domain  (0/360 or
              -180/+180 in longitude respectively, with -90/+90 in  latitude).
              For  calendar time coordinates you may either give relative time
              (relative  to  the  selected  TIME_EPOCH  and  in  the  selected
              TIME_UNIT;  append  t  to  -JX|x),  or absolute time of the form
              [date]T[clock] (append T to -JX|x). At least  one  of  date  and
              clock must be present; the T is always required. The date string
              must be of the form [-]yyyy[-mm[-dd]]  (Gregorian  calendar)  or
              yyyy[-Www[-d]]  (ISO week calendar), while the clock string must
              be of the form hh:mm:ss[.xxx]. The use of delimiters  and  their
              type  and  positions must be as indicated (however, input/output
              and plotting formats are flexible).


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  annotation  and tickmark intervals; see the
              psbasemap man page for all the 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.  Specify the shade (0-255) or
              color (r/g/b, each in 0-255, h/s/v, with h in 0-360, s, and v in
              0-1, and set COLOR_MODEL = hsv, or c/m/y/k, each  in  0-100  %).
              Alternatively,  specify  -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. The 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  Ref-
              erence 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
              (optionally   supply  longitude  slon  for  oblique  projections
              [Default is central meridian]), 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]. The default label  equals  the
              distance  unit  (km,  miles, nautical miles) and is justified on
              top of the scale [t]. Change this by giving your own label (or -
              to  keep the default) and justification (l(eft), r(ight), t(op),
              b(ottom), and u(unit) - using the label as a  unit  appended  to
              all  distance annotations along the scale). If you want to place
              a rectangle behind the scale, specify pen and/or fill parameters
              with the +p and +f modifiers.

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

       -T     Draws  a  simple map directional rose centered on lon0/lat0. Use
              -Tx to specify x/y position instead.  The size is  the  diameter
              of  the rose, and optional label information can be specified to
              override the default values of W, E, S, and N (Give ::  to  sup-
              press  all  labels).  The  default  [plain] map rose only labels
              north. Use -Tf to get a "fancy" rose, and specify what  kind  of
              rose  you want drawn. The default [1] draws the two principal E-
              W, N-S orientations, 2 adds the two intermediate NW-SE and NE-SW
              orientations, while 3 adds the eight minor orientations WNW-ESE,
              NNW-SSE, NNE-SSW, and ENE-WSW.  For  a  magnetic  compass  rose,
              specify  -Tm. If given, info must be the two parameters dec/dla-
              bel, where dec is the magnetic declination and dlabel is a label
              for  the  magnetic compass needle (specify ’-’ to format a label
              from dec). Then, both  directions  to  geographic  and  magnetic
              north  are  plotted  [Default  is geographic only]. If the north
              label = * then a north star is  plotted  instead  of  the  north
              label.  Annotation  and  two  levels  of tick intervals for geo-
              graphic and magnetic directions are 10/5/1 and  30/5/1  degrees,
              respectively;    override    these    settings    by   appending
              +gints[/mints].   Color  and  pen  attributes  are  taken   from
              COLOR_BACKGROUND  and  TICK_PEN, respectively, while label fonts
              and sizes follow the usual annotation, label,  and  header  font
              settings.

       -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.   Give
              c to center plot using current page size.

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

       -bo    Selects binary output. Append s for single precision [Default is
              double].  Append n for the  number  of  columns  in  the  binary
              file(s).


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, use

       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, run

       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, use

       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 rearrangements in Europe. We intend to update
       these as high-resolution data become available 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)



GMT4.0                            1 Oct 2004                        PSCOAST(l)

Man(1) output converted with man2html