1r.compress(1) Grass User's Manual r.compress(1)
2
6 r.compress - Compresses and decompresses raster maps.
7
9 raster, map management, compression
10
12 r.compress
13 r.compress --help
14 r.compress [-upg] map=name[,name,...] [--help] [--verbose] [--quiet]
15 [--ui]
16 Flags:
18 -u
19 Uncompress the map
20 -p
22 Print compression information and data type of input map(s)
23 -g
25 Print compression information in shell script style
26 --help
28 Print usage summary
29 --verbose
31 Verbose module output
32 --quiet
34 Quiet module output
35 --ui
37 Force launching GUI dialog
38 Parameters:
40 map=name[,name,...] [required]
41 Name of existing raster map(s)
42
44 r.compress can be used to compress or decompress raster maps. Addi‐
45 tionally, it prints information about the compression method and data
46 type of the input raster map(s).
47 All raster maps (those imported for the first time and those newly gen‐
49 erated) are compressed by default using the ZLIB compression method
50 (see below). Related no data files (i.e.: NULL files), if present, are
51 compressed by default unless a specific environment variable is set to
52 explicitly disable NULL file compression (GRASS_COMPRESS_NULLS, see
53 below).
54 During compression or re-compression, r.compress compresses raster maps
56 using the method specified by means of the environment variable
57 GRASS_COMPRESSOR. The default compression method is ZLIB’s "deflate"
58 algorithm (LZ77-based). Raster maps that contain very little informa‐
59 tion (such as boundary, geology, soils and land use maps) can be
60 greatly reduced in size. Some raster maps are shrunk to roughly 1% of
61 their original sizes. All newly generated raster maps are automati‐
62 cally stored as compressed data with varying methods depending on the
63 raster format (i.e., CELL: integer; FCELL: single precision; DCELL:
64 double precision; see below). All GRASS GIS modules are able to read
65 both compressed and uncompressed raster maps.
66 Raster maps that are already compressed might be compressed again,
68 either by setting a different method with GRASS_COMPRESSOR (supported
69 methods: RLE, ZLIB, LZ4, BZIP2) or, for the case of ZLIB compression,
70 by changing the compression level with the environment variable
71 GRASS_ZLIB_LEVEL.
72 Compressed raster maps may be decompressed using r.compress with the -u
74 flag. If a raster map was already decompressed and the -u flag is set,
75 the module simply informs the user that the map is already decompressed
76 and exits.
77 Information about the compression method and data type of the input
79 raster map(s) can be printed in shell style with the -g flag. In this
80 case, the module prints to stdout one line per input map with the
81 fields "input map name", "data type", "name of data compression
82 method", "NULL file compression" separated by the pipe character. NULL
83 file compression is indicated with "YES" or "NO".
84 TERMINOLOGY
86 · INTEGER map (CELL data type): a raster map of INTEGER type
87 (whole numbers only)
88 · FLOAT map (FCELL data type): a raster map of FLOAT type (4
90 bytes, 7-9 digits precision)
91 · DOUBLE map (DCELL data type): a raster map of DOUBLE type (8
93 bytes, 15-17 digits precision)
94 · NULL: represents "no data" in raster maps; to be distinguished
96 from 0 (zero) data value
97 OVERVIEW OF AVAILABLE COMPRESSION ALGORITHMS
99 The following compression methods are available (set by export
100 GRASS_COMPRESSOR=method):
101 · NONE (uncompressed)
103 · RLE (generic Run-Length Encoding of single bytes; deprecated)
105 · ZLIB (DEFLATE, good speed and compression - default compres‐
107 sion)
108 · with zlib compression levels (export GRASS_ZLIB_LEVEL=X):
110 -1..9 (-1 is default which corresponds to ZLIB level 6)
111 · note: export GRASS_ZLIB_LEVEL=0 is equal to copying the
113 data as-is from source to destination
114 · LZ4 (fastest, low compression)
116 · BZIP2 (slowest, high compression)
118 Important: the NULL file compression can be turned off with export
119 GRASS_COMPRESS_NULLS=0. Raster maps with NULL file compression can only
120 be opened with GRASS GIS 7.2.0 or later. NULL file compression for a
121 particular raster map can be managed with r.null -z. The NULL file
122 compression is using the LZ4 method as being the best compromise
123 between speed and compression rate.
124 COMPRESSION ALGORITHM DETAILS
126 All GRASS GIS raster map types are by default ZLIB compressed, i.e.
127 using ZLIB’s deflate algorithm. Through the environment variable
128 GRASS_COMPRESSOR the compression method can be set to RLE, ZLIB, LZ4,
129 or BZIP2.
130 Integer (CELL type) raster maps can be compressed with RLE if the envi‐
132 ronment variable GRASS_INT_ZLIB exists and is set to value 0. However,
133 this is not recommended.
134 Floating point (FCELL, DCELL) raster maps never use RLE compression;
136 they are either compressed with ZLIB, LZ4, BZIP2 or are uncompressed.
137 RLE
139 DEPRECATED Run-Length Encoding, poor compression ratio but fast. It
140 is kept for backwards compatibility to read raster maps created
141 with GRASS 6. It is only used for raster maps of type CELL. FCELL
142 and DCELL maps are never and have never been compressed with RLE.
143 ZLIB
145 ZLIB’s deflate is the default compression method for all raster
146 maps. GRASS GIS 7 uses by default 1 as ZLIB compression level which
147 is the best compromise between speed and compression ratio, also
148 when compared to other available compression methods. Valid levels
149 are in the range [1, 9] and can be set with the environment vari‐
150 able GRASS_ZLIB_LEVEL.
151 LZ4
153 LZ4 is a very fast compression method, about as fast as no compres‐
154 sion. Decompression is also very fast. The compression ratio is
155 generally higher than for RLE but worse than for ZLIB. LZ4 is rec‐
156 ommended if disk space is not a limiting factor.
157 BZIP2
159 BZIP2 can provide compression ratios much higher than the other
160 methods, but only for large raster maps (> 10000 columns). For
161 large raster maps, disk space consumption can be reduced by 30 -
162 50% when using BZIP2 instead of ZLIB’s deflate. BZIP2 is the slow‐
163 est compression and decompression method. However, if reading from
164 / writing to a storage device is the limiting factor, BZIP2 com‐
165 pression can speed up raster map processing. Be aware that for
166 smaller raster maps, BZIP2 compression ratio can be worse than
167 other compression methods.
168
170 Compression method number scheme
171 The used compression method is encoded with numbers. In the internal
172 cellhd file, the value for "compressed" is 1 for RLE, 2 for ZLIB, 3 for
173 LZ4, and 4 for BZIP2.
174 Obviously, decompression is controlled by the raster map’s compression,
176 not by the environment variable.
177 Formats
179 Conceptually, a raster data file consists of rows of cells, with each
180 row containing the same number of cells. A cell consists of one or more
181 bytes. For CELL maps, the number of bytes per cell depends on the cate‐
182 gory values stored in the cell. Category values in the range 0-255
183 require 1 byte per cell, while category values in the range 256-65535
184 require 2 bytes, and category values in the range above 65535 require 3
185 (or more) bytes per cell.
186 FCELL maps always have 4 bytes per cell and DCELL maps always have 8
188 bytes per cell.
189 Since GRASS GIS 7.0.0, the default compression method for Integer
191 (CELL) raster maps is ZLIB and no longer RLE.
192 ZLIB compression levels
194 If the environment variable GRASS_ZLIB_LEVEL exists and its value can
195 be parsed as an integer, it determines the compression level used when
196 newly generated raster maps are compressed using ZLIB compression. This
197 applies to all raster map types (CELL, FCELL, DCELL).
198 If the variable does not exist, or the value cannot be parsed as an
200 integer, ZLIB’s compression level 1 will be used.
201
203 Printing of current compression state
204 Example for an uncompressed raster map:
205 r.compress compressed_no -p
206 <compressed_no> (method 0: NONE). Data type: <CELL>
207 Applying ZLIB compression
209 Applying ZLIB compression to a copy of the uncompressed map from above:
210 # compression of map using ZLIB compression
211 g.copy raster=compressed_no,compressed_ZLIB
212 export GRASS_COMPRESSOR=ZLIB # ZLIB
213 r.compress compressed_ZLIB
214 r.compress compressed_ZLIB -p
215 <compressed_ZLIB> is compressed (method 2: ZLIB). Data type: <CELL>
216 Applying BZIP2 compression
218 Applying BZIP2 compression to a copy of the ZLIB-compressed map from
219 above:
220 # compression of map using BZIP2 compression
221 g.copy raster=compressed_ZLIB,compressed_BZIP2
222 export GRASS_COMPRESSOR=BZIP2 # BZIP2
223 r.compress compressed_BZIP2
224 r.compress compressed_BZIP2 -p
225 <compressed_BZIP2> is compressed (method 4: BZIP2). Data type: <CELL>
226 unset GRASS_COMPRESSOR # switch back to default
227
229 r.info, r.null, r.support
230 Compression algorithms: bzip2, LZ4, zlib
232
234 James Westervelt and Michael Shapiro, U.S. Army Construction Engineer‐
235 ing Research Laboratory
236 Markus Metz
238 Last changed: $Date: 2018-08-24 12:37:52 +0200 (Fri, 24 Aug 2018) $
240
242 Available at: r.compress source code (history)
243 Main index | Raster index | Topics index | Keywords index | Graphical
245 index | Full index
246 © 2003-2019 GRASS Development Team, GRASS GIS 7.4.4 Reference Manual
248GRASS 7.4.4 r.compress(1)