fsleyes.profiles.orthoeditprofile

This module provides the OrthoEditProfile class, an interaction Profile for OrthoPanel views.

class fsleyes.profiles.orthoeditprofile.OrthoEditProfile(viewPanel, overlayList, displayCtx)

Bases: fsleyes.profiles.orthoviewprofile.OrthoViewProfile

The OrthoEditProfile class is an interaction profile for use with the OrthoPanel class. It gives the user the ability to make changes to Image overlays, by using the functionality of the editor package.

Modes

The OrthoEditProfile has the following modes, in addition to those already defined by the OrthoViewProfile:

sel	Select mode. The user is able to manually add voxels to the selection using a cursor. The cursor size can be changed with the selectionSize property, and the cursor can be toggled between a 2D square and a 3D cube via the selectionIs3D property. If the drawMode property is True, selected voxels are immediately filled with the fillValue when the mouse is released.
desel	Deselect mode. Identical to sel mode, except that the cursor is used to remove voxels from the selection. If the drawMode property is True, selected voxels are immediately set to 0 when the mouse is released.
chsize	Change-size mode. The use can change the selectionSize attribute via the mouse wheel.
selint	Select by intensity mode. The user can select a voxel, and grow the selected region based on its intensity.
fill	Fill mode. The user can click on a voxel and set its selected state, and the state of adjacent voxels. Restricted to 2D (see selectionIs3D).
chthres	Change-threshold mode. The user can change the intensityThres via the mouse wheel.
chrad	Change-radius mode. The user can change the searchRadius via the mouse wheel.

Actions

The OrthoEditProfile defines the following actions, on top of those already defined by the OrthoViewProfile:

undo	Un-does the most recent change to the selection or to the Image data.
redo	Re-does the most recent undone change to the selection or to the Image data.
clearSelection	Clears the current selection.
fillSelection	Fills the current selection with the fillValue.
invertSelection	Inverts the current selection.
eraseSelection	Fills the current selection with zero.
copySelection	Copies the data within the selection from the currently selected overlay, and stores it in an internal “clipboard”.
pasteSelection	Pastes the data currently stored in the clipboard into the currently selected image, if possible.

Annotations

The OrthoEditProfile class uses annotations on the SliceCanvas panels, displayed in the OrthoPanel, to display information to the user. Two annotations are used:

• The cursor annotation. This is a Rect annotation representing a cursor at the voxel, or voxels, underneath the current mouse location.

• The selection annotation. This is a VoxelSelection annotation which displays the Selection.

The display space

The OrthoEditProfile class has been written in a way which requires the Image instance that is being edited to be displayed in scaled voxel (a.k.a. pixdim) space. The OrthoEditToolBar uses a DisplaySpaceWarning widget to warn the user if the DisplayContext.displaySpace is not set appropriately.

selectionCursorColour = <MagicMock name='mock.Colour()' id='281473498033216'>

Colour used for the cursor annotation.

selectionOverlayColour = <MagicMock name='mock.Colour()' id='281473498033216'>

Colour used for the selection annotation, which displays the voxels that are currently selected.

showSelection = <MagicMock name='mock.Boolean()' id='281473497326640'>

When drawMode is False,` the selection overlay can be hidden by setting this to ``False.

selectionSize = <MagicMock name='mock.Int()' id='281473494293760'>

In sel and desel modes, defines the size of the selection cursor.

selectionIs3D = <MagicMock name='mock.Boolean()' id='281473497326640'>

In sel and desel mode, toggles the cursor between a 2D square and a 3D cube. In selint mode, toggles the selection space between the current slice, and the full 3D volume.

fillValue = <MagicMock name='mock.Real()' id='281473497926576'>

The value used when drawing/filling voxel values - all voxels in the selection will be filled with this value.

eraseValue = <MagicMock name='mock.Real()' id='281473497926576'>

The value used when erasing voxel values - all voxels in the selection will be filled with this value.

drawMode = <MagicMock name='mock.Boolean()' id='281473497326640'>

If True, when in sel or desel mode, clicks and click+ drags cause the image to be immediately modified. Otherwise, editing is a two stage process (as described in the Editor class documentation).

This setting is enabled by default, because it causes FSLeyes to behave like FSLView. However, all advanced editing/selection capabilities are disabled when drawMode is True.

intensityThres = <MagicMock name='mock.Real()' id='281473497926576'>

In selint mode, the maximum distance, in intensity, that a voxel can be from the seed location, in order for it to be selected. Passed as the precision argument to the Selection.selectByValue() method.

intensityThresLimit = <MagicMock name='mock.Real()' id='281473497926576'>

This setting controls the maximum value for the itensityThres property. It is set automatically from the data when an Image is first selected, but can also be manually controlled via this property.

localFill = <MagicMock name='mock.Boolean()' id='281473497326640'>

In selint mode, if this property is True, voxels can only be selected if they are adjacent to an already selected voxel. Passed as the local argument to the Selection.selectByValue() method.

limitToRadius = <MagicMock name='mock.Boolean()' id='281473497326640'>

In selint mode, if this property is True, the search region will be limited to a sphere (in the voxel coordinate system) with its radius specified by the searchRadius property.

searchRadius = <MagicMock name='mock.Real()' id='281473497926576'>

In selint mode, if limitToRadius is true, this property specifies the search sphere radius. Passed as the searchRadius argument to the Selection.selectByValue() method.

targetImage = <MagicMock name='mock.Choice()' id='281473498355456'>

By default, all modifications that the user makes will be made on the currently selected overlay (the DisplayContext.selectedOverlay). However, this property can be used to select a different image as the target for modifications.

This proprty is mostly useful when in selint mode - the selection can be made based on the voxel intensities in the currently selected image, but the selection can be filled in another iamge (e.g. a mask/label image).

This property is updated whenever the OverlayList or the currently selected overlay changes, so that it contains all other overlays which have the same dimensions as the selected overlay.

__init__(viewPanel, overlayList, displayCtx)

Create an OrthoEditProfile.

Parameters

• viewPanel – The OrthoPanel instance.

• overlayList – The OverlayList instance.

• displayCtx – The DisplayContext instance.

locationFollowsMouse = <MagicMock name='mock.Boolean()' id='281473497326640'>

If True, when the user is drawing/erasing/selectiong by clicking and dragging with the mouse, the DisplayContext.location is updated to track the mouse.

Users running on a slower machine may wish to disable this option.

destroy()

Removes some property listeners, destroys the Editor instances, and calls OrthoViewProfile.destroy().

deregister()

Destroys all annotations, and calls OrthoViewProfile.deregister().

currentOverlay()

Returns the overlay that is currently registered with this OrthoEditProfile.

editor(overlay)

Return the Editor associated with the given overlay. Raises a KeyError if there is no editor fo the overlay.

createMask()

Create a 3D mask which has the same size as the currently selected overlay, and insert it into the overlay list.

clearSelection()

Clears the current selection. See Editor.clearSelection().

fillSelection()

Fills the current selection with the fillValue. See Editor.fillSelection().

invertSelection()

Inverts the current selection. See Editor.invertSelection().

eraseSelection()

Fills the current selection with zero. See Editor.fillSelection().

copySelection()

Copies the data within the selection from the currently selected overlay, and stores it in an internal “clipboard”.

pasteSelection()

Pastes the data currently stored in the clipboard into the currently selected image, if possible.

undo()

Un-does the most recent change to the selection or to the Image data. See Editor.undo().

redo()

Re-does the most recent undone change to the selection or to the Image data. See Editor.redo().

isEditable = <MagicMock name='mock.utils.deprecated.deprecated()()' id='281473495817568'>

_selModeMouseMove(ev, canvas, mousePos, canvasPos)

Handles mouse motion events in sel mode.

Draws a cursor annotation at the current mouse location (see __draweCursorAnnotation()).

_selModeLeftMouseDown(ev, canvas, mousePos, canvasPos, add=True, mode='sel')

Handles mouse down events in sel mode.

Starts an Editor change group, and adds to the current Selection.

This method is also used by _deselModeLeftMouseDown(), which may set the add parameter to False.

Parameters

• add – If True (default) a block at the cursor is added to the selection. Otherwise it is removed.

• mode – The current profile mode (defaults to 'sel').

_selModeLeftMouseDrag(ev, canvas, mousePos, canvasPos, add=True, mode='sel')

Handles mouse drag events in sel mode.

Adds to the current Selection.

This method is also used by _deselModeLeftMouseDown(), which may set the add parameter to False.

Parameters

• add – If True (default) a block at the cursor is added to the selection. Otherwise it is removed.

• mode – The current profile mode (defaults to 'sel').

_selModeLeftMouseUp(ev, canvas, mousePos, canvasPos, fillValue=None)

Handles mouse up events in sel mode.

Ends the Editor change group that was started in the _selModeLeftMouseDown() method.

This method is also used by _deselModeLeftMouseUp(), which sets fillValue to eraseValue.

Parameters

fillValue – If drawMode is True, the value to fill the selection with. If not provided, defaults to fillValue.

_selModeMouseLeave(ev, canvas, mousePos, canvasPos)

Handles mouse leave events in sel mode. Makes sure that the selection cursor annotation is not shown on any canvas.

_OrthoEditProfile__applySelection(canvas, voxel, add=True, combine=False, from_=None)

Called by sel mode mouse handlers. Adds/removes a block of voxels, centred at the specified voxel, to/from the current Selection.

Parameters

• canvas – The source SliceCanvas.

• voxel – Coordinates of centre voxel.

• add – If True a block is added to the selection, otherwise it is removed.

• combine – Tell the Selection object to combine this change with the most recent one.

• from – If provided, use the Selection.selectLine() or Selection.deselectLine() methods - should be another voxel coordinate.

_OrthoEditProfile__destroyAnnotations()

Called by other methods. Destroys the SelectionAnnotation and Rect cursor annotation objects, if they exist.

_OrthoEditProfile__drawCursorAnnotation(canvas, voxel, blockSize=None)

Draws the cursor annotation. Highlights the specified voxel with a Rect annotation.

This is used by mouse motion event handlers, so the user can see the possible selection, and thus what would happen if they were to click.

Parameters

• canvas – The SliceCanvas on which to make the annotation.

• voxel – Voxel which is at the centre of the cursor.

• blockSize – Size of the cursor square/cube.

_OrthoEditProfile__drawModeChanged(*a)

Called when the drawMode changes. Updates the enabled state of various actions that are irrelevant when in draw mode.

_OrthoEditProfile__dynamicRefreshCanvases(ev, canvas, mousePos=None, canvasPos=None)

Called by mouse event handlers when the user is interacting with a canvas.

If locationFollowsMouse is True, the DisplayContext.location is set to the current mouse location.

_OrthoEditProfile__getSelectionMerger()

This method is called just before a select-by-intensity selection is about to happen. It rteturns one of three values:

• The string 'clear', indicating that the whole selection (or the whole slice, if selectionIs3D is False) needs to be cleared.

• The value None indicating that the selection does not need to be cleared, and a merge does not need to be made.

• A tuple containing the (offset, size) of a previous change to the selection, specifying the portion of the selection which needs to be cleared, and which can be subsequently merged with a new selection.

_OrthoEditProfile__getTargetImageEditor(srcEditor)

If the targetImage is set to an image other than the currently selected one, this method returns an Editor for the target image.

_OrthoEditProfile__getVoxelLocation(canvasPos)

Returns the voxel location, for the currently selected overlay, which corresponds to the specified canvas position. Returns None if the current canvas position is out of bounds for the current overlay.

_OrthoEditProfile__hideCursorAnnotation()

Configures all of the Rect cursor annotations so that they will not be shown on the next canvas refresh.

_OrthoEditProfile__modeChanged(*a)

Called when the Profile.mode changes. If the mode is changed to 'fill', the selectionIs3D option is set to False.

_OrthoEditProfile__recordSelectionMerger(mode, offset, size)

This method is called whenever a change is made to the Selection object. It stores some information which is used to improve subsequent selection performance when in selint mode, and when limitToRadius is True.

Basically, if the current selection is limited by radius, and a new, similarly limited selection is made, we do not need to clear the entire selection before making the new selection - we just need to clear the cuboid region in which the previous selection was located.

This behaviour is referred to as a ‘merge’ because, ultimately, the region of the first selection is merged with the region of the second selection, and only this part of the Selection image is refreshed.

This method (and the __getSelectionMerger() method) contains some simple, but awkward, logic which figures out when a merge can happen and, conversely, when the full selection does need to be cleared.

Parameters

• offset – Offset into the selection array of the change.

• size – Shape of the change.

_OrthoEditProfile__refreshCanvases()

Short cut to refresh the canvases of the OrthoPanel.

Note

This is done instead of calling OrthoPanel.Refresh because the latter introduces flickering.

_OrthoEditProfile__selectedOverlayChanged(*a)

Called when either the OverlayList or DisplayContext.selectedOverlay change.

Destroys all old annotations. If the newly selected overlay is an Image, new annotations are created.

_OrthoEditProfile__selectionColoursChanged(*a)

Called when either of the selectionOverlayColour or selectionCursorColour properties change.

Updates the annotations colours accordingly.

_OrthoEditProfile__selintPropertyChanged(*a)

Called when the intensityThres, localFill, limitToRadius, or searchRadius properties change. Re-runs select-by-intensity (via __selintSelect()), with the new settings.

_OrthoEditProfile__selintSelect(voxel, canvas)

Selects voxels by intensity, using the specified voxel as the seed location.

Called by the _selintModeLeftMouseDown(), _selintModeLeftMouseDrag(), _selintModeLeftMouseWheel(), and __selintPropertyChanged() methods. See Selection.selectByValue().

_OrthoEditProfile__selintThresLimitChanged(*a)

Called when the intensityThresLimit changes. Updates the maximum value on the intensityThres accordingly.

_OrthoEditProfile__setCopyPasteState()

Enables/disables the copySelection()/ pasteSelection() actions as needed.

_OrthoEditProfile__setPropertyLimits()

Called by the __selectedOverlayChanged() method.

_OrthoEditProfile__showSelectionChanged(*a)

Called when the showSelection property changes. Shows/ hides the VoxelSelection annotations accordingly.

_OrthoEditProfile__targetImageChanged(*a)

Called every time the targetImage is changed. Makes sure that an Editor instance for the selected target image exists.

_OrthoEditProfile__updateTargetImage()

Resets the value and choices on the targetImage. It is populated with all Image instances which are in the same space as the currently selected overlay.

__module__ = 'fsleyes.profiles.orthoeditprofile'

_deselModeLeftMouseDown(ev, canvas, mousePos, canvasPos)

Handles mouse down events in desel mode.

Calls _selModeLeftMouseDown().

_deselModeLeftMouseDrag(ev, canvas, mousePos, canvasPos)

Handles mouse drag events in desel mode.

Calls _selModeLeftMouseDrag().

_deselModeLeftMouseUp(ev, canvas, mousePos, canvasPos)

Handles mouse up events in desel mode.

Calls _selModeLeftMouseUp().

_chsizeModeMouseWheel(ev, canvas, wheelDir, mousePos, canvasPos)

Handles mouse wheel events in chsize mode.

Increases/decreases the current selectionSize.

_selintModeMouseMove(ev, canvas, mousePos, canvasPos)

Handles mouse motion events in selint mode. Draws a selection annotation at the current location (see __drawCursorAnnotation()).

_selintModeLeftMouseDown(ev, canvas, mousePos, canvasPos)

Handles mouse down events in selint mode.

Starts an Editor change group, then clears the current selection, and selects voxels by intensity (see __selintSelect()).

_selintModeLeftMouseDrag(ev, canvas, mousePos, canvasPos)

Handles mouse drag events in selint mode.

A select-by-intensity is re-run with the current mouse location. See the __selintSelect() method.

_selintModeLeftMouseUp(ev, canvas, mousePos, canvasPos)

Handles mouse up events in selint mode. Ends the Editor change group that was started in the _selintModeLeftMouseDown() method.

_selintModeMouseLeave(ev, canvas, mousePos, canvasPos)

Handles mouse leave events in selint mode. Makes sure that the selection cursor annotation is not shown on any canvas.

_fillModeMouseMove(ev, canvas, mousePos, canvasPos)

Handles mouse motion events in fill mode. Draws a selection annotation at the current location (see __drawCursorAnnotation()).

_fillModeLeftMouseDown(ev, canvas, mousePos, canvasPos)

Handles mouse down events in fill mode. Calls Selection.invertRegion() at the current location.

_chthresModeMouseWheel(ev, canvas, wheel, mousePos, canvasPos)

Handles mouse wheel events in chthres mode.

The intensityThres value is decreased/increased according to the mouse wheel direction. If the mouse button is down, select-by-intensity is re-run at the current mouse location.

_chradModeMouseWheel(ev, canvas, wheel, mousePos, canvasPos)

Handles mouse wheel events in chrad mode.

The searchRadius value is decreased/increased according to the mouse wheel direction. If the mouse button is down, select-by-intensity is re-run at the current mouse location.