ImageViewBase

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

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:

logger : Logger or None

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

rgbmap : RGBMapper or None

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

settings : SettingGroup 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.
apply_transforms(data, rot_deg)	Apply transformations to the given data.
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().
convert_via_profile(data_np, order, …)	Convert the given RGB data from the working ICC profile to the output profile in-place.
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_datarect()	Get the approximate bounding box of the displayed image.
get_desired_size()	Get desired size.
get_dims(data)	Get the first two dimensions of Numpy array data.
get_fg()	Get the foreground color.
get_image()	Get the image currently being displayed.
get_image_as_array()	Get the current image shown in the viewer, with any overlaid graphics, in a numpy array with channels as needed and ordered by the back end widget.
get_image_as_buffer([output])	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_object([whence])	Create and return RGB slices representing the data that should be rendered at the current zoom level and pan settings.
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_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])	Get Numpy data array for display window.
getwin_buffer([order, alpha, dtype])	Same as getwin_array(), but with the output array converted to C-order Python bytes.
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.
overlay_images(canvas, data[, whence])	Overlay data from any canvas image objects.
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.
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.
render_image(rgbobj, dst_x, dst_y)	Render image.
reschedule_redraw(time_sec)	Reschedule redraw event.
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_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_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_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 image.
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)

Apply a profile to the viewer.

Parameters:

profile : SettingGroup

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:

image : AstroImage 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.

apply_transforms(data, rot_deg)

Apply transformations to the given data. These include flip/swap X/Y, invert Y, and rotation.

Parameters:

data : ndarray

Data to be transformed.

rot_deg : float

Rotate the data by the given degrees.

Returns:

data : ndarray

Transformed data.

auto_levels(autocuts=None)

Apply auto-cut levels on the image view.

Parameters:

autocuts : subclass 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)

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

Same as get_canvas_xy().

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_reset : bool

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

convert_via_profile(data_np, order, inprof_name, outprof_name)

Convert the given RGB data from the working ICC profile to the output profile in-place.

Parameters:

data_np : ndarray

RGB image data to be displayed.

order : str

Order of channels in the data (e.g. “BGRA”).

inprof_name, outprof_name : str

ICC profile names (see ginga.util.rgb_cms.get_profiles()).

copy_attributes(dst_fi, attrlist, share=False)

Copy interesting attributes of our configuration to another image view.

Parameters:

dst_fi : subclass of ImageViewBase

Another instance of image view.

attrlist : list

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

share : bool

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, hival : float

Low and high values of the cut levels, respectively.

no_reset : bool

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, center=None)

Reverse of offset_to_data().

define_cursor(cname, cursor)

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

Parameters:

cname : str

name of the cursor to define.

cursor : object

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:

tf : bool

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.

get_autocenter_options()

Get all valid autocenter options.

Returns:

autocenter_options : tuple

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_options : tuple

A list of valid options.

get_autozoom_options()

Get all valid autozoom options.

Returns:

autozoom_options : tuple

A list of valid options.

get_bg()

Get the background color.

Returns:

img_bg : tuple

RGB values.

get_canvas()

Get the canvas object used by this instance.

Returns:

canvas : DrawingCanvas

Canvas.

get_canvas_image()

Get canvas image object.

Returns:

imgobj : NormImage

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, center=None)

Reverse of get_data_xy().

get_center()

Get image center.

Returns:

ctr : tuple

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:

key : str

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:

cname : str

name of the cursor to return.

get_cut_levels()

Get cut levels.

Returns:

cuts : tuple

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_y : int

Data indices for X and Y, respectively.

Returns:

value

Data slice.

Raises:

ginga.ImageView.ImageViewNoDataError

Image not found.

get_data_pct(xpct, ypct)

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

Parameters:

xpct, ypct : float

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

Returns:

x, y : int

Scaled dimensions.

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.

Returns:

size : tuple

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

get_data_xy(win_x, win_y, center=None)

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

Parameters:

win_x, win_y : float or ndarray

Window coordinates.

center : bool

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:

coord : tuple

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

get_datarect()

Get the approximate bounding box of the displayed image.

Returns:

rect : tuple

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

get_desired_size()

Get desired size.

Returns:

size : tuple

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:

dims : tuple

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

get_fg()

Get the foreground color.

Returns:

img_fg : tuple

RGB values.

get_image()

Get the image currently being displayed.

Returns:

image : AstroImage or RGBImage

Image object.

get_image_as_array()

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

This should be implemented by subclasses.

get_image_as_buffer(output=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:

output : a file IO-like object or None

open python IO descriptor or None to have one created

Returns:

buffer : file 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:

limits : tuple

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:

logger : Logger

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:

positions : tuple

X and Y positions, in that order.

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:

points : list

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, y2 : number

Pixel coordinates.

Returns:

dist : float

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:

widget : object

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

get_private_canvas()

Get the private canvas object used by this instance.

Returns:

canvas : DrawingCanvas

Canvas.

get_refresh_stats()

Return the measured statistics for timed refresh intervals.

Returns:

stats : float

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 should be implemented by subclasses.

Parameters:

output : a file IO-like object or None

open python IO descriptor or None to have one created

format : str

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:

buffer : file 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:

format : str

See get_rgb_image_as_buffer().

quality: int

See get_rgb_image_as_buffer().

Returns:

buffer : bytes

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:

widget : object

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

get_rgb_object(whence=0)

Create and return RGB slices representing the data that should be rendered at the current zoom level and pan settings.

Parameters:

whence : {0, 1, 2, 3}

Optimization flag that reduces the time to create the RGB object by only recalculating what is necessary:

0. New image, pan/scale has changed, or rotation/transform has changed; Recalculate everything
1. Cut levels or similar has changed
2. Color mapping has changed
3. Graphical overlays have changed

Returns:

rgbobj : RGBPlanes

RGB object.

get_rgb_order()

Get RGB order.

Returns:

rgb : str

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:

rgbmap : RGBMapper

RGB map.

get_rotation()

Get image rotation angle.

Returns:

rot_deg : float

Rotation angle in degrees.

get_rotation_info()

Get rotation information.

Returns:

info : tuple

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:

stretchfactors : tuple

Stretch factors for X and Y, in that order.

get_scale_limits()

Get scale limits.

Returns:

scale_limits : tuple

Minimum and maximum scale limits, respectively.

get_scale_max()

Get maximum scale factor.

Returns:

scalefactor : float

Scale factor for X or Y, whichever is larger.

get_scale_min()

Get minimum scale factor.

Returns:

scalefactor : float

Scale factor for X or Y, whichever is smaller.

get_scale_text()

Report current scaling in human-readable format.

Returns:

text : str

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

get_scale_xy()

Get scale factors.

Returns:

scalefactors : tuple

Scale factors for X and Y, in that order.

get_settings()

Get the settings used by this instance.

Returns:

settings : SettingGroup

Settings.

get_transforms()

Get transformations behavior.

Returns:

transforms : tuple

Selected options for flip_x, flip_y, and swap_xy.

get_window_size()

Get the window size in the underlying implementation.

Returns:

size : tuple

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

get_zoom()

Get zoom level.

Returns:

zoomlevel : float

Zoom level.

get_zoom_algorithm()

Get zoom algorithm.

Returns:

name : str

Name of the zoom algorithm in use.

get_zoomrate()

Get zoom rate.

Returns:

zoomrate : float

Zoom rate.

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

Get Numpy data array for display window.

Parameters:

order : str

The desired order of RGB color layers.

alpha : float

Opacity.

dtype : numpy dtype

Numpy data type desired; defaults to rgb mapper setting.

Returns:

outarr : ndarray

Numpy data array for display window.

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

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

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. See ginga.RGBMap.RGBMapper.invert_cmap().

is_compound()

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

Returns:

status : bool

Currently, this always returns False.

is_redraw_pending()

Indicates whether a deferred redraw has been scheduled.

Returns:

pending : bool

True if a deferred redraw is pending, False otherwise.

make_cursor(iconpath, x, y)

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

Parameters:

iconpath : str

the path to a PNG image file defining the cursor

x : int

the X position of the center of the cursor hot spot

y : int

the Y position of the center of the cursor hot spot

make_timer()

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

Returns:timer : a Timer object

offset_to_data(off_x, off_y, center=None)

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

Parameters:

off_x, off_y : float or ndarray

Cartesian canvas coordinates.

Returns:

coord : tuple

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_y : float or ndarray

Data offsets.

Returns:

coord : tuple

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:

text : str

the text to draw in the window

delay : float 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)

redraw : bool

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.

overlay_images(canvas, data, whence=0.0)

Overlay data from any canvas image objects.

Parameters:

canvas : DrawingCanvas

Canvas containing possible images to overlay.

data : ndarray

Output array on which to overlay image data.

whence

See get_rgb_object().

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

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. This should be implemented by subclasses.

Parameters:

data_x : float

the X position to position the cursor in data coords

data_y : float

the X position to position the cursor in data coords

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:

whence

See get_rgb_object().

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

redraw_now(whence=0)

Redraw the displayed image.

Parameters:

whence

See get_rgb_object().

refresh_timer_cb(timer, flags)

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

Parameters:

timer : a Ginga GUI timer

A GUI-based Ginga timer

flags : dict-like

A set of flags controlling the timer

render_image(rgbobj, dst_x, dst_y)

Render image. This must be implemented by subclasses.

Parameters:

rgbobj : RGBPlanes

RGB object.

dst_x, dst_y : float

Offsets in screen coordinates.

reschedule_redraw(time_sec)

Reschedule redraw event. This must be implemented by subclasses.

Parameters:

time_sec : float

Time, in seconds, to wait.

restore_cmap()

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

restore_contrast()

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

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:

deg : float

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:

filepath : str

path of the file to write

format : str

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:

params : dict

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:

filepath : str

path of the file to write

format : str

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_y : float

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

no_reset : bool

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:

method : str

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

params : dict

Algorithm-specific keywords and values.

set_autocuts(autocuts)

Set the auto-cut algorithm.

Parameters:

autocuts : subclass of AutoCutsBase

An object that implements the desired auto-cut algorithm.

set_bg(r, g, b)

Set the background color.

Parameters:

r, g, b : float

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

set_calg(dist)

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

set_canvas(canvas, private_canvas=None)

Set the canvas object.

Parameters:

canvas : DrawingCanvas

Canvas object.

private_canvas : DrawingCanvas 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_name : str

The name of a color distribution algorithm.

kwdargs : dict

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_name : str

The name of a color map.

set_coordmap(key, mapper)

Set coordinate mapper.

Parameters:

key : str

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:

cursor : object

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:

data : ndarray

This should be at least a 2D Numpy array.

metadata : dict or None

Image metadata mapping keywords to their respective values.

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:

tf : bool

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, b : float

RGB values, which should be 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:

image : AstroImage or RGBImage

Image object.

add_to_canvas : bool

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_name : str

The name of an intensity map.

set_limits(limits, coord='data')

Set the bounding box of the viewer extents.

Parameters:

limits : tuple 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:

text : str

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_y : float

Pan positions in X and Y.

coord : {‘data’, ‘wcs’}

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

no_reset : bool

Do not reset autocenter setting.

set_redraw_lag(lag_sec)

Set lag time for redrawing the canvas.

Parameters:

lag_sec : float

Number of seconds to wait.

set_refresh_rate(fps)

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

Parameters:

fps : float

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:

rgbmap : RGBMapper

RGB map.

set_scale(scale, no_reset=False)

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

Parameters:

scale : tuple of float

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

no_reset : bool

Do not reset autozoom setting.

set_scale_base_xy(scale_x_base, scale_y_base)

Set stretch factors.

Parameters:

scale_x_base, scale_y_base : float

Stretch factors for X and Y, respectively.

set_scale_limits(scale_min, scale_max)

Set scale limits.

Parameters:

scale_min, scale_max : float

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:

width : int

The width of the window in pixels.

height : int

The height of the window in pixels.

set_zoom_algorithm(name)

Set zoom algorithm.

Parameters:

name : str

Name of a zoom algorithm to use.

set_zoomrate(zoomrate)

Set zoom rate.

Parameters:

zoomrate : float

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.

switch_cursor(cname)

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

Parameters:

cname : str

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, flipy : bool

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

swapxy : bool

If True, swap the X and Y axes.

transform_cb(setting, value)

Handle callback related to changes in transformations.

update_image()

Update image. This must be implemented by subclasses.

window_has_origin_upper()

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

Returns:

res : bool

Returns True if the origin is up, False otherwise.

window_to_offset(win_x, win_y)

Reverse of offset_to_window().

zoom_fit(no_reset=False)

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

Parameters:

no_reset : bool

Do not reset autozoom setting.

zoom_in(incr=1.0)

Zoom in a level. Also see zoom_to().

Parameters:

incr : float (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:

decr : float (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:

zoomlevel : int

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

no_reset : bool

Do not reset autozoom setting.

zoomsetting_change_cb(setting, value)

Handle callback related to changes in zoom.