API reference

Top-level package for ncollpyde.

class ncollpyde.Volume(vertices: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], triangles: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], validate=False, threads: bool | None = None, n_rays=3, ray_seed=1991)[source]

Bases: object

contains(coords: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], threads: bool | None = None) → ndarray[Any, dtype[bool_]][source]

Check whether multiple points (as a Px3 array-like) are in the volume.

Parameters:

  • coords –

  • threads – None, Whether to parallelise the queries. If None (default), refer to the instance’s threads attribute.

Returns:

np.ndarray of bools, whether each point is inside the volume

distance(coords: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], signed: bool = True, threads: bool | None = None) → ndarray[source]

Check the distance from the volume to multiple points (as a Px3 array-like).

Distances are reported to the boundary of the volume. By default, if the point is inside the volume, the distance will be reported as negative. signed=False is faster but cannot distinguish between internal and external points.

Parameters:

  • coords –

  • signed – bool, default True. Whether distances to points inside the volume should be reported as negative.

  • threads – None, Whether to parallelise the queries. If None (default), refer to the instance’s threads attribute.

Returns:

np.ndarray of float, the distance from the volume to each given point

dtype: dtype = dtype('float64')

Float data type used internally

property extents: ndarray[Any, dtype[float64]]

Axis-aligned bounding box of the volume.

Returns:

2x3 numpy array of floats, where the first row is mins and the second row is maxes.

property faces: ndarray[Any, dtype[uint32]]

Mx3 array of uint32 describing indexes into points array making up triangles

classmethod from_meshio(mesh: meshio.Mesh, validate=False, threads=None, n_rays=3, ray_seed=1991) → Volume[source]

Convenience function for instantiating a Volume from a meshio Mesh.

Parameters:

  • mesh – meshio Mesh whose only cells are triangles.

  • validate – as passed to __init__, defaults to False

  • threads – as passed to __init__, defaults to None

  • n_rays – as passed to __init__, defaults to 3

  • ray_seed – as passed to __init__, defaults to None (random)

Raises:

ValueError – if Mesh does not have triangle cells

Returns:

Volume instance

intersections(src_points: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], tgt_points: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], threads: bool | None = None) → Tuple[ndarray[Any, dtype[uint64]], ndarray[Any, dtype[float64]], ndarray[Any, dtype[bool_]]][source]

Get intersections between line segments and volume.

Line segments are defined by their start (source) and end (target) points. Only the first intersection for a given line segment is reported.

Even if there is only one line segment to check, the argument arrays must have 2 dimensions, e.g. [[0, 0, 0]], [[1, 1, 1]].

The output arrays are:

  • Which line segment the intersection refers to, as an index into the argument arrays

  • The point of intersection

  • Whether the intersection is with the inside face of the mesh

N.B. the inside face check will report True for cases where a line touches (“skims”) an external edge; see https://github.com/dimforge/ncollide/issues/335 .

N.B. threads=True here uses a slightly different implementation, so you may not see the performance increase as with other methods.

Parameters:

  • src_points – Nx3 array-like

  • tgt_points – Nx3 array-like

  • threads – None, Whether to parallelise the queries. If None (default), refer to the instance’s threads attribute.

Raises:

ValueError – Inputs have different shapes or are not Nx3

Returns:

tuple of uint array of indices (N), float array of locations (Nx3), bool array of is_backface (N)

property points: ndarray[Any, dtype[float64]]

Nx3 array of float describing vertices

property rays: ndarray[Any, dtype[float64]]

Rays used to detect containment as an ndarray of shape (n_rays, 3).

These rays are in random directions (set with the ray seed on construction), and are the length of the diameter of the volume’s bounding sphere.

threads: bool = True

Whether to use threading