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



NNAAMMEE
       rr..ccoommpprreessss  - Compresses and decompresses raster files.
       _(_G_R_A_S_S _R_a_s_t_e_r _P_r_o_g_r_a_m_)

SSYYNNOOPPSSIISS
       rr..ccoommpprreessss
       rr..ccoommpprreessss hheellpp
       rr..ccoommpprreessss [--qquu] mmaapp==_n_a_m_e[,_n_a_m_e,...]

DDEESSCCRRIIPPTTIIOONN
       The  GRASS  program _r_._c_o_m_p_r_e_s_s can be used to compress and
       decompress raster map layers.


       During compression, this program  reformats  raster  files
       using  a  run-length-encoding (RLE) algorithm.  Raster map
       layers which contain  very  little  information	(such  as
       boundary, geology, soils and land use maps) can be greatly
       reduced in size. Some raster  map  layers  are  shrunk  to
       roughly	1%  of	their  original sizes.	Raster map layers
       containing complex images such as elevation and	photo  or
       satellite images may increase slightly in size. GRASS uses
       a new compressed format, and all new raster files are  now
       automatically  stored  in  compressed  form  (see  FORMATS
       below).	GRASS programs can read both compressed and regu-
       lar  (uncompressed)  file formats.  This allows the use of
       whichever raster data format consumes less space.


       As an example, the Spearfish data base  raster  map  layer
       _o_w_n_e_r  was originally a size of 26600 bytes.  After it was
       compressed, the raster file became only 1249 bytes  (25351
       bytes smaller).


       Raster  files  may be decompressed to return them to their
       original format, using the --uu  option  of  _r_._c_o_m_p_r_e_s_s.  If
       _r_._c_o_m_p_r_e_s_s  is  asked  to  compress a raster file which is
       already compressed (or to  decompress  an  already  decom-
       pressed file), it simply informs the user of this and asks
       the user if he wishes to perform the reverse operation.

PPRROOGGRRAAMM OOPPTTIIOONNSS
       _r_._c_o_m_p_r_e_s_s can be run either non-interactively or interac-
       tively.	In non-interactive use, the user must specify the
       name(s) of the raster map layer(s) to  be  compressed  (or
       decompressed)   on   the  command  line,  using	the  form
       mmaapp==_n_a_m_e[,_n_a_m_e,...] (where each _n_a_m_e  is  the  name  of	a
       raster  map  layer  to  be compressed or decompressed). To
       decompress a map, the user must include the --uu  option  on
       the  command line. If the --uu option is not included on the
       command line, _r_._c_o_m_p_r_e_s_s  will  attempt	to  compress  the
       named map layer(s).


       If the user simply types rr..ccoommpprreessss without specifying any
       map layer name(s) on the  command  line,  _r_._c_o_m_p_r_e_s_s  will
       prompt the user for the names of the map layers to be com-
       pressed/decompressed, and ask whether these maps are to be
       compressed  or decompressed. This program interface is the
       standard GRASS parser interface.

   FFllaaggss::
       --uu     If set, _r_._c_o_m_p_r_e_s_s converts a compressed map to its
	      _u_n_c_o_m_p_r_e_s_s_e_d  format.   If not set, _r_._c_o_m_p_r_e_s_s will
	      attempt to compress the named map layer(s).

       --qq     Run quietly. Suppress printing of percent  complete
	      messages to standard output.




   PPaarraammeetteerrss::
       mmaapp==_n_a_m_e[_n_a_m_e,....]
	      The name(s) of raster map layer(s) to be compressed
	      or decompressed.


FFOORRMMAATTSS
       Conceptually, a raster  data  file  consists  of  rows  of
       cells,  with each row containing the same number of cells.
       A cell consists of one or more bytes.  The number of bytes
       per  cell  depends  on  the  category values stored in the
       cell.  Category values in the range 0-255 require  1  byte
       per  cell,  while  category  values in the range 256-65535
       require 2 bytes, and category values in	the  range  above
       65535 require 3 (or more) bytes per cell.


       The ddeeccoommpprreesssseedd raster file format matches the conceptual
       format.	For example, a raster file with 1 byte cells that
       is  100	rows  with  200 cells per row, consists of 20,000
       bytes.  Running the UNIX command _l_s _-_l on this  file  will
       show  a	size  of 20,000.  If the cells were 2 byte cells,
       the file would require 40,000 bytes.  The map layer  cate-
       gory values start with the upper left corner cell followed
       by the other cells along the northern boundary.	The  byte
       following  the  last  byte  of that first row is the first
       cell of the second row of  category  values  (moving  from
       left  to right).  There are no end-of-row markers or other
       syncing codes in the raster  file.   A  cell  header  file
       (_c_e_l_l_h_d)  is  used  to  define how this string of bytes is
       broken up into rows of category values.


       The ccoommpprreesssseedd format is not so simple, but is quite  ele-
       gant  in  its design. It not only requires less disk space
       to store the raster data, but often can result  in  faster
       execution  of graphic and analysis programs since there is
       less disk I/O. There are two compressed formats: the  pre-
       version	3.0  format (which GRASS programs can read but no
       longer produce), and the  version  3.0  format  (which  is
       automatically  used  when  new  raster map layers are cre-
       ated).

   PPRREE--33..00 FFOORRMMAATT::
       First 3 bytes (chars) - These  are  a  special  code  that
       identifies the raster data as compressed.


       Address array (long) - array (size of the number of rows +
       1) of addresses pointing to the	internal  start  of  each
       row.  Because each row may be a different size, this array
       is necessary to provide a mapping of the data.


       Row by row, beginning at the northern edge of the data,	a
       series  of  byte groups describes the data.  The number of
       bytes in each group is the number of bytes per  cell  plus
       one.   The  first  byte of each group gives a count (up to
       255) of the number of cells that contain the category val-
       ues given by the remaining bytes of the group.

   PPOOSSTT--33..00 FFOORRMMAATT::
       The 3 byte code is not used.  Instead, a field in the cell
       header is used to indicate compressed format.


       The address array is the same.


       The RLE format is the same as the pre-3.0 RLE, except that
       each  row  of data is preceded by a single byte containing
       the number of bytes per cell for  the  row,  and  if  run-
       length-encoding	the row would not require less space than
       non-run-length-encoding, then the row is not encoded.


       These  improvements  give  better  compression  than   the
       pre-3.0	format	in  99%  of  the raster data layers.  The
       kinds of raster data layers which get bigger are those  in
       which  each  row  would	be  larger  if	compressed (e.g.,
       imagery band files).  But even in  this	case  the  raster
       data layer would only be larger by the size of the address
       array and the single byte preceding each row.

SSEEEE AALLSSOO
       _r_._s_u_p_p_o_r_t
       _p_a_r_s_e_r

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.compress(1)
