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

Open/save a raster

Open/save a raster

Parsing image metadata

Parsing image metadata

Creating a raster from array

Creating a raster from array

From/to Rasterio

From/to Rasterio

Crop a raster

Crop a raster

Crop a vector

Crop a vector

Reproject a raster

Reproject a raster

Reproject a vector

Reproject a vector

Mask from a vector

Mask from a vector

Polygonize a raster

Polygonize a raster

Raster to points

Raster to points

Rasterize a vector

Rasterize a vector

NumPy interfacing

NumPy interfacing

Python arithmetic

Python arithmetic

Proximity to raster or vector

Proximity to raster or vector

Interpolation from grid

Interpolation from grid

Reduction from window

Reduction from window

Opening a file

Raster(filename_or_dataset[, bands, ...])	The georeferenced raster.
Raster.info([stats, verbose])	Print summary information about the raster.

Create from an array

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

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

Unique 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.

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.count_on_disk	Count of bands on disk if it exists.
Raster.bands	Band indexes loaded in memory if they are, otherwise on disk.
Raster.bands_on_disk	Band indexes on disk if a file exists.
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 (string representation).
Raster.is_loaded	Whether the raster array is loaded.
Raster.is_modified	Whether the array has been modified since it was loaded from disk.
Raster.name	Name of the file on disk, if it exists.
Raster.driver	Driver used to read a file on disk.

Geospatial handling methods

Raster.crop(crop_geom[, mode, inplace])	Crop the raster to a given extent.
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.
Raster.proximity([vector, target_values, ...])	Compute proximity distances to the raster target pixels, or to a vector geometry on the raster grid.
Raster.value_at_coords(x, y[, latlon, band, ...])	Extract raster values at the nearest pixels from the specified coordinates, or reduced (e.g., mean of pixels) from a window around the specified coordinates.
Raster.interp_points(points[, method, band, ...])	Interpolate raster values at a set of points.

Plotting

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

Plot the raster, with axes in projection of image.

Get or update data methods

Raster.copy([new_array, cast_nodata])	Copy the raster in-memory.
Raster.astype(dtype[, convert_nodata, inplace])	Convert data type of the raster.
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([return_mask])	Get NaN array from the raster.
Raster.get_mask()	Get mask of invalid values from the raster.
Raster.subsample(subsample[, ...])	Randomly sample the raster.

I/O methods

Raster.load([bands])	Load the raster array from disk.
Raster.save(filename[, driver, dtype, ...])	Write the raster to file.
Raster.to_pointcloud([data_column_name, ...])	Convert raster to point cloud.
Raster.to_rio_dataset()	Export to a Rasterio in-memory dataset.
Raster.to_xarray([name])	Convert raster to a xarray.DataArray.

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.shift(xoff, yoff[, distance_unit, ...])	Shift a raster by a (x,y) offset.
Raster.outside_image(xi, yj[, index])	Check whether a given point falls outside 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(raster[, match_ref])	Returns the bounding box of intersection between this image and another.

Testing methods

Raster.raster_equal(other[, strict_masked, ...])	Check if two rasters are equal.
Raster.georeferenced_grid_equal(raster)	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 operator casting to Mask

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.

SatelliteImage

Examples using geoutils.SatelliteImage

Parsing image metadata

Parsing image metadata

Opening a file

SatelliteImage(filename_or_dataset[, ...])

Satellite image metadata

SatelliteImage.datetime
SatelliteImage.tile_name
SatelliteImage.satellite
SatelliteImage.sensor
SatelliteImage.product
SatelliteImage.version

Mask

Examples using geoutils.Mask

Mask from a vector

Mask from a vector

Polygonize a raster

Polygonize a raster

Rasterize a vector

Rasterize a vector

NumPy interfacing

NumPy interfacing

Python arithmetic

Python arithmetic

Proximity to raster or vector

Proximity to raster or vector

Opening a file

Mask(filename_or_dataset, **kwargs)

The georeferenced mask.

Overloaded Raster methods

Mask.crop(crop_geom[, mode, inplace])	Crop the raster to a given extent.
Mask.reproject([ref, crs, res, grid_size, ...])	Reproject raster to a different geotransform (resolution, bounds) and/or coordinate reference system (CRS).
Mask.polygonize([target_values])	Polygonize the raster into a vector.
Mask.proximity([vector, target_values, ...])	Compute proximity distances to the raster target pixels, or to a vector geometry on the raster grid.

Multiple rasters

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

Open/save a vector

Open/save a vector

From/to GeoPandas

From/to GeoPandas

Crop a raster

Crop a raster

Crop a vector

Crop a vector

Reproject a raster

Reproject a raster

Reproject a vector

Reproject a vector

Mask from a vector

Mask from a vector

Polygonize a raster

Polygonize a raster

Raster to points

Raster to points

Rasterize a vector

Rasterize a vector

Metric buffer and without overlap

Metric buffer and without overlap

Proximity to raster or vector

Proximity to raster or vector

Opening a file

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

Unique 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(crop_geom[, clip, inplace])	Crop the vector to given extent.
Vector.reproject([ref, crs, inplace])	Reproject vector to a specified coordinate reference system.
Vector.rasterize([raster, crs, xres, yres, ...])	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([raster, crs, xres, ...])

Create a mask from the vector features.

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	Returns a Vector of lower dimensional objects representing each geometry's set-theoretic boundary.
Vector.unary_union	Returns a geometry containing the union of all geometries in the Vector.
Vector.centroid	Returns a Vector of points representing the centroid of each geometry.
Vector.convex_hull	Returns a Vector of geometries representing the convex hull of each geometry.
Vector.envelope	Returns a Vector of geometries representing the envelope of each geometry.
Vector.exterior	Returns a Vector of LinearRings representing the outer boundary of each polygon in the Vector.

Methods:

Vector.representative_point()	Returns a Vector of (cheaply computed) points that are guaranteed to be within each geometry.
Vector.normalize()	Returns a Vector of normalized geometries to normal form (or canonical form).
Vector.make_valid()	Repairs invalid geometries.
Vector.difference(other[, align])	Returns a Vector of the points in each aligned geometry that are not in other.
Vector.symmetric_difference(other[, align])	Returns a Vector of the symmetric difference of points in each aligned geometry with other.
Vector.union(other[, align])	Returns a Vector of the union of points in each aligned geometry with other.
Vector.intersection(other[, align])	Returns a Vector of the intersection of points in each aligned geometry with other.
Vector.clip_by_rect(xmin, ymin, xmax, ymax)	Returns a Vector of the portions of geometry within the given rectangle.
Vector.buffer(distance[, resolution])	Returns a Vector of geometries representing all points within a given distance of each geometric object.
Vector.simplify(*args, **kwargs)	Returns a Vector containing a simplified representation of each geometry.
Vector.affine_transform(matrix)	Return a Vector with translated geometries.
Vector.translate([xoff, yoff, zoff])	Returns a Vector with translated geometries.
Vector.rotate(angle[, origin, use_radians])	Returns a Vector with rotated geometries.
Vector.scale([xfact, yfact, zfact, origin])	Returns a Vector with scaled geometries.
Vector.skew([xs, ys, origin, use_radians])	Returns a Vector with skewed 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])	Clip points, lines, or polygon geometries to the mask extent.
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.set_geometry(col[, drop, inplace, crs])	Set the Vector geometry using either an existing column or the specified input.
Vector.rename_geometry(col[, inplace])	Renames the Vector geometry column to the specified name.
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	Returns or appends to Vector a Series containing the area of each geometry in the Vector expressed in the units of the CRS.
Vector.length	Returns or appends to Vector a Series containing the length of each geometry expressed in the units of the CRS.
Vector.interiors	Returns or appends to Vector 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	Returns or appends to Vector 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	Returns or appends to Vector a Series of dtype('bool') with value True for features that are closed.
Vector.is_simple	Returns or appends to Vector a Series of dtype('bool') with value True for geometries that do not cross themselves.
Vector.has_z	Returns or appends to Vector a Series of dtype('bool') with value True for features that have a z-component.

Methods:

Vector.contains(other[, align])	Returns or appends to Vector a Series of dtype('bool') with value True for each aligned geometry that contains other.
Vector.geom_equals(other[, align])	Returns or appends to Vector a Series of dtype('bool') with value True for each aligned geometry equal to other.
Vector.geom_almost_equals(other[, decimal, ...])	Returns or appends to Vector a Series of dtype('bool') with value True if each aligned geometry is approximately equal to other.
Vector.crosses(other[, align])	Returns or appends to Vector a Series of dtype('bool') with value True for each aligned geometry that cross other.
Vector.disjoint(other[, align])	Returns or appends to Vector a Series of dtype('bool') with value True for each aligned geometry disjoint to other.
Vector.intersects(other[, align])	Returns or appends to Vector a Series of dtype('bool') with value True for each aligned geometry that intersects other.
Vector.overlaps(other[, align])	Returns True for all aligned geometries that overlap other, else False.
Vector.touches(other[, align])	Returns or appends to Vector a Series of dtype('bool') with value True for each aligned geometry that touches other.
Vector.within(other[, align])	Returns or appends to Vector a Series of dtype('bool') with value True for each aligned geometry that is within other.
Vector.covers(other[, align])	Returns a Series of dtype('bool') with value True for each aligned geometry that is entirely covering other.
Vector.covered_by(other[, align])	Returns a Series of dtype('bool') with value True for each aligned geometry that is entirely covered by other.
Vector.distance(other[, align])	Returns or appends to Vector a Series containing the distance to aligned 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.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_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])	Returns a GeoJSON representation of the Vector as a string.
Vector.to_postgis(name, con[, schema, ...])	Upload Vector into PostGIS database.
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.