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, ses=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. 
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
The command-line options are:
To overplot a contour plot on the draw window:
GPItv->contour, array_name [, options...]
To overplot text on the draw window:
GPItv->xyouts, x, y, text_string [, options]
To overplot points or lines on the current plot:
GPItv->plot, xvector, yvector [, options]
To erases all (or last N) plots and text:
GPItv->erase [, N]
To quit GPItv from the command line, just type
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.
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
GPItv can watch directories in order to automatically show any new fits files coming into those specific chosen directories.
Select “DetectFits” in the File menu, and the ‘FitsGet’ window will appear (Fig.9). The left panel allows the user to browse the file system. One click on a directory will expand it. Double-click on a fits file will display the image in the GPItv main windows. Double-click on a directory will place it on the top-right panel which is the list of current directories where new fits files will be detected.
Add your data repositories in this list. Click the “Search most recent fits files” button to automatically display in the bottom-right panel all fits files contained in the selected directories sorted by creation date from newest to oldest. Every time a new fits file come into these folders, it will appear at the top of this list.
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:
Fig.10 represents a simulated DST/Zemax arc lamp image with wavcal grid overplotted that shows detected position and tilts of spectra.
In addition to the functions described above, GPItv has several useful functions such as
Invert the X-axis or Y-axis of the original image
Rotate image by arbitrary angle
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:
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|
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.
Many other shortcuts exist to bring up windows or change settings. The ‘b’ and ‘n’ buttons to move through datacube slices are particularly useful.
|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|
|r||Show row plot|
|s||Show surface plot|
|t||Show contour 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|
|||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.|