d.legend(1)		      Grass User's Manual		   d.legend(1)



NNAAMMEE
       dd..lleeggeenndd - Displays a legend for a raster map layer in the active frame
       on the graphics monitor.
       _(_G_R_A_S_S _D_i_s_p_l_a_y _P_r_o_g_r_a_m_)

SSYYNNOOPPSSIISS
       dd..lleeggeenndd
       dd..lleeggeenndd hheellpp
       dd..lleeggeenndd [--vvccnnssmmff]  mmaapp==_n_a_m_e  [ccoolloorr==_n_a_m_e]  [lliinneess==_v_a_l_u_e]  [tthhiinn==_v_a_l_u_e]
       [llaabbeellnnuumm==_v_a_l_u_e] [aatt==_b_o_t_t_o_m_,_t_o_p_,_l_e_f_t_,_r_i_g_h_t] [rraannggee==_m_i_n_,_m_a_x]

DDEESSCCRRIIPPTTIIOONN
       _d_._l_e_g_e_n_d displays a legend for a user-specified raster map layer in the
       active frame on the graphics monitor.


       The user can run _d_._l_e_g_e_n_d either  non-interactively  or	interactively.
       If  the	user  specifies  the name of a raster mmaapp layer on the command
       line, the program will  run  non-interactively.	 Default  legend  text
       ccoolloorr  and position will be used unless the user specifies other values
       on the command line.


       Alternately, the user can simply type dd..lleeggeenndd on the command line;  in
       this  case, the program will prompt the user for parameter values using
       the standard GRASS parser interface.



OOPPTTIIOONNSS
   FFllaaggss::
       --vv     Do not show category labels

       --cc     Do not show category numbers

       --nn     Skip categories with no label (ignored for floating point maps)

       --ss     Draw smooth gradient (forced automatically  for  floating  point
	      rasters)

       --mm     Use mouse to size & place legend

       --ff     Flip legend vertically or horizontally




   PPaarraammeetteerrss::
       mmaapp==_n_a_m_e
	      Name of raster map.

       ccoolloorr==_n_a_m_e
	      Sets the legend's text color.
	      Options: red, orange, yellow, green, blue, indigo, white, black,
	      brown, magenta, aqua, gray, grey
	      Default: white

       lliinneess==_v_a_l_u_e
	      Number of lines in the legend (useful for truncating  long  leg-
	      ends)
	      Options: 0-1000
	      Default: all

       tthhiinn==_v_a_l_u_e
	      Thinning factor (thin=10 gives cats 0,10,20...)
	      Options: 0-1000
	      Default: 1

       llaabbeellnnuumm==_v_a_l_u_e
	      Number of text labels for smooth gradient legend
	      Options: 2-100
	      Default: 5

       aatt==_b_o_t_t_o_m_,_t_o_p_,_l_e_f_t_,_r_i_g_h_t
	      Placement coordinates, as 0-100% of graphics frame height/width.
	      0,0 is lower left.
	      Options: 0-100
	      Default: automatically placed and scaled

       rraannggee==_m_i_n_,_m_a_x
	      Category range
	      Default: all


NNOOTTEESS
       The legend's default size is based on  the  dimensions  of  the	active
       frame,  specifically its height.  _d_._l_e_g_e_n_d will only obscure those por-
       tions of the active frame that directly underlie the legend.


       When using the mouse or aatt to size & place  the	legend,  if  the  user
       makes  a  horizontal box the values run from left to right and no cate-
       gory values are printed (you may want to use _d_._l_a_b_e_l
	for that). A horizontal legend is created if the box is wider than  it
       is tall.


       Raster  maps based on floating point values will display smoothed, from
       greatest to smallest value, while categorial raster maps  will  display
       in  order,  from  top to bottom. If the box is defined with inverted y-
       values or an inverted rraannggee, the legend	will  automatically  flip.  If
       this  is  not  the  desired  result, the --ff flag may be used to flip it
       back.


       If the user attempts to display a very  long  legend  in  a  relatively
       short display frame, the legend may appear in unreadably small text, or
       even revert to a smooth gradient legend. Use the  lliinneess,  tthhiinn,	rraannggee,
       and/or  --nn  options to reduce the number of categories to be displayed,
       or the --ss flag to force a smooth gradient legend.


       The lliinneess option will  display  the  first  number  of  categories,  as
       defined	by  _v_a_l_u_e,  contained in the raster map. When used with the --nn
       flag, it takes on a new meaning: "up to category  #".  When  used  with
       both tthhiinn and the --nn flag, its meaning becomes more obscure. When using
       lliinneess, auto-scaled text similar to "4 of 16 categories" will be	placed
       at the bottom of the legend.


       The  tthhiinn  option  sets the thinning factor. For raster maps with a 0th
       category, tthhiinn==_1_0 gives cats [0,10,20,...]. For raster maps starting at
       category 1, tthhiinn==_1_0 gives cats [1,11,21,...].


       The  rraannggee  option  lets  the user define the minimum and maximum cate-
       gories to be used in the legend. It may also be used to define the lim-
       its of a smooth gradient legend created from a raster containing float-
       ing point values. Note the color scale will remain faithful to the cat-
       egory values as defined with _r_._c_o_l_o_r_s.


       The flag --nn is useful for categorial maps, as it suppresses the drawing
       of non-existing categories (otherwise the full range is shown).


       Vertical legends produced with _d_._l_e_g_e_n_d will produce text labels to the
       right  of  the  legend box. This text will be auto-scaled to fit within
       the frame, reducing the size of the legend if necessary. Legends  posi-
       tioned  with  the mouse or with the aatt option will not auto-scale text,
       in order to provide more control to  the  user.	Smaller  text  may  be
       obtained  in this case by reducing the height of the box. The --cc and --vv
       flags may be used to suppress  the  display  of	category  numbers  and
       labels  respectively,  or used together to suppress all text of catego-
       rial raster maps.


       The text produced from floating-point raster  maps  will  automatically
       create  output with a meaningful number of significant digits. For very
       small values, numbers will be expressed in  scientific  notation,  e.g.
       "1.7e-9".


       Note  that  old	scripts which relied on setting lliinneess greater than the
       number of categories to scale the legend  may  no  longer  produce  the
       desired	output,  although  the auto-scaling should still produce some-
       thing that looks good in this case.

TTOODDOO
       - Add uussee option for legends of discrete category numbers/values  only.

       - Text labels for horizontal legends.


SSEEEE AALLSSOO
       _d_._c_o_l_o_r_m_o_d_e

       _d_._c_o_l_o_r_s

       _d_._c_o_l_o_r_t_a_b_l_e

       _d_._d_i_s_p_l_a_y

       _d_._e_r_a_s_e

       _d_._g_r_i_d

       _d_._r_a_s_t

       _d_._r_a_s_t_._l_a_b_e_l_s

       _d_._r_a_s_t_._l_e_g

       _d_._v_e_c_t

       _d_._w_h_a_t_._r_a_s_t

       _r_._r_e_c_l_a_s_s
       _p_a_r_s_e_r

AAUUTTHHOORRSS
       Bill Brown, U.S. Army Construction Engineering Research Laboratories

       Late  2002:  Rewrite  of much of the code. Hamish Bowman, Otago Univer-
       sity, New Zealand

       Additional improvements from various authors

       _L_a_s_t _c_h_a_n_g_e_d_: _$_D_a_t_e_: _2_0_0_3_/_0_3_/_1_6 _1_2_:_2_5_:_1_9 _$



GRASS 5.0							   d.legend(1)
