## vrt.VRT A GDAL Virtual Dataset. Usage ``` python 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](#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()](#env) | Return the rasterio environment that can read every source. | | [open()](#open) | Open the VRT from memory, without writing a file. | | [source_files()](#source_files) | Return the leaf files the VRT reads, recursing into nested VRTs. | | [to_xml()](#to_xml) | Serialize to VRT XML. | | [write()](#write) | Write the VRT to `path`. | ------------------------------------------------------------------------ #### env() Return the rasterio environment that can read every source. Usage ``` python 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](vrt.VRT.md#freezebase.vrt.VRT.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](vrt.VRT.md#freezebase.vrt.VRT.source_files). `ImportError` As [source_files](vrt.VRT.md#freezebase.vrt.VRT.source_files). ------------------------------------------------------------------------ #### open() Open the VRT from memory, without writing a file. Usage ``` python open(*, storage_options=None, **kwargs) ``` ##### Parameters `storage_options: Mapping[str, Any] | None = None` Passed to [env()](vrt.VRT.md#freezebase.vrt.VRT.env). `**kwargs: Any` Passed to `rasterio.open`. ##### Returns `AbstractContextManager[DatasetReader]` Context manager yielding the dataset inside [env()](vrt.VRT.md#freezebase.vrt.VRT.env). ##### Raises `ValueError` As [env()](vrt.VRT.md#freezebase.vrt.VRT.env), or if a dtype has no GDAL equivalent. `ImportError` As [env()](vrt.VRT.md#freezebase.vrt.VRT.env). ------------------------------------------------------------------------ #### source_files() Return the leaf files the VRT reads, recursing into nested VRTs. Usage ``` python source_files(*, follow=True, storage_options=None) ``` Followed VRT files are scanned for `` and `` only, so they may hold elements [read](vrt.read.md#freezebase.vrt.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](vrt.read.md#freezebase.vrt.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 ``` python 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 `` 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 ``` python 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](vrt.VRT.md#freezebase.vrt.VRT.to_xml). `RuntimeError` If a source is a nested VRT and rasterio's GDAL is older than 3.11.