manpagez: man pages & more
man pscoast(1)
Home | html | info | man
pscoast(1)                            GMT                           pscoast(1)




NAME

       pscoast - Plot continents, shorelines, rivers, and borders on maps


SYNOPSIS

       pscoast  -Jparameters
        -Rregion  [   -Aarea  ]  [   -B[p|s]parameters  ]  [  -C[l|r/]fill ] [
       -Dresolution[+] ] [  -Edcw ] [  -Fbox ] [  -Gfill|c ] [   -Iriver[/pen]
       ]  [   -Jz|Zparameters  ]  [   -K  ]  [  -Lscalebar ] [  -M ] [  -Nbor-
       der[/pen] ] [  -O ] [  -P ] [  -Q  ]  [   -Sfill|c  ]  [   -Trose  ]  [
       -Tmag_rose  ]  [   -U[stamp]  ]  [   -V[level]  ]  [  -W[level/]pen ] [
       -Xx_offset ] [  -Yy_offset ] [ -bobinary ] [ -pflags ] [ -ttransp ]

       Note: No space is allowed between the option flag  and  the  associated
       arguments.


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  data files 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. A map projection must be supplied.
       The PostScript code is written to standard output.


REQUIRED ARGUMENTS

       -Jparameters (more a|)
              Select map projection.

       -Rwest/east/south/north[/zmin/zmax][+r][+uunit]
              west, east, south, and north specify the region of interest, and
              you    may    specify    them   in   decimal   degrees   or   in
              [A+-]dd:mm[:ss.xxx][W|E|S|N] format Append +r if lower left  and
              upper  right  map  coordinates are given instead of w/e/s/n. The
              two shorthands -Rg and -Rd stand for global  domain  (0/360  and
              -180/+180  in longitude respectively, with -90/+90 in latitude).
              Alternatively for grid creation, give Rcodelon/lat/nx/ny,  where
              code  is a 2-character combination of L, C, R (for left, center,
              or right) and T, M, B for top, middle, or bottom. e.g.,  BL  for
              lower  left.  This indicates which point on a rectangular region
              the lon/lat coordinate refers to, and the grid dimensions nx and
              ny with grid spacings via -I is used to create the corresponding
              region.  Alternatively, specify the name  of  an  existing  grid
              file  and  the -R settings (and grid spacing, if applicable) are
              copied from the grid. Appending +uunit expects projected (Carte-
              sian)  coordinates  compatible  with  chosen -J and we inversely
              project to determine actual rectangular geographic region.   For
              perspective view (-p), optionally append /zmin/zmax.  In case of
              perspective view (-p), a z-range (zmin, zmax) can be appended to
              indicate  the  third  dimension. This needs to be done only when
              using the -Jz option, not when using only the -p option. In  the
              latter  case a perspective view of the plane is plotted, with no
              third dimension.

       For perspective view p, optionally append /zmin/zmax. (more a|)


OPTIONAL ARGUMENTS

       -Amin_area[/min_level/max_level][+ag|i|s|S][+r|l][+ppercent]
              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)].
              Level  2  (lakes)  contains  regular lakes and wide river bodies
              which we normally include  as  lakes;  append  +r  to  just  get
              river-lakes  or  +l to just get regular lakes.  By default (+ai)
              we select the ice shelf boundary as the  coastline  for  Antarc-
              tica;  append  +ag  to  instead select the ice grounding line as
              coastline.  For expert users who wish to print their own Antarc-
              tica  coastline and islands via psxy you can use +as to skip all
              GSHHG features below 60S or +aS to  instead  skip  all  features
              north  of  60S.   Finally,  append +ppercent to exclude polygons
              whose percentage area of the corresponding full-resolution  fea-
              ture  is less than percent. See GSHHG INFORMATION below for more
              details.

       -B[p|s]parameters (more a|)
              Set map boundary frame and axes attributes.

       -C[l|r/]fill
              Set the shade, color,  or  pattern  for  lakes  and  river-lakes
              [Default  is  the fill chosen for aweta areas (-S)]. Optionally,
              specify separate fills by prepending l/ for  lakes  and  r/  for
              river-lakes, repeating the -C option as needed.

       -Dresolution[+]
              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].  Append + to automatically
              select a lower resolution should the one requested not be avail-
              able  [abort  if  not  found].   Alternatively, choose (a)uto to
              automatically select the best resolution given  the  chosen  map
              scale.

       -Ecode1,code2,^<i>a|[+l|L][+gfill][+ppen][+r|R[incs]]
              Select  painting  or  dumping  country polygons from the Digital
              Chart of the World.  This  is  another  dataset  independent  of
              GSHHG  and hence the -A and -D options do not apply.  Append one
              or more comma-separated  countries  using  the  2-character  ISO
              3166-1  alpha-2  convention.  To select a state of a country (if
              available), append .state, e.g, US.TX for Texas.  To  specify  a
              whole  continent,  prepend  =  to  any of the continent codes AF
              (Africa), AN (Antarctica), AS (Asia), EU (Europe), OC (Oceania),
              NA  (North  America),  or SA (South America).  Append +l to just
              list the countries and their codes [no data extraction or  plot-
              ting  takes  place].   Use  +L  to  see  states/territories  for
              Argentina, Australia, Brazil, Canada, and the  US.   Use  +r  to
              obtain the bounding box coordinates from the polygon(s).  Append
              inc, xinc/yinc, or winc/einc/sinc/ninc to adjust the  region  to
              be  a  multiple of these steps [no adjustment]. Use +R to extend
              the region outward by adding these increments instead [no exten-
              sion].   Append  +ppen to draw polygon outlines [no outline] and
              +gfill to fill them [no fill].  One of +p|g  must  be  specified
              unless +r, +R, or -M is in effect, and only one -E option can be
              given.  You may repeat -E to give different groups of items sep-
              arate  pen/fill  settings.   If  modifiers +r or +R are used and
              neither -J nor -M is set then we just print the -Rwesn string.

       -F[+cclear-
       ances][+gfill][+i[[gap/]pen]][+p[pen]][+r[radius]][+s[[dx/dy/][shade]]]
              Without further options, draws a rectangular border  around  the
              map  scale  or rose using MAP_FRAME_PEN; specify a different pen
              with +ppen.  Add +gfill to fill the logo box [no fill].   Append
              +cclearance   where  clearance  is  either  gap,  xgap/ygap,  or
              lgap/rgap/bgap/tgap where these items are uniform,  separate  in
              x- and y-direction, or individual side spacings between logo and
              border.  Append +i to draw a secondary, inner border as well. We
              use  a uniform gap between borders of 2p and the MAP_DEFAULT_PEN
              unless other values are specified. Append  +r  to  draw  rounded
              rectangular  borders  instead,  with a 6p corner radius. You can
              override this radius by appending another value. Finally, append
              +s to draw an offset background shaded region. Here, dx/dy indi-
              cates the shift relative to the foreground  frame  [4p/-4p]  and
              shade sets the fill style to use for shading [gray50].  Requires
              -L or -T.  If both -L or -T, you may repeat  -F  after  each  of
              these.

       -Gfill|c
              Select  filling  or  clipping  of adrya areas. Append the shade,
              color, or pattern; or use -Gc for clipping [Default is no fill].

       -Iriver[/pen]
              Draw  rivers. Specify the type of rivers and [optionally] append
              pen attributes [Default pen: width =  default,  color  =  black,
              style = solid].

              Choose  from  the list of river types below; repeat option -I as
              often as necessary.

              0 = Double-lined rivers (river-lakes)

              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

              You can also choose from several preconfigured river groups:

              a = All rivers and canals (0-10)

              A = All rivers and canals except river-lakes (1-10)

              r = All permanent rivers (0-4)

              R = All permanent rivers except river-lakes (1-4)

              i = All intermittent rivers (5-7)

              c = All canals (8-10)

       -Jz|Zparameters (more a|)
              Set z-axis scaling; same syntax as -Jx.

       -K (more a|)
              Do not finalize the PostScript plot.

       -L[g|j|J|n|x]ref-
       point+c[slon/]slat+wlength[e|f|k|M|n|u][+aalign][+f][+jjus-
       tify][+l[label]][+odx[/dy]][+u]
              Draws a simple map scale centered on the reference point  speci-
              fied  using  one of four coordinate systems: (1) Use -Lg for map
              (user) coordinates, (2) use -Lj or -LJ for setting refpoint  via
              a  2-char  justification code that refers to the (invisible) map
              domain rectangle, (3) use -Ln for normalized (0-1)  coordinates,
              or  (4)  use -Lx for plot coordinates (inches, cm, etc.).  Scale
              is calculated for latitude  slat  (optionally  supply  longitude
              slon  for  oblique  projections  [Default is central meridian]),
              length is in km, or append unit from  e|f|k|M|n|u.   Change  the
              label  alignment  with  +aalign  (choose  among l(eft), r(ight),
              t(op), and b(ottom)).  Append +f to get a afancya scale [Default
              is  plain].   By  default,  the anchor point on the map scale is
              assumed to be the center of the scale  (MC),  but  this  can  be
              changed  by appending +j followed by a 2-char justification code
              justify (see pstext for list and explanation of codes).   Append
              +l  to  select the default label, which equals the distance unit
              (meter, foot, km, mile, nautical mile, US survey  foot)  and  is
              justified  on  top  of the scale [t]. Change this by giving your
              own label (append +llabel).  Add +o to offset the map  scale  by
              dx/dy away from the refpoint in the direction implied by justify
              (or the direction implied by -Dj or -DJ).  Select +u  to  append
              the  unit  to  all distance annotations along the scale (for the
              plain scale, +u will instead select the unit to be  appended  to
              the  distance  length). Note: Use FONT_LABEL to change the label
              font and FONT_ANNOT_PRIMARY to change the annotation font.   The
              height  of  the map scale is controlled by MAP_SCALE_HEIGHT, and
              the pen thickness is set by MAP_TICK_PEN_PRIMARY.  See -F on how
              to place a panel behind the scale.

       -M     Dumps  a  single multisegment ASCII (or binary, see -bo) file to
              standard output. No plotting occurs. Specify one of -E,  -I,  -N
              or  -W.   Note: if -M is used with -E then -R or the +r modifier
              to -E are not required as we automatically determine the  region
              given the selected geographic entities.

       -Nborder[/pen]
              Draw  political  boundaries.  Specify  the  type of boundary and
              [optionally]  append  pen  attributes  [Default  pen:  width   =
              default, color = black, style = 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 (more a|)
              Append to existing PostScript plot.

       -P (more a|)
              Select aPortraita plot orientation.

       -Q     Mark end of existing clip path.  No  projection  information  is
              needed.   Also supply -X and -Y settings if you have moved since
              the clip started.

       -Sfill|c
              Select filling or clipping of aweta  areas.  Append  the  shade,
              color, or pattern; or use -Sc for clipping [Default is no fill].

       -Td[g|j|J|n|x]refpoint+wwidth[+f[level]][+jjus-
       tify][+lw,e,s,n][+odx[/dy]]
              -Td draws a map directional rose on  the  map  at  the  location
              defined  by  the reference and anchor points: Give the reference
              point on the map for the rose using one of four coordinate  sys-
              tems:  (1)  Use g for map (user) coordinates, (2) use j for set-
              ting refpoint via a 2-char justification code that refers to the
              (invisible) map domain rectangle, (3) use n for normalized (0-1)
              coordinates, or (4) use x  for  plot  coordinates  (inches,  cm,
              etc.) [Default].  You can offset the reference point by dx/dy in
              the direction implied by justify.  By default, the anchor  point
              on  the  scale is assumed to be the center of the rose (MC), but
              this can be changed by appending +j followed by a 2-char  justi-
              fication  code  justify  (see pstext for list and explanation of
              codes).  Note: If -Dj is used then justify defaults to the  same
              as  refpoint, if -DJ is used then justify defaults to the mirror
              opposite of refpoint.  Add +o to offset the color scale by dx/dy
              away  from  the refpoint in the direction implied by justify (or
              the direction implied by -Dj or -DJ).  Append +wwidth to set the
              width  of  the  rose  in  plot  coordinates  (in  inches, cm, or
              points).  Add +f to get a afancya rose,  and  specify  in  level
              what  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.   Label  the  cardinal
              points W,E,S,N by adding +l and append your own four comma-sepa-
              rated strings to override the default.  Skip a specific label by
              leaving  it  blank.   See Placing-dir-map-roses and -F on how to
              place a panel behind the scale.

       -Tm[g|j|J|n|x]refpoint+wwidth[+ddec[/dlabel]]][+ipen][+jjus-
       tify][+lw,e,s,n][+ppen][+tints][+odx[/dy]]
          -Tm  draws a map magnetic rose on the map at the location defined by
          the reference and anchor points: Give the reference point on the map
          for the rose using one of four coordinate systems: (1) Use g for map
          (user) coordinates, (2) use j for setting refpoint via a 2-char jus-
          tification code that refers to the (invisible) map domain rectangle,
          (3) use n for normalized (0-1) coordinates, or (4) use  x  for  plot
          coordinates  (inches, cm, etc.) [Default]. You can offset the refer-
          ence point by  dx/dy  in  the  direction  implied  by  justify.   By
          default,  the  anchor point on the scale is assumed to be the center
          of the rose (MC), but this can be changed by appending  +j  followed
          by  a  2-char  justification  code  justify (see pstext for list and
          explanation of codes).  Note: If -Dj is used then  justify  defaults
          to the same as refpoint, if -DJ is used then justify defaults to the
          mirror opposite of refpoint.  Add +o to offset the  color  scale  by
          dx/dy away from the refpoint in the direction implied by justify (or
          the direction implied by -Dj or -DJ).  Append  +wwidth  to  set  the
          width  of  the  rose in plot coordinates (in inches, cm, or points).
          Use +d to assign the magnetic declination and set dlabel, which is a
          label for the magnetic compass needle (Leave empty to format a label
          from dec, or give - to bypass labeling). With +d, both directions to
          geographic  and  magnetic  north  are plotted [Default is geographic
          only]. If the north label is * then a north star is plotted  instead
          of  the north label. Annotation and two levels of tick intervals for
          both geographic and magnetic directions default to  30/5/1  degrees;
          override   these  settings  by  appending  +tints,  and  append  six
          slash-separated intervals to set both the geographic  (first  three)
          and  magnetic  (last  three)  intervals.   Label the cardinal points
          W,E,S,N by adding  +l  and  append  your  own  four  comma-separated
          strings  to  override the default.  Skip a specific label by leaving
          it blank.  Number GMT default parameters control  pens,  fonts,  and
          color.   See  Placing-dir-map-roses  and  -F on how to place a panel
          behind the scale.

       -U[[just]/dx/dy/][c|label] (more a|)
              Draw GMT time stamp logo on plot.

       -V[level] (more a|)
              Select verbosity level [c].

       -W[level/]pen (more a|)
              Draw  shorelines  [Default  is  no   shorelines].   Append   pen
              attributes  [Defaults:  width  = default, color = black, style =
              solid] which apply to all four levels. To set the pen  for  each
              level differently, prepend level/, where level is 1-4 and repre-
              sent   coastline,   lakeshore,   island-in-lake    shore,    and
              lake-in-island-in-lake  shore.   Repeat  -W as needed. When spe-
              cific level pens are set, those not listed  will  not  be  drawn
              [Default draws all levels; but see -A].

       -X[a|c|f|r][x-shift[u]]

       -Y[a|c|f|r][y-shift[u]] (more a|)
              Shift plot origin.

       -bo[ncols][type] (more a|)
              Select native binary output.

       -p[x|y|z]azim[/elev[/zlevel]][+wlon0/lat0[/z0]][+vx0/y0] (more a|)
              Select perspective view.

       -t[transp] (more a|)
              Set PDF transparency level in percent.

       -^ or just -
              Print  a  short  message  about  the syntax of the command, then
              exits (NOTE: on Windows just use -).

       -+ or just +
              Print an extensive usage (help) message, including the  explana-
              tion  of  any  module-specific  option  (but  not the GMT common
              options), then exits.

       -? or no arguments
              Print a complete usage (help) message, including the explanation
              of all options, then exits.


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

              gmt pscoast -R-30/30/-40/40 -Jm0.1i -B5 -I1/1p,blue -N1/0.25p,- \
                          -I2/0.25p,blue -W0.25p,white -Ggreen -Sblue -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

              gmt pscoast -R-30/-10/60/65 -Jm1c -B5 -Gp28+r100 > 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

              gmt pscoast  -R-30/30/-40/40 -Jm0.1i -B5 -Gc -P -K > africa.ps
              gmt grdimage -Jm0.1i etopo5.nc -Ccolors.cpt -O -K >> africa.ps
              gmt pscoast  -Q -O >> africa.ps

       To plot Great Britain, Italy, and France in blue with a red outline and
       Spain, Portugal and Greece in yellow (no outline), and pick up the plot
       domain form the extents of these countries, use

              gmt pscoast  -JM6i -P -Baf -EGB,IT,FR+gblue+p0.25p,red+r -EES,PT,GR+gyellow > map.ps

       To  extract  a  high-resolution  coastline data table for Iceland to be
       used in your analysis, try

              gmt pscoast -R-26/-12/62/68 -Dh -W -M > iceland.txt

       pscoast  will   first   look   for   coastline   files   in   directory
       $GMT_SHAREDIR/coast  If the desired file is not found, it will look for
       the file $GMT_SHAREDIR/coastline.conf. This file may contain any number
       of  records  that each holds the full pathname of an alternative direc-
       tory. Comment lines (#) and blank lines are allowed.  The desired  file
       is then sought for in the alternate directories.


GSHHS INFORMATION

       The coastline database is GSHHG (formerly GSHHS) which is compiled from
       three sources:  World Vector Shorelines (WVS), CIA World Data  Bank  II
       (WDBII),  and Atlas of the Cryosphere (AC, for Antarctica only).  Apart
       from Antarctica, 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.
       The Antarctica coastlines come in two flavors: ice-front  or  grounding
       line, selectable via the -A option.  Much processing has taken place to
       convert WVS, WDBII, and AC 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  data-
       base using the Douglas-Peucker line-simplification algorithm. The clas-
       sification 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  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 1970s-style but  have  been
       updated  to  reflect  more  recent  border rearrangements in Europe and
       elsewhere. Let us know if you find something out of date.

       The full-resolution coastlines are also from a digitizing effort in the
       1970-80s  and it is difficult to assess the accuracy. Users who zoom in
       close enough may find that the GSHHG coastline is  not  matching  other
       data,  e.g.,  satellite images, more recent coastline data, etc. We are
       aware of such mismatches but cannot undertake band-aid  solutions  each
       time this occurs.

       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 inter-annually. There are some areas of permanent
       shelf ice. In addition  to  these  time-varying  ice-ocean  boundaries,
       there  are  also shelf ice grounding lines where ice goes from floating
       on the sea to sitting on land, and lines delimiting areas of rock  out-
       crop.  For  consistencyas sake, we have used the World Vector Shoreline
       throughout the world in pscoast, as described in the GMT  Cookbook  Ap-
       pendix  K.  Users who need specific boundaries in Antarctica should get
       the Antarctic Digital Database, prepared by the British Antarctic  Sur-
       vey, Scott Polar Research Institute, World Conservation Monitoring Cen-
       tre, 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  Scien-
       tific  Committee on Antarctic Research, Scott Polar Research Institute,
       Lensfield Road, Cambridge CB2 1ER, United Kingdom.


SEE ALSO

       gmt(1), gmt.conf(5), gmtcolors(5), grdlandmask(1), psbasemap(1)


COPYRIGHT

       2017, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe



5.4.2                            Jun 24, 2017                       pscoast(1)

gmt5 5.4.2 - Generated Thu Jun 29 15:04:08 CDT 2017
© manpagez.com 2000-2021
Individual documents may contain additional copyright information.