pygmt.Figure.text
- Figure.text(textfiles=None, x=None, y=None, position=None, text=None, angle=None, font=None, justify=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
, andtext
position
andtext
The text strings passed via the
text
parameter can contain ASCII characters and non-ASCII characters defined in the Adobe ISOLatin1+, Adobe Symbol, Adobe ZapfDingbats and ISO-8859-x (x can be 1-11, 13-16) encodings. Refer to Supported Encodings and Non-ASCII Characters 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:
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
, andjustify
parameters, respectively. If these parameters are set toTrue
, 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 (
Optional
[Literal
['TL'
,'TC'
,'TR'
,'ML'
,'MC'
,'MR'
,'BL'
,'BC'
,'BR'
]], default:None
) –Set reference point on the map for the text by using x, y coordinates extracted from
region
instead of providing them throughx
/y
. Specify with a two-letter (order independent) code, chosen from:Vertical: T(op), M(iddle), B(ottom)
Horizontal: L(eft), C(entre), R(ight)
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 totextfiles
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 totextfiles
must have this information in one of its columns.justify (
Union
[bool
,None
,Literal
['TL'
,'TC'
,'TR'
,'ML'
,'MC'
,'MR'
,'BL'
,'BC'
,'BR'
],Sequence
[Literal
['TL'
,'TC'
,'TR'
,'ML'
,'MC'
,'MR'
,'BL'
,'BC'
,'BR'
]]], default:None
) – 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 totextfiles
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
orfill
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 usingfill
and/orpen
. 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
].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 viaautolabel
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 usingx
/y
andtext
.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.
Examples using pygmt.Figure.text
Cartesian, circular, and geographic vectors
Cross-section along a transect