Metadata-Version: 2.5
Name: pointclouds
Version: 0.0.0
Summary: Point cloud (LAS/LAZ/COPC) I/O, filtering, decimation and gridding
Project-URL: homepage, https://github.com/serapeum-org/pointclouds
Project-URL: repository, https://github.com/serapeum-org/pointclouds
Project-URL: documentation, https://serapeum-org.github.io/pointclouds
Project-URL: Changelog, https://github.com/serapeum-org/pointclouds/blob/main/docs/change-log.md
Author-email: Mostafa Farrag <moah.farag@gmail.com>
License: GNU General Public License v3
License-File: LICENSE.md
Keywords: COPC,GIS,LAS,LAZ,lidar,point cloud,pointcloud
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: <4,>=3.11
Requires-Dist: laspy[lazrs]>=2.5
Requires-Dist: numpy>=2.0.0
Requires-Dist: pyproj>=3.7
Requires-Dist: scipy>=1.10
Provides-Extra: all
Requires-Dist: fsspec>=2024.1; extra == 'all'
Requires-Dist: pyramids-core>=0.70.0; extra == 'all'
Requires-Dist: s3fs; extra == 'all'
Provides-Extra: cloud
Requires-Dist: fsspec>=2024.1; extra == 'cloud'
Requires-Dist: s3fs; extra == 'cloud'
Provides-Extra: gis
Requires-Dist: pyramids-core>=0.70.0; extra == 'gis'
Description-Content-Type: text/markdown

# pointclouds

Read, filter, decimate and grid **point clouds** (LAS / LAZ, and COPC/EPT) in Python.

A *point cloud* is a set of 3-D measured points - typically from lidar or photogrammetry - each carrying `x`, `y`,
`z` plus per-point attributes such as intensity, return number and ASPRS classification. `pointclouds` reads the
standard exchange formats, exposes the header without touching the records, and provides the operations a cloud
needs before analysis or rendering: classification filtering, decimation, reprojection, and gridding to a raster
surface (DSM / DTM / density).

## Install

```bash
pip install pointclouds          # core: reads LAS/LAZ, grids to arrays, no GDAL required
pip install pointclouds[gis]     # + pyramids-gis: to_dataset() / to_feature_collection()
pip install pointclouds[cloud]   # + fsspec/s3fs: remote LAZ / COPC
pip install pointclouds[all]     # everything
```

The core depends only on `numpy`, `laspy`, `pyproj` and `scipy` - no GDAL - so it installs anywhere numpy runs.
GIS interoperability (turning a cloud into a `pyramids` `Dataset` or `FeatureCollection`) is an optional extra.

## Quick look

```python
import pointclouds as pc

cloud = pc.PointCloud.read_file("survey.laz")
cloud.crs, cloud.bounds, cloud.count          # from the header, no record read
xyz = cloud.to_array(("X", "Y", "Z"))         # (N, 3) float64

# COPC: read a window instead of the whole cloud - only the chunks that overlap are decompressed
box = pc.PointCloud.read_window("survey.copc.laz", bbox=(155000, 463000, 156000, 464000))
coarse = pc.PointCloud.read_window("survey.copc.laz", resolution=5.0)   # ~one point per 5 m

# EPT (Entwine): same windowed read, by directory or URL (remote needs the [cloud] extra)
box = pc.PointCloud.read_window("s3://bucket/survey-ept", bbox=(155000, 463000, 156000, 464000))

ground = cloud.filter(classification=2)
thin = ground.decimate(target=2_000_000, method="random")

arr, transform, crs = ground.to_grid(cell_size=1.0, aggregate="min")   # pure NumPy
dtm = ground.to_dataset(cell_size=1.0, aggregate="min")                # needs [gis]
```

## Where it sits

`pointclouds` is an independent package in the serapeum-org stack. It interoperates with
[`pyramids`](https://github.com/serapeum-org/pyramids) (the raster/vector GIS engine) through two converter methods
behind the `[gis]` extra, but does not depend on it for reading, gridding or classification. See
`planning/placement-decision.md` for the full architecture rationale.

## License

GPLv3.
