fsleyes.editor

The editor package contains functionality for editing Image overlays.

The editor package provides the following two classes:

Selection	The Selection class represents a selection of voxels in a 3D Image.
Editor	The Editor class provides functionality to edit the data of an Image overlay.

Making an edit to an Image requires two stages:

1. Select some voxels in the Image.

2. Modify the values stored in those voxels.

The Selection class implements the functionality for the first stage, and the Editor class implements functinoality for the second. The Editor class also keeps track of changes to the current selection, and to the image data, thus allowing the user to undo/redo any changes.

fsleyes.editor.isEditable(overlay, displayCtx)

Returns True if the given overlay is editable, False otherwise.

Parameters:

• overlay – The overlay to check

• displayCtx – The relevant DisplayContext()

Returns:

True if overlay``is editable, ``False otherwise

class fsleyes.editor.Editor(image, overlayList, displayCtx, recordSelection=False)

Bases: ActionProvider

The Editor class provides functionality to edit the data of an Image overlay. An Editor instance is associated with a specific Image overlay, passed to __init__().

An Editor instance uses a selection.Selection object which allows voxel selections to be made, and keeps track of all changes to both the selection and image data.

The editing process

Making changes to the data in an Image involves two steps:

1. Create a selection

2. Change the value of voxels in that selection

The first step can be peformed by working directly with the Selection object - this is accessible via the getSelection() method. The fillSelection() method can be used to perform the second step.

Some convenience methods are also provided for working with selections:

getSelection	Returns the selection.Selection instance currently in use.
fillSelection	Fills the current selection with the specified value or values.
copySelection	Copies the Image data in the current selection.
pasteSelection	Pastes the data in the given clipboard into the Image that is managed by this Editor.

Change tracking

An Editor instance keeps track of all changes made to the Image data and to the Selection Every selection/data change made is recorded using SelectionChange and ValueChange instances, which are stored in a list. These changes can be undone (and redone), through the undo() and redo() “action” methods (see the actions module). Changes to the Selection object are, by default, only recorded when the selection is cleared. However, you can track all selection changes by initialising an Editor instance with recordSelection=True.

Sometimes it is useful to treat many small changes as a single large change. For example, if a selection is being updated by dragging the mouse across a canvas, storing a separate change for every change in mouse position would result in many small changes which, if the user then wishes to undo, would have to be undone one by one. This problem can be overcome by the use of change groups. Whenever an operation similar to the above begins, you can call the startChangeGroup() method - from now on, all changes will be aggregated into one group. When the operation completes, call the endChangeGroup() to stop group changes. When undoing/redoing changes, all of the changes in a change group will be undone/redone together.

__applyChange(change)

Called by the fillSelection() and redo() methods.

Applies the given change (either a ValueChange or a SelectionChange).

__changeMade(change)

Called by the fillSelection() and __selectionChanged() methods, whenever a data/selection change is made.

Saves the change, and updates the state of the undo()/ redo() methods.

__makeSlice(offset, shape, volume=None)

Generate a tuple of slice objects and/or integers, suitable for indexing a region of an image at the given offset, with the given shape. If the image has more than three dimensions, the generated slice will index the specified volume (assumed to be a sequence of indices).

__revertChange(change)

Called by the undo() method. Reverses the change made by the given change object, (either a ValueChange or a SelectionChange)

__selectionChanged(*a)

Called when the current Selection.selection changes.

Saves a record of the change with a SelectionChange object.

__annotations__ = {}

__del__()

Prints a log message.

__init__(image, overlayList, displayCtx, recordSelection=False)

Create an Editor.

Parameters:

• image – The Image instance being edited.

• overlayList – The OverlayList instance.

• displayCtx – The DisplayContext instance.

• recordSelection – Defaults to False. If True, changes to the selection.Selection are recorded in the change history.

__module__ = 'fsleyes.editor.editor'

clearSelection(*args, **kwargs)

Clears the selection.Selection (see selection.Selection.clearSelection()). If this Editor is not recording all selection changes (recordSelection=False in __init__()), the selection state before being cleared is saved in the change history.

All arguments are passed through to selection.Selection.clearSelection().

copySelection()

Copies the Image data in the current selection. Returns the data in a format that can be passed directly to the pasteSelection() method of this, or another, Editor instance.

Note

The format of the returned data might change, so I haven’t specified it.

destroy()

Removes some property listeners, and clears references to objects to prevent memory leaks.

endChangeGroup()

Ends a change group previously started by a call to startChangeGroup().

fillSelection(newVals)

Fills the current selection with the specified value or values.

Parameters:

newVals – A scalar value, or a sequence containing the same number of values as the current selection size.

getImage()

Returns the Image associated with this Editor.

getSelection()

Returns the selection.Selection instance currently in use.

ignoreChanges()

Cause this Editor to ignore any changes that are made to the selection or the image data until further notice. Call the recordChanges() method to resume recording changes.

invertSelection()

Inverts the current selection.

pasteSelection(clipboard)

Pastes the data in the given clipboard into the Image that is managed by this Editor.

The clipboard is assumed to have been created by the copySelection() method of another Editor instance which is managing an Image that has the same resolution and dimensions as the Image managed by this instance.

recordChanges(record=True)

Cause this Editor to either record or ignore any changes that are made to the selection or the image data until further notice.

Parameters:

record – If True, changes are recorded. Otherwise they are ignored.

redo()

Re-does the most recent undone change. Returns a list containing all change objects that were undone - either ValueChange or SelectionChange objects.

startChangeGroup()

Starts a change group. All subsequent changes will be grouped together, for undo()/redo() purposes, until a call to endChangeGroup().

undo()

Un-does the most recent change. Returns a list containing all change objects that were undone - either ValueChange or SelectionChange objects.

class fsleyes.editor.Selection(*args, **kwargs)

Bases: Notifier

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

__getSelectionBlock(size, offset)

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

__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.

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

__annotations__ = {}

__del__()

Prints a log message.

__getitem__(key)

Convenience wrapper around self.getSelection().__getitem__.

__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.

__module__ = 'fsleyes.editor.selection'

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

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

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

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.

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.

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.

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

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.

getSelectionSize()

Returns the number of voxels that are currently selected.

invertRegion(seedLoc, restrict=None)

Inverts the selected state of the region adjacent to seedLoc.

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

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

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

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.

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.

setChange(block, offset, oldBlock=None)

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

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

property shape

Returns the selection shape.

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.

class fsleyes.editor.ValueChange(overlay, volume, offset, oldVals, newVals)

Bases: object

Represents a change which has been made to the data for an Image instance. Stores the location, the old values, and the new values.

__dict__ = mappingproxy({'__module__': 'fsleyes.editor.editor', '__doc__': 'Represents a change which has been made to the data for an\n    :class:`.Image` instance. Stores the location, the old values,\n    and the new values.\n    ', '__init__': <function ValueChange.__init__>, '__dict__': <attribute '__dict__' of 'ValueChange' objects>, '__weakref__': <attribute '__weakref__' of 'ValueChange' objects>, '__annotations__': {}})

__init__(overlay, volume, offset, oldVals, newVals)

Create a ValueChange.

Parameters:

• overlay – The Image instance.

• volume – Sequence of volume indices, if overlay has more than 3 dimensions.

• offset – Location (voxel coordinates) of the change.

• oldVals – A numpy array containing the old image values.

• newVals – A numpy array containing the new image values.

__module__ = 'fsleyes.editor.editor'

__weakref__

list of weak references to the object

class fsleyes.editor.SelectionChange(overlay, offset, oldSelection, newSelection)

Bases: object

Represents a change which has been made to a selection.Selection instance. Stores the location, the old selection, and the new selection.

__dict__ = mappingproxy({'__module__': 'fsleyes.editor.editor', '__doc__': 'Represents a change which has been made to a\n    :class:`.selection.Selection` instance. Stores the location, the old\n    selection, and the new selection.\n    ', '__init__': <function SelectionChange.__init__>, '__dict__': <attribute '__dict__' of 'SelectionChange' objects>, '__weakref__': <attribute '__weakref__' of 'SelectionChange' objects>, '__annotations__': {}})

__init__(overlay, offset, oldSelection, newSelection)

Create a SelectionChange.

Parameters:

• overlay – The Image instance.

• offset – Location (voxel coordinates) of the change.

• oldSelection – A numpy array containing the old selection.

• newSelection – A numpy array containing the new selection.

__module__ = 'fsleyes.editor.editor'

__weakref__

list of weak references to the object