Additional Features

Starting Multiple gpitv sessions

By default, if you already have a GPItv running and you type “GPItv, array_name”, the display comes up in your previously existing GPItv window. If you want more than one display window, you can start multiple sessions of GPItv running simultaneously.

To start an additional session, use:

GPItv, fitsfile_name, session=num

where ‘fitsfile_name’ is a string containing the name of the FITS file (including extension and directory if needed) to be read and ‘num’ is an integer that defines an integer ID for the gpitv window to be used. For example,

GPItv, 'test.fits', ses=0

will display ‘test.fits’ in session #0. You can launch arbitrarily additional copies by changing the value of the ‘ses’ keyword. For instance,

GPItv, 'test2.fits', ses=7

will display ‘test2.fits’ in an other Gpitv viewer (#7), so you will have two GPItv viewers opened. Each window will be identified by a unique ID number, shown in the title bar of the window (and also of any child windows or dialogs that are opened from that particular GPItv). You can open as many different sessions as you want. [1]

Once a session is running, you can change the image displayed or adjust scaling or other display parameters with additional calls using the same session number.

GPItv, 'test3.fits', ses=0, /log, min=0, max=1000

Optional Input Keywords

The command-line options are:

  • [,/alignp]: preserves the current display center and zoom when reading in a new image.
  • [,/alignwav]: for data-cubes, keep the same slice number to be displayed.
  • [,header=header]: use this to enter the FITS header corresponding to an image array. The FITS header is a string array.
  • [,min = min_value]: sets the minimum array value to be mapped into the color table. (can be modified interactively)
  • [,max=max_value]: sets the maximum array value to be mapped into the color table. (can be modified interactively)
  • [,/autoscale]: tells GPItv to set min and max automatically to -2 and +10 sigmas about the image median. Setting autoscale overrides min and max. GPItv will autoscale by default, so it’s not necessary to include this keyword unless you’ve turned off default autoscaling.
  • [,/linear]: maps data values to the color table linearly
  • [,/log]: maps the log of data values into the color table
  • [,/histeq]: histogram-equalizes the image into the color table. (good for images with a large dynamic range)
  • [,/stretch]: preserves the current min/max values when reading in a new image
  • [,/block]: starts ATV as a blocking widget, which can occasionally be useful

The coordinate system

Raw 2D images coming from the GPI IFS will not contain WCS information because spatial and spectral domains are mixed. However, the GPI data pipeline delivers datacubes with WCS information. If the image header has a valid world coordinate system (WCS), then GPItv will display the coordinates of the cursor position. By default, it uses the native coordinate system and equinox given in the image header. GPItv can also convert the native coordinates into J2000, B1950, ecliptic, or galactic coordinates. To change the output to a different system, go to the ImageInfo menu and select one of the coordinate options.

If the WCS information describes the 3rd dimension of a datacube in either spectral or polarimetric format, this information will be displayed as you scan through the datacube. For this to work, GPItv requires FITS keywords compliant with the WCS standard as defined in the papers by Griesen & Calabretta, et al.

Image statistics

The statistics window (Fig.6) shows the min, max, mean, median, number of NaNs, for a box centered on the cursor position in addition to the image min and max value.

To bring up the image statistics window, hit “i”, or set the mouse mode to “Stat” and use left button of the mouse, or select it in the ImageInfo menu.

You can change the box center or the box size by entering new numbers in the input boxes. To see a zoomed-in view of the stats region, click on “Show Region”.

Figure 9: Example of basic statistical information given by the Stat/ImExam3d modes, such as mean value, median, std dev, number of Nan.

To display all statistics for a multi-plane datacube (Fig.7), set the mouse mode to “Stat/ImExam3D” and use right button of the mouse to select a region in the image (select arbitrary box with two clicks, defining the corners).

Figure 10: Example of image statistics for a multi-plane datacube

Blinking images

GPItv easily allows you to blink images, as follows. Load in the first image, and get the display exactly how you want it. Then, go to the Blink menu and select “Set Blink1”. Then load in the second image and set the mouse mode to “Blink”. Now, with the cursor in the main draw window, just hold down the first mouse button to display the first image, and release the button to show the current image.

You can save up to 3 blink images and blink them with mouse buttons 1, 2, or 3. If you have fewer than 3 mouse buttons, you won’t be able to use all 3 blink images.

Displaying GPI Wavelength Calibration grids

GPI raw 2D image contains both spatial and spectral information. The wavcal grid allows the GPI pipeline to extract a 3D datacube from a GPI image. The wavcal grid contains positions of spectra in the image at a specific wavelength, tilts of spectra, and coefficients which give the dispersion law of each spectrum in the image. The wavcal grid is obtained with calibration narrow-band data, such as Xe arc lamp.

To select a wavcal grid to overplot, choose the wavcal file with ‘Select Wavcal grid’ in the ‘Labels’ menu, then select ‘Plot wavcal grid’ in the same menu.

The GPI wavcal grid can be overplotted on 2D image in order to check out:

  • proper calculation of the wavcal grid during engineering measurement
  • spatial shifts of micro-lens PSF positions in the image for spectroscopic or polarimetric scientific images since the last wavcal solution measurement.

Other functions

In addition to the functions described above, GPItv has several useful functions such as

Measure distance:
Measure distance with the mouse
Write out a new fits image to disk (single-plane or entire image)
Write a PostScript file of the current display
Write a JPEG, TIFF, BMP, PICT, or PNG image of the current display
Save to IDL variable:
Save current image or cube as an IDL variable
Save/Load Region :
Save or load currently displayed regions to a SAOImage/DS9 region file with .reg format

Invert the X-axis or Y-axis of the original image

Rotate image by arbitrary angle

Datacube Default Scaling Mode Droplist

When a 3D datacube is opened and you change the plane displayed, the min and max for the display scaling of the new plane can be controlled by the following options:

Keep Min/Max values the same for each image plane
Set display Min/Max to [-2 sigma, +10 sigma] for the new plane
Set display Min/Max to Min/Max of the displayed plane

Mouse modes in display window

The effect of clicking any of the mouse buttons depends on the ‘Mouse Mode’ drop-down list setting.

Mouse Mode Left Click Middle Click Right Click
Recenter/Color Recenter Adjust color stretch Adjust color stretch
Zoom Zoom in Recenter Zoom out
Blink Show blink image #1 Show blink image #2 Show blink image #3
Statistics 2D/3D Show 2D Statistics Show 3D Statistics Show 3D Statistics
Vector Plot vector cut across the image.
Measure Distance Measure distance between two points
Photometry Aperture Photometry Recenter Plot Angular Profile
Spectrum Plot Spectral plot using aperture photometry around selected pixel Spectral plot of selected pixel
Draw Region Draw Region
Row/Column Plot Draw plot of current row in image Draw plot of current column in image
Gauss Row/Column Plot Fit Gaussian to local region of current row in image Fit Gaussian to local region of current column in image
Histogram/Contour Plot Plot histogram of region around cursor   Draw contour plot of region around cursor
Surface Plot Draw surface plot of region around cursor    
Move Wavecal Grid Reposition the wavecal grid with some integer pixel offset    

Keyboard shortcut commands in display window

Arrow keys move the cursor around the main image window. The numeric keypad (with NUM LOCK on) will also work, and allows motion along diagonals too.

Key Action
1 Down-Left
2 Down
3 Down-Right
4 Left
6 Right
7 Up-Left
8 Up
9 Up-Right

Many other shortcuts exist to bring up windows or change settings. The ‘b’ and ‘n’ buttons to move through datacube slices are particularly useful.

Key Action
b Change slice number, previous (“back”)
n Change slice number, next
a Change image display min/max to Auto-Scale -2/+5 sigma
g Show region plot
h Show histogram plot of pixels around current cursor position
c Show column plot
i Show image statistics at current position
j Show 1D Gaussian fit to image rows around current cursor position, +- 10 pixels
k Show 1D Gaussian fit to image columns around current cursor position, +- 10 pixels
l Plot pixel value vs wavelength, for 3D images (“l” for “lambda”)
m Change mouse mode (cycles through list of modes, one mode at a time.)
p Do aperture photometry at current position
q Quit GPItv
r Show row plot
s Show surface plot
t Show contour plot
y Recenter plot
z Show pixel table
E Erase anything drawn in main window
M Change image display min/max to image min/max
R Rotate image by arbitrary angle
- Zoom out
+ Zoom in

Displaying the state of GPI during some FITS file

If you have the gpidiagram display utility available in your $PATH, then gpitv can launch a gpidiagram display to show the state of most important mechanisms in GPI at the time that file was taken (based on the state information in the FITS header).

Note that this requires you have gpidiagram in your $PATH directly, not an alias, or else gpitv won’t be able to find it.


[1]There is no inherent IDL limitation on how many GPItv viewers can be displayed, apart from your available computer memory. However, currently the max number of sessions is limited to 100, due to the size of a pointer array used internally for bookkeeping. It seems unlikely for anyone to want >100 concurrent sessions, but if you do, this can be enabled with a trivial code change.