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  com-
       plex  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  regular
       (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 orig-
       inally 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  for-
       mat,  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 com-
       press a raster file which is already compressed (or  to	decompress  an
       already decompressed 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  interactively.   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 compressed/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	decom-
	      pressed.


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 val-
       ues 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 category
       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  elegant  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  pro-
       grams  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 created).

   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 cate-
       gory values 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)
