---
name: "pstext"
section: "1"
platform: "linux"
package: "gmt-manpages"
version: "3.4-1"
release: "Debian 3.0 (Woody)"
platforms: ["linux"]
url: "https://new.carta.tech/pstext"
---

# pstext(1)

To plot text on maps

## NAME

pstext - To plot text on maps

## SYNOPSIS

**pstext** *textfile* **-J***parameters* **-R***west/east/south/north***\[r\]** **\[ -B***tickinfo* **\] \[ -C***dx/dy* **\]** **-D\[j\]***dx/dy***\[v\[***red/green/blue***\] \] \[ -E***azimuth/elevation* **\]** **\[ -G***red/green/blue* **\] \[ -H\[***nrec***\] \] \[ -K \] \[ -L \] \[ -M\[***flag***\] \] \[ -N \] \[ -O \] \[ -P \]** **\[ -S***pen* **\] \[ -U\[***/dx/dy/***\]\[***label***\] \] \[ -V \] \[ -W\[***red/green/blue***\]\[o\|O\|c\|C\[***pen***\]\] \]** **\[ -X***x-shift* **\] \[ -Y***y-shift* **\] \[ -Z***zlevel* **\]** **\[ -c***copies* **\] \[ -: \]**

## DESCRIPTION

**pstext plots textstrings of variable size, font type, and orientation.** **Various map projections are provided, with the option to draw and annotate the** **map boundaries.** *PostScript* **code is written to standard output. Greek** **characters, subscript, superscript, and small caps are supported as follows:** **The sequence @~ toggles between the selected font and Greek (Symbol).** **@%***no***% sets the font to** *no***; @%% resets the font to the starting font,** **@- toggles subscripts on/off, @+ toggles superscript on/off, and @# toggles small** **caps on/off. @@ prints the @ sign. @e, @o, @a, @E, @O, @A give the accented** **Scandinavian characters. 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 4.16 and Appendix F in the** **GMT Technical Reference and Cookbook. Note that WANT\_EURO\_FONT must be** **set to TRUE in your .gmtdefaults file in order to use the accented characters.** **Using the -W option, a colored 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)).**

- *textfile*

  **This file contains 1 or more records with (***x, y, size, angle, fontno, justify, text***).** **If no file is given, pstext will read standard input.** *size* **is text size in points,** *angle* **is measured in degrees counter-clockwise from horizontal,** *fontno* **sets the font type,** *justify* **sets the alignment.** **If** *fontno* **is not an integer, then it is taken to be a textstring with the desired fontname. See the gmtdefaults man page** **for names and numbers of avaiable fonts (or run pstext -L). The alignment refers to the** **part of the textstring 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.**

- **-J**

  **Selects the map projection. Scale is UNIT/degree, 1:xxxxx, or width in UNIT (upper case modifier).** **UNIT is cm, inch, or m, depending on the MEASURE\_UNIT setting in .gmtdefaults, but this can be** **overridden on the command line by appending the c, i, or m to the scale/width value.**\

  **CYLINDRICAL PROJECTIONS:**\

  **-Jc***lon0/lat0/scale* **(Cassini)**\
   **-Jj***lon0/scale* **(Miller)**\
   **-Jm***scale* **(Mercator - Greenwich and Equator as origin)**\
   **-Jm***lon0/lat0/scale* **(Mercator - Give meridian and standard parallel)**\
   **-Joa***lon0/lat0/azimuth/scale* **(Oblique Mercator - point and azimuth)**\
   **-Job***lon0/lat0/lon1/lat1/scale* **(Oblique Mercator - two points)**\
   **-Joc***lon0/lat0/lonp/latp/scale* **(Oblique Mercator - point and pole)**\
   **-Jq***lon0/scale* **(Equidistant Cylindrical Projection (Plate Carree))**\
   **-Jt***lon0/scale* **(TM - Transverse Mercator, with Equator as y = 0)**\
   **-Jt***lon0/lat0/scale* **(TM - Transverse Mercator, set origin)**\
   **-Ju***zone/scale* **(UTM - Universal Transverse Mercator)**\
   **-Jy***lon0/lats/scale* **(Basic Cylindrical Projection)**\

  **AZIMUTHAL PROJECTIONS:**\

  **-Ja***lon0/lat0/scale* **(Lambert).**\
   **-Je***lon0/lat0/scale* **(Equidistant).**\
   **-Jf***lon0/lat0/horizon/scale* **(Gnomonic).**\
   **-Jg***lon0/lat0/scale* **(Orthographic).**\
   **-Js***lon0/lat0/***\[***slat/***\]***scale* **(General Stereographic)**\

  **CONIC PROJECTIONS:**\

  **-Jb***lon0/lat0/lat1/lat2/scale* **(Albers)**\
   **-Jd***lon0/lat0/lat1/lat2/scale* **(Equidistant)**\
   **-Jl***lon0/lat0/lat1/lat2/scale* **(Lambert)**\

  **MISCELLANEOUS PROJECTIONS:**\

  **-Jh***lon0/scale* **(Hammer)**\
   **-Ji***lon0/scale* **(Sinusoidal)**\
   **-Jk\[f\|s\]***lon0/scale* **(Eckert IV (f) and VI (s))**\
   **-Jn***lon0/scale* **(Robinson)**\
   **-Jr***lon0/scale* **(Winkel Tripel)**\
   **-Jv***lon0/scale* **(Van der Grinten)**\
   **-Jw***lon0/scale* **(Mollweide)**\

  **NON-GEOGRAPHICAL PROJECTIONS:**\

  **-Jp\[a\]***scale***\[***/origin***\] (polar (theta,r) coordinates, optional a for azimuths and offset theta \[0\])**\
   **-Jx***x-scale***\[l\|p***pow***\]\[***/y-scale***\[l\|p***pow***\]\] (Linear, log, and power scaling)**\
   **More details can be found in the psbasemap manpages.**\

- **-Jz**

  **Sets the vertical scaling (for 3-D maps). Same syntax as -Jx.**

- **-R**

  *west, east, south,* **and** *north* **specify the Region of interest. To specify boundaries** **in degrees and minutes \[and seconds\], use the dd:mm\[:ss\] format. Append r if lower left and upper right** **map coordinates are given instead of wesn.**

## OPTIONS

**No space between the option flag and the associated arguments.**

- **-B**

  **Sets map boundary tickmark intervals. See psbasemap for details.**

- **-C**

  **Sets the clearance between the text and the surrounding box \[0.15c/0.15c (or 0.05i/0.05i)\].** **Only used if -W is specified.**

- **-D**

  **Offsets the text from the projected (***x,y***) point by** *dx,dy* **\[0/0\].** **Use -Dj to offset the text away from the point instead (i.e. the text's justification'** **will determine the direction of the shift). In paragraph mode** **(-M), one may append v which will draw a line from the original point to the shifted point.** **Optionally append a** *pen* **for this line.**

- **-E**

  **Sets the viewpoint's azimuth and elevation (for perspective view) \[180/90\].'** **(Not implemented for paragraph mode).**

- **-G**

  **Sets the gray-shade (0-255) or color (r/g/b, each 0-255) used for drawing the text. \[Default is black\]**

- **-H**

  **Input file(s) has Header record(s). Number of header records can be changed by editing** **your .gmtdefaults file. If used, GMT default is 1 header record.**

- **-K**

  **More** *PostScript* **code will be appended later \[Default terminates the plot system\].**

- **-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 column, 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 size angle fontno justify linespace parwidth parjust),** **where** *x y size angle fontno justify* **are defined above, 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 as well as three** **more: @;***r/g/b***; changes the font color (@;; resets it), @:***size***: changes the** **font size (@:: resets it), and @\_ toggles underline on/off. Separate paragraphs with a blank line.**

- **-N**

  **Do NOT clip text at map boundaries \[Default will clip\].**

- **-O**

  **Selects Overlay plot mode \[Default initializes a new plot system\].**

- **-P**

  **Selects Portrait plotting mode \[GMT Default is Landscape, see gmtdefaults to change this\].**

- **-S**

  **Draw text outline. Append pen attributes.** **(Not implemented for paragraph mode).**

- **-U**

  **Draw Unix System time stamp on plot. User may specify where the lower left corner** **of the stamp should fall on the page relative to lower left corner of plot. Optionally,** **append a label, or c (which will plot the command string.). The GMT parameters** **UNIX\_TIME and UNIX\_TIME\_POS can affect the appearance; see the gmtdefaults man** **page for details.**

- **-V**

  **Selects verbose mode, which will send progress reports to stderr \[Default runs "silently"\].**

- **-W**

  **Paint a rectangle beneath the text string. Set color \[Default is no fill\].** **Append o to draw rectangle outline, add a** *pen* **to specify pen attributes \[1/0/0/0\].** **Choose upper case O to get a rounded rectangle (only in paragraph mode).** **Choose lower case c to get a concave rectangle (only in paragraph mode).** **Choose upper case C to get a convex rectangle (only in paragraph mode).**

- **-X -Y**

  **Shift origin of plot by (***x-shift,y-shift***).** **Prepend a for absolute coordinates;** **the default (r) will reset plot origin.**

- **-Z**

  **For 3-D projections: Sets the z-level of the basemap \[0\].** **(Not implemented for paragraph mode).**

- **-:**

  **Toggles between (longitude,latitude) and (latitude,longitude) input/output. \[Default is (longitude,latitude)\].** **Applies to geographic coordinates only.**

- **-c**

  **Specifies the number of plot copies. \[Default is 1\]**

## EXAMPLES

**To plot the outlines of the textstrings stored in the file text.d on a Mercator plot with** **the given specifications, try**\

**pstext text.d -R-30/30/-10/20 -Jm0.1i -P -B5 -S0.5p \> plot.ps**\

**To add a typeset figure caption for a 3-inch wide illustration, try**\

**pstext -R0/3/0/5 -JX3i -O -H -M -N \<\< EOF \>\> figure.ps**\
 **This is an optional header record**\
 **\> 0 -0.5 12 0 4 LT 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**\

## BUGS

**Except for paragraph mode, the horizontal justification of surrounding rectangles** **does not work when Greek symbols, sub- and superscripts, and/or composite characters** **are imbedded in the textstring. In paragraph mode, the presence of composite** **characters and other escape sequences may lead to unfortunate word splitting.** **Finally, the outline option does not work with the escape sequences.**\
 **The -N option does not adjust the BoundingBox information so you may** **have to post-process the PostScript outout with epstool or ps2epsi to obtain** **a correct BoundingBox.**

## SEE ALSO

*gmt*(l), *psbasemap*(l)