ImageViewBase

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

Bases: 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_orient()	Set the orientation for the image to a reasonable default.
autocut_params_cb(setting, value)	Handle callback related to changes in auto-cut levels.
calc_pan_pct([pad, min_pct, max_pct])	Calculate values for vertical/horizontal panning by percentages from the current pan position.
canvas_changed_cb(canvas, whence)	Handle callback for when canvas has changed.
canvascoords(data_x, data_y)	Same as get_canvas_xy().
capture_default_viewer_profile()
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)	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.
flip_x()	Transform view of the image by flipping the X axis.
flip_y()	Transform view of the image by flipping the Y axis.
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)	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_rect()	Get the approximate LL and UR corners of the displayed image.
get_data_size()	Get the dimensions of the image currently being displayed.
get_data_xy(win_x, win_y)	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_bbox()	Get the coordinates in the actual data corresponding to the area needed for drawing images for the current zoom level and pan.
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_bbox()	Get the coordinates in the actual data corresponding to the area shown in the display for the current zoom level and pan.
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.
invert_color_map()	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[, size])	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)	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_by_pct(pct_x, pct_y[, pad])	Pan by a percentage of the data space.
pan_cb(setting, value)	Handle callback related to changes in pan.
pan_center_px()	Pan to the center of the current pixel under the cursor.
pan_delta_px(x_delta_px, y_delta_px)	Pan by a delta in X and Y specified in pixels.
pan_lr(pct_vw, sign)	Pan left/right by an amount specified as a percentage of the visible width.
pan_omni(direction_deg, amount[, lock_x, lock_y])	Pan in a direction defined in degrees by an amount specified as a percentage.
pan_ud(pct_vh, sign[, msg])	Pan up/down by an amount specified as a percentage of the visible height.
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_at_canvas_xy(data_pt, canvas_pt[, ...])	Position a data point at a certain canvas position.
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.
reload_image()
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.
rotate_color_map(pct)	Rotate the color map.
rotate_delta(delta_deg)	Rotate the view of an image in a channel by a delta.
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_brightness(pct)	Set the brightness of the viewer.
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_contrast(pct)	Set the contrast of the viewer.
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.
swap_xy()	Transform view of the image by swapping the X and Y axes.
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_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([axis, 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)

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)

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)

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_orient()

Set the orientation for the image to a reasonable default.

autocut_params_cb(setting, value)

Handle callback related to changes in auto-cut levels.

calc_pan_pct(pad=0, min_pct=0.0, max_pct=0.9)

Calculate values for vertical/horizontal panning by percentages from the current pan position. Mostly used by scrollbar callbacks.

Parameters:

padint (optional, defaults to 0)

a padding amount in pixels to add to the limits when calculating

min_pctfloat (optional, range 0.0:1.0, defaults to 0.0)

max_pctfloat (optional, range 0.0:1.0, defaults to 0.9)

Returns:

resBunch

calculation results, which include the following attributes: - rng_x : the range of X of the limits (including padding) - rng_y : the range of Y of the limits (including padding) - vis_x : the visually shown range of X in the viewer - vis_y : the visually shown range of Y in the viewer - thm_pct_x : the length of a X scrollbar arm as a ratio - thm_pct_y : the length of a Y scrollbar arm as a ratio - pan_pct_x : the pan position of X as a ratio - pan_pct_y : the pan position of Y as a ratio

canvas_changed_cb(canvas, whence)

Handle callback for when canvas has changed.

canvascoords(data_x, data_y)

Same as get_canvas_xy().

capture_default_viewer_profile()

capture_profile(profile)

center_cursor()

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

This should be implemented by subclasses.

center_image(no_reset=True)

Pan to the center of the image.

Parameters:

no_resetbool

See set_pan().

check_cursor_location()

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

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=False, whence=0)

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)

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

Parameters:

target

Subclass of ImageViewBase.

cut_levels(loval, hival, no_reset=False)

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)

Handle callback related to changes in cut levels.

data_to_offset(data_x, data_y)

Reverse of offset_to_data().

define_cursor(cname, cursor)

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()

Handle delayed redrawing of the canvas.

enable_auto_orient(tf)

Set auto_orient behavior.

Parameters:

tfbool

Turns automatic image orientation on or off.

enable_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.

enable_autocuts(option)

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)

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.

flip_x()

Transform view of the image by flipping the X axis.

flip_y()

Transform view of the image by flipping the Y axis.

get_autocenter_options()

Get all valid autocenter options.

Returns:

autocenter_optionstuple

A list of valid options.

get_autocut_methods()

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

get_autocuts_options()

Get all valid autocuts options.

Returns:

autocuts_optionstuple

A list of valid options.

get_autozoom_options()

Get all valid autozoom options.

Returns:

autozoom_optionstuple

A list of valid options.

get_bg()

Get the background color.

Returns:

img_bgtuple

RGB values.

get_canvas()

Get the canvas object used by this instance.

Returns:

canvasDrawingCanvas

Canvas.

get_canvas_image()

Get canvas image object.

Returns:

imgobjNormImage

Normalized image sitting on the canvas.

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)

Reverse of get_data_xy().

get_center()

Get image center.

Returns:

ctrtuple

X and Y positions, in that order.

get_color_algorithms()

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

get_coordmap(key)

Get coordinate mapper.

Parameters:

keystr

Name of the desired coordinate mapper.

Returns:

mapper

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

get_cursor(cname)

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()

Get cut levels.

Returns:

cutstuple

Low and high values, in that order.

get_data(data_x, data_y)

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)

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)

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

get_data_rect()

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_data_size()

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)

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

Parameters:

win_x, win_yfloat or ndarray

Window coordinates.

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()

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()

Get desired size.

Returns:

sizetuple

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

get_dims(data)

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_bbox()

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_bbox(), 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_draw_rect()

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_bbox(), 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()

Get the foreground color.

Returns:

img_fgtuple

RGB values.

get_image()

Get the image currently being displayed.

Returns:

imageAstroImage or RGBImage

Image object.

get_image_as_array(order=None)

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)

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()

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

get_last_win_xy()

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

get_limits(coord='data')

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()

Get the logger used by this instance.

Returns:

loggerLogger

Logger.

get_pan(coord='data')

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_bbox()

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_pan_rect()

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)

Calculate distance between the given pixel positions.

Parameters:

x1, y1, x2, y2number

Pixel coordinates.

Returns:

distfloat

Rounded distance.

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. 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()

Get the private canvas object used by this instance.

Returns:

canvasDrawingCanvas

Canvas.

get_refresh_stats()

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)

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)

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)

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()

Get RGB order.

Returns:

rgbstr

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

get_rgbmap()

Get the RGB map object used by this instance.

Returns:

rgbmapRGBMapper

RGB map.

get_rotation()

Get image rotation angle.

Returns:

rot_degfloat

Rotation angle in degrees.

get_rotation_info()

Get rotation information.

Returns:

infotuple

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

get_scale()

Same as get_scale_max().

get_scale_base_xy()

Get stretch factors.

Returns:

stretchfactorstuple

Stretch factors for X and Y, in that order.

get_scale_limits()

Get scale limits.

Returns:

scale_limitstuple

Minimum and maximum scale limits, respectively.

get_scale_max()

Get maximum scale factor.

Returns:

scalefactorfloat

Scale factor for X or Y, whichever is larger.

get_scale_min()

Get minimum scale factor.

Returns:

scalefactorfloat

Scale factor for X or Y, whichever is smaller.

get_scale_text()

Report current scaling in human-readable format.

Returns:

textstr

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

get_scale_xy()

Get scale factors.

Returns:

scalefactorstuple

Scale factors for X and Y, in that order.

get_settings()

Get the settings used by this instance.

Returns:

settingsSettingGroup

Settings.

get_transforms()

Get transformations behavior.

Returns:

transformstuple

Selected options for flip_x, flip_y, and swap_xy.

get_vip()

Get the ViewerImageProxy object used by this instance.

Returns:

vipViewerImageProxy

A ViewerImageProxy object.

get_window_size()

Get the window size in the underlying implementation.

Returns:

sizetuple

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

get_zoom()

Get zoom level.

Returns:

zoomlevelfloat

Zoom level.

get_zoom_algorithm()

Get zoom algorithm.

Returns:

namestr

Name of the zoom algorithm in use.

get_zoomrate()

Get zoom rate.

Returns:

zoomratefloat

Zoom rate.

getwin_array(order='RGB', alpha=1.0, dtype=None)

getwin_buffer(order='RGB', alpha=1.0, dtype=None)

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.

invert_color_map()

Invert the color map.

is_compound()

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()

Indicates whether a deferred redraw has been scheduled.

Returns:

pendingbool

True if a deferred redraw is pending, False otherwise.

make_cursor(iconpath, x, y, size=None)

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

size: (int, int) tuple or None (optional, defaults to None)

the size of the cursor to create in pixels (width, height)

make_timer()

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)

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)

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)

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()

Erase any message onscreen in the viewer window.

pan_by_pct(pct_x, pct_y, pad=0)

Pan by a percentage of the data space. This method is designed to be called by scrollbar callbacks.

Parameters:

pct_xfloat (range 0.01.0)

Percentage in the X range to pan

pct_yfloat (range 0.01.0)

Percentage in the Y range to pan

padint (optional, defaults to 0)

a padding amount in pixels to add to the limits when calculating

min_pctfloat (optional, range 0.0:1.0, defaults to 0.0)

max_pctfloat (optional, range 0.0:1.0, defaults to 0.9)

pan_cb(setting, value)

Handle callback related to changes in pan.

pan_center_px()

Pan to the center of the current pixel under the cursor.

pan_delta_px(x_delta_px, y_delta_px)

Pan by a delta in X and Y specified in pixels.

Parameters:

x_delta_pxfloat

Delta pixels in X

y_delta_pxfloat

Delta pixels in Y

pan_lr(pct_vw, sign)

Pan left/right by an amount specified as a percentage of the visible width.

Parameters:

pct_vwfloat (range 0.01.0)

Percent of visible width to pan

signint (1 or -1)

-1 for left, 1 for right

pan_omni(direction_deg, amount, lock_x=False, lock_y=False)

Pan in a direction defined in degrees by an amount specified as a percentage.

Parameters:

direction_degfloat (range 0.0360.0)

Direction in which to pan, where 0.0 is defined as

amountfloat (range 0.01.0)

Amount to distribute to X and Y according to direction

lock_xbool (optional, defaults to False)

If True, do not allow any panning in the X direction

lock_ybool (optional, defaults to False)

If True, do not allow any panning in the Y direction

pan_ud(pct_vh, sign, msg=False)

Pan up/down by an amount specified as a percentage of the visible height.

Parameters:

pct_vhfloat (range 0.01.0)

Percent of visible height to pan

signint (1 or -1)

-1 for up, 1 for down

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=False)

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

position_at_canvas_xy(data_pt, canvas_pt, no_reset=False)

Position a data point at a certain canvas position. Calculates and sets the pan position necessary to position a data point precisely at a point on the canvas.

Parameters:

data_pttuple

data point to position, must include x and y (x, y).

canvas_pttuple

canvas coordinate (cx, cy) where data point should end up.

no_resetbool

See set_pan().

position_cursor(data_x, data_y)

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)

This can be overridden by subclasses.

recalc_transforms(trcat=None)

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

redraw(whence=0)

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)

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)

Redraw the displayed image.

Parameters:

whence

See redraw().

refresh_timer_cb(timer, flags)

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

reload_image()

reschedule_redraw(time_sec)

Reschedule redraw event.

This should be implemented by subclasses.

Parameters:

time_secfloat

Time, in seconds, to wait.

reset_limits()

Reset the bounding box of the viewer extents.

Parameters:

None

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.

Note

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

Parameters:

degfloat

Rotation angle in degrees.

rotate_color_map(pct)

Rotate the color map.

Parameters:

pctfloat

The percentage (range: -1.0: 1.0) to rotate the color map.

rotate_delta(delta_deg)

Rotate the view of an image in a channel by a delta.

Note

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

Parameters:

delta_degfloat

Incremental rotation angle in degrees.

rotation_change_cb(setting, value)

Handle callback related to changes in rotation angle.

save_plain_image_as_file(filepath, format='png', quality=90)

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)

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)

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)

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

scale_cb(setting, value)

Handle callback related to image scaling.

scale_to(scale_x, scale_y, no_reset=False)

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)

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)

Set the auto-cut algorithm.

Parameters:

autocutssubclass of AutoCutsBase

An object that implements the desired auto-cut algorithm.

set_background(bg)

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)

Set the background color.

Parameters:

r, g, bfloat

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

set_brightness(pct)

Set the brightness of the viewer.

Parameters:

pctfloat

The percentage (range: 0.0: 1.0) to set the brightness.

set_calg(dist)

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

set_canvas(canvas, private_canvas=None)

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)

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

set_color_algorithm(calg_name, **kwdargs)

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)

Set the color map.

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

Parameters:

cmap_namestr

The name of a color map.

set_contrast(pct)

Set the contrast of the viewer.

Parameters:

pctfloat

The percentage (range: 0.0: 1.0) to set the contrast.

set_coordmap(key, mapper)

Set coordinate mapper.

Parameters:

keystr

Name of the coordinate mapper.

mapper

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

set_cursor(cursor)

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)

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)

See set_window_size().

set_enter_focus(tf)

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)

Set the foreground color.

Parameters:

r, g, bfloat

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

set_foreground(fg)

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)

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)

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

set_intensity_map(imap_name)

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')

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)

Set viewer name.

set_onscreen_message(text, redraw=True)

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)

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)

Set lag time for redrawing the canvas.

Parameters:

lag_secfloat

Number of seconds to wait.

set_refresh_rate(fps)

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

Parameters:

fpsfloat

Desired rate in frames per second.

set_renderer(renderer)

Set and initialize the renderer used by this instance.

set_rgbmap(rgbmap)

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)

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)

Set stretch factors.

Parameters:

scale_x_base, scale_y_basefloat

Stretch factors for X and Y, respectively.

set_scale_limits(scale_min, scale_max)

Set scale limits.

Parameters:

scale_min, scale_maxfloat

Minimum and maximum scale limits, respectively.

set_window_size(width, height)

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)

Set zoom algorithm.

Parameters:

namestr

Name of a zoom algorithm to use.

set_zoomrate(zoomrate)

Set zoom rate.

Parameters:

zoomratefloat

Zoom rate.

shift_cmap(pct)

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

show_color_bar(tf, side='bottom')

show_focus_indicator(tf, color='white')

show_mode_indicator(tf, corner='ur')

show_pan_mark(tf, color='red')

start_refresh()

Start redrawing the canvas at the previously set timed interval.

stop_refresh()

Stop redrawing the canvas at the previously set timed interval.

swap_xy()

Transform view of the image by swapping the X and Y axes.

switch_cursor(cname)

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

Parameters:

cnamestr

name of the cursor to switch to.

take_focus()

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)

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)

Handle callback related to changes in transformations.

update_widget()

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

classmethod 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.

Returns:

resbool

Returns True if the origin is up, False otherwise.

window_to_offset(win_x, win_y)

Reverse of offset_to_window().

zoom_fit(axis='lock', no_reset=False)

Zoom to fit display window. Pan the image and scale the view to fit the size of the set limits (usually set to the image size). Parameter axis can be used to set which axes are allowed to be scaled; if set to ‘lock’ then all axes are scaled in such a way as to keep the scale factor uniform between axes. Also see zoom_to().

Parameters:

axisstr

One of: ‘x’, ‘y’, ‘xy’, or ‘lock’ (default).

no_resetbool

Do not reset autozoom setting.

zoom_in(incr=1.0)

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)

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)

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)

Handle callback related to changes in zoom.