i.basemap - GRASS manual

NAME

i.basemap - Import basemaps from various web map services

KEYWORDS

SYNOPSIS

i.basemap

i.basemap --help

i.basemap [-lcrob] output=name [server=string] [url=string] [maxcols=integer] [maxrows=integer] [srs=string] [format=string] [composite_levels=integer] [--overwrite] [--help] [--verbose] [--quiet] [--ui]

Flags:

-l: List available web map servers
-c: Use current computational region
-r: Reproject to current location's projection
-o: Overwrite existing maps
-b: Keep separate red/green/blue band maps instead of a single composite
--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:

output=name [required]: Name for output raster map(s)
server=string: Web map server to use; Options: Google_Satellite, OpenStreetMap, Bing_Aerial, ESRI_WorldImagery, USGS_Topo, Google_Terrain, Google_Hybrid, Bing_Roads, Stamen_Terrain, Stamen_Toner, Stamen_Watercolor, OpenTopoMap, OSM_Humanitarian, Natural_Earth, USGS_NAIP, USGS_3DEP, USGS_Hydro, ESA_WorldCover, Copernicus_Sentinel, Landsat, MODIS, NOAA_Climate, ESA_Climate, WorldBank, UN_GeoWeb; Default: OpenStreetMap
url=string: Custom URL template for XYZ tiles (use {x}, {y}, {z} or {quadkey})
maxcols=integer: Maximum width of output map in pixels; Default: 1024
maxrows=integer: Maximum height of output map in pixels; Default: 1024
srs=string: Spatial reference system for the output; Default: EPSG:3857
format=string: Output format for downloaded tiles; Options: png, jpeg; Default: png
composite_levels=integer: Number of color levels per RGB channel used by r.composite (256 = lossless for 8-bit imagery); Options: 1-256; Default: 256

DESCRIPTION

The i.basemap module provides a comprehensive interface for downloading and importing base map data from 25 freely available web map servers with robust error handling, randomized downloads, and retry logic. All servers are fully functional (100% success rate). The module supports multiple web mapping standards including:

XYZ - Slippy map tiles (OpenStreetMap, Google, ESRI, etc.)
Quadkey - Bing Maps quadkey format (Bing Aerial, Bing Roads)
Automatic Detection - Routes to appropriate handler based on server type

AVAILABLE SERVERS

The module includes a comprehensive catalog of 25 freely available web map servers:

Web Mapping Services (XYZ)

OpenStreetMap - Free collaborative map of world (Max Zoom: 19)
ESRI_WorldImagery - High-resolution satellite and aerial imagery (Max Zoom: 19)
Google_Satellite - Google satellite imagery (Max Zoom: 20)
Google_Terrain - Google terrain maps with elevation data (Max Zoom: 15)
Google_Hybrid - Google hybrid satellite with road overlays (Max Zoom: 20)
Stamen_Terrain - Terrain maps with hillshading (Max Zoom: 18)
Stamen_Toner - High-contrast black and white maps (Max Zoom: 20)
Stamen_Watercolor - Artistic watercolor style maps (Max Zoom: 18)
OpenTopoMap - Topographic maps with hiking trails (Max Zoom: 17)
OSM_Humanitarian - Humanitarian response focused maps (Max Zoom: 20)
Natural_Earth - National Geographic style world map (Max Zoom: 16)
USGS_Topo - USGS topographic map data (Max Zoom: 16)
USGS_NAIP - USGS National Agriculture Imagery Program (Max Zoom: 18)
USGS_3DEP - USGS high-resolution elevation data (Max Zoom: 15)
USGS_Hydro - USGS hydrography data (Max Zoom: 16)
ESA_WorldCover - ESA 10m global land cover map (Max Zoom: 12)
Copernicus_Sentinel - Sentinel-2 satellite imagery (Max Zoom: 14)
Landsat - Landsat 8 satellite imagery (Max Zoom: 14)
MODIS - MODIS satellite data (Max Zoom: 10)
NOAA_Climate - NOAA climate and weather data (Max Zoom: 12)
ESA_Climate - ESA climate data and indicators (Max Zoom: 12)
WorldBank - World Bank development indicators (Max Zoom: 12)
UN_GeoWeb - United Nations geographic data (Max Zoom: 12)

Quadkey Services (Bing)

Bing_Aerial - Microsoft Bing aerial photography (Max Zoom: 19)
Bing_Roads - Microsoft Bing road maps (Max Zoom: 19)

USAGE EXAMPLES

Basic Usage

# List all available servers (25 total)
i.basemap -l

# Download OpenStreetMap for current region
i.basemap server=OpenStreetMap output=osm_map -c

# Download satellite imagery
i.basemap server=Google_Satellite output=satellite -c

# Download Bing aerial imagery
i.basemap server=Bing_Aerial output=aerial -c

Advanced Usage

# Custom URL with API key
i.basemap url="https://api.example.com/{z}/{x}/{y}?key={api_key}" output=custom api_key=your_key

# High resolution output
i.basemap server=ESRI_WorldImagery output=high_res maxcols=2048 maxrows=2048 -c

# Scientific data
i.basemap server=Copernicus_Sentinel output=sentinel -c
i.basemap server=Landsat output=landsat -c

# Climate data
i.basemap server=NOAA_Climate output=climate -c

TECHNICAL DETAILS

Coordinate System

Input: Supports projected or geographic coordinates
Transformation: Automatic conversion to lat/lon for XYZ tiles
Output: Reprojects to current GRASS location projection

Tile Processing

Download: Uses curl with connection timeouts
Validation: Basic image header verification
Retry: Up to 3 attempts per failed tile
Randomization: Tiles downloaded in random order
World Files: Automatic creation for georeferencing

Performance Features

Dynamic Zoom: Automatic zoom level selection based on region resolution
Overlap Buffer: 10% bbox expansion + 1-tile overlap
Memory Efficient: Temporary file cleanup
Error Recovery: Graceful handling of network issues

SERVER CATEGORIES

High-Resolution Satellite (8)

Google_Satellite, ESRI_WorldImagery, ESA_WorldCover, Landsat, MODIS, Copernicus_Sentinel, Bing_Aerial, USGS_NAIP

Topographic & Terrain (6)

USGS_Topo, OpenTopoMap, Stamen_Terrain, Google_Terrain, Natural_Earth, USGS_3DEP

Street & General Maps (7)

OpenStreetMap, OSM_Humanitarian, Google_Hybrid, Bing_Roads, NOAA_Climate, ESA_Climate, WorldBank

Artistic & Specialized (4)

Stamen_Toner, Stamen_Watercolor, UN_GeoWeb, USGS_Hydro

DEPENDENCIES

Required

GRASS GIS 8.5+: For core functionality
curl: For tile downloads
gdal: For VRT creation and import

Optional

pyproj: For coordinate transformation (auto-installed if needed)

TROUBLESHOOTING

Common Issues

No tiles downloaded
Check coordinate transformation and region bounds. Partial downloads
Network issues - retry logic handles automatically. Projection errors
Ensure GRASS location is properly set. Memory issues
Reduce maxcols/maxrows for large regions.

Performance Tips

Smaller regions: Faster downloads and processing
Appropriate zoom: Let script auto-select based on resolution
Network stability: Wired connection preferred for large downloads

SOURCE CODE

Available at: i.basemap source code (history)

Accessed: Monday Jul 27 12:22:26 2026