## NAME

           pslegend - To plot a map legend

## SYNOPSIS

           pslegend     textfile    -D[x]lon/lat/width/height/just    -Jparameters
           -Rwest/east/south/north[r] [ -Cdx/dy ] [ -F ] [  -Gfill  ]  [  -K  ]  [
           -Lspacing  ] [ -O ] [ -P ] [ -S[script] ] [ -U[/dx/dy/][label] ] [ -V ]
           [ -Xx-shift ] [ -Yy-shift ]

## DESCRIPTION

           pslegend will make legends that can be overlaid on maps. It reads  spe-
           cific legend-related information from an input file [or stdin]. Because
           all the elements of the legend can already be created with other  tools
           (psxy,  pstext)  we use those tools by creating a batch job of commands
           that are executed to make the final PostScript overlay. Because of this
           process,  the option exists to just output the script which can then be
           fine-tuned manually.

           textfile
                  This file contains instruction 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. Ten different record  types
                  are  recognized,  and  the  syntax for each of these records are
                  presented below:

           # Comment records
                  Records starting with # and blank lines are skipped.

           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,
                  or a named color.

           D offset pen
                  The D record results in a horizontal line across the legend. The
                  line  starts and stops offset units from the frame sides, and is
                  drawn using the specified pen.

           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.

           H fontsize font Header
                  The H record plots a centered text string  using  the  specified
                  font parameters.

           I image.ras width justification
                  Place a Sun 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 using the specified font parameters.

           M slon|- slat length f|p [ -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),  length,  the length of the scale in km (append m or n
                  for miles or nautical miles), and f|p for fancy or plain  scale.
                  If  the -R -J supplied to pslegend is different than the projec-
                  tion needed for the scale, supply the optional -R -J settings as
                  well.  Note  that  length  can  have :label:just appended, where
                  label replaces the default label (unless - is  given)  and  just
                  (l|r|t|b) dictates where the label is placed [Default is t]. Use
                  u to treat the label as distance units appended to each  annota-
                  tion.

           N ncolums
                  Change the number of columns in the legend [1].

           S dx1 symbol size fill pen dx2 text
                  Plots  the  selected  symbol with specified size, fill, and out-
                  line. The symbol is centered at dx1 from the left margin of  the
                  column,  with the explanatory text starting dx2 from the margin.
                  Use - if no fill is required. Two psxy  symbols  front  (f)  and
                  vector  (v)  require  special  attention.  You  must prepend the
                  length of the desired item to the rest of the  symbol  argument;
                  this  will be used internally to set the correct fault or vector
                  length and will be stripped  before  passing  the  arguments  to
                  psxy.

           > <paragraph mode header for pstext>
                  Start  a  new  text  paragraph  by specifying all the parameters
                  needed (see pstext -M description).  Note  that  pslegend  knows
                  what  all  those values should be, so normally you can leave the
                  entire record (after >) blank.  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 -.

           T paragraph-text
                  One or more of these T records with text must follow after the >
                  record.

           V offset pen
                  The V record draws a vertical line between columns (if more than
                  one) using the selected pen. offset is analogous to  the  offset
                  for the D records but in the vertical direction.

           -D     Positions  the  legend  and  specifies  its  size. The just is a
                  2-char justification string (see pstext) that relates the  given
                  position  to  a point on the rectangular legend box. If you want
                  to specify the position in projected units (i.e., inches or cm),
                  use -Dx.

           -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 .gmtdefaults4, but this
                  can be overridden on the command line by appending c, i, or m to
                  the  scale/width  value.   For map height, max dimension, or min
                  dimension, append h, +, or - to the width, respectively.

                  CYLINDRICAL PROJECTIONS:

                  -Jclon0/lat0/scale (Cassini)
                  -Jjlon0/scale (Miller)
                  -Jmscale (Mercator - Greenwich and Equator as origin)
                  -Jmlon0/lat0/scale (Mercator - Give meridian and standard paral-
                  lel)
                  -Joalon0/lat0/azimuth/scale   (Oblique   Mercator  -  point  and
                  azimuth)
                  -Joblon0/lat0/lon1/lat1/scale (Oblique Mercator - two points)
                  -Joclon0/lat0/lonp/latp/scale  (Oblique  Mercator  -  point  and
                  pole)
                  -Jqlon0/scale   (Equidistant   Cylindrical   Projection   (Plate
                  Carree))
                  -Jtlon0/scale (TM - Transverse Mercator, with Equator as y = 0)
                  -Jtlon0/lat0/scale (TM - Transverse Mercator, set origin)
                  -Juzone/scale (UTM - Universal Transverse Mercator)
                  -Jylon0/lats/scale (Basic Cylindrical Projection)

                  AZIMUTHAL PROJECTIONS:

                  -Jalon0/lat0/scale (Lambert).
                  -Jelon0/lat0/scale (Equidistant).
                  -Jflon0/lat0/horizon/scale (Gnomonic).
                  -Jglon0/lat0/scale (Orthographic).
                  -Jslon0/lat0/[slat/]scale (General Stereographic)

                  CONIC PROJECTIONS:

                  -Jblon0/lat0/lat1/lat2/scale (Albers)
                  -Jdlon0/lat0/lat1/lat2/scale (Equidistant)
                  -Jllon0/lat0/lat1/lat2/scale (Lambert)

                  MISCELLANEOUS PROJECTIONS:

                  -Jhlon0/scale (Hammer)
                  -Jilon0/scale (Sinusoidal)
                  -Jk[f|s]lon0/scale (Eckert IV (f) and VI (s))
                  -Jnlon0/scale (Robinson)
                  -Jrlon0/scale (Winkel Tripel)
                  -Jvlon0/scale (Van der Grinten)
                  -Jwlon0/scale (Mollweide)

                  NON-GEOGRAPHICAL PROJECTIONS:

                  -Jp[a]scale[/origin] (polar (theta,r)  coordinates,  optional  a
                  for azimuths and offset theta [0])
                  -Jxx-scale[l|ppow][/y-scale[l|ppow]][d]  (Linear, log, and power
                  scaling)
                  More details can be found in the psbasemap man pages.

           -R     xmin, xmax, ymin, and ymax specify the Region of  interest.  For
                  geographic  regions,  these  limits  correspond  to  west, east,
                  south, and north and you may specify them in decimal degrees  or
                  in  [+-]dd:mm[:ss.xxx][W|E|S|N]  format.  Append r if lower left
                  and upper right map coordinates are given instead of  wesn.  The
                  two  shorthands  -Rg  -Rd  stand  for  global  domain  (0/360 or
                  -180/+180 in longitude respectively, with -90/+90 in  latitude).
                  For  calendar time coordinates you may either give relative time
                  (relative  to  the  selected  TIME_EPOCH  and  in  the  selected
                  TIME_UNIT;  append  t  to  -JX|x),  or absolute time of the form
                  [date]T[clock] (append T to -JX|x). At least  one  of  date  and
                  clock must be present; the T is always required. The date string
                  must be of the form [-]yyyy[-mm[-dd]]  (Gregorian  calendar)  or
                  yyyy[-Www[-d]]  (ISO week calendar), while the clock string must
                  be of the form hh:mm:ss[.xxx]. The use of delimiters  and  their
                  type  and  positions must be as indicated (however, input/output
                  and plotting formats are flexible).

## OPTIONS

           No space between the option flag and the associated arguments.

           -C     Sets the clearance between the legend  frame  and  the  internal
                  items [0.15c/0.15c (or 0.05i/0.05i)].

           -F     Draws a border around the legend using FRAME_PEN.

           -G     Specify the shade (0-255) or color (r/g/b, each in 0-255, h/s/v,
                  with h in 0-360, s, and v in 0-1, and set COLOR_MODEL = hsv,  or
                  c/m/y/k,  each  in 0-100 %).  Alternatively, specify -Gpdpi/pat-
                  tern, where pattern gives the number  of  the  built-in  pattern
                  (1-90)  or  the name of a Sun 1-, 8-, or 24-bit raster file. The
                  dpi sets the resolution of the image. For 1-bit rasters: use -GP
                  for  inverse video, or append :Fr/g/b[B[r/g/b]] to specify fore-
                  and background colors (use r/g/b = - for transparency).  See GMT
                  Cookbook  &  Technical  Reference  Appendix E for information on
                  individual patterns.

           -K     More PostScript code will be appended later [Default  terminates
                  the plot system].

           -L     Sets  the  linespacing factor in units of the current annotation
                  font size [1.1].

           -O     Selects Overlay plot mode [Default initializes a new  plot  sys-
                  tem].

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

           -S     Instead of writing the PostScript plot [Default], output the GMT
                  script used to make the legend to standard output, or optionally
                  to the file script.

           -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"].

           -X -Y  Shift origin of plot by (x-shift,y-shift).  Prepend a for  abso-
                  lute  coordinates; the default (r) will reset plot origin.  Give
                  c to center plot using current page size.

## EXAMPLES

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

           pslegend -R -JM -O -G255 << EOF >> map.ps
           G -0.15i
           H 24 Times-Roman My Map Legend
           G 0.05i
           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 t 0.15i 255/255/0 0.25p 0.3i This triangle is yellow
           S 0.1i h 0.15i 0/255/0 0.25p 0.3i This hexagon is green
           S 0.1i d 0.15i 0/0/255 0.25p 0.3i This diamond is blue
           S 0.1i - 0.15i - 0.25tap 0.3i A contour
           V 0 1p
           D 0.2i 1p
           M 5 5 500:km:u f
           I SOEST_logo.ras 3 CT
           L 9 4 R Smith et al., @%5%J. Geophys. Res., 99@%%, 2000
           G 0.15i
           >
           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 need to adjust the box height to get the right size.

## SEE ALSO

           gmt(l), psbasemap(l), pstext(l), psxy(l)

    GMT4.0                            1 Oct 2004                       PSLEGEND(l)