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:
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).
Modal vs. Non-modal Operation
Ginga viewer widgets have a dual modal/non-modal (aka “modeless”) operation. If no mode is active, then certain operations from a mode can still be invoked by default bindings that are declared for the modeless state. For example, by default, the scroll wheel will normally operate the zoom operation on the viewer even though that is officially an operation defined in the “Pan” mode. Furthermore, Ginga canvases can also register for keystroke and cursor bindings. The resolution order of handling a particular keyboard or cursor event is as follows:
if the viewer is in a mode, and there is a binding for the event in the mode
if there is a active canvas that has a binding for the event
if there is a binding for the event in the modeless state
At each stage of this event resolution, if the event is not handled by the event handler (in the previous stage), then the next stage of event handling is invoked.
Basically, this boils down to the following practical advice:
A mode takes precedence; you can always count on the bindings in the mode doing what they do, no matter what canvases are active.
If you are using an active canvas (like many Reference Viewer plugins do), you may need to exit out of a mode if bindings for the mode interfere (mask) necessary bindings for the canvas.
If some default modeless binding doesn’t seem to be working, it may be because an active canvas has registered for that binding. In such a case, you can invoke a mode to do the operation and then exit the mode to get back to working with the canvas, or close the plugin that has installed the active canvas.
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 whenEsc
is pressed (if no cursor drag is performed)locked
: The mode is locked until the meta mode key is pressed again (orEsc
)
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