r.reclass(1)	       Grass User's Manual	     r.reclass(1)



NNAAMMEE
       rr..rreeccllaassss  - Creates a new map layer whose category values
       are based upon the user's reclassification  of  categories
       in an existing raster map layer.
       _(_G_R_A_S_S _R_a_s_t_e_r _P_r_o_g_r_a_m_)

SSYYNNOOPPSSIISS
       rr..rreeccllaassss
       rr..rreeccllaassss hheellpp
       rr..rreeccllaassss iinnppuutt==_n_a_m_e oouuttppuutt==_n_a_m_e [TTIITTLLEE==_n_a_m_e]

DDEESSCCRRIIPPTTIIOONN
       _r_._r_e_c_l_a_s_s  creates  an  _o_u_t_p_u_t map layer based on an _i_n_p_u_t
       raster map layer.  The output map layer will be a  reclas-
       sification  of  the input map layer based on reclass rules
       input to _r_._r_e_c_l_a_s_s, and can be treated in  much	the  same
       way that raster files are treated.  A _T_I_T_L_E for the output
       map layer may be (optionally) specified by the user.


       The reclass rules are read from standard input (i.e., from
       the  keyboard,  redirected  from  a file, or piped through
       another program).


       The program will be  run  non-interactively  if	the  user
       specifies the _n_a_m_e of the raster map layer to be reclassi-
       fied, the _n_a_m_e of an output layer to hold  reclass  rules,
       and (optionally) the _n_a_m_e of a TITLE for the output map:


       rr..rreeccllaassss iinnppuutt==_n_a_m_e oouuttppuutt==_n_a_m_e [TTIITTLLEE==_n_a_m_e]



       After  the user types in the above information on the com-
       mand line, the program will (silently) prompt the user for
       reclass	rules  to be applied to the input map layer cate-
       gories.	The form of these rules is described  in  further
       detail  in  the	sections  on  non-interactive program use
       reclass rules and examples, below.


       Alternately, the user can simply  type  rr..rreeccllaassss  on  the
       command	line,  without	program arguments.  In this case,
       the user will be prompted for all needed inputs.


       Before using _r_._r_e_c_l_a_s_s one must know the following:

	      The new categories desired;  and, which  old  cate-
	      gories fit into which new categories.

	      The names of the new categories.


IINNTTEERRAACCTTIIVVEE PPRROOGGRRAAMM UUSSEE:: EEXXAAMMPPLLEE
       Suppose	we want to reclassify the raster map layer _r_o_a_d_s,
       consisting of five categories, into the	three  new  cate-
       gories:	 paved roads, unpaved roads, and railroad tracks.
       The user is asked whether  the  reclass	table  is  to  be
       established  with  each category value initially set to 0,
       or with each category  value  initially	set  to  its  own
       value.  A screen like that shown below then appears, list-
       ing the categories of the _r_o_a_d_s raster  map  layer  to  be
       reclassified  and  prompting the user for the new category
       values to be assigned them.



	    ENTER NEW CATEGORY NUMBERS FOR THESE CATEGORIES

	    OLD CATEGORY NAME	    OLD     NEW
				    NUM     NUM
	    no data		    0	   0___
	    Hard Surface, 2 lanes    1	    0___
	    Loose Surface, 1 lane    2	    0___
	    Improved Dirt	     3	    0___
	    Unimproved Dirt Trail    4	    0___
	    Railroad, single track   5	    0___

	    AFTER COMPLETING ALL ANSWERS, HIT <ESC> TO CONTINUE
			 (OR <Ctrl-C> TO CANCEL)

       In the following screen the new category values have  been
       entered	beside the appropriate old category names.  Cells
       assigned category values 2, 3, and 4 in the old raster map
       layer  are  now	assigned  the new category value 2 in the
       reclassed map; cell data  formerly  assigned  to  category
       value 5 in the old raster map map are now assigned the new
       category value 3 in the reclassed map.

	    ENTER NEW CATEGORY NUMBERS FOR THESE CATEGORIES


	    OLD CATEGORY NAME	      OLD     NEW
				     NUM     NUM
	    no data		      0      0___
	    Hard Surface, 2 lanes     1      1___
	    Loose Surface, 1 lane     2      2___
	    Improved Dirt	  3	 2___
	    Unimproved Dirt Trail     4      2___
	    Railroad, single track    5      3___

	    AFTER COMPLETING ALL ANSWERS, HIT <ESC> TO CONTINUE
			 (OR <Ctrl-C> TO CANCEL)

       Hitting the  escape  key   will	bring  up  the	following
       screen,	which  prompts	the user to enter a new TITLE and
       category label for the newly rreeccllaasssseedd categories.

	    ENTER NEW CATEGORY NAMES FOR THESE CATEGORIES

	    TITLE:  Roads Reclassified
		   CAT	       NEW CATEGORY NAME
		   NUM
		    0	       no data
		    1	       Paved Roads
		    2	       Unpaved Roads
		    3	       Railroad, single track

	      AFTER COMPLETING ALL ANSWERS, HIT <ESC> TO CONTINUE
			    (OR <Ctrl-C> TO CANCEL)

       Based  upon  the  information  supplied by the user in the
       above sample screens, the new output map, supporting cate-
       gory, color, history, and header files are created.

NNOONN--IINNTTEERRAACCTTIIVVEE PPRROOGGRRAAMM UUSSEE:: RREECCLLAASSSS RRUULLEESS
       In non-interactive program use, the names of an input map,
       output map, and output map TITLE are given on the  command
       line.   However,  the  reclass  rules  are still read from
       standard input (i.e., from the keyboard, redirected from a
       file, or piped through another program).


       Once  the  user	has  specified an input raster map layer,
       output map layer name, and (optionally) output  map  layer
       TITLE   by   typing   rr..rreeccllaassss	 iinnppuutt==_n_a_m_e   oouuttppuutt==_n_a_m_e
       [TTIITTLLEE==_n_a_m_e]

       Each  line  of  input  must  have  the  following  format:
       iinnppuutt__ccaatteeggoorriieess==_o_u_t_p_u_t___c_a_t_e_g_o_r_y  [_l_a_b_e_l]



       where  the  input lines specify the category values in the
       input raster map layer to be reclassified to the new  _o_u_t_-
       _p_u_t___c_a_t_e_g_o_r_y  category value.  Specification of a _l_a_b_e_l to
       be associated with the new output map  layer  category  is
       optional.   If  specified,  it is recorded as the category
       label for the new category value.  The  equal  sign  =  is
       required.   The	_i_n_p_u_t___c_a_t_e_g_o_r_y_(_i_e_s_) may consist of single
       category values or a range of such values  in  the  format
       "_l_o_w thru _h_i_g_h." The word "thru" must be present.


       To  include  all (remaining) values the asterix "*" can be
       used. This rule has to be set as  last  rule.  No  further
       rules are accepted after setting this rule.


       No data have to be spcified with NULL.


       A  line containing only the word eenndd terminates the input.

NNOONN--IINNTTEERRAACCTTIIVVEE PPRROOGGRRAAMM UUSSEE:: EEXXAAMMPPLLEESS
       The following examples may help clarify the reclass rules.



	1. This example reclassifies categories 1, 2 and 3 in the
       input raster
	      map layer "roads" to category 1 with category label
	      "good quality" in the output map layer, and reclas-
	      sifies input raster map layer categories 4 and 5 to
	      category 2 with the label  "poor	quality"  in  the
	      output map layer.

		  1 2 3   = 1	 good quality
		  4 5	  = 2	 poor quality



       2.  This example reclassifies input raster map layer cate-
       gories 1 thru 10 to output map layer category 1, input map
       layer  categories  11 thru 20 to output map layer category
       2, and input map layer categories 21 thru 30 to output map
       layer category 3, all without labels. The range from 30 to
       40 is reclassified as NULL.

	    1 thru 10 = 1
	   11 thru 20 = 2
	   21 thru 30 = 3
	   30 thru 40  = NULL

       3. Subsequent rules override previous  rules.   Therefore,
       the below example reclassifies input raster map layer cat-
       egories 1 thru 19 and 51 thru 100 to  category  1  in  the
       output  map  layer,  input  raster map layer categories 20
       thru 24 and 26 thru 50 to the output map layer category 2,
       and input raster map layer category 25 to the output cate-
       gory 3.

	    1 thru 100	   = 1	  poor quality
	   20 thru 50 = 2    medium quality
	   25		 = 3	good quality

       4. This example reclassifies categories 1, 3 and 5 in  the
       input  raster  map layer to category 1 with category label
       "poor quality" in the output map layer,	and  reclassifies
       input  raster map layer categories 2, 4, and 6 to category
       2 with the label "good quality" in the output  map  layer.
       All other values are reclassified to NULL.

	   1 3 5   = 1	  poor quality
	   2 4 6   = 2	  good quality
	   *	   = NULL



       5. The previous example could also have been entered as:

	    1 thru 19  51 thru 100   = 1    poor quality
	   20 thru 24  26 thru 50    = 2    medium quality
	   25			= 3    good quality

       or as:

	    1 thru 19  = 1    poor quality
	   51 thru 100	    = 1
	   20 thru 24  = 2
	   26 thru 50  = 2    medium quality
	   25	       = 3    good quality



       The  final  example  was  given to show how the labels are
       handled.  If a new category value appears in more than one
       rule  (as  is  the case with new category values 1 and 2),
       the last label which was specified becomes the  label  for
       that  category.	 In  this  case  the  labels are assigned
       exactly as in the two previous examples.

NNOOTTEESS
       In fact, the _r_._r_e_c_l_a_s_s program does _n_o_t generate  any  new
       raster  map layers (in the interests of disk space conser-
       vation).  Instead, a rreeccllaassss ttaabbllee is stored which will be
       used to reclassify the original raster map layer each time
       the new (reclassed) map name is requested.  As far as  the
       user  (and  programmer)	is concerned, that raster map has
       been created.  Also note that although the user can gener-
       ate  a  _r_._r_e_c_l_a_s_s  map which is based on another _r_._r_e_c_l_a_s_s
       map, the new _r_._r_e_c_l_a_s_s map map will be stored in GRASS  as
       a  reclass  of  the _o_r_i_g_i_n_a_l raster map on which the first
       reclassed map was based.  Therefore,  while  GRASS  allows
       the  user to provide _r_._r_e_c_l_a_s_s map layer information which
       is based on an already reclassified map	(for  the  user's
       convenience), no _r_._r_e_c_l_a_s_s map layer (i.e., _r_e_c_l_a_s_s _t_a_b_l_e)
       will ever be _s_t_o_r_e_d as a _r_._r_e_c_l_a_s_s of a _r_._r_e_c_l_a_s_s.


       To convert a reclass map to a regular  raster  map  layer,
       set  your geographic region settings to match the settings
       in the header for the reclass map  (an  ASCII  file  found
       under   the  _c_e_l_l_h_d  directory,	or  viewable  by  running
       _r_._r_e_s_a_m_p_l_e.


       _r_._m_a_p_c_a_l_c can also be used to convert a reclass map  to	a
       regular raster map layer:


       rr..mmaappccaallcc rraasstteerr__mmaapp==reclass_map



       where _r_a_s_t_e_r___m_a_p is the name to be given to the new raster
       map, and _r_e_c_l_a_s_s___m_a_p is an existing reclass map.

BBEEWWAARREE
       Because _r_._r_e_c_l_a_s_s generates a table referencing some orig-
       inal  raster  map  layer  rather than creating a reclassed
       raster map layer, a _r_._r_e_c_l_a_s_s map layer will no longer  be
       accessible  if the original raster map layer upon which it
       was based is later removed.


       A _r_._r_e_c_l_a_s_s map is not a true raster map  layer.   Rather,
       it  is  a table of reclassification values which reference
       the input raster map layer.  Therefore, users who wish  to
       retain reclassified map layers must also save the original
       input raster map layers from which  they  were  generated.
       Alternatively r.recode can be used.


       Category values which are not explicitly reclassified to a
       new value by the user will be reclassified to NULL.

SSEEEE AALLSSOO
       _r_._r_e_s_a_m_p_l_e

       _r_._r_e_s_c_a_l_e, _r_._r_e_c_o_d_e

AAUUTTHHOORRSS
       James Westervelt,
       Michael Shapiro,
       U.S.Army Construction Engineering Research Laboratory

       _L_a_s_t _c_h_a_n_g_e_d_: _$_D_a_t_e_: _2_0_0_2_/_0_1_/_2_5 _0_5_:_4_5_:_3_4 _$



GRASS 5.0					     r.reclass(1)
