text

Plot or typeset text

Synopsis

gmt text [ textfiles ] -Jparameters -Rwest/east/south/north[/zmin/zmax][+r][+uunit] [ -A ] [ -B[p|s]parameters ] [ -C[dx[/dy]][+to|O|c|C] ] [ -D[j|J]dx[/dy][+v[pen]] ] [ -F[+a[angle]][+c[justify]][+f[font]][+j[justify]][+h|l|r[first] |ttext|z[format]] ] [ -G[fill][+n] ] [ -L ] [ -M ] [ -N ] [ -Ql|u ] [ -S[dx/dy/][shade] ] [ -U[stamp] ] [ -V[level] ] [ -Wpen ] [ -X[a|c|f|r][xshift] ] [ -Y[a|c|f|r][yshift] ] [ -Z ] [ -acol=name[…] ] [ -eregexp ] [ -fflags ] [ -hheaders ] [ -itword ] [ -pflags ] [ -qiflags ] [ -ttransp ] [ -wflags ] [ -:[i|o] ] [ --PAR=value ]

Description

text plots text strings of variable size, font type, and orientation. Various map projections are provided, with the option to draw and annotate the map boundaries.

Greek characters, subscript, superscript, and small caps are supported as follows:

Symbol

Behavior

@~

Toggles between the selected font and Greek (Symbol)

@%font%

Switches to font where font can either be a font number or name (see -L) (@%% resets it)

@-

Toggles subscripts on/off

@+

Toggles superscript on/off

@#

Toggles small caps on/off

@;color;

Changes the font color (@;; resets it)

@:size:

Changes the font size (@:: resets it)

@_

Toggles underline on/off

@@

Prints the @ sign

@.

Prints the degree symbol

@a, @c, @e, @i, @n, @o, @s, @u, @A, @C, @E, @N, @O, and @U give various accented European characters, as indicated in Table escape. Composite characters (overstrike) may be indicated with the @!<char1><char2> sequence, which will print the two characters on top of each other.

To learn the octal codes for symbols not available on the keyboard and some accented European characters, see Section Character escape sequences and Appendix Chart of Octal Codes for Characters in the GMT Technical Reference. Note that PS_CHAR_ENCODING must be set to an extended character set in your gmt.conf file in order to use the accented characters.

Using the -G or -W options, a rectangle underlying the text may be plotted (does not work for strings with sub/super scripts, symbols, or composite characters, except in paragraph mode (-M)).

Finally, you may typeset LaTeX expressions provided they are enclosed in @[ … @[ or <math> … </math>; see Chapter Using LaTeX Expressions in GMT for more details.

Required Arguments

textfiles

This is one or more files containing 1 or more records with (x y [font angle justify] text). The presence or absence of items in the brackets are determined by -F. If no files are given, text will read standard input. font is a font specification with format [size,][font,][color] where size is text size in points, font is the font to use, and color sets the font color. To draw outline fonts you append =pen to the font specification. The angle is measured in degrees counter-clockwise from horizontal, and justify sets the alignment. If font is not an integer, then it is taken to be a text string with the desired font name (see -L for available fonts). The alignment refers to the part of the text string that will be mapped onto the (x,y) point. Choose a 2 character combination of L, C, R (for left, center, or right) and T, M, B for top, middle, or bottom. e.g., BL for bottom left.

-Jparameters

Specify the projection. (See full description) (See cookbook summary) (See projections table).

-Rxmin/xmax/ymin/ymax[+r][+uunit]

Specify the region of interest. (See full description) (See cookbook information).

For perspective view -p, optionally append /zmin/zmax. (more …)

Optional Arguments

-A

Angles are given as azimuths; convert them to directions using the current projection.

-B[p|s]parameters

Set map boundary frame and axes attributes. (See full description) (See cookbook information).

-C[dx[/dy]][+to|O|c|C]

Adjust the clearance between the text and the surrounding box [15%]. Only used if -W or -G are specified. Append the unit you want (cm, inch, or point; if not given we consult PROJ_LENGTH_UNIT) or % for a percentage of the font size. If dy is not specified then it is set equal to dx. Optionally, use modifier +t to append the shape of the textbox when using -G and/or -W:

  • o - Straight rectangle [Default].

  • O - Set a rounded rectangle.

  • c - (Paragraph mode (-M only) selects a concave rectangle.

  • C - (Paragraph mode (-M only) selects a convex rectangle.

-D[j|J]dx[/dy][+v[pen]]

Offsets the text from the projected (x,y) point by dx,dy [0/0]. If dy is not specified then it is set equal to dx. Prepend an optional directive:

  • -j - Offset the text away from the point instead (i.e., the text justification will determine the direction of the shift).

  • -J - Shorten diagonal offsets at corners by \(\sqrt{2}\).

Optionally, append the modifier:

  • +v - Draw a line from the original point to the shifted point; append a pen to change the attributes for this line. Note: The -Dj|J selection cannot be used with paragraph mode (-M).

-F[+a[angle]][+c[justify]][+f[font]][+j[justify]][+h|l|r[first]|ttext|z[format]]

By default, text will be placed horizontally, using the primary annotation font attributes [FONT_ANNOT_PRIMARY], and centered on the data point. Use -F to override these defaults by specifying up to three text attributes (font, angle, and justification) directly on the command line via these modifiers:

  • +a - Set the text angle; if no angle is given then the input file must have this angle as a column.

  • +A - Force text-baselines to convert into the -90/+90 range.

  • +c - Append justification to set the x, y coordinates extracted from the -R string instead of providing them in the input file. For example -F+cTL gets the x_min, y_max from the -R string and plots the text at the Upper Left corner of the map.

  • +f - Set the font ([size][,fontname][,color]); if no font info is given then the input file must have this information in one of its columns.

  • +h - Use the most recent segment header as the text to be plotted. comes from the data record. Instead, use +h or +l to select the

  • +j - Set the text justification; if no justification is given then the input file must have this item as a column.

  • +l - Use the most recent segment label as the text to be plotted.

  • +r - Use the record number (counting up from first [0]) as the text to be plotted.

  • +t - Use the appended text to set a fixed text string (if text contains plus characters then the +t modifier must be the last modifier in -F).

  • +z - Format incoming z values to a string using the supplied format [if not appended we use FORMAT_FLOAT_MAP].

Notes: (1) If -Z is in effect then the z value used for formatting is in the 4th, not 3rd column. If you only want a specific word from the trailing text and not the whole line, use -itword to indicate which word (0 is the first word) you want. (2) Items read from the data file should be in the same order as the modifiers are specified with the -F option. Example: -F+f12p,Helvetica-Bold,red+j+a selects a 12p red Helvetica-Bold font and expects to read the justification and angle from the file, in that order, after x y and before text.

-G[fill][+n]

Sets the shade or color used for filling the text box [Default is no fill]. Alternatively, give no fill to plot text and then use the text dimensions (and -C) to build clip paths and turn clipping on. This clipping can then be turned off later with clip -C. To not plot the text but activate clipping, use -G+n instead. Note: cannot be used with LaTeX expressions.

-L

Lists the font-numbers and font-names available, then exits.

-M

Paragraph mode. Files must be multiple segment files. Segments are separated by a special record whose first character must be flag [Default is >]. Starting in the 3rd field, we expect to find information pertaining to the typesetting of a text paragraph (the remaining lines until next segment header). The information expected is (x y [font angle justify] linespace parwidth parjust), where x y font angle justify are defined above (the presence or absence of font, angle, and justify are determined by -F), while linespace and parwidth are the linespacing and paragraph width, respectively. The justification of the text paragraph is governed by parjust which may be l(eft), c(enter), r(ight), or j(ustified). The segment header is followed by one or more lines with paragraph text. Text may contain the escape sequences discussed above, although composite characters are not supported. Separate paragraphs with a blank line. Note that here, the justification set via -F+j applies to the box alignment since the text justification is set by parjust. Note: cannot be used with LaTeX expressions.

-N

Do not clip text at map boundaries [Default will clip].

-Ql|u

Change all text to either lower or upper case [Default leaves all text as is].

-S[dx/dy/][shade]

Plot an offset background shaded region beneath the text box. Here, dx/dy indicates the shift relative to the text box [4p/-4p] and shade sets the fill color to use for shading [gray50].

-U[label|+c][+jjustify][+odx[/dy]][+ttext]

Draw GMT time stamp logo on plot. (See full description) (See cookbook information).

-V[level]

Select verbosity level [w]. (See full description) (See cookbook information).

-Wpen

Sets the pen used to draw a rectangle around the text string (see -C) [Default is width = 0.25p, color = black, style = solid]. Note: cannot be used with LaTeX expressions.

-X[a|c|f|r][xshift]

Shift plot origin. (See full description) (See cookbook information).

-Y[a|c|f|r][yshift]

Shift plot origin. (See full description) (See cookbook information).

-Z

For 3-D projections: expect each item to have its own level given in the 3rd column, and -N is implicitly set. (Not implemented for paragraph mode). Note: If -F+z is used then the text level is based on the 4th data column instead.

-a[[col=]name[,…]] (more …)

Set aspatial column associations col=name.

-e[~]“pattern” | -e[~]/regexp/[i] (more …)

Only accept data records that match the given pattern.

-f[i|o]colinfo (more …)

Specify data types of input and/or output columns.

-h[i|o][n][+c][+d][+msegheader][+rremark][+ttitle] (more …)

Skip or produce header record(s).

-itword

In this module, -it can be used to select a specific word from the trailing text [Default is the entire trailing text]. The word indicates the word order, with the first word being 0. No numerical columns can be specified.

-p[x|y|z]azim[/elev[/zlevel]][+wlon0/lat0[/z0]][+vx0/y0] (more …)

Select perspective view. (Not implemented for paragraph mode).

-qi[~]rows|limits[+ccol][+a|t|s] (more …)

Select input rows or data limit(s) [default is all rows].

-t[transp[/transp2]][+f][+s]

Set transparency level for an overlay, in [0-100] percent range. [Default is 0, i.e., opaque]. Only visible when PDF or raster format output is selected. Only the PNG format selection adds a transparency layer in the image (for further processing). If given, transp applies to both fill and stroke, but you can limit the transparency to one of them by appending +f or +s for fill or stroke, respectively. Alternatively, append /transp2 to set separate transparencies for fills and strokes. If no transparencies are given then we expect to read them from the last numerical column(s). Use the modifiers to indicate which one(s) we should be reading (if both are requested, fill transparency is expected before stroke transparency in the column order). If just -t is given then we interpret it to mean -t+f for fill transparency only.

-wy|a|w|d|h|m|s|cperiod[/phase][+ccol] (more …)

Convert an input coordinate to a cyclical coordinate.

-:[i|o] (more …)

Swap 1st and 2nd column on input and/or output.

-^ or just -

Print a short message about the syntax of the command, then exit (Note: on Windows just use -).

-+ or just +

Print an extensive usage (help) message, including the explanation of any module-specific option (but not the GMT common options), then exit.

-? or no arguments

Print a complete usage (help) message, including the explanation of all options, then exit.

--PAR=value

Temporarily override a GMT default setting; repeatable. See gmt.conf for parameters.

Examples

Note: Below are some examples of valid syntax for this module. The examples that use remote files (file names starting with @) can be cut and pasted into your terminal for testing. Other commands requiring input files are just dummy examples of the types of uses that are common but cannot be run verbatim as written.

Note: Since many GMT plot examples are very short (i.e., one module call between the gmt begin and gmt end commands), we will often present them using the quick modern mode GMT Modern Mode One-line Commands syntax, which simplifies such short scripts.

To plot just the red outlines of the (lon lat text strings) stored in the file text.txt on a Mercator plot with the given specifications, use:

gmt text text.txt -R-30/30/-10/20 -Jm0.1i -F+f18p,Helvetica,-=0.5p,red -B5 -pdf plot

To plot a text at the upper left corner of a 10 cm map:

echo TopLeft | gmt text -R1/10/1/10 -JX10 -B -F+cTL -pdf plot

To add a typeset figure caption for a 3-inch wide illustration, use:

gmt text -R0/3/0/5 -JX3i -h1 -M -N -F+f12,Times-Roman+jLT -pdf figure << EOF
This is an unmarked header record not starting with #
> 0 -0.5 13p 3i j
@%5%Figure 1.@%% This illustration shows nothing useful, but it still needs
a figure caption. Highlighted in @;255/0/0;red@;; you can see the locations
of cities where it is @\_impossible@\_ to get any good Thai food; these are to be avoided.
EOF

To place a line containing a Latex equation, try:

echo 3 3 'Use @[\Delta g = 2\pi\rho Gh@[' | gmt text -R0/6/0/6 -JX15c -B -F+f32p+a30 -pdf map

To place text with a surrounding box and an underlying, shifted shade, both using a rounded rectangle, try:

gmt text -R0/10/0/5 -Jx1c -F+f32p+cCM+tWELCOME -B -Gyellow -Wfaint -S -C+tO -pdf map

Windows Remarks

Note that under Windows, the percent sign (%) is a variable indicator (like $ under Unix). To indicate a plain percentage sign in a batch script you need to repeat it (%%); hence the font switching mechanism (@%font% and @%%) may require twice the number of percent signs. This only applies to text inside a script or that otherwise is processed by DOS. Data files that are opened and read by the module do not need such duplication.

Composite Characters

If the two characters that are to be combined come from different fonts (say, Symbol and Times), then it is allowed for the second character (but not the first) to be surrounded by escape codes to temporarily change the font for that character. For instance, the sequence “@!\227@~\145@~” will print the epsilon character (octal code \145 from the Symbol font) with time-derivative indicated by the over-printed dot (octal code \227 from the current font, assuming the ISOLatin1 character set).

Limitations

In paragraph mode, the presence of composite characters and other escape sequences may lead to unfortunate word splitting. Also, if a font is requested with an outline pen it will not be used in paragraph mode. Note if any single word is wider than your chosen paragraph width then the paragraph width is automatically enlarged to fit the widest word.

Use from external interface

When the module is called from external interfaces then we impose the following condition on the -F setting: We require that +a (read angle from input), if specified, must appear before either of +f (read font from input) and +j (read justification from input), if these are present. This is necessary because the angle is a numerical column while font and justification must be encoded as part of the trailing text.

Adding more fonts

To add custom fonts, please see General Features.

See Also

gmt, gmt.conf, clip, gmtcolors, psconvert, basemap, legend, plot