fsleyes.editor.selection
This module provides the Selection
class, which represents a
selection of voxels in a 3D Image
.
- class fsleyes.editor.selection.Selection(image, display, selection=None)[source]
Bases:
__main__.docbuilder.run.<locals>.MockClass
The
Selection
class represents a selection of voxels in a 3DImage
. The selection is stored as anumpy
mask array, the same shape as the image. Methods are available to query and update the selection.Changes to a
Selection
can be made through blocks, which are 3D cuboid regions. The following methods allow a block to be selected/deselected, where the block is specified by a voxel coordinate, and a block size:Selects the block (sets all voxels to 1) specified by the given voxel and block size.
De-selects the block (sets all voxels to 0) specified by the given voxel and box size.
The following methods offer more fine grained control over selection blocks - with these methods, you pass in a block that you have created yourself, and an offset into the selection, specifying its location:
Copies the given
block
into the selection, starting atoffset
.Adds the selection (via a boolean OR operation) in the given
block
to the current selection, starting atoffset
.Clears all voxels in the selection where the values in
block
are non-zero.A third approach to making a selection is provided by the
selectByValue()
method, which allows a selection to be made in a manner similar to a bucket fill technique found in any image editor.The related
invertRegion()
method, given a seed location, will invert the selected state of all voxels adjacent to that location. This approach allows a fill holes type approach, where a region outline is delineated, and then the interior inverted to select it.A
Selection
object keeps track of the most recent change made through any of the above methods. The most recent change can be retrieved through thegetLastChange()
method. TheSelection
class inherits from theNotifier
class - you can be notified whenever the selection changes by registering as a listener.Finally, the
Selection
class offers a few other methods for convenience:Returns the selection array.
Returns the number of voxels that are currently selected.
Clears (sets to 0) the entire selection, or the selection specified by the
restrict
parameter, if it is given.Extracts the smallest region from the
selection
which contains all selected voxels.Returns a \(N \times 3\) array which contains the coordinates of all voxels that are currently selected.
- __init__(image, display, selection=None)[source]
Create a
Selection
instance.- Parameters
image – The
Image
instance associated with thisSelection
.display – The
Display
instance for theimage
.selection – Selection array. If not provided, one is created. Must be a
numpy.uint8
array with the same shape asimage
. This array is not copied.
- property shape
Returns the selection shape.
- getSelection()[source]
Returns the selection array.
Warning
Do not modify the selection array directly - use the
Selection
instance methods (e.g.setSelection()
) instead. If you modify the selection directly through this attribute, thegetLastChange()
method, and selection notification, will break.
- selectBlock(voxel, boxSize, axes=(0, 1, 2), bias=None, combine=False)[source]
Selects the block (sets all voxels to 1) specified by the given voxel and block size. See the
routines.voxelBlock()
function for details on the arguments.- Parameters
combine – Combine this change with the previous stored change (see
__storeChange()
).
- deselectBlock(voxel, boxSize, axes=(0, 1, 2), bias=None, combine=False)[source]
De-selects the block (sets all voxels to 0) specified by the given voxel and box size. See the
routines.voxelBlock()
function for details on the arguments.- Parameters
combine – Combine this change with the previous stored change (see
__storeChange()
).
- setSelection(block, offset, combine=False)[source]
Copies the given
block
into the selection, starting atoffset
.- Parameters
block – A
numpy.uint8
array containing a selection.offset – Voxel coordinates specifying the block location.
combine – Combine this change with the previous stored change (see
__storeChange()
).
- addToSelection(block, offset, combine=False)[source]
Adds the selection (via a boolean OR operation) in the given
block
to the current selection, starting atoffset
.- Parameters
block – A
numpy.uint8
array containing a selection.offset – Voxel coordinates specifying the block location.
combine – Combine this change with the previous stored change (see
__storeChange()
).
- removeFromSelection(block, offset, combine=False)[source]
Clears all voxels in the selection where the values in
block
are non-zero.- Parameters
block – A
numpy.uint8
array containing a selection.offset – Voxel coordinates specifying the block location.
combine – Combine this change with the previous stored change (see
__storeChange()
).
- getBoundedSelection()[source]
Extracts the smallest region from the
selection
which contains all selected voxels.Returns a tuple containing the region, as a
numpy.uint8
array, and the coordinates specifying its location in the fullselection
array.
- clearSelection(restrict=None, combine=False)[source]
Clears (sets to 0) the entire selection, or the selection specified by the
restrict
parameter, if it is given.Note
Calling this method when the selection is already empty will clear the most recently stored change - see
getLastChange()
.- Parameters
restrict – An optional sequence of three
slice
objects, specifying the portion of the selection to clear.combine – Combine this change with the previous stored change (see
__storeChange()
).
- getLastChange()[source]
Returns the most recent change made to this
Selection
.A tuple is returned, containing the following:
A
numpy.uint8
array containing the old block valueA
numpy.uint8
array containing the new block valueVoxel coordinates denoting the block location in the full
selection
array.
If there is no stored change this method will return
(None, None, None)
(see also the note inclearSelection()
).
- setChange(block, offset, oldBlock=None)[source]
Sets/overwrites the most recently saved change made to this
Selection
.
- __storeChange(old, new, offset, combine=False)
Stores the given selection change.
- Parameters
old – A copy of the portion of the
selection
that has changed,new – The new selection values.
offset – Offset into the full
selection
arraycombine – If
False
(the default), the previously stored change will be replaced by the current change. Otherwise the previous and current changes will be combined.
- getIndices(restrict=None)[source]
Returns a \(N \times 3\) array which contains the coordinates of all voxels that are currently selected.
If the
restrict
argument is not provided, the entire selection image is searched.- Parameters
restrict – A
slice
object specifying a sub-set of the full selection to consider.
- selectByValue(seedLoc, precision=None, searchRadius=None, local=False, restrict=None, combine=False)[source]
A bucket fill style selection routine.
- Parameters
combine – Combine with the previous stored change (see
__storeChange()
).
See the
selectByValue()
function for details on the other arguments.- Returns
The generated selection array (a
numpy
boolean array), and offset of this array into the full selection image.
- invertRegion(seedLoc, restrict=None)[source]
Inverts the selected state of the region adjacent to
seedLoc
.See the
selectByValue()
function for details on the other arguments.
- selectLine(from_, to, boxSize, axes=(0, 1, 2), bias=None, combine=False)[source]
Selects a line from
from_
toto
.- Parameters
combine – Combine with the previous stored change (see
__storeChange()
).
See the
selectLine()
function for details on the other arguments.
- deselectLine(from_, to, boxSize, axes=(0, 1, 2), bias=None, combine=False)[source]
Deselects a line from
from_
toto
.- Parameters
combine – Combine with the previous stored change (see
__storeChange()
).
See the
selectLine()
function for details on the other arguments.
- transferSelection(destImg, destDisplay)[source]
Re-samples the current selection into the destination image space.
Each
Selection
instance is in terms of a specificImage
instance, which has a specific dimensionality. In order to apply aSelection
which is in terms of oneImage
, the selection array needs to be re-sampled.- Parameters
destImg – The
Image
that the selection is to be transferred to.destDisplay – The
Display
instance associated withdestImg
.
- Returns
a new
numpy.uint8
array, suitable for creating a newSelection
object for use with the givendestImg
.
- __updateSelectionBlock(block, offset, combine=False)
Replaces the current selection at the specified
offset
with the givenblock
.The old values for the block are stored, and can be retrieved via the
getLastChange()
method.- Parameters
block – A
numpy.uint8
array containing the new selection values.offset – Voxel coordinates specifying the location of
block
.combine – Combine with the previous stored change (see
__storeChange()
).
- __getSelectionBlock(size, offset)
Extracts a block from the selection image starting from the specified
offset
, and of the specifiedsize
.
- __annotations__ = {}
- __module__ = 'fsleyes.editor.selection'
- fsleyes.editor.selection.fixSlices(slices)[source]
A convenience function used by
selectByValue()
,clearSelection()
andgetIndices()
, to sanitise theirrestrict
parameter.
- fsleyes.editor.selection.selectByValue(data, seedLoc, precision=None, searchRadius=None, local=False, restrict=None)[source]
A bucket fill style selection routine. Given a seed location, finds all voxels which have a value similar to that of that location. The current selection is replaced with all voxels that were found.
- Parameters
seedLoc – Voxel coordinates specifying the seed location
precision – Voxels which have a value that is less than
precision
from the seed location value will be selected.searchRadius – May be either a single value, or a sequence of three values - one for each axis. If provided, the search is limited to a sphere (in the voxel coordinate system), centred on the seed location, with the specified
searchRadius
(in voxels). If not provided, the search will cover the entire image space.local – If
True
, a voxel will only be selected if it is adjacent to an already selected voxel (using 8-neighbour connectivity).restrict – An optional sequence of three
slice
object, specifying a sub-set of the image to search.
- Returns
The generated selection array (a
numpy
boolean array), and offset of this array into the data.
- fsleyes.editor.selection.selectLine(shape, dims, from_, to, boxSize, axes=(0, 1, 2), bias=None)[source]
Selects a continuous “line” in an array of the given
shape
, between the pointsfrom_
andto
.- Parameters
shape – Shape of the image in which the selection is taking place.
dims – Size of one voxel along each axis (the pixdims).
from – Start point of the line
to – End point of the line
See the
routines.voxelBlock()
function for details on the other arguments.- Returns
A tuple containing:
A 3D boolean
numpy
array containing the selected line.An offset of this array according to the
shape
of the full image. If the