Modes

As discussed in the Concepts section on Modes, modes are a mechanism that allow Ginga to accommodate many key and pointer bindings for a large number of possible operations. Modes are associated with the basic Ginga viewer widget and so can be used even with the widget standalone in your own programs (i.e., apart from the Reference Viewer; see Developing with Ginga for details).

Invoking Modes

Modes are used to make bindings between keyboard, mouse, trackpad and gesture events and certain operations on the viewer widget. By invoking a mode, certain keystrokes and cursor bindings are enabled for certain operations within the viewer window in which the mode was entered. Typically, pressing the space key with the widget focus in the viewer window is used to enter the special “Meta” mode, in which you can then enter any one of the registered modes by following up pressing its mode activation key.

Only one mode (or no mode) can be active at a time in a particular viewer widget. Once a mode is activated, the mode indicator should turn on in one of the corners of the viewer window to indicate which mode is active:

../_images/mode_indicator.png

To exit a mode, press the Esc (escape) key.

Note

In the Reference Viewer, you can also enter and exit certain modes using the “Toolbar” plugin (see Toolbar).

Mode Types

The mode switching system has a mode type which can be set to one of:

  • oneshot: The mode is exited by initiating and finishing a cursor drag, or when Esc is pressed (if no cursor drag is performed)

  • locked: The mode is locked until the meta mode key is pressed again (or Esc)

By default most modes are activated in “locked” type.

Note

When the lock is active, it is signified by an additional “[L]” (locked) appearing in the mode indicator; oneshot mode is indicated by “[O]”. In the figure above, you can see the mode indicator showing that the viewer is in “contrast” mode, with the mode type as “Lock”. In the Reference Viewer, the same information can be seen in the Toolbar plugin, where the lock icon shows the state of the mode type (engaged == 'Lock').

Standard Modes

These are the set of modes that come with Ginga. Those interested in writing their own custom mode should refer to Developing Modes in the developers manual.

Note

The standard modes and default bindings are summarized in the Quick Reference Quick Reference. In the reference viewer, you can pop up a help tab with the bindings for the mode if you press ‘h’ in the channel viewer while that viewer is in a mode.

CMap

CMap Mode enables bindings that can adjust the color and intensity maps of an image in a Ginga image viewer.

Enter the mode by

  • Space, then “y”

Exit the mode by

  • Esc

Default bindings in mode

  • Y : reset colormap to default (gray)

  • r : restore color map (undo any color map inversion, rotation or stretch)

  • I : invert current color map (preserving any rotation or stretch)

  • up arrow : set previous colormap in list (preserves any rotation or stretch)

  • down arrow : set next colormap in list (preserves any rotation or stretch)

  • c : overlay a visible colormap on the image

  • i : restore the default intensity map to “ramp”, the default

  • j, left arrow : set previous intensity map in list

  • k, right arrow : set next intensity map in list

  • scroll : choose color map from list

  • Ctrl + scroll : choose intensity map from list

  • pan gesture: choose color map from list (hint: use up/down arrows keys to finalize selection)

  • left drag : rotate current color map

  • right click : restore color map (same as “r”)

Contrast

Contrast Mode enables bindings that can adjust the contrast of an image in a Ginga image viewer.

Enter the mode by

  • Space, then “t”

Exit the mode by

  • Esc

Default bindings in mode

  • T : restore contrast to defaults

  • left drag : adjust contrast * Interactive shift/stretch colormap (aka contrast and bias). * Moving left/right controls shift, up/down controls stretch. * Release button when satisfied with the contrast.

  • right click : restore contrast to defaults

  • scroll wheel : change contrast (add Ctrl to change more finely)

  • Shift + scroll wheel : change brightness (add Ctrl to change more finely)

  • Ctrl + pan gesture : change contrast

  • Shift + pan gesture : change brightness

Cuts

Cuts Mode enables bindings that can adjust the low and high cut levels of an image in a Ginga image viewer.

Enter the mode by

  • Space, then “s”

Exit the mode by

  • Esc

Default bindings in mode

  • l : set low cut level to the value of the pixel under the cursor

  • k : set high cut level to the value of the pixel under the cursor

  • S : set the the low and high cut levels to the min/max values in the image

  • A : set the low and high cut levels to 0, 255; useful for standard RGB images, mostly

  • a : perform an auto cut levels using the currently selected auto cuts algorithm and parameters

  • b, up arrow : select the previous auto cuts algorithm in the list

  • n, down arrow : select the next auto cuts algorithm in the list

  • colon : toggle auto cuts for new images “on” or “off” in this viewer

  • semicolon : set auto cuts for new images to “override” in this viewer

  • scroll wheel : adjust contrast by squeezing or stretching levels; one direction squeezes, the other stretches

  • Ctrl + scroll : adjust micro contrast by squeezing or stretching levels; similar to scroll, but amount of stretch/squeeze is reduced

  • Shift + scroll : change current auto cuts algorithm

  • left drag : adjust levels by moving cursor; moving left/right adjusts high level, up/down adjusts low level

  • Shift + left drag : adjust low level by moving cursor; moving left/right adjusts low level

  • Ctrl + left drag : adjust high level by moving cursor; moving left/right adjusts high level

  • right click : perform an auto levels (same as “a”)

  • pinch gesture: widen or narrow gap between low and high cut levels (similar to scroll wheel)

  • Ctrl + pan gesture: change high cut level up or down

  • Shift + pan gesture: change low cut level up or down

Dist

Dist Mode enables bindings that can adjust the color distribution of an image in a Ginga image viewer.

These algorithms are similar to “curves” type profiles: “linear”, “log”, “power”, “sqrt”, “squared”, “asinh”, “sinh”, “histeq”

Enter the mode by

  • Space, then “d”

Exit the mode by

  • Esc

Default bindings in mode

  • D : reset the color distribution algorithm to “linear”

  • b, up arrow : select the previous distribution algorithm in the list

  • n, down arrow : select the next distribution algorithm in the list

  • scroll wheel : select the color distribution algorithm by scrolling

  • pan gesture : select the color distribution algorithm by swiping (hint: finalize selection of algorithm with up/down arrow keys)

Pan

Pan Mode enables bindings that can set the pan position (the position under the center pixel) and zoom level (scale) in a Ginga image viewer.

Enter the mode by

  • Space, then “q”

Exit the mode by

  • Esc

Default bindings in mode

  • plus, equals : zoom in one zoom level

  • minus, underscore : zoom out one zoom level

  • 1-9,0 : zoom to level N (0 is 10)

  • Shift + 1-9,0 : zoom to level -N (0 is -10)

  • backquote : fit image to window size

  • doublequote : toggle auto fit for new images “on” or “off” in this viewer

  • singlequote : set auto fit for new images to “override” in this viewer

  • p : pan to the position under the cursor

  • c : pan to the center of the image

  • z : save zoom level (scale)

  • r : pan to cursor and zoom to saved scale level

  • left/right/up/down arrow : pan left/right/up/down by a small percentage

  • Shift + left/right/up/down arrow : pan left/right/up/down by a very small percentage

  • pageup (pagedown) : pan up (down) by a large percentage of the screen

  • home (end) : pan towards the top (bottom) of the image

  • “?” : toggle auto center for new images “on” or “off” in this viewer

  • “/” : set auto center for new images to “override” in this viewer

  • scroll : zoom (scale) the image

  • left drag : pan the view

  • right drag : camera pan the view

  • pan gesture: pan the view porportionally to the gesture

  • pinch gesture: zoom the image porportionally to the gesture

Zoom

Zoom Mode enables bindings that can set the pan position (the center pixel) and zoom level (scale) in a Ginga image viewer.

It differs from Pan mode in the types of scrolling and panning controls.

Enter the mode by

  • Space, then “w”

Exit the mode by

  • Esc

Default bindings in mode

  • middle drag : freely pan around the image

  • left click : set pan under the cursor and zoom in

  • right click : zoom out

  • pan gesture : zoom in/out of the image

  • Shift + pan gesture : zoom in/out of the image with origin set

Rotate

Rotate Mode enables bindings that can flip or swap the axes of an image, or rotate it, in a Ginga image viewer.

Enter the mode by

  • Space, then “r”

Exit the mode by

  • Esc

Default bindings in mode

  • “[” : (toggle) flip the image in the X axis

  • “{” : Restore the X axis

  • “]” : (toggle) flip the image in the Y axis

  • “}” : Restore the Y axis

  • backslash : (toggle) swap the X and Y axes

  • “|” : Restore the swapped axes to normal

  • R : reset rotation to 0 deg (does not reset any flips or swaps)

  • t : resets any flips or swaps

  • period : rotate image incrementally by +90 deg

  • comma : rotate image by incrementally -90 deg

  • o : orient the image so that North points up and East points left

  • O : orient the image so that North points up and East points right

  • left drag : rotate the image interactively

  • right click : reset the rotation to 0 deg (same as R)

  • rotation gesture : rotate the image interactively

Naxis

Naxis Mode enables bindings that can move through the slices in an image stack in a Ginga image viewer.

Enter the mode by

  • Space, then “n”

Exit the mode by

  • Esc

Default bindings in mode

  • scroll : select previous or next slice of current axis

  • Ctrl + scroll : select previous or next axis as current axis

  • left drag : select slice as a function of percentage of cursor/window width

  • up/down arrow : select previous or next axis as current axis