API Reference

Full information about geoutils’ functionality is provided on this page.

Geovector

geoutils.vectortools provides a toolset for working with vector data.

class geoutils.geovector.Vector(filename)[source]

Create a Vector object from a fiona-supported vector dataset.

copy()[source]

Return a copy of the Vector.

create_mask(rst=None, crs=None, xres=None, yres=None, bounds=None)[source]

Rasterize the vector features into a boolean raster which has the extent/dimensions of the provided raster file.

Alternatively, user can specify a grid to rasterize on using xres, yres, bounds and crs. Only xres is mandatory, by default yres=xres and bounds/crs are set to self’s. Vector features which fall outside the bounds of the raster file are not written to the new mask file.

Parameters

  • rst (Raster object or str) – A Raster object or string to filename

  • crs (pyproj.crs.crs.CRS, rasterio.crs.CRS) – A pyproj or rasterio CRS object (Default to rst.crs if not None then self.crs)

  • xres (float) – Output raster spatial resolution in x. Only is rst is None.

  • yres (float) – Output raster spatial resolution in y. Only if rst is None. (Default to xres)

  • bounds (tuple) – Output raster bounds (left, bottom, right, top). Only if rst is None (Default to self bounds)

Returns

array containing the mask

Return type

numpy.array

crop2raster(rst)[source]

Update self so that features outside the extent of a raster file are cropped. Reprojection is done on the fly if both data set have different projections.

Parameters

rst (Raster object or str) – A Raster object or string to filename

info()[source]

Returns string of information about the vector (filename, coordinate system, number of layers, features, etc.).

Returns

text information about Vector attributes.

Return type

str

query(expression, inplace=False)[source]

Query the Vector dataset with a valid Pandas expression.

Parameters

  • expression (str) – A python-like expression to evaluate. Example: “col1 > col2”

  • inplace – Whether the query should modify the data in place or return a modified copy.

Returns

Vector resulting from the provided query expression or itself if inplace=True.

rasterize(rst=None, crs=None, xres=None, yres=None, bounds=None, in_value=None, out_value=0)[source]

Return an array with input geometries burned in.

By default, output raster has the extent/dimensions of the provided raster file. Alternatively, user can specify a grid to rasterize on using xres, yres, bounds and crs. Only xres is mandatory, by default yres=xres and bounds/crs are set to self’s.

Burn value is set by user and can be either a single number, or an iterable of same length as self.ds. Default is an index from 1 to len(self.ds).

Parameters

  • rst (Raster object or str) – A raster to be used as reference for the output grid

  • crs (pyproj.crs.crs.CRS, rasterio.crs.CRS) – A pyproj or rasterio CRS object (Default to rst.crs if not None then self.crs)

  • xres (float) – Output raster spatial resolution in x. Only is rst is None.

  • yres (float) – Output raster spatial resolution in y. Only if rst is None. (Default to xres)

  • bounds (tuple) – Output raster bounds (left, bottom, right, top). Only if rst is None (Default to self bounds)

  • in_value (int, float, iterable) – Value(s) to be burned inside the polygons (Default is self.ds.index + 1)

  • out_value (int, float) – Value to be burned outside the polygons (Default is 0)

Returns

array containing the burned geometries

Return type

numpy.array

Georaster

geoutils.georaster provides a toolset for working with raster data.

class geoutils.georaster.Raster(filename_or_dataset, bands=None, load_data=True, downsample=1, masked=True, attrs=None, as_memfile=False)[source]

Create a Raster object from a rasterio-supported raster dataset.

If not otherwise specified below, attribute types and contents correspond to the attributes defined by rasterio.

Attributes:
filenamestr

The path/filename of the loaded, file, only set if a disk-based file is read in.

datanp.array

Loaded image. Dimensions correspond to (bands, height, width).

nbandsint

Number of bands loaded into .data

bandstuple

The indexes of the opened dataset which correspond to the bands loaded into data.

is_loadedbool

True if the image data have been loaded into this Raster.

dsrio.io.DatasetReader

Link to underlying DatasetReader object.

bounds

count

crs

dataset_mask

driver

dtypes

height

indexes

name

nodata

res

shape

transform

width

__init__(filename_or_dataset, bands=None, load_data=True, downsample=1, masked=True, attrs=None, as_memfile=False)[source]

Load a rasterio-supported dataset, given a filename.

Parameters

  • filename_or_dataset (str, Raster, rio.io.Dataset, rio.io.MemoryFile) – The filename of the dataset.

  • bands (int, or list of ints) – The band(s) to load into the object. Default is to load all bands.

  • load_data (bool) – Load the raster data into the object. Default is True.

  • downsample (int, float) – Reduce the size of the image loaded by this factor. Default is 1

  • masked (bool) – the data is loaded as a masked array, with no data values masked. Default is True.

  • attrs (list of strings) – Additional attributes from rasterio’s DataReader class to add to the Raster object. Default list is [‘bounds’, ‘count’, ‘crs’, ‘dataset_mask’, ‘driver’, ‘dtypes’, ‘height’, ‘indexes’, ‘name’, ‘nodata’, ‘res’, ‘shape’, ‘transform’, ‘width’] - if no attrs are specified, these will be added.

  • as_memfile (bool) – open the dataset via a rio.MemoryFile.

Returns

A Raster object

astype(dtype)[source]

Converts the data type of a Raster object.

Parameters

dtype (Union[type, str]) – Any numpy dtype or string accepted by numpy.astype

Return type

Raster

Returns

the output Raster with dtype changed.

coords(offset='corner', grid=True)[source]

Get x,y coordinates of all pixels in the raster.

Parameters

  • offset (str) – coordinate type. If ‘corner’, returns corner coordinates of pixels. If ‘center’, returns center coordinates. Default is corner.

  • grid (bool) – Return grid

Returns x,y

numpy arrays corresponding to the x,y coordinates of each pixel.

copy(new_array=None)[source]

Copy the Raster object in memory

Parameters

new_array (np.ndarray) – New array to use for the copied Raster

Returns

crop(cropGeom, mode='match_pixel')[source]

Crop the Raster to a given extent.

Parameters

  • cropGeom – Geometry to crop raster to, as either a Raster object, a Vector object, or a list of coordinates. If cropGeom is a Raster, crop() will crop to the boundary of the raster as returned by Raster.ds.bounds. If cropGeom is a Vector, crop() will crop to the bounding geometry. If cropGeom is a list of coordinates, the order is assumed to be [xmin, ymin, xmax, ymax].

  • mode (str) – one of ‘match_pixel’ (default) or ‘match_extent’. ‘match_pixel’ will preserve the original pixel resolution, cropping to the extent that most closely aligns with the current coordinates. ‘match_extent’ will match the extent exactly, adjusting the pixel resolution to fit the extent.

property data

Get data.

Returns

data array.

Return type

np.ndarray

classmethod from_array(data, transform, crs, nodata=None)[source]

Create a Raster from a numpy array and some geo-referencing information.

Parameters

  • data (np.ndarray) – data array

  • transform (tuple, affine.Affine.) – the 2-D affine transform for the image mapping. Either a tuple(x_res, 0.0, top_left_x, 0.0, y_res, top_left_y) or an affine.Affine object.

  • crs (rasterio.crs.CRS or int) – Coordinate Reference System for image. Either a rasterio CRS, or the EPSG integer.

  • nodata (int or float) – nodata value

Returns

A Raster object containing the provided data.

Return type

Raster.

Example:

You have a data array in EPSG:32645. It has a spatial resolution of 30 m in x and y, and its top left corner is X=478000, Y=3108140.

>>> transform = (30.0, 0.0, 478000.0, 0.0, -30.0, 3108140.0)
>>> myim = Raster.from_array(data, transform, 32645)
get_bounds_projected(out_crs, densify_pts_max=5000)[source]

Return self’s bounds in the given CRS.

Parameters

  • out_crs (rasterio.crs.CRS) – Output CRS

  • densify_pts_max (int) – Maximum points to be added between image corners to account for non linear edges (Default 5000) Reduce if time computation is really critical (ms) or increase if extent is not accurate enough.

ij2xy(i, j, offset='center')[source]

Return x,y coordinates for a given row, column index pair.

Parameters

  • i (array-like) – row (i) index of pixel.

  • j (array-like) – column (j) index of pixel.

  • offset (str) – return coordinates as “corner” or “center” of pixel

Returns x, y

x,y coordinates of i,j in reference system.

info(stats=False)[source]

Returns string of information about the raster (filename, coordinate system, number of columns/rows, etc.).

Parameters

stats (bool) – Add statistics for each band of the dataset (max, min, median, mean, std. dev.). Default is to not calculate statistics.

Returns

text information about Raster attributes.

Return type

str

interp_points(pts, input_latlon=False, mode='linear', band=1, area_or_point=None, **kwargs)[source]

Interpolate raster values at a given point, or sets of points.

Parameters

pts – Point(s) at which to interpolate raster value. If points fall outside of image,

value returned is nan. Shape should be (N,2)’ :type pts: array-like :param input_latlon: Whether the input is in latlon, unregarding of Raster CRS :type input_latlon: bool :param mode: One of ‘linear’, ‘cubic’, or ‘quintic’. Determines what type of spline is

used to interpolate the raster value at each point. For more information, see scipy.interpolate.interp2d. Default is linear.

Parameters

  • band (int) – Raster band to use

  • area_or_point (str, None) – shift index according to GDAL AREA_OR_POINT attribute (None) or force position (‘Point’ or ‘Area’) of the interpretation of where the raster value corresponds to in the pixel (‘Area’ = lower left or ‘Point’ = center)

Returns rpts

Array of raster value(s) for the given points.

Rtype rpts

array-like

intersection(rst)[source]

Returns the bounding box of intersection between this image and another.

If the rasters have different projections, the intersection extent is given in self’s projection system.

:param rst : path to the second image (or another Raster instance) :type rst: str, Raster

Returns

extent of the intersection between the 2 images (xmin, ymin, xmax, ymax) in self’s coordinate system.

Return type

tuple

property is_modified

Check whether file has been modified since it was created/opened.

Returns

True if Raster has been modified.

Return type

bool

load(bands=None, **kwargs)[source]

Load specific bands of the dataset, using rasterio.read(). Ensure that self.data.ndim = 3 for ease of use (needed e.g. in show)

Parameters

bands (int, or list of ints) – The band(s) to load. Note that rasterio begins counting at 1, not 0.

**kwargs: any additional arguments to rasterio.io.DatasetReader.read. Useful ones are: .. hlist:: * out_shape : to load a subsampled version * window : to load a cropped version * resampling : to set the resampling algorithm

outside_image(xi, yj, index=True)[source]

Check whether a given point falls outside of the raster.

Parameters

  • xi (array-like) – Indices (or coordinates) of x direction to check.

  • yj (array-like) – Indices (or coordinates) of y direction to check.

  • index (bool) – Interpret ij as raster indices (default is True). If False, assumes ij is coordinates.

Returns is_outside

True if ij is outside of the image.

reproject(dst_ref=None, dst_crs=None, dst_size=None, dst_bounds=None, dst_res=None, nodata=None, dtype=None, resampling=<Resampling.nearest: 0>, silent=False, n_threads=0, memory_limit=64)[source]

Reproject raster to a specified grid.

The output grid can either be given by a reference Raster (using dst_ref), or by manually providing the output CRS (dst_crs), dimensions (dst_size), resolution (with dst_size) and/or bounds (dst_bounds). Any resampling algorithm implemented in rasterio can be used.

Currently: requires image data to have been loaded into memory. NOT SUITABLE for large datasets yet! This requires work…

To reproject a Raster with different source bounds, first run Raster.crop.

Parameters

  • dst_ref (Raster object, rasterio data set or a str.) – a reference raster. If set will use the attributes of this raster for the output grid. Can be provided as Raster/rasterio data set or as path to the file.

  • crs (int, dict, str, CRS) – Specify the Coordinate Reference System to reproject to. If dst_ref not set, defaults to self.crs.

  • dst_size (tuple(int, int)) – Raster size to write to (x, y). Do not use with dst_res.

  • dst_bounds (dict or rio.coords.BoundingBox) – a BoundingBox object or a dictionary containing left, bottom, right, top bounds in the source CRS.

  • dst_res (float or tuple(float, float)) – Pixel size in units of target CRS. Either 1 value or (xres, yres). Do not use with dst_size.

  • nodata (int, float, None) – nodata value in reprojected data.

  • resampling (rio.warp or a matching string representation.) – A rasterio Resampling method

  • silent (bool) – If True, will not print warning statements

  • n_threads (int) – The number of worker threads. Defaults to (os.cpu_count() - 1).

  • memory_limit (int) – The warp operation memory limit in MB. Larger values may perform better.

Returns

Raster

Return type

Raster

save(filename, driver='GTiff', dtype=None, blank_value=None, co_opts={}, metadata={}, gcps=[], gcps_crs=None)[source]

Write the Raster to a geo-referenced file.

Given a filename to save the Raster to, create a geo-referenced file on disk which contains the contents of self.data.

If blank_value is set to an integer or float, then instead of writing the contents of self.data to disk, write this provided value to every pixel instead.

Parameters

  • filename (str) – Filename to write the file to.

  • driver (str) – the ‘GDAL’ driver to use to write the file as.

  • dtype (np.dtype) – Data Type to write the image as (defaults to dtype of image data)

  • blank_value (None, int, float.) – Use to write an image out with every pixel’s value corresponding to this value, instead of writing the image data to disk.

  • co_opts (dict) – GDAL creation options provided as a dictionary, e.g. {‘TILED’:’YES’, ‘COMPRESS’:’LZW’}

  • metadata (dict) – pairs of metadata key, value

  • gcps (list) – list of gcps, each gcp being [row, col, x, y, (z)]

  • gcps_crs (rasterio.crs.CRS) – the CRS of the GCPS (Default is None)

Returns

None.

set_dtypes(dtypes, update_array=True)[source]

Set new dtypes for bands (and possibly update arrays)

Parameters

  • dtypes (collections.abc.Iterable or type or str) – data types

  • update_array – change the existing dtype in arrays

Type

update_array: bool

set_ndv(ndv, update_array=False)[source]

Set new nodata values for bands (and possibly update arrays)

Parameters

  • ndv (collections.abc.Iterable or int or float) – nodata values

  • update_array (bool) – change the existing nodata in array

shift(xoff, yoff)[source]

Translate the Raster by a given x,y offset.

Parameters

  • xoff (float) – Translation x offset.

  • yoff (float) – Translation y offset.

show(band=None, cmap=None, vmin=None, vmax=None, cb_title=None, add_cb=True, ax=None, **kwargs)[source]

Show/display the image, with axes in projection of image.

This method is a wrapper to rasterio.plot.show. Any **kwargs which you give this method will be passed to rasterio.plot.show.

Parameters

  • band (int) – which band to plot, from 0 to self.count-1 (default is all)

  • cmap (matplotlib.colors.Colormap, str) – The figure’s colormap. Default is plt.rcParams[‘image.cmap’]

  • vmin (int, float) – Colorbar minimum value. Default is data min.

  • vmax (int, float) – Colorbar maximum value. Default is data min.

  • cb_title (str) – Colorbar label. Default is None.

  • add_cb (bool) – Set to True to display a colorbar. Default is True.

  • ax (matplotlib.axes.Axes) – A figure ax to be used for plotting. If None, will create default figure and axes, and plot figure directly.

Returns

if ax is not None, returns (ax, cbar) where cbar is the colorbar (None if add_cb is False)

Return type

(matplotlib.axes.Axes, matplotlib.colors.Colormap)

You can also pass in **kwargs to be used by the underlying imshow or contour methods of matplotlib. The example below shows provision of a kwarg for rasterio.plot.show, and a kwarg for matplotlib as well:

import matplotlib.pyplot as plt
ax1 = plt.subplot(111)
mpl_kws = {'cmap':'seismic'}
myimage.show(ax=ax1, mpl_kws)
split_bands(copy=False, subset=None)[source]

Split the bands into separate copied rasters.

Parameters

  • copy – Copy the bands or return slices of the original data.

  • subset – Optional. A subset of band indices to extract. Defaults to all.

Returns

A list of Rasters for each band, or one Raster if len(subset)==1.

to_xarray(name=None)[source]

Convert this Raster into an xarray DataArray using rioxarray.

This method uses rioxarray to generate a DataArray with associated geo-referencing information.

See the documentation of rioxarray and xarray for more information on the methods and attributes of the resulting DataArray.

Parameters

name (str) – Set the name of the DataArray.

Returns

xarray DataArray

Return type

xr.DataArray

value_at_coords(x, y, latlon=False, band=None, masked=False, window=None, return_window=False, boundless=True, reducer_function=<numpy.ma.core._frommethod object>)[source]

Extract the pixel value(s) at the nearest pixel(s) from the specified coordinates.

Extract pixel value of each band in dataset at the specified coordinates. Alternatively, if band is specified, return only that band’s pixel value.

Optionally, return mean of pixels within a square window.

Parameters

  • x (float) – x (or longitude) coordinate.

  • y (float) – y (or latitude) coordinate.

  • latlon (boolean) – Set to True if coordinates provided as longitude/latitude.

  • band (int) – the band number to extract from.

  • masked (bool, optional (default False)) – If masked is True the return value will be a masked array. Otherwise (the default) the return value will be a regular array.

  • window (None, int) – expand area around coordinate to dimensions window * window. window must be odd.

  • return_window (boolean) – If True when window=int, returns (mean,array) where array is the dataset extracted via the specified window size.

  • boundless (bool, optional (default False)) – If True, windows that extend beyond the dataset’s extent are permitted and partially or completely filled arrays (with self.nodata) will be returned as appropriate.

  • reducer_function (function, optional (Default is np.ma.mean)) – a function to apply to the values in window.

Returns

When called on a Raster or with a specific band set, return value of pixel.

Return type

float

Returns

If mutiple band Raster and the band is not specified, a dictionary containing the value of the pixel in each band.

Return type

dict

Returns

In addition, if return_window=True, return tuple of (values, arrays)

Return type

tuple

Examples

>>> self.value_at_coords(-48.125,67.8901,window=3)
Returns mean of a 3*3 window:
    v v v             v c v  | = float(mean)
    v v v /
(c = provided coordinate, v= value of surrounding coordinate)
xy2ij(x, y, op=<class 'numpy.float32'>, area_or_point=None, precision=None)[source]

Return row, column indices for a given x,y coordinate pair.

Parameters

  • x (array-like) – x coordinates

  • y (array-like) – y coordinates

  • op (Any) – operator to calculate index

  • precision (Any) – precision for rio.Dataset.index

  • area_or_point – shift index according to GDAL AREA_OR_POINT attribute (None) or force position (‘Point’ or ‘Area’) of

the interpretation of where the raster value corresponds to in the pixel (‘Area’ = lower left or ‘Point’ = center) :type area_or_point: str, None

Returns i, j

indices of x,y in the image.

Rtype i, j

array-like

Projection Tools

GeoUtils.projtools provides a toolset for dealing with different coordinate reference systems (CRS).

geoutils.projtools.bounds2poly(boundsGeom, in_crs=None, out_crs=None)[source]

Converts self’s bounds into a shapely Polygon. Optionally, returns it into a different CRS.

Parameters

  • boundsGeom (list, tuple, object with attributes bounds or total_bounds) – A geometry with bounds. Can be either a list of coordinates (xmin, ymin, xmax, ymax), a rasterio/Raster object, a geoPandas/Vector object

  • in_crs (rasterio.crs.CRS) – Input CRS

  • out_crs (rasterio.crs.CRS) – Output CRS

Returns

Output polygon

Return type

shapely Polygon

geoutils.projtools.compare_proj(proj1, proj2)[source]

Compare two projections to see if they are the same, using pyproj.CRS.is_exact_same.

Parameters

  • proj1 (pyproj.CRS, rasterio.crs.CRS) – The first projection to compare.

  • proj2 (pyproj.CRS, rasterio.crs.CRS) – The first projection to compare.

Returns

True if the two projections are the same.

geoutils.projtools.reproject_from_latlon(pts, out_crs, round_=2)[source]

Reproject a set of point from lat/lon to out_crs.

Parameters

  • pts (list, tuple, np.ndarray') – Input points to be reprojected. Must be of shape (2, N), i.e (x coords, y coords)

  • out_crs (rasterio.crs.CRS) – Output CRS

  • round (int) – Output rounding. Default of 2 ensures cm accuracy

Returns

Reprojected points, of same shape as pts.

Return type

list

geoutils.projtools.reproject_points(pts, in_crs, out_crs)[source]

Reproject a set of point from input_crs to output_crs.

Parameters

  • pts (list, tuple, np.ndarray') – Input points to be reprojected. Must be of shape (2, N), i.e (x coords, y coords)

  • in_crs (rasterio.crs.CRS) – Input CRS

  • out_crs (rasterio.crs.CRS) – Output CRS

Returns

Reprojected points, of same shape as pts.

Return type

list

geoutils.projtools.reproject_shape(inshape, in_crs, out_crs)[source]

Reproject a shapely geometry from one CRS into another CRS.

Parameters

  • inshape (shapely geometry) – Shapely geometry to be reprojected.

  • in_crs (rasterio.crs.CRS) – Input CRS

  • out_crs (rasterio.crs.CRS) – Output CRS

Returns

Reprojected geometry

Return type

shapely geometry

geoutils.projtools.reproject_to_latlon(pts, in_crs, round_=8)[source]

Reproject a set of point from in_crs to lat/lon.

Parameters

  • pts (list, tuple, np.ndarray') – Input points to be reprojected. Must be of shape (2, N), i.e (x coords, y coords)

  • in_crs (rasterio.crs.CRS) – Input CRS

  • round (int) – Output rounding. Default of 8 ensures cm accuracy

Returns

Reprojected points, of same shape as pts.

Return type

list