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.19.0-cp36-abi3-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 061a8c443c431d9f7497f3a7ee6bbb07ca10694f561c6afb0ab2a5669fc4845b |
|
MD5 | e4caf0b08c954e8559002dfe7f2d1a3d |
|
BLAKE2b-256 | 18c4f81dd1b9afe6374cd5bd1c36fc2aa8679c7d12c9d98d99465242dc8bc866 |
Hashes for ncollpyde-0.19.0-cp36-abi3-manylinux_2_5_x86_64.manylinux1_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 44dcf09e1bf1182545028f4fe9ced92cca876312e8880b6b722bf28b1dca0098 |
|
MD5 | cb0d8105d5ca47e3b45d04425428eae2 |
|
BLAKE2b-256 | ecc62cf06a369079717b948e53940404a62f2d2408cd8d5424ff9e876b0213c0 |
Hashes for ncollpyde-0.19.0-cp36-abi3-macosx_10_9_x86_64.macosx_11_0_arm64.macosx_10_9_universal2.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | e00d12ac0e682b5700a432f55eff392ab885aa29927e4d7a786fd40e2b58c6a6 |
|
MD5 | d4a2e84a28de36a5c5e7960eaba81c7d |
|
BLAKE2b-256 | 75a3b89736d889380317d575e1183d4f611821ebbcaca0b15617850a3431939c |