TV module

Introduction

tv is a module that provide an enhanced image display tool built on top of the basic functionality of a matplotlib figure. The tv tool is an object that displays images and also allows the user to get input from the display.

It can take as input either a numpy array, an pyvista Data/astropy NDData/CCDData or a FITS HDU object (e.g., from astropy.io.fits), and will display it in the window. Pixel and value readout is provided. For FITS input, WCS as well as pixel locations are given, as is the OBJECT information. Two plot windows are created for use with some built-in functions (row and column plots, radial profiles).

While normal matplotlib options/buttons (zoom/pan) are available, the tool includes an event handler that by default responds to mouse clicks in the image display section, so it can be confusing to use the matplotlib tools here. The event handler in the main display window can be toggled on/off using the ‘z’ key, if users prefer to use the matplotlib buttons.

Several keys are defined to do asynchronous interaction with the data in the display, see below. In particular, four images are stored internally, allowing for rapid cycling (blinking) between them using the ‘-’ and ‘+/=’ keys.

A tvmark() method is provided to allow the user to retrieve the location of a keystroke event in the window along with the key that was pressed.

An imexam() method allows for interactive measurement of objects in the image.

tvbox() and tvcirc() allow the user to overlay graphics.

Usage

The tv module is part of pyvista, and defines a TV object. To load it:

from pyvista import tv

If the pyautogui package is available it will be loaded: this functionality is required for interactive functions that move the cursor. Note that for some versions of MacOSX, the controlling application needs to be given permission to access the mouse.

A display tool is created when a pyvista TV object is instantiated, e.g.

display = tv.TV()

In this way, multiple displays can be used if desired.

Once the TV object is created, images are displayed using the tv() function, e.g.

display.tv(image)

where image is one of the input data types. By default, the image is displayed using greyscale (colormap “Greys_r”) with an automatically determined stretch; however, the display scaling can be set explicitly using the min= and max= keywords, and the cmap= keyword can be used to specify a different colormap. If the input data type is an pyvista Data/astropy NDData/CCDData object, then the sn= keyword can be used to display the S/N image (data extension divided by uncertainty dimension).

Given a TV object with image data loaded, various asynchronous functions are available in the main display window:

left mouse

zoom in, centered on cursor

center mouse

zoom out, centered on cursor

right mouse

pan, center to cursor

z

toggle use of mouse clicks in main display, e.g. if users prefer to use matplotlib button

r

redraw at default zoom

+/=

toggle to next image in stack

-

toggle to previous image in stack

arrow keys

move single image pixels (with pyautogui)

a

toggle axes on/off

h/?

print this help

Several synchronous (waits for input) methods are also available:

imexam(size=11,fwhm=5,scale=1,pafixed=False) :

draws radial profiles and fits Gaussian around cursor position when key is hit

tvmark() :

returns (x,y,key) when a key is hit at (data) position (x,y)

clear() :

clears the display

tvbox(x,y,box=None,size=3,color=’m’) :

displays square of specified size at input position (or pyvista box object) with specified color

tvcirc(x,y,rad=3,color=’m’) :

displays circle of specified size and color at input position

tvclear() :

clears graphics patches from display

flip() :

toggles vertical flip of displays (default starts with origin in lower left)

Module functions

class pyvista.tv.TV(figsize=(12, 8.5), aspect='equal', clickzoom=True, flipx=False, flipy=False, nroll=4)

A “TV” figure

Usage: import tv

tv=TV() to set up a new TV object (display window)

clear()

Clear image

flip()

toggle display x flip

flipy()

toggle display y flip

imexam(x=None, y=None, size=11, fwhm=5, scale=1, pafixed=False, ret=False)

Fit gaussian and show radial profile of stars marked interactively

savefig(name)

hardcopy of only display Axes

tv(img, min=None, max=None, same=False, cmap=None, sn=False, object=None, draw=True)

main display routine: displays image with optional scaling

Parameters

• img – pyvista Data object, numpy array, or fits HDU

• min= – optional scaling arguments

• max= – optional scaling arguments

• same= – bool, if True use display scaling from previous image

• cmap= – specify different color map

tvbox(x=0, y=0, box=None, size=3, color='m', ls=None, lw=None)

displays a patch (box by default) on an image

Parameters

• x – center position of patch

• y – center position of patch

Keyword args :

size= : patch size color= : patch color

tvcirc(x, y, rad=3, color='m', ls=None, lw=None)

displays a circle on an image

Parameters

• x – center position of patch

• y – center position of patch

Keyword args :

size= : patch size color= : patch color

tvclear()

clears patches from image

tvmark()

Blocking input: waits for key press in display and returns key that was pressed and data pixel location of the keypress

Parameters

none –

Returns

key pressed, x data position, y data position

tvtext(x, y, text, color='m', ha='center', va='center')

Annotates with text