API reference

This page provides a summary of GeoUtils’ API. For more details and examples, refer to the relevant chapters in the main part of the documentation.

Raster API

GeoUtils exposes the raster API through two mirrored interfaces:

• Raster, an interface operating directly on a GeoUtils object,

• A rst accessor extending xarray.DataArray objects as rasters.

Both expose the same methods and attributes.

Only file opening and scalable execution differ between the two interfaces:

• File opening: Raster objects are opened by instantiating the class, whereas open_raster() is used for an xarray.DataArray object,

• Scalable execution: the rst accessor supports Dask, while the Raster supports Multiprocessing instead.

Opening a raster file

Use open_raster() for an xarray.DataArray, or instantiate for a Raster.

open_raster(filename[, is_mask])	Open a raster using Rioxarray, always masked and squeezed.
Raster.__init__(filename_or_dataset[, ...])	Instantiate a raster from a filename or rasterio dataset.

Create raster from an array

from_array(data, transform, crs[, nodata, ...])

Main attributes

data	Array of the raster.
crs	Coordinate reference system of the raster.
transform	Geotransform of the raster.
nodata	Nodata value of the raster.
area_or_point	Pixel interpretation of the raster.

Derived attributes

shape	Shape (i.e., height, width) of the raster in pixels.
height	Height of the raster in pixels.
width	Width of the raster in pixels.
count	Count of bands loaded in memory if they are, otherwise the one on disk.
bands	Band indexes loaded in memory if they are, otherwise on disk.
res	Resolution (X, Y) of the raster in georeferenced units.
bounds	Bounding coordinates of the raster.
footprint	Footprint of the raster.
dtype	Data type of the raster.

Other attributes

is_mask	Whether the raster array is a boolean data type (a mask).
is_loaded	Whether the raster array is loaded.
name	Name of the file on disk, if it exists.
driver	Driver used to read a file on disk.
tags	Metadata tags of the raster.

Geospatial operations

crop(bbox[, inplace])	Crop the raster to a given extent.
icrop(bbox[, inplace])	Crop raster based on pixel indices (bbox), converting them into georeferenced coordinates.
reproject([ref, crs, res, grid_size, ...])	Reproject raster to a different geotransform (resolution, bounds) and/or coordinate reference system (CRS).
polygonize([target_values, connectivity, ...])	Polygonize the raster into a vector of polygon geometries delineating target values.
proximity([vector, target_values, ...])	Compute proximity distances to the raster target pixels, or to a vector geometry on the raster grid.
interp_points(points[, method, ...])	Interpolate raster values at a set of points.
reduce_points(points[, reducer_function, ...])	Reduce raster values around point coordinates.
filter(method[, size, sigma, engine, ...])	Apply a filter to the array.

Plotting

Statistics

stats([statistics, by, values, bins, ...])

Calculate summary statistics or statistics grouped by categories, bins, or vector zones.

Data manipulation

copy([new_array, cast_nodata, deep])	Copy the raster in-memory.
set_nodata(new_nodata[, update_array, ...])	Set a new nodata value for all bands.
get_nanarray([floating_dtype, return_mask])	Get NaN array from the raster.
subsample(subsample[, return_indices, band, ...])	Randomly sample valid raster values allowed by mask, without replacement.

Loading, writing and converting

load()
to_pointcloud([data_column_name, data_band, ...])	Convert raster to point cloud.
from_pointcloud_regular(pointcloud[, ...])	Create a raster from a point cloud with coordinates on a regular grid.

Georeferencing utilities

xy2ij(x, y[, op, precision, shift_area_or_point])	Get indexes (row,column) of coordinates (x,y).
ij2xy(i, j[, shift_area_or_point, force_offset])	Get coordinates (x,y) of indexes (row,column).
coords([grid, shift_area_or_point, ...])	Get coordinates (x,y) of all pixels in the raster.
translate(xoff, yoff[, distance_unit, inplace])	Translate a raster by a (x,y) offset.
outside_image(xi, yj[, index])	Check whether a given point falls outside the bounds of the raster.

Projection utilities

get_metric_crs([local_crs_type, method])	Get local metric coordinate reference system for the raster (UTM, UPS, or custom Mercator or Polar).
get_bounds_projected(out_crs[, densify_points])	Get raster bounds projected in a specified CRS.
get_footprint_projected(out_crs[, ...])	Get raster footprint projected in a specified CRS.
intersection(other[, match_ref])	Returns the bounding box of intersection between this raster and another.

Testing utilities

raster_equal(other[, strict_masked, ...])	Check if two rasters are equal.
georeferenced_grid_equal(other[, warn_3d_crs])	Check that raster shape, geotransform and CRS are equal.

Multiple rasters

raster.load_multiple_rasters(raster_paths[, ...])	Function to load multiple rasters at once in a memory efficient way.
raster.stack_rasters(rasters[, reference, ...])	Stack a list of rasters on their maximum extent into a multi-band raster.
raster.merge_rasters(rasters[, reference, ...])	Spatially merge a list of rasters into one larger raster of their maximum extent.

Vector

Examples using geoutils.Vector

Metric buffer and without overlap

Metric buffer and without overlap

Proximity to raster or vector

Proximity to raster or vector

Crop a raster

Crop a raster

Crop a vector

Crop a vector

Reproject a raster

Reproject a raster

Reproject a vector

Reproject a vector

Gridding points to raster

Gridding points to raster

Mask from a vector

Mask from a vector

Polygonize a raster

Polygonize a raster

Rasterize a vector

Rasterize a vector

From/to GeoPandas

From/to GeoPandas

Open/save a point cloud

Open/save a point cloud

Open/save a vector

Open/save a vector

Opening a file

Vector(filename_or_dataset)	The georeferenced vector.
Vector.info([verbose])	Summarize information about the vector.

Main attributes

Vector.ds	Geodataframe of the vector.
Vector.crs	Coordinate reference system of the vector.
Vector.bounds	Total bounding box of the vector.
Vector.name	Name on disk, if it exists.

Caution

The bounds attribute of a Vector corresponds to the total_bounds attribute of a GeoDataFrame, for consistency between rasters and vectors (and can also be accessed through total_bounds).

The equivalent of geopandas.GeoDataFrame.bounds (i.e., a per-feature bounds) for Vectors is geom_bounds.

Geospatial handling methods

Vector.crop([bbox, clip, inplace, crop_geom])	Crop the vector to given extent.
Vector.reproject([ref, crs, inplace])	Reproject vector to a specified coordinate reference system.
Vector.rasterize([ref, in_value, out_value, ...])	Rasterize vector to a raster or mask, with input geometries burned in.
Vector.proximity([raster, size, ...])	Compute proximity distances to this vector's geometry.

Plotting

Vector.plot([ref_crs, cmap, vmin, vmax, ...])

Plot the vector.

Create mask

Vector.create_mask([ref, all_touched, crs, ...])

Create a raster or point cloud mask from the vector features.

Geometry manipulation

Vector.buffer_metric(buffer_size)	Buffer the vector features in a local metric system.
Vector.buffer_without_overlap(buffer_size[, ...])	Buffer the vector geometries without overlapping each other.

Projection tools

Vector.get_metric_crs([local_crs_type, method])	Get local metric coordinate reference system for the vector.
Vector.from_bounds_projected(raster_or_vector)	Create a vector polygon from projected bounds of a raster or vector.
Vector.get_bounds_projected(out_crs[, ...])	Get vector bounds projected in a specified CRS.
Vector.get_footprint_projected(out_crs[, ...])	Get vector footprint projected in a specified CRS.

Indexing

Vector.__getitem__(key)

Index the geodataframe.

From Shapely and GeoPandas

Geometric attributes and methods

This first category of attributes and methods return a geometric output converted to a Vector by default.

Attributes:

Vector.boundary	Return a Vector of lower dimensional objects representing each geometry's set-theoretic boundary.
Vector.centroid	Return a Vector of points representing the centroid of each geometry.
Vector.convex_hull	Return a Vector of geometries representing the convex hull of each geometry.
Vector.envelope	Return a Vector of geometries representing the envelope of each geometry.
Vector.exterior	Return a Vector of LinearRings representing the outer boundary of each polygon in the Vector.

Methods:

Vector.representative_point()	Return a Vector of (cheaply computed) points that are guaranteed to be within each geometry.
Vector.normalize()	Return a Vector of normalized geometries to normal form (or canonical form).
Vector.make_valid()	Repairs invalid geometries.
Vector.difference(other[, align])	Return a Vector of the points in each aligned geometry that are not in other.
Vector.symmetric_difference(other[, align])	Return a Vector of the symmetric difference of points in each aligned geometry with other.
Vector.union(other[, align])	Return a Vector of the union of points in each aligned geometry with other.
Vector.union_all([method])	Return a geometry containing the union of all geometries in the Vector.
Vector.intersection(other[, align])	Return a Vector of the intersection of points in each aligned geometry with other.
Vector.intersection_all()	Return a geometry containing the intersection of all geometries in the Vector.
Vector.clip_by_rect(xmin, ymin, xmax, ymax)	Return a Vector of the portions of geometry within the given rectangle.
Vector.buffer(distance[, resolution, ...])	Return a Vector of geometries representing all points within a given distance of each geometric object.
Vector.simplify(tolerance[, preserve_topology])	Return a Vector containing a simplified representation of each geometry.
Vector.affine_transform(matrix)	Return a Vector with translated geometries.
Vector.translate([xoff, yoff, zoff, inplace])	Shift a vector by a coordinate offset.
Vector.rotate(angle[, origin, use_radians])	Return a Vector with rotated geometries.
Vector.scale([xfact, yfact, zfact, origin])	Return a Vector with scaled geometries.
Vector.skew([xs, ys, origin, use_radians])	Return a Vector with skewed geometries.
Vector.concave_hull([ratio, allow_holes])	Return a Vector of geometries representing the concave hull of vertices of each geometry.
Vector.delaunay_triangles([tolerance, ...])	Return a Vector consisting of objects representing the computed Delaunay triangulation between the vertices of an input geometry.
Vector.voronoi_polygons([tolerance, ...])	Return a Vector consisting of objects representing the computed Voronoi diagram around the vertices of an input geometry.
Vector.minimum_rotated_rectangle()	Return a Vector of the general minimum bounding rectangle that contains the object.
Vector.minimum_bounding_circle()	Return a Vector of geometries representing the minimum bounding circle that encloses each geometry.
Vector.extract_unique_points()	Return a Vector of MultiPoints representing all distinct vertices of an input geometry.
Vector.remove_repeated_points([tolerance])	Return a Vector containing a copy of the input geometry with repeated points removed.
Vector.offset_curve(distance[, quad_segs, ...])	Return a LineString or MultiLineString geometry at a distance from the object on its right or its left side.
Vector.reverse()	Return a Vector with the order of coordinates reversed.
Vector.segmentize(max_segment_length)	Return a Vector with vertices added to line segments based on maximum segment length.
Vector.polygonize([node, full])	Create polygons formed from the linework of a Vector.
Vector.transform(transformation[, include_z])	Return a Vector with the transformation function applied to the geometry coordinates.
Vector.force_2d()	Force the dimensionality of a geometry to 2D.
Vector.force_3d([z])	Force the dimensionality of a geometry to 3D.
Vector.line_merge([directed])	Return (Multi)LineStrings formed by combining the lines in a MultiLineString.
Vector.shortest_line(other[, align])	Return the shortest two-point line between two geometries.
Vector.interpolate(distance[, normalized])	Return a point at the specified distance along each geometry.
Vector.shared_paths(other[, align])	Return the shared paths between two geometries.
Vector.dissolve([by, aggfunc, as_index, ...])	Dissolve geometries within groupby into single observation.
Vector.explode([column, ignore_index, ...])	Explode multi-part geometries into multiple single geometries.
Vector.sjoin(df, *args, **kwargs)	Spatial join of two Vectors.
Vector.sjoin_nearest(right[, how, ...])	Spatial join of two Vectors based on the distance between their geometries.
Vector.overlay(right[, how, keep_geom_type, ...])	Perform spatial overlay between Vectors.
Vector.clip(mask[, keep_geom_type, sort])	Clip points, lines, or polygon geometries to the mask extent.
Vector.snap(other, tolerance[, align])	Snap the vertices and segments of the geometry to vertices of the reference.
Vector.to_crs([crs, epsg, inplace])	Transform geometries to a new coordinate reference system.
Vector.set_crs([crs, epsg, inplace, ...])	Set the Coordinate Reference System (CRS) of the Vector.
Vector.get_geometry(index)	Return the n-th geometry from a collection of geometries.
Vector.set_geometry(col[, drop, inplace, crs])	Set the Vector geometry using either an existing column or the specified input.
Vector.rename_geometry(col[, inplace])	Rename the Vector geometry column to the specified name.
Vector.set_precision([grid_size, mode, inplace])	Return a GeoSeries with the precision set to a precision grid size.
Vector.get_precision()	Return a Series of the precision of each geometry.
Vector.get_coordinates([include_z, ...])	Get coordinates from a Vector as a DataFrame of floats.
Vector.cx()	Coordinate based indexer to select by intersection with bounding box.

Non-geometric per-feature attributes and methods

This second category of attributes and methods return a non-geometric output with same length as the number of features. They are thus appended in the dataframe of the current Vector by default, using as column name the name of the operation (e.g., “area”, “contains” or “intersects”).

Otherwise, calling the method from Vector.ds, they return a pandas.Series as in GeoPandas.

Attributes:

Vector.area	Return a Series containing the area of each geometry in the Vector expressed in the units of the CRS.
Vector.length	Return a Series containing the length of each geometry expressed in the units of the CRS.
Vector.interiors	Return a Series of List representing the inner rings of each polygon in the Vector.
Vector.geom_type	Returns a Series of strings specifying the Geometry Type of each object.
Vector.geom_bounds	Returns or appends to Vector a Series with the bounds of each geometry feature.
Vector.is_valid	Return a Series of dtype('bool') with value True for geometries that are valid.
Vector.is_empty	Returns a Series of dtype('bool') with value True for empty geometries.
Vector.is_ring	Return a Series of dtype('bool') with value True for features that are closed.
Vector.is_simple	Return a Series of dtype('bool') with value True for geometries that do not cross themselves.
Vector.is_ccw	Return a Series of dtype('bool') with value True if a LineString or LinearRing is counterclockwise.
Vector.is_closed	Return a Series of dtype('bool') with value True if a LineString's or LinearRing's first and last points are equal.
Vector.has_z	Return a Series of dtype('bool') with value True for features that have a z-component.

Methods:

Vector.contains(other[, align])	Return a Series of dtype('bool') with value True for each aligned geometry that contains other.
Vector.geom_equals(other[, align])	Return a Series of dtype('bool') with value True for each aligned geometry equal to other.
Vector.crosses(other[, align])	Return a Series of dtype('bool') with value True for each aligned geometry that cross other.
Vector.disjoint(other[, align])	Return a Series of dtype('bool') with value True for each aligned geometry disjoint to other.
Vector.intersects(other[, align])	Return a Series of dtype('bool') with value True for each aligned geometry that intersects other.
Vector.overlaps(other[, align])	Return True for all aligned geometries that overlap other, else False.
Vector.touches(other[, align])	Return a Series of dtype('bool') with value True for each aligned geometry that touches other.
Vector.within(other[, align])	Return a Series of dtype('bool') with value True for each aligned geometry that is within other.
Vector.covers(other[, align])	Return a Series of dtype('bool') with value True for each aligned geometry that is entirely covering other.
Vector.covered_by(other[, align])	Return a Series of dtype('bool') with value True for each aligned geometry that is entirely covered by other.
Vector.distance(other[, align])	Return a Series containing the distance to aligned other.
Vector.is_valid_reason()	Return a Series of strings with the reason for invalidity of each geometry.
Vector.count_coordinates()	Return a Series containing the count of the number of coordinate pairs in each geometry.
Vector.count_geometries()	Return a Series containing the count of geometries in each multi-part geometry.
Vector.count_interior_rings()	Return a Series containing the count of the number of interior rings in a polygonal geometry.
Vector.get_precision()	Return a Series of the precision of each geometry.
Vector.minimum_clearance()	Return a Series containing the minimum clearance distance, which is the smallest distance by which a vertex of the geometry could be moved to produce an invalid geometry.
Vector.minimum_bounding_radius()	Return a Series of the radii of the minimum bounding circles that enclose each geometry.
Vector.contains_properly(other[, align])	Return a Series of dtype('bool') with value True for each aligned geometry that is completely inside other, with no common boundary points.
Vector.dwithin(other, distance[, align])	Return a Series of dtype('bool') with value True for each aligned geometry that is within a set distance from other.
Vector.hausdorff_distance(other[, align, ...])	Return a Series containing the Hausdorff distance to aligned other.
Vector.frechet_distance(other[, align, densify])	Return a Series containing the Frechet distance to aligned other.
Vector.hilbert_distance([total_bounds, level])	Calculate the distance along a Hilbert curve.
Vector.relate(other[, align])	Return the DE-9IM intersection matrices for the geometries.
Vector.relate_pattern(other, pattern[, align])	Return True if the DE-9IM string code for the relationship between the geometries satisfies the pattern, else False.
Vector.project(other[, normalized, align])	Return the distance along each geometry nearest to other.

I/O, conversions and others

Important

The behaviour of methods below is not modified in Vector, as they deal with outputs of different types. To ensure those are up-to-date with GeoPandas, alternatively call those from Vector.ds.

Vector.from_file(filename, **kwargs)	Alternate constructor to create a Vector from a file.
Vector.from_features(features, crs, columns)	Alternate constructor to create Vector from an iterable of features or a feature collection.
Vector.from_postgis(sql, con[, geom_col, ...])	Alternate constructor to create a Vector from a sql query containing a geometry column in WKB representation.
Vector.from_dict(data[, geometry, crs])	Construct Vector from dict of array-like or dicts by overriding DataFrame.from_dict method with geometry and crs.
Vector.from_arrow(table[, geometry])	Construct a Vector from an Arrow table object based on GeoArrow extension types.
Vector.to_file(filename[, driver, schema, index])	Write the Vector to a file.
Vector.to_feather(path[, index, ...])	Write a Vector to the Feather format.
Vector.to_parquet(path[, index, ...])	Write a Vector to the Parquet format.
Vector.to_arrow([index, geometry_encoding, ...])	Encode a Vector to GeoArrow format.
Vector.to_wkt(**kwargs)	Encode all geometry columns in the Vector to WKT.
Vector.to_wkb([hex])	Encode all geometry columns in the Vector to WKB.
Vector.to_json([na, show_bbox, drop_id])	Return a GeoJSON representation of the Vector as a string.
Vector.to_postgis(name, con[, schema, ...])	Upload Vector into PostGIS database.
Vector.to_geo_dict([na, show_bbox, drop_id])	Return a python feature collection representation of the Vector as a dictionary with a list of features based on the __geo_interface__ GeoJSON-like specification.
Vector.to_csv([path_or_buf, sep, na_rep, ...])	Write object to a comma-separated values (csv) file.

Other attributes and methods

Vector.has_sindex	Check the existence of the spatial index without generating it.
Vector.sindex	Generate the spatial index.
Vector.total_bounds	Total bounds of the vector.

See also

The methods above are described in GeoPandas GeoSeries’s API and Shapely object’s documentation.

Point cloud

Examples using geoutils.PointCloud

Gridding points to raster

Gridding points to raster

Interpolate raster at points

Interpolate raster at points

Reduce raster around points

Reduce raster around points

Raster to regular points

Raster to regular points

Creating a point cloud from arrays

Creating a point cloud from arrays

Open/save a point cloud

Open/save a point cloud

Opening a file

PointCloud(filename_or_dataset[, data_column])	The georeferenced point cloud.
PointCloud.info([verbose, stats])	Print summary information about the point cloud.

Main attributes

PointCloud.ds	Geodataframe of the point cloud.
PointCloud.data_column	Name of data column of the point cloud.
PointCloud.data	Data of the point cloud.
PointCloud.crs	Coordinate reference system of the vector.

Other attributes

PointCloud.point_count

Number of points in the point cloud.

Create and convert from data

PointCloud.from_xyz(x, y, z, crs[, ...])	Create a point cloud from separate X, Y and Z arrays.
PointCloud.from_array(data, crs[, ...])	Create a point cloud from a 3 x N or N x 3 array of X, Y and Z values.
PointCloud.from_tuples(tuples_xyz, crs[, ...])	Create a point cloud from an iterable of X, Y and Z tuples.
PointCloud.to_xyz()	Convert point cloud to three 1D arrays of coordinates for X/Y/Z.
PointCloud.to_array()	Convert point cloud to a 3 x N array of X coordinates, Y coordinates and Z values.
PointCloud.to_tuples()	Convert point cloud to a list of 3-tuples.

Geospatial

PointCloud.crop([bbox, clip, inplace, crop_geom])	Crop the vector to given extent.
PointCloud.reproject([ref, crs, inplace, ...])	Reproject point coordinates, preserving their order and value columns.
PointCloud.translate([xoff, yoff, zoff, inplace])	Shift a vector by a coordinate offset.

Interface with raster

PointCloud.grid([ref, grid_coords, res, ...])

Grid the point cloud into a raster.

Statistics

PointCloud.stats([statistics, by, values, ...])	Calculate summary statistics or statistics grouped by categories, bins, or vector zones.
PointCloud.subsample(subsample[, ...])	Randomly sample finite point cloud values allowed by mask, without replacement.

Testing methods

PointCloud.pointcloud_equal(other, **kwargs)	Check if two point clouds are equal.
PointCloud.georeferenced_coords_equal(pc[, ...])	Check that point-cloud X/Y coordinates and CRS are equal.

Multiprocessing configuration

To perform chunked execution on GeoUtils objects, pass this Multiprocessing configuration to function that support it.

multiproc.MultiprocConfig(chunks[, outfile, ...])

Configuration class for handling multiprocessing parameters in raster and point cloud processing.