Skip to content

r.buildvrt

Build a VRT (Virtual Raster) from the list of input raster maps.

r.buildvrt [input=name [,name,...]] [file=name] output=name [title=phrase] [--overwrite] [--verbose] [--quiet] [--qq] [--ui]

Example:

r.buildvrt output=name

grass.script.run_command("r.buildvrt", input=None, file=None, output, title=None, overwrite=False, verbose=False, quiet=False, superquiet=False)

Example:

gs.run_command("r.buildvrt", output="name")

Parameters

input=name [,name,...]
    Name of input raster files
file=name
    Input file with one raster map name per line
output=name [required]
    Name for output raster map
title=phrase
    Title for resultant raster map
--overwrite
    Allow output files to overwrite existing files
--help
    Print usage summary
--verbose
    Verbose module output
--quiet
    Quiet module output
--qq
    Very quiet module output
--ui
    Force launching GUI dialog

input : str | list[str], optional
    Name of input raster files
    Used as: input, raster, name
file : str, optional
    Input file with one raster map name per line
    Used as: input, file, name
output : str, required
    Name for output raster map
    Used as: output, raster, name
title : str, optional
    Title for resultant raster map
    Used as: phrase
overwrite: bool, optional
    Allow output files to overwrite existing files
    Default: False
verbose: bool, optional
    Verbose module output
    Default: False
quiet: bool, optional
    Quiet module output
    Default: False
superquiet: bool, optional
    Very quiet module output
    Default: False

DESCRIPTION

r.buildvrt builds a virtual raster (VRT) that is a mosaic of the list of input raster maps. The purpose of such a VRT is to provide fast access to small subsets of the VRT, also with multiple simultaneous read requests.

NOTES

r.buildvrt creates a list of raster maps that can be located in different mapsets. The output is a read-only link to the original raster maps which is only valid if the original raster maps remain in the originally indicated mapset. A VRT can also be built from raster maps registered with r.external. However, GRASS VRTs built from external registered data (see below) are known to have performance issues.

Reading the whole VRT is slower than reading the equivalent single raster map. Only reading small parts of the VRT provides a performance benefit.

A GRASS virtual raster can be regarded as a simplified version of GDAL's virtual raster format. The GRASS equivalent is simpler because issues like nodata, projection, resolution, resampling, masking are already handled by native GRASS raster routines.

EXAMPLES

VRT from a DEM in the North Carolina sample dataset

In this exercise a low resolution DEM is resampled to a high resolution DEM. This is subsequently cut into small tiles and from that a virtual tile mosaik is created:

# set the computational region to elevation map
g.region raster=elev_state_500m -p
# enforce higher resolution
g.region res=50 -p
# resample the 500 meter DEM to 50 meter resolution
r.resamp.interp input=elev_state_500m output=elev_state_50m method=bilinear
# create tiles from resulting large 50 m elevation map
r.tile input=elev_state_50m output=elev_state_50m_tile_ width=1000 height=1000 overlap=0
# for convenience, dump list of tile names to a file
g.list type=raster pattern=elev_state_50m_tile_* output=tilelist.csv
# build a mosaik as VRT from tile list
r.buildvrt file=tilelist.csv output=elev_state_50m_vrt

KNOWN ISSUES

Users may experience significant performance degradation with virtual rasters built with r.buildvrt over GDAL-linked (r.external) raster maps, especially on slower file systems with latency like NFS. Performance degradation may also occur on local file systems, but is usually less severe. For such use cases consider using the GRASS GIS addon r.buildvrt.gdal or building GDAL VRTs, e.g. with gdalbuildvrt.

SEE ALSO

r.tile, r.patch, r.external r.buildvrt.gdal

The equivalent GDAL utility gdalbuildvrt

AUTHOR

Markus Metz
Sponsored by mundialis

SOURCE CODE

Available at: r.buildvrt source code (history)
Latest change: Friday Feb 07 19:16:09 2025 in commit a82a39f