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

Examples using geoutils.Raster

NumPy interfacing

NumPy interfacing

Python arithmetic

Python arithmetic

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

Interpolate raster at points

Interpolate raster at points

Reduce raster around points

Reduce raster around points

Raster to regular points

Raster to regular points

Mask from a vector

Mask from a vector

Polygonize a raster

Polygonize a raster

Rasterize a vector

Rasterize a vector

From/to Rasterio

From/to Rasterio

Creating a raster from array

Creating a raster from array

Open/save a raster

Open/save a raster

Parsing sensor metadata

Parsing sensor metadata

Opening a file

Raster(filename_or_dataset[, bands, ...])	The georeferenced raster.
Raster.info([stats, verbose])

Create from an array

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

Create a raster from a numpy array and the georeferencing information.

Main attributes

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

Derived attributes

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

Other attributes

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

Geospatial handling methods

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

Plotting

Raster.plot([bands, cmap, vmin, vmax, ...])

Get statistics

Raster.get_stats([stats_name, inlier_mask, ...])

Get or update data methods

Raster.copy([new_array, cast_nodata, deep])	Copy the raster in-memory.
Raster.astype(dtype[, convert_nodata, inplace])
Raster.set_mask(mask)	Set a mask on the raster array.
Raster.set_nodata(new_nodata[, ...])	Set a new nodata value for all bands.
Raster.get_nanarray([floating_dtype, ...])
Raster.get_mask()	Get mask of invalid values from the raster.
Raster.subsample(subsample[, ...])

I/O methods

Raster.load([bands])	Load the raster array from disk.
Raster.to_file(filename[, driver, dtype, ...])	Write the raster to file.
Raster.to_pointcloud([data_column_name, ...])
Raster.from_pointcloud_regular(pointcloud[, ...])	Create a raster from a point cloud with coordinates on a regular grid.
Raster.to_rio_dataset()	Export to a Rasterio in-memory dataset.
Raster.to_xarray([name])	Convert a xarray.DataArray raster.

Coordinate and extent methods

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

Projection methods

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

Testing methods

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

Arithmetic with other rasters, arrays or numbers

Raster.__add__(other)	Sum two rasters, or a raster and a numpy array, or a raster and single number.
Raster.__sub__(other)	Subtract two rasters, or a raster and a numpy array, or a raster and single number.
Raster.__neg__()	Take the raster negation.
Raster.__mul__(other)	Multiply two rasters, or a raster and a numpy array, or a raster and single number.
Raster.__truediv__(other)	True division of two rasters, or a raster and a numpy array, or a raster and single number.
Raster.__floordiv__(other)	Floor division of two rasters, or a raster and a numpy array, or a raster and single number.
Raster.__mod__(other)	Modulo of two rasters, or a raster and a numpy array, or a raster and single number.
Raster.__pow__(power)	Power of a raster to a number.

And reverse operations.

Logical operators casting to mask (boolean raster)

Raster.__eq__(other)	Element-wise equality of two rasters, or a raster and a numpy array, or a raster and single number.
Raster.__ne__(other)	Element-wise negation of two rasters, or a raster and a numpy array, or a raster and single number.
Raster.__lt__(other)	Element-wise lower than comparison of two rasters, or a raster and a numpy array, or a raster and single number.
Raster.__le__(other)	Element-wise lower or equal comparison of two rasters, or a raster and a numpy array, or a raster and single number.
Raster.__gt__(other)	Element-wise greater than comparison of two rasters, or a raster and a numpy array, or a raster and single number.
Raster.__ge__(other)	Element-wise greater or equal comparison of two rasters, or a raster and a numpy array, or a raster and single number.

Array interface with NumPy

Raster.__array_ufunc__(ufunc, method, ...)	Method to cast NumPy universal functions directly on Raster classes, by passing to the masked array.
Raster.__array_function__(func, types, args, ...)	Method to cast NumPy array function directly on a Raster object by applying it to the masked array.

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])

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])
Vector.reproject([ref, crs, inplace])
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, ...])

Geometry manipulation

Vector.buffer_metric(buffer_size)	Buffer the vector features in a local metric system (UTM or UPS).
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 (UTM, UPS, or custom Mercator or Polar).
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])
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])

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 point cloud from three 1D array-like coordinates for X/Y/Z.
PointCloud.from_array(data, crs[, ...])	Create point cloud from a 3 x N or N x 3 array of X coordinates, Y coordinates and Z values.
PointCloud.from_tuples(tuples_xyz, crs[, ...])	Create point cloud from an iterable of 3-tuples (X coordinate, Y coordinate, Z value).
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 (X coordinate, Y coordinate, Z value).

Geospatial

PointCloud.crop([bbox, clip, inplace, crop_geom])
PointCloud.reproject([ref, crs, inplace])
PointCloud.translate([xoff, yoff, zoff, inplace])

Interface with raster

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

Grid point cloud into a raster.

Statistics

PointCloud.get_stats([stats_name])
PointCloud.subsample(subsample[, ...])

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.