DragonFly On-Line Manual Pages
PSCONTOUR(1) Generic Mapping Tools PSCONTOUR(1)
NAME
pscontour - Contour xyz-data by direct triangulation [method]
SYNOPSIS
pscontour xyzfile -Ccptfile -Jparameters -Rwest/east/south/north[r] [
-A[-][labelinfo] ] [ -B[p|s]parameters ] [ -D[dumpfile] ] [
-Eazim/elev[+wlon/lat[/z]][+vx0/y0] ] [ -G[d|f|n|l|L|x|X]params ] [
-H[i][nrec] ] [ -I ] [ -K ] [ -Lpen ] [ -N ] [ -O ] [ -P ] [ -S[p|t] ]
[ -Tindexfile ] [ -U[just/dx/dy/][c|label] ] [ -V ] [ -W[*]pen ] [
-X[a|c|r][x-shift[u]] ] [ -Y[a|c|r][y-shift[u]] ] [ -ccopies ] [
-:[i|o] ] [ -b[i|o][s|S|d|D[ncol]|c[var1/...]] ] [ -m[flag] ]
DESCRIPTION
pscontour reads an ASCII [or binary] xyz-file and produces a raw
contour plot by triangulation. By default, the optimal Delaunay
triangulation is performed (using either Shewchuk's [1996] or Watson's
[1982] method as selected during GMT installation; type pscontour - to
see which method is selected), but the user may optionally provide a
second file with network information, such as a triangular mesh used
for finite element modeling. In addition to contours, the area between
contours may be painted according to the color palette file.
xyzfile
Raw ASCII (or binary, see -b) xyz data to be contoured.
-C name of the color palette file. Must have discrete colors if
you want to paint the surface (-I). Only contours that have
annotation flags set will be annotated.
-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)
-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).
OPTIONS
No space between the option flag and the associated arguments.
-A Give - to disable all annotations. 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].
+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).
+llabel
Sets the constant label text.
+Lflag Sets the label text according to the specified flag:
+Lh 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). For multiple-word labels, enclose entire
label in double quotes.
+Ld Take the Cartesian plot distances along the line
as the label; append c|i|m|p as the unit [Default
is MEASURE_UNIT].
+LD 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.
+Lf Use text after the 2nd column in the fixed label
location file as the label. Requires the fixed
label location setting.
+Lx As +Lh but use the headers in the xfile.d instead.
Requires the crossing file option.
+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. [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, where cont is the contour value
and segment is a running segment number for each contour
interval (for closed contours we append _i.) 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).
-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 the coordinates of the end points 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_lon/start_lat/stop_lon/stop_lat. Both
start_lon/start_lat and stop_lon/stop_lat can be replaced
by a 2-character key that uses the justification format
employed in pstext to indicate a point on the map, given
as [LCR][BMT]. -GL will interpret the point pairs as
defining great circles [Default is straight line].
-Gn|Nn_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].
-H Input file(s) has header record(s). If used, the default number
of header records is N_HEADER_RECS. Use -Hi if only input data
should have header records [Default will write out header
records if the input data have them]. Blank lines and lines
starting with # are always skipped.
-I Color the triangles using the color palette table.
-Jz Sets the vertical scaling (for 3-D maps). Same syntax as -Jx.
-K More PostScript code will be appended later [Default terminates
the plot system].
-L Draw the underlying triangular mesh using the specified pen
attributes [Default is no mesh]. (See SPECIFYING PENS below).
-N Do NOT clip contours or image at the boundaries [Default will
clip to fit inside region -R].
-O Selects Overlay plot mode [Default initializes a new plot
system].
-P Selects Portrait plotting mode [Default is Landscape, see
gmtdefaults to change this].
-S Or -Sp: Skip all input xyz points that fall outside the region
[Default uses all the data in the triangulation].
Alternatively, use -St to skip triangles whose three vertices
are all outside the region.
-T Give name of file with network information. Each record must
contain triplets of node numbers for a triangle [Default
computes these using Delaunay triangulation (see triangulate)].
-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 Select contouring and set contour pen attributes. If the * flag
is set then the contour lines are colored according to the cpt
file (see -C). (See SPECIFYING PENS below).
-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.
-: Toggles between (longitude,latitude) and (latitude,longitude)
input and/or output. [Default is (longitude,latitude)]. Append
i to select input only or o to select output only. [Default
affects both].
-bi Selects binary input. Append s for single precision [Default is
d (double)]. Uppercase S or D will force byte-swapping.
Optionally, append ncol, the number of columns in your binary
input file if it exceeds the columns needed by the program. Or
append c if the input file is netCDF. Optionally, append
var1/var2/... to specify the variables to be read. [Default is
3 input columns]. Use 4-byte integer triplets for node ids
(-T).
-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. [Default is 3 output columns].
-c Specifies the number of plot copies. [Default is 1].
-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.
EXAMPLES
To make a raw contour plot from the file topo.xyz and drawing the
contours (pen = 0.5p) given in the color palette file topo.cpt on a
Lambert map at 0.5 inch/degree along the standard parallels 18 and 24,
use
pscontour topo.xyz -R 320/330/20/30 -Jl 18/24/0.5i -C topo.cpt -W 0.5p
> topo.ps
To create a color PostScript plot of the numerical temperature solution
obtained on a triangular mesh whose node coordinates and temperatures
are stored in temp.xyz and mesh arrangement is given by the file
mesh.ijk, using the colors in temp.cpt, run
pscontour temp.xyz -R 0/150/0/100 -Jx 0.1 -C temp.cpt -G -W 0.25p >
temp.ps
BUGS
Sometimes there will appear to be thin lines of the wrong color in the
image. This is a round-off problem which may be remedied by using a
higher value of DOTS_PR_INCH in the .gmtdefaults4 file.
SEE ALSO
GMT(1), gmtcolors(5), grdcontour(1), grdimage(1), nearneighbor(1),
psbasemap(1), psscale(1), surface(1), triangulate(1)
REFERENCES
Watson, D. F., 1982, Acord: Automatic contouring of raw data, Comp. &
Geosci., 8, 97-101.
Shewchuk, J. R., 1996, Triangle: Engineering a 2D Quality Mesh
Generator and Delaunay Triangulator, First Workshop on Applied
Computational Geometry (Philadelphia, PA), 124-133, ACM, May 1996.
www.cs.cmu.edu/~quake/triangle.html
GMT 4.5.14 1 Nov 2015 PSCONTOUR(1)