torchgeo.datasets#

TorchGeo defines several kinds of datasets for geospatial data.

Benchmark Datasets#

Curated benchmark datasets allow for model training and evaluation. They typically provide both input images and output labels, and target a variety of downstream applications.

C = classification, R = regression, S = semantic segmentation, I = instance segmentation, T = time series, CD = change detection, OD = object detection, IC = image captioning#
Dataset	Task	Source	# Samples	# Classes	Size (px)	Resolution (m)	Bands	License
ADVANCE	C	Google Earth, Freesound	5,075	13	512x512	0.5	RGB	CC-BY-4.0
AgriFieldNet	S	Sentinel-2	7,081	14	256x256	10	MSI	CC-BY-4.0
Air Quality	R	Pirelli Labs multi-sensor device	9,358				air quality, weather	CC-BY-4.0
BRIGHT	CD	MAXAR, NAIP, Capella, Umbra	3239	4	1024x1024	0.1–1	RGB, SAR	CC-BY-4.0 AND CC-BY-NC-4.0
Benin Cashew Plantations	S	Airbus Pléiades	70	6	1,122x1,186	10	MSI	CC-BY-4.0
BioMassters	R	Sentinel-1/2 and Lidar			256x256	10	SAR, MSI	CC-BY-4.0
COWC	C, R	CSUAV AFRL, ISPRS, LINZ, AGRC	388,435	2	256x256	0.15	RGB	AGPL-3.0-only
CaBuAr	CD	Sentinel-2	424	2	512x512	20	MSI	OpenRAIL
CaFFe	S	Sentinel-1, TerraSAR-X, TanDEM-X, ENVISAT, ERS-1/2, ALOS PALSAR, and RADARSAT-1	19092	2 or 4	512x512	6-20	SAR	CC-BY-4.0
ChaBuD	CD	Sentinel-2	356	2	512x512	10	MSI	OpenRAIL
Chesapeake Land Cover	S	NAIP		13, 54		1	MSI	CC0-1.0
Cloud Cover Detection	S	Sentinel-2	22,728	2	512x512	10	MSI	CC-BY-4.0
CropHarvest	C	Sentinel-1/2, SRTM, ERA5	70,213	351	1x1	10	SAR, MSI, SRTM	CC-BY-SA-4.0
DFC2022	S	Aerial	3,981	15	2,000x2,000	0.5	RGB	CC-BY-4.0
DIOR	OD	Aerial	23,463	20	800x800	0.5	RGB	CC-BY-NC-4.0
DL4GAM	S	Sentinel-2	2,251 or 11,440	2	256x256	10	MSI	CC-BY-4.0
DLRSD	S	USGS National Map	2,100	17	256x256	0.3	RGB	CC-BY-4.0
DLRSD Multilabel	C	USGS National Map	2,100	17	256x256	0.3	RGB	CC-BY-4.0
DOTA	OD	Google Earth, Gaofen-2, Jilin-1, CycloMedia B.V.	5,229	15	800–4000		RGB	non-commercial
DeepGlobe Land Cover	S	DigitalGlobe +Vivid	803	7	2,448x2,448	0.5	RGB
Digital Typhoon	C, R	Himawari	189,364	8	512	5000	Infrared	CC-BY-4.0
ETCI2021 Flood Detection	S	Sentinel-1	66,810	2	256x256	5–20	SAR
EnviroAtlas	S	NAIP, NLCD, OpenStreetMap		10		1	MSI	CC-BY-4.0
EuroSAT	C	Sentinel-2	27,000	10	64x64	10	MSI	MIT
EverWatch	OD	Aerial	5,325	8	1,500x1500p	0.01	RGB	CC0-1.0
FAIR1M	OD	Gaofen/Google Earth	15,000	37	1,024x1,024	0.3–0.8	RGB	CC-BY-NC-SA-3.0
Fields Of The World	S,I	Sentinel-2	70795	2,3	256x256	10	MSI	Various
FireRisk	C	NAIP Aerial	91,872	7	320x320	1	RGB	CC-BY-NC-4.0
Forest Damage	OD	Drone imagery	1,543	4	1,500x1,500		RGB	CDLA-Permissive-1.0
GID-15	S	Gaofen-2	150	15	6,800x7,200	3	RGB
GeoNRW	S	Aerial	7,783	11	1,000x1,000	1	RGB, DEM	CC-BY-4.0
I/O Bench	S	Landsat, CDL	1		8,000x8,000	30	MSI	CC-BY-4.0
IDTReeS	OD,C	Aerial	591	33	200x200	0.1–1	RGB	CC-BY-4.0
Inria Aerial Image Labeling	S	Aerial	360	2	5,000x5,000	0.3	RGB
Kenya Crop Type	S	Sentinel-2	4,688	7	3,035x2,016	10	MSI	CC-BY-SA-4.0
L7 Irish	S	Landsat 7	206	5	8,400x7,500	15, 30	MSI	CC0-1.0
L8 Biome	S	Landsat 8	96	5	8,900x8,900	15, 30	MSI	CC0-1.0
LEVIR-CD+	CD	Google Earth	985	2	1,024x1,024	0.5	RGB
LEVIR-CD	CD	Google Earth	637	2	1,024x1,024	0.5	RGB
LandCover.ai	S	Aerial	10,674	5	512x512	0.25–0.5	RGB	CC-BY-NC-SA-4.0
LoveDA	S	Google Earth	5,987	7	1,024x1,024	0.3	RGB	CC-BY-NC-SA-4.0
MDAS	S	Sentinel-1/2,EnMAP,HySpex	3	20	100x120, 300x360, 1364x1636, 10000x12000, 15000x18000	0.3–30	HSI	CC-BY-SA-4.0
MMFlood	S	Sentinel, MapZen/TileZen, OpenStreetMap	1,748	2	2,147x2,313	20	SAR	MIT
MapInWild	S	Sentinel-1/2, ESA WorldCover, NOAA VIIRS DNB	1018	1	1920x1920	10–463.83	SAR, MSI, 2020_Map, avg_rad	CC-BY-4.0
NASA Marine Debris	OD	PlanetScope	707	1	256x256	3	RGB	Apache-2.0
OSCD	CD	Sentinel-2	24	2	241–1,180	60	MSI	CC-BY-NC-SA-4.0
PASTIS	I	Sentinel-1/2	2,433	19	128x128xT	10	MSI	CC-BY-4.0
PatternNet	C	Google Earth	30,400	38	256x256	0.06–5	RGB	CC-BY-4.0
Potsdam	S	Aerial	38	6	6,000x6,000	0.05	MSI
QuakeSet	C, R	Sentinel-1	3,327	2	512x512	10	SAR	OpenRAIL
RESISC45	C	Google Earth	31,500	45	256x256	0.2–30	RGB	CC-BY-NC-4.0
ReforesTree	OD, R	Aerial	100	6	4,000x4,000	0.02	RGB	CC-BY-4.0
Rwanda Field Boundary	S	Planetscope	70	2	256x256	4.7	RGB + NIR	NICFI AND CC-BY-4.0
SEN12MS	S	Sentinel-1/2, MODIS	180,662	33	256x256	10	SAR, MSI	CC-BY-4.0
SKIPP’D	R	Fish-eye	363,375		64x64		RGB	CC-BY-4.0
SODA	OD	Aerial	2513	9	~2700x~4800		RGB	CC-BY-NC-4.0
SSL4EO-L Benchmark	S	Lansat & CDL	25K	134	264x264	30	MSI	CC0-1.0
SSL4EO-L Benchmark	S	Lansat & NLCD	25K	17	264x264	30	MSI	CC0-1.0
SeasoNet	S	Sentinel-2	1,759,830	33	120x120	10	MSI	CC-BY-4.0
So2Sat	C	Sentinel-1/2	400,673	17	32x32	10	SAR, MSI	CC-BY-4.0
Solar Plants Brazil	S	Aerial	272	2	256x256	10	RGB + NIR	CC-BY-NC-4.0
South Africa Crop Type	S	Sentinel-2		10	256x256	10	MSI	CC-BY-4.0
Substation	S	OpenStreetMap & Sentinel-2	27K	2	228x228	10	MSI	CC-BY-4.0
SustainBench Crop Yield	R	MODIS	11k		32x32		MSI	CC-BY-SA-4.0
TreeSatAI	C, R, S	Aerial, Sentinel-1/2	50K	12, 15, 20	6, 20, 304	0.2, 10	CIR, MSI, SAR	CC-BY-4.0
Tropical Cyclone	R	GOES 8–16	108,110		256x256	4K–8K	MSI	CC-BY-4.0
UC Merced	C	USGS National Map	2,100	21	256x256	0.3	RGB	public domain
USAVars	R	NAIP Aerial	100K			4	RGB, NIR	CC-BY-4.0
VHR-10	I	Google Earth, Vaihingen	800	10	358–1,728	0.08–2	RGB	CC-BY-NC-4.0
Vaihingen	S	Aerial	33	6	1,281–3,816	0.09	RGB
Western USA Live Fuel Moisture	R	Landsat8, Sentinel-1	2615					CC-BY-NC-ND-4.0
ZueriCrop	I, T	Sentinel-2	116K	48	24x24	10	MSI	CC-BY-NC-4.0
xBD	CD	Maxar	3,732	4	1,024x1,024	0.8	RGB	CC-BY-NC-SA-4.0

Copernicus-Bench#

Copernicus-Bench is a comprehensive evaluation benchmark with 15 downstream tasks hierarchically organized across preprocessing (e.g., cloud removal), base applications (e.g., land cover classification), and specialized applications (e.g., air quality estimation). This benchmark enables systematic assessment of foundation model performances across various Sentinel missions on different levels of practical applications.

C = classification, R = regression, S = semantic segmentation, I = instance segmentation, T = time series, CD = change detection, OD = object detection, IC = image captioning#
Level	Dataset	Task	Source	# Samples	# Classes	Size (px)	Resolution (m)	Bands	License
L1	Cloud-S2	S	Sentinel-2	2,817	4	512x512	10	MSI	CC0-1.0
L1	Cloud-S3	S	Sentinel-3	1,995	5	256x256	300	MSI	CC-BY-4.0
L2	EuroSAT-S1	C	Sentinel-1	27,000	10	64x64	10	SAR	CC-BY-4.0
L2	EuroSAT-S2	C	Sentinel-2	27,000	10	64x64	10	SAR	MIT
L2	BigEarthNet-S1	C	Sentinel-1	24,002	19	120x120	10	SAR	CDLA-Permissive-1.0
L2	BigEarthNet-S2	C	Sentinel-2	24,002	19	120x120	10	MSI	CDLA-Permissive-1.0
L2	LC100Cls-S3	C	Sentinel-3	8,635	23	96x96	300	MSI	CC-BY-4.0
L2	LC100Seg-S3	S	Sentinel-3	8,635	23	96x96	300	MSI	CC-BY-4.0
L2	DFC2020-S1	S	Sentinel-1	5,128	10	256x256	10	SAR	CC-BY-4.0
L2	DFC2020-S2	S	Sentinel-2	5,128	10	256x256	10	MSI	CC-BY-4.0
L3	Flood-S1	CD	Sentinel-1	5,000	3	224x224	10	SAR	MIT
L3	LCZ-S2	C	Sentinel-2	25,000	17	32x32	10	MSI	CC-BY-4.0
L3	Biomass-S3	R	Sentinel-3	5,000		96x96	300	MSI	CC-BY-4.0
L3	AQ-NO2-S5P	R	Sentinel-5P	2,467		56x56	1,000		CC-BY-4.0
L3	AQ-O3-S5P	R	Sentinel-5P	2,467		56x56	1,000		CC-BY-4.0

SpaceNet#

The SpaceNet Dataset is hosted as an Amazon Web Services (AWS) Public Dataset. It contains ~67,000 square km of very high-resolution imagery, >11M building footprints, and ~20,000 km of road labels to ensure that there is adequate open source data available for geospatial machine learning research. SpaceNet Challenge Dataset’s have a combination of very high resolution satellite imagery and high quality corresponding labels for foundational mapping features such as building footprints or road networks.

C = classification, R = regression, S = semantic segmentation, I = instance segmentation, T = time series, CD = change detection, OD = object detection, IC = image captioning#
Dataset	Task	Source	# Samples	# Classes	Size (px)	Resolution (m)	Bands	License
SpaceNet 1	I	WorldView-2	9,735		406x439, 102x110	0.5–1	RGB, MSI	CC-BY-SA-4.0
SpaceNet 2	I	WorldView-3	14,119		650x650, 163x163	0.3–1.24	RGB, MSI	CC-BY-SA-4.0
SpaceNet 3	I	WorldView-3	3,477	7	1,300x1,300, 325x325	0.3–1.24	RGB, MSI	CC-BY-SA-4.0
SpaceNet 4	I	WorldView-2	1,991		900x900, 225x225	0.46–1.67	RGB, MSI	CC-BY-SA-4.0
SpaceNet 5	I	WorldView-3	2,588		1,300x1,300, 325x325	0.3–1.24	RGB, MSI	CC-BY-SA-4.0
SpaceNet 6	I	WorldView-2	5,462		900x900, 450x450	0.5–2	SAR, RGB, MSI	CC-BY-SA-4.0
SpaceNet 7	I	Dove	1,889		1,024x1,024	4	RGB	CC-BY-SA-4.0
SpaceNet 8	I	Maxar	1,289	8	1,300x1,300	0.3–0.8	RGB	CC-BY-SA-4.0

Pre-Training Datasets#

Pre-training datasets are designed for foundation model development, providing millions of input images with global distributions. These datasets may come with output labels for supervised pre-training, or come without output labels for self-supervised pre-training.

C = classification, R = regression, S = semantic segmentation, I = instance segmentation, T = time series, CD = change detection, OD = object detection, IC = image captioning, LE = location encoding#
Dataset	Task	Source	# Samples	# Classes	Size (px)	Resolution (m)	Bands	License
BigEarthNet	C	Sentinel-1/2	590,326	19–43	120x120	10	SAR, MSI	CDLA-Permissive-1.0
Copernicus-Pretrain	T	Sentinel-1/2/3/5P, DEM	18.7M		264x264 or 96x96 or 28x28 or 960x960	10–1000	SAR, MSI, Air Pollutants, DEM	CC-BY-4.0
HySpecNet-11k		EnMAP	11k		128	30	HSI	CC0-1.0
MMEarth	C, S	Aster, Sentinel, ERA5	100K–1M		128x128 or 64x64	10	MSI	CC-BY-4.0
Million-AID	C	Google Earth	1M	51–73		0.5–153	RGB
S2-100k	LE	Sentinel-2	100k		256x256	10	MSI	MIT
SSL4EO-L	T	Landsat	1M		264x264	30	MSI	CC0-1.0
SSL4EO-S12	T	Sentinel-1/2	1M		264x264	10	SAR, MSI	CC-BY-4.0
SatlasPretrain	C, R, S, I, OD	NAIP, Landsat, Sentinel	302M	137	512	0.6–30	SAR, MSI	ESA AND CC0-1.0 AND ODbL-1.0 AND CC-BY-4.0
Seasonal Contrast	T	Sentinel-2	100K–1M		264x264	10	MSI	CC-BY-4.0
SkyScript	IC	NAIP, orthophotos, Planet SkySat, Sentinel-2, Landsat 8–9	5.2M		100–1000	0.1–30	RGB	MIT

Embeddings Datasets#

Embeddings are low-dimensional representations generated by foundation models. There are both patch-based embeddings designed for similarity search and pixel-based embeddings designed for applications like land cover mapping.

Global coverage only implies land surfaces. Temporal resolution is divided into “snapshot” for embeddings generated from a single mosaic and “annual” for embeddings generated from annual time series data. *Product has sparse spatial or temporal coverage.#
Dataset	Kind	Spatial Extent	Spatial Resolution	Temporal Extent	Temporal Resolution	Dimensions	Dtype	License
Clay Embeddings v0 Sentinel	Patch	Global*	5.12 km	2018–2023*	Snapshot	768	float32	ODC-By-1.0
Clay Embeddings v1.5 NAIP	Patch	USA	154–256 m	2010–2021*	Snapshot	1024	float32	CC-BY-4.0
Major TOM Embeddings	Patch	Global	2.14–3.56 km	2015–2024*	Snapshot	2048	float32	CC-BY-SA-4.0
Earth Index Embeddings	Patch	Global	320 m	2024	Snapshot	384	float32	CC-BY-4.0
Copernicus-Embed	Patch	Global	0.25°	2021	Annual	768	float32	CC-BY-4.0
Clay Embeddings v1.5 Sentinel	Patch	Global	2.56 km	2024–2025	Snapshot	1024	float32	CC-BY-4.0
EarthEmbeddings	Patch	Global*	2.24–3.84 km	2015–2024*	Snapshot	256–1152	float16, float32	CC-BY-SA-4.0
Presto Embeddings	Pixel	Togo	10 m	2019–2020	Annual	128	uint16	CC-BY-4.0
Tessera Embeddings	Pixel	Global	10 m	2017–2025*	Annual	128	int8 → float32	CC0-1.0
Google Satellite Embedding	Pixel	Global	10 m	2017–2025	Annual	64	int8 → float64	CC-BY-4.0
Embedded Seamless Data	Pixel	Global	30 m	2000–2024	Annual	12	uint16 → float32	CC-BY-4.0

Image Sources#

Uncurated raster imagery can be used within TorchGeo, either for inference using a pre-trained model, or for training by combination with mask labels.

Dataset	Type	Source	Size (px)	Resolution (m)	License
Airphen	Imagery	Airphen	1,280x960	0.047–0.09
EnMAP	Imagery	EnMAP	1,200x1,200	30	EnMAP Data License
Landsat	Imagery	Landsat	8,900x8,900	30	public domain
NAIP	Imagery	Aerial	6,100x7,600	0.3–2	public domain
OpenAerialMap	Imagery	Aerial	256x256 OR 512x512	0.03–50	CC-BY-4.0
PRISMA	Imagery	PRISMA	512x512	5–30
Sentinel	Imagery	Sentinel	10,000x10,000	10	CC-BY-SA-3.0-IGO

Mask Labels#

Uncurated raster and vector masks can be used within TorchGeo, typically in combination with an image source for model training.

Dataset	Type	Source	Size (px)	Resolution (m)	License
Aboveground Woody Biomass	Masks	Landsat, LiDAR	40,000x40,000	30	CC-BY-4.0
Aster Global DEM	DEM	Aster	3,601x3,601	30	public domain
Canadian Building Footprints	Geometries	Bing Imagery			ODbL-1.0
Cropland Data Layer	Masks	Landsat		30	public domain
EDDMapS	Points	Citizen Scientists
EU-DEM	DEM	Aster, SRTM, Russian Topomaps		25	CSCDA-ESA
Esri2020	Masks	Sentinel-2		10	CC-BY-4.0
EuroCrops	Geometries	EU Countries			CC-BY-SA-4.0
GBIF	Points	Citizen Scientists			CC0-1.0 OR CC-BY-4.0 OR CC-BY-NC-4.0
GlobBiomass	Masks	Landsat	45,000x45,000	100	CC-BY-4.0
Global Mangrove Distribution	Masks	Remote Sensing, In Situ Measurements		3	public domain
GlobalBuildingMap	Masks	PlanetScope	180K	3	CC-BY-4.0
NCCM	Masks	Sentinel-2		10	CC-BY-4.0
NLCD	Masks	Landsat		30	public domain
Open Buildings	Geometries	Maxar, CNES/Airbus			CC-BY-4.0 OR ODbL-1.0
OpenStreetMap	Geometries	OpenStreetMap			ODbL-1.0
South America Soybean	Masks	Landsat, MODIS		30
iNaturalist	Points	Citizen Scientists

Toy Datasets#

Toy datasets are tiny, ~100 image datasets designed for tutorials, demos, or few-shot learning.

C = classification, R = regression, S = semantic segmentation, I = instance segmentation, T = time series, CD = change detection, OD = object detection, IC = image captioning#
Dataset	Task	Source	# Samples	# Classes	Size (px)	Resolution (m)	Bands	License
EuroSAT 100	C	Sentinel-2	27,000	10	64x64	10	MSI	MIT
LandCover.ai 100	S	Aerial	10,674	5	512x512	0.25–0.5	RGB	CC-BY-NC-SA-4.0
OSCD 100	CD	Sentinel-2	24	2	241–1,180	60	MSI	CC-BY-NC-SA-4.0
PASTIS 100	I	Sentinel-1/2	2,433	19	128x128xT	10	MSI	CC-BY-4.0

Base Classes#

If you want to write your own custom dataset, you can extend one of these abstract base classes.

GeoDataset#

class torchgeo.datasets.GeoDataset[source]#

Bases: Dataset[dict[str, Any]], ABC, PlottingMixin

Abstract base class for datasets containing geospatial information.

Geospatial information includes things like:

coordinates (latitude, longitude)
coordinate reference system (CRS)
resolution

GeoDataset is a special class of datasets. Unlike NonGeoDataset, the presence of geospatial information allows two or more datasets to be combined based on latitude/longitude. This allows users to do things like:

Combine image and target labels and sample from both simultaneously (e.g., Landsat and CDL)
Combine datasets for multiple image sources for multimodal learning or data fusion (e.g., Landsat and Sentinel)
Combine image and other raster data (e.g., elevation, temperature, pressure) and sample from both simultaneously (e.g., Landsat and Aster Global DEM)

These combinations require that all queries are present in both datasets, and can be combined using an IntersectionDataset:

dataset = landsat & cdl

Users may also want to:

Combine datasets for multiple image sources and treat them as equivalent (e.g., Landsat 7 and Landsat 8)
Combine datasets for disparate geospatial locations (e.g., Chesapeake NY and PA)

These combinations require that all queries are present in at least one dataset, and can be combined using a UnionDataset:

dataset = landsat7 | landsat8

filename_glob = '*'#

Glob expression used to search for files.

This expression should be specific enough that it will not pick up files from other datasets. It should not include a file extension, as the dataset may be in a different file format than what it was originally downloaded as.

__add__ = None#: GeoDataset addition can be ambiguous and is no longer supported. Users should instead use the intersection or union operator.

abstractmethod __getitem__(index)[source]#

Retrieve input, target, and/or metadata indexed by spatiotemporal slice.

Parameters:: index (slice | tuple[slice] | tuple[slice, slice] | tuple[slice, slice, slice]) – [xmin:xmax:xres, ymin:ymax:yres, tmin:tmax:tres] coordinates to index.
Returns:: Sample of input, target, and/or metadata at that index.
Raises:: IndexError – If index is not found in the dataset.
Return type:: dict[str, Any]

__and__(other)[source]#

Take the intersection of two GeoDataset.

Parameters:: other (GeoDataset) – another dataset
Returns:: a single dataset
Raises:: ValueError – if other is not a GeoDataset
Return type:: IntersectionDataset

Added in version 0.2.

__or__(other)[source]#

Take the union of two GeoDatasets.

Parameters:: other (GeoDataset) – another dataset
Returns:: a single dataset
Raises:: ValueError – if other is not a GeoDataset
Return type:: UnionDataset

Added in version 0.2.

__len__()[source]#

Return the number of files in the dataset.

Returns:: length of the dataset
Return type:: int

__str__()[source]#

Return the informal string representation of the object.

Returns:: informal string representation
Return type:: str

property bounds: tuple[slice, slice, slice]#

Bounds of the index.

Returns:: Bounding x, y, and t slices.

property crs: CRS#

coordinate reference system (CRS) of the dataset.

Returns:: The coordinate reference system (CRS).

property res: tuple[float, float]#

Resolution of the dataset in units of CRS.

Returns:: The resolution of the dataset.

property files: list[str]#

A list of all files in the dataset.

Returns:: All files in the dataset.

Added in version 0.5.

RasterDataset#

class torchgeo.datasets.RasterDataset(paths='data', crs=None, res=None, bands=None, transforms=None, cache=True, time_series=False)[source]#

Bases: GeoDataset

Abstract base class for GeoDataset stored as raster files.

filename_regex = '.*'#

Regular expression used to extract date from filename.

The expression should use named groups. The expression may contain any number of groups. The following groups are specifically searched for by the base class:

date: used to calculate mint and maxt for index insertion
start: used to calculate mint for index insertion
stop: used to calculate maxt for index insertion

When separate_files is True, the following additional groups are searched for to find other files:

band: replaced with requested band name

date_format = '%Y%m%d'#

Date format string used to parse date from filename.

Not used if filename_regex does not contain a date group or start and stop groups.

mint: datetime = Timestamp('1677-09-21 00:12:43.145224193')#: Minimum timestamp if not in filename

maxt: datetime = Timestamp('2262-04-11 23:47:16.854775807')#: Maximum timestamp if not in filename

is_image = True#

True if the dataset only contains model inputs (such as images). False if the dataset only contains ground truth model outputs (such as segmentation masks).

The sample returned by the dataset/data loader will use the “image” key if is_image is True, otherwise it will use the “mask” key.

For datasets with both model inputs and outputs, the recommended approach is to use 2 RasterDataset instances and combine them using an IntersectionDataset.

separate_files = False#: True if data is stored in a separate file for each band, else False.

property dtype: dtype#

The dtype of the dataset (overrides the dtype of the data file via a cast).

Defaults to float32 if is_image is True, else long. Can be overridden for tasks like pixel-wise regression where the mask should be float32 instead of long.

Returns:: the dtype of the dataset

Added in version 0.5.

property resampling: Resampling#

Resampling algorithm used when reading input files.

Defaults to bilinear for float dtypes and nearest for int dtypes.

Returns:: The resampling method to use.

Added in version 0.6.

__init__(paths='data', crs=None, res=None, bands=None, transforms=None, cache=True, time_series=False)[source]#

Initialize a new RasterDataset instance.

Parameters:

paths (str | PathLike[str] | Iterable[str | PathLike[str]]) – one or more root directories to search or files to load
crs (CRS | None) – coordinate reference system (CRS) to warp to (defaults to the CRS of the first file found)
res (float | tuple[float, float] | None) – resolution of the dataset in units of CRS (defaults to the resolution of the first file found)
bands (Sequence[str] | None) – bands to return (defaults to all bands)
transforms (Callable[[dict[str, Any]], dict[str, Any]] | None) – a function/transform that takes an input sample and returns a transformed version
cache (bool) – if True, cache file handle to speed up repeated sampling
time_series (bool) – if True, stack data along the time series dimension (typically [T, C, H, W]). If False, merge data into a mosaic (typically [C, H, W]). For mask-style datasets (is_image=False), single-band data may have the channel dimension squeezed, resulting in shapes [T, H, W] or [H, W] when C == 1.

Raises:

AssertionError – If bands are invalid.
DatasetNotFoundError – If dataset is not found.

Added in version 0.9: The time_series parameter.

Changed in version 0.5: root was renamed to paths.

__getitem__(index)[source]#

Retrieve input, target, and/or metadata indexed by spatiotemporal slice.

Parameters:: index (slice | tuple[slice] | tuple[slice, slice] | tuple[slice, slice, slice]) – [xmin:xmax:xres, ymin:ymax:yres, tmin:tmax:tres] coordinates to index.
Returns:: Sample of input, target, and/or metadata at that index.
Raises:: IndexError – If index is not found in the dataset.
Return type:: dict[str, Any]

VectorDataset#

class torchgeo.datasets.VectorDataset(paths='data', crs=None, res=(0.0001, 0.0001), transforms=None, label_name=None, task='semantic_segmentation', layer=None)[source]#

Bases: GeoDataset

Abstract base class for GeoDataset stored as vector files.

filename_regex = '.*'#

Regular expression used to extract date from filename.

The expression should use named groups. The expression may contain any number of groups. The following groups are specifically searched for by the base class:

date: used to calculate mint and maxt for index insertion

date_format = '%Y%m%d'#

Date format string used to parse date from filename.

Not used if filename_regex does not contain a date group.

property dtype: dtype#

The dtype of the dataset (overrides the dtype of the data file via a cast).

Defaults to long.

Returns:: the dtype of the dataset

Added in version 0.6.

__init__(paths='data', crs=None, res=(0.0001, 0.0001), transforms=None, label_name=None, task='semantic_segmentation', layer=None)[source]#

Initialize a new VectorDataset instance.

Parameters:

paths (str | PathLike[str] | Iterable[str | PathLike[str]]) – one or more root directories to search or files to load
crs (CRS | None) – coordinate reference system (CRS) to warp to (defaults to the CRS of the first file found)
res (float | tuple[float, float]) – resolution of the dataset in units of CRS
transforms (Callable[[dict[str, Any]], dict[str, Any]] | None) – a function/transform that takes input sample and its target as entry and returns a transformed version
label_name (str | None) – name of the dataset property that has the label to be rasterized into the mask
task (Literal['object_detection', 'semantic_segmentation', 'instance_segmentation']) – computer vision task the dataset is used for. Supported output types object_detection, semantic_segmentation, instance_segmentation
layer (str | int | None) – if the input is a multilayer vector dataset, such as a geopackage, specify which layer to use. Can be int to specify the index of the layer, str to select the layer with that name or None which opens the first layer

Raises:

DatasetNotFoundError – If dataset is not found.
ValueError – If task is not one of allowed tasks

Added in version 0.4: The label_name parameter.

Changed in version 0.5: root was renamed to paths.

Added in version 0.8: The task and layer parameters

__getitem__(index)[source]#

Retrieve input, target, and/or metadata indexed by spatiotemporal slice.

Parameters:: index (slice | tuple[slice] | tuple[slice, slice] | tuple[slice, slice, slice]) – [xmin:xmax:xres, ymin:ymax:yres, tmin:tmax:tres] coordinates to index.
Returns:: Sample of input, target, and/or metadata at that index.
Raises:: IndexError – If index is not found in the dataset.
Return type:: dict[str, Any]

get_label(feature)[source]#

Get label value to use for rendering a feature.

Parameters:: feature (Series) – the row from the GeoDataFrame from which to extract the label.
Returns:: the integer label, or 0 if the feature should not be rendered.
Return type:: int

Added in version 0.6.

Changed in version 0.8: The feature parameter changed to a pandas.Series

NonGeoDataset#

class torchgeo.datasets.NonGeoDataset[source]#

Bases: Dataset[dict[str, Any]], ABC, PlottingMixin

Abstract base class for datasets lacking geospatial information.

This base class is designed for datasets with pre-defined image chips.

abstractmethod __getitem__(index)[source]#

Return an index within the dataset.

Parameters:: index (int) – index to return
Returns:: data and labels at that index
Raises:: IndexError – if index is out of range of the dataset
Return type:: dict[str, Any]

abstractmethod __len__()[source]#

Return the length of the dataset.

Returns:: length of the dataset
Return type:: int

__str__()[source]#

Return the informal string representation of the object.

Returns:: informal string representation
Return type:: str

NonGeoClassificationDataset#

class torchgeo.datasets.NonGeoClassificationDataset(root='data', transforms=None, loader=<function default_loader>, is_valid_file=None)[source]#

Bases: NonGeoDataset, ImageFolder

Abstract base class for classification datasets lacking geospatial information.

This base class is designed for datasets with pre-defined image chips which are separated into separate folders per class.

__init__(root='data', transforms=None, loader=<function default_loader>, is_valid_file=None)[source]#

Initialize a new NonGeoClassificationDataset instance.

Parameters:

root (str | PathLike[str]) – root directory where dataset can be found
transforms (Callable[[dict[str, Any]], dict[str, Any]] | None) – a function/transform that takes input sample and its target as entry and returns a transformed version
loader (Callable[[str], Image | NDArray[generic]]) – a callable function which takes as input a path to an image and returns a PIL Image or numpy array
is_valid_file (Callable[[str | PathLike[str]], bool] | None) – A function that takes the path of an Image file and checks if the file is a valid file

__getitem__(index)[source]#

Return an index within the dataset.

Parameters:: index (int) – index to return
Returns:: data and label at that index
Return type:: dict[str, Any]

__len__()[source]#

Return the number of data points in the dataset.

Returns:: length of the dataset
Return type:: int

IntersectionDataset#

class torchgeo.datasets.IntersectionDataset(dataset1, dataset2, spatial_only=False, collate_fn=<function concat_samples>, transforms=None)[source]#

Bases: GeoDataset

Dataset representing the intersection of two GeoDatasets.

This allows users to do things like:

Combine image and target labels and sample from both simultaneously (e.g., Landsat and CDL)
Combine datasets for multiple image sources for multimodal learning or data fusion (e.g., Landsat and Sentinel)
Combine image and other raster data (e.g., elevation, temperature, pressure) and sample from both simultaneously (e.g., Landsat and Aster Global DEM)

These combinations require that all queries are present in both datasets, and can be combined using an IntersectionDataset:

dataset = landsat & cdl

Added in version 0.2.

__init__(dataset1, dataset2, spatial_only=False, collate_fn=<function concat_samples>, transforms=None)[source]#

Initialize a new IntersectionDataset instance.

When computing the intersection between two datasets that both contain model inputs (such as images) or model outputs (such as masks), the default behavior is to stack the data along the channel dimension. The collate_fn parameter can be used to change this behavior.

Parameters:

dataset1 (GeoDataset) – the first dataset
dataset2 (GeoDataset) – the second dataset
spatial_only (bool) – if True, ignore temporal dimension when computing intersection
collate_fn (Callable[[Sequence[dict[str, Any]]], dict[str, Any]]) – function used to collate samples
transforms (Callable[[dict[str, Any]], dict[str, Any]] | None) – a function/transform that takes input sample and its target as entry and returns a transformed version

Raises:

RuntimeError – if datasets have no spatiotemporal intersection
ValueError – if either dataset is not a GeoDataset

Added in version 0.8: The spatial_only parameter.

Added in version 0.4: The transforms parameter.

__getitem__(index)[source]#

Retrieve input, target, and/or metadata indexed by spatiotemporal slice.

Parameters:: index (slice | tuple[slice] | tuple[slice, slice] | tuple[slice, slice, slice]) – [xmin:xmax:xres, ymin:ymax:yres, tmin:tmax:tres] coordinates to index.
Returns:: Sample of input, target, and/or metadata at that index.
Raises:: IndexError – If index is not found in the dataset.
Return type:: dict[str, Any]

__str__()[source]#

Return the informal string representation of the object.

Returns:: informal string representation
Return type:: str

property crs: CRS#

coordinate reference system (CRS) of both datasets.

Returns:: The coordinate reference system (CRS).

property res: tuple[float, float]#

Resolution of both datasets in units of CRS.

Returns:: Resolution of both datasets.

UnionDataset#

class torchgeo.datasets.UnionDataset(dataset1, dataset2, collate_fn=<function merge_samples>, transforms=None)[source]#

Bases: GeoDataset

Dataset representing the union of two GeoDatasets.

This allows users to do things like:

Combine datasets for multiple image sources and treat them as equivalent (e.g., Landsat 7 and Landsat 8)
Combine datasets for disparate geospatial locations (e.g., Chesapeake NY and PA)

These combinations require that all queries are present in at least one dataset, and can be combined using a UnionDataset:

dataset = landsat7 | landsat8

Added in version 0.2.

__init__(dataset1, dataset2, collate_fn=<function merge_samples>, transforms=None)[source]#

Initialize a new UnionDataset instance.

When computing the union between two datasets that both contain model inputs (such as images) or model outputs (such as masks), the default behavior is to merge the data to create a single image/mask. The collate_fn parameter can be used to change this behavior.

Parameters:

dataset1 (GeoDataset) – the first dataset
dataset2 (GeoDataset) – the second dataset
collate_fn (Callable[[Sequence[dict[str, Any]]], dict[str, Any]]) – function used to collate samples
transforms (Callable[[dict[str, Any]], dict[str, Any]] | None) – a function/transform that takes input sample and its target as entry and returns a transformed version

Raises:

ValueError – if either dataset is not a GeoDataset

Added in version 0.4: The transforms parameter.

__getitem__(index)[source]#

Retrieve input, target, and/or metadata indexed by spatiotemporal slice.

Parameters:: index (slice | tuple[slice] | tuple[slice, slice] | tuple[slice, slice, slice]) – [xmin:xmax:xres, ymin:ymax:yres, tmin:tmax:tres] coordinates to index.
Returns:: Sample of input, target, and/or metadata at that index.
Raises:: IndexError – If index is not found in the dataset.
Return type:: dict[str, Any]

__str__()[source]#

Return the informal string representation of the object.

Returns:: informal string representation
Return type:: str

property crs: CRS#

coordinate reference system (CRS) of both datasets.

Returns:: The coordinate reference system (CRS).

property res: tuple[float, float]#

Resolution of both datasets in units of CRS.

Returns:: The resolution of both datasets.

Mixins#

class torchgeo.datasets.PlottingMixin[source]#

Bases: object

Mixin for dataset plotting.

Added in version 0.10.

all_bands: tuple[str, ...] = ()#: Names of all available bands in the dataset

rgb_bands: tuple[str, ...] = ()#: Names of RGB bands in the dataset

cmap: str | Colormap | None = None#: Color map for the dataset

__weakref__#: list of weak references to the object

Utilities#

Collation Functions#

torchgeo.datasets.stack_samples(samples)[source]#

Stack a list of samples along a new axis.

Useful for forming a mini-batch of samples to pass to torch.utils.data.DataLoader.

Parameters:: samples (Iterable[dict[str, Any]]) – list of samples
Returns:: a single sample
Return type:: dict[str, Any]

Added in version 0.2.

torchgeo.datasets.concat_samples(samples)[source]#

Concatenate a list of samples along an existing axis.

Useful for joining samples in a torchgeo.datasets.IntersectionDataset.

Parameters:: samples (Iterable[dict[str, Any]]) – list of samples
Returns:: a single sample
Return type:: dict[str, Any]

Added in version 0.2.

torchgeo.datasets.merge_samples(samples)[source]#

Merge a list of samples.

Useful for joining samples in a torchgeo.datasets.UnionDataset.

Parameters:: samples (Iterable[dict[str, Any]]) – list of samples
Returns:: a single sample
Return type:: dict[str, Any]

Added in version 0.2.

torchgeo.datasets.unbind_samples(sample)[source]#

Reverse of stack_samples().

Useful for turning a mini-batch of samples into a list of samples. These individual samples can then be plotted using a dataset’s plot method.

Parameters:: sample (dict[str, Any]) – a mini-batch of samples
Returns:: list of samples
Return type:: list[dict[str, Any]]

Added in version 0.2.

Splitting Functions#

torchgeo.datasets.random_bbox_assignment(dataset, lengths, generator=<torch._C.Generator object>)[source]#

Split a GeoDataset randomly assigning its index’s objects.

This function will go through each object in the GeoDataset’s index and randomly assign it to new GeoDatasets.

Parameters:

dataset (GeoDataset) – dataset to be split
lengths (Sequence[float]) – lengths or fractions of splits to be produced
generator (Generator | None) – (optional) generator used for the random permutation

Returns:

A list of the subset datasets.

Return type:

list[GeoDataset]

Added in version 0.5.

torchgeo.datasets.random_bbox_splitting(dataset, fractions, generator=<torch._C.Generator object>)[source]#

Split a GeoDataset randomly splitting its index’s objects.

This function will go through each object in the GeoDataset’s index, split it in a random direction and assign the resulting objects to new GeoDatasets.

Parameters:

dataset (GeoDataset) – dataset to be split
fractions (Sequence[float]) – fractions of splits to be produced
generator (Generator | None) – generator used for the random permutation

Returns:

A list of the subset datasets.

Return type:

list[GeoDataset]

Added in version 0.5.

torchgeo.datasets.random_grid_cell_assignment(dataset, fractions, grid_size=6, generator=<torch._C.Generator object>)[source]#

Overlays a grid over a GeoDataset and randomly assigns cells to new GeoDatasets.

This function will go through each object in the GeoDataset’s index, overlay a grid over it, and randomly assign each cell to new GeoDatasets.

Parameters:

dataset (GeoDataset) – dataset to be split
fractions (Sequence[float]) – fractions of splits to be produced
grid_size (int) – number of rows and columns for the grid
generator (Generator | None) – generator used for the random permutation

Returns:

A list of the subset datasets.

Return type:

list[GeoDataset]

Added in version 0.5.

torchgeo.datasets.roi_split(dataset, rois)[source]#

Split a GeoDataset intersecting it with a ROI for each desired new GeoDataset.

Parameters:

dataset (GeoDataset) – dataset to be split
rois (Sequence[Polygon]) – regions of interest of splits to be produced

Returns:

A list of the subset datasets.

Return type:

list[GeoDataset]

Added in version 0.5.

torchgeo.datasets.time_series_split(dataset, lengths)[source]#

Split a GeoDataset on its time dimension to create non-overlapping GeoDatasets.

Parameters:

dataset (GeoDataset) – dataset to be split
lengths (Sequence[float] | Sequence[Timedelta] | Sequence[Interval]) – lengths, fractions or pairs of timestamps (start, end) of splits to be produced

Returns:

A list of the subset datasets.

Return type:

list[GeoDataset]

Added in version 0.5.

Errors#

class torchgeo.datasets.DatasetNotFoundError(dataset)[source]#

Bases: FileNotFoundError

Raised when a dataset is requested but doesn’t exist.

Added in version 0.6.

__init__(dataset)[source]#

Initialize a new DatasetNotFoundError instance.

Parameters:: dataset (Dataset[object]) – The dataset that was requested.

__weakref__#: list of weak references to the object

class torchgeo.datasets.DependencyNotFoundError[source]#

Bases: Exception

Raised when an optional dataset dependency is not installed.

Added in version 0.6.

__weakref__#: list of weak references to the object

class torchgeo.datasets.RGBBandsMissingError[source]#

Bases: ValueError

Raised when a dataset is missing RGB bands for plotting.

Added in version 0.6.

__init__()[source]#

Initialize a new RGBBandsMissingError instance.

__weakref__#: list of weak references to the object