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)

Man(1) output converted with man2html