1r.compress(1) GRASS GIS 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 ZSTD compression method if
50 available, otherwise ZLIB compression is used (see below). Related no
51 data files (i.e.: NULL files), if present, are compressed by default
52 unless a specific environment variable is set to explicitly disable
53 NULL file compression (GRASS_COMPRESS_NULLS, see 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 ZSTD if available,
58 otherwise ZLIB’s "deflate" algorithm (LZ77-based). Raster maps that
59 contain very little information (such as boundary, geology, soils and
60 land use maps) can be greatly reduced in size. Some raster maps are
61 shrunk to roughly 1% of their original sizes. All newly generated
62 raster maps are automatically stored as compressed data with varying
63 methods depending on the raster format (i.e., CELL: integer; FCELL:
64 single precision; DCELL: double precision; see below). All GRASS GIS
65 modules are able to read both compressed and uncompressed raster maps.
66 Raster maps that are already compressed might be compressed again, ei‐
68 ther by setting a different method with GRASS_COMPRESSOR (supported
69 methods: RLE, ZLIB, LZ4, BZIP2, ZSTD) or, for the case of ZLIB compres‐
70 sion, 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)
107 • with zlib compression levels (export GRASS_ZLIB_LEVEL=X):
109 -1..9 (-1 is default which corresponds to ZLIB level 6)
110 • note: export GRASS_ZLIB_LEVEL=0 is equal to copying the
112 data as-is from source to destination
113 • LZ4 (fastest, low compression)
115 • BZIP2 (slowest, high compression)
117 • ZSTD (compared to ZLIB, faster and higher compression, much
119 faster decompression - default compression)
120 Important: the NULL file compression can be turned off with export
121 GRASS_COMPRESS_NULLS=0. Raster maps with NULL file compression can only
122 be opened with GRASS GIS 7.2.0 or later. NULL file compression for a
123 particular raster map can be managed with r.null -z. The NULL file
124 compression is using the LZ4 method as being the best compromise be‐
125 tween speed and compression rate.
126 COMPRESSION ALGORITHM DETAILS
128 All GRASS GIS raster map types are by default ZSTD compressed if avail‐
129 able, otherwise ZLIB compressed. Through the environment variable
130 GRASS_COMPRESSOR the compression method can be set to RLE, ZLIB, LZ4,
131 BZIP2, or ZSTD.
132 Integer (CELL type) raster maps can be compressed with RLE if the envi‐
134 ronment variable GRASS_COMPRESSOR exists and is set to RLE. However,
135 this is not recommended.
136 Floating point (FCELL, DCELL) raster maps never use RLE compression;
138 they are either compressed with ZLIB, LZ4, BZIP2, ZSTD or are uncom‐
139 pressed.
140 RLE
142 DEPRECATED Run-Length Encoding, poor compression ratio but fast. It
143 is kept for backwards compatibility to read raster maps created
144 with GRASS 6. It is only used for raster maps of type CELL. FCELL
145 and DCELL maps are never and have never been compressed with RLE.
146 ZLIB
148 ZLIB’s deflate is the default compression method for all raster
149 maps, if ZSTD is not available. GRASS GIS 8 uses by default 1 as
150 ZLIB compression level which is the best compromise between speed
151 and compression ratio, also when compared to other available com‐
152 pression methods. Valid levels are in the range [1, 9] and can be
153 set with the environment variable GRASS_ZLIB_LEVEL.
154 LZ4
156 LZ4 is a very fast compression method, about as fast as no compres‐
157 sion. Decompression is also very fast. The compression ratio is
158 generally higher than for RLE but worse than for ZLIB. LZ4 is rec‐
159 ommended if disk space is not a limiting factor.
160 BZIP2
162 BZIP2 can provide compression ratios much higher than the other
163 methods, but only for large raster maps (> 10000 columns). For
164 large raster maps, disk space consumption can be reduced by 30 -
165 50% when using BZIP2 instead of ZLIB’s deflate. BZIP2 is the slow‐
166 est compression and decompression method. However, if reading from
167 / writing to a storage device is the limiting factor, BZIP2 com‐
168 pression can speed up raster map processing. Be aware that for
169 smaller raster maps, BZIP2 compression ratio can be worse than
170 other compression methods.
171 ZSTD
173 ZSTD (Zstandard) provides compression ratios higher than ZLIB but
174 lower than BZIP2 (for large data). ZSTD compresses up to 4x faster
175 than ZLIB, and usually decompresses 6x faster than ZLIB. ZSTD is
176 the default compression method if available.
177
179 Compression method number scheme
180 The used compression method is encoded with numbers. In the internal
181 cellhd file, the value for "compressed" is 1 for RLE, 2 for ZLIB, 3 for
182 LZ4, 4 for BZIP2, and 5 for ZSTD.
183 Obviously, decompression is controlled by the raster map’s compression,
185 not by the environment variable.
186 Formats
188 Conceptually, a raster data file consists of rows of cells, with each
189 row containing the same number of cells. A cell consists of one or more
190 bytes. For CELL maps, the number of bytes per cell depends on the cate‐
191 gory values stored in the cell. Category values in the range 0-255 re‐
192 quire 1 byte per cell, while category values in the range 256-65535 re‐
193 quire 2 bytes, and category values in the range above 65535 require 3
194 (or more) bytes per cell.
195 FCELL maps always have 4 bytes per cell and DCELL maps always have 8
197 bytes per cell.
198 Since GRASS GIS 7.0.0, the default compression method for Integer
200 (CELL) raster maps is ZLIB and no longer RLE.
201 ZLIB compression levels
203 If the environment variable GRASS_ZLIB_LEVEL exists and its value can
204 be parsed as an integer, it determines the compression level used when
205 newly generated raster maps are compressed using ZLIB compression. This
206 applies to all raster map types (CELL, FCELL, DCELL).
207 If the variable does not exist, or the value cannot be parsed as an in‐
209 teger, ZLIB’s compression level 1 will be used.
210
212 Printing of current compression state
213 Example for an uncompressed raster map:
214 r.compress compressed_no -p
215 <compressed_no> (method 0: NONE). Data type: <CELL>
216 Applying ZLIB compression
218 Applying ZLIB compression to a copy of the uncompressed map from above:
219 # compression of map using ZLIB compression
220 g.copy raster=compressed_no,compressed_ZLIB
221 export GRASS_COMPRESSOR=ZLIB # ZLIB
222 r.compress compressed_ZLIB
223 r.compress compressed_ZLIB -p
224 <compressed_ZLIB> is compressed (method 2: ZLIB). Data type: <CELL>
225 unset GRASS_COMPRESSOR # switch back to default
226 Applying BZIP2 compression
228 Applying BZIP2 compression to a copy of the ZLIB-compressed map from
229 above:
230 # compression of map using BZIP2 compression
231 g.copy raster=compressed_ZLIB,compressed_BZIP2
232 export GRASS_COMPRESSOR=BZIP2 # BZIP2
233 r.compress compressed_BZIP2
234 r.compress compressed_BZIP2 -p
235 <compressed_BZIP2> is compressed (method 4: BZIP2). Data type: <CELL>
236 unset GRASS_COMPRESSOR # switch back to default
237 Applying ZSTD compression
239 Applying ZSTD compression to a copy of the BZIP2-compressed map from
240 above:
241 # compression of map using ZSTD compression
242 g.copy raster=compressed_BZIP2,compressed_ZSTD
243 export GRASS_COMPRESSOR=ZSTD # ZSTD
244 r.compress compressed_ZSTD
245 r.compress compressed_ZSTD -p
246 <compressed_ZSTD> is compressed (method 5: ZSTD). Data type: <CELL>
247 unset GRASS_COMPRESSOR
248
250 r.info, r.null, r.support
251 Compression algorithms: bzip2, LZ4, zlib, zstd
253
255 James Westervelt and Michael Shapiro, U.S. Army Construction Engineer‐
256 ing Research Laboratory
257 Markus Metz
259
261 Available at: r.compress source code (history)
262 Accessed: Saturday Oct 28 18:17:28 2023
264 Main index | Raster index | Topics index | Keywords index | Graphical
266 index | Full index
267 © 2003-2023 GRASS Development Team, GRASS GIS 8.3.1 Reference Manual
269GRASS 8.3.1 r.compress(1)