Compute the geometric features associated with each point's neighborhood:
Project description
📌 Description
The pgeof
library provides utilities for fast, parallelized computing ⚡ of local geometric
features for 3D point clouds ☁️ on CPU .
️List of available features ️👇
- linearity
- planarity
- scattering
- verticality (two formulations)
- normal_x
- normal_y
- normal_z
- length
- surface
- volume
- curvature
- optimal neighborhood size
pgeof
allows computing features in multiple fashions: on-the-fly subset of features
a la jakteristics, array of features, or
multiscale features. Moreover, pgeof
also offers functions for fast K-NN or
radius-NN searches 🔍.
Behind the scenes, the library is a Python wrapper around C++ utilities. The overall code is not intended to be DRY nor generic, it aims at providing efficient as possible implementations for some limited scopes and usages.
🧱 Installation
From binaries
python -m pip install pgeof
or
python -m pip install git+https://github.com/drprojects/point_geometric_features
Building from sources
pgeof
depends on Eigen library, Taskflow, nanoflann and nanobind.
The library adheres to PEP 517 and uses scikit-build-core as build backend.
Build dependencies (nanobind
, scikit-build-core
, ...) are fetched at build time.
C++ third party libraries are embedded as submodules.
# Clone project
git clone --recurse-submodules https://github.com/drprojects/point_geometric_features.git
cd point_geometric_features
# Build and install the package
python -m pip install .
🚀 Using Point Geometric Features
Here we summarize the very basics of pgeof
usage.
Users are invited to use help(pgeof)
for further details on parameters.
At its core pgeof
provides three functions to compute a set of features given a 3D point cloud and
some precomputed neighborhoods.
import pgeof
# Compute a set of 11 predefined features per points
pgeof.compute_features(
xyz, # The point cloud. A numpy array of shape (n, 3)
nn, # CSR data structure see below
nn_ptr, # CSR data structure see below
k_min = 1 # Minimum number of neighbors to consider for features computation
verbose = false # Basic verbose output, for debug purposes
)
# Sequence of n scales feature computation
pgeof.compute_features_multiscale(
...
k_scale # array of neighborhood size
)
# Feature computation with optimal neighborhood selection as exposed in Weinmann et al., 2015
# return a set of 12 features per points (11 + the optimal neighborhood size)
pgeof.compute_features_optimal(
...
k_min = 1, # Minimum number of neighbors to consider for features computation
k_step = 1, # Step size to take when searching for the optimal neighborhood
k_min_search = 1, # Starting size for searching the optimal neighborhood size. Should be >= k_min
)
⚠️ Please note that for theses three functions the neighbors are expected in CSR format. This allows expressing neighborhoods of varying sizes with dense arrays (e.g. the output of a radius search).
We provide very tiny and specialized k-NN and radius-NN search routines.
They rely on nanoflann
C++ library and should be faster and lighter than scipy
and
sklearn
alternatives.
Here are some examples of how to easily compute and convert typical k-NN or radius-NN neighborhoods to CSR format (nn
and nn_ptr
are two flat uint32
arrays):
import pgeof
import numpy as np
# Generate a random synthetic point cloud and k-nearest neighbors
num_points = 10000
k = 20
xyz = np.random.rand(num_points, 3).astype("float32")
knn, _ = pgeof.knn_search(xyz, xyz, k)
# Converting k-nearest neighbors to CSR format
nn_ptr = np.arange(num_points + 1) * k
nn = knn.flatten()
# You may need to convert nn/nn_ptr to uint32 arrays
nn_ptr = nn_ptr.astype("uint32")
nn = nn.astype("uint32")
features = pgeof.compute_features(xyz, nn, nn_ptr)
import pgeof
import numpy as np
# Generate a random synthetic point cloud and k-nearest neighbors
num_points = 10000
radius = 0.2
k = 20
xyz = np.random.rand(num_points, 3).astype("float32")
knn, _ = pgeof.radius_search(xyz, xyz, radius, k)
# Converting radius neighbors to CSR format
nn_ptr = np.r_[0, (knn >= 0).sum(axis=1).cumsum()]
nn = knn[knn >= 0]
# You may need to convert nn/nn_ptr to uint32 arrays
nn_ptr = nn_ptr.astype("uint32")
nn = nn.astype("uint32")
features = pgeof.compute_features(xyz, nn, nn_ptr)
At last, and as a by-product, we also provide a function to compute a subset of features on the fly.
It is inspired by the jakteristics python package (while
being less complete but faster).
The list of features to compute is given as an array of EFeatureID
.
import pgeof
from pgeof import EFeatureID
import numpy as np
# Generate a random synthetic point cloud and k-nearest neighbors
num_points = 10000
radius = 0.2
k = 20
xyz = np.random.rand(num_points, 3)
# Compute verticality and curvature
features = pgeof.compute_features_selected(xyz, radius, k, [EFeatureID.Verticality, EFeatureID.Curvature])
Known limitations
Some functions only accept float
scalar types and uint32
index types, and we avoid implicit
cast / conversions.
This could be a limitation in some situations (e.g. point clouds with double
coordinates or
involving very large big integer indices).
Some C++ functions could be templated / to accept other types without conversion.
For now, this feature is not enabled everywhere, to reduce compilation time and enhance code
readability.
Please let us know if you need this feature !
By convention, our normal vectors are forced to be oriented towards positive Z values. We make this design choice in order to return consistently-oriented normals.
Testing
Some basic tests and benchmarks are provided in the tests
directory.
Tests can be run in a clean and reproducible environments via tox
(tox run
and
tox run -e bench
).
💳 Credits
This implementation was largely inspired from Superpoint Graph. The main modifications here allow:
- parallel computation on all points' local neighborhoods, with neighborhoods of varying sizes
- more geometric features
- optimal neighborhood search from this paper
- some corrections on geometric features computation
Some heavy refactoring (port to nanobind, test, benchmarks), packaging, speed optimization, feature addition (NN search, on the fly feature computation...) were funded by:
Centre of Wildfire Research of Swansea University (UK) in collaboration with the Research Institute of Biodiversity (CSIC, Spain) and the Department of Mining Exploitation of the University of Oviedo (Spain).
Funding provided by the UK NERC project (NE/T001194/1):
'Advancing 3D Fuel Mapping for Wildfire Behaviour and Risk Mitigation Modelling'
and by the Spanish Knowledge Generation project (PID2021-126790NB-I00):
‘Advancing carbon emission estimations from wildfires applying artificial intelligence to 3D terrestrial point clouds’.
License
Point Geometric Features is licensed under the MIT License.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distributions
File details
Details for the file pgeof-0.3.0.tar.gz
.
File metadata
- Download URL: pgeof-0.3.0.tar.gz
- Upload date:
- Size: 4.8 MB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.1.1 CPython/3.12.5
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 79460efd9d2b0bedfa627cafbd5ad95b6d342b8735b36da6d62fa3e29d566a5b |
|
MD5 | 5d47589048d12e2bca8ccf363403855c |
|
BLAKE2b-256 | f19aa9c04aa38a75480cece144e049cc6c7a6334bfefcc2c5e93cdb16abbca2a |
File details
Details for the file pgeof-0.3.0-cp312-cp312-win_amd64.whl
.
File metadata
- Download URL: pgeof-0.3.0-cp312-cp312-win_amd64.whl
- Upload date:
- Size: 170.0 kB
- Tags: CPython 3.12, Windows x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.1.1 CPython/3.12.5
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 16ee12d5bef97e5e020c59eb286f9dfe9accbc91ea3d2673bdbc372504a39589 |
|
MD5 | cf7796910e3bd698f5bd758b04a72de1 |
|
BLAKE2b-256 | 9774896947344c0fdee8f125de8fbceafc9e095b72006f4dfcc0066708b8878d |
File details
Details for the file pgeof-0.3.0-cp312-cp312-musllinux_1_2_x86_64.whl
.
File metadata
- Download URL: pgeof-0.3.0-cp312-cp312-musllinux_1_2_x86_64.whl
- Upload date:
- Size: 677.4 kB
- Tags: CPython 3.12, musllinux: musl 1.2+ x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.1.1 CPython/3.12.5
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 3ad59c40d38edfc54463d08f1a44bb60af0dd5f61d47b75f1fa8025ac585fcea |
|
MD5 | 6601908d130d05fca95b33c5679b1664 |
|
BLAKE2b-256 | d3bc5029bddaf1ce4094895e53514c5ede2b85ccc9caaa582ca009611433cef7 |
File details
Details for the file pgeof-0.3.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
.
File metadata
- Download URL: pgeof-0.3.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
- Upload date:
- Size: 218.5 kB
- Tags: CPython 3.12, manylinux: glibc 2.17+ x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.1.1 CPython/3.12.5
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 75db29a74ce0538ff87a5a93f173129cec1f687c6e1b03c1d2041da5fd1c5383 |
|
MD5 | 646d66b04e5905283a9caf1d7f1c4d4b |
|
BLAKE2b-256 | d28ca88f52be9fc448425f967d7c49de9bb177c13d76b2eba064592d3a86f8ad |
File details
Details for the file pgeof-0.3.0-cp312-cp312-macosx_11_0_x86_64.whl
.
File metadata
- Download URL: pgeof-0.3.0-cp312-cp312-macosx_11_0_x86_64.whl
- Upload date:
- Size: 169.1 kB
- Tags: CPython 3.12, macOS 11.0+ x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.1.1 CPython/3.12.5
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | f4b4fe9aad9387cc9022106b003f90d4dad2fbe06a003d2af46cd8487e3fc185 |
|
MD5 | 09ed8d5be2f833c743f34d4b919c2458 |
|
BLAKE2b-256 | 3d490059f6214a8ce8afd68fd0c6357e938a5faaa1077ea2b26492e16d0b3a77 |
File details
Details for the file pgeof-0.3.0-cp312-cp312-macosx_11_0_arm64.whl
.
File metadata
- Download URL: pgeof-0.3.0-cp312-cp312-macosx_11_0_arm64.whl
- Upload date:
- Size: 147.1 kB
- Tags: CPython 3.12, macOS 11.0+ ARM64
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.1.1 CPython/3.12.5
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0fb31289dd57ea65b5aa6d498298f2d36f0fd8da34c6a5f3300199c35204f1fd |
|
MD5 | 3fb19205c7407f0fc2d9034005f9a75a |
|
BLAKE2b-256 | e7915f2320dd1e952c1f8a60fff11ae4cbcdffb564d160016b593fbada41d96e |
File details
Details for the file pgeof-0.3.0-cp311-cp311-win_amd64.whl
.
File metadata
- Download URL: pgeof-0.3.0-cp311-cp311-win_amd64.whl
- Upload date:
- Size: 170.1 kB
- Tags: CPython 3.11, Windows x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.1.1 CPython/3.12.5
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 23719bd23ed824a5013a46b79b7666c5c484934c99a773e317b3fd9f5efadfe4 |
|
MD5 | 643528d357b3a2e61156e76df1fbe8e8 |
|
BLAKE2b-256 | 79767d57b89698372fb899f0f382acc62afc8034eb2fbc15b986481791c3e30b |
File details
Details for the file pgeof-0.3.0-cp311-cp311-musllinux_1_2_x86_64.whl
.
File metadata
- Download URL: pgeof-0.3.0-cp311-cp311-musllinux_1_2_x86_64.whl
- Upload date:
- Size: 677.7 kB
- Tags: CPython 3.11, musllinux: musl 1.2+ x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.1.1 CPython/3.12.5
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 65e917c58174150829543a40f6dcf977385e1b15765dc33d8a6372cba2f6f439 |
|
MD5 | 8eac9b4dd417d40fd95c56d8beb0dc8b |
|
BLAKE2b-256 | 016c650a330186c7a0981406530d621e4435d89c4ae3b853d0fdcccb7ba7f4c7 |
File details
Details for the file pgeof-0.3.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
.
File metadata
- Download URL: pgeof-0.3.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
- Upload date:
- Size: 219.9 kB
- Tags: CPython 3.11, manylinux: glibc 2.17+ x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.1.1 CPython/3.12.5
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 2a3bdd8f7a9ff875f11d0906151562c738176b1e1fcd63697e81896895706a9e |
|
MD5 | ee69acb5c7d1832341a3bd0bec1a525e |
|
BLAKE2b-256 | 509a452a7d4666fe3e6716470a259513acb1e1cb35cdfdfe49d8265da10602e8 |
File details
Details for the file pgeof-0.3.0-cp311-cp311-macosx_11_0_x86_64.whl
.
File metadata
- Download URL: pgeof-0.3.0-cp311-cp311-macosx_11_0_x86_64.whl
- Upload date:
- Size: 168.7 kB
- Tags: CPython 3.11, macOS 11.0+ x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.1.1 CPython/3.12.5
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 14e3f8e6ec7c86ad2d1cad19de24b8bf878fc3bf68bb6660f93911be3a4bcd33 |
|
MD5 | 5eedaeecacaca4c5b550bd187f6f8d06 |
|
BLAKE2b-256 | f737bc58c1447e5a0d4b9a23a2c58d6f0c9bf770df7a65fa292226d7595aa001 |
File details
Details for the file pgeof-0.3.0-cp311-cp311-macosx_11_0_arm64.whl
.
File metadata
- Download URL: pgeof-0.3.0-cp311-cp311-macosx_11_0_arm64.whl
- Upload date:
- Size: 147.0 kB
- Tags: CPython 3.11, macOS 11.0+ ARM64
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.1.1 CPython/3.12.5
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | bb2c844c4bcd4bc97be458e22bb15e3ec7b3204de40066f7dac275476f560aa9 |
|
MD5 | d4350f606f0bed780cfad2d73d00ffea |
|
BLAKE2b-256 | 9ea364eb96e7ead3f5b83c7b1dabf0e13910fa67345123d5b914b16b53e1e57b |
File details
Details for the file pgeof-0.3.0-cp310-cp310-win_amd64.whl
.
File metadata
- Download URL: pgeof-0.3.0-cp310-cp310-win_amd64.whl
- Upload date:
- Size: 170.2 kB
- Tags: CPython 3.10, Windows x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.1.1 CPython/3.12.5
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | d66f8a99efc0b5342eefc3acf250f87063568296e77f4d880ab497493ffc54d9 |
|
MD5 | 8027d46d469c63ab8e1a0e8732b067d3 |
|
BLAKE2b-256 | 5d336c1e3f39cddf66c38d0295c3ac448338725b149d83eaa0b4e5b843ff1d3a |
File details
Details for the file pgeof-0.3.0-cp310-cp310-musllinux_1_2_x86_64.whl
.
File metadata
- Download URL: pgeof-0.3.0-cp310-cp310-musllinux_1_2_x86_64.whl
- Upload date:
- Size: 677.8 kB
- Tags: CPython 3.10, musllinux: musl 1.2+ x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.1.1 CPython/3.12.5
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 449eed6612c5646bda23e75b6e5e69d88e44a64129b5d0146c9bc54ea79ee535 |
|
MD5 | a0619280cfa14ea82a6f44c082fa70ef |
|
BLAKE2b-256 | e34c8f971f4ec4b814752f5977a3bbaad44cf986658726a905400d2b047b8988 |
File details
Details for the file pgeof-0.3.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
.
File metadata
- Download URL: pgeof-0.3.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
- Upload date:
- Size: 220.1 kB
- Tags: CPython 3.10, manylinux: glibc 2.17+ x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.1.1 CPython/3.12.5
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 723a55923d9d71d71e5f4baef6395e9297bebcb017caeb4bf00427f56f9c9b73 |
|
MD5 | c778fa28e91c9a977b2593be406d7743 |
|
BLAKE2b-256 | 3ff0e4ca4f968e6cfd461a8650ed7a4fa953ef38da94a72a16f1cec188732486 |
File details
Details for the file pgeof-0.3.0-cp310-cp310-macosx_11_0_x86_64.whl
.
File metadata
- Download URL: pgeof-0.3.0-cp310-cp310-macosx_11_0_x86_64.whl
- Upload date:
- Size: 168.8 kB
- Tags: CPython 3.10, macOS 11.0+ x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.1.1 CPython/3.12.5
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5901245fb6a3be10ebf66d51fc027057b29e901929ff58658cdc927fb6974178 |
|
MD5 | 88d87034a6ca14f3445af7365191abf8 |
|
BLAKE2b-256 | e1c93b741825865168b3577f5c7d1142d54973e220e86a4d83dc5d6e56a0e1c7 |
File details
Details for the file pgeof-0.3.0-cp310-cp310-macosx_11_0_arm64.whl
.
File metadata
- Download URL: pgeof-0.3.0-cp310-cp310-macosx_11_0_arm64.whl
- Upload date:
- Size: 147.1 kB
- Tags: CPython 3.10, macOS 11.0+ ARM64
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.1.1 CPython/3.12.5
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 4845a0338fe319c83a76e41d1122d38c1c0c1f540eea98cfa496c0a3dd761514 |
|
MD5 | d5f199f50a04f3baacc2cdd683cac5a9 |
|
BLAKE2b-256 | dd26fd0b94495ae43e19d913c589cdff03bf29f68ae16ca5dfe2812d1330b9d7 |
File details
Details for the file pgeof-0.3.0-cp39-cp39-win_amd64.whl
.
File metadata
- Download URL: pgeof-0.3.0-cp39-cp39-win_amd64.whl
- Upload date:
- Size: 170.6 kB
- Tags: CPython 3.9, Windows x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.1.1 CPython/3.12.5
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 9eb5857118e3e21be2972844b66436b67ddb0f508728bcbe192bfb00d64aee99 |
|
MD5 | efec75078db601dd50a40d636e9af2e4 |
|
BLAKE2b-256 | 3be8e20ae432cf4397f7605b37c6357ec9a8a36a35b5aa4058ba302948634a1e |
File details
Details for the file pgeof-0.3.0-cp39-cp39-musllinux_1_2_x86_64.whl
.
File metadata
- Download URL: pgeof-0.3.0-cp39-cp39-musllinux_1_2_x86_64.whl
- Upload date:
- Size: 678.0 kB
- Tags: CPython 3.9, musllinux: musl 1.2+ x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.1.1 CPython/3.12.5
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 19af0ddf8d0dd97c2c62e82fcd746389d96b231714832d8f92f53e04d30e7e50 |
|
MD5 | 516a033349a95bff53181e38965ffc2b |
|
BLAKE2b-256 | 70602b9cb93c4192b090092b241575dde2046567c40ede492863356b77cbc163 |
File details
Details for the file pgeof-0.3.0-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
.
File metadata
- Download URL: pgeof-0.3.0-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
- Upload date:
- Size: 220.2 kB
- Tags: CPython 3.9, manylinux: glibc 2.17+ x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.1.1 CPython/3.12.5
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | f155f7cff9baa1ff2cb3b57168947502c287b58038a5c42bc1c9b9995fe42731 |
|
MD5 | fa1ef511869aa961fbca0f508193348c |
|
BLAKE2b-256 | db0865d88e7f8070c540bcafb05882150025453f1189d0086f0c07670dcbd9ce |
File details
Details for the file pgeof-0.3.0-cp39-cp39-macosx_11_0_x86_64.whl
.
File metadata
- Download URL: pgeof-0.3.0-cp39-cp39-macosx_11_0_x86_64.whl
- Upload date:
- Size: 168.8 kB
- Tags: CPython 3.9, macOS 11.0+ x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.1.1 CPython/3.12.5
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | c003aa9616a8440916ca704c02f1e9552594d8d5e70eec6da45e25b9c1d7e85f |
|
MD5 | 0bf07d01e1ff937a4707cbf931bfcb2f |
|
BLAKE2b-256 | 75bd94442394922a15669f2bd92ba78bb98bf9c0cedec54298982ae9deb42324 |
File details
Details for the file pgeof-0.3.0-cp39-cp39-macosx_11_0_arm64.whl
.
File metadata
- Download URL: pgeof-0.3.0-cp39-cp39-macosx_11_0_arm64.whl
- Upload date:
- Size: 147.2 kB
- Tags: CPython 3.9, macOS 11.0+ ARM64
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.1.1 CPython/3.12.5
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 4c6c43519f4f26cd69d7a6609212b12490f26849dff52a83cb4b21db52428d9c |
|
MD5 | 8533869e9fe9dc2ad2fadbecab730a38 |
|
BLAKE2b-256 | e45de8a0aa2325ec537d1dc3ce15d76a599b3e81fcf2cb3e04f351af634fe9b5 |