Provided by: gmt_4.5.11-1build1_amd64 bug

NAME

       grdcontour - Contouring of 2-D gridded data sets

SYNOPSIS

       grdcontour    grdfile   -Ccont_int   -Jparameters   [   -A[-|annot_int][labelinfo]   ]   [
       -B[p|s]parameters  ]  [  -Ddumpfile  ]   [   -Eazimuth/elevation   ]   [   -F[l|r]   ]   [
       -G[d|f|n|l|L|x|X]params  ]  [  -K  ]  [  -Llow/high  ]  [  -O  ]  [  -P  ]  [  -Qcut  ]  [
       -Rwest/east/south/north[r]  ]  [  -Ssmoothfactor  ]   [   -T[+|-][gap/length][:LH]   ]   [
       -U[just/dx/dy/][c|label]  ]  [  -V  ]  [  -W[+][type]pen  ]  [  -X[a|c|r][x-shift[u]]  ] [
       -Y[a|c|r][y-shift[u]]    ]    [    -Z[factor[/shift]][p]    ]    [    -ccopies     ]     [
       -bo[s|S|d|D[ncol]|c[var1/...]] ] [ -m[flag] ]

DESCRIPTION

       grdcontour  reads  a  2-D  grid  file  and  produces a contour map by tracing each contour
       through the grid.  As an option, the x/y/z positions of the contour lines may be dumped to
       a  single multisegment file or many separate files.  PostScript code is generated and sent
       to standard output.  Various options that affect the plotting are available.

       grdfile
              2-D gridded data set to be contoured.  (See GRID FILE FORMATS below).

       -C     The contours to be drawn may be specified in one of three possible ways:
              (1) If cont_int has the suffix ".cpt" and can be opened as a file, it is assumed to
              be  a  color  palette table.  The color boundaries are then used as contour levels.
              If the cpt-file has annotation flags in the last column then those contours will be
              annotated.    By  default  all  contours  are  labeled;  use  -A-  to  disable  all
              annotations.
              (2) If cont_int is a file but not a cpt-file, it is  expected  to  contain  contour
              levels  in column 1 and a C(ontour) OR A(nnotate) in col 2. The levels marked C (or
              c) are contoured,  the  levels  marked  A  (or  a)  are  contoured  and  annotated.
              Optionally,  a  third  column may be present and contain the fixed annotation angle
              for this contour level.
              (3) If no file is found,  then  cont_int  is  interpreted  as  a  constant  contour
              interval.   If  -A  is set and -C is not, then the contour interval is set equal to
              the specified annotation interval.
              If a file is given and -T is set, then only contours marked with upper case C or  A
              will  have  tickmarks.   In all cases the contour values have the same units as the
              grid.

       -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.  When central meridian is optional, default is center
              of longitude range on -R option.  Default standard parallel is  the  equator.   For
              map  height,  max  dimension,  or  min  dimension,  append h, +, or - to the width,
              respectively.
              More details can be found in the psbasemap man pages.

              CYLINDRICAL PROJECTIONS:

              -Jclon0/lat0/scale (Cassini)
              -Jcyl_stere/[lon0/[lat0/]]scale (Cylindrical Stereographic)
              -Jj[lon0/]scale (Miller)
              -Jm[lon0/[lat0/]]scale (Mercator)
              -Jmlon0/lat0/scale (Mercator - Give meridian and standard parallel)
              -Jo[a]lon0/lat0/azimuth/scale (Oblique Mercator - point and azimuth)
              -Jo[b]lon0/lat0/lon1/lat1/scale (Oblique Mercator - two points)
              -Joclon0/lat0/lonp/latp/scale (Oblique Mercator - point and pole)
              -Jq[lon0/[lat0/]]scale (Cylindrical Equidistant)
              -Jtlon0/[lat0/]scale (TM - Transverse Mercator)
              -Juzone/scale (UTM - Universal Transverse Mercator)
              -Jy[lon0/[lat0/]]scale (Cylindrical Equal-Area)

              CONIC PROJECTIONS:

              -Jblon0/lat0/lat1/lat2/scale (Albers)
              -Jdlon0/lat0/lat1/lat2/scale (Conic Equidistant)
              -Jllon0/lat0/lat1/lat2/scale (Lambert Conic Conformal)
              -Jpoly/[lon0/[lat0/]]scale ((American) Polyconic)

              AZIMUTHAL PROJECTIONS:

              -Jalon0/lat0[/horizon]/scale (Lambert Azimuthal Equal-Area)
              -Jelon0/lat0[/horizon]/scale (Azimuthal Equidistant)
              -Jflon0/lat0[/horizon]/scale (Gnomonic)
              -Jglon0/lat0[/horizon]/scale (Orthographic)
              -Jglon0/lat0/altitude/azimuth/tilt/twist/Width/Height/scale (General Perspective).
              -Jslon0/lat0[/horizon]/scale (General Stereographic)

              MISCELLANEOUS PROJECTIONS:

              -Jh[lon0/]scale (Hammer)
              -Ji[lon0/]scale (Sinusoidal)
              -Jkf[lon0/]scale (Eckert IV)
              -Jk[s][lon0/]scale (Eckert VI)
              -Jn[lon0/]scale (Robinson)
              -Jr[lon0/]scale (Winkel Tripel)
              -Jv[lon0/]scale (Van der Grinten)
              -Jw[lon0/]scale (Mollweide)

              NON-GEOGRAPHICAL PROJECTIONS:

              -Jp[a]scale[/origin][r|z] (Polar coordinates (theta,r))
              -Jxx-scale[d|l|ppow|t|T][/y-scale[d|l|ppow|t|T]] (Linear, log, and power scaling)

OPTIONS

       No space between the option flag and the associated arguments.

       -A     annot_int is annotation interval in data units; it is ignored if contour levels are
              given  in  a  file.   [Default  is  no  annotations].    Append  -  to  disable all
              annotations implied by -C.  The optional labelinfo controls the  specifics  of  the
              label  formatting  and  consists  of  a  concatenated  string made up of any of the
              following control arguments:

              +aangle
                     For annotations at a fixed angle, +an for  line-normal,  or  +ap  for  line-
                     parallel  [Default].   By  appending the u or d we get annotations whose top
                     face the next upper or lower annotation, respectively.

              +cdx[/dy]
                     Sets the clearance between label and optional text box.  Append  c|i|m|p  to
                     specify the unit or % to indicate a percentage of the label font size [15%].

              +d     Turns  on  debug  which  will draw helper points and lines to illustrate the
                     workings of the quoted line setup.

              +ffont Sets the desired font [Default ANNOT_FONT_PRIMARY].

              +g[color]
                     Selects opaque text boxes [Default is transparent]; optionally  specify  the
                     color [Default is PAGE_COLOR].  (See SPECIFYING COLOR below).

              +jjust Sets label justification [Default is MC].  Ignored when -SqN|n+|-1 is used.

              +kcolor
                     Sets  color  of  text labels [Default is COLOR_BACKGROUND].  (See SPECIFYING
                     COLOR below).

              +ndx[/dy]
                     Nudges the placement of labels by the specified amount  (append  c|i|m|p  to
                     specify  the  units).   Increments  are  considered in the coordinate system
                     defined by the orientation of the line; use +N to force  increments  in  the
                     plot x/y coordinates system [no nudging].

              +o     Selects   rounded  rectangular  text  box  [Default  is  rectangular].   Not
                     applicable for curved text (+v) and only makes sense for opaque text boxes.

              +p[pen]
                     Draws the outline of  text  boxsets  [Default  is  no  outline];  optionally
                     specify  pen for outline [Default is width = 0.25p, color = black, texture =
                     solid].  (See SPECIFYING PENS below).

              +rmin_rad
                     Will not place labels where the line's radius  of  curvature  is  less  than
                     min_rad [Default is 0].

              +ssize Sets the desired font size in points [Default is 9].

              +uunit Appends  unit  to  all line labels. If unit starts with a leading hyphen (-)
                     then there will be no space between label value  and  the  unit.   If  z  is
                     appended we use the unit specified in the grid file.  [Default is no unit].

              +v     Specifies curved labels following the path [Default is straight labels].

              +w     Specifies  how  many  (x,  y)  points  will be used to estimate label angles
                     [Default is 10].

              +=prefix
                     Prepends prefix to all line labels.  If prefix starts with a leading  hyphen
                     (-) then there will be no space between label value and the prefix. [Default
                     is no prefix].

       -B     Sets map boundary annotation and tickmark intervals; see the psbasemap man page for
              all the details.

       -D     Dump  the  (x,y,z)  coordinates  of  each  contour  to separate files, one for each
              contour segment. The files will be named dumpfile_cont_segment[_i].xyz (or .b is -b
              is  selected),  where  cont  is  the contour value and segment is a running segment
              number for each contour interval (for closed contours we append _i.)  If the prefix
              is  given as '-' the file names are instead C#_i (interior) or C#_e (external) plus
              extension, and # is just a running number.  This allows us to make short file names
              that  will  work  with  GNU  utilities  under  DOS.   However,  when  -m is used in
              conjunction with -D a single multisegment file is created instead.

       -E     Sets the viewpoint's azimuth and elevation (for perspective  view)  [180/90].   For
              frames  used for animation, you may want to append + to fix the center of your data
              domain (or specify a particular world coordinate point with  +wlon0/lat[/z])  which
              will  project  to  the  center of your page size (or specify the coordinates of the
              projected view point with +vx0/y0).

       -F     Force dumped contours to be oriented so that higher z-values are to the  left  (-Fl
              [Default])  or  right  (-Fr)  as  we  move  along the contour [Default is arbitrary
              orientation].  Requires -D.

       -G     Controls the placement of labels along the contours.  Choose among five controlling
              algorithms:

              -Gddist[c|i|m|p] or -GDdist[d|e|k|m|n]
                     For  lower  case  d,  give  distances  between  labels  on  the plot in your
                     preferred measurement unit c (cm), i (inch), m (meter), or p (points), while
                     for upper case D, specify distances in map units and append the unit; choose
                     among e (m), k (km), m (mile), n (nautical mile), or d  (spherical  degree).
                     [Default is 10c or 4i].

              -Gfffile.d
                     Reads the ascii file ffile.d and places labels at locations in the file that
                     matches locations along the contours.  Inexact matches  and  points  outside
                     the region are skipped.

              -Gl|Lline1[,line2,...]
                     Give  start  and  stop  coordinates for one or more comma-separated straight
                     line segments.  Labels will  be  placed  where  these  lines  intersect  the
                     contours.   The format of each line specification is start/stop, where start
                     and stop are either a specified point lon/lat or a 2-character XY  key  that
                     uses  the justification format employed in pstext to indicate a point on the
                     map, given as [LCR][BMT].   In  addition,  you  may  use  Z+  and  Z-  which
                     correspond to the locations of the global max and min locations in the grid,
                     respectively.  -GL will interpret the point pairs as defining great  circles
                     [Default is straight line].

              -Gnn_label
                     Specifies  the  number  of  equidistant labels for contours line [1].  Upper
                     case -GN starts labeling exactly at the start of the line  [Default  centers
                     them  along  the  line].   -GN-1  places one justified label at start, while
                     -GN+1 places one justified label at the end of contours.  Optionally, append
                     /min_dist[c|i|m|p]  to  enforce  that  a minimum distance separation between
                     successive labels is enforced.

              -Gx|Xxfile.d
                     Reads the multi-segment file xfile.d and places labels at the  intersections
                     between  the  contours and the lines inxfile.d.  -GX will resample the lines
                     first along great-circle arcs.

              In addition, you may optionally append +rradius[c|i|m|p] to  set  a  minimum  label
              separation in the x-y plane [no limitation].

       -K     More PostScript code will be appended later [Default terminates the plot system].

       -L     Limit range: Do not draw contours for data values below low or above high.

       -O     Selects Overlay plot mode [Default initializes a new plot system].

       -P     Selects  Portrait  plotting  mode  [Default is Landscape, see gmtdefaults to change
              this].

       -Q     Do not draw contours with less than cut number of points [Draw all contours].

       -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 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, specify the name of an existing grid
              file and the -R settings (and grid spacing, if  applicable)  are  copied  from  the
              grid.   For  calendar  time  coordinates  you  may  either  give  (a) relative time
              (relative to the selected TIME_EPOCH and in the selected  TIME_UNIT;  append  t  to
              -JX|x),  or  (b)  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 exactly as indicated
              (however, input, output  and  plot  formats  are  customizable;  see  gmtdefaults).
              [Default is region defined in the grid file].

       -S     Used  to  resample  the  contour lines at roughly every (gridbox_size/smoothfactor)
              interval.

       -T     Will draw tickmarks  pointing  in  the  downward  direction  every  gap  along  the
              innermost  closed  contours.   Append  gap  and  tickmark  length  or  use defaults
              [0.5c/0.1c or 0.2i/0.04i].  User may choose to tick only local highs or local  lows
              by  specifying  -T+ or -T-, respectively.  Appending :LH will plot the characters L
              and H at the center of closed innermost contours (local lows and highs).  L  and  H
              can  be  any single character (e.g., LH, -+, etc.)  If a file is given by -C and -T
              is set, then only contours marked with upper case C or A will have  tickmarks  [and
              annotation].

       -U     Draw  Unix  System time stamp on plot.  By adding just/dx/dy/, the user may specify
              the justification of the stamp and where the stamp should fall on the page relative
              to  lower  left  corner of the plot.  For example, BL/0/0 will align the lower left
              corner of the time stamp with the lower  left  corner  of  the  plot.   Optionally,
              append  a  label,  or  c (which will plot the command string.).  The GMT parameters
              UNIX_TIME, UNIX_TIME_POS, and UNIX_TIME_FORMAT can affect the appearance;  see  the
              gmtdefaults man page for details.  The time string will be in the locale set by the
              environment variable TZ (generally local time).

       -V     Selects verbose mode, which will send progress  reports  to  stderr  [Default  runs
              "silently"].

       -W     type,  if  present,  can  be  a  for  annotated  contours or c for regular contours
              [Default].  pen sets the attributes for the particular line.   Default  values  for
              annotated  contours:  width  =  0.75p,  color  =  black,  texture = solid.  Regular
              contours have default width = 0.25p.  (See SPECIFYING PENS below).  If the  +  flag
              is  specified  then the color of the contour lines are taken from the cpt file (see
              -C).

       -X -Y  Shift  plot  origin  relative  to  the  current  origin  by  (x-shift,y-shift)  and
              optionally  append  the  length  unit (c, i, m, p).  You can prepend a to shift the
              origin back to the original position after plotting, or  prepend   r  [Default]  to
              reset  the  current origin to the new location.  If -O is used then the default (x-
              shift,y-shift)  is  (0,0),  otherwise  it  is  (r1i,  r1i)   or   (r2.5c,   r2.5c).
              Alternatively,  give c to align the center coordinate (x or y) of the plot with the
              center of the page based on current page size.

       -Z     Use to subtract shift from the data and  multiply  the  results  by  factor  before
              contouring  starts [1/0].  (Numbers in -A, -C, -L refer to values after scaling and
              translation have occurred.)  Append p to indicate that this grid file  contains  z-
              values  that  are periodic in 360 degrees (e.g., phase data, angular distributions)
              and that special precautions must be taken when determining 0-contours.

       -bo    Selects binary output.  Append s for single  precision  [Default  is  d  (double)].
              Uppercase  S or D will force byte-swapping.  Optionally, append ncol, the number of
              desired columns in your binary output file.

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

       -f     Special formatting of input and/or output  columns  (time  or  geographical  data).
              Specify  i  or  o  to  make  this apply only to input or output [Default applies to
              both].  Give one or more columns (or column ranges) separated by commas.  Append  T
              (absolute calendar time), t (relative time in chosen TIME_UNIT since TIME_EPOCH), x
              (longitude), y (latitude), or f (floating point) to each  column  or  column  range
              item.  Shorthand -f[i|o]g means -f[i|o]0x,1y (geographic coordinates).

       -m     When  used  in  conjunction with -D a single multisegment file is created, and each
              contour section is preceded by a header record whose first column is flag  followed
              by the contour level.

   SPECIFYING PENS
       pen    The  attributes  of  lines  and  symbol  outlines  as  defined  by  pen  is a comma
              delimetered list of width, color and texture, each of which is optional.  width can
              be   indicated   as   a   measure   (points,  centimeters,  inches)  or  as  faint,
              thin[ner|nest], thick[er|est], fat[ter|test], or obese.   color  specifies  a  gray
              shade  or  color  (see SPECIFYING COLOR below).  texture is a combination of dashes
              `-' and dots `.'.

   SPECIFYING COLOR
       color  The color of lines, areas and patterns can be specified by a valid color name; by a
              gray  shade  (in  the  range  0-255); by a decimal color code (r/g/b, each in range
              0-255; h-s-v, ranges 0-360, 0-1, 0-1; or c/m/y/k, each  in  range  0-1);  or  by  a
              hexadecimal  color  code (#rrggbb, as used in HTML).  See the gmtcolors manpage for
              more information and a full list of color names.

ASCII FORMAT PRECISION

       The ASCII  output  formats  of  numerical  data  are  controlled  by  parameters  in  your
       .gmtdefaults4    file.     Longitude    and    latitude   are   formatted   according   to
       OUTPUT_DEGREE_FORMAT, whereas other values are formatted according to D_FORMAT.  Be  aware
       that  the  format in effect can lead to loss of precision in the output, which can lead to
       various problems downstream.  If you find the output is not written with enough precision,
       consider  switching to binary output (-bo if available) or specify more decimals using the
       D_FORMAT setting.

FILE FORMATS

       GMT is able to recognize many of the commonly used grid  file  formats,  as  well  as  the
       precision,  scale  and  offset  of the values contained in the grid file. When GMT needs a
       little help with that, you can add the suffix =id[/scale/offset[/nan]], where id is a two-
       letter  identifier of the grid type and precision, and scale and offset are optional scale
       factor and offset to be applied to all grid values, and nan is the value used to  indicate
       missing  data.   See  grdreformat(1)  and  Section 4.17 of the GMT Technical Reference and
       Cookbook for more information.

       When reading a netCDF file that contains multiple grids, GMT will read,  by  default,  the
       first  2-dimensional  grid  that  can  find in that file. To coax GMT into reading another
       multi-dimensional variable in the grid file, append  ?varname  to  the  file  name,  where
       varname  is the name of the variable. Note that you may need to escape the special meaning
       of ? in your shell program by putting a backslash in  front  of  it,  or  by  placing  the
       filename  and suffix between quotes or double quotes.  See grdreformat(1) and Section 4.18
       of the GMT Technical Reference and Cookbook for more information, particularly on  how  to
       read splices of 3-, 4-, or 5-dimensional grids.

EXAMPLES

       To  contour  the  file hawaii_grav.grd every 25 mGal on a Mercator map at 0.5 inch/degree,
       annotate every 50 mGal (using fontsize = 10), using 1 degree tickmarks, and draw 30 minute
       gridlines:

       grdcontour hawaii_grav.grd -Jm 0.5i -C 25 -A 50+s10 -B 1g30m > hawaii_grav.ps

       To  contour  the file image.grd using the levels in the file cont.d on a linear projection
       at 0.1 cm/x-unit and 50 cm/y-unit, using 20 (x) and 0.1 (y) tickmarks, smooth the contours
       a  bit,  use "RMS Misfit" as plot-title, use a thick red pen for annotated contours, and a
       thin, dashed, blue pen for the rest, and send the output to the default printer:

       grdcontour image.grd -Jx 0.1c/50.0c -C cont.d -S 4 -B 20/0.1:."RMS Misfit": -Wa  thick,red
       -Wc thinnest,blue,- | lp

       The labeling of local highs and lows may plot outside the innermost contour since only the
       mean value of the contour coordinates is used to position the label.

SEE ALSO

       GMT(1), gmtdefaults(1), gmtcolors(5), psbasemap(1), grdimage(1), grdview(1), pscontour(1)