Skip to main content

Compute the geometric features associated with each point's neighborhood:

Project description

Point Geometric Features

python C++ license

📌 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

pgeof-0.3.0.tar.gz (4.8 MB view details)

Uploaded Source

Built Distributions

pgeof-0.3.0-cp312-cp312-win_amd64.whl (170.0 kB view details)

Uploaded CPython 3.12 Windows x86-64

pgeof-0.3.0-cp312-cp312-musllinux_1_2_x86_64.whl (677.4 kB view details)

Uploaded CPython 3.12 musllinux: musl 1.2+ x86-64

pgeof-0.3.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (218.5 kB view details)

Uploaded CPython 3.12 manylinux: glibc 2.17+ x86-64

pgeof-0.3.0-cp312-cp312-macosx_11_0_x86_64.whl (169.1 kB view details)

Uploaded CPython 3.12 macOS 11.0+ x86-64

pgeof-0.3.0-cp312-cp312-macosx_11_0_arm64.whl (147.1 kB view details)

Uploaded CPython 3.12 macOS 11.0+ ARM64

pgeof-0.3.0-cp311-cp311-win_amd64.whl (170.1 kB view details)

Uploaded CPython 3.11 Windows x86-64

pgeof-0.3.0-cp311-cp311-musllinux_1_2_x86_64.whl (677.7 kB view details)

Uploaded CPython 3.11 musllinux: musl 1.2+ x86-64

pgeof-0.3.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (219.9 kB view details)

Uploaded CPython 3.11 manylinux: glibc 2.17+ x86-64

pgeof-0.3.0-cp311-cp311-macosx_11_0_x86_64.whl (168.7 kB view details)

Uploaded CPython 3.11 macOS 11.0+ x86-64

pgeof-0.3.0-cp311-cp311-macosx_11_0_arm64.whl (147.0 kB view details)

Uploaded CPython 3.11 macOS 11.0+ ARM64

pgeof-0.3.0-cp310-cp310-win_amd64.whl (170.2 kB view details)

Uploaded CPython 3.10 Windows x86-64

pgeof-0.3.0-cp310-cp310-musllinux_1_2_x86_64.whl (677.8 kB view details)

Uploaded CPython 3.10 musllinux: musl 1.2+ x86-64

pgeof-0.3.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (220.1 kB view details)

Uploaded CPython 3.10 manylinux: glibc 2.17+ x86-64

pgeof-0.3.0-cp310-cp310-macosx_11_0_x86_64.whl (168.8 kB view details)

Uploaded CPython 3.10 macOS 11.0+ x86-64

pgeof-0.3.0-cp310-cp310-macosx_11_0_arm64.whl (147.1 kB view details)

Uploaded CPython 3.10 macOS 11.0+ ARM64

pgeof-0.3.0-cp39-cp39-win_amd64.whl (170.6 kB view details)

Uploaded CPython 3.9 Windows x86-64

pgeof-0.3.0-cp39-cp39-musllinux_1_2_x86_64.whl (678.0 kB view details)

Uploaded CPython 3.9 musllinux: musl 1.2+ x86-64

pgeof-0.3.0-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (220.2 kB view details)

Uploaded CPython 3.9 manylinux: glibc 2.17+ x86-64

pgeof-0.3.0-cp39-cp39-macosx_11_0_x86_64.whl (168.8 kB view details)

Uploaded CPython 3.9 macOS 11.0+ x86-64

pgeof-0.3.0-cp39-cp39-macosx_11_0_arm64.whl (147.2 kB view details)

Uploaded CPython 3.9 macOS 11.0+ ARM64

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

Hashes for pgeof-0.3.0.tar.gz
Algorithm Hash digest
SHA256 79460efd9d2b0bedfa627cafbd5ad95b6d342b8735b36da6d62fa3e29d566a5b
MD5 5d47589048d12e2bca8ccf363403855c
BLAKE2b-256 f19aa9c04aa38a75480cece144e049cc6c7a6334bfefcc2c5e93cdb16abbca2a

See more details on using hashes here.

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

Hashes for pgeof-0.3.0-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 16ee12d5bef97e5e020c59eb286f9dfe9accbc91ea3d2673bdbc372504a39589
MD5 cf7796910e3bd698f5bd758b04a72de1
BLAKE2b-256 9774896947344c0fdee8f125de8fbceafc9e095b72006f4dfcc0066708b8878d

See more details on using hashes here.

File details

Details for the file pgeof-0.3.0-cp312-cp312-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for pgeof-0.3.0-cp312-cp312-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 3ad59c40d38edfc54463d08f1a44bb60af0dd5f61d47b75f1fa8025ac585fcea
MD5 6601908d130d05fca95b33c5679b1664
BLAKE2b-256 d3bc5029bddaf1ce4094895e53514c5ede2b85ccc9caaa582ca009611433cef7

See more details on using hashes here.

File details

Details for the file pgeof-0.3.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for pgeof-0.3.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 75db29a74ce0538ff87a5a93f173129cec1f687c6e1b03c1d2041da5fd1c5383
MD5 646d66b04e5905283a9caf1d7f1c4d4b
BLAKE2b-256 d28ca88f52be9fc448425f967d7c49de9bb177c13d76b2eba064592d3a86f8ad

See more details on using hashes here.

File details

Details for the file pgeof-0.3.0-cp312-cp312-macosx_11_0_x86_64.whl.

File metadata

File hashes

Hashes for pgeof-0.3.0-cp312-cp312-macosx_11_0_x86_64.whl
Algorithm Hash digest
SHA256 f4b4fe9aad9387cc9022106b003f90d4dad2fbe06a003d2af46cd8487e3fc185
MD5 09ed8d5be2f833c743f34d4b919c2458
BLAKE2b-256 3d490059f6214a8ce8afd68fd0c6357e938a5faaa1077ea2b26492e16d0b3a77

See more details on using hashes here.

File details

Details for the file pgeof-0.3.0-cp312-cp312-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for pgeof-0.3.0-cp312-cp312-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 0fb31289dd57ea65b5aa6d498298f2d36f0fd8da34c6a5f3300199c35204f1fd
MD5 3fb19205c7407f0fc2d9034005f9a75a
BLAKE2b-256 e7915f2320dd1e952c1f8a60fff11ae4cbcdffb564d160016b593fbada41d96e

See more details on using hashes here.

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

Hashes for pgeof-0.3.0-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 23719bd23ed824a5013a46b79b7666c5c484934c99a773e317b3fd9f5efadfe4
MD5 643528d357b3a2e61156e76df1fbe8e8
BLAKE2b-256 79767d57b89698372fb899f0f382acc62afc8034eb2fbc15b986481791c3e30b

See more details on using hashes here.

File details

Details for the file pgeof-0.3.0-cp311-cp311-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for pgeof-0.3.0-cp311-cp311-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 65e917c58174150829543a40f6dcf977385e1b15765dc33d8a6372cba2f6f439
MD5 8eac9b4dd417d40fd95c56d8beb0dc8b
BLAKE2b-256 016c650a330186c7a0981406530d621e4435d89c4ae3b853d0fdcccb7ba7f4c7

See more details on using hashes here.

File details

Details for the file pgeof-0.3.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for pgeof-0.3.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 2a3bdd8f7a9ff875f11d0906151562c738176b1e1fcd63697e81896895706a9e
MD5 ee69acb5c7d1832341a3bd0bec1a525e
BLAKE2b-256 509a452a7d4666fe3e6716470a259513acb1e1cb35cdfdfe49d8265da10602e8

See more details on using hashes here.

File details

Details for the file pgeof-0.3.0-cp311-cp311-macosx_11_0_x86_64.whl.

File metadata

File hashes

Hashes for pgeof-0.3.0-cp311-cp311-macosx_11_0_x86_64.whl
Algorithm Hash digest
SHA256 14e3f8e6ec7c86ad2d1cad19de24b8bf878fc3bf68bb6660f93911be3a4bcd33
MD5 5eedaeecacaca4c5b550bd187f6f8d06
BLAKE2b-256 f737bc58c1447e5a0d4b9a23a2c58d6f0c9bf770df7a65fa292226d7595aa001

See more details on using hashes here.

File details

Details for the file pgeof-0.3.0-cp311-cp311-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for pgeof-0.3.0-cp311-cp311-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 bb2c844c4bcd4bc97be458e22bb15e3ec7b3204de40066f7dac275476f560aa9
MD5 d4350f606f0bed780cfad2d73d00ffea
BLAKE2b-256 9ea364eb96e7ead3f5b83c7b1dabf0e13910fa67345123d5b914b16b53e1e57b

See more details on using hashes here.

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

Hashes for pgeof-0.3.0-cp310-cp310-win_amd64.whl
Algorithm Hash digest
SHA256 d66f8a99efc0b5342eefc3acf250f87063568296e77f4d880ab497493ffc54d9
MD5 8027d46d469c63ab8e1a0e8732b067d3
BLAKE2b-256 5d336c1e3f39cddf66c38d0295c3ac448338725b149d83eaa0b4e5b843ff1d3a

See more details on using hashes here.

File details

Details for the file pgeof-0.3.0-cp310-cp310-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for pgeof-0.3.0-cp310-cp310-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 449eed6612c5646bda23e75b6e5e69d88e44a64129b5d0146c9bc54ea79ee535
MD5 a0619280cfa14ea82a6f44c082fa70ef
BLAKE2b-256 e34c8f971f4ec4b814752f5977a3bbaad44cf986658726a905400d2b047b8988

See more details on using hashes here.

File details

Details for the file pgeof-0.3.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for pgeof-0.3.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 723a55923d9d71d71e5f4baef6395e9297bebcb017caeb4bf00427f56f9c9b73
MD5 c778fa28e91c9a977b2593be406d7743
BLAKE2b-256 3ff0e4ca4f968e6cfd461a8650ed7a4fa953ef38da94a72a16f1cec188732486

See more details on using hashes here.

File details

Details for the file pgeof-0.3.0-cp310-cp310-macosx_11_0_x86_64.whl.

File metadata

File hashes

Hashes for pgeof-0.3.0-cp310-cp310-macosx_11_0_x86_64.whl
Algorithm Hash digest
SHA256 5901245fb6a3be10ebf66d51fc027057b29e901929ff58658cdc927fb6974178
MD5 88d87034a6ca14f3445af7365191abf8
BLAKE2b-256 e1c93b741825865168b3577f5c7d1142d54973e220e86a4d83dc5d6e56a0e1c7

See more details on using hashes here.

File details

Details for the file pgeof-0.3.0-cp310-cp310-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for pgeof-0.3.0-cp310-cp310-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 4845a0338fe319c83a76e41d1122d38c1c0c1f540eea98cfa496c0a3dd761514
MD5 d5f199f50a04f3baacc2cdd683cac5a9
BLAKE2b-256 dd26fd0b94495ae43e19d913c589cdff03bf29f68ae16ca5dfe2812d1330b9d7

See more details on using hashes here.

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

Hashes for pgeof-0.3.0-cp39-cp39-win_amd64.whl
Algorithm Hash digest
SHA256 9eb5857118e3e21be2972844b66436b67ddb0f508728bcbe192bfb00d64aee99
MD5 efec75078db601dd50a40d636e9af2e4
BLAKE2b-256 3be8e20ae432cf4397f7605b37c6357ec9a8a36a35b5aa4058ba302948634a1e

See more details on using hashes here.

File details

Details for the file pgeof-0.3.0-cp39-cp39-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for pgeof-0.3.0-cp39-cp39-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 19af0ddf8d0dd97c2c62e82fcd746389d96b231714832d8f92f53e04d30e7e50
MD5 516a033349a95bff53181e38965ffc2b
BLAKE2b-256 70602b9cb93c4192b090092b241575dde2046567c40ede492863356b77cbc163

See more details on using hashes here.

File details

Details for the file pgeof-0.3.0-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for pgeof-0.3.0-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 f155f7cff9baa1ff2cb3b57168947502c287b58038a5c42bc1c9b9995fe42731
MD5 fa1ef511869aa961fbca0f508193348c
BLAKE2b-256 db0865d88e7f8070c540bcafb05882150025453f1189d0086f0c07670dcbd9ce

See more details on using hashes here.

File details

Details for the file pgeof-0.3.0-cp39-cp39-macosx_11_0_x86_64.whl.

File metadata

File hashes

Hashes for pgeof-0.3.0-cp39-cp39-macosx_11_0_x86_64.whl
Algorithm Hash digest
SHA256 c003aa9616a8440916ca704c02f1e9552594d8d5e70eec6da45e25b9c1d7e85f
MD5 0bf07d01e1ff937a4707cbf931bfcb2f
BLAKE2b-256 75bd94442394922a15669f2bd92ba78bb98bf9c0cedec54298982ae9deb42324

See more details on using hashes here.

File details

Details for the file pgeof-0.3.0-cp39-cp39-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for pgeof-0.3.0-cp39-cp39-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 4c6c43519f4f26cd69d7a6609212b12490f26849dff52a83cb4b21db52428d9c
MD5 8533869e9fe9dc2ad2fadbecab730a38
BLAKE2b-256 e45de8a0aa2325ec537d1dc3ce15d76a599b3e81fcf2cb3e04f351af634fe9b5

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page