GRASS logo

Note: This document is for an older version of GRASS GIS that will be discontinued soon. You should upgrade, and read the current manual page.


r.external - Links GDAL supported raster data as a pseudo GRASS raster map.


raster, import, external


r.external --help
r.external [-fojeahvtmr] [input=name] [source=name] output=name [band=integer] [title=phrase] [--overwrite] [--help] [--verbose] [--quiet] [--ui]


List supported formats and exit
Override projection check (use current location's projection)
Assume that the dataset has same projection as the current location
Perform projection check only and exit
Extend region extents based on new dataset
Also updates the default region if in the PERMANENT mapset
Auto-adjustment for lat/lon
Attempt to fix small precision errors in resolution and extents
Flip horizontally
Flip vertically
List available bands including band type in dataset and exit
Format: band number,type,projection check
Read data range from metadata
WARNING: metadata are sometimes approximations with wrong data range
Create fast link without data range
WARNING: some modules do not work correctly without known data range
Allow output files to overwrite existing files
Print usage summary
Verbose module output
Quiet module output
Force launching GUI dialog


Name of raster file to be linked
Name of non-file GDAL data source
output=name [required]
Name for output raster map
Band to select (default is all bands)
Title for resultant raster map

Table of contents


r.external allows a user to link a GDAL supported raster file to a binary raster map layer, from any GDAL supported raster map format, with an optional title. The file is not imported but just registered as GRASS raster map.


In essence, r.external creates a read-only link to the original dataset which is only valid if the original dataset remains at the originally indicated directory and filename.

NULL data handling

GDAL-linked (r.external) maps do not have or use a NULL bitmap, hence r.null cannot manipulate them directly. Here NULL cells are those whose value matches the value reported by the GDALGetRasterNoDataValue() function. To apply the GDAL-linked the user need to either create a MASK (e.g. with r.mask) and then "apply" it using e.g. r.resample, or use r.mapcalc to create a copy with the appropriate categories changed to NULL (if() condition).


RGB Orthophoto from GeoTIFF

# import of all channels (each channel will become a GRASS raster map):
r.external input=/home/user/data/maps/059100.tif output=ortho
g.region raster=ortho.3 -p
d.rgb r=ortho.1 g=ortho.2 b=ortho.3
r.composite r=ortho.1 g=ortho.2 b=ortho.3 output=ortho.rgb

Processing workflow without data import and export

External raster maps to be processed can be directly linked using r.external; likewise, results can be written out to standard raster formats with r.external.out (GDAL supported formats):
# register GeoTIFF file to be used in current mapset:
r.external input=terra_lst1km20030314.LST_Day.tif output=modis_celsius
# define output directory for files resulting from GRASS calculation:
r.external.out directory=$HOME/gisoutput/ format="GTiff"

# perform GRASS calculation (here: extract pixels > 20 deg C)
# this stores the output map directly as GeoTIFF:
r.mapcalc "warm.tif = if(modis_celsius > 20.0, modis_celsius, null() )"

# cease GDAL output connection and turn back to write GRASS raster files:
r.external.out -r

# now use the resulting file elsewhere
gdalinfo $HOME/gisoutput/warm.tif


GDAL Pages:


r.import,, r.external.out

v.import,, v.external, v.external.out


Glynn Clements


Available at: r.external source code (history)

Latest change: Saturday Apr 02 15:47:21 2022 in commit: a08769cd9820ae36075cf822ee4a63d1ed4e3de4

Note: This document is for an older version of GRASS GIS that will be discontinued soon. You should upgrade, and read the current manual page.

Main index | Raster index | Topics index | Keywords index | Graphical index | Full index

© 2003-2023 GRASS Development Team, GRASS GIS 8.2.2dev Reference Manual