# PSCONTOUR

NAME
SYNOPSIS
DESCRIPTION
OPTIONS
EXAMPLES
BUGS
SEE ALSO
REFERENCES

## NAME

pscontour − Contour xyz-data by direct triangulation [method]

## SYNOPSIS

pscontour xyzfile −C cptfile −J parameters −R west/east/south/north[r] [ −A[-][labelinfo] ] [ −B[p|s]parameters ] [ −D[dumpfile] ] [ −E azim/elev[+w lon/lat[/z]][+v x0/y0] ] [ −G[d|f|n|l|L|x|X]params ] [ −H[i][nrec] ] [ −I ] [ −K ] [ −L pen ] [ −N ] [ −O ] [ −P ] [ −S ] [ −T indexfile ] [ −U[just/dx/dy/][c|label] ] [ −V ] [ −W[+]pen ] [ −X[a|c|r][x-shift[u]] ] [ −Y[a|c|r][y-shift[u]] ] [ −c copies ] [ −:[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:

−Jc lon0/lat0/scale (Cassini)
−Jcyl_stere/[lon0/[lat0/]]scale (Cylindrical Stereographic)
−Jj[lon0/]scale (Miller)
−Jm[lon0/[lat0/]]scale (Mercator)
−Jm lon0/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)
−Joc lon0/lat0/lonp/latp/scale (Oblique Mercator - point and pole)
−Jq[lon0/[lat0/]]scale (Cylindrical Equidistant)
−Jt lon0/[lat0/]scale (TM - Transverse Mercator)
−Ju zone/scale (UTM - Universal Transverse Mercator)
−Jy[lon0/[lat0/]]scale (Cylindrical Equal-Area)

CONIC PROJECTIONS:

−Jb lon0/lat0/lat1/lat2/scale (Albers)
−Jd lon0/lat0/lat1/lat2/scale (Conic Equidistant)
−Jl lon0/lat0/lat1/lat2/scale (Lambert Conic Conformal)
−Jpoly/[lon0/[lat0/]]scale ((American) Polyconic)

AZIMUTHAL PROJECTIONS:

−Ja lon0/lat0[/horizon]/scale (Lambert Azimuthal Equal-Area)
−Je lon0/lat0[/horizon]/scale (Azimuthal Equidistant)
−Jf lon0/lat0[/horizon]/scale (Gnomonic)
−Jg lon0/lat0[/horizon]/scale (Orthographic)
−Jg lon0/lat0/altitude/azimuth/tilt/twist/Width/Height/scale (General Perspective).
−Js lon0/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))
−Jx x-scale[d|l|p pow|t|T][/y-scale[d|l|p pow|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:

+a angle

For annotations at a fixed angle, +an for line-normal, or +ap for line-parallel [Default].

+c dx[/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.
| +f font |  | 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).

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

+k color

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

+l label

Sets the constant label text.

| +L flag |  | Sets the label text according to the specified flag:

| +Lh |  | Take the label from the current multisegment header (first scan for an embedded −L label 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.

+n dx[/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).

+r min_rad

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

| +s size |  | Sets the desired font size in points [Default is 9].
| +u unit |  | 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 +w lon0/lat[/z]) which will project to the center of your page size (or specify the coordinates of the projected view point with +v x0/y0).
| −G |  | Controls the placement of labels along the contours. Choose among five controlling algorithms:

−Gd dist[c|i|m|p] or −GD dist[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].

−Gf ffile.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|L line1[,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]. −GL will interpret the point pairs as defining great circles [Default is straight line].

−Gn n_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|X xfile.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 +r radius[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 |  | Skip all input xyz points that fall outside the region [Default uses all the data in the triangulation].
| −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 −R320/330/20/30 −Jl18/24/0.5i −Ctopo.cpt −W0.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 −R0/150/0/100 −Jx0.1 −Ctemp.cpt −G −W0.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