1r.compress(1)               GRASS GIS User's Manual              r.compress(1)
2
3
4

NAME

6       r.compress  - Compresses and decompresses raster maps.
7

KEYWORDS

9       raster, map management, compression
10

SYNOPSIS

12       r.compress
13       r.compress --help
14       r.compress [-upg] map=name[,name,...]  [--help]  [--verbose]  [--quiet]
15       [--ui]
16
17   Flags:
18       -u
19           Uncompress the map
20
21       -p
22           Print compression information and data type of input map(s)
23
24       -g
25           Print compression information in shell script style
26
27       --help
28           Print usage summary
29
30       --verbose
31           Verbose module output
32
33       --quiet
34           Quiet module output
35
36       --ui
37           Force launching GUI dialog
38
39   Parameters:
40       map=name[,name,...] [required]
41           Name of existing raster map(s)
42

DESCRIPTION

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
48       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
55       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
67       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
73       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
78       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
85   TERMINOLOGY
86           •   INTEGER  map  (CELL  data  type):  a raster map of INTEGER type
87               (whole numbers only)
88
89           •   FLOAT map (FCELL data type): a raster  map  of  FLOAT  type  (4
90               bytes, 7-9 digits precision)
91
92           •   DOUBLE  map  (DCELL  data type): a raster map of DOUBLE type (8
93               bytes, 15-17 digits precision)
94
95           •   NULL: represents "no data" in raster maps; to be  distinguished
96               from 0 (zero) data value
97
98   OVERVIEW OF AVAILABLE COMPRESSION ALGORITHMS
99       The   following  compression  methods  are  available  (set  by  export
100       GRASS_COMPRESSOR=method):
101
102           •   NONE (uncompressed)
103
104           •   RLE  (generic Run-Length Encoding of single bytes; deprecated)
105
106           •   ZLIB (DEFLATE, good speed and compression)
107
108               •   with zlib compression levels  (export  GRASS_ZLIB_LEVEL=X):
109                   -1..9 (-1 is default which corresponds to ZLIB level 6)
110
111               •   note:  export  GRASS_ZLIB_LEVEL=0  is  equal to copying the
112                   data as-is from source to destination
113
114           •   LZ4  (fastest, low compression)
115
116           •   BZIP2 (slowest, high compression)
117
118           •   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
127   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
133       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
137       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
141       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
147       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
155       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
161       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
172       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

NOTES

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
184       Obviously, decompression is controlled by the raster map’s compression,
185       not by the environment variable.
186
187   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
196       FCELL maps always have 4 bytes per cell and DCELL maps  always  have  8
197       bytes per cell.
198
199       Since  GRASS  GIS  7.0.0,  the  default  compression method for Integer
200       (CELL) raster maps is ZLIB and no longer RLE.
201
202   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
208       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

EXAMPLES

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
217   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
227   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
238   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

SEE ALSO

250        r.info, r.null, r.support
251
252       Compression algorithms: bzip2, LZ4, zlib, zstd
253

AUTHORS

255       James Westervelt and Michael Shapiro, U.S. Army Construction  Engineer‐
256       ing Research Laboratory
257
258       Markus Metz
259

SOURCE CODE

261       Available at: r.compress source code (history)
262
263       Accessed: Saturday Oct 28 18:17:28 2023
264
265       Main  index  | Raster index | Topics index | Keywords index | Graphical
266       index | Full index
267
268       © 2003-2023 GRASS Development Team, GRASS GIS 8.3.1 Reference Manual
269
270
271
272GRASS 8.3.1                                                      r.compress(1)
Impressum