vrt.VRT

A GDAL Virtual Dataset.

Usage

vrt.VRT(
    crs,
    transform,
    width,
    height,
    bands=list(),
    metadata=dict(),
    warp=None,
    metadata_domains=dict()
)

Parameters

crs: CRS | None: Coordinate reference system.
transform: Affine: Pixel-to-CRS affine transform.
width: int: Raster size in pixels.
height: int: Raster size in pixels.
bands: list[Band] = list(): Bands in order.
metadata: dict[str, str] = dict(): Dataset metadata items.
warp: Warp | None = None: Set for a warped VRT, whose bands then carry no sources.
metadata_domains: dict[str, dict[str, str]] = dict(): Dataset metadata items of named domains, such as IMAGE_STRUCTURE, by domain.

Attributes

Name	Description
sources	Direct sources in document order, then the warp source.

sources

Direct sources in document order, then the warp source.

sources: list[SourceRef]

Duplicates are removed: files by path, nested VRTs by identity. No I/O.

Methods

Name	Description
env()	Return the rasterio environment that can read every source.
open()	Open the VRT from memory, without writing a file.
source_files()	Return the leaf files the VRT reads, recursing into nested VRTs.
to_xml()	Serialize to VRT XML.
write()	Write the VRT to `path`.

env()

Return the rasterio environment that can read every source.

Usage

Source

env(*, storage_options=None)

Local sources need a plain environment, S3 sources the credentialed S3 environment, public HTTP(S) sources the HTTP one. Local sources mix with either. Callers using thread pools enter it in the main thread, because credentials set in a worker thread don’t reach GDAL’s reader threads.

Parameters

storage_options: Mapping[str, Any] | None = None: Options for the VRT files followed to find the sources, as for source_files.

Returns

AbstractContextManager[None]: Context manager that applies the environment while active.

Raises

ValueError: If S3 sources have different storage options, S3 is mixed with HTTP(S), or a source uses another protocol, or as source_files.
ImportError: As source_files.

open()

Open the VRT from memory, without writing a file.

Usage

Source

open(*, storage_options=None, **kwargs)

Parameters

storage_options: Mapping[str, Any] | None = None: Passed to env().
**kwargs: Any: Passed to rasterio.open.

Returns

AbstractContextManager[DatasetReader]: Context manager yielding the dataset inside env().

Raises

ValueError: As env(), or if a dtype has no GDAL equivalent.
ImportError: As env().

source_files()

Return the leaf files the VRT reads, recursing into nested VRTs.

Usage

Source

source_files(*, follow=True, storage_options=None)

Followed VRT files are scanned for <SourceFilename> and <SourceDataset> only, so they may hold elements read refuses; sources of any other kind, and paths on GDAL virtual file systems other than /vsis3/ and /vsicurl/, are not listed.

Parameters

follow: bool = True: Read .vrt file sources and recurse into them; False lists them as files.
storage_options: Mapping[str, Any] | None = None: Options for reading followed VRT files and their S3 sources, as for read. None keeps each path’s own, and a followed file without any inherits those of the VRT that references it.

Returns

list[UPath]: Files in first-seen order, without duplicates.

Raises

ValueError: If a followed VRT file names a relative source path inside an in-memory VRT.
ImportError: If a followed VRT file is http(s):// and aiohttp is not installed.

to_xml()

Serialize to VRT XML.

Usage

Source

to_xml(*, relative_to=None)

Parameters

relative_to: UPath | None = None: Path of the VRT file that source paths are written relative to; None writes absolute paths.

Returns

str: The <VRTDataset> document.

Raises

ValueError: If a band or source dtype has no GDAL equivalent, a metadata_domains key is empty, or a band of a warped VRT has sources or a pixel function.
RuntimeError: If a source is a nested VRT and rasterio’s GDAL is older than 3.11.

write()

Write the VRT to path.

Usage

Source

write(path, *, relative=True)

Sources on the same store as path (local, or the same S3 bucket) are written relative to it; others as absolute GDAL paths. Local writes are atomic.

Parameters

path: str | Path | UPath: Destination, local (a path or file://) or s3://.
relative: bool = True: False writes every source path absolute.

Returns

UPath: The path written.

Raises

ValueError: If path is neither local nor s3://, or as to_xml.
RuntimeError: If a source is a nested VRT and rasterio’s GDAL is older than 3.11.