geoutils.Raster.to_pointcloud#
- Raster.to_pointcloud(data_column_name='b1', data_band=1, auxiliary_data_bands=None, auxiliary_column_names=None, subsample=1, as_array=False, random_state=None, force_pixel_offset='ul')[source]#
Convert raster to point cloud.
A point cloud is a vector of point geometries associated to a data column, and possibly other auxiliary data columns, see geoutils.PointCloud.
For a single band raster, the main data column name of the point cloud defaults to “b1” and stores values of that single band. For a multi-band raster, the main data column name of the point cloud defaults to “bX” where X is the data band index chosen by the user (defaults to 1, the first band). Optionally, all other bands can also be stored in columns “b1”, “b2”, etc. For more specific band selection, use Raster.split_bands previous to converting to point cloud.
Optionally, randomly subsample valid pixels for the data band (nodata values are skipped, but only for the band that will be used as data column of the point cloud). If ‘subsample’ is either 1, or is equal to the pixel count, all valid points are returned. If ‘subsample’ is smaller than 1 (for fractions), or smaller than the pixel count, a random subsample of valid points is returned.
If the raster is not loaded, sampling will be done from disk using rasterio.sample after loading only the masks of the dataset.
- Formats:
as_array == False: A vector with dataframe columns [“b1”, “b2”, …, “geometry”],
as_array == True: A numpy ndarray of shape (N, 2 + count) with the columns [x, y, b1, b2..].
- Parameters:
data_column_name (
str) – Name to use for point cloud data column, defaults to “bX” where X is the data band number.data_band (
int) – (Only for multi-band rasters) Band to use for data column, defaults to first. Band counting starts at 1.auxiliary_data_bands (
list[int] |None) – (Only for multi-band rasters) Whether to save other band numbers as auxiliary data columns, defaults to none.auxiliary_column_names (
list[str] |None) – (Only for multi-band rasters) Names to use for auxiliary data bands, only if auxiliary data bands is not none, defaults to “b1”, “b2”, etc.subsample (
float|int) – Subsample size. If > 1, parsed as a count, otherwise a fraction.as_array (
bool) – Return an array instead of a vector.random_state (
RandomState|int|None) – Random state or seed number.force_pixel_offset (
Literal['center','ul','ur','ll','lr']) – Force offset to derive point coordinate with. Raster coordinates normally only associate to upper-left corner “ul” (“Area” definition) or center (“Point” definition).
- Raises:
ValueError – If the sample count or fraction is poorly formatted.
- Return type:
ndarray[Any,dtype[Union[floating[Any],integer[Any]]]] |Vector- Returns:
A point cloud, or array of the shape (N, 2 + count) where N is the sample count.