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)

Man(1) output converted with man2html