Vector¶

`bbox`	create a bounding box vector object or file.
`boundary`	Get the boundary of the largest geometry as new vector object.
`centerdist`	Get the center distance between two vector objects.
`dissolve`	dissolve the polygons of a vector file by an attribute field
`feature2vector`	create a Vector object from ogr features
`intersect`	intersect two Vector objects
`set_field`	Wrapper for setting a field
`Vector`	This is intended as a vector meta information handler with options for reading and writing vector data in a convenient manner by simplifying the numerous options provided by the OGR python binding.
`vectorize`	Vectorization of an array using `osgeo.gdal.Polygonize()`.
`wkt2vector`	convert well-known text geometries to a Vector object.

class spatialist.vector.Vector(filename=None, driver=None)[source]¶

Bases: object

This is intended as a vector meta information handler with options for reading and writing vector data in a convenient manner by simplifying the numerous options provided by the OGR python binding.

Parameters:

filename (str or None) –
the vector file to read; if filename is None, a new in-memory Vector object is created. In this case driver is overridden and set to ‘Memory’. The following file extensions are auto-detected:
- .geojson (GeoJSON)
- .gpkg (GPKG)
- .json (GeoJSON)
- .kml (KML)
- .shp (ESRI Shapefile)
driver (str) – the vector file format; needs to be defined if the format cannot be auto-detected from the filename extension

__getitem__(expression)[source]¶

subset the vector object by index or attribute.

Parameters:: expression (int or str) – the key or expression to be used for subsetting. See osgeo.ogr.Layer.SetAttributeFilter() for details on the expression syntax.
Returns:: a vector object matching the specified criteria
Return type:: Vector

Examples

Assuming we have a shapefile called testsites.shp, which has an attribute sitename, we can subset individual sites and write them to new files like so:

>>> from spatialist import Vector
>>> filename = 'testsites.shp'
>>> with Vector(filename)["sitename='site1'"] as site1:
>>>     site1.write('site1.shp')

addfeature(geometry, fields=None)[source]¶

add a feature to the vector object from a geometry

Parameters:

geometry (osgeo.ogr.Geometry) – the geometry to add as a feature
fields (dict or None) – the field names and values to assign to the new feature

addfield(name, type, width=10, values=None)[source]¶

add a field to the vector layer

Parameters:

name (str) – the field name
type (int) – the OGR Field Type (OFT), e.g. ogr.OFTString. See osgeo.ogr.FieldDefn.
width (int) – the width of the new field (only for ogr.OFTString fields)
values (List or None) – an optional list with values for each feature to assign to the new field. The length must be identical to the number of features.

addlayer(name, srs, geomType)[source]¶

add a layer to the vector layer

Parameters:

name (str) – the layer name
srs (int or str or osgeo.osr.SpatialReference) – the spatial reference system. See spatialist.auxil.crsConvert() for options.
geomType (int) – an OGR well-known binary data type. See Module ogr.

addvector(vec)[source]¶

add a vector object to the layer of the current Vector object

Parameters:

vec (Vector) – the vector object to add
merge (bool) – merge overlapping polygons?

bbox(outname=None, driver=None, overwrite=True)[source]¶

create a bounding box from the extent of the Vector object

Parameters:

outname (str or None) – the name of the vector file to be written; if None, a Vector object is returned
driver (str) – the name of the file format to write
overwrite (bool) – overwrite an already existing file?

Returns:

if outname is None, the bounding box Vector object

Return type:

Vector or None

clone()[source]¶

close()[source]¶: closes the OGR vector file connection

convert2wkt(set3D=True)[source]¶

export the geometry of each feature as a wkt string

Parameters:: set3D (bool) – keep the third (height) dimension?

property extent¶

the extent of the vector object

Returns:: a dictionary with keys xmin, xmax, ymin, ymax
Return type:: dict

property fieldDefs¶

Returns:: the field definition for each field of the Vector object
Return type:: list[osgeo.ogr.FieldDefn]

property fieldnames¶

Returns:: the names of the fields
Return type:: list of str

property geomType¶

Returns:: the layer geometry type
Return type:: int

property geomTypes¶

Returns:: the geometry type of each feature
Return type:: list

getArea()[source]¶

Returns:: the area of the vector geometries
Return type:: float

getFeatureByAttribute(fieldname, attribute)[source]¶

get features by field attribute

Parameters:

fieldname (str) – the name of the queried field
attribute (int or str) – the field value of interest

Returns:

the feature(s) matching the search query

Return type:

list[osgeo.ogr.Feature] or osgeo.ogr.Feature

getFeatureByIndex(index)[source]¶

get features by numerical (positional) index

Parameters:: index (int) – the queried index
Returns:: the requested feature
Return type:: osgeo.ogr.Feature

getProjection(type)[source]¶

get the CRS of the Vector object. See spatialist.auxil.crsConvert().

Parameters:: type (str) – the type of projection required.
Returns:: the output CRS
Return type:: int or str or osgeo.osr.SpatialReference

getUniqueAttributes(fieldname)[source]¶

Parameters:: fieldname (str) – the name of the field of interest
Returns:: the unique attributes of the field
Return type:: list of str or int

getfeatures()[source]¶

Returns:: a list of cloned features
Return type:: list[osgeo.ogr.Feature]

init_features()[source]¶: delete all in-memory features

init_layer()[source]¶: initialize a layer object

property layerdef¶

Returns:: the layer’s feature definition
Return type:: osgeo.ogr.FeatureDefn

property layername¶

Returns:: the name of the layer
Return type:: str

load()[source]¶: load all feature into memory

property nfeatures¶

Returns:: the number of features
Return type:: int

property nfields¶

Returns:: the number of fields
Return type:: int

property nlayers¶

Returns:: the number of layers
Return type:: int

property proj4¶

Returns:: the CRS in PRO4 format
Return type:: str

reproject(projection)[source]¶

in-memory reprojection

Parameters:: projection (int or str or osgeo.osr.SpatialReference) – the target CRS. See spatialist.auxil.crsConvert().

setCRS(crs)[source]¶

directly reset the spatial reference system of the vector object. This is not going to reproject the Vector object, see reproject() instead.

Parameters:: crs (int or str or osgeo.osr.SpatialReference) – the input CRS

Example

>>> site = Vector('shape.shp')
>>> site.setCRS('+proj=longlat +ellps=WGS84 +datum=WGS84 +no_defs ')

property srs¶

Returns:: the geometry’s spatial reference system
Return type:: osgeo.osr.SpatialReference

to_geopandas()[source]¶

Convert the object to a geopandas GeoDataFrame. DateTime fields are converted to pandas.Timestamp using pandas.to_datetime().

Return type:: geopandas.GeoDataFrame

See also

osgeo.ogr.Feature.items

write(outfile, driver=None, overwrite=True)[source]¶

write the Vector object to a file

Parameters:

outfile –
the name of the file to write; the following extensions are automatically detected for determining the format driver:
- .geojson (GeoJSON)
- .gpkg (GPKG)
- .json (GeoJSON)
- .kml (KML)
- .shp (ESRI Shapefile)
driver (str or None) – the output file format; default None: try to autodetect from the file name extension
overwrite (bool) – overwrite an already existing file?

spatialist.vector.bbox(coordinates, crs, outname=None, driver=None, overwrite=True)[source]¶

create a bounding box vector object or file. The CRS can be in either WKT, EPSG or PROJ4 format

Parameters:

coordinates (dict) – a dictionary containing numerical variables with keys xmin, xmax, ymin and ymax
crs (int or str or osgeo.osr.SpatialReference) – the coordinate reference system of the coordinates. See crsConvert() for options.
outname (str) – the file to write to. If None, the bounding box is returned as Vector object
driver (str) –

the output file format; needs to be defined if the format cannot
be auto-detected from the filename extension
overwrite (bool) – overwrite an existing file?

Returns:

the bounding box Vector object

Return type:

Vector or None

spatialist.vector.boundary(vectorobject, expression=None, outname=None)[source]¶

Get the boundary of the largest geometry as new vector object. The following steps are performed:

find the largest geometry matching the expression

compute the geometry’s boundary using osgeo.ogr.Geometry.Boundary(), returning a MULTILINE geometry

select the longest line of the MULTILINE geometry

create a closed linear ring from this longest line

create a polygon from this linear ring

create a new Vector object and add the newly created polygon

Parameters:

vectorobject (Vector) – the vector object containing multiple polygon geometries, e.g. all geometries with a certain value in one field.
expression (str or None) – the SQL expression to select the candidates for the largest geometry.
outname (str or None) – the name of the output vector file; if None, an in-memory object of type Vector is returned.

Returns:

if outname is None, a vector object pointing to an in-memory dataset else None

Return type:

Vector or None

spatialist.vector.centerdist(obj1, obj2)[source]¶

Get the center distance between two vector objects.

Parameters:

obj1 (Vector)
obj2 (Vector)

Return type:

float

spatialist.vector.dissolve(infile, outfile, field, layername=None)[source]¶

dissolve the polygons of a vector file by an attribute field

Parameters:

infile (str) – the input vector file
outfile (str) – the output shapefile
field (str) – the field name to merge the polygons by
layername (str) – the name of the output vector layer; If set to None the layername will be the basename of infile without extension

spatialist.vector.feature2vector(feature, ref, layername=None)[source]¶

create a Vector object from ogr features

Parameters:

feature (list[osgeo.ogr.Feature] or osgeo.ogr.Feature) – a single feature or a list of features
ref (Vector) – a reference Vector object to retrieve geo information from
layername (str or None) – the name of the output layer; retrieved from ref if None

Returns:

the new Vector object

Return type:

Vector

spatialist.vector.intersect(obj1, obj2)[source]¶

intersect two Vector objects

Parameters:

obj1 (Vector) – the first vector object; this object is reprojected to the CRS of obj2 if necessary
obj2 (Vector) – the second vector object

Returns:

the intersection of obj1 and obj2 if both intersect and None otherwise

Return type:

Vector or None

spatialist.vector.set_field(target, name, type, width=10, values=None)[source]¶

Wrapper for setting a field

Parameters:

target (Vector or osgeo.ogr.Feature) – the object for which to set the field
name (str) – the field name
type (int) – the OGR Field Type (OFT), e.g. ogr.OFTString. See osgeo.ogr.FieldDefn.
width (int) – the width of the new field (only for ogr.OFTString fields)
values (List or None) – an optional list with values for each feature to assign to the new field. If target is of type Vector, the length must be identical to the number of features.

spatialist.vector.vectorize(target, reference, outname=None, layername='layer', fieldname='value', driver=None)[source]¶

Vectorization of an array using osgeo.gdal.Polygonize().

Parameters:

target (numpy.ndarray) – the input array. Each identified object of pixels with the same value will be converted into a vector feature.
outname (str or None) – the name of the vector file. If None a vector object is returned.
reference (Raster) – a reference Raster object to retrieve geo information and extent from.
layername (str) – the name of the vector object layer.
fieldname (str) – the name of the field to contain the raster value for the respective vector feature.
driver (str or None) – the vector file type of outname. Several extensions are read automatically (see Vector.write()). Is ignored if outname=None.

spatialist.vector.wkt2vector(wkt, srs, layername='wkt')[source]¶

convert well-known text geometries to a Vector object.

Parameters:

wkt (str or list[str]) – the well-known text description(s). Each geometry will be placed in a separate feature.
srs (int or str) – the spatial reference system; see spatialist.auxil.crsConvert() for options.
layername (str) – the name of the internal osgeo.ogr.Layer object.

Returns:

the vector representation

Return type:

Vector

Examples

>>> from spatialist.vector import wkt2vector
>>> wkt1 = 'POLYGON ((0. 0., 0. 1., 1. 1., 1. 0., 0. 0.))'
>>> with wkt2vector(wkt1, srs=4326) as vec:
>>>     print(vec.getArea())
1.0
>>> wkt2 = 'POLYGON ((1. 1., 1. 2., 2. 2., 2. 1., 1. 1.))'
>>> with wkt2vector([wkt1, wkt2], srs=4326) as vec:
>>>     print(vec.getArea())
2.0

Vector¶

Table of Contents

Previous topic

Next topic

This Page