---
name: "r.external"
section: "1grass"
platform: "linux"
package: "grass-doc"
version: "8.4.1-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/r.external"
---

# r.external(1grass)

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

## NAME

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

## KEYWORDS

raster, import, external

## SYNOPSIS

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

### Flags:

- **-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

- **--ui**

  Force launching GUI dialog

### 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

## 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 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).

## 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)

Accessed: Monday Feb 24 17:50:37 2025

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

© 2003-2025 GRASS Development Team, GRASS GIS 8.4.1 Reference Manual