<!-- meta page description: Raster data processing in GRASS GIS -->
<!-- meta page index: raster -->
<h3>Raster maps in general</h3>

A "raster map" is a data layer consisting of a gridded array of cells.
It has a certain number of rows and columns, with a data point (or null
value indicator) in each cell. These may exist as a 2D grid or as a 3D
cube made up of many smaller cubes, i.e. a stack of 2D grids.
<p>
The geographic boundaries of the raster map are described by the north,
south, east, and west fields. These values describe the lines which bound
the map at its edges. These lines do NOT pass through the center of the
grid cells at the edge of the map, but along the edge of the map itself.
i.e. the geographic extent of the map is described by the outer bounds of
all cells within the map.

<p>
As a general rule in GRASS GIS:
<ol>
<li> Raster output maps have their bounds and resolution equal to those
of the current computational region.</li>
<li> Raster input maps are automatically cropped/padded and rescaled
(using nearest-neighbour resampling) to match the current region.</li>
<li> Raster input maps are automatically masked if a raster map named
     MASK exists. The MASK is only applied when <i>reading</i> maps
     from the disk.</li>
</ol>

There are a few exceptions to this:

<code>r.in.*</code> programs read the data cell-for-cell, with no resampling. When
reading non-georeferenced data, the imported map will usually have its
lower-left corner at (0,0) in the project's coordinate system; the user
needs to use <a href="r.region.html">r.region</a> to "place" the imported map.
<p>
Some programs which need to perform specific types of resampling (e.g.
<a href="r.resamp.rst.html">r.resamp.rst</a>) read the input maps at
their original resolution then do the resampling themselves.
<p>
<a href="r.proj.html">r.proj</a> has to deal with two regions (source
and destination) simultaneously; both will have an impact upon the
final result.

<h3>Raster import and export</h3>

The module <a href="r.in.gdal.html">r.in.gdal</a> offers a common
interface for many different raster formats. Additionally, it also
offers options such as on-the-fly project creation or extension of
the default region to match the extent of the imported raster map.
For special cases, other import modules are available. The full map
is always imported.
<p>
For importing scanned maps, the user will need to create a
x,y-project, scan the map in the desired resolution and save it into
an appropriate raster format (e.g. tiff, jpeg, png, pbm) and then use
<a href="r.in.gdal.html">r.in.gdal</a> to import it. Based on
reference points the scanned map can be recified to obtain geocoded
data.
<p>
Raster maps are exported with <a href="r.out.gdal.html">r.out.gdal</a>
into common formats. Also <a href="r.out.bin.html">r.out.bin</a>,
<a href="r.out.vtk.html">r.out.vtk</a>, <a href="r.out.ascii.html">r.out.ascii</a>
and other export modules are available. They export the data according
to the current region settings. If those differ from the original map,
the map is resampled on the fly (nearest neighbor algorithm). In other
words, the output will have as many rows and columns as the current region.
To export maps with various grid spacings (e.g, 500x500 or 200x500), you
can just change the region resolution with <a href="g.region.html">g.region</a>
and then export the map. The resampling is done with nearest neighbor
algorithm in this case. If you want some other form of resampling,
first change the region, then explicitly resample the map with e.g.
<a href="r.resamp.interp.html">r.resamp.interp</a> or
<a href="r.resamp.stats.html">r.resamp.stats</a>, then export the
resampled map.
<p>
GRASS GIS raster map exchange between different projects with the same CRS
can be done in a lossless way using the <a href="r.pack.html">r.pack</a>
and <a href="r.unpack.html">r.unpack</a> modules.

<h3>Metadata</h3>

The <a href="r.info.html">r.info</a> module displays general information
about a map such as region extent, data range, data type, creation history,
and other metadata.
Metadata such as map title, units, vertical datum etc. can be updated
with <a href="r.support.html">r.support</a>. Timestamps are managed
with <a href="r.timestamp.html">r.timestamp</a>. Region extent and
resolution are mangaged with <a href="r.region.html">r.region</a>.


<h3>Raster map operations</h3>

<h4>Resampling methods and interpolation methods</h4>
GRASS raster map processing is always performed in the current region
settings (see <a href="g.region.html">g.region</a>), i.e. the current
region extent and current raster resolution is used. If the resolution
differs from that of the input raster map(s), on-the-fly resampling is
performed (nearest neighbor resampling). If this is not desired, the
input map(s) has/have to be resampled beforehand with one of the dedicated
modules.
<p>

The built-in nearest-neighbour resampling of raster data calculates
the centre of each region cell, and takes the value of the raster cell
in which that point falls.
<p>

If the point falls exactly upon a grid line, the exact result will be
determined by the direction of any rounding error. One consequence of
this is that downsampling by a factor which is an even integer will
always sample exactly on the boundary between cells, meaning that the
result is ill-defined.
<p>

The following modules are available for reinterpolation of "filled"
raster maps (continuous data) to a different resolution:
<ul>
<li><a href="r.resample.html">r.resample</a> uses the built-in resampling,
so it should produce identical results as the on-the-fly resampling done
via the raster import modules.</li>
<li><a href="r.resamp.interp.html">r.resamp.interp</a> Resampling with
nearest neighbor, bilinear, and bicubic method: <b>method=nearest</b> uses the
same algorithm as <a href="r.resample.html">r.resample</a>, but not the same
code, so it may not produce identical results in cases which are decided
by the rounding of floating-point numbers.
<br>
For <a href="r.resamp.interp.html">r.resamp.interp</a> <b>method=bilinear</b>
and <b>method=bicubic</b>, the raster values are treated as samples at each
raster cell's centre, defining a piecewise-continuous surface. The resulting
raster values are obtained by sampling the surface at each region cell's centre.
As the algorithm only interpolates, and doesn't extrapolate, a margin of 0.5
(for bilinear) or 1.5 (for bicubic) cells is lost from the extent of the original
raster. Any samples taken within this margin will be null.</li>

<li><a href="r.resamp.rst.html">r.resamp.rst</a> Regularized Spline with Tension
(RST) interpolation 2D: Behaves similarly, i.e. it computes a surface assuming
that the values are samples at each raster cell's centre, and samples the surface
at each region cell's centre.</li>
<li><a href="r.resamp.bspline.html">r.resamp.bspline</a> Bicubic or bilinear
spline interpolation with Tykhonov regularization.</li>
<li>For <a href="r.resamp.stats.html">r.resamp.stats</a> without <b>-w</b>, the value of
each region cell is the chosen aggregate of the values from all of the raster
cells whose centres fall within the bounds of the region cell.
<br>
With <b>-w</b>, the samples are weighted according to the proportion of the
raster cell which falls within the bounds of the region cell, so the
result is normally unaffected by rounding error (a minuscule difference
in the position of the boundary results in the addition or subtraction of
a sample weighted by a minuscule factor; also, The min and max aggregates
can't use weights, so <b>-w</b> has no effect for those).</li>

<li> <a href="r.fillnulls.html">r.fillnulls</a> for Regularized Spline with Tension (RST)
interpolation 2D for hole filling (e.g., SRTM DEM)</li>
</ul>
<p>

Furthermore, there are modules available for reinterpolation of "sparse"
(scattered points or lines) maps:

<ul>
<li> Inverse distance weighted average (IDW) interpolation
 (<a href="r.surf.idw.html">r.surf.idw</a>)</li>
<li> Interpolating from contour lines (<a href="r.contour.html">r.contour</a>)</li>
<li> Various vector modules for interpolation</li>
</ul>

For Lidar and similar data, <a href="r.in.pdal.html">r.in.pdal</a> and <a href="r.in.xyz.html">r.in.xyz</a>
support loading and binning of ungridded x,y,z ASCII data into a new raster map.
The user may choose from a variety of statistical methods in creating the new raster map.
<p>

Otherwise, for interpolation of scattered data, use the <em>v.surf.*</em> set of
modules.

<h4>Raster MASKs</h4>
If a raster map named "MASK" exists, most GRASS raster modules will operate
only on data falling inside the masked area, and treat any data falling
outside of the mask as if its value were NULL. The mask is only applied
when <em>reading</em> an existing GRASS raster map, for example when used
in a module as an input map.
<p>
The mask is read as an integer map. If MASK is actually a
floating-point map, the values will be converted to integers using the
map's quantisation rules (this defaults to round-to-nearest, but can
be changed with r.quant).
<p>
(see <a href="r.mask.html">r.mask</a>)

<h3>Raster map statistics</h3>

A couple of commands are available to calculate local statistics
(<a href="r.neighbors.html">r.neighbors</a>), and global statistics
(<a href="r.statistics.html">r.statistics</a>, <a href="r.surf.area.html">r.surf.area</a>).
Profiles and transects can be generated
(<a href="d.profile.html">d.profile</a>, <a href="r.profile.html">r.profile</a>,
<a href="r.transect.html">r.transect</a>) as well as histograms
(<a href="d.histogram.html">d.histogram</a>) and polar diagrams
(<a href="d.polar.html">d.polar</a>).

Univariate statistics (<a href="r.univar.html">r.univar</a>) and
reports are also available (<a href="r.report.html">r.report</a>,<a
href="r.stats.html">r.stats</a>, <a href="r.volume.html">r.volume</a>).

Since <a href="r.univar.html">r.univar</a> may be slow for extended
statistics these can be calculated using
<a href="r.stats.quantile.html">r.stats.quantile</a>. Without a zones input
raster, the <a href="r.quantile.html">r.quantile</a> module will be significantly
more efficient for calculating percentiles with large maps. For calculating
univariate statistics from a raster map based on vector polygon map and
upload statistics to new attribute columns, see
<a href="v.rast.stats.html">v.rast.stats</a>. Category or object
oriented statistics can be computed with <a href="r.statistics.html">r.statistics</a>.
For floating-point cover map support for this, see the alternative
<a href="r.stats.zonal.html">r.stats.zonal</a>. For quantile calculations
with support for floating-point cover maps, see the alternative
<a href="r.stats.quantile.html">r.stats.quantile</a>.

<h3>Raster map algebra and aggregation</h3>

The <a href="r.mapcalc.html">r.mapcalc</a> command provides raster map
algebra methods.
The <a href="r.resamp.stats.html">r.resamp.stats</a> command resamples raster
map layers using various aggregation methods, the <a href="r.statistics.html">r.statistics</a>
command aggregates one map based on a second map.
<a href="r.resamp.interp.html">r.resamp.interp</a> resamples raster map
layers using interpolation.

<h3>Regression analysis</h3>

Both linear (<a href="r.regression.line.html">r.regression.line</a>) and
multiple regression (<a href="r.regression.multi.html">r.regression.multi</a>)
are supported.

<h3>Hydrologic modeling toolbox</h3>

Watershed modeling related modules are
<a href="r.basins.fill.html">r.basins.fill</a>,
<a href="r.water.outlet.html">r.water.outlet</a>,
<a href="r.watershed.html">r.watershed</a>, and
<a href="r.terraflow.html">r.terraflow</a>.

Water flow related modules are
<a href="r.carve.html">r.carve</a>,
<a href="r.drain.html">r.drain</a>,
<a href="r.fill.dir.html">r.fill.dir</a>,
<a href="r.fillnulls.html">r.fillnulls</a>,
<a href="r.flow.html">r.flow</a>, and
<a href="r.topidx.html">r.topidx</a>.

Flooding can be simulated with <a href="r.lake.html">r.lake</a>.

Hydrologic simulation model are available as
<a href="r.sim.sediment.html">r.sim.sediment</a>,
<a href="r.sim.water.html">r.sim.water</a>, and
<a href="r.topmodel.html">r.topmodel</a>.

<h3>Raster format</h3>

In GRASS GIS, raster data can be stored as 2D or 3D grids.

<h4>2D raster maps</h4>

2D rasters support three data types (for technical details, please refer
to the Wiki article
<a href="https://grasswiki.osgeo.org/wiki/GRASS_raster_semantics">GRASS raster semantics</a>):

<ul>
<li>32bit signed integer (CELL),</li>
<li>single-precision floating-point (FCELL), and</li>
<li>double-precision floating-point (DCELL).</li>
</ul>

In most GRASS GIS resources, 2D raster maps are usually called "raster" maps.

<h4>3D raster maps</h4>

The 3D raster map type is usually called "3D raster" but other names like
"RASTER3D", "voxel", "volume", "GRID3D" or "3d cell" are yet common.

3D rasters support only single- and double-precision floating-point.
3D raster's single-precision data type is most often called "float",
and the double-precision one "double".

<h4>No-data management and data portability</h4>

GRASS GIS distinguishes NULL and zero. When working with NULL data, it
is important to know that operations on NULL cells lead to NULL cells.

<p>
The GRASS GIS raster format is architecture independent and portable between
32bit and 64bit machines.

<h3>Raster compression</h3>
<!-- keep in sync with raster/r.compress/r.compress.html -->

All GRASS GIS raster map types are by default ZSTD compressed if
available, otherwise ZLIB compressed. Through the environment variable
<code>GRASS_COMPRESSOR</code> the compression method can be set to RLE,
ZLIB, LZ4, BZIP2, or ZSTD.
<p>
Important: the NULL file compression can be turned off with
<code>export GRASS_COMPRESS_NULLS=0</code>. Raster maps with NULL file
compression can only be opened with GRASS GIS 7.2.0 or later. NULL file
compression for a particular raster map can be managed with <b>r.null -z</b>.
<p>
Integer (CELL type) raster maps can be compressed with RLE if
the environment variable <code>GRASS_COMPRESSOR</code> exists and is set to
RLE. However, this is not recommended.
<p>
Floating point (FCELL, DCELL) raster maps never use RLE compression;
they are either compressed with ZLIB, LZ4, BZIP2, ZSTD or are uncompressed.

<dl>
<dt><strong>RLE</strong></dt>
<dd><b>DEPRECATED</b> 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.
</dd>
<dt><strong>ZLIB</strong></dt>
<dd>ZLIB's deflate is the default compression method for all raster
maps, if ZSTD is not available. GRASS GIS 8 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 <code>GRASS_ZLIB_LEVEL</code>.</dd>
<dt><strong>LZ4</strong></dt>
<dd>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.</dd>
<dt><strong>BZIP2</strong></dt>
<dd>BZIP2 can provide compression ratios much higher than the other
methods, but only for large raster maps (&gt; 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.</dd>
<dt><strong>ZSTD</strong></dt>
<dd>ZSTD (Zstandard) provides compression ratios higher than ZLIB but
lower than BZIP2 (for large data). ZSTD compresses up to 4x faster than
ZLIB, and usually decompresses 6x faster than ZLIB. ZSTD is the
default compression method if available.</dd>
</dl>

<p>
In the internal cellhd file, the value for "compressed" is 1 for RLE, 2
for ZLIB, 3 for LZ4,4 for BZIP2, and 5 for ZSTD.
<p>
Obviously, decompression is controlled by the raster map's compression,
not the environment variable.

<h3>See also</h3>

<ul>
  <li><a href="raster3dintro.html">Introduction into 3D raster data (voxel) processing</a></li>
  <li><a href="vectorintro.html">Introduction into vector data processing</a></li>
  <li><a href="imageryintro.html">Introduction into image processing</a></li>
  <li><a href="temporalintro.html">Introduction into temporal data processing</a></li>
  <li><a href="databaseintro.html">Database management</a></li>
  <li><a href="projectionintro.html">Projections and spatial transformations</a></li>
  <li><a href="wxguiintro.html">Graphical User Interface</a></li>
</ul>