Skip to content

r.external

Links GDAL supported raster data as a pseudo GRASS raster map.

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

Example:

r.external output=name

grass.script.run_command("r.external", input=None, source=None, output, band=None, title=None, flags=None, overwrite=False, verbose=False, quiet=False, superquiet=False)

Example:

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

Parameters

input=name
    Name of raster file to be linked
source=name
    Name of non-file GDAL data source
output=name [required]
    Name for output raster map
band=integer
    Band to select (default is all bands)
title=phrase
    Title for resultant raster map
-f
    List supported formats and exit
-o
    Override projection check (use current project's CRS)
    Assume that the dataset has the same coordinate reference system as the current project
-j
    Perform projection check only and exit
-e
    Extend region extents based on new dataset
    Also updates the default region if in the PERMANENT mapset
-a
    Auto-adjustment for lat/lon
    Attempt to fix small precision errors in resolution and extents
-h
    Flip horizontally
-v
    Flip vertically
-t
    List available bands including band type in dataset and exit
    Format: band number,type,projection check
-m
    Read data range from metadata
    WARNING: metadata are sometimes approximations with wrong data range
-r
    Create fast link without data range
    WARNING: some modules do not work correctly without known data range
--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, optional
    Name of raster file to be linked
    Used as: input, file, name
source : str, optional
    Name of non-file GDAL data source
    Used as: name
output : str, required
    Name for output raster map
    Used as: output, raster, name
band : int, optional
    Band to select (default is all bands)
title : str, optional
    Title for resultant raster map
    Used as: phrase
flags : str, optional
    Allowed values: f, o, j, e, a, h, v, t, m, r
    f
        List supported formats and exit
    o
        Override projection check (use current project's CRS)
        Assume that the dataset has the same coordinate reference system as the current project
    j
        Perform projection check only and exit
    e
        Extend region extents based on new dataset
        Also updates the default region if in the PERMANENT mapset
    a
        Auto-adjustment for lat/lon
        Attempt to fix small precision errors in resolution and extents
    h
        Flip horizontally
    v
        Flip vertically
    t
        List available bands including band type in dataset and exit
        Format: band number,type,projection check
    m
        Read data range from metadata
        WARNING: metadata are sometimes approximations with wrong data range
    r
        Create fast link without data range
        WARNING: some modules do not work correctly without known data range
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.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.

NOTES

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 introduce additional NULL values to a computation based on a GDAL-linked raster, the user needs to either create a mask with with r.mask and then "apply" it using e.g. r.resample or r.mapcalc, or use r.mapcalc to create a copy with the appropriate categories changed to NULL (if() condition).

EXAMPLES

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

REFERENCES

GDAL Pages: https://gdal.org/

SEE ALSO

r.import, r.in.gdal, r.external.out

v.import, v.in.ogr, v.external, v.external.out

AUTHOR

Glynn Clements

SOURCE CODE

Available at: r.external source code (history)
Latest change: Tuesday Apr 01 04:59:21 2025 in commit 8bb8306