API Reference

odc.geo.xr

Interfacing with xarray.DataArray and xarray.Dataset classes.

ODCExtension(state)	ODC extension base class.
ODCExtension.geobox	Query GeoBox or GCPGeoBox.
ODCExtension.output_geobox(crs, **kw)	Compute geobox of this data in other projection.
ODCExtension.spatial_dims	Return names of spatial dimensions, or None.
ODCExtension.crs	Query CRS.
ODCExtension.map_bounds()	See odc.geo.geobox.GeoBox.map_bounds().
ODCExtension.crop(poly[, apply_mask, ...])	Crops and optionally mask an xarray.Dataset or xarray.DataArray to the spatial extent of a geometry.
ODCExtension.mask(poly[, invert, all_touched])	Apply a polygon geometry as a mask, setting all xarray.Dataset or xarray.DataArray pixels outside the rasterized polygon to NaN.
ODCExtension.explore([map, bands, vmin, ...])	Plot xarray data on an interactive folium leaflet map for rapid data exploration.
ODCExtensionDa(xx)	ODC extension for xarray.DataArray.
ODCExtensionDa.assign_crs(crs[, crs_coord_name])	See odc.geo.xr.assign_crs().
ODCExtensionDa.reload()	Reload geospatial state info in-place.
ODCExtensionDa.write_cog(fname, *[, ...])	Save xarray.DataArray to a file in Cloud Optimized GeoTiff format.
ODCExtensionDa.to_cog([blocksize, ...])	Compress xarray.DataArray into Cloud Optimized GeoTiff bytes in memory.
ODCExtensionDa.reproject(how, *[, ...])	Reproject raster to different projection/resolution.
ODCExtensionDa.colorize([cmap, attrs, clip, ...])	Apply colormap to data.
ODCExtensionDa.add_to(map, *[, name, index, ...])	Add image to an interactive map.
ODCExtensionDa.compress(*args[, ...])	Save image to RAM in jpeg/png/webp format.
ODCExtensionDa.ydim	Index of the Y dimension.
ODCExtensionDa.xdim	Index of the X dimension.
ODCExtensionDa.nodata	Extract nodata/_FillValue attribute if set.
ODCExtensionDs(ds)	ODC extension for xarray.Dataset.
ODCExtensionDs.to_rgba([bands, vmin, vmax])	Convert dataset to RGBA image.
ODCExtensionDs.reload()	Reload geospatial state info in-place.
assign_crs(xx, crs[, crs_coord_name])	Assign CRS for a non-georegistered array or dataset.
rasterize(poly, how, *[, value_inside, ...])	Generate raster from geometry.
spatial_dims(xx[, relaxed])	Find spatial dimensions of xx.
wrap_xr(im, gbox, *[, time, nodata, ...])	Wrap xarray around numpy array with CRS and x,y coords.
xr_coords(gbox[, crs_coord_name, always_yx, ...])	Dictionary of Coordinates in xarray format.
xr_reproject(src, how, *[, resampling, ...])	Reproject raster to different projection/resolution.
xr_zeros(geobox[, dtype, chunks, time, ...])	Construct geo-registered xarray from a GeoBox.
colorize(x[, cmap, attrs, clip, vmin, vmax, ...])	Apply colormap to data.
to_rgba(ds[, bands, vmin, vmax])	Convert dataset to RGBA image.
add_to(xx, map, *[, name, index, fmt, ...])	Add image to an interactive map.
rio_reproject(src, dst, s_gbox, d_gbox, ...)	Perform reproject from ndarray->ndarray using rasterio as backend library.
to_cog(geo_im[, blocksize, ovr_blocksize, ...])	Compress xarray.DataArray into Cloud Optimized GeoTiff bytes in memory.
write_cog(geo_im, fname, *[, overwrite, ...])	Save xarray.DataArray to a file in Cloud Optimized GeoTiff format.
compress(xx, /, *args[, as_data_url, ...])	Save image to RAM in jpeg/png/webp format.
mask(xx, poly[, invert, all_touched])	Apply a polygon geometry as a mask, setting all xarray.Dataset or xarray.DataArray pixels outside the rasterized polygon to NaN.
crop(xx, poly[, apply_mask, all_touched])	Crops and optionally mask an xarray.Dataset or xarray.DataArray to the spatial extent of a geometry.

odc.geo.cog

Cloud Optimized GeoTIFF construction

save_cog_with_dask(xx[, dst, compression, ...])	Save a Cloud Optimized GeoTIFF to S3 or file with Dask.
cog_gbox(gbox, *[, tile, nlevels])	Return padded gbox with safe dimensions for COG.
to_cog(geo_im[, blocksize, ovr_blocksize, ...])	Compress xarray.DataArray into Cloud Optimized GeoTiff bytes in memory.
write_cog(geo_im, fname, *[, overwrite, ...])	Save xarray.DataArray to a file in Cloud Optimized GeoTiff format.
write_cog_layers(layers[, dst, overwrite, ...])	Write COG from externally computed overviews.

odc.geo.geobox

Methods for creating and manipulating geoboxes.

GeoBox

GeoBox(shape, affine, crs)	Defines the location and resolution of a rectangular grid of data, including it's CRS.
GeoBox.from_geopolygon(geopolygon[, ...])	Construct GeoBox from a polygon.
GeoBox.from_bbox(bbox[, crs, tight, shape, ...])	Construct GeoBox from a bounding box.
GeoBox.from_rio(rdr)	Construct GeoBox from rasterio.
GeoBox.affine	Linear mapping from pixel space to CRS.
GeoBox.anchor	Anchor point in pixel coordinates.
GeoBox.boundary([pts_per_side])	Boundary of a GeoBox.
GeoBox.buffered(xbuff[, ybuff])	Produce a tile buffered by xbuff, ybuff (in CRS units).
GeoBox.coordinates	Query coordinates.
GeoBox.crs	Coordinate Reference System of the GeoBox.
GeoBox.dimensions	List of dimension names of the GeoBox.
GeoBox.dims	List of dimension names of the GeoBox.
GeoBox.flipx()	Flip along X axis.
GeoBox.flipy()	Flip along Y axis.
GeoBox.extent	GeoBox footprint in native CRS.
GeoBox.explore([map, grid_lines, tiles, ...])	Plot a visual representation of the GeoBox's extent on an interactive folium leaflet map.
GeoBox.footprint(crs[, buffer, npoints])	Compute footprint in foreign CRS.
GeoBox.boundingbox	GeoBox bounding box in the native CRS.
GeoBox.map_bounds()	Query bounds in folium/ipyleaflet style.
GeoBox.geographic_extent	GeoBox extent in EPSG:4326.
GeoBox.overlap_roi(other[, tol])	Compute overlap as ROI.
GeoBox.height	Height in pixels (ny).
GeoBox.is_empty()	Check if geobox is "empty".
GeoBox.left	Same size geobox to the left of this one.
GeoBox.right	Same size geobox to the right of this one.
GeoBox.top	Same size geobox directly above this one.
GeoBox.bottom	Same size geobox directly below this one.
GeoBox.pad(padx[, pady])	Pad geobox.
GeoBox.pad_wh([alignx, aligny])	Possibly expand GeoBox by a few pixels.
GeoBox.resolution	Resolution, pixel size in CRS units.
GeoBox.aspect	Aspect ratio (X/Y in pixel space).
GeoBox.rotate(deg)	Rotate GeoBox around the center.
GeoBox.shape	Shape in pixels (height, width).
GeoBox.transform	Linear mapping from pixel space to CRS.
GeoBox.translate_pix(tx, ty)	Shift GeoBox in pixel plane.
GeoBox.snap_to(other)	Snap pixel grid to other.
GeoBox.enclosing(region)	Construct compatible geobox covering given region.
GeoBox.to_crs(crs, *[, resolution, shape, ...])	Compute GeoBox covering the same region in a different projection.
GeoBox.width	Width in pixels (nx).
GeoBox.zoom_out(factor)	Compute GeoBox with changed resolution.
GeoBox.zoom_to([shape, resolution])	Change GeoBox shape.
GeoBox.qr2sample(n[, padding, with_edges, ...])	Generate quasi-random sample of image locations.
GeoBox.__mul__(transform)	Apply affine transform on pixel side.
GeoBox.__rmul__(transform)	Apply affine transform on CRS side.

GeoboxTiles

GeoboxTiles(box, tile_shape, *[, _tiles])	Partition GeoBox into sub geoboxes.
GeoboxTiles.base	Access base Geobox
GeoboxTiles.chunk_shape(idx)	Query chunk shape for a given chunk.
GeoboxTiles.chunks
GeoboxTiles.range_from_bbox(bbox)	Intersect with a bounding box.
GeoboxTiles.shape	Number of tiles along each dimension.
GeoboxTiles.tiles(query)	Return tile indexes overlapping with a given geometry.
GeoboxTiles.grid_intersect(src)	Figure out tile to tile overlap graph between two grids.
GeoboxTiles.roi	Access ROI covered by tile.

Standalone Methods

bounding_box_in_pixel_domain(geobox, reference)	Bounding box of geobox in pixel space of reference.
geobox_intersection_conservative(geoboxes)	Intersection of geoboxes.
geobox_union_conservative(geoboxes)	Union of geoboxes as a geobox.
scaled_down_geobox(src_geobox, scaler)	Compute GeoBox of a zoomed image.
affine_transform_pix(gbox, transform)	Alias for odc.geo.geobox.GeoBox.__mul__().
flipx(gbox)	Alias for odc.geo.geobox.flipx().
flipy(gbox)	Alias for odc.geo.geobox.flipy().
gbox_boundary(gbox[, pts_per_side])	Alias for odc.geo.geobox.GeoBox.boundary().
pad(gbox, padx[, pady])	Alias for odc.geo.geobox.GeoBox.pad().
pad_wh(gbox[, alignx, aligny])	Alias for odc.geo.geobox.GeoBox.pad_wh().
rotate(gbox, deg)	Alias for odc.geo.geobox.GeoBox.().
translate_pix(gbox, tx, ty)	Alias for odc.geo.geobox.GeoBox.translate_pix().
zoom_out(gbox, factor)	Alias for odc.geo.geobox.GeoBox.zoom_out().
zoom_to(gbox[, shape, resolution])	Alias for odc.geo.geobox.GeoBox.zoom_to().

odc.geo.crs

Contains CRS class and related operations.

CRS(crs_spec)	Wrapper around pyproj.crs.CRS for backwards compatibility.
CRS.utm(x[, y, datum_name])	Construct appropriate UTM CRS for a given point.
CRS.to_epsg()	EPSG Code of the CRS or None.
CRS.to_wkt([pretty, version])	Generate WKT representation of this CRS.
CRS.transformer_to_crs(other[, always_xy])	Build coordinate transformer to other projection.
CRS.authority	Get (authority_name, code) tuple.
CRS.units	List of dimension units of the CRS.
CRS.dimensions	List of dimension names of the CRS.
CRSMismatchError	CRS Mismatch Error.
norm_crs(crs[, ctx])	Normalise CRS representation.
norm_crs_or_error(crs[, ctx])	Normalise CRS representation, raise error if input is None.
crs_units_per_degree(crs, lon[, lat, step])	Helper method for converting resolution between meters/degrees.

odc.geo.geom

Shapely geometry classes with CRS information attached.

Geometry(geom[, crs])	2D Geometry with CRS.
Geometry.to_crs(crs[, resolution, ...])	Convert geometry to a different Coordinate Reference System.
Geometry.geojson([properties, simplify, ...])	Render geometry to GeoJSON.
Geometry.explore([map, tiles, attr, map_kwds])	Plot Geometry on an interactive folium leaflet map for rapid data exploration.
BoundingBox(left, bottom, right, top[, crs])	Bounding box, defining extent in cartesian coordinates.
BoundingBox.explore([map, tiles, attr, map_kwds])	Plot BoundingBox on an interactive folium leaflet map for rapid data exploration.
BoundingBox.from_xy(x, y[, crs])	Construct BoundingBox from x and y ranges.
BoundingBox.from_points(p1, p2[, crs])	Construct BoundingBox from two points.
BoundingBox.from_transform(shape, transform)	Construct BoundingBox from image shape and transform.
BoundingBox.transform(transform)	Map bounding box through a linear transform.
BoundingBox.buffered(xbuff[, ybuff])	Return a new BoundingBox, buffered in the x and y dimensions.
BoundingBox.boundary([pts_per_side])	Points along the perimeter as a linear ring.
BoundingBox.qr2sample(n[, padding, ...])	Generate quasi-random sample of points within this boundingbox.
box(left, bottom, right, top, crs)	Create a 2D Box (Polygon).
line(coords, crs)	Create a 2D LineString (Connected set of lines).
point(x, y, crs)	Create a 2D Point.
polygon(outer, crs, *inners)	Create a 2D Polygon.
multigeom(geoms)	Construct Multi{Polygon|LineString|Point}.
multiline(coords, crs)	Create a 2D MultiLineString (Multiple disconnected sets of lines).
multipoint(coords, crs)	Create a 2D MultiPoint Geometry.
multipolygon(coords, crs)	Create a 2D MultiPolygon.
polygon_from_transform(shape, transform, crs)	Create a 2D Polygon from an affine transform and shape.
chop_along_antimeridian(geom[, precision])	Chop a geometry along the antimeridian.
clip_lon180(geom[, tol])	Tweak Geometry in the vicinity of longitude discontinuity.
common_crs(geoms)	Compute common CRS.
densify(coords, resolution)	Adds points so they are at most resolution units apart.
intersects(a, b)	Check for intersection.
lonlat_bounds(geom[, mode, resolution])	Return the bounding box of a geometry in lon/lat.
mid_longitude(geom)	Compute longitude of the center point of a geometry.
projected_lon(crs, lon[, lat, step])	Project vertical line along some longitude into a given CRS.
sides(poly)	Returns a sequence of Geometry[Line] objects.
bbox_intersection(bbs)	Compute intersection of boudning boxes.
bbox_union(bbs)	Compute union of bounding boxes.
unary_intersection(geoms)	Compute intersection of multiple (multi)polygons.
unary_union(geoms)	Compute union of multiple (multi)polygons efficiently.
triangulate(pts, **kw)	Creates the Delaunay triangulation and returns a geometry collection.

odc.geo

Basic types used for unambigous specification of X/Y values.

XY(x, y)	Immutable container for anything X/Y.
XY.xy	Convert to tuple in X,Y order.
XY.yx	Convert to tuple in Y,X order.
XY.lonlat	Convert to tuple in Longitude,Latitude order.
XY.latlon	Convert to tuple in Latitude,Longitude order.
XY.x	Access X value.
XY.y	Access Y value.
XY.lon	Access Longitude value (X).
XY.lat	Access Latitude value (Y).
XY.wh	Interpret as width, height, (X, Y) order.
XY.shape	Interpret as shape (Y, X) order.
Resolution(x[, y])	Resolution for X/Y dimensions.
Shape2d(x, y)	2d shape.
Index2d(x, y)	2d index.
AnchorEnum(value)	Defines which way to snap geobox pixel grid.
xy_(x[, y])	Construct from X,Y order.
yx_(y[, x])	Construct from Y,X order.
res_(x, /)	Resolution for square pixels with inverted Y axis.
resxy_(x, y, /)	Construct resolution from X,Y order.
resyx_(y, x, /)	Construct resolution from Y,X order.
wh_(w, h, /)	Shape from width/height.
shape_(x)	Normalise shape representation.
ixy_(x[, y])	Construct 2d index in X,Y order.
iyx_(y[, x])	Construct 2d index in Y,X order.

odc.geo.roi

Various helper methods for working with 2d slices into arrays.

polygon_path(x[, y, closed])	Points along axis aligned polygon.
roi_boundary(roi[, pts_per_side])	Get boundary points from a 2d roi.
roi_center(roi)	Return center point of an roi.
roi_from_points(xy, shape[, padding, align])	Build ROI from sample points.
roi_intersect(a, b)	Compute intersection of two ROIs.
roi_is_empty(roi)	Check if ROI is "empty".
roi_is_full(roi, shape)	Check if ROI covers the entire region.
roi_normalise(roi, shape)	Normalise ROI.
roi_pad(roi, pad, shape)	Pad ROI on each side, with clamping.
roi_shape(roi)	Shape of an array after cropping with roi.
scaled_down_roi(roi, scale)	Compute ROI for a scaled down image.
scaled_down_shape(shape, scale)	Compute shape of the overview image.
scaled_up_roi(roi, scale[, shape])	Compute ROI for a scaled up image.

odc.geo.math

Bin1D(sz[, origin, direction])	Class for translating continous coordinates to bin index.
Bin1D.bin(x)	Lookup bin index that x falls into.
Bin1D.from_sample_bin(idx, bin[, direction])	Construct Bin1D from a sample.
Poly2d(cc, A)	Wrapper around polyval2d with input normalization.
Poly2d.fit(aa, bb)	Fit 2d polynomial that minimizes poly(aa) - bb.
Poly2d.grid2d(x, y)	Evaluate on the Cartesian product of x and y.
Poly2d.with_input_transform(A)	Make a new transform by chaining a linear mapping A on input side.
affine_from_axis(xx, yy[, fallback_resolution])	Compute Affine transform from axis.
align_down(x, align)	Align integer down.
align_up(x, align)	Align integer up.
apply_affine(A, x, y)	Broadcast A*(x_i, y_i) across all elements of x/y.
clamp(x, lo, up)	Clamp x to be lo <= x <= up.
data_resolution_and_offset(data[, ...])	Compute resolution and offset from x/y axis data.
edge_index(shape[, closed])	Like ndindex in numpy but for edge locations and limited to 2d.
is_affine_st(A[, tol])	Check if transfrom is pure scale and translation.
is_almost_int(x, tol)	Check if number is close enough to an integer.
maybe_int(x, tol)	Turn almost ints to actual ints.
maybe_zero(x, tol)	Turn almost zeros to actual zeros.
norm_xy(pts[, out])	Normalize Nx2 points.
snap_scale(s[, tol])	Snap scale.
snap_affine(A[, ttol, stol, tol])	Snap scale and translation parts to integer when close enough.
split_float(x)	Split float number into whole and fractional parts.
split_translation(t)	Split translation into pixel aligned and sub-pixel parts.
quasi_random_r2(n[, shape, offset])	Generate quasi-random set of points.

odc.geo.gridspec

GridSpec(crs, tile_shape, resolution[, ...])	Definition for a regular spatial grid.
GridSpec.from_sample_tile(box, *[, shape, ...])	Construct odc.geo.gridspec.GridSpec from a sample tile.
GridSpec.web_tiles(zoom[, npix])	Construct GridSpec that matches slippy tiles.
GridSpec.alignment	Pixel boundary alignment.
GridSpec.dimensions	List of dimension names of the grid spec.
GridSpec.tile_shape	Tile shape in pixels (Y,X order, like numpy).
GridSpec.pt2idx(x, y)	Compute tile index from a point.
GridSpec.tile_geobox(tile_index)	Tile geobox.
GridSpec.__getitem__(idx)	Lookup GeoBox of a given tile.
GridSpec.tiles(bounds[, geobox_cache])	Query tiles overlapping with bounding box.
GridSpec.tiles_from_geopolygon(geopolygon[, ...])	Query tiles overlapping with a given polygon.
GridSpec.geojson(*[, bbox, geopolygon])	Render to GeoJSON.

odc.geo.overlap

ReprojectInfo(roi_src, roi_dst, paste_ok, ...)	Describes computed data loading parameters.
affine_from_pts(X, Y)	Given points X,Y compute A, such that: Y = A*X.
compute_output_geobox(gbox, crs, *[, ...])	Compute output GeoBox.
compute_reproject_roi(src, dst[, ttol, ...])	Compute reprojection information.

odc.geo.converters

from_geopandas(series)	Convert Geopandas data into list of Geometry.
extract_gcps_raw(src)	Extract Ground Control points from rasterio.DatasetReader.
extract_gcps_raw(src)	Extract Ground Control points from rasterio.DatasetReader.
map_crs(m, /)
rio_geobox(rdr)	Construct GeoBox from rasterio.