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

NAME

       r.compress  - Compresses and decompresses raster maps.

KEYWORDS

       raster, map management, compression

SYNOPSIS

       r.compress
       r.compress --help
       r.compress [-upg] map=name[,name,...]  [--help]  [--verbose]  [--quiet]  [--ui]

   Flags:
       -u
           Uncompress the map

       -p
           Print compression information and data type of input map(s)

       -g
           Print compression information in shell script style

       --help
           Print usage summary

       --verbose
           Verbose module output

       --quiet
           Quiet module output

       --ui
           Force launching GUI dialog

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

DESCRIPTION

r.compress can be used to compress or decompress raster maps. Additionally, it prints
information about the compression method and data type of the input raster map(s).

All raster maps (those imported for the first time and those newly generated) are
compressed by default using the ZLIB compression method (see below). Related no data files
(i.e.: NULL files), if present, are not compressed by default unless a specific
environment variable is set (GRASS_COMPRESS_NULLS, see below).

During compression or re-compression, r.compress compresses raster maps using the method
specified by means of the environment variable GRASS_COMPRESSOR. The default compression
method is ZLIB’s "deflate" algorithm (LZ77-based). Raster maps that contain very little
information (such as boundary, geology, soils and land use maps) can be greatly reduced in
size. Some raster maps are shrunk to roughly 1% of their original sizes. All newly
generated raster maps are automatically stored as compressed data with varying methods
depending on the raster format (i.e., CELL: integer; FCELL: single precision; DCELL:
double precision; see below). All GRASS GIS modules are able to read both compressed and
uncompressed raster maps.

Raster maps that are already compressed might be compressed again, either by setting a
different method with GRASS_COMPRESSOR (supported methods: RLE, ZLIB, LZ4, BZIP2) or, for
the case of ZLIB compression, by changing the compression level with the environment
variable GRASS_ZLIB_LEVEL.

Compressed raster maps may be decompressed using r.compress to return them to their
original format, using the -u flag. If a raster map was already decompressed and the -u
flag is set, the module simply informs the user that the map is already decompressed and
exits.

Information about the compression method and data type of the input raster map(s) can be
printed in shell style with the -g flag. In this case, the module prints to stdout one
line per input map with the fields "input map name", "data type", "name of data
compression method", "NULL file compression" separated by the pipe character. NULL file
compression is indicated with "YES" or "NO".

TERMINOLOGY
• INTEGER map (CELL data type): a raster map of INTEGER type (whole numbers only)

• FLOAT map (FCELL data type): a raster map of FLOAT type (4 bytes, 7-9 digits
precision)

• DOUBLE map (DCELL data type): a raster map of DOUBLE type (8 bytes, 15-17 digits
precision)

• NULL: represents "no data" in raster maps; to be distinguished from 0 (zero) data
value

OVERVIEW OF AVAILABLE COMPRESSION ALGORITHMS
The following compression methods are available (set by export GRASS_COMPRESSOR=method):

• NONE (uncompressed)

• RLE (generic Run-Length Encoding of single bytes; deprecated)

• ZLIB (DEFLATE, good speed and compression - default compression)

• with zlib compression levels (export GRASS_ZLIB_LEVEL=X): -1..9 (-1 is default
which corresponds to ZLIB level 6)

• note: export GRASS_ZLIB_LEVEL=0 is equal to copying the data as-is from source
to destination

• LZ4 (fastest, low compression)

• BZIP2 (slowest, high compression)
Important: the NULL file compression must be explicitly turned on with export
GRASS_COMPRESS_NULLS=1 - such raster maps can then only be opened with GRASS GIS 7.2.0 or
later. NULL file compression can be managed with r.null -z. The NULL file compression is
using the LZ4 method as being the best compromise between speed and compression rate.

COMPRESSION ALGORITHM DETAILS
All GRASS GIS raster map types are by default ZLIB compressed, i.e. using ZLIB’s deflate
algorithm. Through the environment variable GRASS_COMPRESSOR the compression method can be
set to RLE, ZLIB, LZ4, or BZIP2.

Integer (CELL type) raster maps can be compressed with RLE if the environment variable
GRASS_INT_ZLIB exists and is set to value 0. However, this is not recommended.

Floating point (FCELL, DCELL) raster maps never use RLE compression; they are either
compressed with ZLIB, LZ4, BZIP2 or are uncompressed.

RLE
DEPRECATED Run-Length Encoding, poor compression ratio but fast. It is kept for
backwards compatibility to read raster maps created with GRASS 6. It is only used for
raster maps of type CELL. FCELL and DCELL maps are never and have never been
compressed with RLE.

ZLIB
ZLIB’s deflate is the default compression method for all raster maps. GRASS GIS 7 uses
by default 1 as ZLIB compression level which is the best compromise between speed and
compression ratio, also when compared to other available compression methods. Valid
levels are in the range [1, 9] and can be set with the environment variable
GRASS_ZLIB_LEVEL.

LZ4
LZ4 is a very fast compression method, about as fast as no compression. Decompression
is also very fast. The compression ratio is generally higher than for RLE but worse
than for ZLIB. LZ4 is recommended if disk space is not a limiting factor.

BZIP2
BZIP2 can provide compression ratios much higher than the other methods, but only for
large raster maps (> 10000 columns). For large raster maps, disk space consumption can
be reduced by 30 - 50% when using BZIP2 instead of ZLIB’s deflate. BZIP2 is the
slowest compression and decompression method. However, if reading from / writing to a
storage device is the limiting factor, BZIP2 compression can speed up raster map
processing. Be aware that for smaller raster maps, BZIP2 compression ratio can be
worse than other compression methods.

NOTES

Compression method number scheme
The used compression method is encoded with numbers. In the internal cellhd file, the
value for "compressed" is 1 for RLE, 2 for ZLIB, 3 for LZ4, and 4 for BZIP2.

Obviously, decompression is controlled by the raster map’s compression, not by the
environment variable.

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. For CELL maps, 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.

FCELL maps always have 4 bytes per cell and DCELL maps always have 8 bytes per cell.

Since GRASS GIS 7.0.0, the default compression method for Integer (CELL) raster maps is
ZLIB and no longer RLE.

ZLIB compression levels
If the environment variable GRASS_ZLIB_LEVEL exists and its value can be parsed as an
integer, it determines the compression level used when newly generated raster maps are
compressed using ZLIB compression. This applies to all raster map types (CELL, FCELL,
DCELL).

If the variable does not exist, or the value cannot be parsed as an integer, ZLIB’s
compression level 1 will be used.

EXAMPLES

       Printing of current compression state:
       r.compress compressed_no -p
         <compressed_no> (method 0: NONE). Data type: <CELL>

       Applying RLE compression to a copy of the uncompressed map (not recommended!):
       # compression of map using the deprecated RLE compression
       g.copy raster=compressed_no,compressed_RLE
       export GRASS_INT_ZLIB=0 # RLE
       r.compress compressed_RLE
       r.compress compressed_RLE -p
         <compressed_RLE> is compressed (method 1: RLE). Data type: <CELL>
       unset GRASS_INT_ZLIB

       Applying ZLIB compression to a copy of the uncompressed map:
       # compression of map using ZLIB compression
       g.copy raster=compressed_no,compressed_ZLIB
       export GRASS_INT_ZLIB=1 # ZLIB
       r.compress compressed_ZLIB
       r.compress compressed_ZLIB -p
         <compressed_ZLIB> is compressed (method 2: ZLIB). Data type: <CELL>
       unset GRASS_INT_ZLIB

       Applying BZIP2 compression to a copy of the ZLIB-compressed map:
       # compression of map using BZIP2 compression
       g.copy raster=compressed_ZLIB,compressed_BZIP2
       export GRASS_COMPRESSOR=BZIP2 # BZIP2
       r.compress compressed_BZIP2
       r.compress compressed_BZIP2 -p
         <compressed_BZIP2> is compressed (method 4: BZIP2). Data type: <CELL>
       unset GRASS_COMPRESSOR

AUTHORS

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

       Markus Metz

       Last changed: $Date: 2017-12-06 13:43:03 +0100 (Wed, 06 Dec 2017) $

SOURCE CODE

       Available at: r.compress source code (history)

       Main index | Raster index | Topics index | Keywords index | Graphical index | Full index

       © 2003-2018 GRASS Development Team, GRASS GIS 7.4.0 Reference Manual