gdf.pc.cosample() or PointCloud.cosample()

gdf.pc.cosample() or PointCloud.cosample()#

PointCloudBase.cosample(other, *, other_band=1, auxiliary=None, auxiliary_at=None, at=None, mask=None, mask_mode='inside', subsample=1, random_state=None, strategy='topk', raster_point_mode=None, grid_method='linear', resample_method='linear', grid_kwargs=None, resample_kwargs=None, align='raise', mp_config=None)[source]#

Sample this point cloud and another dataset at common finite locations.

This point cloud provides the default spatial support. Use raster_point_mode="grid_points" to grid point values onto a raster input instead. An explicit at chooses the exact output locations and must agree with any explicit mode. Raw auxiliary arrays must identify their primary input’s grid or point ordering.

Spatial inputs, explicit output support and raster or point masks must use one family: Raster/PointCloud objects, or DataArray/GeoDataFrame objects. The latter may mix eager and Dask storage. Plain arrays and vector outlines are accepted with either family.

Parameters:

  • other (geoutils.raster.base.RasterBase | DataArray | PointCloudBase | GeoDataFrame | ArrayLike) – Dataset to sample alongside this point cloud. A plain array follows this point cloud’s order.

  • other_band (int) – Band selected from other if it is a raster, counting from one.

  • auxiliary (Mapping[str, Any] | None) – Additional values by output name (e.g. {“slope”: slope_raster}). Select a raster band with {“slope”: (slope_raster, 2)} or a point column with {“intensity”: (points, “intensity”)}. Spatial inputs without a selector use the first raster band or active point values.

  • auxiliary_at (Literal['self', 'other'] | Mapping[str, Literal['self', 'other']] | None) – Input locations followed by plain auxiliary arrays: “self”, “other”, or a choice per name (e.g. {“slope”: “other”}). Spatial auxiliaries use their own coordinates.

  • at (Literal['self', 'other'] | geoutils.raster.base.RasterBase | DataArray | PointCloudBase | GeoDataFrame | None) – Output locations: “self”, “other”, or a reference raster/point cloud. Defaults to this point cloud. Point inputs must share the selected point order; “grid_points” selects a raster grid instead.

  • mask (geoutils.raster.base.RasterBase | DataArray | geoutils.vector.base.VectorBase | GeoDataFrame | ArrayLike | None) – Locations eligible for sampling, defined by a boolean array, spatial mask, or vector outlines.

  • mask_mode (Literal['inside', 'outside']) – Whether a vector mask keeps locations “inside” or “outside” its geometries.

  • subsample (int | float) – Fraction of common finite locations (e.g. 0.1), or maximum count (e.g. 1000); 1 keeps all.

  • random_state (int | Generator | None) – Seed or random generator for reproducible sampling (e.g. 42).

  • strategy (Literal['sequential', 'topk']) – Sampling with “topk” or “sequential”; “topk” keeps the same seeded sample across chunk sizes.

  • raster_point_mode (Literal['grid_points', 'resample_raster'] | None) – Conversion direction: “grid_points” places points on a raster, “resample_raster” reads rasters at points. Defaults to at’s locations, or this point cloud’s locations. Must agree with at.

  • grid_method (Literal['nearest', 'linear', 'cubic', 'idw'] | Literal['mean', 'average', 'minimum', 'min', 'maximum', 'max', 'range', 'count', 'stdev', 'average_distance', 'average_distance_pts'] | Interpolator | Reducer) – Point gridding by SciPy interpolation (“nearest”, “linear”, “cubic”), or circular “idw”, “mean”, “minimum”, “maximum”, “range”, “count”, “stdev”, “average_distance”, “average_distance_pts”. The aliases “average”, “min” and “max” select “mean”, “minimum” and “maximum”.

  • resample_method (Literal['nearest', 'linear', 'cubic', 'quintic', 'slinear', 'pchip', 'splinef2d'] | Literal['reduce']) – Raster interpolation using the SciPy methods “nearest”, “linear”, “cubic”, “quintic”, “slinear”, “pchip” or “splinef2d”. Window reduction (“reduce”) is not implemented.

  • grid_kwargs (Mapping[str, Any] | None) – Options for PointCloud.grid(), e.g. {“radius”: 2, “min_points”: 3} sets a two-pixel radius and minimum of three finite points for circular methods. Other options include “distance_power” for IDW and “engine” (“scipy” or “numba”). Set locations and method with at and grid_method.

  • resample_kwargs (Mapping[str, Any] | None) – Options for Raster.interp_points(), e.g. {“nodata_handling”: “ignore”}. The choices are “nearest”, “ignore”, “propagate”, a half-order rule, or a non-negative distance in pixels. Set locations, band and method with the corresponding cosample() arguments.

  • align (Literal['raise', 'reproject']) – Handling of mismatched grids or coordinate systems: “raise” an error, or “reproject” to match at. Point inputs must still share the same ordered coordinates when sampled at points.

  • mp_config (MultiprocConfig | None) – Worker and tile settings for multiprocessing. Raster output uses its outfile; cannot be combined with Dask inputs.

Return type:

geoutils.raster.base.RasterBase | DataArray | PointCloudBase | GeoDataFrame

Returns:

Raster or point cloud on the selected support; Xarray DataArray or eager/lazy GeoDataFrame for accessor calls. Bands or columns contain “self”, “other”, then auxiliaries in mapping order. Raster outputs retain the target grid with a common mask; point outputs retain selected geometries and index labels, with “self” as the active data attribute.