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)

Bases: __main__.MockClass

The Selection class represents a selection of voxels in a 3D Image. The selection is stored as a numpy 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:

selectBlock	Selects the block (sets all voxels to 1) specified by the given voxel and block size.
deselectBlock	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:

setSelection	Copies the given block into the selection, starting at offset.
replaceSelection	Copies the given block into the selection, starting at offset.
addToSelection	Adds the selection (via a boolean OR operation) in the given block to the current selection, starting at offset.
removeFromSelection	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 the getLastChange() method. The Selection class inherits from the Notifier 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:

getSelection	Returns the selection array.
getSelectionSize	Returns the number of voxels that are currently selected.
clearSelection	Clears (sets to 0) the entire selection, or the selection specified by the restrict parameter, if it is given.
getBoundedSelection	Extracts the smallest region from the selection which contains all selected voxels.
getIndices	Returns a \(N \times 3\) array which contains the coordinates of all voxels that are currently selected.

__init__(image, display, selection=None)

Create a Selection instance.

Parameters

• image – The Image instance associated with this Selection.

• display – The Display instance for the image.

• selection – Selection array. If not provided, one is created. Must be a numpy.uint8 array with the same shape as image. This array is not copied.

__del__()

Prints a log message.

property shape

Returns the selection shape.

getSelection()

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, the getLastChange() method, and selection notification, will break.

selectBlock(voxel, boxSize, axes=(0, 1, 2), bias=None, combine=False)

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)

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)

Copies the given block into the selection, starting at offset.

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()).

replaceSelection(block, offset, combine=False)

Copies the given block into the selection, starting at offset.

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)

Adds the selection (via a boolean OR operation) in the given block to the current selection, starting at offset.

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)

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()).

getSelectionSize()

Returns the number of voxels that are currently selected.

getBoundedSelection()

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 full selection array.

Warning

This method is slow, and in many cases it may be faster simply to access the full selection array.

clearSelection(restrict=None, combine=False)

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()

Returns the most recent change made to this Selection.

A tuple is returned, containing the following:

• A numpy.uint8 array containing the old block value

• A numpy.uint8 array containing the new block value

• Voxel 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 in clearSelection()).

setChange(block, offset, oldBlock=None)

Sets/overwrites the most recently saved change made to this Selection.

getIndices(restrict=None)

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)

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)

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)

Selects a line from from_ to to.

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)

Deselects a line from from_ to to.

Parameters

combine – Combine with the previous stored change (see __storeChange()).

See the selectLine() function for details on the other arguments.

transferSelection(destImg, destDisplay)

Re-samples the current selection into the destination image space.

Each Selection instance is in terms of a specific Image instance, which has a specific dimensionality. In order to apply a Selection which is in terms of one Image, 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 with destImg.

Returns

a new numpy.uint8 array, suitable for creating a new Selection object for use with the given destImg.

_Selection__getSelectionBlock(size, offset)

Extracts a block from the selection image starting from the specified offset, and of the specified size.

_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 array

• combine – If False (the default), the previously stored change will be replaced by the current change. Otherwise the previous and current changes will be combined.

_Selection__updateSelectionBlock(block, offset, combine=False)

Replaces the current selection at the specified offset with the given block.

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()).

__module__ = 'fsleyes.editor.selection'

fsleyes.editor.selection.fixSlices(slices)

A convenience function used by selectByValue(), clearSelection() and getIndices(), to sanitise their restrict parameter.

fsleyes.editor.selection.selectByValue(data, seedLoc, precision=None, searchRadius=None, local=False, restrict=None)

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)

Selects a continuous “line” in an array of the given shape, between the points from_ and to.

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