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, and text

  • position and text

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

Aliases:

  • B = frame

  • C = clearance

  • D = offset

  • G = fill

  • J = projection

  • N = no_clip

  • R = region

  • V = verbose

  • W = pen

  • X = xshift

  • Y = yshift

  • c = panel

  • p = perspective

  • t = transparency

Parameters

  • textfiles (str or list) – A text data file name, or a list of filenames containing 1 or more records with (x, y[, angle, font, justify], text).

  • x/y (float or 1d arrays) – The x and y coordinates, or an array of x and y coordinates to plot the text

  • position (str) –

    Sets reference point on the map for the text by using x,y coordinates extracted from region instead of providing them through x and 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 Upper Left corner of the map.

  • text (str or 1d array) – The text string, or an array of strings to plot on the figure

  • angle (int, float, str or bool) – 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 textfile(s) must have this as a column.

  • font (str or bool) – 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. E.g. “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 textfile(s) must have this information in one of its columns.

  • justify (str or bool) – Set the alignment which 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 lower left. If no justification is explicitly given (i.e. justify=True), then the input textfile(s) must have this as a column.

  • projection (str) – Required if this is the first plot command. Select map projection.

  • region (str or list) – Required if this is the first plot command. 'xmin/xmax/ymin/ymax[+r][+uunit]'. Specify the region of interest.

  • clearance (str) – [dx/dy][+to|O|c|C] Adjust the clearance between the text and the surrounding box [15%]. Only used if pen or fill are specified. Append the unit you want (‘c’ for cm, ‘i’ for inch, or ‘p’ for point; 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 textbox when using fill and/or pen. Append lower case ‘o’ to get a straight rectangle [Default]. 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) – Sets the shade or color used for filling the text box [Default is no fill].

  • offset (str) – [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. Use offset=’j’ to offset the text away from the point instead (i.e., the text justification will determine the direction of the shift). Using offset=’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) – Sets the pen used to draw a rectangle around the text string (see clearance) [Default is width = default, color = black, style = solid].

  • no_clip (bool) – Do NOT clip text at map boundaries [Default is False, i.e. will clip].

  • verbose (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 algorthms);

    • i - Informational messages (same as “verbose=True”)

    • c - Compatibility warnings

    • d - Debugging messages

  • xshift (str) – [a|c|f|r][xshift]. Shift plot origin in x-direction.

  • yshift (str) – [a|c|f|r][yshift]. Shift plot origin in y-direction. Full documentation is at https://docs.generic-mapping-tools.org/latest/gmt.html#xy-full.

  • panel (int or list) – [row,col|index]. Used to advance to the selected subplot panel. Only allowed when in subplot mode. Available to all plot modules. If no arguments are given then we advance to the next panel in the selected order. If no panel is given and we just entered subplot mode then the first panel (top, left) is selected. Instead of row, col you may give the one-dimensional index which depends on the order you set via autolabel when the subplot was defined. Note: row, col, and index all start at 0.

  • 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/latest/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).

Examples using pygmt.Figure.text