O.2 Label Attributes

Determining where to place labels is half the battle. The other half is to specify exactly what are the attributes of the labels. It turns out that there are quite a few possible attributes that we may want to control, hence understanding how to specify these attributes becomes important. In the contouring programs, one or more attributes may be appended to the -A option using the format +code[args] for each attribute, whereas for the line plotting programs these attributes are appended to the -Sq option following a colon (:) that separates the label codes from the placement algorithm. Several of the attributes do not apply to contours so we start off with listing those that apply universially. These codes are:

+a:

Controls the angle of the label relative to the angle of the line. Append n for normal to the line, give a fixed angle measured counter-clockwise relative to the horizontal. or append p for parallel to the line [Default]. If using grdcontour the latter option you may further append u or d to get annotations whose upper edge always face the next higher or lower contour line.

+c:

Surrounding each label is an imaginary label ``textbox'' which defines a region in which no segment lines should be visible. The initial box provides an exact fit to the enclosed text but clearance may be extended in both the horizontal and vertical directions (relative to the label baseline) by the given amounts. If these should be different amounts please separate them by a slash; otherwise the single value applies to both directions. Append the distance units of your choice (c$\vert$i$\vert$m$\vert$p), or give % to indicate that the clearance should be this fixed percentage of the label font size in use. The default is 15%.

+d:

Debug mode. This is useful when testing contour placement as it will draw the normally invisible helper lines and points in the label placement algorithms above.

+f:

Specifies the desired label font. See pstext for font names or numbers. The default font is given by ANNOT_FONT_PRIMARY.

+g:

Selects opaque rather than the default transparent textboxes. You may optionally append the color you want to fill the label boxes; the default is the same as PAGE_COLOR.

+j:

Selects the justification of the label relative to the placement points determined above. Normally this is center/mid justified (CM in pstext justification parlance) and this is indeed the default setting. Override by using this option and append another justification key code from [L$\vert$C$\vert$R][B$\vert$M$\vert$T]. Note for curved text (+v) only vertical justification will be affected.

+k:

Sets the color of the text labels, which otherwise defaults to that given by COLOR_BACKGROUND.

+o:

Request a rounded, rectangular label box shape; the default is rectangular. This is only manifested if the box is filled or outlined, neither of which is implied by this option alone (see +g and +p). As this option only applies to straight text, it is ignored if +v is given.

+p:

Selects the drawing of the label box outline; append your preferred pen unless you want the default GMT pen [0.25p,black].

+r:

Do not place labels at points along the line whose local radius of curvature falls below the given threshold value. Append the radius unit of your choice (c$\vert$i$\vert$m$\vert$p) [Default is 0].

+s:

Change the font size of the labels, which by default is 9 points.

+u:

Append the chosen unit to the label. Normally a space will separate the label and the unit. If you want to close this gap, append a unit that begins with a hyphen (-). If you are contouring with grdcontour and you specify this option without appending a unit, the unit will be taken from the $z$-unit attribute of the grid header.

+v:

Place curved labels that follow the wiggles of the line segments. This is especially useful if the labels are long relative to the length-scale of the wiggles. The default places labels on an invisible straight line at the angle determined.

+w:

The angle of the line at the point of straight label placement is calculated by a least-squares fit to the width closest points. If not specified, width defaults to 10.

+=:

Similar in most regards to +u but applies instead to a label prefix which you must append.

For contours, the label will be the value of the contour (possibly modified by +u or +=). However, for quoted lines other options apply:

+l:

Append a fixed label that will be placed at all label locations. If the label contains spaces you must place it inside matching quotes.

+L:

Append a code flag that will determine the label. Available codes are:

+Lh:

Take the label from the current multi-segment header (hence it is assumed that the input line segments are given in the multi-segment file format; if not we pick the single label from the file's header record). We first scan the header for an embedded -Llabel option; if none is found we instead use the first word following the segment marker [$>$].

+Ld:

Take the Cartesian plot distances along the line as the label; append c$\vert$i$\vert$m$\vert$p as the unit [Default is MEASURE_UNIT]. The label will be formatted according to the D_FORMAT string, unless label placement was determined from map distances along the segment lines, in which case we determine the appropriate format from the distance value itself.

+LD:

Calculate actual Earth surface distances and use the distance at the label placement point as the label; append d$\vert$e$\vert$k$\vert$m$\vert$n to specify the unit [If not given we default to degrees, unless label placement was determined from map distances along the segment lines, in which case we use the same unit specified for that algorithm]. Requires a map projection to be used.

+Lf:

Use all text after the 2nd column in the fixed label location file fix.d as labels. This choice obviously requires the fixed label location algorithm (code f) to be in effect.

+Ln:

Use the running number of the current multi-segment as label.

+LN:

Use a slash-separated combination of the current file number and the current multi-segment number as label.

+Lx:

As h but use the multi-segment headers in the cross.d file instead. This choice obviously requires the crossing segments location algorithm (code x$\vert$X) to be in effect.