fsleyes.editor
¶
The editor
package contains functionality for editing Image
overlays.

The editor
package provides the following two classes:
The |
|
The |
Making an edit to an Image
requires two stages:
Select some voxels in the
Image
.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)[source]¶ 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)[source]¶ Bases:
fsleyes.actions.ActionProvider
The
Editor
class provides functionality to edit the data of anImage
overlay. AnEditor
instance is associated with a specificImage
overlay, passed to__init__()
.An
Editor
instance uses aselection.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:Create a selection
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 thegetSelection()
method. ThefillSelection()
method can be used to perform the second step.Some convenience methods are also provided for working with selections:
Returns the
selection.Selection
instance currently in use.Fills the current selection with the specified value or values.
Copies the
Image
data in the current selection.Pastes the data in the given
clipboard
into theImage
that is managed by thisEditor
.Change tracking
An
Editor
instance keeps track of all changes made to theImage
data and to theSelection
Every selection/data change made is recorded usingSelectionChange
andValueChange
instances, which are stored in a list. These changes can be undone (and redone), through theundo()
andredo()
“action” methods (see theactions
module). Changes to theSelection
object are, by default, only recorded when the selection is cleared. However, you can track all selection changes by initialising anEditor
instance withrecordSelection=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 theendChangeGroup()
to stop group changes. When undoing/redoing changes, all of the changes in a change group will be undone/redone together.-
__init__
(image, overlayList, displayCtx, recordSelection=False)[source]¶ Create an
Editor
.- Parameters
image – The
Image
instance being edited.overlayList – The
OverlayList
instance.displayCtx – The
DisplayContext
instance.recordSelection – Defaults to
False
. IfTrue
, changes to theselection.Selection
are recorded in the change history.
-
destroy
()[source]¶ Removes some property listeners, and clears references to objects to prevent memory leaks.
-
getSelection
()[source]¶ Returns the
selection.Selection
instance currently in use.
-
clearSelection
()[source]¶ Clears the
selection.Selection
(seeselection.Selection.clearSelection()
). If thisEditor
is not recording all selection changes (recordSelection=False
in__init__()
), the selection state before being cleared is saved in the change history.
-
fillSelection
(newVals)[source]¶ 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.
-
startChangeGroup
()[source]¶ Starts a change group. All subsequent changes will be grouped together, for
undo()
/redo()
purposes, until a call toendChangeGroup()
.
-
endChangeGroup
()[source]¶ Ends a change group previously started by a call to
startChangeGroup()
.
-
recordChanges
(record=True)[source]¶ 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.
-
ignoreChanges
()[source]¶ Cause this
Editor
to ignore any changes that are made to the selection or the image data until further notice. Call therecordChanges()
method to resume recording changes.
-
undo
()[source]¶ Un-does the most recent change. Returns a list containing all change objects that were undone - either
ValueChange
orSelectionChange
objects.
-
redo
()[source]¶ Re-does the most recent undone change. Returns a list containing all change objects that were undone - either
ValueChange
orSelectionChange
objects.
-
copySelection
()[source]¶ Copies the
Image
data in the current selection. Returns the data in a format that can be passed directly to thepasteSelection()
method of this, or another,Editor
instance.Note
The format of the returned data might change, so I haven’t specified it.
-
pasteSelection
(clipboard)[source]¶ Pastes the data in the given
clipboard
into theImage
that is managed by thisEditor
.The
clipboard
is assumed to have been created by thecopySelection()
method of anotherEditor
instance which is managing anImage
that has the same resolution and dimensions as theImage
managed by this instance.
-
__selectionChanged
(*a)¶ Called when the current
Selection.selection
changes.Saves a record of the change with a
SelectionChange
object.
-
__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.
-
__applyChange
(change)¶ Called by the
fillSelection()
andredo()
methods.Applies the given
change
(either aValueChange
or aSelectionChange
).
-
__revertChange
(change)¶ Called by the
undo()
method. Reverses the change made by the givenchange
object, (either aValueChange
or aSelectionChange
)
-
__makeSlice
(offset, shape, volume=None)¶ Generate a tuple of
slice
objects and/or integers, suitable for indexing a region of an image at the givenoffset
, with the givenshape
. If the image has more than three dimensions, the generated slice will index the specifiedvolume
(assumed to be a sequence of indices).
-
__module__
= 'fsleyes.editor.editor'¶
-
class
fsleyes.editor.
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
.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()
).
-
replaceSelection
(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.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)[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
.
-
__module__
= 'fsleyes.editor.selection'¶
-
-
class
fsleyes.editor.
ValueChange
(overlay, volume, offset, oldVals, newVals)[source]¶ 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.-
__init__
(overlay, volume, offset, oldVals, newVals)[source]¶ 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.
-
__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__': {}})¶
-
__module__
= 'fsleyes.editor.editor'¶
-
__weakref__
¶ list of weak references to the object (if defined)
-
-
class
fsleyes.editor.
SelectionChange
(overlay, offset, oldSelection, newSelection)[source]¶ Bases:
object
Represents a change which has been made to a
selection.Selection
instance. Stores the location, the old selection, and the new selection.-
__init__
(overlay, offset, oldSelection, newSelection)[source]¶ 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.
-
__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__': {}})¶
-
__module__
= 'fsleyes.editor.editor'¶
-
__weakref__
¶ list of weak references to the object (if defined)
-