Ubuntu Manpage: r.compress - Compresses and decompresses raster maps.

NAME

       r.compress  - Compresses and decompresses raster maps.

KEYWORDS

       raster, map management

SYNOPSIS

       r.compress
       r.compress help
       r.compress [-uq] map=string[,string,...]  [--verbose]  [--quiet]

   Flags:
       -u
           Uncompress the map

       -q
           Run quietly

       --verbose
           Verbose module output

       --quiet
           Quiet module output

   Parameters:
       map=string[,string,...]
           Name of existing raster map(s)

DESCRIPTION

       The GRASS program r.compress can be used to compress and decompress raster map layers.

       During  compression,  this  program  reformats  raster  maps 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.   All  new raster maps 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 owner was originally a size of 26600 bytes.
       After it was compressed, the raster map became only 1249 bytes (25351 bytes smaller).

       Raster files may be decompressed to  return  them  to  their  original  format,  using  the  -u  flag  of
       r.compress. If r.compress is asked to compress a raster map which is already compressed (or to decompress
       an  already  decompressed  raster  map), it simply informs the user the map is already (de)compressed and
       exits.

NOTES

r.compress 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 map=name[,name,...] (where each name is the name of a raster map layer to be compressed or
decompressed). The default behavior is to compress the named map(s).

FORMATS
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 decompressed raster map format matches the conceptual format. For example, a raster map with 1 byte
cells that is 100 rows with 200 cells per row, consists of 20,000 bytes. Running the UNIX command ls -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 map. A cell header file (cellhd) is used to define how this string of bytes
is broken up into rows of category values.

The compressed 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
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 created).

RLE compression versus zlib compression: if the environment variable GRASS_INT_ZLIB exists, new raster
maps will be compressed using zlib instead of RLE compression. In the cellhd file, the value for
"compressed" is 1 for RLE and 2 for zlib.
Obviously, decompression is controlled by the raster's "compressed" header value, not the environment
variable.

PRE-3.0 FORMAT:
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 values given by the remaining
bytes of the group.

POST-3.0 FORMAT:
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.

AUTHORS