navis.in_volume¶
- navis.in_volume(x, volume, mode='IN', backend=('ncollpyde', 'pyoctree'), n_rays=None, prevent_fragments=False, validate=False, inplace=False)[source]¶
Test if points/neurons are within a given volume.
Notes
This function requires ncollpyde (recommended and installed with navis) or pyoctree as backends for raycasting. If neither is installed, we can fall back to using scipy’s ConvexHull instead. This is, however, slower and will give wrong positives for concave meshes!
- Parameters:
x ((N, 3) array-like | pandas.DataFrame | Neuron/List) –
neuron(s)
array-like is treated as list of x/y/z oordinates. Has to be of shape (N, 3), i.e.
[[x1, y1, z1], [x2, y2, z2], ..]
pandas.DataFrame
needs to havex, y, z
columns
volume (Volume | mesh-like | dict or list thereof) – Multiple volumes can be given as list (
[volume1, volume2, ...]
) or dict ({'label1': volume1, ...}
).mode ('IN' | 'OUT', optional) – If ‘IN’, parts of the neuron that are within the volume are kept.
backend ('ncollpyde' | 'pyoctree' | 'scipy' | iterable thereof) – Which backend so be used (see Notes). If multiple backends are given, will use the first backend that is available.
n_rays (int | None, optional) – Number of rays used to determine if a point is inside a volume. More rays give more reliable results but are slower (especially with pyoctree backend). If
None
will use default number of rays (3 for ncollpyde, 1 for pyoctree).prevent_fragments (bool, optional) – Only relevant if input is TreeNeuron(s). If True, will attempt to keep neuron from fragmenting.
validate (bool, optional) – If True, validate volume and try to fix issues using trimesh. Will raise ValueError if issue could not be fixed.
inplace (bool, optional) – Only relevant if input is Neuron/List. Ignored if multiple volumes are provided.
- Return type:
Union
[NeuronList
,TreeNeuron
,BaseNeuron
,MeshNeuron
,Sequence
[bool
],Dict
[str
,Union
[Sequence
[bool
],NeuronList
,TreeNeuron
,BaseNeuron
,MeshNeuron
]],None
]- Returns:
Neuron – If input is a single neuron or NeuronList, will return subset of the neuron(s) (nodes and connectors) that are within given volume.
list of bools – If input is (N, 3) array of coordinates, returns a (N, ) boolean array:
True
if in volume,False
if not in order.dict – If multiple volumes are provided, results will be returned in dictionary with volumes as keys:
{'volume1': in_volume(x, volume1), 'volume2': in_volume(x, volume2), ... }
Examples
Prune neuron to volume
>>> import navis >>> n = navis.example_neurons(1) >>> lh = navis.example_volume('LH') >>> n_lh = navis.in_volume(n, lh, inplace=False) >>> n_lh type navis.TreeNeuron name 1734350788 id 1734350788 n_nodes 344 n_connectors None n_branches 49 n_leafs 50 cable_length 32313.5 soma None units 8 nanometer dtype: object