O.1 Label Placement

While the previous GMT verions 1-3 allowed for a single algorithm that determined where labels would be placed, GMT 4 allows for five different algorithms. Futhermore, a new ``symbol'' option (-Sq for ``quoted line'') has been added to psxy and psxyz and hence the new label placement mechanisms apply to those programs as well. The contouring programs expect the algorithm to be specified as arguments to -G while the line plotting programs expect the same arguments to follow -Sq. The information appended to these options is the same in both cases and is of the form [code]info. The five algorithms correspond to the five codes below (some codes will appear in both upper and lower case; they share the same algorithm but differ in some other ways). In what follows, the phrase ``line segment'' is taken to mean either a contour or a line to be labelled. The codes are:

d:

Full syntax is ddist[c$\vert$i$\vert$m$\vert$p][/frac]. Place labels according to the distance measured along the projected line on the map. Append the unit you want to measure distances in [Default is taken from MEASURE_UNIT]. Starting at the beginning of a line, place labels every dist increment of distance along the line. To ensure that closed lines whose total length is less than dist get annotated, we may append frac which will place the first label at the distance $d =$ dist $\times$ frac from the start of a closed line (and every dist thereafter). If not given, frac defaults to 0.25.

D:

Full syntax is Ddist[d$\vert$e$\vert$k$\vert$m$\vert$n][/frac]. This option is similar to d except the original data must be referred to geographic coordinates (and a map projection must have been chosen) and actual Earth^O.1 surface distances along the lines are considered. Append the unit you want to measure distances in; choose among degree, meter [Default], kilometer, statute miles, or nautical miles. Other aspects are similar to code d.

f:

Full syntax is ffix.d[/slop[c$\vert$i$\vert$m$\vert$p]]. Here, an ASCII file fix.d is given which must contain records whose first two columns hold the coordinates of points along the lines at which locations the labels should be placed. Labels will only be placed if the coordinates match the line coordinates to within a distance of slop (append unit or we use MEASURE_UNIT). The default slop is zero, meaning only exact coordinate matches will do.

l:

Full syntax is lline1[,line2[, ...]]. One or more straight line segments are specified separated by commas, and labels will be placed at the intersections between these lines and our line segments. Each line specification implies a start and stop point, each corresponding to a coordinate pair. These pairs can be regular coordinate pairs (i.e., longitude/latitude separated by a slash), or they can be two-character codes that refer to predetermined points relative to the map region. These codes are taken from the pstext justification keys [L$\vert$C$\vert$R][B$\vert$M$\vert$T] so that the first character determines the $x$-coordinate and the second determines the $y$-coordinate. In grdcontour, you can also use the two codes Z+ and Z- as shorthands for the location of the grid's global maximum and minimum, respectively. For example, the line LT/RB is a diagonal from the upper left to the lower right map corner, while Z-/135W/15S is a line from the grid minimum to the point (135$^{o}$W, 15$^{o}$S).

L:

Same as l except we will treat the lines given as great circle start/stop coordinates and fill in the points between before looking for intersections.

n:

Full syntax is nnumber[/minlength[c$\vert$i$\vert$m$\vert$p]]. Place number of labels along each line regardless of total line length. The line is divided into number segments and the labels are placed at the centers of these segments. Optionally, you may give a minlength distance to ensure that no labels are placed closer than this distance to its neighbors.

N:

Full syntax is Nnumber[/minlength[c$\vert$i$\vert$m$\vert$p]]. Similar to code n but here labels are placed at the ends of each segment (for number $\geq 2$). A special case arises for number $= 1$ when a single label will be placed according to the sign of number: $-1$ places one label justified at the start of the line, while $+1$ places one label justified at the end of the line.

x:

Full syntax is xcross.d. Here, an ASCII file cross.d is a multi-segment file whose lines will intersect our segment lines; labels will be placed at these intersections.

X:

Same as x except we treat the lines given as great circle start/stop coordinates and fill in the points between before looking for intersections.

Only one algorithm can be specified at any given time.