ImageViewBase

class ginga.ImageView.ImageViewBase(logger=None, rgbmap=None, settings=None)[source]

Bases: ginga.misc.Callback.Callbacks

An abstract base class for displaying images represented by Numpy data arrays.

This class attempts to do as much of the image handling as possible using Numpy array manipulations (even color and intensity mapping) so that only a minimal mapping to a pixel buffer is necessary in concrete subclasses that connect to an actual rendering surface (e.g., Qt, GTK, Tk, HTML5).

Parameters
loggerLogger or None

Logger for tracing and debugging. If not given, one will be created.

rgbmapRGBMapper or None

RGB mapper object. If not given, one will be created.

settingsSettingGroup or None

Viewer preferences. If not given, one will be created.

Attributes Summary

vname

vtypes

Methods Summary

apply_profile(profile[, keylist])

Apply a profile to the viewer.

apply_profile_or_settings(image)

Apply a profile to the viewer.

auto_levels([autocuts])

Apply auto-cut levels on the image view.

auto_levels_cb(setting, value)

Handle callback related to changes in auto-cut levels.

auto_orient()

Set the orientation for the image to a reasonable default.

canvas_changed_cb(canvas, whence)

Handle callback for when canvas has changed.

canvascoords(data_x, data_y[, center])

Same as get_canvas_xy().

capture_profile(profile)

center_cursor()

Center the cursor in the viewer’s widget, in both X and Y.

center_image([no_reset])

Pan to the center of the image.

check_cursor_location()

Check whether the data location of the last known position of the cursor has changed.

checkpoint_profile()

clear()

Clear the displayed image.

configure(width, height)

See set_window_size().

configure_surface(width, height)

See configure().

copy_attributes(dst_fi, attrlist[, share, …])

Copy interesting attributes of our configuration to another image view.

copy_to_dst(target)

Extract our image and call set_image() on the target with it.

cut_levels(loval, hival[, no_reset])

Apply cut levels on the image view.

cut_levels_cb(setting, value)

Handle callback related to changes in cut levels.

data_to_offset(data_x, data_y[, center])

Reverse of offset_to_data().

define_cursor(cname, cursor)

Define a viewer cursor under a name.

delayed_redraw()

Handle delayed redrawing of the canvas.

enable_auto_orient(tf)

Set auto_orient behavior.

enable_autocenter(option)

Set autocenter behavior.

enable_autocuts(option)

Set autocuts behavior.

enable_autozoom(option)

Set autozoom behavior.

get_autocenter_options()

Get all valid autocenter options.

get_autocut_methods()

Same as ginga.AutoCuts.AutoCutsBase.get_algorithms().

get_autocuts_options()

Get all valid autocuts options.

get_autozoom_options()

Get all valid autozoom options.

get_bg()

Get the background color.

get_canvas()

Get the canvas object used by this instance.

get_canvas_image()

Get canvas image object.

get_canvas_pt(data_pt)

Similar to get_canvas_xy(), except that it takes a single array of points.

get_canvas_xy(data_x, data_y[, center])

Reverse of get_data_xy().

get_center()

Get image center.

get_color_algorithms()

Get available color distribution algorithm names.

get_coordmap(key)

Get coordinate mapper.

get_cursor(cname)

Get the cursor stored under the name.

get_cut_levels()

Get cut levels.

get_data(data_x, data_y)

Get the data value at the given position.

get_data_pct(xpct, ypct)

Calculate new data size for the given axis ratios.

get_data_pt(win_pt)

Similar to get_data_xy(), except that it takes a single array of points.

get_data_size()

Get the dimensions of the image currently being displayed.

get_data_xy(win_x, win_y[, center])

Get the closest coordinates in the data array to those reported on the window.

get_dataobj()

Get the image currently being displayed.

get_datarect()

Get the approximate LL and UR corners of the displayed image.

get_desired_size()

Get desired size.

get_dims(data)

Get the first two dimensions of Numpy array data.

get_draw_rect()

Get the coordinates in the actual data corresponding to the area needed for drawing images for the current zoom level and pan.

get_fg()

Get the foreground color.

get_image()

Get the image currently being displayed.

get_image_as_array([order])

Get the current image shown in the viewer, with any overlaid graphics, in a numpy array with channels as needed and ordered.

get_image_as_buffer([output, order])

Get the current image shown in the viewer, with any overlaid graphics, in a IO buffer with channels as needed and ordered by the back end widget.

get_last_data_xy()

Get the last position of the cursor in data coordinates.

get_last_win_xy()

Get the last position of the cursor in window coordinates.

get_limits([coord])

Get the bounding box of the viewer extents.

get_logger()

Get the logger used by this instance.

get_pan([coord])

Get pan positions.

get_pan_rect()

Get the coordinates in the actual data corresponding to the area shown in the display for the current zoom level and pan.

get_pixel_distance(x1, y1, x2, y2)

Calculate distance between the given pixel positions.

get_plain_image_as_widget()

Get the current image shown in the viewer, without any overlaid graphics, in the format of an image widget in the back end toolkit.

get_private_canvas()

Get the private canvas object used by this instance.

get_refresh_stats()

Return the measured statistics for timed refresh intervals.

get_rgb_image_as_buffer([output, format, …])

Get the current image shown in the viewer, with any overlaid graphics, in a file IO-like object encoded as a bitmap graphics file.

get_rgb_image_as_bytes([format, quality])

Get the current image shown in the viewer, with any overlaid graphics, in the form of a buffer in the form of bytes.

get_rgb_image_as_widget([output, format, …])

Get the current image shown in the viewer, with any overlaid graphics, in the form of a image widget in the toolkit of the back end.

get_rgb_order()

Get RGB order.

get_rgbmap()

Get the RGB map object used by this instance.

get_rotation()

Get image rotation angle.

get_rotation_info()

Get rotation information.

get_scale()

Same as get_scale_max().

get_scale_base_xy()

Get stretch factors.

get_scale_limits()

Get scale limits.

get_scale_max()

Get maximum scale factor.

get_scale_min()

Get minimum scale factor.

get_scale_text()

Report current scaling in human-readable format.

get_scale_xy()

Get scale factors.

get_settings()

Get the settings used by this instance.

get_transforms()

Get transformations behavior.

get_vip()

Get the ViewerImageProxy object used by this instance.

get_window_size()

Get the window size in the underlying implementation.

get_zoom()

Get zoom level.

get_zoom_algorithm()

Get zoom algorithm.

get_zoomrate()

Get zoom rate.

getwin_array([order, alpha, dtype])

getwin_buffer([order, alpha, dtype])

Same as getwin_array(), but with the output array converted to C-order Python bytes.

icc_profile_cb(setting, value)

Handle callback related to changes in output ICC profiles.

initialize_private_canvas(private_canvas)

Initialize the private canvas used by this instance.

interpolation_change_cb(setting, value)

Handle callback related to changes in interpolation.

invert_cmap()

Invert the color map.

is_compound()

Indicate if canvas object is a compound object.

is_redraw_pending()

Indicates whether a deferred redraw has been scheduled.

make_cursor(iconpath, x, y)

Make a cursor in the viewer’s native widget toolkit.

make_timer()

Return a timer object implemented using the back end.

offset_to_data(off_x, off_y[, center])

Get the closest coordinates in the data array to those in cartesian fixed (non-scaled) canvas coordinates.

offset_to_window(off_x, off_y)

Convert data offset to window coordinates.

onscreen_message(text[, delay, redraw])

Place a message onscreen in the viewer window.

onscreen_message_off()

Erase any message onscreen in the viewer window.

pan_cb(setting, value)

Handle callback related to changes in pan.

panset_pct(pct_x, pct_y)

Similar to set_pan(), except that pan positions are determined by multiplying data dimensions with the given scale factors, where 1 is 100%.

panset_xy(data_x, data_y[, no_reset])

Similar to set_pan(), except that input pan positions are always in data space.

position_cursor(data_x, data_y)

Position the current cursor to a location defined it data coords.

prepare_image(cvs_img, cache, whence)

This can be overridden by subclasses.

recalc_transforms([trcat])

Takes a catalog of transforms (trcat) and builds the chain of default transforms necessary to do rendering with most backends.

redraw([whence])

Redraw the canvas.

redraw_data([whence])

Render image from RGB map and redraw private canvas.

redraw_now([whence])

Redraw the displayed image.

refresh_timer_cb(timer, flags)

Refresh timer callback.

reschedule_redraw(time_sec)

Reschedule redraw event.

reset_limits()

Reset the bounding box of the viewer extents.

restore_cmap()

Restores the color map from any rotation, stretch and/or shrinkage.

restore_contrast()

Restores the color map from any stretch and/or shrinkage.

rgbmap_cb(rgbmap)

Handle callback for when RGB map has changed.

rotate(deg)

Rotate the view of an image in a channel.

rotation_change_cb(setting, value)

Handle callback related to changes in rotation angle.

save_plain_image_as_file(filepath[, format, …])

Save the current image shown in the viewer, without any overlaid graphics, in a file with the specified format and quality.

save_profile(**params)

Save the given parameters into profile settings.

save_rgb_image_as_file(filepath[, format, …])

Save the current image shown in the viewer, with any overlaid graphics, in a file with the specified format and quality.

scale_and_shift_cmap(scale_pct, shift_pct)

Stretch and/or shrink the color map.

scale_cb(setting, value)

Handle callback related to image scaling.

scale_to(scale_x, scale_y[, no_reset])

Scale the image in a channel.

set_autocenter(option)

Set autocenter behavior.

set_autocut_params(method, **params)

Set auto-cut parameters.

set_autocuts(autocuts)

Set the auto-cut algorithm.

set_background(bg)

Set the background color.

set_bg(r, g, b)

Set the background color.

set_calg(dist)

Set color distribution algorithm.

set_canvas(canvas[, private_canvas])

Set the canvas object.

set_cmap(cm)

Set color map.

set_color_algorithm(calg_name, **kwdargs)

Set the color distribution algorithm.

set_color_map(cmap_name)

Set the color map.

set_coordmap(key, mapper)

Set coordinate mapper.

set_cursor(cursor)

Set the cursor in the viewer widget.

set_data(data[, metadata])

Set an image to be displayed by providing raw data.

set_dataobj(image[, add_to_canvas])

Set an image to be displayed.

set_desired_size(width, height)

See set_window_size().

set_enter_focus(tf)

Determine whether the viewer widget should take focus when the cursor enters the window.

set_fg(r, g, b)

Set the foreground color.

set_foreground(fg)

Set the foreground color.

set_image(image[, add_to_canvas])

Set an image to be displayed.

set_imap(im)

Set intensity map.

set_intensity_map(imap_name)

Set the intensity map.

set_limits(limits[, coord])

Set the bounding box of the viewer extents.

set_name(name)

Set viewer name.

set_onscreen_message(text[, redraw])

Called by a subclass to update the onscreen message.

set_pan(pan_x, pan_y[, coord, no_reset])

Set pan position.

set_redraw_lag(lag_sec)

Set lag time for redrawing the canvas.

set_refresh_rate(fps)

Set the refresh rate for redrawing the canvas at a timed interval.

set_renderer(renderer)

Set and initialize the renderer used by this instance.

set_rgbmap(rgbmap)

Set RGB map object used by this instance.

set_scale(scale[, no_reset])

Scale the image in a channel.

set_scale_base_xy(scale_x_base, scale_y_base)

Set stretch factors.

set_scale_limits(scale_min, scale_max)

Set scale limits.

set_window_size(width, height)

Report the size of the window to display the image.

set_zoom_algorithm(name)

Set zoom algorithm.

set_zoomrate(zoomrate)

Set zoom rate.

shift_cmap(pct)

Shift color map.

show_color_bar(tf[, side])

show_focus_indicator(tf[, color])

show_mode_indicator(tf[, corner])

show_pan_mark(tf[, color])

start_refresh()

Start redrawing the canvas at the previously set timed interval.

stop_refresh()

Stop redrawing the canvas at the previously set timed interval.

switch_cursor(cname)

Switch the viewer’s cursor to the one defined under a name.

take_focus()

Have the widget associated with this viewer take the keyboard focus.

transform(flip_x, flip_y, swap_xy)

Transform view of the image.

transform_cb(setting, value)

Handle callback related to changes in transformations.

update_image()

update_widget()

Update the area corresponding to the backend widget.

viewable(dataobj)

Test whether dataobj is viewable by this viewer.

window_has_origin_upper()

Indicate if window of backend toolkit is implemented with an origin up or down.

window_to_offset(win_x, win_y)

Reverse of offset_to_window().

zoom_fit([no_reset])

Zoom to fit display window.

zoom_in([incr])

Zoom in a level.

zoom_out([decr])

Zoom out a level.

zoom_to(zoomlevel[, no_reset])

Set zoom level in a channel.

zoomsetting_change_cb(setting, value)

Handle callback related to changes in zoom.

Attributes Documentation

vname = 'Ginga Image'
vtypes = [<class 'ginga.BaseImage.BaseImage'>]

Methods Documentation

apply_profile(profile, keylist=None)[source]

Apply a profile to the viewer.

Parameters
profileSettingGroup
This function is used to initialize the viewer to a known state.
The keylist, if given, will limit the items to be transferred
from the profile to viewer settings, otherwise all items are
copied.
apply_profile_or_settings(image)[source]

Apply a profile to the viewer.

Parameters
imageAstroImage or RGBImage

Image object.

This function is used to initialize the viewer when a new image
is loaded. Either the embedded profile settings or the default
settings are applied as specified in the channel preferences.
auto_levels(autocuts=None)[source]

Apply auto-cut levels on the image view.

Parameters
autocutssubclass of AutoCutsBase or None

An object that implements the desired auto-cut algorithm. If not given, use algorithm from preferences.

auto_levels_cb(setting, value)[source]

Handle callback related to changes in auto-cut levels.

auto_orient()[source]

Set the orientation for the image to a reasonable default.

canvas_changed_cb(canvas, whence)[source]

Handle callback for when canvas has changed.

canvascoords(data_x, data_y, center=None)[source]

Same as get_canvas_xy().

capture_profile(profile)[source]
center_cursor()[source]

Center the cursor in the viewer’s widget, in both X and Y.

This should be implemented by subclasses.

center_image(no_reset=True)[source]

Pan to the center of the image.

Parameters
no_resetbool

See set_pan().

check_cursor_location()[source]

Check whether the data location of the last known position of the cursor has changed. If so, issue a callback.

checkpoint_profile()[source]
clear()[source]

Clear the displayed image.

configure(width, height)[source]

See set_window_size().

configure_surface(width, height)[source]

See configure().

copy_attributes(dst_fi, attrlist, share=False, whence=0)[source]

Copy interesting attributes of our configuration to another image view.

Parameters
dst_fisubclass of ImageViewBase

Another instance of image view.

attrlistlist

A list of attribute names to copy. They can be 'transforms', 'rotation', 'cutlevels', 'rgbmap', 'zoom', 'pan', 'autocuts', 'limits', 'icc' or 'interpolation'.

sharebool

If True, the designated settings will be shared, otherwise the values are simply copied.

copy_to_dst(target)[source]

Extract our image and call set_image() on the target with it.

Parameters
target

Subclass of ImageViewBase.

cut_levels(loval, hival, no_reset=False)[source]

Apply cut levels on the image view.

Parameters
loval, hivalfloat

Low and high values of the cut levels, respectively.

no_resetbool

Do not reset autocuts setting.

cut_levels_cb(setting, value)[source]

Handle callback related to changes in cut levels.

data_to_offset(data_x, data_y, center=None)[source]

Reverse of offset_to_data().

define_cursor(cname, cursor)[source]

Define a viewer cursor under a name. Does not change the current cursor.

Parameters
cnamestr

name of the cursor to define.

cursorobject

a cursor object in the back end’s toolkit

`cursor` is usually constructed from `make_cursor`.
delayed_redraw()[source]

Handle delayed redrawing of the canvas.

enable_auto_orient(tf)[source]

Set auto_orient behavior.

Parameters
tfbool

Turns automatic image orientation on or off.

enable_autocenter(option)[source]

Set autocenter behavior.

Parameters
option{‘on’, ‘override’, ‘once’, ‘off’}

Option for auto-center behavior. A list of acceptable options can also be obtained by get_autocenter_options().

Raises
ginga.ImageView.ImageViewError

Invalid option.

enable_autocuts(option)[source]

Set autocuts behavior.

Parameters
option{‘on’, ‘override’, ‘once’, ‘off’}

Option for auto-cut behavior. A list of acceptable options can also be obtained by get_autocuts_options().

Raises
ginga.ImageView.ImageViewError

Invalid option.

enable_autozoom(option)[source]

Set autozoom behavior.

Parameters
option{‘on’, ‘override’, ‘once’, ‘off’}

Option for zoom behavior. A list of acceptable options can also be obtained by get_autozoom_options().

Raises
ginga.ImageView.ImageViewError

Invalid option.

get_autocenter_options()[source]

Get all valid autocenter options.

Returns
autocenter_optionstuple

A list of valid options.

get_autocut_methods()[source]

Same as ginga.AutoCuts.AutoCutsBase.get_algorithms().

get_autocuts_options()[source]

Get all valid autocuts options.

Returns
autocuts_optionstuple

A list of valid options.

get_autozoom_options()[source]

Get all valid autozoom options.

Returns
autozoom_optionstuple

A list of valid options.

get_bg()[source]

Get the background color.

Returns
img_bgtuple

RGB values.

get_canvas()[source]

Get the canvas object used by this instance.

Returns
canvasDrawingCanvas

Canvas.

get_canvas_image()[source]

Get canvas image object.

Returns
imgobjNormImage

Normalized image sitting on the canvas.

get_canvas_pt(data_pt)[source]

Similar to get_canvas_xy(), except that it takes a single array of points.

get_canvas_xy(data_x, data_y, center=None)[source]

Reverse of get_data_xy().

get_center()[source]

Get image center.

Returns
ctrtuple

X and Y positions, in that order.

get_color_algorithms()[source]

Get available color distribution algorithm names. See ginga.ColorDist.get_dist_names().

get_coordmap(key)[source]

Get coordinate mapper.

Parameters
keystr

Name of the desired coordinate mapper.

Returns
mapper

Coordinate mapper object (see ginga.canvas.coordmap).

get_cursor(cname)[source]

Get the cursor stored under the name. This can be overridden by subclasses, if necessary.

Parameters
cnamestr

name of the cursor to return.

get_cut_levels()[source]

Get cut levels.

Returns
cutstuple

Low and high values, in that order.

get_data(data_x, data_y)[source]

Get the data value at the given position. Indices are zero-based, as in Numpy.

Parameters
data_x, data_yint

Data indices for X and Y, respectively.

Returns
value

Data value.

get_data_pct(xpct, ypct)[source]

Calculate new data size for the given axis ratios. See get_limits().

Parameters
xpct, ypctfloat

Ratio for X and Y, respectively, where 1 is 100%.

Returns
x, yint

Scaled dimensions.

get_data_pt(win_pt)[source]

Similar to get_data_xy(), except that it takes a single array of points.

get_data_size()[source]

Get the dimensions of the image currently being displayed.

Returns
sizetuple

Image dimensions in the form of (width, height).

get_data_xy(win_x, win_y, center=None)[source]

Get the closest coordinates in the data array to those reported on the window.

Parameters
win_x, win_yfloat or ndarray

Window coordinates.

centerbool

If True, then the coordinates are mapped such that the pixel is centered on the square when the image is zoomed in past 1X. This is the specification of the FITS image standard, that the pixel is centered on the integer row/column.

Returns
coordtuple

Data coordinates in the form of (x, y).

get_dataobj()

Get the image currently being displayed.

Returns
imageAstroImage or RGBImage

Image object.

get_datarect()[source]

Get the approximate LL and UR corners of the displayed image.

Returns
recttuple

Bounding box in data coordinates in the form of (x1, y1, x2, y2).

get_desired_size()[source]

Get desired size.

Returns
sizetuple

Desired size in the form of (width, height).

get_dims(data)[source]

Get the first two dimensions of Numpy array data. Data may have more dimensions, but they are not reported.

Returns
dimstuple

Data dimensions in the form of (width, height).

get_draw_rect()[source]

Get the coordinates in the actual data corresponding to the area needed for drawing images for the current zoom level and pan. Unlike get_pan_rect(), this includes areas outside of the current viewport, but that might be viewed with a transformation or rotation subsequently applied.

Returns
pointslist

Coordinates in the form of [(x0, y0), (x1, y1), (x2, y2), (x3, y3)] corresponding to the four corners.

get_fg()[source]

Get the foreground color.

Returns
img_fgtuple

RGB values.

get_image()[source]

Get the image currently being displayed.

Returns
imageAstroImage or RGBImage

Image object.

get_image_as_array(order=None)[source]

Get the current image shown in the viewer, with any overlaid graphics, in a numpy array with channels as needed and ordered.

This can be overridden by subclasses.

get_image_as_buffer(output=None, order=None)[source]

Get the current image shown in the viewer, with any overlaid graphics, in a IO buffer with channels as needed and ordered by the back end widget.

This can be overridden by subclasses.

Parameters
outputa file IO-like object or None

open python IO descriptor or None to have one created

Returns
bufferfile IO-like object

This will be the one passed in, unless output is None in which case a BytesIO obejct is returned

get_last_data_xy()[source]

Get the last position of the cursor in data coordinates. This can be overridden by subclasses, if necessary.

get_last_win_xy()[source]

Get the last position of the cursor in window coordinates. This can be overridden by subclasses, if necessary.

get_limits(coord='data')[source]

Get the bounding box of the viewer extents.

Returns
limitstuple
Bounding box in coordinates of type coord in the form of

(ll_pt, ur_pt).

get_logger()[source]

Get the logger used by this instance.

Returns
loggerLogger

Logger.

get_pan(coord='data')[source]

Get pan positions.

Parameters
coord{‘data’, ‘wcs’}

Indicates whether the pan positions are returned in data or WCS space.

Returns
positionstuple

X and Y positions, in that order.

get_pan_rect()[source]

Get the coordinates in the actual data corresponding to the area shown in the display for the current zoom level and pan.

Returns
pointslist

Coordinates in the form of [(x0, y0), (x1, y1), (x2, y2), (x3, y3)] from lower-left to lower-right.

get_pixel_distance(x1, y1, x2, y2)[source]

Calculate distance between the given pixel positions.

Parameters
x1, y1, x2, y2number

Pixel coordinates.

Returns
distfloat

Rounded distance.

get_plain_image_as_widget()[source]

Get the current image shown in the viewer, without any overlaid graphics, in the format of an image widget in the back end toolkit. Typically used for generating thumbnails. This should be implemented by subclasses.

Returns
widgetobject

An image widget object in the viewer’s back end toolkit

get_private_canvas()[source]

Get the private canvas object used by this instance.

Returns
canvasDrawingCanvas

Canvas.

get_refresh_stats()[source]

Return the measured statistics for timed refresh intervals.

Returns
statsfloat

The measured rate of actual back end updates in frames per second.

get_rgb_image_as_buffer(output=None, format='png', quality=90)[source]

Get the current image shown in the viewer, with any overlaid graphics, in a file IO-like object encoded as a bitmap graphics file.

This can be overridden by subclasses.

Parameters
outputa file IO-like object or None

open python IO descriptor or None to have one created

formatstr

A string defining the format to save the image. Typically at least ‘jpeg’ and ‘png’ are supported. (default: ‘png’)

quality: int

The quality metric for saving lossy compressed formats.

Returns
bufferfile IO-like object

This will be the one passed in, unless output is None in which case a BytesIO obejct is returned

get_rgb_image_as_bytes(format='png', quality=90)[source]

Get the current image shown in the viewer, with any overlaid graphics, in the form of a buffer in the form of bytes.

Parameters
formatstr

See get_rgb_image_as_buffer().

quality: int

See get_rgb_image_as_buffer().

Returns
bufferbytes

The window contents as a buffer in the form of bytes.

get_rgb_image_as_widget(output=None, format='png', quality=90)[source]

Get the current image shown in the viewer, with any overlaid graphics, in the form of a image widget in the toolkit of the back end.

Parameters
See :meth:`get_rgb_image_as_buffer`.
Returns
widgetobject

An image widget object in the viewer’s back end toolkit

get_rgb_order()[source]

Get RGB order.

Returns
rgbstr

Returns the order of RGBA planes required by the subclass to render the canvas properly.

get_rgbmap()[source]

Get the RGB map object used by this instance.

Returns
rgbmapRGBMapper

RGB map.

get_rotation()[source]

Get image rotation angle.

Returns
rot_degfloat

Rotation angle in degrees.

get_rotation_info()[source]

Get rotation information.

Returns
infotuple

X and Y positions, and rotation angle in degrees, in that order.

get_scale()[source]

Same as get_scale_max().

get_scale_base_xy()[source]

Get stretch factors.

Returns
stretchfactorstuple

Stretch factors for X and Y, in that order.

get_scale_limits()[source]

Get scale limits.

Returns
scale_limitstuple

Minimum and maximum scale limits, respectively.

get_scale_max()[source]

Get maximum scale factor.

Returns
scalefactorfloat

Scale factor for X or Y, whichever is larger.

get_scale_min()[source]

Get minimum scale factor.

Returns
scalefactorfloat

Scale factor for X or Y, whichever is smaller.

get_scale_text()[source]

Report current scaling in human-readable format.

Returns
textstr

'<num> x' if enlarged, or '1/<num> x' if shrunken.

get_scale_xy()[source]

Get scale factors.

Returns
scalefactorstuple

Scale factors for X and Y, in that order.

get_settings()[source]

Get the settings used by this instance.

Returns
settingsSettingGroup

Settings.

get_transforms()[source]

Get transformations behavior.

Returns
transformstuple

Selected options for flip_x, flip_y, and swap_xy.

get_vip()[source]

Get the ViewerImageProxy object used by this instance.

Returns
vipViewerImageProxy

A ViewerImageProxy object.

get_window_size()[source]

Get the window size in the underlying implementation.

Returns
sizetuple

Window size in the form of (width, height).

get_zoom()[source]

Get zoom level.

Returns
zoomlevelfloat

Zoom level.

get_zoom_algorithm()[source]

Get zoom algorithm.

Returns
namestr

Name of the zoom algorithm in use.

get_zoomrate()[source]

Get zoom rate.

Returns
zoomratefloat

Zoom rate.

getwin_array(order='RGB', alpha=1.0, dtype=None)[source]
getwin_buffer(order='RGB', alpha=1.0, dtype=None)[source]

Same as getwin_array(), but with the output array converted to C-order Python bytes.

icc_profile_cb(setting, value)[source]

Handle callback related to changes in output ICC profiles.

initialize_private_canvas(private_canvas)[source]

Initialize the private canvas used by this instance.

interpolation_change_cb(setting, value)[source]

Handle callback related to changes in interpolation.

invert_cmap()[source]

Invert the color map. See ginga.RGBMap.RGBMapper.invert_cmap().

is_compound()[source]

Indicate if canvas object is a compound object. This can be re-implemented by subclasses that can overplot objects.

Returns
statusbool

Currently, this always returns False.

is_redraw_pending()[source]

Indicates whether a deferred redraw has been scheduled.

Returns
pendingbool

True if a deferred redraw is pending, False otherwise.

make_cursor(iconpath, x, y)[source]

Make a cursor in the viewer’s native widget toolkit. This should be implemented by subclasses.

Parameters
iconpathstr

the path to a PNG image file defining the cursor

xint

the X position of the center of the cursor hot spot

yint

the Y position of the center of the cursor hot spot

make_timer()[source]

Return a timer object implemented using the back end. This should be implemented by subclasses.

Returns
timera Timer object
offset_to_data(off_x, off_y, center=None)[source]

Get the closest coordinates in the data array to those in cartesian fixed (non-scaled) canvas coordinates.

Parameters
off_x, off_yfloat or ndarray

Cartesian canvas coordinates.

Returns
coordtuple

Data coordinates in the form of (x, y).

offset_to_window(off_x, off_y)[source]

Convert data offset to window coordinates.

Parameters
off_x, off_yfloat or ndarray

Data offsets.

Returns
coordtuple

Offset in window coordinates in the form of (x, y).

onscreen_message(text, delay=None, redraw=True)[source]

Place a message onscreen in the viewer window. This must be implemented by subclasses.

Parameters
textstr

the text to draw in the window

delayfloat or None

if None, the message will remain until another message is set. If a float, specifies the time in seconds before the message will be erased. (default: None)

redrawbool

True if the widget should be redrawn right away (so that the message appears). (default: True)

onscreen_message_off()[source]

Erase any message onscreen in the viewer window.

pan_cb(setting, value)[source]

Handle callback related to changes in pan.

panset_pct(pct_x, pct_y)[source]

Similar to set_pan(), except that pan positions are determined by multiplying data dimensions with the given scale factors, where 1 is 100%.

panset_xy(data_x, data_y, no_reset=False)[source]

Similar to set_pan(), except that input pan positions are always in data space.

position_cursor(data_x, data_y)[source]

Position the current cursor to a location defined it data coords. This should be implemented by subclasses.

Parameters
data_xfloat

the X position to position the cursor in data coords

data_yfloat

the X position to position the cursor in data coords

prepare_image(cvs_img, cache, whence)[source]

This can be overridden by subclasses.

recalc_transforms(trcat=None)[source]

Takes a catalog of transforms (trcat) and builds the chain of default transforms necessary to do rendering with most backends.

redraw(whence=0)[source]

Redraw the canvas.

Parameters
whenceint or float

Optimization flag that reduces the time to refresh the viewer by only recalculating what is necessary:

0: New image, pan/scale has changed 1: Cut levels or similar has changed 2: Color mapping has changed 2.3: ICC profile has changed 2.5: Transforms have changed 2.6: Rotation has changed 3: Graphical overlays have changed

redraw_data(whence=0)[source]

Render image from RGB map and redraw private canvas.

Note

Do not call this method unless you are implementing a subclass.

Parameters
whence

See redraw().

redraw_now(whence=0)[source]

Redraw the displayed image.

Parameters
whence

See redraw().

refresh_timer_cb(timer, flags)[source]

Refresh timer callback. This callback will normally only be called internally.

Parameters
timera Ginga GUI timer

A GUI-based Ginga timer

flagsdict-like

A set of flags controlling the timer

reschedule_redraw(time_sec)[source]

Reschedule redraw event.

This should be implemented by subclasses.

Parameters
time_secfloat

Time, in seconds, to wait.

reset_limits()[source]

Reset the bounding box of the viewer extents.

Parameters
None
restore_cmap()[source]

Restores the color map from any rotation, stretch and/or shrinkage. See ginga.RGBMap.RGBMapper.restore_cmap().

restore_contrast()[source]

Restores the color map from any stretch and/or shrinkage. See ginga.RGBMap.RGBMapper.reset_sarr().

rgbmap_cb(rgbmap)[source]

Handle callback for when RGB map has changed.

rotate(deg)[source]

Rotate the view of an image in a channel.

Note

Transforming the image is generally faster than rotating, if rotating in 90 degree increments. Also see transform().

Parameters
degfloat

Rotation angle in degrees.

rotation_change_cb(setting, value)[source]

Handle callback related to changes in rotation angle.

save_plain_image_as_file(filepath, format='png', quality=90)[source]

Save the current image shown in the viewer, without any overlaid graphics, in a file with the specified format and quality. Typically used for generating thumbnails. This should be implemented by subclasses.

Parameters
filepathstr

path of the file to write

formatstr

See get_rgb_image_as_buffer().

quality: int

See get_rgb_image_as_buffer().

save_profile(**params)[source]

Save the given parameters into profile settings.

Parameters
paramsdict

Keywords and values to be saved.

save_rgb_image_as_file(filepath, format='png', quality=90)[source]

Save the current image shown in the viewer, with any overlaid graphics, in a file with the specified format and quality. This can be overridden by subclasses.

Parameters
filepathstr

path of the file to write

formatstr

See get_rgb_image_as_buffer().

quality: int

See get_rgb_image_as_buffer().

scale_and_shift_cmap(scale_pct, shift_pct)[source]

Stretch and/or shrink the color map. See ginga.RGBMap.RGBMapper.scale_and_shift().

scale_cb(setting, value)[source]

Handle callback related to image scaling.

scale_to(scale_x, scale_y, no_reset=False)[source]

Scale the image in a channel. This only changes the viewer settings; the image is not modified in any way. Also see zoom_to().

Parameters
scale_x, scale_yfloat

Scaling factors for the image in the X and Y axes, respectively.

no_resetbool

Do not reset autozoom setting.

set_autocenter(option)

Set autocenter behavior.

Parameters
option{‘on’, ‘override’, ‘once’, ‘off’}

Option for auto-center behavior. A list of acceptable options can also be obtained by get_autocenter_options().

Raises
ginga.ImageView.ImageViewError

Invalid option.

set_autocut_params(method, **params)[source]

Set auto-cut parameters.

Parameters
methodstr

Auto-cut algorithm. A list of acceptable options can be obtained by get_autocut_methods().

paramsdict

Algorithm-specific keywords and values.

set_autocuts(autocuts)[source]

Set the auto-cut algorithm.

Parameters
autocutssubclass of AutoCutsBase

An object that implements the desired auto-cut algorithm.

set_background(bg)[source]

Set the background color.

Parameters
bgstr or tuple of float

color name or tuple of floats, between 0 and 1, inclusive.

set_bg(r, g, b)[source]

Set the background color.

Parameters
r, g, bfloat

RGB values, which should be between 0 and 1, inclusive.

set_calg(dist)[source]

Set color distribution algorithm. See ginga.RGBMap.RGBMapper.set_dist().

set_canvas(canvas, private_canvas=None)[source]

Set the canvas object.

Parameters
canvasDrawingCanvas

Canvas object.

private_canvasDrawingCanvas or None

Private canvas object. If not given, this is the same as canvas.

set_cmap(cm)[source]

Set color map. See ginga.RGBMap.RGBMapper.set_cmap().

set_color_algorithm(calg_name, **kwdargs)[source]

Set the color distribution algorithm.

Available color distribution algorithm names can be discovered using ginga.ColorDist.get_dist_names().

Parameters
calg_namestr

The name of a color distribution algorithm.

kwdargsdict

Keyword arguments for color distribution object (see ColorDist).

set_color_map(cmap_name)[source]

Set the color map.

Available color map names can be discovered using get_names().

Parameters
cmap_namestr

The name of a color map.

set_coordmap(key, mapper)[source]

Set coordinate mapper.

Parameters
keystr

Name of the coordinate mapper.

mapper

Coordinate mapper object (see ginga.canvas.coordmap).

set_cursor(cursor)[source]

Set the cursor in the viewer widget. This should be implemented by subclasses.

Parameters
cursorobject

a cursor object in the back end’s toolkit

set_data(data, metadata=None)[source]

Set an image to be displayed by providing raw data.

This is a convenience method for first constructing an image with AstroImage and then calling set_image().

Parameters
datandarray

This should be at least a 2D Numpy array.

metadatadict or None

Image metadata mapping keywords to their respective values.

set_dataobj(image, add_to_canvas=True)

Set an image to be displayed.

If there is no error, the 'image-unset' and 'image-set' callbacks will be invoked.

Parameters
imageAstroImage or RGBImage

2D Image object.

add_to_canvasbool

Add image to canvas.

set_desired_size(width, height)[source]

See set_window_size().

set_enter_focus(tf)[source]

Determine whether the viewer widget should take focus when the cursor enters the window.

Parameters
tfbool

If True the widget will grab focus when the cursor moves into the window.

set_fg(r, g, b)[source]

Set the foreground color.

Parameters
r, g, bfloat

RGB values, which should be between 0 and 1, inclusive.

set_foreground(fg)[source]

Set the foreground color.

Parameters
fgstr or tuple of float

color name or tuple of floats, between 0 and 1, inclusive.

set_image(image, add_to_canvas=True)[source]

Set an image to be displayed.

If there is no error, the 'image-unset' and 'image-set' callbacks will be invoked.

Parameters
imageAstroImage or RGBImage

2D Image object.

add_to_canvasbool

Add image to canvas.

set_imap(im)[source]

Set intensity map. See ginga.RGBMap.RGBMapper.set_imap().

set_intensity_map(imap_name)[source]

Set the intensity map.

Available intensity map names can be discovered using ginga.imap.get_names().

Parameters
imap_namestr

The name of an intensity map.

set_limits(limits, coord='data')[source]

Set the bounding box of the viewer extents.

Parameters
limitstuple or None

A tuple setting the extents of the viewer in the form of (ll_pt, ur_pt).

set_name(name)[source]

Set viewer name.

set_onscreen_message(text, redraw=True)[source]

Called by a subclass to update the onscreen message.

Parameters
textstr

The text to show in the display.

set_pan(pan_x, pan_y, coord='data', no_reset=False)[source]

Set pan position.

Parameters
pan_x, pan_yfloat

Pan positions in X and Y.

coord{‘data’, ‘wcs’}

Indicates whether the given pan positions are in data or WCS space.

no_resetbool

Do not reset autocenter setting.

set_redraw_lag(lag_sec)[source]

Set lag time for redrawing the canvas.

Parameters
lag_secfloat

Number of seconds to wait.

set_refresh_rate(fps)[source]

Set the refresh rate for redrawing the canvas at a timed interval.

Parameters
fpsfloat

Desired rate in frames per second.

set_renderer(renderer)[source]

Set and initialize the renderer used by this instance.

set_rgbmap(rgbmap)[source]

Set RGB map object used by this instance. It controls how the values in the image are mapped to color.

Parameters
rgbmapRGBMapper

RGB map.

set_scale(scale, no_reset=False)[source]

Scale the image in a channel. Also see zoom_to().

Parameters
scaletuple of float

Scaling factors for the image in the X and Y axes.

no_resetbool

Do not reset autozoom setting.

set_scale_base_xy(scale_x_base, scale_y_base)[source]

Set stretch factors.

Parameters
scale_x_base, scale_y_basefloat

Stretch factors for X and Y, respectively.

set_scale_limits(scale_min, scale_max)[source]

Set scale limits.

Parameters
scale_min, scale_maxfloat

Minimum and maximum scale limits, respectively.

set_window_size(width, height)[source]

Report the size of the window to display the image.

Callbacks

Will call any callbacks registered for the 'configure' event. Callbacks should have a method signature of:

(viewer, width, height, ...)

Note

This is called by the subclass with width and height as soon as the actual dimensions of the allocated window are known.

Parameters
widthint

The width of the window in pixels.

heightint

The height of the window in pixels.

set_zoom_algorithm(name)[source]

Set zoom algorithm.

Parameters
namestr

Name of a zoom algorithm to use.

set_zoomrate(zoomrate)[source]

Set zoom rate.

Parameters
zoomratefloat

Zoom rate.

shift_cmap(pct)[source]

Shift color map. See ginga.RGBMap.RGBMapper.shift().

show_color_bar(tf, side='bottom')[source]
show_focus_indicator(tf, color='white')[source]
show_mode_indicator(tf, corner='ur')[source]
show_pan_mark(tf, color='red')[source]
start_refresh()[source]

Start redrawing the canvas at the previously set timed interval.

stop_refresh()[source]

Stop redrawing the canvas at the previously set timed interval.

switch_cursor(cname)[source]

Switch the viewer’s cursor to the one defined under a name.

Parameters
cnamestr

name of the cursor to switch to.

take_focus()[source]

Have the widget associated with this viewer take the keyboard focus. This should be implemented by subclasses, if they have a widget that can take focus.

transform(flip_x, flip_y, swap_xy)[source]

Transform view of the image.

Note

Transforming the image is generally faster than rotating, if rotating in 90 degree increments. Also see rotate().

Parameters
flipx, flipybool

If True, flip the image in the X and Y axes, respectively

swapxybool

If True, swap the X and Y axes.

transform_cb(setting, value)[source]

Handle callback related to changes in transformations.

update_image()[source]
update_widget()[source]

Update the area corresponding to the backend widget. This must be implemented by subclasses.

classmethod viewable(dataobj)[source]

Test whether dataobj is viewable by this viewer.

window_has_origin_upper()[source]

Indicate if window of backend toolkit is implemented with an origin up or down.

Returns
resbool

Returns True if the origin is up, False otherwise.

window_to_offset(win_x, win_y)[source]

Reverse of offset_to_window().

zoom_fit(no_reset=False)[source]

Zoom to fit display window. Also see zoom_to().

Parameters
no_resetbool

Do not reset autozoom setting.

zoom_in(incr=1.0)[source]

Zoom in a level. Also see zoom_to().

Parameters
incrfloat (optional, defaults to 1)

The value to increase the zoom level

zoom_out(decr=1.0)[source]

Zoom out a level. Also see zoom_to().

Parameters
decrfloat (optional, defaults to 1)

The value to decrease the zoom level

zoom_to(zoomlevel, no_reset=False)[source]

Set zoom level in a channel. This only changes the relevant settings; The image is not modified. Also see scale_to().

Note

In addition to the given zoom level, other zoom settings are defined for the channel in preferences.

Parameters
zoomlevelint

The zoom level to zoom the image. Negative value to zoom out; positive to zoom in.

no_resetbool

Do not reset autozoom setting.

zoomsetting_change_cb(setting, value)[source]

Handle callback related to changes in zoom.