geoutils.open_pointcloud

geoutils.open_pointcloud#

geoutils.open_pointcloud(filename, data_name=None, columns='main', chunks=None, downsample=1, *, as_object_type=None, level=None, load=False, parse_sensor_metadata=False)[source]#

Open a point cloud as a Xarray DataArray, Dataset or GeoDataFrame.

LAS, LAZ and COPC files are read with LasPy, GeoParquet files and partition directories with PyArrow, and other point vector formats with GeoPandas.

Passing chunks opens the point data lazily using Dask arrays (Xarray objects) or Dask-GeoPandas (Pandas object). Use downsample to select a deterministic random sample. For example, downsample=2 returns half the points, rounded up. For COPC, we select levels from coarse to fine until they contain enough points, then sample those points to the requested count. Other formats sample the full point cloud.

Use level to select COPC levels of detail, following LasPy. Each point belongs to one level: level 0 holds a coarse sample, and higher levels add points. Selected levels are combined into one point cloud. An integer selects only that level; level=range(3) combines levels 0 through 2. Explicit levels cannot be combined with downsample > 1.

Parameters:

  • filename (str | Path) – Point file or directory of GeoParquet partitions.

  • data_name (str | None) – Attribute containing point values. Defaults to Z for LAS, the saved active attribute for GeoParquet, or geometry elevations when no attribute is selected in other vector formats.

  • columns (Literal['all', 'main'] | list[str]) – Attributes to read from LAS or GeoParquet: main selects the active values, all selects every attribute, and a list selects named attributes as well as the active values. Ignored for other vector formats.

  • chunks (int | None) – Points per Dask chunk or partition. GeoParquet GeoDataFrame partitions follow the stored row groups. None uses deferred file reads unless load=True.

  • downsample (int | float | integer[Any] | floating[Any]) – Factor reducing the point count to ceil(N / downsample), with a deterministic random sample.

  • as_object_type (Literal['dataarray', 'dataset', 'geodataframe'] | None) – Returned representation: dataarray, dataset, or geodataframe. None uses config[“pointcloud_return_type”], which defaults to dataarray.

  • level (int | range | None) – COPC level of detail, or a range of levels. None combines all levels unless downsample is used.

  • load (bool) – Whether to read values immediately or not. The default False defers reads but requires using Xarray as object type, a GeoDataFrame requires Dask-GeoPandas.

  • parse_sensor_metadata (bool) – Parse sensor metadata from the filename and add it to the returned attributes.

Return type:

DataArray | Dataset | GeoDataFrame | Any

Returns:

A DataArray with active values and auxiliary coordinates, a Dataset with separate value variables, or a GeoDataFrame.