## NAME

           grdcontour - contouring of 2-D gridded data sets

## SYNOPSIS

           grdcontour grdfile -Ccont_int -Jparameters [ -A[-|annot_int][labelinfo]
           ]  [  -Btickinfo  ]  [  -Ddumpfile  ]   [   -Eazimuth/elevation   ]   [
           -G[d|f|n|l|L|x|X]info  ] [ -K ] [ -Llow/high ] [ -M[flag] ] [ -O ] [ -P
           ] [ -Qcut  ]  [  -Rwest/east/south/north[r]  ]  [  -Ssmoothfactor  ]  [
           -T[+|-][gap/length][:LH]   ]   [   -U[/dx/dy/][label]   ]  [  -V   ]  [
           -W[+][type]pen ] [ -Xx-shift ] [ -Yy-shift ] [ -Z[factor[/shift]][p]  ]
           [ -ccopies ] [ -bo[s][n] ]

## DESCRIPTION

           grdcontour reads a 2-D gridded file and produces a contour map by trac-
           ing 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  out-
           put. Various options that affect the plotting are available.
                   No  space between the option flag and the associated arguments.
           Use upper case for the option flags and lower case for modifiers.

           grdfile
                  2-D gridded data set to be contoured

           -C     The contours to be drawn may be specified in one of three possi-
                  ble ways:
                  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.
                  If cont_int is a file but not a cpt-file, it is expected to con-
                  tain 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.
                  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.   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.

## OPTIONS

           No space between the option flag and the associated arguments.

           -A     annot_int is annotation interval in data units. Ignored if  con-
                  tour  levels  are given in a file.  [Default is no annotations].
                  Give - 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  follow-
                  ing control arguments:
                  +aangle  for  annotations at a fixed angle, +an for line-normal,
                  or +ap for line-parallel [Default].
                  +cdx[/dy] sets the clearance between  label  and  optional  text
                  box.  Append c|i|m|p to specify the unit or % to indicate a per-
                  centage of the label font size [15%].
                  +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].
                  +jjust sets label justification [Default is CM].
                  +kcolor sets color of text labels [Default is COLOR_BACKGROUND].
                  +llabel sets the constant label text.
                  +Llflag sets the label text according to the specified flag:
                  flag is h: Take the label from the current  multisegment  header
                  (first scan for an embedded -Llabel option, if not use the first
                  word following the segment flag).
                  flag is d: Take the Cartesian plot distances along the  line  as
                  the label; append c|i|m|p as the unit [Default is MEASURE_UNIT].
                  flag is D: Calculate actual map distances; append  d|e|k|m|n  as
                  the unit [Default is d(egrees), unless label placement was based
                  on map distances along the lines in which case we use  the  same
                  unit  specified  for that algorithm].  Requires a map projection
                  to be used.
                  flag is f: Use text after the 2nd  column  in  the  fixed  label
                  location  file  as  the label. Requires the fixed label location
                  setting.
                  flag is x: As h but use the  headers  in  the  xfile.d  instead.
                  Requires the crossing file option.
                  +o  selects  rounded  rectangular text box [Default is rectangu-
                  lar]. 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 out-
                  line]; optionally specify pen for outline [Default  is  width  =
                  0.25p, color = black, texture = solid].
                  +rmin_rad  will not place labels where the line’s radius of cur-
                  vature 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  hypen  (-)  then  there  will be no space between label
                  value and the unit.  [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  hypen  (-) then there will be no space between
                  label value and the prefix. [Default is no prefix].  If no  name
                  is specified, the unit given in the grdfile will be used.

           -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 dump-
                  file_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 (inte-
                  rior) 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  con-
                  junction  with -D a single multisegment file is created instead.

           -E     Sets the viewpoint’s azimuth and elevation for perspective  view
                  [180/90].

           -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 measure-
                  ment 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 mathces 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 con-
                  tours 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 jus-
                  tified  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.

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

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

           -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     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  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).  [Default is region  defined
                  in the grd file].

           -S     Used  to  resample  the  contour  lines  at roughly every (grid-
                  box_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  annota-
                  tion].

           -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     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 =
                  3, color = black, texture = solid. Regular contours have default
                  width = 1. If the + flag is specified then the color of the con-
                  tour lines are taken from the cpt file (see -C).

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

           -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 this scaling has 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-con-
                  tours.

           -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 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   -Jm0.5i   -C25   -A50+f10   -B1g30m    >
           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 -Jx0.1c/50.0c -Ccont.d -S4 -B20/0.1:."RMS Misfit":
           -Wa5/255/0/0 -Wc1/0/0/255ta | 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(l), gmtdefaults(l), psbasemap(l), grdimage(l),  grdview(l),  pscon-
           tour(l)

    GMT4.0                            1 Oct 2004                     GRDCONTOUR(l)