xenial (1) pslegend.1gmt.gz

Provided by: gmt-common_5.2.1+dfsg-3build1_all bug

NAME

       pslegend - Plot legends on maps

SYNOPSIS

       pslegend  [  specfile  ]  refpoint  ]  [  dx/dy  ]  [  box  ]  [ parameters ] [  ] [  ] [  ] [ region ] [
       [just/dx/dy/][c|label] ] [ [level] ] [ x_offset ] [ y_offset ] [ -ccopies ] [ -p<flags> ] [ -t<transp> ]

       Note: No space is allowed between the option flag and the associated arguments.

DESCRIPTION

       pslegend will make legends that can be overlaid on maps. It  reads  specific  legend-related  information
       from  an  input  file  [or  stdin].   Unless  otherwise noted, annotations will be made using the primary
       annotation font and size in effect (i.e., FONT_ANNOT_PRIMARY)

REQUIRED ARGUMENTS

       -D[g|j|J|n|x]refpoint+wwidth[/height][+jjustify][+lspacing][+odx[/dy]]
              Defines the reference point on the map for the legend using one of four  coordinate  systems:  (1)
              Use  -Dg  for  map  (user)  coordinates,  (2)  use  -Dj  or  -DJ for setting refpoint via a 2-char
              justification code that refers to the (invisible) map domain rectangle, (3) use -Dn for normalized
              (0-1)  coordinates,  or (4) use -Dx for plot coordinates (inches, cm, etc.).  All but -Dx requires
              both -R and -J to be specified.  Append +wwidth[/height] to set the  width  (and  height)  of  the
              legend  box  in  plot  coordinates  (inches,  cm,  etc.).   If height is zero or not given then we
              estimate height based the expected vertical extent of the items to be  placed.   By  default,  the
              anchor  point  on the legend is assumed to be the bottom left corner (BL), but this can be changed
              by appending +j followed by a 2-char justification code justify (see pstext).   Note:  If  -Dj  is
              used  then  justify  defaults to the same as refpoint, if -DJ is used then justify defaults to the
              mirror opposite of refpoint.  Use +lspacing to change the line-spacing  factor  in  units  of  the
              current  font  size  [1.1].   Finally,  add  +o  to  offset the color scale by dx/dy away from the
              refpoint point in the direction implied by justify (or the direction implied by -Dj or -DJ).

OPTIONAL ARGUMENTS

       -B[p|s]parameters (more ...)
              Set map boundary intervals.

       -Cdx/dy
              Sets the clearance between the legend frame and the internal items [4p/4p].

       -F[+cclearances][+gfill][+i[[gap/]pen]][+p[pen]][+r[radius]][+s[[dx/dy/][shade]]]
              Without further options, draws a rectangular border around the legend using MAP_FRAME_PEN; specify
              a  different  pen  with  +ppen.   Add +gfill to fill the legend box [no fill].  Append +cclearance
              where clearance is either gap, xgap/ygap, or lgap/rgap/bgap/tgap where these  items  are  uniform,
              separate  in  x- and y-direction, or individual side spacings between scale and border.  Append +i
              to draw a secondary, inner border as well. We use a uniform gap between  borders  of  2p  and  the
              MAP_DEFAULTS_PEN  unless other values are specified. Append +r to draw rounded rectangular borders
              instead, with a 6p corner radius. You  can  override  this  radius  by  appending  another  value.
              Finally,  append  +s  to  draw an offset background shaded region. Here, dx/dy indicates the shift
              relative to the foreground frame [4p/-4p] and shade  sets  the  fill  style  to  use  for  shading
              [gray50].

       -Jparameters (more ...)
              Select map projection.

       -K (more ...)
              Do not finalize the PostScript plot.

       -O (more ...)
              Append to existing PostScript plot.

       -P (more ...)
              Select "Portrait" plot orientation.

       -R[unit]xmin/xmax/ymin/ymax[r] (more ...)
              Specify the region of interest.

       -U[just/dx/dy/][c|label] (more ...)
              Draw GMT time stamp logo on plot.

       -V[level] (more ...)
              Select verbosity level [c].

       -X[a|c|f|r][x-shift[u]]

       -Y[a|c|f|r][y-shift[u]] (more ...)
              Shift plot origin.

       -ccopies (more ...)
              Specify number of plot copies [Default is 1].

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

       -t[transp] (more ...)
              Set PDF transparency level in percent.

       -^ or just -
              Print a short message about the syntax of the command, then exits (NOTE: on Windows use just -).

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

       -? or no arguments
              Print a complete usage (help) message, including the explanation of options, then exits.

       --version
              Print GMT version and exit.

       --show-datadir
              Print full path to GMT share directory and exit.

PSLEGEND CODES

       specfile
              This ASCII file contains instructions for the layout of items in the legend. Each legend  item  is
              described  by  a  unique  record.  All records begin with a unique character that is common to all
              records of the same kind. The order of the legend items is implied by the order  of  the  records.
              Fourteen  different  record  types  are  recognized,  and the syntax for each of these records are
              presented below:

       # comment
              Records starting with # and blank lines are skipped.

       A cptname
              Symbol or cell color fills may be given indirectly via a z-value which can be used for  the  color
              look-up  via  the  given  CPT  file  cptname.   You  may switch to other cptname by repeating this
              command.

       B cptname offset height [ optional arguments ]
              The B record will plot a horizontal color bar, psscale-style in the  middle,  starting  at  offset
              from  the  left edge, and of the given height. You may add any additional psscale options as well.
              Any of the modifiers [+e[b|f][<length>]][+h][+ma|c|l|u][+n[<txt>]] may be appended to  the  height
              argument,  while  other  module  options  -B  -I -L -M -N -S -Z and -p may be appended as optional
              arguments at the end of the record.  See psscale for details on all modifiers and options.

       C textcolor
              The C record specifies the color with which the remaining text is to be printed. textcolor can  be
              in  the  form  r/g/b,  c/m/y/k,  a named color, or an indirect color via z=*value* (requires the A
              command).  Use - to reset to default color.

       D [offset] pen [-|+|=]
              The D record results in a horizontal line with specified pen across the legend with one quarter of
              the  line-spacing  left  blank  above  and below the line. Two gaps of offset units are left blank
              between the horizontal line and the left and right frame sides [0]. If no  pen  is  given  we  use
              MAP_GRID_PEN_PRIMARY,  and  if pen is set to - then no visible line is drawn (we just remember the
              location as a possible start/stop point for a vertical line; see  V).   To  not  add  the  quarter
              line-spacing  before  the  line,  add  -.   To  not add the spacing after the line, add +.  For no
              spacing at all, add = [Default places a quarter line-spacing both before and after the line].

       F fill1 fill2 ... filln
              Specify fill (color of pattern) for cells.  Alternatively, you can specify an indirect  color  via
              z=*value*  (requires  the  A  command).  If only fill1 is given then it is used to fill the entire
              row, otherwise give one fill value for each active column (see N).  If any fill is - then no  fill
              takes place [Default].

       G gap  The  G  record specifies a vertical gap of the given length. In addition to the standard units (i,
              c, p) you may use l for lines. A negative gap will move the current line upwards (thus  closing  a
              gap).

       H fontsize|- font|- header
              The H record plots a centered text string using the specified font parameters. Use - to default to
              size and type of FONT_TITLE.

       I imagefile width justification
              Place an EPS or raster image in the legend justified relative to  the  current  point.  The  image
              width determines the size of the image on the page.

       L fontsize|- font|- justification label
              The  L  record  plots a (L)eft, (C)entered, or (R)ight-justified text string within a column using
              the specified font parameters. Use - to default to the size and type of FONT_LABEL.

       M slon|- slat length [+f][+l[label]][+u] [-Fparam] [ -Rw/e/s/n -Jparam ]
              Place a map scale in the legend. Specify slon slat, the point on the map where the  scale  applies
              (slon  is  only  meaningful  for  certain  oblique  projections. If not needed, you must specify -
              instead). Give length, the length of the scale in km (for other units append e (meter), f  (foot),
              M  (mile),  n  (nautical  mile),  or u (survey foot)). Append +f for a fancy map scale [Default is
              plain].  Append +l to the length to select the  default  label  which  equals  the  distance  unit
              (meter,  feet,  km,  miles, nautical miles, survey feet) and is justified on top of the scale [t].
              Change this by giving your own label (append +llabel). Change label alignment with +aalign (choose
              among  l(eft),  r(ight),  t(op)  ,  and  b(ottom)).   Apply  +u to append the unit to all distance
              annotations along the scale. If you want to place a map panel behind the scale, add a suitable  -F
              panel option (see psbasemap for details on panels as well as map scale modifiers).  All +modifiers
              must be appended to length to make a single string argument.  If the -R -J supplied to pslegend is
              different  than  the projection needed for the scale (or not given at all, e.g., with -Dx), supply
              the two optional -R -J settings as well.

       N [ncolumns or relwidth1 relwidth2 ... relwidthn]
              Change the number of columns in the legend [1]. This only affects the printing of symbols (S)  and
              labels (L). The number of columns stay in effect until N is used again.  To get columns of unequal
              width, instead provide the relative width of each column separated  by  whitespace.   The  sum  of
              these  widths  are  equated  to  the  legend width set via -D.  If no argument is given the we set
              n_columns to 1.

       P paragraph-mode-header-for-pstext
              Start a new text paragraph  by  specifying  all  the  parameters  needed  (see  pstext  -M  record
              description).  Note that pslegend knows what all those values should be, so normally you can leave
              the entire record (after P) blank or leave it out all together. If you need to set at least one of
              the  parameters directly, you must specify all and set the ones you want to leave at their default
              value to -.

       S [dx1 symbol size fill pen [ dx2 text ]]
              Plots the selected symbol with specified diameter, fill, and outline (see  psxy).  The  symbol  is
              centered  at  dx1  from the left margin of the column, with the optional explanatory text starting
              dx2 from the margin, printed with FONT_ANNOT_PRIMARY. Use  -  if  no  fill  or  outline  (pen)  is
              required.  Alternatively,  the  fill  may  be  specified indirectly via z=*value* and the color is
              assigned vi the CPT look-up (requires the A command).  When plotting just a symbol, without  text,
              dx2  and  text  can  be  omitted.  The dx1 value can also be given as a justification code L, C, R
              which justifies the symbol with respect to the current column.  If no arguments  are  given  to  S
              then we simply skip to the next column.  Three psxy symbols may take special modifiers: front (f),
              quoted line (q)  and vector (v).  You can append modifiers  to  the  symbol  and  affect  how  the
              fronts,  quoted  lines and vectors are presented (see psxy man page for modifiers).  pslegend will
              determine default settings for all modifiers and secondary arguments if not provided.  A few other
              symbols  (the  rectangles,  ellipse,  wedge, mathangle) may take more than a single argument size.
              Note that for a line segment you should use the horizontal dash symbol (-).  If just a single size
              if  given  then  pslegend  will  provide  reasonable arguments to plot the symbol  (See Defaults).
              Alternatively, combine the required arguments into a single, comma-separated string and  use  that
              as the symbol size (again, see psxy for details on the arguments needed).

       T paragraph-text
              One  or  more  of  these T records with paragraph-text printed with FONT_ANNOT_PRIMARY. To specify
              special positioning and typesetting arrangements, or to enter a paragraph break, use the  optional
              P record.

       V [offset] pen
              The  V  record  draws  a  vertical line between columns (if more than one) using the selected pen.
              Here, offset is analogous to the offset for the D records but in the vertical direction [0].   The
              first  time  V is used we remember the vertical position of the last D line, and the second time V
              is set we draw from that past location to the most recent location of the D line.  Thus, D must be
              used to mark the start and stop of a vertical line (so V must follow D).  If no horizontal line is
              desired simply give - as pen to D.

DEFAULTS

       When attributes are not provided, or extended symbol information (for symbols taking more  than  just  an
       overall size) are not given as comma-separated quantities, pslegend will provide the following defaults:

       Front:  Front  symbol  is  left-side  (here, that means upper side) box, with dimensions 30% of the given
       symbol size.

       Vector: Head size is 30% of given symbol size.

       Ellipse: Minor axis is 65% of major axis (the symbol size), with an azimuth of 0 degrees.

       Rectangle: Height is 65% of width (the symbol size).

       Rotated rectangle: Same, with a rotation of 30 degrees.

       Rounded rectangle: Same as rectangle, but with corner radius of 10% of width.

       Mathangle: Angles are -10 and 45 degrees, with arrow head size 30% of symbol size.

       Wedge: Angles are -30 and 30 degrees.

EXAMPLES

       To add an example of a legend to a Mercator plot (map.ps) with the given specifications, use

              gmt pslegend -R-10/10/-10/10 -JM6i -F+gazure1 -Dx0.5i/0.5i+w5i/3.3i+jBL+l1.2 \
              -C0.1i/0.1i -B5f1 << EOF >> map.ps
              # Legend test for pslegend
              # G is vertical gap, V is vertical line, N sets # of columns, D draws horizontal line.
              # H is header, L is label, S is symbol, T is paragraph text, M is map scale.
              #
              G -0.1i
              H 24 Times-Roman My Map Legend
              D 0.2i 1p
              N 2
              V 0 1p
              S 0.1i c 0.15i p300/12 0.25p 0.3i This circle is hachured
              S 0.1i e 0.15i yellow 0.25p 0.3i This ellipse is yellow
              S 0.1i w 0.15i green 0.25p 0.3i This wedge is green
              S 0.1i f0.1i+l+t 0.25i blue 0.25p 0.3i This is a fault
              S 0.1i - 0.15i - 0.25p,- 0.3i A dashed contour
              S 0.1i v0.1i+a40+e 0.25i magenta 0.25p 0.3i This is a vector
              S 0.1i i 0.15i cyan 0.25p 0.3i This triangle is boring
              V 0 1p
              D 0.2i 1p
              N 1
              M 5 5 600+u f
              G 0.05i
              I SOEST_logo.ras 3i CT
              G 0.05i
              B colors.cpt 0.2i 0.2i
              G 0.05i L 9 4 R Smith et al., @%5%J. Geophys. Res., 99@%%, 2000
              G 0.1i
              P
              T Let us just try some simple text that can go on a few lines.
              T There is no easy way to predetermine how many lines will be required,
              T so we may have to adjust the box height to get the right size box.
              EOF

NOTE ON LEGEND HEIGHT

       As -D suggests, leaving the height off forces a calculation of the expected  height.  This  is  an  exact
       calculation  except  in  the  case  of legends that place paragraph text. Here we simply do a first-order
       estimate of how many typeset lines might appear. Without  access  to  font  metrics  this  estimate  will
       occasionally be off by 1 line. If so, note the reported height (with -V) and specify a slightly larger or
       smaller height in -D.

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 pslegend do not need
       such duplication.

SEE ALSO

       gmt, gmt.conf, gmtcolors, gmtlogo psbasemap, pstext, psxy

       2015, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe