A python wrapper around a subset of the ncollide rust library
Project description
A python library for spatial queries of points and line segments with meshes. ncollpyde wraps around a subset of the parry rust library (formerly its predecessor ncollide).
Free software: MIT License
Documentation: https://ncollpyde.readthedocs.io.
Install
pip install ncollpyde
Pre-built wheels are available for Linux, MacOS, and Windows. If you have a stable rust compiler, you should also be able to install from source.
Features
Checking whether points are inside a volume defined by a triangular mesh
Checking the intersection of line segments with the mesh
Get the (signed) distance from points to the boundary of a mesh
Usage
This library implements most of its functionality through the Volume class, instantiated from an array of vertices, and an array of triangles as indices into the vertex array.
# get an array of vertices and triangles which refer to those points
import meshio
mesh = meshio.read("meshes/teapot.stl")
# use this library
from ncollpyde import Volume
volume = Volume(mesh.points, mesh.cells_dict["triangle"])
# or, for convenience
volume = Volume.from_meshio(mesh)
# containment checks: singular and multiple
assert [-2.30, -4.15, 1.90] in volume
assert np.array_equal(
volume.contains(
[
[-2.30, -4.15, 1.90],
[-0.35, -0.51, 7.61],
]
),
[True, False]
)
# line segment intersection
seg_idxs, intersections, is_backface = volume.intersections(
[[-10, -10, -10], [0, 0, 3], [10, 10, 10]],
[[0, 0, 3], [10, 10, 10], [20, 20, 20]],
)
assert np.array_equal(seg_idxs, [0, 1]) # idx 2 does not intersect
assert np.array_equal(seg_idxs, [0, 1])
assert np.allclose(
intersections,
[
[-2.23347309, -2.23347309, 0.09648498],
[ 3.36591285, 3.36591285, 5.356139],
],
)
assert np.array_equal(
is_backface,
[False, True],
)
# distance from boundary (negative means internal)
assert np.array_equal(
volume.distance([[10, 10, 10], [0, 0, 3]]),
[10.08592464, -2.99951118],
)
See the API docs for more advanced usage.
Known issues
Performance gains for multi-threaded queries are underwhelming, especially for ray intersections: see this issue
- Very rare false positives for containment
Due to a bug in the underlying library
Only happens when the point is outside the mesh and fires a ray which touches a single edge or vertex of the mesh.
Also affects is_backface result for ray intersection checks
manylinux-compatible wheels are built on CI but not necessarily in your local environment. Always allow CI to deploy the wheels.
If you are installing from a source distribution rather than a wheel, you need a compatible rust toolchain
Meshes with >= ~4.3bn vertices are not supported, as the underlying library uses u32 to address them. This is probably not a problem at time of writing; such a mesh would take up hundreds of GB of RAM to operate on.
ncollpyde v0.11 was the last to support meshio < 4.0.
Acknowledgements
Thanks to top users Philipp Schlegel (check out navis!) and Nik Drummond for their help in debugging and expanding ncollpyde ‘s functionality.
Thanks also to pyo3/ maturin developers @konstin and @messense for taking an interest in the project and helping along the way.
Project details
Release history Release notifications | RSS feed
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
Hashes for ncollpyde-0.18.0-cp36-abi3-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 550888e9b2e7db39a1600608f360d55760c171448e40bfb43a8d15c044de8e9b |
|
MD5 | 131af9423b2f4aed0e61dd52a21a8de2 |
|
BLAKE2b-256 | e1f9e12f02eb60aeb452fd6037298c2e0d4394606820c8336cc1a1d1230d73c0 |
Hashes for ncollpyde-0.18.0-cp36-abi3-manylinux_2_5_x86_64.manylinux1_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | f47f6ba86b6a685c7aafa9943bc9c0d0a642dbf80c4fffa6bb1aa70a975febb5 |
|
MD5 | 49d73406decaa891d07f1ce62545b6fc |
|
BLAKE2b-256 | be0ddb644ebff5d88ff0e57ae875d4f13ab2742010598ff107c45f214e869bbf |
Hashes for ncollpyde-0.18.0-cp36-abi3-macosx_10_9_x86_64.macosx_11_0_arm64.macosx_10_9_universal2.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 82c4fcb4959c31a108a364402f97b8d07e3a8caa4b609b9dcc893c6030cea960 |
|
MD5 | b29b0a4451a6239601b105eb197b6107 |
|
BLAKE2b-256 | fd5e525aceccc503c2ad8c878930692f624ec559d49a822440e367e51cd60c17 |