`gws.lib.gdalx`¶

GDAL/OGR wrapper.

This package provides a thin layer over the GDAL Python bindings (osgeo.gdal, osgeo.ogr) for reading and writing raster and vector data sets.

Data sets are opened with open_raster or open_vector, or created in memory from an image with open_from_image. If no driver name is given, the driver is chosen by the file extension. Data sets are context managers that flush and close themselves on exit.

RasterDataSet reads a raster into a gws.Image, reports its size and bounds, warps it to an image or a file (gdal.Warp), and saves copies in other formats.
VectorDataSet gives access to VectorLayer objects, creates new layers and runs transactions.
VectorLayer describes its columns, reads features as gws.FeatureRecord objects and inserts records.

Attribute values are converted between OGR field types and gws.AttributeType, geometries between OGR and gws.Shape. Geo-transforms always use the easting/longitude-first axis order.

Example:

import gws.lib.gdalx

with gws.lib.gdalx.open_raster('/data/ortho.tif') as ds:
    bounds = ds.bounds()
    img = ds.to_image()

with gws.lib.gdalx.open_vector('/data/out.gpkg', 'w') as ds:
    la = ds.create_layer('roads', {'name': gws.AttributeType.str}, gws.GeometryType.linestring, crs)
    la.insert(records)

Source code: gws.lib.gdalx

Package Contents¶

class gws.lib.gdalx.DriverInfo(*args, **kwargs)¶

Bases: gws.Data

Information about a GDAL driver.

extensions: list[str]¶: File extensions supported by the driver.

index: int¶: Driver index in GDAL.

longName: str¶: Long driver name, like GeoTIFF.

metaData: dict¶: Driver metadata.

name: str¶: Short driver name, like GTiff.

exception gws.lib.gdalx.Error¶

Bases: gws.Error

GDAL error.

gws.lib.gdalx.gdal_config(options: dict)¶

Context manager that temporarily sets GDAL config options.

The previous values are restored on exit.

Parameters:: options – GDAL config options, like {'GDAL_CACHEMAX': '512'}.

gws.lib.gdalx.get_driver(name: str) → DriverInfo | None¶

Get driver info by name.

Parameters:: name – Short driver name, like GTiff.
Returns:: Driver information, or None if the driver is not found.

gws.lib.gdalx.get_drivers() → list[DriverInfo]¶

Enumerate GDAL drivers.

Returns:: Information about all available drivers.

gws.lib.gdalx.open_from_image(image: gws.Image, bounds: gws.Bounds, rotation: gws.Size = None, options: dict = None) → RasterDataSet¶

Create an in-memory raster data set from an image.

Parameters:

image – Image object.
bounds – Bounds of the image.
rotation – Geo-transform rotation terms (x, y), no rotation by default.
options – Driver-specific creation options.

Returns:

The raster data set.

gws.lib.gdalx.open_raster(path: str, mode: str = 'r', driver: str = '', default_crs: gws.Crs | None = None, options: dict = None) → RasterDataSet¶

Open a raster data set.

Parameters:

path – File path.
mode – r (read), a (update) or w (create).
driver – Driver name. If omitted, the driver is chosen by the path extension.
default_crs – CRS to use if the data set has none, web mercator by default.
options – Driver-specific open or creation options.

Returns:

The raster data set.

Raises:

Error – If the mode is invalid, no suitable raster driver is found, or the data set cannot be opened or created.

gws.lib.gdalx.open_vector(path: str, mode: str = 'r', driver: str = '', encoding: str | None = 'utf8', default_crs: gws.Crs | None = None, geometry_as_text: bool = False, options: dict = None) → VectorDataSet¶

Open a vector data set.

Parameters:

path – File path.
mode – r (read), a (update) or w (create).
driver – Driver name. If omitted, the driver is chosen by the path extension.
encoding – Encoding of string attributes. If set, strings are decoded when reading, otherwise they are returned as bytes.
default_crs – CRS for geometries without one, web mercator by default.
geometry_as_text – Do not convert geometries to shapes, return them as EWKT in FeatureRecord.ewkt.
options – Driver-specific open or creation options.

Returns:

The vector data set.

Raises:

Error – If the mode is invalid, no suitable vector driver is found, or the data set cannot be opened or created.

class gws.lib.gdalx.RasterDataSet(dso: _DataSetOptions, gd_dataset)¶

Bases: _DataSet

Raster data set.

bounds() → gws.Bounds¶

Get the bounds of the raster, computed from its geo-transform.

Returns:: The bounds, in the data set CRS or the default CRS.

save_as(path: str, driver: str = '', strict=False, options: dict = None)¶

Save a copy of the data set, including its metadata.

Parameters:

path – Destination path.
driver – Driver name. If omitted, the driver is chosen by the path extension.
strict – Fail if the copy cannot be made exactly, for example, if the format does not support some data.
options – Driver-specific creation options.

Raises:

Error – If no suitable raster driver is found.

size() → gws.Size¶

Get the raster size.

Returns:: A (width, height) tuple in pixels.

to_image() → gws.Image¶

Convert the raster data set to an image.

Each raster band becomes an image channel, values are read as 8-bit.

Returns:: The image.

warp_to_image(options: dict) → gws.Image¶

Warp the data set in memory and return the result as an image.

See https://gdal.org/en/stable/api/python/utilities.html#osgeo.gdal.WarpOptions and https://gdal.org/en/stable/programs/gdalwarp.html for the options.

Parameters:: options – Keyword arguments for gdal.Warp. The format option is ignored.
Returns:: The warped image.
Raises:: Error – If the warp fails.

warp_to_path(path: str, options: dict)¶

Warp the data set and store it at the given path.

See https://gdal.org/en/stable/api/python/utilities.html#osgeo.gdal.WarpOptions and https://gdal.org/en/stable/programs/gdalwarp.html for the options.

Parameters:

path – Destination path.
options – Keyword arguments for gdal.Warp. If format is not given, it is chosen by the path extension.

Raises:

Error – If no driver is found for the path or the warp fails.

gws.lib.gdalx.supported_attribute_types()¶

Get attribute types that can be written to vector data sets.

Returns:: A list of gws.AttributeType values.

class gws.lib.gdalx.VectorDataSet(dso: _DataSetOptions, gd_dataset)¶

Bases: _DataSet

Vector data set.

create_layer(name: str, columns: dict[str, gws.AttributeType], geometry_type: gws.GeometryType = None, crs: gws.Crs = None, overwrite=False, options: dict = None) → VectorLayer¶

Create a new layer.

For Shapefiles, the data set encoding is passed to the driver.

Parameters:

name – Layer name.
columns – Map of column names to attribute types.
geometry_type – Geometry type. If omitted, the layer has no geometry.
crs – CRS for geometries, the default CRS of the data set by default.
overwrite – Overwrite an existing layer.
options – Driver-specific layer creation options.

Returns:

The new layer.

layer(name_or_index: str | int) → VectorLayer | None¶

Get a layer by name or index.

Parameters:: name_or_index – Layer name or index.
Returns:: The layer, or None if not found.

layers() → list[VectorLayer]¶

Get all layers.

Returns:: A list of layers.

require_layer(name_or_index: str | int) → VectorLayer¶

Get a layer by name or index, and fail if it is not found.

Parameters:: name_or_index – Layer name or index.
Returns:: The layer.
Raises:: Error – If the layer is not found.

transaction()¶

Context manager that runs a transaction.

The transaction is committed on success and rolled back on an exception.

Yields:: This data set.

class gws.lib.gdalx.VectorLayer(ds: VectorDataSet, gd_layer: osgeo.ogr.Layer)¶

Layer of a vector data set.

dso: _DataSetOptions¶: Options of the data set.

gdDefn: osgeo.ogr.FeatureDefn¶: Underlying OGR feature definition.

gdLayer: osgeo.ogr.Layer¶: Underlying OGR layer.

name: str¶: Layer name.

count(force=False)¶

Count features in the layer.

Parameters:: force – Count features even if this is expensive for the driver.
Returns:: The number of features, or -1 if the count is not available without force.

describe() → gws.DataSetDescription¶

Describe the layer columns.

The description includes the FID column (as the primary key), attribute columns of supported types, and geometry columns. If there are several geometry columns, the last one is used as the layer geometry.

Returns:: The layer description.

get(fid: int) → gws.FeatureRecord | None¶

Read a feature by its id.

Parameters:: fid – Feature id.
Returns:: The feature record, or None if not found.

get_all() → list[gws.FeatureRecord]¶

Read all features.

Returns:: A list of feature records.

insert(records: list[gws.FeatureRecord]) → list[int]¶

Insert feature records into the layer.

Integer record uids are used as feature ids. Attributes that are None or have no matching column are skipped.

Parameters:: records – Feature records.
Returns:: Feature ids of the inserted features.
Raises:: Error – If an attribute value cannot be set.

iter_features() → Iterable[gws.FeatureRecord]¶

Iterate over all features.

Yields:: Feature records. The record uid is the feature id as a string, meta['layerName'] is the layer name.

`gws.lib.gdalx`¶

Package Contents¶

Table of Contents

Previous topic

Next topic

gws.lib.gdalx¶

Package Contents¶

`gws.lib.gdalx`¶