pygmt.Figure.text

Figure.text(textfiles=None, x=None, y=None, position=None, text=None, angle=None, font=None, justify=None, *, region=None, projection=None, frame=None, clearance=None, offset=None, fill=None, no_clip=None, verbose=None, pen=None, aspatial=None, panel=None, find=None, coltypes=None, header=None, use_word=None, perspective=None, transparency=None, wrap=None, **kwargs)

Plot or typeset text strings of variable size, font type, and orientation.

Must provide at least one of the following combinations as input:

textfiles
x/y, and text
position and text

The text strings passed via the text parameter can contain ASCII characters and non-ASCII characters defined in the ISOLatin1+ encoding (i.e., IEC_8859-1), and the Symbol and ZapfDingbats character sets. See https://docs.generic-mapping-tools.org/6.5/reference/octal-codes.html for the full list of supported non-ASCII characters.

Full option list at https://docs.generic-mapping-tools.org/6.5/text.html

Aliases:

B = frame
C = clearance
D = offset
G = fill
J = projection
N = no_clip
R = region
V = verbose
W = pen
a = aspatial
c = panel
e = find
f = coltypes
h = header
it = use_word
p = perspective
t = transparency
w = wrap

Parameters:

textfiles (str or list) –
A file name or a list of file names containing one or more records. Each record has the following columns:
- x: X coordinate or longitude
- y: Y coordinate or latitude
- angle: Angle in degrees counter-clockwise from horizontal
- font: Text size, font, and color
- justify: Two-character justification code
- text: The text string to typeset
The angle, font, and justify columns are optional and can be set by using the angle, font, and justify parameters, respectively. If these parameters are set to True, then the corresponding columns must be present in the input file(s) and the columns must be in the order mentioned above.
x/y (float or 1-D arrays) – The x and y coordinates, or an array of x and y coordinates to plot the text.
position (str) –
Set reference point on the map for the text by using x, y coordinates extracted from region instead of providing them through x/y. Specify with a two-letter (order independent) code, chosen from:
- Horizontal: L(eft), C(entre), R(ight)
- Vertical: T(op), M(iddle), B(ottom)
For example, position="TL" plots the text at the Top Left corner of the map.
text (str or 1-D array) – The text string, or an array of strings to plot on the figure.
angle (float, str, bool or list) – Set the angle measured in degrees counter-clockwise from horizontal (e.g. 30 sets the text at 30 degrees). If no angle is explicitly given (i.e. angle=True) then the input to textfiles must have this as a column.
font (str, bool or list of str) – Set the 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. For example, font="12p,Helvetica-Bold,red" selects a 12p, red, Helvetica-Bold font. If no font info is explicitly given (i.e. font=True), then the input to textfiles must have this information in one of its columns.
justify (str, bool or list of str) – Set the alignment which refers to the part of the text string that will be mapped onto the (x, y) point. Choose a two-letter 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. If no justification is explicitly given (i.e. justify=True), then the input to textfiles must have this as a column.
projection (str) – projcode[projparams/]width|scale. Select map projection.
region (str or list) – xmin/xmax/ymin/ymax[+r][+uunit]. Specify the region of interest. Required if this is the first plot command.
clearance (str) – [dx/dy][+to|O|c|C]. Adjust the clearance between the text and the surrounding box [Default is 15% of the font size]. Only used if pen or fill are specified. Append the unit you want (c for centimeters, i for inches, or p for points; if not given we consult PROJ_LENGTH_UNIT) or % for a percentage of the font size. Optionally, use modifier +t to set the shape of the text box when using fill and/or pen. Append lower case o to get a straight rectangle [Default is o]. Append upper case O to get a rounded rectangle. In paragraph mode (paragraph) you can also append lower case c to get a concave rectangle or append upper case C to get a convex rectangle.
fill (str) – Set color for filling text boxes [Default is no fill].
offset (str) – [j|J]dx[/dy][+v[pen]]. Offset the text from the projected (x, y) point by dx/dy [Default is "0/0"]. If dy is not specified then it is set equal to dx. Use j to offset the text away from the point instead (i.e., the text justification will determine the direction of the shift). Using J will shorten diagonal offsets at corners by sqrt(2). Optionally, append +v which will draw a line from the original point to the shifted point; append a pen to change the attributes for this line.
pen (str) – Set the pen used to draw a rectangle around the text string (see clearance) [Default is "0.25p,black,solid"].
no_clip (bool) – Do not clip text at the frame boundaries [Default is False].
verbose (bool or str) –
Select verbosity level [Default is w], which modulates the messages written to stderr. Choose among 7 levels of verbosity:
- q - Quiet, not even fatal error messages are produced
- e - Error messages only
- w - Warnings [Default]
- t - Timings (report runtimes for time-intensive algorithms)
- i - Informational messages (same as verbose=True)
- c - Compatibility warnings
- d - Debugging messages
aspatial (bool or str) – [col=]name[,…]. Control how aspatial data are handled during input and output. Full documentation is at https://docs.generic-mapping-tools.org/6.5/gmt.html#aspatial-full.
panel (bool, int, or list) – [row,col|index]. Select a specific subplot panel. Only allowed when in subplot mode. Use panel=True to advance to the next panel in the selected order. Instead of row,col you may also give a scalar value index which depends on the order you set via autolabel when the subplot was defined. Note: row, col, and index all start at 0.
find (str) – [~]“pattern” | [~]/regexp/[i]. Only pass records that match the given pattern or regular expressions [Default processes all records]. Prepend ~ to the pattern or regexp to instead only pass data expressions that do not match the pattern. Append i for case insensitive matching. This does not apply to headers or segment headers.
coltypes (str) – [i|o]colinfo. Specify data types of input and/or output columns (time or geographical data). Full documentation is at https://docs.generic-mapping-tools.org/6.5/gmt.html#f-full.
header (str) –
[i|o][n][+c][+d][+msegheader][+rremark][+ttitle]. Specify that input and/or output file(s) have n header records [Default is 0]. Prepend i if only the primary input should have header records. Prepend o to control the writing of header records, with the following modifiers supported:
- +d to remove existing header records.
- +c to add a header comment with column names to the output [Default is no column names].
- +m to add a segment header segheader to the output after the header block [Default is no segment header].
- +r to add a remark comment to the output [Default is no comment]. The remark string may contain \n to indicate line-breaks.
- +t to add a title comment to the output [Default is no title]. The title string may contain \n to indicate line-breaks.
Blank lines and lines starting with # are always skipped.
use_word (int) – Select a specific word from the trailing text, with the first word being 0 [Default is the entire trailing text]. No numerical columns can be specified.
perspective (list or str) – [x|y|z]azim[/elev[/zlevel]][+wlon0/lat0[/z0]][+vx0/y0]. Select perspective view and set the azimuth and elevation angle of the viewpoint [Default is [180, 90]]. Full documentation is at https://docs.generic-mapping-tools.org/6.5/gmt.html#perspective-full.
transparency (float) – Set transparency level, 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). transparency can also be a 1-D array to set varying transparency for texts, but this option is only valid if using x/y and text.
wrap (str) –
y|a|w|d|h|m|s|cperiod[/phase][+ccol]. Convert the input x-coordinate to a cyclical coordinate, or a different column if selected via +ccol. The following cyclical coordinate transformations are supported:
- y - yearly cycle (normalized)
- a - annual cycle (monthly)
- w - weekly cycle (day)
- d - daily cycle (hour)
- h - hourly cycle (minute)
- m - minute cycle (second)
- s - second cycle (second)
- c - custom cycle (normalized)
Full documentation is at https://docs.generic-mapping-tools.org/6.5/gmt.html#w-full.