# Welcome to Xguiphot

Xguiphot is a new IRAF multi-aperture photometry tool for measuring the brightness of astronomical objects. In interactive mode Xguiphot communicates with the user through a graphical user interface. In non-interactive mode Xguiphot can be driven by an existing object list or by an object list generated automatically at run-time. The Xguiphot GUI is based on the same widget server technology, object manager library, and messaging facilities employed by the IRAF XGterm graphics terminal emulator and XImtool display server. Xguiphot is an extension of an earlier and much simpler prototype written to aid development of the IRAF GUI facilities.

The new scientific capabilities and GUI facilities are summarized in the Introduction section. Detailed help on various topics can be found by searching the Table of Contents.

Xguiphot is still under development. If you have comments, bug reports, or specific suggestions for improvement please contact the author at davis@noao.edu or the iraf help desk at iraf@noao.edu.

# Table of Contents

1. Introduction to Xguiphot
2. Xguiphot System Requirements
3. Before Starting Xguiphot
4. Xguiphot Basics

1. Loading the Xapphot Package
2. On-Line Help
3. Editing the Xguiphot Parameters
4. The Input Images
5. The Input Objects Files
6. The Output Results Files
7. The Output Objects Files
8. Output Results File Logging
9. The Xguiphot Parameter Sets
10. Editing the Xguiphot Parameter Sets
11. Updating the Xguiphot Parameter Sets
12. Interactive Mode
13. The GUI File
14. Non-Interactive Mode

5. The Xguiphot Parameter Sets

1. The Impars Parameter Set
2. The Dispars Parameter Set
3. The Findpars Parameter Set
4. The Omarkpars Parameter Set
5. The Cenpars Parameter Set
6. The Skypars Parameter Set
7. The Photpars Parameter Set
8. The Cplotpars Parameter Set
9. The Splotpars Parameter Set

6. Running Xguiphot with the GUI

1. Starting Xguiphot
2. Quitting Xguiphot
3. Getting On-Line Help
4. Dealing with Directories
5. Dealing with Images

1. Setting the Image Directory
2. Setting the Image Template
3. Browsing the Image List
4. Browsing the Image Headers
5. Interacting with the Image Display
6. Setting the Dispars Parameters
7. Estimating the Hwhm of the Psf
8. Setting the Impars Parameters

6. Dealing with Objects Files

1. Setting the Objects File Directory
2. Setting the Objects File Template
3. Browsing the Objects File List

7. Dealing with Object Lists

1. Creating Objects Lists From Objects Files
2. Creating Objects Lists Automatically
3. Setting the Findpars Parameters
4. Creating Objects Lists with the Image Cursor
5. Creating Objects Lists with the Photometry Marker
6. Viewing the Objects List
7. Setting the Omarkpars Parameters
8. Browsing the Objects List
9. Deleting and Undeleting Objects from the Objects List
10. Adding Objects to the Objects List
11. Saving the Objects List

8. Dealing with Results Files

1. Setting the Results File Directory
2. Setting the Results File Template
3. Logging the Results

9. Doing Photometry

1. Setting the Impars Parameters
2. Setting the Cenpars Parameters
3. Setting the Skypars Parameters
4. Setting the Photpars Parameters
5. Measuring Objects with the Image Cursor
6. Measuring Objects Through the Photometry Marker
7. Detecting and Measuring Objects Automatically
8. Measuring Objects in the Objects List
9. Measuring Objects Through the Object List Marker

10. Viewing the Results

1. The Status Line
2. The Graphics Overlay
3. The Quick-Look Photometry Table
4. The Quick-Look Photometry Plots

7. The Xguiphot Default GUI

1. The Xguiphot Control Panel
2. The Main Menus and Commands

1. The Files Menu
2. The Images Menu
3. The Lists Menu
4. The Edit Menu
5. The Phot Menu
6. The Results Menu
7. The Psets Menu
8. The Help Command
9. The Quit Command

3. The Image Display Window

1. The Files Marker
2. The Coordinates Marker
3. The Status Line
4. The Image Display Cursor
5. The Image Display Menu
6. The Xguiphot Keystroke Commands
7. The Cursor Mode Keystroke Commands
8. The Xguiphot Colon Commands
9. The Cursor Mode Colon Commands
10. The Object List Marker
11. The Photometry Marker

4. The Control Panels

1. The Help Panel
2. The Files Panel
3. The Image Header Panel
4. The Pset Editing Panel
5. The Model Fitting Panel
6. The Object List Panel
7. The Photometry Table Panel
8. The Photometry Plots Panel

8. Appendices

1. The Objects File Format
2. The Moment Analysis Computation
3. The Magnitude Computation
4. The Magnitude Error Computation
5. Limitations of the Current GUI

# Introduction to Xguiphot

Xguiphot is a new IRAF task for doing multi-aperture moment analysis and fractional pixel aperture photometry through circular, elliptical, rectangular, or polygonal object apertures, and sky analysis through annular or offset circular, elliptical, rectangular, or polygonal sky apertures.

In interactive mode a GUI provides facilities for: selecting and displaying images and object files; creating, viewing and editing object lists; setting, reviewing, editing and saving parameter sets; selecting objects to measure from the image display or the object list using the image cursor, and / or object markers; displaying the results in both text table and graphical form; and browsing the on-line documentation. In non-interactive mode Xguiphot can be driven from an existing object file or from an object list generated at runtime.

# Xguiphot System Requirements

Xguiphot is currently installed in the external add-on package Xapphot. To run Xguiphot you must have IRAF version 2.11.?, X11IRAF version ?.?, and the external add-on package Xapphot, installed on your system.

# Before Running Xguiphot

Before starting Xguiphot users should ask themselves the following questions and take appropriate action if the answers are unsatisfactory.

Have the images to be analyzed been correctly reduced ?
  Problems with flat-fielding, variable pixel scales, etc. can impact Xguiphot photometry. Tasks in the IRAF ccdred package can be used to do the CCD reductions.

Are the effective gain and readout noise of the images known ?
  Have the gain and readout noise been corrected to reflect any image combining, scaling, etc. operations ? Are the gain and readout noise present and correct in the image headers ? Xguiphot uses the effective gain and readout noise to estimate the magnitude errors.

Are the effective exposure times of the images known ?
  Have these been corrected for shutter errors ? for the effect of any image combining operations ? Are the effective exposure times present and correct in the image headers ? Are the exposure times all in the same units ? Xguiphot uses the exposure times to normalize the computed magnitudes.

Are the effective airmass, filter, and time of observation of the images known ?
  Has the airmass and time of observation been corrected to mid-exposure ? Are these quantities present and correct in the image headers ?

The IRAF hselect, hedit, and setairmass tasks can be used to view the current image headers, edit in any missing information, and correct erroneous information.

For more information on issues that may affect the accuracy of the photometry Consult the Data Requirements section of the IRAF xguiphot help page.

# Xguiphot Basics

## Loading the Xapphot Package

The Xguiphot task is located in the external add-on package Xapphot. The Xapphot package must be loaded before the Xguiphot task can be run. To load the Xapphot package type the package name as shown below.

    cl> xapphot

Xguiphot is the only compiled task in the xapphot package. The remaining tasks are parameter set tasks.

## On-Line Help

On-line help for all the Xapphot tasks is available via the usual builtin IRAF help facilities as shown below. These help pages contain information not available in the on-line GUI documentation. To obtain a one line description of each Xapphot task type help followed by the package name as shown below.

    xa> help xapphot

To view the help page for a particular task on the terminal type phelp followed by the task name as shown below.

    xa> phelp xguiphot

Help text, in this case the xguiphot tutorial, can also be piped to the local printer as shown below

    xa> help xgtutor1 | lprint
    xa> help xgtutor2 | lprint

The on-line GUI documentation can be found in the HTML document xapphot$doc/xguiphot.html. This document can be viewed and printed with any standard web browser.

## Editing the Xguiphot Parameters

The Xguiphot task parameters specifying the input and output file names, the parameter sets, and the task mode of operation can be edited before GUI startup using the standard IRAF parameter editing utilities. To edit the Xguiphot task parameters type epar followed by the task name as shown below.

    xa> epar xguiphot

To edit an Xguiphot parameter move the cursor to the line specifying the desired parameter name, enter the new value followed by a carriage return. When editing is complete type ":wq" to exit the epar task and update the parameters. Techniques for editing the impars, dispars, findpars, omarkpars, cenpars, skypars, photpars, cplotpars, and splotpars parameter set parameters are described in the Editing the Xguiphot Parameter Sets section.

## The Input Images

The Xguiphot images parameter specifies the input images to be analyzed. Images may be a null list, e.g. "", a single image, e.g. "m51", a list of images, e.g. "m51b,m51v,m51r", an image template, e.g. "m51*", or an image list, e.g. "@imlist" where imlist is a file containing a list of images one image per line as shown below.

    xa> type imlist
    m51b
    m51v
    m51r

The default value of images is "*" which will select all images of any type in the current directory. Images may include a directory specification, e.g. "may31/*" or "mydata$*.fits", where mydata$ is an IRAF environment variable defined by the user specifying the desired path name.

The root image name, i.e. the image name stripped of directory and section information, is used to set up the default input object and output results file naming conventions. For example the root image name for the image file /u2/davis/m51b.imh[200:400,200:400] is "m51b.imh" so by default Xguiphot will search for an objects file called "m51b.imh.obj.#" and create an output file called "m51b.imh.mag.#" where "#" is latest and next available version number respectively.

Xguiphot can analyze images in multi-extension files, e.g. m51b.fits[3] specifies the image in the third extension of the FITS file m51b.fits and m51b.hhh[2/4] specifies the second image in the four image GEIS file m51b.hhh. In the latter two cases the root image names are "m51b.fits3" and "m51b.hhh2" respectively. The square brackets around the extension numbers are removed to avoid problems with special characters in file names.

In general users should try and keep their image names as short as possible. Although this is not always convenient they should also, if possible, avoid appending the ".imh", ".hhh", or ".fits" extensions to their input image names, as these extensions automatically become part of the default input and output file names.

## The Input Objects Files

The Xguiphot objects parameter specifies the input objects files. Objects may be a null list, e.g. "", a single file, e.g. "m51xy", a list of files, e.g. "m51bxy,m51vxy,m51rxy", a file template, e.g. "m51*xy", or an object file list, e.g. "@objlist" where objlist is a file containing a list of objects files one file per line as shown below.

    xa> type objlist
    m51bxy
    m51vxy
    m51rxy

By default Xguiphot attempts to match the input images and objects files one to one. If the number of objects files is greater than zero but less than the number of images then the last objects file will be used for all the "extra" images. In interactive mode the user can override the default image and object file matching behavior.

Xguiphot supports a default input file name convention. If objects is "default", then for each image Xguiphot searches for a file called "root.obj.version", where root is the root image name described above, "obj" is extension identifying the file as an objects file, and version is the latest version, e.g. "m51b.obj.2" or "m51b.fits.obj.3".

The simplest object file is a text file containing the x and y coordinates of the objects to be measured, one object per line with the x and y coordinates in columns one and two respectively. A portion of a simple object file is shown below.

    xa> type objfile
      31.23    80.61
     102.42   305.73
     518.11  1021.89

Xguiphot also supports a more complex objects file format capable of describing circular, elliptical, rectangular, and polygonal object and sky apertures, and either concentric or offset sky apertures. Detailed information about the object file format can be found in the Objects File Format section of the appendices. A portion of a more complex objects file is shown below.

    507.000 445.000
    442.482 409.575 circle 9.59 ; circle 17.10 23.69
    266.589 60.769 ellipse 18.69 0.4706 0.0 ; ellipse 24.91 31.56 0.4706 0.0
    258.633 259.180 ellipse 65.06 0.8243 29.465 ; 442.482 460.780  rectangle 0.00 47
    .14 0.6940 3.877

If the object or sky geometry is absent or undefined, i.e. equal to INDEF in the input objects file, then the default object and sky geometries are defined by the default values in the photpars and skypars parameter sets.

## The Output Results Files

The Xguiphot results parameter specifies the output results files. Results may be a null list, e.g. "", a single file, e.g. "m51mag", a list of files, e.g. "m51bmag,m51vmag,m51mag", a file template, e.g. "m51*mag", or a file list, e.g. "@maglist" where maglist is a file containing a list of results files one file per line as shown below.

    cl> type maglist
    m51bmag
    m51vmag
    m51rmag

By default Xguiphot attempts to match the input images and results files one to one. If the number of results files is greater than zero but less than the number of images then the last results file will contain the results for all the "extra" images in addition to the results for the one it matches. In interactive mode the user can override the default image and results file matching behavior.

Xguiphot supports a default output file name convention. If results is "default", then for each input image, Xguiphot creates a file called "root.mag.version", where root is the root image name described above, "mag" is an extension identifying the file as a results file, and version is the next available version number, e.g. "m51b.mag.1" or "m51b.fits.mag.2".

## The Output Objects Files

The Xguiphot robjects parameter specifies the output objects files. The output objects files contain the object description for each object whose photometry was written to the results files. Writing to the output objects files is currently disabled. User should leave the robjects parameter set to "".

## Output Results File Logging

In non-interactive mode results logging is always enabled although the user can disable it by setting the results parameter to "". In interactive mode results logging is disabled by default. The user must explicitly set the logresults parameter to "yes" to enable logging. This allows the user time set the parameters and make a few experimental measurements before beginning serious work.

## The Xguiphot Parameter Sets

The Xguiphot parameters have been grouped together into 9 parameter sets: impars, dispars, findpars, omarkpars, cenpars, skypars, photpars, cplotpars, and splotpars. Five of these parameter sets impars, findpars, cenpars, skypars, and photpars control the Xguiphot science algorithm parameters. Impars defines the image data dependent parameters such as hwhmpsf, the half-width at half-maximum of the PSF, imindata and imaxdata, the good data limits, igain and ireadnoise, the gain and readout noise of the detector, and ietime the exposure time. Findpars defines the automatic object detection algorithm parameters such as the detection threshold fthreshold and the minimum separation fsepmin. The object centering, sky fitting, and photometry algorithms are defined by the cenpars, skypars, and photpars parameter sets respectively. Two parameters sets dispars and omarkpars control the image display and object list marking algorithms respectively. Two additional parameters sets cplotpars and splotpars control the object and sky region display algorithms respectively.

## Editing the Xguiphot Parameter Sets

The Xguiphot parameter sets can be edited before GUI startup in the same manner as the Xguiphot task level parameters. To edit a parameter set type epar followed by the parameter set name or type the parameter set name, and edit the impars parameters in the usual way as shown below.

    xa> epar impars

    xa> impars

Parameter sets can also be edited from within the main task editor. To edit the impars parameter set while editing the Xguiphot task parameters type "epar xguiphot". Move the cursor to the impars line and type ":e". The menu for impars will appear ready for editing. Edit the parameters and type ":wq" to quit and update the impars parameters. Epar will return to the Xguiphot parameter menu after which other parameter sets or task parameters can be edited.

## Updating the Xguiphot Parameter Sets

By default Xguiphot does not update the default parameter set files in the users uparm$ directory when it terminates. Users who wish to automatically update their pset files on task termination should set the update parameter to "yes". If update is "no", it is still possible to force parameters set updates in interactive mode. However users should be aware that if update = "yes" previous internal updates may be overwritten at task termination.

## Interactive Mode

In interactive mode the user can issue instructions to the Xguiphot task as it is running. If the guifile parameter is defined then these instructions will be in the form of:

- mouse button clicks
- text entry
- task specific keystroke commands
- task specific colon commands
- IRAF cursor mode keystroke commands
- IRAF cursor mode colon commands

For example in order to redisplay the current image with a log10 instead of a linear transformation using the GUI, the user would

- press the Images menu button
- select the "Dispars pset ..." item
- move to the ztransform entry box in the Dispars panel
- press the left mouse button to bring up the ztransform menu
- select the "log" item
- press the Apply button
- press the Display button to redisplay the image

Users familiar with the equivalent task specific keystroke and colon commands could accomplish the same task by typing ":ztransform log" CR command followed by an "i" keystroke command in the image display window.

If the guifile is undefined the user can still run Xguiphot interactively. However only keystroke and colon commands will be available, only a single graphics window will be available for displaying the image, the object and sky regions, and the results, and certain functions like windowing the image display will be unavailable. This mode of running Xguiphot is not discussed in this document. More information about it can be found in the regular Xguiphot help page.

## The GUI File

The default GUI file is a text file which describes the widget tree hierarchy and specifies its layout and appearance on the screen, defines the procedures to be executed when the user interacts with the GUI, and defines the GUI parameters and call-backs through which the client Xguiphot task sends messages to the GUI.

Since the GUI file is a text file which is read at runtime, an individual user or site can customize the GUI to local taste. The default GUI is stored in the file "xapphot$gui/xguiphot.gui".

## Non-interactive Mode

In non-interactive mode Xguiphot reads the input images and objects files, reads the default parameter set files, performs the analysis, and writes the output files without any interaction with the user. If the user does not specify the input objects files then the automatic object detection algorithm generates the input object list. This mode of running Xguiphot is not discussed further in this document. More information about it can be found in the regular Xguiphot help page.

# The Xguiphot Parameter Sets

The nine Xguiphot parameter sets: impars, dispars, findpars, omarkpars, cenpars, skypars, photpars, splotpars, and cplotpars are described below in the order they appear in the Xguiphot task parameter file. This order corresponds to the order in which a user normally encounters and edits them in a typical interactive Xguiphot session.

## The Impars Parameter Set

The impars parameters define the image data dependent parameters. Impars parameters are functions of the telescope and instrument optics, the detector noise and linearity range, and the observing conditions. Impars should be checked and edited before any photometric measurements are made.

iscale = 1.0 (units per pixel)
  The scale of the image e.g. 0.46 arc-seconds per pixel. Most Xguiphot length parameters are defined in units of iscale, pixels if iscale = 1.0, arc-seconds etc. otherwise. Xguiphot users should leave iscale set to 1.0 unless they need to compare their aperture photometry directly with results in the literature.

ihwhmpsf = 1.0 (scale units)
  The half-width at half-maximum of the PSF in scale units, e.g. 2.0 pixels or 0.92 arc-seconds if iscale = 0.46 arc-seconds per pixel. Xguiphot users should set ihwhmpsf accurately in order to optimize the performance of the object detection algorithm and the "gauss1d" and "ofilter1d" centering algorithms.

iemission = yes
  Are the objects to be measured emission objects, iemission = "yes", or absorption objects, iemission = no ? Most Xguiphot users should leave iemission set to "yes".

iskysigma = INDEF (ADU)
  The default standard deviation of the sky pixels in ADU. Users should set iskysigma to a realistic value if they plan to set the centering algorithm cthreshold parameter or use the sky fitting algorithms "zero" or "constant".

imindata = INDEF (ADU)
  The minimum good pixel value. Xguiphot users should set this parameter if they wish, to remove low bad data from the object detection analysis, to remove low bad data from the sky analysis, or if they wish to flag objects with low bad data in the centering and photometry apertures. To avoid biasing the sky estimates Xguiphot users should exercise care in setting imindata for image sets with varying average background levels.

imaxdata = INDEF (ADU)
  The maximum good pixel value. Xguiphot users should set this parameter if they wish, to remove high bad data from the object detection analysis, to remove high bad data from the sky pixel analysis, or to flag saturated objects or objects with high bad data in their centering and photometry apertures.

inoisemodel = "poisson"
  The noise model used to estimate the the Xguiphot magnitude errors. Currently the only option is:
  poisson
    Poisson statistics in the object and the sky background as well as readout noise are used to estimate the error in the object magnitude measurement.
  Xguiphot users should be aware that the parameters ikgain or igain and ikreadnoise or ireadnoise must be correctly set in order to compute the valid magnitude error estimates.

ikgain = "GAIN"
  The image header keyword defining the gain value whose units are assumed to be electrons per ADU. If ikgain is undefined or does not exist then the gain defaults to the value of igain.

ikreadnoise = "RDNOISE"
  The image header keyword defining the readout noise value whose units are assumed to be electrons. If ikreadnoise is undefined or does not exist the readout noise defaults to the value of ireadnoise.

igain = 1.0
  The default gain in electrons per ADU if ikgain does not exist. Xguiphot users should set the ikgain or igain parameter before making measurements in order to insure that the magnitude error estimates are valid.

ireadnoise = 0.0
  The default readout noise in electrons if ikreadnoise does not exist. Xguiphot users should set ikreadnoise or ireadnoise before making measurements in order to insure that the magnitude error estimates are valid.

ikexptime = "EXPTIME"
  The image header exposure time keyword. The time units are arbitrary but must be consistent for any list of images whose magnitudes are to be compared. The computed magnitudes are normalized to 1 timeunit. Xguiphot users should set this parameter in order to normalize the magnitude scale and simplify future reduction steps. If ikexptime is undefined or does not exist the exposure defaults to the value of ietime.

ikairmass = "AIRMASS"
  The image header airmass keyword. This parameter does not affect the Xguiphot computations in any way, but the airmass values stored in the output files can simplify future reductions steps. If ikairmass is undefined or does not exist the exposure defaults to the value of iairmass.

ikfilter = "FILTERS"
  The image header filter id keyword. This parameter does not affect the Xguiphot computations in any way, but the filter id values stored in the output files can simplify future reductions steps. If ikfilter is undefined or does not exist the exposure defaults to the value of ifilter.

ikobstime = "UT"
  The image header time of observation keyword. This parameter does not affect the computations in any way, but the time of observation values stored in the output files can simplify future reductions steps. If ikobstime is undefined or does not exist the exposure defaults to the value of iobstime.

ietime = 1.0
  The default exposure time for the image in arbitrary units if ikexptime does not exist. The computed magnitudes are normalized to 1 timeunit.

xairmass = INDEF
  The default value of the airmass if ikairmass is undefined.

ifilter = "INDEF"
  The default value of the filter id string if ikfilter is undefined.

iotime = "INDEF"
  The default value of the time of observation string if ikitime is undefined.

## The Dispars Parameter Set

The dispars parameters control the Xguiphot image display algorithms. These parameters are used to map the image to the display window in both position and intensity. The current image display algorithms are based on but not identical to the algorithms used by the IRAF display task.

derase = yes
  Erase the screen before displaying the image ?

dfill = yes
  Interpolate the image to fit the display window ?

dxviewport = 1.0, dyviewport = 1.0
  The horizontal and vertical sizes of the display window in viewport or normalized coordinates.

xmag = 1.0, ymag = 1.0
  The horizontal and vertical image magnifications used when dfill = "no". Magnifications greater than 1 map image pixels into more than 1 display pixel and magnifications less than 1 map more than 1 image pixel into a display pixel.

dztransform = "linear"
  The algorithm used to transform the image intensity levels to the display levels. The choices are:

  "linear"
    Map the minimum and maximum image intensities linearly to the minimum and maximum display levels.

  "log"
    Map the minimum and maximum image intensities linearly to the range 1 to 1000, take the logarithm (base 10), and then map the logarithms to the display range.

  "none"
    Apply no mapping of the image intensities. For most image displays, values exceeding the maximum display value are truncated by masking the highest bits. This corresponds to applying a modulus operation to the intensity values and produces "wrap-around" in the display levels.

  "user"
    Use the look-up table of image intensities and corresponding display intensities in the file specified by dlutfile.

dzlimits = "median"
  The algorithm used to determine the minimum and maximum image intensities to map to the minimum and maximum display intensities. The choices are:

  "median"
    Compute the image intensity limits using an automatic mapping algorithm and the parameters dznsample and dzcontrast.

  "image"
    Use the minimum and maximum values in the image header or by subsampling the entire image.

  "user"
    Use the values dz1 and dz2 supplied by the user. If dz1 and dz2 are INDEF then dzlimits defaults to the "median" algorithm.

dzcontrast = 0.25
  The contrast factor for the dzlimits = "median" algorithm. If a value of zero is given then the minimum and maximum of the intensity sample is used.

dznsample = 5
  The number of sample lines for the dzlimits = "median" algorithm.

dz1 = INDEF (ADU), z2 = INDEF (ADU)
  The minimum and maximum image intensity to be mapped to the minimum and maximum display levels if dzlimits = "user".

dlutfile = ""
  The name of the text file containing the look-up table for the dztransform = "user" algorithm. The table should contain two columns per line; column 1 contains the intensity, column 2 the desired greyscale output.

drepeat = no
  Use the previous intensity transformation if defined ?

## The Findpars Parameter Set

The findpars parameters along with the impars parameters ihwhmpsf, imindata, and imaxfata control the Xguiphot object detection algorithm. The current algorithm is optimized for detecting stellar objects.

fthreshold = 320 (ADU)
  The detection threshold above local background in ADU.

fradius = 2.5 (ihwhmpsf)
  The fitting radius in units of ihwhmpsf. Fradius defines the size of the Gaussian kernel used to compute the density enhancement image, and the size of the image region used to compute the roundness and sharpness statistics.

fsepmin = 1.0 (ihwhmpsf)
  The minimum separation for detected objects in units of ihwhmpsf.

fnpixmin = 5
  The minimum area of the detected objects in pixels.

froundlo = 0.0, froundhi = 0.2
  The minimum and maximum ellipticity values of the detected objects, where ellipticity is defined as 1 - b / a, and a and b are the semi-major and semi-minor axis lengths respectively.

fsharplo = 0.5, fsharphi = 2.0
  The minimum and maximum sharpness values of the detected objects, where sharpness is defined to be the ratio of the estimated object size to the ihwhmpsf parameter value.

## The Omarkpars Parameter Set

The omarkpars parameters control the object marking algorithms. The default mark size osizemark and object matching tolerance otolerance parameters scale with the image scale defined by the impars iscale parameter.

objmark = yes
  Enable object list marking on the image display ?

ocharmark = "plus"
  The mark to be drawn. The options are: "point", "box", "cross", "plus", "circle", "diamond", and "shape". If the "shape" option is selected, the object and sky regions are outlined on the image display.

onumber = no
  Number the marked objects ?

opcolormark = "green"
  The color of the marked object region. The options are "red", "blue", "green", and "yellow".

oscolormark = "blue"
  The color of the marked sky region. The options are "red", "blue", "green", and "yellow".

osizemark = 5.0 (iscale units)
  The object mark half-width in scale units if ocharmark is not equal to "shape". If osizemark is INDEF the half-width is set to the impars ihwhmpsf parameter.

otolerance = 5.0 (iscale units)
  The position matching tolerance for selecting an object from the object list with the image cursor.

## The Cenpars Parameter Set

The cenpars parameters control the action of the centering algorithms. The default values should produce reasonable results in most cases. Some of the centering parameters scale with the image data dependent impars parameters iscale and iskysigma.

calgorithm = "centroid1d"
  The centering algorithm. The centering algorithm options are:
  none
    Set the object centers to the initial centers.

  centroid1d
    Set the object centers to the the intensity weighted means of the marginal profiles in x and y. This is the recommended algorithm for Xguiphot users.

  gauss1d
    Set the object centers by fitting a Gaussian of fixed hwhmpsf to the marginal profiles in x and y using non-linear least squares techniques. Hwhmpsf is set to the value of the impars ihwhmpsf parameter.

  ofilter1d
    Set the object centers using optimal filtering techniques, a triangular weighting function of half width equal to hwhmpsf, and the marginal distributions in x and y. Hwhmpsf is set to the value of the impars ihwhmpsf parameter.

cradius = 3.5 (iscale units)
  The radius of the image subraster used for object centering in units of the impars iscale parameter. Cradius should be big enough to include most of the core of the object, but small enough to remain unbiased by noise.

cthreshold = INDEF (iskysigma units)
  Only points cthreshold * iskysigma above (emission features) or below (absorption features) the data minimum or maximum respectively are used by the centering algorithms. Xguiphot users should leave cthreshold set to INDEF which invokes the default thresholding technique appropriate for each centering algorithm. Setting cthreshold to 0.0 turns off thresholding altogether for all the centering algorithms.

cminsnratio = 3.0
  The minimum signal to noise ratio for object centering. If the estimated signal to noise ratio is less than cminsnratio the computed center is returned with an error flag.

cmaxiter = 10
  The maximum number of centering algorithm iterations.

cxyshift = 5.0 (iscale units)
  The maximum permissible shift of the center with respect to the initial coordinates in units of the impars iscale parameter. If the shift computed by the centering algorithms is larger than cxyshift, the computed center is returned with an error flag.

ctrmark = no
  Mark the computed object centers on the image display ?

ccharmak = "plus"
  The character used to mark the object centers. The options are "point", "box", "cross", "plus", "circle", and "diamond".

ccolormark = "red"
  The center mark color. The options are "red", "blue", "green" and "yellow".

csizemark = 5.0 (iscale units)
  The size of the center mark in units of the impars iscale parameter. If csizemark is undefined the mark size defaults to 2.0 * cradius.

## The Skypars Parameter Set

The skypars parameters control the action of the sky fitting algorithms. The default values have been chosen for efficiency and to give reasonable results in the majority of cases. Several of the sky fitting parameters scale with the image scale defined by the impars iscale parameter and the computed standard deviation of the sky pixels sigma. Data outside the good data range defined by the impars parameters imindata and imaxdata are rejected from the sky pixel distribution before the sky is fit.

smode = "concentric"
  The default sky measurement mode. The options are:

  concentric
    Measure the sky in a region concentric with the object.

  offset
    Measure the sky in a region offset from the object.

sgeometry = "circle"
  The default geometry of the sky region. The options are "circle", "ellipse", "rectangle", and "polygon".

srannulus = 20.0 (iscale units)
  The inner semi-major axis of the annular sky fitting region in units of the impars iscale parameter. Srannulus may be 0.0. If the sky region is a concentric polygon the inner "axis" of the user defined polygon is pushed outward by srannulus pixels; if it is an offset polygon srannulus is ignored.

swannulus = 5.0 (iscale units)
  The width of the annular sky fitting region in units of the impars iscale parameter.

saxratio = 1.0
  The default ratio of the minor to major axis of the sky region. This parameter does not apply to polygons.

posangle = 0.0 (degrees)
  The default position angle of the sky region in degrees counter-clockwise from the positive x axis. This parameter does not apply to polygons.

salgorithm = "hcentroid"
  The sky fitting algorithm to be employed. The sky fitting options are:

  none
    Use 0.0 for the sky background.

  constant
    Use the current value of the sconstant parameter for the sky background.

  mean
    Estimate the mean of the sky pixel distribution.

  median
    Estimate the median of the sky pixel distribution.

  mode32
    Estimate the mode of the sky pixel distribution using the mode = 3 * median - 2 * mean algorithm.

  hcentroid
    Estimate the intensity-weighted mean or centroid of the sky pixel histogram. This algorithm is equivalent to estimating the mode of the histogram.

  hgauss
    Fit a Gaussian function to the sky pixel histogram using non-linear least-squares techniques.

  hofilter
    Estimate the sky using the optimal filtering algorithm, a triangular weighting function, and the histogram of the sky pixels.

  hcrosscor
    Estimate the sky value using the cross-correlation function of the sky pixel histogram and a Gaussian noise function with a sigma equal to the computed sigma of the sky pixel distribution.

  If the sky fitting algorithm is "zero" or "constant" then the computed standard deviation of the sky pixels is set to the value of the impars iskysigma parameter.
sconstant
  The constant used by the "constant" sky fitting algorithm.

shwidth = 3.0 (sigma)
  The ksigma clipping factor for computing the histogram of the sky pixels. Shwidth is in units of the computed sky sigma. The computed histogram will be 2.0 * shwidth * sigma wide.

shbinsize = 0.20 (sigma)
  The resolution of the sky pixel histogram in units of the computed sky sigma. The number of histogram bins will be 2 * shwidth / shbinsize + 1.

shmooth = yes
  Boxcar smooth the sky histogram before computing a sky value?

smaxiter = 10
  The maximum number of iterations performed by the "hgauss" and "hofilter" sky fitting algorithms.

sloclip = 0.0 (percent)
  The low-side clipping factor in percentage points of the total number of sky pixels.

shiclip = 0.0 (percent)
  The high-side clipping factor in percentage points of the total number of sky pixels.

snreject = 50
  The maximum number of sky pixel rejection cycles.

sloreject = 3.0 (sigma)
  The ksigma low-side clipping factor for the pixel rejection phase of the sky fitting algorithm in units of the computed sky sigma.

shireject = 3.0 (sigma)
  The ksigma high-side clipping factor for the pixel rejection phase of the sky fitting algorithm in units of the computed sky sigma.

srgrow = 0.0 (iscale units)
  The region growing radius for sky pixel rejection in units of iscale. When a bad sky pixel is detected, all pixels within srgrow / iscale pixels will be rejected. If srgrow is 0.0 region growing is not performed.

skymark = yes
  Mark the sky region on the displayed image ?

scolormark = "yellow"
  The color of the marked sky region. The options are "red", "blue", "green", and "yellow".

## The Photpars Parameter Set

The photpars parameters control the action of the photometry algorithms. The default values have been chosen for efficiency and to give reasonable results in common cases. The photometry apertures scale with the image scale defined by the impars iscale parameter. Magnitudes for objects with data outside the good data limits defined by the impars imindata and imaxdata parameters are set to INDEF although the sums and fluxes are still computed.

pgeometry = "circle"
  The default geometry of the object region. The options are "circle", "ellipse", "rectangle", or "polygon".

papertures = "10" (iscale units)
  The semi-major axes of the photometry apertures in units of the impars iscale parameter or the file name containing the list of semi-major axes. Individual aperture axes may be separated by whitespace or commas, e.g "3,5,10". A ranges syntax of the form ap1:apN:apstep, e.g. "1:10:0.5" is also supported. The maximum number of photometry apertures is 100.

paxratio = 1.0
  The default ratio of minor to major axes of the object region. This parameter does not apply to polygons.

pposangle = 0.0 (degrees)
  The default position angle of the object region in degrees counter-clockwise from the positive x axis. This parameter does not apply to polygons.

pzmag = 25.00 (magnitudes)
  The zero point of the magnitude scale.

photmark = yes
  Mark the photometry apertures on the displayed image ?

pcolormark = "red"
  The color of the marked apertures. The options are "red", "blue", "green", and "yellow".

## The Cplotpars Parameter Set

The cplotpars parameter set controls the contouring algorithms used by the Xguiphot object and sky viewing routines. Users can display contour plots of the object and sky regions or contour plots overlaid on the object and sky regions.

enx = 31 (pixels), eny = 31 (pixels)
  The default width of the region to be contoured in pixels. Enx and eny are only used if for some reason the code cannot figure out the size of the object or sky regions.

ez1 = INDEF (ADU)
  The minimum pixel value to be contoured. If ez1 = INDEF, the data minimum is used for the minimum.

ez2 = INDEF (ADU)
  The maximum pixel value to be contoured. If ez2 = INDEF, the data maximum is used for the maximum.

ez0 = INDEF (ADU)
  The intensity value of the zero contour, i.e., the value of a zero point shift to be applied to the image data before plotting. The value of ez0 does not affect the values of the ez1 and ez2 parameters. The default value of ez0 is 0.0.

encontours = 5
  The number of contours to be drawn. If encontours is INDEF then the value of edz determines the number of contours.

edz = INDEF (ADU)
  The contour interval used if encontours is INDEF. If encontours and edz are both undefined then between 20 and 30 contours spanning the data range are drawn.

ehilomark = "none"
  The high / low contour marking options. The choices are:

  "none"
    The highs and lows are not marked.

  "hilo"
    The highs and lows are marked on the plot.

  "pixel"
    The intensity of each pixel is marked on the plot.

edashpat = 528
  The dash pattern for negative contours.

elabel = no
  Label the major contours in the contour plot ?

ebox = no
  Draw a box around the plot ?

eticklabel = no
  Label the tick marks ?

exmajor = 5, exminor = 0
  The number of major and minor axis divisions along the x axis.

eymajor = 5, eyminor = 0
  The number of major and minor axis divisions along the y axis.

eround = no
  Round the axes limits to nice values ?

efill = no
  Fill the output viewport or enforce unity aspect ratio ?

## The Splotpars Parameter Set

The splotpars parameter set controls the surface plotting algorithms used by the Xguiphot object and sky region viewing routines. Users can display surface plots of the object and sky regions.

anx = 31 (pixels), any = 31 (pixels)
  The default width of the region to be plotted in pixels. Anx and any are only used if for some reason the code cannot figure out the size of the object or sky apertures.

az1 = INDEF (ADU)
  The minimum value to be plotted. If az1 = INDEF, the data minimum is used for the minimum value.

az2 = INDEF (ADU)
  The maximum value to be plotted. If az2 = INDEF, the data maximum is used for the maximum value.

alabel = no
  Draw and label the axes ?

angv = 25 (degrees)
  The vertical viewing angle in degrees.

angh = -33 (degrees)
  The horizontal viewing angle in degrees.

# Running Xguiphot with the GUI

## Starting Xguiphot

To start Xguiphot, cd to your working directory, type xguiphot at the xapphot package prompt, and enter the input image list, the input objects file list, and the output results lists, as shown below.

    xa> cd [mydir]
    xa> xguiphot
    List of images to be analyzed (*):
    List of input objects files (default):
    List of output results files (default):

After a few seconds the xguiphot control panel activates, the first image is displayed in the image display window, the image display cursor activates, and Xguiphot is ready to accept user commands.

If an error condition is detected when Xguiphot starts up a warning message will be displayed in the status line at the bottom of the image display window.

## Quitting Xguiphot

To quit Xguiphot press the Quit button in the Xguiphot control panel. The quit command tells Xguiphot to shut down all the open windows, terminate task execution, and return control to the IRAF cl.

## Getting On-Line Help

To access the Xguiphot on-line help activate the help panel by: pressing the Help Button in the Xguiphot control panel, typing ? in the image display window, pressing any Help button in any active Xguiphot panel.

The text displayed in the help panel is part of the HTML document xapphot$doc/xguiphot.html, which can be browsed while Xguiphot is running or viewed and printed off-line with your standard web browser.

## Dealing with Directories

The default Xguiphot current directory is the directory in which Xguiphot is started. This is also the default directory from which images and objects files are read and into which results files are written.

To display the current directory and subdirectory structure bring up the files panel using the files menu as shown below.

- move the mouse to the Files menu button
- select the "Files panel ..." option

The current directory is displayed in the "Current Directory Listing" section of the files panel in the "Current Dir" entry box. The current directory subdirectory structure is listed below.

To set a new current directory using the Files panel:

- move the mouse to the "Current Directory Listing" section "Current Dir" entry box
- type Ctrl k to delete the existing directory specification
- enter the new directory specification
- hit return or move to and press the Apply button

To browze the subdirectory structure using the Files panel:

- move the mouse to the "Current Directory Listing" section
- click the left mouse button on the desired subdirectory
- the new current directory will appear in the "Current Dir" box
- "Current Dir" box text will change to white
- hit Return in the "Current Dir" box

## Dealing with Images

## Setting the Image Directory

The default Xguiphot image directory is the directory in which Xguiphot is started. If the Xguiphot task parameter images includes a directory specification, e.g. "/u2/davis/may31/* then the directory specification, e.g. "/u2/davis/may31/" becomes the default image directory and overrides the current directory.

To display the current image file directory bring up the files panel using the files menu as shown below.

- move the mouse to the Files menu button
- select the "Files panel ..." option

The current image directory is displayed in the "Input Images" section of the files panel in the "Dir" entry box. If the Xguiphot images parameter includes a directory specification, it is displayed in the "Images" entry box not the "Dir" entry box.

To enter a new images file directory using the Files panel:

- move the mouse to the "Input Images" section "Dir" entry box
- type Ctrl k to delete the existing directory specification
- enter the new directory specification
- press the Apply button

To enter a new global default directory using the Files panel:

- move the mouse to the "Input Images" section "Dir" entry box
- type Ctrl k to delete the existing directory specification
- enter the new directory specification and hit Return
- press the Apply button

The new image directory specification is prepended to the current images template defined by the images parameter, and new images, input objects file, and output results file lists are generated. The current image, current objects file, and default output file names are displayed in the Files panel, and the first image in the new image list is displayed in the image display window.

## Setting the Image Template

The default Xguiphot image template is the value of the images parameter. The default value of images is "*" which selects for all images of all types in the current working directory. For more information about image templates, image names, and root image names see the Input Images section.

To display the current image file directory using the Files panel and Files menu as shown below.

- move the mouse to the Files menu button
- select the "Files panel ..." option

The current image directory, image template, and image list are displayed in the "Input Images" section of the files panel. The current image name is highlighted in the image list and should match the image name displayed in the Files marker in the image display window.

To quickly display the current image template, image name, and image sequence number without using the Files panel use the builtin colon commands as shown below.

- move the mouse to the image display window
- type :images to display the current image template
- type :imname to display the current image name
- type :imnumber to display the current image number

To enter a new image template using the Files panel:

- move the mouse to the "Input Images" section "Images" entry box
- type Ctrl k to delete the existing images template specification
- enter the new image template and hit Return
- or press the Apply button

New images, input objects file, and output results file lists are generated. The current image, current objects file, and default output file names are displayed in the Files panel, and the first image in the new image list is displayed in the image display window.

To quickly define a new image template and load a new image list without bringing up the Files panel using the builtin colon commands.

- move the mouse to the image display window
- type :images [newtemplate] to load a new image template

## Browsing the Image List

To browse the current image list in any order using the Files panel:

- move the mouse to the Files menu button
- select the "Files panel ..." option
- move the "Input Images" section scrollbar to view the image list

The image currently displayed in the image display window is highlighted in the image list.

To select a new image using the Files panel:

- position the mouse to the desired image name in the image list
- click the left mouse button

Now the new image name is highlighted in the image list and displayed in the image display window. A new default input objects file is selected and highlighted in the input objects file list, and a new default output file is selected.

To quickly change images using the builtin colon commands:

- move the mouse to the image display window
- type :imname [newimage] to select a new image

To move backwards and forwards sequentially in the image list without bringing up the Files panel:

- move the mouse to the Files menu button
- select the "Next image" or "Previous image" items

or use the builtin keystroke commands as shown below.

- move the mouse to the image display window
- type the n or p keystroke commands

## Browsing the Image Headers

To view the current image header using the image header panel:

- move the mouse to the Images menu button
- select the "Display header ..." item
- scroll the header text

To bring up the image header panel using a simple keystroke command:

- move the mouse to the image display window
- type the h keystroke command

The image header panel displays the current image name, size, pixel type, title, creation and modification dates, and keywords.

To browse the image headers use the image header panel Next and Prev buttons.

The image header browsing facilities can be used to check whether critical keywords defining the gain, readout noise, exposure time, filter, airmass, and time of the observation are present and correct in the image headers, and whether these keywords match the expected keywords defined by the impars parameters ikgain, ikreadnoise, ikexptime, ikairmass, ikfilter, and ikobstime. Missing keywords will generate an error message in the status line at the bottom of the image display window.

## Interacting with the Image Display

To view and / or modify the image display options using the Images menu:

- move the mouse to the Images menu button
- select the Options submenu
- select the desired option

To pan the image:

- move the mouse to the desired position
- click once on the middle mouse button

To zoom the image display:

- move the mouse to the desired position
- click the middle mouse button twice to zoom in
- hold down the Shift key and click the middle mouse button to zoom out
- hold down the Control key and click the middle mouse button to unzoom

To window the image display:

- hold down the 3rd mouse button and move the mouse

To use the builtin task specific keystroke commands:

- move the mouse to the desired position in the image display window
- type the keystroke, e.g. i to redisplay the image

The builtin IRAF cursor mode keystroke commands are also supported. Users should be aware of the following:

- C print the coordinates of the cursor
- E expand the plot, 2 keystrokes
- M pan
- Z zoom in
- P zoom out
- R redraw the screen
- 0 reset and redraw the screen

To redisplay the current image:

- press the Images menu button
- select the "Current image" item
.

or use the i keystroke command as shown below.

To access the image display menu:

- move to the desired position in the image display window
- press the left mouse button
- select the desired menu item

## Setting the Dispars Parameters

Occasionally neither the default image display parameters nor the image display windowing capabilities do a satisfactory job of displaying the image. In this case the user must alter the default display spatial and intensity mapping algorithms by editing the dispars parameter set.

To edit the dispars parameters using the dispars parameter editing panel:

- move the mouse to the Images menu button
- select the "Dispars pset ..." item

A panel appears which describes each dispars parameter, and lists its current value and name. The parameter values can be edited as follows.

- move mouse to the parameter entry box
- if box highlights

- click left mouse button to toggle boolean parameters
- or press left mouse button and select menu item

- if caret appears in box

- position cursor to beginning of old entry
- type Ctrl k to delete the existing parameter value
- enter the new value and hit Return

- press the Apply button to enter changes
- press the Display button to redisplay the image
- press the Dismiss button

To edit a dispars parameter without bringing up the dispars parameter editing panel type in the appropriate colon command as shown below for the case of the dispars ztransform parameter.

- move mouse to the image display window
- type in the command :ztransform log followed by return
- type in the command :ztransform to check the new value
- type the i keystroke command to redisplay the image

## Estimating the Hwhm of the Psf

Xguiphot users can obtain an accurate estimate of the half-width at half-maximum of the stellar psf by fitting an elliptical Gaussian function to one or more stellar objects.

To compute and print the model fit parameters using the image display menu and / or a keystroke command:

- move the mouse to a star in the image display window
- press the left mouse button
- select the "Compute model fit..." item
- repeat last 3 commands for new objects, or type x instead

The fitted x and y center, amplitude, half-width at half-max, axis ratio, position angle, sky background, and sky sigma are printed in the status line for each measured object.

To compute, plot and print the model fit using the Model fitting panel:

- move the mouse to a star in the image display window
- press the left mouse button
- select the "Show model fit ..." item, or type y
- move mouse to new object of interest
- press the left mouse button
- select the "Compute model fit ..." item, or type x

Note that the plot is not a radial profile plot but a major axis plot where the intensity of each point is plotted against its major axis.

To store the new value of the hwhm in impars parameter ihwhmpsf using the Model fitting panel.

- move the mouse to the Model fitting panel
- press the Activate button
- press the Setwidth button
- press the Refit button to check stability of fit
- press the Deactivate command button

To check that the impars ihwhmpsf parameter has been correctly updated being up the impars parameter editing panel as shown below:

- move the mouse to the Images menu button
- select the "Impars pset ..." item
- check the displayed ihwhmpsf parameter value

or use the builtin colon commands as shown below.

- move the mouse to the image display window
- type :ihwhmpsf to display the current parameter value

## Setting the Impars Parameters

The impars parameters should normally be checked and edited before doing any serious photometry. Although reasonable default values have been chosen for all the impars parameters, the performance of some of some algorithms will be improved, and future analysis simplified if the impars parameters are set appropriately for the data.

Most users should set the impars parameters ihwhmpsf, imindata, imaxdata, ikreadnoise, ikgain, and ikexptime parameters to values appropriate for their entire data set. The ikairmass, ikfilter, and ikobstime keywords should be set if the user plans to do photometric calibrations of the measurements. The remaining parameters can normally be left at their default values.

To edit the impars parameters using the impars parameter editing panel:

- move the mouse to the Images menu button
- select the "Impars pset ..." item

A parameter editing panel appears which describes each impars parameter and lists its current value and name. The parameter values can be edited as described below.

- move mouse to the parameter entry box
- if box highlights

- click left mouse button to toggle boolean parameters
- or press left mouse button to activate menu and select item

- if caret appears in box

- position cursor to beginning of existing string
- type Ctrl k to delete the existing parameter value
- enter the new value and hit Return

- press the Apply button to enter the changes
- press the Dismiss button

To edit an impars parameter without bringing up the impars parameter editing panel, type in the appropriate colon command as shown below for the case of the impars imaxdata parameter.

- move mouse to the image display window
- type in the command :imaxdata 32000 followed by return
- type in the command :imaxdata to check the new value

Users can check that Xguiphot is reading in correct values for the keywords ikgain, ikreadnoise, ikexptime, ikairmass, ikfilter, and ikobstime from the image header by displaying both the image header panel and the impars parameter editing panel as they browse the image list. If the header keywords are read in correctly the correct values of gain, readout noise, exposure time, airmass, filter id, and time of observation should appear opposite the igain, ireadnoise, ietime, iairmass, ifilter, and iotime impars parameters in the parameter editing panel.

## Dealing with Objects Files

## Setting the Objects File Directory

The default Xguiphot objects file directory is the directory in which Xguiphot is started. If the Xguiphot task parameter objects includes a directory specification, e.g. "/u2/davis/may31/default then the directory specification, e.g. "/u2/davis/may31/" becomes the default objects file directory and overrides the current directory.

To display the current objects file file directory activate the Files panel using the Files menu as shown below.

- move the mouse to the Files menu button
- select the "Files panel ..." option

The current objects file directory is displayed in the "Input Objects Files" section of the Files panel in the "Dir" entry box. If the Xguiphot objects parameter includes a directory specification, this directory specification is displayed in the "Objects" entry box not the "Dir" entry box.

To enter a new objects file directory using the Files panel:

- move the mouse to the "Input Objects Files" section "Dir" entry box
- position the mouse to the beginning of the existing entry
- type Ctrl k to delete the existing entry
- enter the new directory specification and press Return
- move to the "Input Objects Files" section "Objects" entry box
- press Return

The new objects file directory specification is prepended to the current objects file template defined by the objects parameter and a new input objects file list is generated. The current objects file is highlighted in the Files panel and displayed in the Files marker in the image display window.

## Setting the Objects File Template

The default Xguiphot objects file template is the value of the objects parameter. The default value of objects, "default", defines names of the form "root.obj.version", where root is the root image name, "obj" is an extension identifying the file as an objects file, and version is the highest version number. For more information about object file templates see the Input Objects Files section.

To display the current objects file directory bring up the Files panel using the Files menu as shown below.

- move the mouse to the Files menu button
- select the "Files panel ..." item

The current objects file directory, objects file template, and objects file list are displayed in the "Input Objects File" section of the Files panel. The current objects file name is highlighted in the objects file list and matches the objects file name displayed in the Files marker.

To display the current objects file template, objects file name, and objects file sequence number without bringing up the Files panel use the builtin colon commands as shown below.

- move the mouse to the image display window
- type :objects to display the current objects file template
- type :olname to display the current objects file name
- type :olnumber to display the current objects file number

To enter a new objects file template using the Files panel:

- bring up the files panel as shown above
- move to the "Input Objects Files" section "Objects" entry box
- position mouse to beginning of existing entry
- type Ctrl k to delete the existing entry
- enter the new objects file template and hit Return

A new input objects file list is generated and a new current input objects file is selected.

To define a new objects file template and load a new objects file list without bringing up the files panel use the builtin colon commands as shown below.

- move the mouse to the image display window
- type :objects [newtemplate] to load a new objects file template

## Browsing the Objects File List

To browse the current objects file list in any order using the Files panel:

- move the mouse to the Files menu button
- select the "Files panel ..." option
- use the "Input Objects Files" scrollbar to view the objects file list

The current objects file in the objects file list is highlighted and displayed in the Files marker.

To select a new current objects file using the Files panel:

- position to the desired objects file name in the objects file list
- click the left mouse button

The same operation can be performed using the builtin colon commands as shown below:

- move the mouse to the image display window
- type :olname [newobjectsfile] to select a new objects file

To move backwards and forwards sequentially in the objects file list without bringing up the Files panel:

- move the mouse to the Files menu button
- select the "Next objects file" or "Previous objects file" items

or use keystroke commands as shown below.

- move the mouse to the image display window
- type the ] or [ keystroke commands

## Dealing with Objects Lists

Xguiphot supports facilities for creating, viewing, editing, and saving objects lists. Objects lists are maintained by Xguiphot as internal data structures and should not be confused with object files on disk. The latter are described in the Input Objects Files and the Object File Formats sections of this document.

## Creating Object Lists from Object Files

If the objects file specified by the Xguiphot objects parameter exists and the current objects list is undefined, then Xguiphot will automatically create the objects list when a command requiring it is issued.

To create an objects list from the current objects file using the List menu:

- move the mouse to the Lists menu button
- select the "Current file" item
- next select the "Mark list" item

A message will appear in the status line stating how many objects were read from the file and marked on the image display.

To perform the same functions using the List panel:

- move the mouse to the Lists menu button
- select the "List panel ..." item
- move to the Create New List section of the List panel
- press the Reread button to make sure the list is current
- move to the View and Edit section of the List panel
- press the Show button to mark the object list on the image display

To perform the same functions using the builtin cursor keystroke commands:

- move the mouse to the image display window
- type r to read the current objects file into an object list
- type m to mark the object list on the image display

## Creating Object Lists Automatically

Object lists can be created automatically from the image using Xguiphot's builtin object detection algorithm. The current algorithm is optimized for detecting stellar objects. Before running the detection algorithm users should set the impars parameters ihwhmpsf to a value appropriate for the current image as described in the section Setting the Hwhm of the Psf. Image data outside the bad limits defined by the impars imindata and imaxdata parameters will be ignored by the detection algorithms, although objects with enough remaining good data inside the region of interest will still be detected.

To create an object list for an image using the List menu:

- move the mouse to the Lists menu button
- select the "Find list" item
- next select the "Mark list" item

A message will appear in the status line stating how many objects were found and marked on the image display.

To perform the same functions using the List panel:

- move the mouse to the Lists menu button
- select the "List panel ..." item
- move to the Create New List section of the List panel
- press the Find button to create the list

Note that the detected objects have been assigned an INDEF geometry even though a rough estimate for the axis ratio and the position angle has been computed. This means that Xguiphot will use the values of the photpars and skypars parameters to assign a geometry to each object.

To perform the same functions using the builtin cursor keystroke commands:

- move the mouse to the image display window
- type @ to create the objects list

## Setting the Findpars Parameters

The findpars parameters control the action of the automatic detection algorithm. Although reasonable default values have been chosen for most of the findpars parameters, most users will need to adjust the fthreshold parameter to a value suitable for their scientific goals. The default value of 320 counts was chosen to be 1% of the typical maximum good value of 16 bit signed integer data ~32000 counts. The remaining parameters have been set to select for stellar objects. Users should also be aware that image data outside the good data range defined by the impars parameters imindata and imaxdata will be ignored by the detection algorithm even if it falls with the region defined by the findpars fradius parameter. If insufficient good data remains the object will be eliminated from the list.

To edit the findpars parameters using the findpars parameter editing panel:

- move the mouse to the Lists menu button
- select the "Findpars pset ..." item

A parameter editing panel appears which describes each findpars parameter, and lists its current value and name. To edit the parameter values:

- move mouse to the parameter entry box
- if box highlights

- click left mouse button to toggle boolean parameters
- or press left mouse button to activate menu and select item

- if caret appears in box

- move cursor to beginning of existing entry
- type Ctrl k to delete the existing parameter value
- enter the new value and hit Return

- press the Apply button to enter changes
- press the Dismiss button

To edit a findpars parameter without bringing up the findpars parameter editing panel type in the appropriate colon command as shown below for the case of the findpars fthreshold parameter.

- move mouse to the image display window
- type in :fthreshold 32.0 followed by return
- type in :fthreshold to check the new value

## Creating Object Lists with the Image Cursor

Object lists can also be created graphically using the image display and the image cursor. Users are prompted for the object record type, the object position and geometry, and the sky position and geometry.

The four supported object record types are listed below. The most common record types are object and object plus annular sky.

Object only (key = o)
  The user is prompted for the object aperture position and geometry only. The sky position and geometry default to the choices defined in the skypars parameter set.
Sky only (key = s)
  The user is prompted for the sky aperture position and geometry only. The object position and geometry default to the choices defined in the photpars parameter set.
Object Plus Annular Sky (key = a)
  The user is prompted for the position and geometry of the object aperture and the geometry of the sky aperture to be centered on the object aperture.
Object Plus Offset Sky (key = b)
  The user is prompted for the position and geometry of the object aperture and the position and geometry of the sky aperture which is offset from the object aperture.

Six object and sky geometries are supported.

point (key = .)
  Only the aperture position is defined.
circle (key = c)
  The object or sky aperture is a circle.
ellipse (key = e)
  The object or sky aperture is an ellipse.
rectangle (key = r)
  The object or sky aperture is a rectangle.
polygon (key = p)
  The object or sky aperture is a polygon.
again (key = a)
  The object or sky aperture is set to last defined object or sky aperture.

Xguiphot prompts for different quantities for the different geometries, i.e. radii only for circles, semi-major and minor axes and position angle for ellipses, etc.

The following example shows how to create a simple object list consisting of a set of identical circular object and circular annular sky region records.

- move mouse to the Lists menu button
- select "Draw list ..." item
- move to image display window and type a at "Object type" prompt
- move to star and type c at "Add object" prompt
- move to desired radius and type c at "Mark radius of circle" prompt
- type c to select a circular sky annulus at the "Add sky" prompt
- move to inner sky radius and type c at "Mark inner radius of circle" prompt
- move to outer sky radius and type c at "Mark outer radius of circle" prompt
- move to next star and type a at "Add object" prompt to repeat the object apertures
- type a at "Add sky" prompt to repeat the sky aperture
- repeat last two instructions for every star to be added to the list
- type q to quit the "Draw list ..." menu item

The following example shows how to draw an elliptical aperture on the image display.

- move mouse to the Lists menu button
- select "Draw list ..." item
- move mouse to image display window and type o at "Add object" prompt
- move to object and type e at "Add object" prompt
- move to desired semi-major axis and type e at "Mark semi-major axis of ellipse" prompt
- move to desired semi-minor axis and type e at "Mark semi-minor axis of ellipse" prompt
- type q to quit the "Draw list ..." menu item

Note that in both cases the "Draw list ..." menu item can be replaced with the keystroke commands z followed by a.

## Creating Object Lists with Markers

Object lists can be created interactively using the photometry marker and the main mouse menu as outlined below.

- move the mouse to the Lists menu button
- next select the "List panel ..." item
- press the Init button to delete any existing list
- move mouse to the image display window
- press the left mouse button
- select the "Show phot marker" item
- adjust the shape, position, size, and orientation of the marker
- move the mouse inside the object part of the marker
- press the right mouse button
- select the "Save to objects list" item
- release the right mouse button

The photometry marker materializes at the position the main mouse menu is activated. Its default object and sky region geometries are defined in the photpars and skypars parameter sets. Users can alter the geometry, position, shape, and orientation of the photometry markers using the mouse as described in the The Photometry Region Marker section.

## Viewing the Object List

The objects list can be viewed either by marking the objects on the image display or by scrolling the object list .

To view the objects list using the List panel:

- move mouse to the Lists menu button
- select "List panel ..." item
- move to the View and Edit section of the List panel
- press the Show button to mark the list on the image display
- use the Scrollbars to page the object list

The format of the object list can be can be found the Objects File Format section of the appendices. Note that in order to save space object and sky region polygon vertices are not displayed in the objects list.

To overlay the object list on the image display using the List menu:

- move the mouse to the Lists menu button
- next select the "Mark list" item

To perform the same operation with the builtin keystroke commands:

- move the mouse to the image display window
- type the m key

## Setting the Omarkpars Parameters

The omarkpars parameters control the action of object list marking routines. By default the object list object centers are marked with a green plus and the object list sky centers, if different, are marked with a blue plus. For large object lists the defaults will result in a relatively uncluttered graphics overlay, although in some especially crowded cases users may wish to decrease the value of the osizemark parameter or change the ocharmark parameter to "point". For smaller object lists containing large extended objects users may wish to set the ocharmark parameter to "shape" in order to draw the outlines of the object and sky apertures on the image display. Users should also be aware of the otolerance parameter which is used by the position matching code to select objects for analysis from the object list.

To edit the omarkpars parameters using the omarkpars parameter editing panel:

- move the mouse to the Lists menu button
- select the "Omarkpars pset ..." item

A parameter editing panel appears describing each omarkpars parameter, and listing its current value and name. To edit the omarkpars parameters:

- move mouse to the parameter entry box
- if box highlights

- click left mouse button to toggle boolean parameters
- press left mouse button to activate menu and select item

- if caret appears in box

- move cursor to beginning of existing entry
- type Ctrl k to delete the existing entry
- enter the new value and hit Return

- press the Apply button to enter the changes
- press the Dismiss button

To edit an omarkpars parameters without bringing up the omarkpars parameter editing panel type in the appropriate colon command, as shown below for the case of the omarkpars otolerance and ocharmark parameters.

- move mouse to the image display window
- type in the command :otolerance 8.0 followed by return
- type in the command :otolerance to check the new value
- type in the command :ocharmark shape followed by return
- type in the command :ocharmark to check the new value

## Browsing the Objects List

The object list can be browsed sequentially using the List panel and the object list marker as shown below

- move mouse to Edit menu button
- select the "List panel ..." item
- move to "View and Edit List" section of the List panel
- press the Rewind button to rewind object list
- press the Show Marker button to activate the object list marker
- repeatedly press the Next button to select the next object
- press the Dismiss Marker button to activate the object list marker

As each new object is selected the object marker is moved and the object is highlighted in the object list in the List panel.

The same function can be performed using the Edit menu as shown below.

- move mouse to Edit menu button
- select the "Show object marker" item
- select the "Rewind list" item
- repeatedly select the "Next object" item

Typing the ^ and f keystroke commands in the image display window can also be used to rewind and step forward sequentially through the image list.

If the object list marker is active, users can also select the "Next object" item from the object list marker menu by pressing the right mouse button inside the object list marker, or by typing the f keystroke command inside the object list marker. To browse the object list randomly or locate a specific object in the object list on the image display using the List panel:

- press the Show Marker button to activate the object list marker
- move to object of interest in the object list
- press the left mouse button to select an object
- press the Dismiss marker button

The selected object in the object list will highlight and the object marker will display the object and sky aperture in the image display window. If the object or sky aperture geometries are undefined in the object list, then the values in the photpars and skypars parameter sets are used.

To browse the object list randomly or to locate a specific object in the object list using the image display and image display menu:

- move mouse to the image display window
- move to object of interest
- press the left mouse button
- select the "Find nearest in list" item
- examine the status line and List panel

If the status line states that the object was not found this might mean that it is truly not in the object list or that the mouse was positioned too far away from the object. Try repositioning the cursor. The matching tolerance is controlled by the omarkpars parameter otolerance.

## Deleting and Undeleting Objects from the Objects List

To delete or undelete and object from the object list using the List panel.

- move mouse to Edit menu button
- Select the "List panel ..." item
- move to "View and Edit List" section of the list panel
- press the Show marker button to active the object list marker
- move to object to be deleted in object list
- press left mouse button
- press the Delete or Undelete button
- press the Dismiss marker button to active the object list marker

When an object has been successfully deleted its sequence number in the object list will be replaced by the letters DEL and it will be marked with a cross on the image display. When an object as been successfully undeleted its sequence number will be restored and the cross marking its position erased.

To perform the same functions using the image cursor and image display menu.

- move to the star to be deleted/undeleted in the image display
- press the left mouse button
- select the "Delete/Undelete nearest ..." item

The d and u keystroke commands typed directly in the image display window can also be used to delete / undelete objects.

If the object list marker is active then the current object can be deleted or undeleted by pressing the right mouse button inside the object marker and selecting the "Delete current object" or "Undelete current object" items, or by typing the d and u keys inside the object marker.

## Adding Objects to the Objects List

To add objects to an existing list using the List panel:

- move mouse to Edit menu button
- select the "List panel ..." item
- move to "View and Edit List" section of the list panel
- press the Draw button and move mouse to image display window
- follow instructions at the prompt

The drawing instructions are described in the Creating Object Lists with the Image Cursor section. The same functions can be performed without being up the List panel by selecting the "Add object(s) ..." item from the Edit menu, or by typing the a keystroke command in the image display window.

The object and sky position and geometries can also be added to the objects list by typing them into "Enter object geometry" entry box and hitting the Enter button. The required object formats are described in the Objects File Format section of the appendices. For small numbers of objects the model fitting code described in the Estimating the Hwhm of the Psf section can be used to determine good values for the x and y coordinates, axis ratios, and position angles.

The photometry marker can also be used to add objects to an existing list as described in the Creating Object Lists with Markers section.

## Saving the Objects List

To save the current object list to a file using the List panel.

- move mouse to Lists menu button
- select the "List panel ..." item
- move to the Save list section of the List panel
- press the Save button

A message listing the output file name and number of objects written will appear in the image display window status line.

To save the objects list to a file using the builtin colon commands:

- move the mouse to the image display window
- type :osave default

## Dealing with Results Files

## Setting the Results File Directory

The default Xguiphot results file directory is the directory in which Xguiphot is started. If the Xguiphot task parameter results includes a directory specification, e.g. "/u2/davis/may31/default then the directory specification, e.g. "/u2/davis/may31/" becomes the default results file directory overiding the current directory.

To display the current results file directory bring up the Files panel using the Files menu as shown below.

- move the mouse to the Files menu button
- select the "Files panel ..." option

The current results file directory is displayed in the "Output Results Files" section of the Files panel in the "Dir" entry box. If the Xguiphot results parameter includes a directory specification, this directory specification is displayed in the "Results" entry box not the "Dir" entry box.

To enter a new results file directory using the Files panel:

- move the mouse to the "Output Results Files" section "Dir" entry box
- position the cursor to the beginning of the existing entry
- type Ctrl k to delete the existing entry
- enter the new directory specification and press Return
- move the "Output Results Files" section "Results" entry box
- press Return

The new results file directory specification is prepended to the results file template specified by the results parameter, and the new results file is displayed beneath the results entry box.

## Setting the Results File Template

The Xguiphot results file template is the value of the results parameter. The default value of results is "default". It defines a name of the form "root.mag.version", where root is the root image name, "mag" is the extension, and version is the next available version number. For more information about results file templates see the Output Results Files section.

To display the current results file template using the Files panel and files menu;

- move the mouse to the Files menu button
- select the "Files panel ..." option

The current results file directory, results file template, and results file are displayed in the "Output Results File" section of the Files panel. The current results file name should match the results file name displayed in the Files marker in the image display window.

To display the current results file template, results file name, and results file sequence number using the the builtin colon commands:

- move the mouse to the image display window
- type :results to display the current results file template
- type :rlname to display the current results file name
- type :rlnumber to display the current results file number

To enter a new results file template using the Files panel:

- move to the "Output Results File" section "Results" entry box
- move cursor to beginning of existing entry
- type Ctrl k to delete the existing entry
- enter the new results file template and hit Return

To define a new results file template using the builtin colon commands:

- move the mouse to the image display window
- type :results [newtemplate] to load a new results file template

## Logging the Results

Results logging is disabled by default. The user must set the logresults parameter to "yes" to enable it. This allows the user time set the parameters and make a few experimental measurements before beginning serious work.

Users can check or change the results file logging status using the Files menu, the Files panel, the Files marker and Files marker menu, the "Logresults" command buttons in the List panel, the Photometry table panel, the Photometry plots panel, or by typing the ":logresults" colon command in the image display window.

For example to enable / disable results file logging:

- move mouse to the Files menu
- select the Disable / Enable logging item

or

- move mouse to the image display window
- type :logresults to check status
- type :logresults yes or :logresults no to set status

## Doing Photometry

This section describes how to use Xguiphot set the centering, sky fitting, and photometry algorithm parameters, and use it to make photometric measurements.

## Setting the Impars Parameters

The behavior of the centering, sky fitting, and photometry algorithms depend on parameters in the impars parameter set. Users should review the section Setting the Impars Parameters and before proceeding.

## Setting the Cenpars Parameters

The cenpars parameters should be reviewed before beginning serious photometric work. Although reasonable default values have been chosen for all the cenpars parameters, the performance of some of some algorithms may be improved if parameter settings are optimized for the data.

Users should review the recentering algorithm parameter calgorithm The most useful options are "none" which disables recentering, and and the default value "centroid1d".

Users check the values of cradius and set it to a reasonable value, usually something like 2-3 times the hwhm of the psf, but never less than 2.5 pixels.

By default center marking is disabled (ctrmark is "no"), while object and sky marking is enabled. In crowded regions users may wish to turn on center marking, and disable object and sky aperture marking, in order to avoid drawing a lot of confusing graphics on the image display.

To edit the cenpars parameters using the cenpars parameter editing panel as follows:

- move the mouse to the Phot menu button
- select the "Cenpars pset ..." item

A parameter editing panel appears describing each cenpars parameter, and listing its current value and name. The parameter values can be edited as shown below.

- move mouse to the parameter entry box
- if box highlights

- click left mouse button to toggle boolean parameters
- or press left mouse button to activate menu and select item

- if caret appears in box

- move cursor to beginning of existing entry
- type Ctrl k to delete the existing entry
- enter the new value and hit Return

- press the Apply button to enter the changes
- press the Dismiss button

To edit a cenpars parameter by typing in the appropriate colon command follow the example shown below for the cradius and ctrmark parameters.

- move mouse to the image display window
- type in :cradius 3.5 followed by return
- type in :cradius to check the new value
- type in :ctrmark yes followed by return
- type in :ctrmark to check the new value

## Editing the Skypars Parameters

The skypars parameters should be reviewed before doing any serious photometric work. Although reasonable default values have been chosen for all the skypars parameters, the performance of some of some algorithms will be improved, if the parameters are optimized for the data.

Users should check and set the sky geometry parameters smode, sgeometry, srannulus, swannulus, saxratio, and sposangle. For bright stellar objects mode is usually "concentric", srannulus is usually ~10 * hwhm of the psf and swannulus is 5-10 pixels.

Users should check the sky fitting algorithm parameter salgorithm. The most useful options are usually "constant", "mean", "median", "mode32", and "hcentroid". The remaining algorithm parameters should normally be left at their default values.

By default sky aperture marking is enabled (skymark is "yes"), and the default sky aperture marking color is different from the photometry aperture marking color. Users should normally leave sky marking enabled if they are measuring objects interactively, and disable it if they are measuring large numbers of objects automatically.

To edit the skypars parameters using the skypars parameter editing panel:

- move the mouse to the Phot menu button
- select the "Skypars pset ..." item

A parameter editing panel appears which lists each skypars parameter, its current value, and its name. To edit the parameter values:

- move mouse to the parameter entry box
- if box highlights

- click left mouse button to toggle boolean parameters
- or press left mouse button to activate menu and select item

- if caret appears in box

- move cursor to beginning of existing entry
- type Ctrl k to delete the existing entry
- enter the new value and hit Return

- press the Apply button to enter the changes
- press the Dismiss button

To edit a skypars parameter by typing in the appropriate colon command follow the example shown below for the srannulus, swannulus and skymark parameters.

- move mouse to the image display window
- type in :srannulus 15.0 followed by return
- type in :srannulus to check the new value
- type in :swannulus 5.0 followed by return
- type in :swannulus to check the new value
- type in :skymark yes followed by return
- type in :skymark to check the new value

## Editing the Photpars Parameters

The photpars parameters should be reviewed before doing serious photometric work. Although reasonable default values have been chosen for all the photpars parameters, the performance of some of some algorithms will be improved if the photpars parameters are optimal for the data.

Users should check and set the object geometry parameters pgeometry, papertures, paxratio, and pposangle. Multiple apertures lists or ranges may be specified as follows, i.e. papertures = "3,5,7,10,15" or "1:15:1.0"

Users may also wish to change the default value of the magnitude zero point pzmag. The most useful choices are 0.0 and 25. The former value provides a direct conversion to flux, and the latter value agrees with the task defaults in the digiphot package and the imexamine task (except for the effects of exposure time normalization).

By default photometry aperture marking enabled (photmark is "yes"), and the default photometry aperture marking color is different from the sky aperture marking color. Users should leave photometry aperture marking enabled if they are measuring objects interactively, and disable it if they are measuring a large number of objects automatically.

To edit the photpars parameters using the photpars parameter editing panel:

- move the mouse to the Phot menu button
- select the "Photpars pset ..." item

A parameter editing panel describing each photpars parameter, and listing its current value and name. To edit the parameter values:

- move mouse to the parameter entry box
- if box highlights

- click left mouse button to toggle boolean parameters
- or press left mouse button to activate menu and select item

- if caret appears in box

- move cursor to beginning of the existing entry
- type Ctrl k to delete the existing entry
- enter the new value and hit Return

- press the Apply button to enter the changes
- press the Dismiss button

To edit a photpars parameter by typing in the appropriate colon command as shown below for the case of the photpars papertures, and photmark parameters:

- move mouse to the image display window
- type in :papertures 1:10:1 followed by return
- type in :papertures to check the new value
- type in :photmark yes followed by return
- type in :photmark to check the new value

## Measuring Objects with the Image Cursor

The simplest way to measure an objects interactively is to use the image display and image cursor and the default object and sky geometries defined in the photpars and skypars parameter sets.

To measure an object using the image display menu:

- move the mouse to an object in the image display window
- press down the left mouse button
- select the "Point and measure item
- release the left mouse button

or alternatively

- move the mouse to an object in the image display window
- press the Spacebar key

By default the object and sky apertures are marked on the image display in different colors, and quick-look results are printed in the status line in the following format.

- fitted x center in pixels
- fitted y center in pixels
- fitted sky value in counts
- fitted sky sigma in counts
- moments analysis hwhm through largest aperture in iscale units
- moments analysis axis ratio through largest aperture
- moments analysis position angle through largest aperture in degrees
- object flux through largest aperture in counts
- magnitude through largest aperture
- magnitude error through largest aperture
- error code through largest aperture, 0 means no error

If the sky fitting mode parameter smode is "offset" instead of the default "concentric", the user must make two "Point and measure" menu selections, or type Spacebar twice, once at the position of the object and once at the position of the sky, and the message Again: will appear on the terminal between the two measurements.

If either the photometry or sky aperture geometry parameters, pgeometry or sgeometry are "polygon" the user must define the polygonal apertures interactively before doing photometry. This is done by using either the "Mark polygons ..." item in the Phot menu or the v keystroke command in the image display window. In either case the user must mark the vertices of the desired polygon by moving to each vertex in order and typing v to mark the vertex, followed by the q keystroke to quit the polygon marking menu. Xguiphot will automatically close the polygon. The user can redefine the polygon at any time. Xguiphot will use the stored aperture only when the pgeometry parameter is set to "polygon". If the value of the smode parameter is "concentric" and the sky geometry is "polygon", then Xguiphot will construct an annular polygonal sky region using the object polygon and the values of the srannulus and swannulus parameters to define a polygonal sky annulus. If the sky fitting mode is "offset" then the user is prompted for and must draw a separate sky polygon, which will be annular or filled depending on the value of swannulus.

## Measuring Objects Through the Photometry Marker

Measuring objects through the photometry marker is similar to measuring them with the image cursor, except that the marker provides the ability to alter the object and sky geometries before making measurements, and without editing the skypars and photpars parameter sets. The photometry marker is fully described in the The Photometry Region Marker section. This section outlines how it can be used to make simple photometry measurements.

To measure an object using the default photometry marker and mouse:

- move to an object in the image display window
- press down the left mouse button
- select the "Show phot marker" item
- move the mouse into the object part of the photometry marker
- press down the right mouse button
- select the "Measure" item

The measured object will be marked on the display, although the measurement aperture may be shifted from the photometry marker aperture due to the effects of centering was enabled.

Users should be aware that measuring an object through the default photometry marker is not quite that same as point at it with the mouse and typing Spacebar, because in the former case the measurement geometry is read from the marker itself, and in the latter case it is read from the photpars and skypars parameter sets. Due to the finite precision of the image display window these two geometries will not exactly equal.

To redefine the measurement apertures interactively and do the measurement through the photometry marker in "concentric" sky mode:

- move the mouse to an object in the image display window
- press the left mouse button
- select the "Show phot marker" item
- move, resize, and rotate the object part of the marker
- resize and rotate the inner sky part of the marker
- resize the outer part of the sky marker
- move the mouse into the object part of the marker
- press the right mouse button
- select the "Measure" item

To redefine the measurement apertures interactively and do the measurement using the photometry marker in "offset" sky mode:

- move the mouse to an object in the image display window
- press the left mouse button
- select the "Show phot marker" item
- move the mouse to the sky region
- press the left mouse button
- select the "Offset sky marker" item
- move, resize, and rotate the object part of the marker
- move, resize, and rotate the inner part of the sky marker
- resize the outer part of the sky marker
- move the mouse into the object part of the marker
- press the right mouse button
- select the Measure item

The default sky fitting mode can be changed quickly from "concentric" to "offset" by:

- move mouse to the image display window
- press the left mouse button
- select the "Offset sky" or "Annular sky" item

A list of objects can be saved for later measurement by repeating any of the above recipes and selecting the "Save to objects list" item from the Photometry marker menu, instead of the "Measure" item.

Each time the photometry marker is dismissed and reactivated it is redrawn using the default object and sky geometries specified in the skypars and photpars parameters, and any user changes are lost. To make the current photometry marker geometry the default geometry:

- move mouse to the object part of the photometry marker
- press the right mouse button
- select the "Save to psets" item
- edit the photpars and skypars parameter sets to round the numbers

After each measurement the object and sky apertures will be marked on the image display in different colors, and the quick-look results will be printed in the status line in the following format.

- fitted x center in pixels
- fitted y center in pixels
- fitted sky value in counts
- fitted sky sigma in counts
- moments analysis hwhm through largest aperture in iscale units
- moments analysis axis ratio through largest aperture
- moments analysis position angle through largest aperture in degrees
- object flux through largest aperture in counts
- magnitude through largest aperture
- magnitude error through largest aperture
- error code through largest aperture, 0 means no error

## Finding and Measuring Objects Automatically

Objects can be detected and measured automatically using the builtin object finding algorithm described in the Creating Objects Lists Automatically and Setting the Findpars Parameters sections, and the current values of the impars, cenpars, skypars, and photpars parameters.

To find and measure objects automatically using the Phot menu:

- move the mouse to the Phot menu button
- select the "Find and measure list" item

or alternatively type the keystroke command * in the image display window.

By default the sky and photometry apertures will be marked on the image display as the objects are detected and measured. In crowded fields users may wish to disable the object and sky marking options, and enable the center marking option instead. When the measurements are complete a message stating the number of detected objects will appear in the status line.

## Measuring Objects in the Objects List

To measure all the object in the object list using the Phot menu:

- move the mouse to the Phot menu button
- select the "Measure list" item

or alternatively type the keystroke command # in the image display window.

To measure the objects in the list sequentially using the Phot menu:

- move the mouse to the Phot menu button
- select the "Rewind list" item
- select the "Measure next" item
- repeat last command for remaining list objects

To select and measure objects in the objects list using the List panel:

- move the mouse to the Phot menu button
- select the "List panel ..." item
- move to the Measure List section of the list panel

The commands buttons Next, Prev, Restof, All can be used to measure the next list object, the previous list object, the remaining list objects, or the entire list. To select a particular object from the list, click on the object in the list and press the Current button.

The function of the objects list panel Next, Prev, Restof, and All commands buttons are duplicated by the o, -, +, and # keystroke commands executed in the image display window. The list object nearest the image cursor can be selected and measured using the . keystroke command.

To select and measure the list object nearest the image cursor using the image display menu:

- move to the image display window
- press the left mouse button
- select the "Measure nearest in list" item

## Measuring Objects Through the Objects List Marker

The object marker can be used to simultaneously visualize and measure objects in the object list. To use the object marker and Phot menu to measure objects from the object list.

- move the mouse to the Phot menu button
- select the "Show object marker" item
- select the "Measure next" item
- move the mouse to the object part of the object marker
- press the right mouse button
- select the "Measure next" item
- or type the o keystroke
- move the mouse to the Phot menu button
- select the "Dismiss object marker" item

## Viewing the Results

## The Status Line

As individual objects are measured the following quantities are printed in the image display window status line.

- fitted x center in pixels
- fitted y center in pixels
- fitted sky value in counts
- fitted sky sigma in counts
- moments analysis hwhm in iscale through largest aperture
- moments analysis axis ratio through largest aperture
- moments analysis position angle in degrees through largest aperture
- object flux in counts through largest aperture
- magnitude through largest aperture
- magnitude error through largest aperture
- error code through largest aperture, 0 means no error

The last measurement can be recalled at any time by selecting the "Display last result" item from the Results menu, or by typing the ; keystroke command in the image display window.

The status line cn be cleared by selecting the "Clear status line" item from the Results menu or by typing the ; keystroke command in the image display window.

If several objects in the object list are measured with a single command, then only the results of last measurement are printed in the status line.

The results of the automatic detection and measuring command are not printed to the status line. Instead a message stating the number of object that were detected and measured is printed. The last measurement may still be recalled and printed as described above.

## Graphics Overlay of Measured Objects

By default the sky and photometry apertures of the measured objects are marked on the image display. The default colors of the measurement colors are yellow and red, different from the colors blue and green colors used to mark the object list sky and object apertures.

To disable sky and photometry aperture marking and enable center marking instead using the Results menu:

- move to the Results menu button
- select the "Enable ctrmark" item
- select the "Disable skymark" item
- select the "Disable photmark" item

or edit the appropriate parameters in the cenpars, skypars, and photpars parameter sets. The default colors for all 3 marks can also be changed by editing the above parameter sets.

If the object list is detected and measured automatically, then the initial object list centers are also marked if the omarkpars parameter objmark is enabled.

## The Quick-Look Photometry Table

Xguiphot provides capabilities for displaying the quick-look results in tabular via a quick-look photometry table. To enable the photometry table using the <href="#grmenu">Results menu:

- move to the Results menu button
- select the "Photometry table ..." item

or alternatively, type the t keystroke command in the image display window.

If the table is enabled when a measurement is made then the following quantities are printed to the table where they can be examined.

- the image name
- fitted x center in pixels
- fitted y center in pixels
- fitted sky value in counts
- fitted sky sigma in counts
- moments analysis hwhm in iscale through largest aperture
- moments analysis axis ratio through largest aperture
- moments analysis position angle in degrees through largest aperture
- object flux in counts through largest aperture
- magnitude through largest aperture
- magnitude error through largest aperture
- filter id
- exposure time
- airmass
- time of observation
- logging status

If the quick-look photometry table is disabled at the time of measurements the results are not written to the table, although the last result may be recalled by select the "Display last result" item from the Results menu or by typing the ; keystroke command in the image display window.

The quick-look table is photometry table is most useful for making comparative measurements, e.g. repeated measurements of the same object with different parameter settings, or repeated measurements of the same object taken at different times, in different observing conditions, etc.

For reasons of efficiency it is a good idea to disable the quick-look table when making measurements of large numbers of objects simultaneously, and to clear the table using the Clear button when it becomes too large.

## The Quick-Look Photometry Plots

Xguiphot provides capabilities for displaying the quick-look results in graphical via quick-look photometry plots. To enable the photometry plots panel using the <href="#grmenu">Results menu:

- move to the Results menu button
- select the "Photometry plots ..." item

or alternatively, type the g keystroke command in the image display window.

If the plotting panel is enabled when a measurement is made then the following quantities are displayed by default in the plots panel:

- a multi-aperture analysis of the object
- the object region overlayed by the largest photometry aperture
- a major-axis plot of the object region
- the sky region overlayed by the sky aperture
- a histogram of the sky region

Each plot has an associated menu button which can be used change the default plot type. For example, it is possible to display the object or sky region in the from of a data subraster (with or without an object aperture or contour plot overlay), a contour plot, or a mesh plot; the sky analysis plot in the form of a histogram, a position angle profile, or a semi-major axis profile; and the object analysis plot in the form of a major-axis profile or a position angle profile. It is also possible to display the results of the moments analysis versus aperture radius.

Each plot has an associated Activate button. Pressing the Activate button activates IRAF cursor mode; pressing the Deactivate button deactivates it. In cursor mode the user can select different plots with the associated menu button; and use the builtin IRAF cursor mode keystroke commands to display the plot in various ways.

The multi-aperture analysis includes the following quantities:

- the x and y coordinates of the object aperture
- the x and y coordinates of the sky aperture
- the sky value, sky standard deviation, and number of good sky pixels
- the aperture radius in scale units
- the moments analysis hwhm in scale units as a function of radius
- the moments analysis axis ratio as a function of radius
- the moments analysis position angle in degrees as a function of radius
- the effective area of the aperture as a function of radius
- the object flux as a function of radius
- the object magnitude as a function of radius
- the object magnitude error as a function of radius

If the quick-look photometry plots panel is disabled at the time of measurement the results are not displayed in the panel, although the last result may be recalled by select the "Display last result" item from the Results menu or by typing the ; keystroke command in the image display window.

The quick-look photometry plots panel is most useful for examining the object and sky region in detail as measurements are made, for examining the often critical sky measurements more closely, and for examining the results of any multi-aperture analysis.

For reasons of efficiency it is a good idea to disable the quick-look photometry plots panel when making measurements of large numbers of objects simultaneously.

# The Xguiphot Default GUI

The GUI defined by the Xguiphot task parameter guifile whose default value is the builtin GUI file xapphot$gui/guifile.gui. The elements of the GUI are described below.

## The Xguiphot Control Panel

The Xguiphot control panel is the most important element of the Xguiphot GUI. The Xguiphot control panel is automatically activated when Xguiphot starts up, is visible at all times when Xguiphot is running, and is the last panel to deactivate when Xguiphot terminates: The Xguiphot control panel consists of the following elements:

The Main Menu and Command Bar
  The main menu and command bar consists of 7 menu buttons: Files, Images, Lists, Edit, Phot, Results, and Psets, and 2 command buttons: Help and Quit, which define the main menus and commands,

The Image Display Window
  The image display window displays the current image and accepts user commands in the form Four markers are associated with the image display window: the files marker, the coordinates marker, the status line, the objects list marker and the photometry marker.

## The Main Menus and Commands

The 7 main menus are: the Files menu, the Images menu, the Lists menu, the Edit menu, the Phot menu, the Results menu, and the Psets menu .

To select an item from one of the the main menus:

- move the mouse to the menu button
- press the left mouse button
- move the mouse to the desired menu item
- release the left mouse button

The function of a menu item preceded by a characters, e.g. item

    n | Next image

in the Files menu, can be duplicated by typing the character, i.e. the character n in the preceding example, in the image display window.

Menu items with trailing periods, e.g. item

      | Help ...

in the Files menu, either bring up a new panel or demand further action from the user. Menu items with a trailing solid right caret, e.g. item

      Edit >

in the Psets menu bring up a submenu.

The 2 main command buttons are: the Help button and the Quit button.

To use activate a command button:

- move the mouse to the command button
- press and release the left mouse button

### The Files Menu

The Files menu provides a selection of common file management functions. The following menu items are currently available.

    $ | Files panel ...                    # Activate the files panel
    n | Next image                         # Select next image
    p | Previous image                     # Select previous image
    ] | Next objects file                  # Select next objects file
    [ | Previous objects file              # Select previous objects file
      | Enable / Disable file logging      # Toggle output file logging
      | Help ...                           # Display help for files menu

More on selecting files can be found in the Setting the Image Directory, Setting the Image Template, Browsing the Image List, Browsing the Image Headers, Setting the Objects File Directory, Setting the Objects File Template, Browsing the Objects File List, Setting the Results File Directory, Setting the Output File Template, and Logging the Results sections.

### The Images Menu

The Images menu contains a selection of common image display and image browsing functions. The following menu items are currently available.

    n | Next image                        # Display next image
    p | Previous image                    # Display previous image
      | Dispars pset ...                  # Activate dispars pset editing panel
    i | Current image                     # Redisplay current image
      | Impars pset ...                   # Activate impars pset editing panel
    h | Display header ...                # Toggle image header display panel
    x | Compute model fit ...             # Print model fit results
    y | Show model fit ...                # Toggle model fit display panel
      | Options >                      # Display options submenu
      | Help ...                          # Display help for images menu

The options sub-menu contains the following choices.

        Show / Dismiss crosshair          # Toggle crosshair cursor
        Dismiss / Showfiles marker        # Toggle files marker
        Dismiss / Show coords marker      # Toggle coords marker
        Clear status line                 # Erase status line

Further information on browsing images and image headers can be found in the Browsing the Image List, Setting the Impars Parameters, and Browsing the Image Headers sections

Further information on interacting with the image display window and changing the default image display parameters can be found the sections on Setting the Dispars Parameters and Interacting with the Image Display.

Information on modeling objects and determining a good value for the impars ihwhmpsf parameter can be found in the section Estimating the Hwhm of the Psf.

More about the crosshair cursor, files marker, coordinates marker, and status line can be found in the Image Display Cursor, the Files Marker, the Coordinates Marker, and the Status Line sections.

### The Lists Menu

The object list creation menu contains a selection of object list creation and viewing functions. The following menu items are currently currently.

    l | List panel ...                Activate the list editing and viewing panel
    ] | Next file                     Select the next input objects file
    [ | Previous file                 Select the previous input objects file
    r | Current file                  Reread the current objects file
      | Impars pset ...               Activate the impars pset editing panel
      | Findpars pset ...             Activate the findpars pset editing panel
    @ | Find list                     Find objects and write to list
      | Draw list ...                 Activate the list drawing code
      | Omarkpars pset ...            Activate the omarkpars pset editing panel
    m | Mark list                     Mark list on the image display
    e | Erase list                    Erase marked list from the image display
    e | Help ...                      Display help for the lists menu

Further information on creating object lists can be found in the Creating Objects Lists from Object Files, Creating Objects Lists Automatically, Setting the Findpars Parameters, Creating Objects Lists with the Image Cursor, and. Creating Objects Lists with the Photometry Marker sections.

More information on overlaying the object list on the image display can be found in the Viewing the Image List, and Setting the Omarkpars Parameters sections.

### The Edit Menu

The Edit menu contains a selection of object list editing and viewing functions. The following menu items are currently available.

    l | List panel ...             Activate the list viewing and editing panel
      | Show object marker         Show / dismiss the object marker
    ^ | Rewind list                Rewind the objects list
    f | Next object                Select next object in list
    b | Previous object            Select previous object in list
    ~ | Nearest object ...         Select list object nearest cursor
    a | Add object(s) ...          Add objects to list graphically
    d | Delete object(s) ...       Delete objects from the list
    u | Undelete object(s) ...     Undelete deleted list objects
    z | Delete list                Delete entire list
      | Help ...                   Display help for lists menu

Further information on browsing, viewing, and editing objects lists can be found in the Browsing the Objects List, Deleting and Undeleting Objects from the Objects List, Adding Objects to the Objects List, and Saving Objects Lists ti Objects Files, sections.

### The Phot Menu

The Phot menu contains a selection of object measuring functions. The following menu items are currently available.

       | Impars pset ...             # Activate impars pset editing panel
       | Cenpars pset ...            # Activate cenpars pset editing panel
       | Skypars pset ...            # Activate skypars pset editing panel
       | Photpars pset ...           # Activate photometry parameters editing panel
    v  | Draw polygons ...           # Draw object or object / sky polygons
    Sp | Point and measure ...       # Measure object(s) nearest the cursor
       | Findpars pset ...           # Activate detection parameters editing panel
    *  | Find and measure            # Find and measure objects automatically
    #  | Measure list                # Measure existing object list
    l  | List panel ...              # Activate list panel
       | Show/Dismiss object marker  # Show / Dismiss object list marker
    ^  | Rewind list                 # Rewind objects list
    o  | Measure next                # Measure next in list
    +  | Measure rest of             # Measure rest of list
    -  | Measure previous            # Measure previous in list
    .  | Measure nearest             # Measure nearest in list
       | Help ...                    # Display help for phot menu

More information on setting the algorithm parameters can be found in the Setting the Impars Parameters, Setting the Cenpars Parameters, Setting the Skypars Parameters, and Setting the Photpars Parameters sections.

More on the various modes of making photometry measurements can be found in the Measuring Objects with the Image Cursor, Measuring Objects Through the Photometry Marker, Detecting and Measuring Objects Automatically, Measuring Objects in the Objects List, and Measuring Objects Through the Object List Marker sections.

### The Results Menu

The results menu contains a selection of results viewing functions The following menu items are currently available.

       | Enable / Disable logging    # Toggle results file logging
    CR | Clear status line           # Clear status line
    ;  | Display last result         # Display last result
       | Enable / Disable ctrmark    # Toggle object center marking
       | Disable / Enable skymark    # Toggle sky aperture marking
       | Disable / Enable photmark   # Toggle photometry aperture marking
    t  | Photometry table ...        # Display the photometry table panel
    g  | Photometry plots ...        # Display the photometry plots panel
       | Cplotpars ...               # Activate cplotpars pset editing panel
       | Splotpars ...               # Activate splotpars pset editing panel
       | Help ...                    # Display help for results menu

More on view the results can be found in the The Status Line, The Graphics Overlay, The Quick-Look Photometry Table, andThe Quick-Look Photometry Plots sections.

### The Psets Menu

The Psets menu contains a selection of parameter editing functions. The following menu items are currently available.

        Edit                        # Edit the selected psets
        Apply                       # Apply parameter changes to selected psets
        Cancel                      # Cancel parameter changes to selected psets
        Unlearn                     # Return selected psets to their default state
        Update                      # Update selected psets on disk
        Dismiss                     # Dismiss selected pset editing panels
        Help                        # Display help for psets menu

Each menu item above is actually a submenu of the following form:

        All
        Impars
        Dispars
        Findpars
        Omarkpars
        Cenpars
        Skypars
        Photpars
        Cplotpars
        Splotpars

More about parameter editing using the parameter editing panel can be found in the The Parameter Set Editing Panel section. The equivalent colon commands are listed in the Colon Commands section.

Information about setting the parameters to their optimal values can be found in the in the Setting the Impars Parameters, in the Setting the Dispars Parameters, in the Setting the Findpars Parameters, in the Setting the Omarkpars Parameters, Setting the Cenpars Parameters, Setting the Skypars Parameters, and Setting the Photpars Parameters sections. sections.

### The Help Command

The Help command is accessed from the Help command button in the main command bar. Hitting the help button beings up the Help panel, hitting the Help button again dismisses the Help panel. The ? keystroke command in the image display window performs the same function. When the help panel is activated from the main menu before, the help document comes up point to the Running Xguiphot with the GUI section

### The Quit Command

The Quit command is accessed from the Quit command button in the main command bar. Hitting the quit button will terminate the Xguiphot task immediately.

## The Image Display Window

The image display window is the most important window in Xguiphot. It displays the current input and output files in the files marker, the current image image in the graphics window, the current cursor position in the coordinates marker and current status messages if any in the status line.

When the image display cursor activates, the image display window is ready to accept user commands in the form of mouse clicks, task specific keystroke commands, IRAF builtin keystroke commands, task specific colon commands, and IRAF builtin colon commands.

### The Files Marker

The files marker is normally displayed in the upper left corner of the image display window. The files marker displays the current image name, the current objects file name, the results logging status, and the current output results file name. The displayed values cannot be altered by the user but will automatically update as the user browses the image list or input objects file list, or changes the default output results file.

To move the files marker:

- move the mouse into the files marker
- wait until cursor changes to small cross
- press the left mouse button
- drag the mouse to the new position
- release the left mouse button

To resize the files marker:

- move the mouse to the lower right corner of the files marker
- wait till cursor changes to box with 2 arrows
- press left mouse button to grab marker
- move mouse in or out to resize marker

To bring up the files marker menu and select an item:

- move the mouse into the files marker
- wait until cursor changes to small cross
- press the right mouse button
- select an item
- release the right mouse button

The current files marker menu is:

        Enable / Disable logging             # Enable / Disable results logging
        Help ...                             # Display help for files marker
        Dismiss marker                       # Delete the files marker

To delete the files marker:

- move the mouse into the files marker
- wait until cursor changes to small cross
- press the delete key

or select the "Dismiss marker" command from the files marker menu.

To reactivate the files marker:

- move the mouse to the Images menu button
- press the left mouse button
- select the Options submenu
- select the "Show files marker" item

For more on displaying the current input and output file names using the Files panel or colon commands see the Setting the Image Template, Setting the Objects Files Template, and Setting the Results Files Template sections.

### The Coordinates Marker

The coordinates marker is normally displayed in the lower right corner of the image display window. The coordinates marker tracks the position of the image display cursor in the image display window. If the cursor is in the part of the image display window containing the displayed image, the coordinate units are image pixels, otherwise they are in screen coordinates. Image pixel coordinates begin at 0.5,0.5 at the edge of the lower left corner of the image. Screen coordinates begin at 0,0 in the upper left hand corner of the image.

To move the coordinates marker around:

- move the mouse into the coordinates marker
- wait until cursor changes to small cross
- press the left mouse button
- drag the mouse to the new position
- release the left mouse button

To resize the coordinates marker:

- move the mouse to the lower right corner of the coordinates marker
- wait till cursor changes to box with 2 arrows
- press left mouse button to grab marker
- move mouse in or out to resize marker

To bring up the coordinates marker menu and select an item:

- move the mouse into the coordinates marker
- wait until cursor changes to small cross
- press the right mouse button
- select an item
- release the right mouse button

The current coordinates marker menu is:

        Help ...                             # Display help for coordinates marker
        Dismiss marker                       # Delete the coordinates marker

To delete the coordinates marker:

- move the mouse into the coordinates marker
- wait until cursor changes to small cross
- press the delete key

or select the "Dismiss marker" item from the coordinates marker menu.

To reactivate the coordinates marker:

- move the mouse to the Images menu button
- press the left mouse button
- select the Options submenu
- select the "Show coords marker" item

### The Status Line

The status line is an area the width of the image display window and several pixels high located at the bottom of the image display window. Normally invisible it highlights when a warning message is printed, when Xguiphot issues a prompt string, when the user types a colon command, or and when quick-look results are printed.

To erase the status line:

- move the mouse to the Images menu button
- press the left mouse button
- select the Options submenu
- select the "Clear status line" item

or

- move the mouse to the Results menu button
- press the left mouse button
- select the "Clear status line" item
- release the left mouse button

or

- move the mouse into the image display window
- press the Return key

To recall the last photometric measurement to the status line:

- move the mouse to the Results menu button
- press the left mouse button
- select the "Redisplay last result" item
- release the left mouse button

or

- move the mouse into the image display window
- press the ; key

To input a colon command from the status line:

- move the mouse into the image display window
- type : followed by the command, e.g. :imname

### The Image Display Cursor

When the image display cursor is active and ready to accept user commands in the image display window it is displayed as a small white open circle. When the image display cursor is busy or deactivated it is displayed as a small filled in black cross.

In some cases a crosshair cursor can be more useful that the default circle. To change the default image display cursor from a circle to a crosshair:

- move the mouse to the Images menu button
- press the left mouse button
- select the "Options" submenu
- select the "Show crosshair" menu item
- release the left mouse button

To recall the default cursor repeat the above commands, replacing the "Show crosshair" menu item with the "Dismiss crosshair" item.

To track the cursor coordinates in image pixel units

- move the mouse to image display window
- move to the object of interest in the displayed image

The pixel coordinates are displayed in the coordinates marker. If the coordinates marker has been dismissed, it it can be reactivated by selecting the "Show coords marker" item in the Images menu Options submenu.

To print the current position of the image display cursor in the status line:

- move the mouse into the image display window
- position the image cursor
- type the C keystroke command

### The Image Display Menu

The mouse can be used to perform several important image display functions.

To window the image display:

- move the mouse into the image display
- press the right mouse button
- drag the mouse around
- release the right mouse button

To pan the image:

- move the mouse to the desired position in the the image display
- click the middle mouse button

To zoom up:

- move the mouse to the desired position in the the image display
- click the middle mouse button twice

To zoom down:

- move the mouse to the desired position in the the image display
- hold down the Shift key
- click the middle mouse button

To return to the default zoom:

- move the mouse to the desired position in the image display window
- hold down the Control key
- click the middle mouse button

More displaying images can be found in the Interacting with the Image Display and Setting the Dispars Parameters sections.

To activate the image display menu:

- move the mouse to the image display window
- press the left mouse button
- select the desired menu item
- release the left mouse button

The following menu items are currently available.

    Sp | Point and measure                 # Measure object nearest the cursor
     . | Measure nearest in list           # Measure list object nearest the cursor
     ~ | Find nearest in list              # Locate list object nearest the cursor
     d | Delete nearest in list            # Delete list object nearest the cursor
     u | Undelete nearest in list          # Undelete list object nearest the cursor
       | Show / Dismiss phot marker        # Activate / deactivate the phot marker
       | Align / Offset photsky marker     # Align / offset the photsky marker
       | Set offset / concentric sky       # Toggle the sky fitting mode
     x | Compute model fit                 # Fit gaussian to nearest object
     y | Show / Dismiss model plot ...     # Toggle model fit plotting

Note that most of these commands use the current cursor position as an initial position in some way, e.g. the measure, list editing, and model fit commands use the the cursor x and y position as an initial position. The photometry marker commands activate or move the marker to the position of the cursor.

For more about selecting and measuring objects with the cursor go to the Measuring Objects with the Image Cursor and Measuring Objects in the Objects List sections.

For more about locating objects in the objects list and deleting or undeleting objects from the objects list go to the Browsing the Objects List and Deleting and Undeleting Objects from the Objects List sections.

For more about creating and manipulating the photometry marker go to the The Photometry Marker section. For information on using the photometry marker to create objects lists see the Creating Objects Lists with the Photometry Marker and Adding Objects to the Objects List sections.

For information on how to use the photometry marker to make quick-look measurements go to the Measuring Objects Through the Photometry Marker section.

### The Xguiphot Keystroke Commands Summary

Many Xguiphot functions have associated keystroke accelerator commands. To execute these functions using the keystroke accelerators rather than the using the main menus, move to the image display window and type the keystroke. The following Xguiphot keystroke accelerators are defined:

    General commands
        ?  Toggle help panel            Q  Quit task
        $  Toggle files panel           :  Colon command
       CR  Erase status line

    Image display commands
        i  Redisplay current image      h  Toggle image header panel
        n  Display next image           p  Display previous image
        x  Model nearest object         \X Refit previous object
        y  Toggle model fitting panel

    Object list creation and display Commands
        l  Toggle objects list panel    r  Reread current objects file
        ]  Read next objects file       [  Read previous objects file
        @  Autofind objects list      z,a  Draw objects list
        m  Mark objects list            e  Erase objects list

    Object list editing commands
        ^  Rewind object list           ~  Move to nearest list object
        f  Move to next list object     b  Move to previous list object
        z  Delete entire objects list   d  Delete nearest list object
        u  Undelete nearest list object a  Add object to list

    Object measurement commands
       SP  Measure nearest object       v  Draw object and sky polygons
        *  Find and measure objects     #  Measure object list
        o  Measure next list object     -  Measure previous list object
        +  Measure rest of list         .  Measure nearest list object

    Results display commands
        t  Toggle tables panel
        g  Toggle plots panel           G  Replot
       CR  Erase status line            ;  Display last measurement

### The Cursor Mode Keystroke Commands

The IRAF builtin cursor mode keystroke commands are available in any active graphics window including the image display. To execute the command move to the graphics window and type the keystroke. The following builtin cursor keystrokes are currently available.

        A  Draw and label axes          B  Backup over last instruction
        C  Print the cursor position    D  Draw a line segment
        E  Expand the plot              F  Set fast cursor
        H  Step cursor left             J  Step cursor down
        K  Step cursor up               J  Step cursor right
        M  Pan                          P  Zoom out
        R  Redraw                       T  Draw text at cursor
        U  Undo last edit               V  Set slow cursor
        W  Set wcs at cursor            X  Zoom in in x
        Y  Zoom in in y                 Z  Zoom in
        <  Set lower limit of plot to y >  Set upper limit of plot to y
        \  Escape next character        :. Cursor mode colon command
        =  Draw a plot                  0  Reset and redraw

Users should be aware that not all the keys are yet fully functional for the image display window and the zoomed up image displays of the object and sky region in the photometry plots panel. In particular it is not yet possible to produce hardcopies of the image display with the = keystroke.

### The Xguiphot Colon Commands

Many Xguiphot commands have associated colon commands. Most but not all of these are parameter showing and setting commands. To execute these commands using colon commands rather using menu items or the parameter editing panels move to the image display window and type the command. The following Xguiphot colon commands are defined:

    File Management Colon Commands

        :images   [template]    Show / Set a new image template
        :objects  [template]    Show / Set a new objects file template
        :results  [template]    Show / Set a new results file template
        :robjects [template]    Show / Set a new output objects file template
        :imname   [name]        Show / Select the current image
        :olname   [name]        Show / Select the current objects file
        :rlname                 Show the current results file
        :glname                 Show the current output objects file
        :imnumber [number]      Show / Select the current image number
        :olnumber [number]      Show / Select the current objects file number
        :rlname                 Show the current results file number
        :glname                 Show the current output objects file number
        :logresults [yes/no]    Log the results to the results file ?

    Object List Management Commands

        :oselect   number      Select the current object
        :odelete   number      Delete the current object
        :oundelete number      Undelete the current object
        :oadd      geometry    Add object to object list
        :osave     file        Save current object list to objects file

    Impars Parameter Colon Commands

       :iscale      [value]    Show / Set the image scale
       :ihwhmpsf    [value]    Show / Set the hwhm of the psf
       :iemission   [yes/no]   Show / Set emission features switch
       :iskysigma   [value]    Show / Set the sigma of the background
       :imindata    [value]    Show / Set the minimum good data value
       :imaxdata    [value]    Show / Set the maximum good data value

       :inoisemodel [name]     Show / Set the noise model
       :ikgain      [value]    Show / Set the CCD gain keyword
       :ikreadnoise [value]    Show / Set the CCD readout noise keyword
       :igain       [value]    Show / Set the CCD gain in e-/ADU
       :ireadnoise  [value]    Show / Set the CCD readout noise in e-

       :ikexptime   [value]    Show / Set the exposure time keyword
       :ikairmass   [value]    Show / Set the airmass keyword
       :ikfilter    [value]    Show / Set the ifilter id keyword
       :ikobstime   [value]    Show / Set the time of observation keyword
       :ietime      [value]    Show / Set the exposure time
       :iairmass    [value]    Show / Set the airmass value
       :ifilter     [value]    Show / Set the ifilter id
       :iotime      [value]    Show / Set the time of observation

       *Permitted values of inoisemodel are: "poisson".

    Dispars Parameter Colon Commands

       :derase      [yes/no]   Show / Set the erase status
       :dfill       [yes/no]   Show / Set the fill status
       :dxviewport  [value]    Show / Set the x viewport
       :dyviewport  [value]    Show / Set the y viewport
       :dxmag       [value]    Show / Set the x magnification
       :dymag       [value]    Show / Set the y magnification

       :dztransform [name]     Show / Set the intensity transform
       :dzlimits    [name]     Show / Set the intensity limits algorithm
       :dzcontrast  [value]    Show / Set the intensity contrast
       :dznsample   [value]    Show / Set the number of sample lines
       :dz1         [value]    Show / Set the minimum intensity level
       :dz2         [value]    Show / Set the maximum intensity level
       :dlutfile    [value]    Show / Set the user lookup table file
       :drepeat     [yes/no]   Show / Set repeat status

       *Permitted values of dztransform are: "linear", "log", and "none".
       *Permitted values of dzlimits are: "median", "image", and "user".

    Findpars Parameter Colon commands

       :fthreshold  [value]    Show / Set the detection threshold
       :fradius     [value]    Show / Set the fitting radius
       :fsepmin     [value]    Show / Set the minimum separation
       :froundlo    [value]    Show / Set the lower ellipticity limit
       :froundhi    [value]    Show / Set the upper ellipticity limit
       :fsharplo    [value]    Show / Set the lower sharpness limit
       :fsharphi    [value]    Show / Set the upper sharpness limit

    Omarkpars Parameter Colon Commands

       :objmark     [yes/no]   Show / Set the object marking switch
       :otolerance  [value]    Show / Set the object matching tolerance
       :ocharmark   [value]    Show / Set the object marking parameter
       :onumber     [yes/no]   Show / Set the object numbering switch
       :opcolormark [value]    Show / Set the object mark color
       :oscolormark [value]    Show / Set the sky mark color
       :osizemark   [value]    Show / Set the mark size

       *Permitted values of ocharmark are: "point", "box", "cross", "plus",
       "circle", "diamond", and "shape".
       *Permitted values of opcolormark and oscolormark are: "red", "blue",
       "green", and "yellow".

    Cenpars Parameter Colon Commands

        :calgorithm [value]    Show / Set the centering algorithm
        :cradius    [value]    Show / Set the centering radius
        :cthreshold [value]    Show / Set the centering threshold
        :cminsnrati [value]    Show / Set the minimum signal-to-noise ratio
        :cmaxiter   [value]    Show / Set the maximum number of iterations
        :cxyshift   [value]    Show / Set the maximum x or y coordinate shift

        :ctrmark    [yes/no]   Show / Set the center marking switch
        :ccharmark  [value]    Show / Set the center marking character
        :ccolormark [value]    Show / Set the center mark color
        :csizemark  [value]    Show / Set the center mark size

        *Permitted values of calgorithm are: "none", "centroid1d", "gauss1d",
        and "ofilter1d".
        *Permitted values of ccharmark are: "point", "box", "cross", "plus",
        "circle", and "diamond".
        *Permitted values of ccolormark are: "red", "blue", "green" and
        "yellow".

    Skypars Parameter Colon Commands

        :smode      [value]    Show / Set the sky fitting mode
        :sgeometry  [value]    Show / Set the sky fitting geometry
        :srannulus  [value]    Show / Set the inner radius of sky annulus
        :saxratio   [value]    Show / Set the sky annulus axis ratio
        :sposangle  [value]    Show / Set the sky annulus p.a. in degrees

        :salgorithm [value]    Show / Set the sky fitting algorithm
        :sconstant  [value]    Show / Set the constant for constant sky fitting
        :shwidth    [value]    Show / Set the half-width of histogram in sigma
        :shbinsize  [value]    Show / Set the resolution of histogram in sigma
        :shsmooth   [yes/no]   Show / Set the histogram smoothing switch
        :smaxiter   [value]    Show / Set the max number of fitting iterations

        :sloclip    [value]    Show / Set the lower clipping factor in %
        :shiclip    [value]    Show / Set the upper clipping factor in %
        :snreject   [value]    Show / Set the max number of rejection iterations
        :sloreject  [value]    Show / Set the lower k-sigma rejection limit
        :shireject  [value]    Show / Set the upper k-sigma rejection limit
        :srgrow     [value]    Show / Set the region growing radius

        :skymark    [yes/no]   Show / Set the sky marking switch
        :scolormark [value]    Show / Set the sky aperture mark color

        *Permitted values of smode are: "concentric" and "offset".
        *Permitted values of sgeometry are: "circle", "ellipse", "rectangle",
        and "polygon".
        *Permitted values of salgorithm are: "zero", "constant", "mean",
        "median", "mode32", "hcentroid", "hgauss", "hofilter", "hcrosscor".
        *Permitted values of scolormark are: "read", "blue", "green", and
        "yellow".

    Photpars Parameter Colon Commands

        :pgeometry  [value]    Show / Set the photometry aperture geometry
        :papertures [value]    Show / Set the photometry apertures
        :paxratio   [value]    Show / Set the photometry aperture axis ratio
        :pposangle  [value]    Show / Set the aperture position angle in degrees
        :pzmag      [value]    Show / Set the photometry zero point
        :photmark   [yes/no]   Show / Set the photometry aperture marking switch
        :pcolormark [value]    Show / Set the photometry aperture mark color

        *Permitted values of pgeometry are: "circle", "ellipse", "rectangle",
        and "polygon".
        *Permitted values of pcolormark are: "red", "blue", "green", and
        "yellow".

    Cplotpars Parameter Colon Commands

        :enx        [value]    Show / Set number of columns to be contoured
        :eny        [value]    Show / Set number of lines to be contoured
        :ez1        [value]    Show / Set minimum greylevel to be contoured
        :ez2        [value]    Show / Set maximum greylevel to be contoured
        :ez0        [value]    Show / Set the greylevel of the zero contour
        :encontours [value]    Show / Set the number of contours to be plotted
        :edz        [value]    Show / Set the contour greylevel interval
        :ehilomark  [value]    Show / Set the high / low contour marking option
        :edashpat   [value]    Show / Set the bit pattern for drawing lines
        :elabel     [yes/no]   Show / Set the major contours labeling switch
        :ebox       [yes/no]   Show / Set the box drawing switch
        :eticklabel [yes/no]   Show / Set the tick mark labeling switch
        :exmajor    [value]    Show / Set the number of major x axis divisions
        :exminor    [value]    Show / Set the number of minor x axis divisions
        :eymajor    [value]    Show / Set the number of major y axis divisions
        :eyminor    [value]    Show / Set the numver of minor y axis divisions
        :eround     [yes/no]   Show / Set the axis rounding switch
        :efill      [yes/no]   Show / Set viewport filling switch

        *Permitted values of ehilomark: "none", "hilo", and "pixel".

    Splotpars Parameter Colon Commands

        :anx        [value]    Show / Set number of columns to be plotted
        :any        [value]    Show / Set number of lines to be plotted
        :az1        [value]    Show / Set minimum greylevel to be plotted
        :az2        [value]    Show / Set maximum greylevel to be plotted
        :alabel     [yes/no]   Show / Set the axes drawing switch
        :angv       [value]    Show / Set the vertical viewing angle
        :angh       [value]    Show / Set the horizontal viewing angle

### The Cursor Mode Colon Commands Summary

The IRAF builtin cursor mode colon commands are available in any active graphics window including the image display. To execute the command move to the graphics window and type the colon command. The following builtin colon commands are currently available.

    :.axes[+-]              Draw axes of viewport whenever screen is redrawn
    :.case[+-]              Enable case sensitivity for keystrokes
    :.clear                 Clear alpha memory (e.g, this text)
    :.cursor n              Select cursor
    :.gflush                Flush plotter output
    :.help                  Print help text for cursor mode
    :.init                  Initialize the graphics system
    :.markcur[+-]           Mark cursor position after each cursor read
    :.off [keys]            Disable selected cursor mode keys
    :.on [keys]             Enable selected cursor mode keys
    :.page[+-]              Enable screen clear before printing help text
    :.read file             Fill frame buffer from a file
    :.show                  Print cursor mode and graphics kernel status
    :.snap [device]         Make hardcopy of graphics display
    :.txqual qual           Set character generator quality (normal,l,m,h)
    :.txset format          Set text drawing parameters (size,up,hj,vj,etc)
    :.xres=value            Set X resolution (stdgraph only)
    :.yres=value            Set Y resolution (stdgraph only)
    :.viewport x1 x2 y1 y2  Set workstation viewport in world coordinates
    :.write[!][+] file      Save frame buffer in a spool file
    :.zero                  Set viewport and redraw frame

Users should be aware that not all the commands are yet fully functional for the image display window and the zoomed up image displays of the object and sky region in the photometry plots panel. In particular it is not yet possible to produce hardcopies of the image display with the :.snap command.

### The Object List Marker

The object list marker is used to mark the object and sky apertures of the current object in the object list. The object list marker can be created, redrawn, and destroyed by the user, but cannot be moved to an arbitrary position, resized, rotated or have its native geometry changed. The geometry of the object list marker is defined by the object list. If the object list entry is incomplete the geometry parameters in the photpars and skypars parameter sets are used to draw the marker.

To activate the object list marker:

- move the mouse to Edit or Phot menu button
- press the left mouse button
- select the "Show object marker" item
- release the left mouse button

or

- move the mouse to the Edit menu
- press the left mouse button
- select the "List panel ..." item
- release the left mouse button
- move the mouse to the "View and Edit" section of the List panel
- press the Show object marker button

The marker will remain invisible if the current object is undefined, i.e. the object list pointer is located at the beginning or end of the list, but will appear as soon as a current object is defined, e.g if the f key is typed in the image display window or the "Next object" item is selected from the Edit menu. By default the object and sky parts of the marker take on the colors specified by the omarkpars opcolormark and oscolormark parameters.

Every attempt has been made to ensure that the object list marker resizes and redraws correctly if the image display window is resized manually, or if the displayed image is zoomed, panned, etc.

The object list marker menu contains a selection of single object object list viewing, editing, and measuring functions, plus a small number of marker manipulation functions.

To use the object marker menu:

- move the mouse into the object part of the object marker
- press the right mouse button
- select the desired menu item
- release the right mouse button

The following menu items are currently available.

    f | Select next object                # Move to next object in object list
    b | Select previous object            # Move to previous object list object
    ~ | Select current object             # Select current object list object
    d | Delete current object             # Delete current object list object
    u | Undelete current object           # Undelete deleted object list object
    o | Measure next object               # Measure next object in object list
    - | Measure previous object           # Measure previous object in object list
    . | Measure current object            # Measure current object in object list
      | Object region colors              # Set object region marker colors
      | Sky region colors                 # Set sky region marker colors
      | Redraw marker                     # Redraw the marker
      | Dismiss the marker                # Dismiss the marker

Note that the keystroke accelerators associated with the menu items are the same as those that would be typed directly in the image display window, i.e. typing d in the object marker is the same as moving to the same object in the image display window and typing d if the marker were not there.

To delete the object marker:

- move the mouse into the object part of the object marker
- press the delete key

or alternatively select the "Dismiss marker" item in the object marker menu, select the "Dismiss object marker" item from the Edit or Phot menus, or press Dismiss marker button in the List panel.

More about using the object list marker to browse and measure objects in the object list can be found in the Browsing the Objects List and Measuring Objects Through the Object List Marker sections.

### The Photometry Marker

The photomery marker can be used to view and edit the default object and sky aperture geometry. Unlike the object list marker the photometry marker may be created, relocated, resized, rotated, redrawn, and destroyed by the user. The default geometry of the photometry marker is the geometry defined by the photpars and skypars object and sky geometry parameters. If the default object or sky geometry is polygonal, the user must define the object and sky polygons using either select the "Draw polygons ..." item in the Phot menu or type the v keystroke command in the image display window, before attempting to activate the marker. Otherwise the marker geometry will default to rectangular.

If the sky fitting mode is concentric the sky portion of the photometry marker will activate concentric with the object portion; otherwise only the object portion will activate. To quickly toggle between concentric and offset sky fitting mode:

- move the mouse to the image display window
- press the left mouse button
- select the "Set offset / annular sky" item
- release the left mouse button

or either edit the smode parameter in the skypars parameter set, or type the colon command ":smode offset" or ":smode concentric" in the image display window.

To activate the photometry marker:

- move the mouse to the desired position in the image display window
- press the left mouse button
- select the "Show phot marker"
- release the left mouse button

To activate the offset sky marker if the photometry marker was created in offset sky mode or if the sky fitting mode was changed from concentric to offset while the marker was active:

- move the mouse to the desired sky position in the image display window
- press the left mouse button
- select the "Offset photsky marker" item
- release the left mouse button

To realign the sky marker if the the sky fitting mode was changed from offset to concentric while the marker was active and offset:

- move the mouse to the image display window
- press the left mouse button
- select the "Align photsky marker"
- release the left mouse button

The marker is active and ready to accept commands when its border highlights and the cursor changes as the mouse is moved in and out of the marker. If several markers are stacked together as is often the case for the photometry marker, then the one whose border is highlighted is the one ready to accept commands. If the desired marker is not currently the active marker and moving into does not make it so, then click the middle mouse button to lower the current marker to the bottom of the stack until the desired marker is active, or the click left mouse button to raise the current marker to the top of the stack until the desired marker is active.

To move the photometry marker from one place to another:

- move the mouse into the object part of the photometry marker
- wait until the marker highlights and the cursor changes to a cross
- press down on the left mouse button
- drag the object marker to the new position
- release the left mouse button

If the sky fitting mode is concentric the sky markers will automatically shift to the new position along with the object region, otherwise only object marker will shift. The sky markers can be moved in the same fashion if the sky fitting mode is offset. If the inner sky region marker is moved the outer sky marker will automatically shift with it and vice versa.

To rotate the photometry marker:

- move the mouse to the boundary of the object marker
- wait until it changes shape to a box containing a . or a box with arrows
- press down on the Shift key
- press down on the left mouse button
- rotate the object marker to the new position by moving the mouse
- release the left mouse button

If the sky fitting mode is concentric that the sky region markers will rotate to match the new orientation of the object marker, otherwise only the object marker will rotate. The sky markers can be rotated in the same manner. If the inner sky region marker is rotated the outer sky region marker will be rotated to match it and vice versa.

To resize the photometry marker:

- move the mouse to the boundary of the object marker
- wait until it changes shape to a box containing a . or a box with arrows
- press down on the left mouse button
- drag the object marker to its new shape
- release the left mouse button

If the sky fitting mode is concentric then the sky markers will resize so as to try and preserve the distances between the object marker and the inner sky marker and the inner and outer sky markers, otherwise only the object marker will resize. The sky markers can be resized in the the same manner. If the inner sky marker is resized the outer will resize so as to try and preserve the distance between them. If the outer sky marker is resized it is restricted to being larger than the inner sky marker, and the inner sky marker is unaltered.

Polygon markers are currently a special case. They must be drawn and stored by the user using the Phot menu "Draw polygons ..." item or the v keystroke command prior to activating the photometry marker. If a polygon marker is requested but none has been defined then a rectangular marker will be created instead. Polygon markers can be moved, rotated, and resized just like any other marker. However at present the user cannot add and subtract vertices from the polygon marker interactively, although the IRAF Xgterm widget does provide support for this operation.

Every attempt has been made to ensure that the photometry marker resizes and redraws correctly if the image display window is resized manually or the displayed image is zoomed, panned, etc.

To select and item from the photometry marker menu:

- move the mouse into the object part of the marker
- wait until the marker changes to a small cross
- press the right mouse button
- select the desired item
- release the right mouse button

        Measure                        Measure object at marker position
        Object geometry                Set the object region marker geometry
        Sky geometry                   Set the sky region marker geometry
        Object colors                  Set the object region marker colors
        Sky colors                     Set the sky region marker colors
        Redraw marker                  Redraw the marker
        Save to object list            Save marker x,y,geometry to objects list
        Save to psets                  Save marker geometry to skypars and photpars
        Help ...                       Display help
        Dismiss marker                 Dismiss marker

The menu Measure item measures the object at the position of the photometry marker using the geometry defined by the marker not the geometry in the skypars and photpars parameter sets. Note that even if the marker was created using that geometry, there will still be minor differences because of precision problems in reading back the marker geometry.

The object and sky marker geometries can be modified using the "Object geometry" and "Sky geometry" menu items. Markers can be transformed to and from the shapes "circle", "ellipse", "rectangle", and "polygon". However if a polygon was not defined by the user prior to requesting a polygonal marker a rectangular marker will be created.

By default the object and sky parts of the marker take on the colors specified by the photpars pcolormark parameter and the skypars and scolormark parameters. The default colors can be changed by selecting the "Object colors" and "Sky colors" submenus.

To delete the photometry marker:

- move the mouse into the object part of the marker
- hit the Delete key

or select the "Dismiss marker" item from the the photometry marker menu, or select the "Dismiss phot marker" from the image display menu.

More about how to use the photometry marker to create and edit the objects list and to make photometry measurements can be found in the Creating the Objects List with the Photometry Marker, Adding Objects to the Objects List, and Measuring Objects Through the Photometry Marker sections.

## The Control Panels

### The Help Panel

The help panel permits the user to view the on-line help document while Xguiphot is running. The help panel can be activated by pressing the help command button in any Xguiphot panel, by selecting the "Help ..." item from and Xguiphot menu, or by typing the ? keystroke command in the image display window. The help panel consists of the the help command button bar and the help display window which are described below.

The Help Command Button Bar
  The command button bar contains the following command buttons.

  The Back Command Button
    Pressing the Back command button moves backwards through the previously visited links.

  The Forward Button
    Pressing the Forward command button moves forward through the list of visited links.

  The Home Button
    Pressing the Home command button sets the help display window to the "Running Xguiphot with the GUI" section.

  The Toc Button
    Pressing the TOC command button sets the help display window to the Table of Contents section.

  The Reset Button
    Pressing the Reset command button erases the list of visited links.

  The Help Button
    Pressing the Help command button sets the help display window to the "The Help Panel" section.

  The Dismiss Button
    Pressing the Dismiss command button deactivates the help panel.

Help Display Window
  The help display window consists of a single HTML widget. Users can scroll through the text, click on the scrollbars, or click on the high-lighted links in the usual manner.

### The Files Panel

The files panel permits the user to view and edit the current input and output data directories and the current input and output image and file name templates, and select the current input image, the current input objects file, and the current results file. The files can be activated by selecting the "Files panel ..." item in the Files menu, or by typing the $ keystroke command in the image display window. The files panel is divided into 5 sections: the current directory listing section, the input images section, the input objects file section, the output results file section, and the files command button bar.

The Current Directory Listing Section
  The current directory listing section consists of the following 2 elements:

  The Current Dir Entry Box
    Entering a new current directory specification into the Current Dir entry box and hitting Return sets the new directory and re-expands the input image, input object file, and results file templates.

  The Subdirectory Listing
    Clicking on a new subdirectory item expands the subdirectory listing but does not re-expand the input image, input object file, or results file template. The text of the Current Dir entry box values changes from black to white to indicate that the current directory listing is out of date.

The Input Images Section
  The input images section consists of the following 3 elements:

  The Dir Entry Box
    Entering a new directory specification into the Dir entry box and hitting Return enters the new directory specification in all the files panel Dir entry boxes. The new directory specification will be prepended to the current Images, Objects, Results, and Robjects entry box values when the Apply button is pressed.

  The Images Entry Box
    Entering a new images template into the Images entry box and hitting return updates the input image, the input objects file, and output results file lists and selects a new current image, a new current input objects file, and new current output results files.

  The Image List
    Clicking on a new image name in the image list selects a new current image, displays the selected image in the image display window, and selects new default input objects and output results files. The builtin scroll bars can be used to scroll through the images list.

  More on defining the default global and / or image directories, defining the image list, and selecting the current image can be found in the Setting the Image Directory, Setting the Image Template, Browsing the Image List Sections, Browsing the Image Headers, section.

The Input Objects File Section
  The input objects file section consists of the following 3 elements:

  The Dir Entry Box
    Entering a new directory specification into the Dir entry box and hitting Return will enter a new input objects file directory specification. The new directory specification will be prepended to the current Objects entry box value when the Apply button is pressed.

  The Objects Entry Box
    Entering a new input objects file template into the Objects entry box and hitting return updates the input objects file list and selects a new current input objects file.

  The Input Objects File List
    Clicking on a new objects file name in the objects file list selects a new current input objects file. The builtin scroll bars can be used to scroll through the input objects file list.

  More on defining the default objects file directory, defining the object file list, and selecting the current input objects file can be found in the Setting the Objects File Directory, Setting the Objects File Template, and Browsing the Objects File List sections.

The Output Results File Section
  The output results file section consists of the following 7 elements.

  The Log Results Command Button
    Pressing the log results command button toggles results file logging.

  The Results Dir Entry Box
    Entering a new directory specification into the Results Dir entry box and hitting Return enters a new global results directory specification. The new directory specification will be prepended to the current Results and Robjects entry box values when the Apply button is pressed.

  The Robjects Dir Entry Box
    Entering a new directory specification into the robjects Dir entry box and hitting Return will enter a new robjects file directory specification. The new directory specification will be prepended to the current Robjects entry box value when the Apply button is pressed.

  The Results Entry Box
    Entering a new results file template into the Results entry box and hitting return updates the results file list and selects a new current output results file.

  The Robjects Entry Box
    Entering a new robjects file template into the Robjects entry box and hitting return updates the robjects file list and selects a new current output objects file.

  The Current Results File
    The current output results file is displayed in the deactivated entry box under the results entry box.

  The Current Robjects File
    The current output robjects file is displayed in the deactivated entry box under the robjects entry box.

  More on defining the default results file directory, defining the results file list, setting the current output results file, and enabling and disabling results file logging can be found in the Setting the Results File Directory, Setting the Results File Template, and Logging the Results sections.

The Files Command Button Bar
  The command button bar contains the following command buttons:

  The Apply Button
    Pressing the Apply button updates the input image, the input objects file, and output results file lists and selects a new current image, input objects file, and output results files.

  The Cancel Button
    Pressing the Cancel button cancels all changes since the last Apply button press.

  The Defaults Button
    Pressing the Defaults button resets the directory and image and file templates to their default settings, updates the input image, the input objects file, and output results file lists, and selects a new current image, a new current input objects file, and new current output results files.

  The Help Button
    Pressing the Help button activates the help panel and sets the help text to the "Files Panel" section.

  The Dismiss Button
    Pressing the Dismiss button deactivates the files panel.

### The Image Header Panel

The image header panel permits the user to scroll through the header of the currently displayed image. The image header panel can be activated by selecting the "Display header ..." item from the Images menu or by typing the h keystroke command in the image display window. The image header panel consists of:

The Title Bar
  The title bar displays the name of the current image.

The Header Display Window
  The header display window consists of 2 scrollbars and a text area.

The Command Button Bar
  The command button bar contains 4 command buttons:

  The Next Button
    Pressing the Next button displays the next image and image header.

  The Prev Button
    Pressing the Prev button displays the previous image and image header.

  The Help Button
    Pressing the Help button points the help text to the "Image Header Panel" section

  The Dismiss Button
    Pressing the Dismiss button deactivate the image header panel.

More information on examining the image headers can be found in the Browsing the Image Headers and Setting the Impars Parameters sections.

### The Parameter Editing Panel

The parameter editing panel permits the user to view and / or edit the a parameter set. Parameter editing panels can activated from selected main menu buttons, e.g. the findpars pset can be activated from the Lists or Phot main menus. Any parameter set can be viewed, edited, and dismissed from the Psets menu.

The parameter editing panel consists of the following elements:

The Title Bar
  The title bar displays the title of the parameter set being edited.

The Parameter Groups
  The parameters in a pset may be divided into subgroups for ease of interpretation. Each subgroup has a title and is surrounded by a frame. For example the image display parameters dispars are subdivided into two groups, one describing the spatial transformation, and the other describing the intensity transformation. Each parameter within a group is defined by a descriptive phrase, a data entry box, and a name. There are 3 types of data entry boxes:

  Boolean
    Boolean parameters have yes or no values. When the boolean data entry box is ready to accept input it highlights. Clicking the left mouse button on a boolean entry box toggles the parameter value. An example of a boolean parameter in the dispars parameter set is the dfill parameter.

  Enumerated
    Enumerated parameters have a finite list of permitted values. When an enumerated parameter data entry box is ready to accept input it highlights. Clicking the left mouse button on an enumerated entry box will bring up a menu of permitted values. Moving to the new value and releasing the left mouse button will select the new value. An example of an enumerated parameter in the dispars parameter set is the dztransform parameter.

  Text
    Text parameters are character strings, usually but not necessarily representing a numerical value. When a text entry box is ready to accept input the caret appears at the position of the cursor. Deleting the existing value, typing in a new value, and pressing Return will enter the new value. Existing values can be deleted by moving the caret to the beginning of the value and typing Control K key, or by moving the caret to the end of the existing string and typing BackSpace or Delete to delete characters one at a time. Example of text parameters are the dispars parameters dz1 and dz2.

  If one or more new parameter values have been entered into the pset editing panel, but not yet entered into memory with the Apply button, the Apply button label and the new parameter values will be white instead of black and in order to alert the user that the new parameter values are not the current values.

The Command Button Bar
  The command button bar contains 6 required command buttons and may contain 0 or more pset specific command buttons. The required command buttons are:

  The Apply Button
    Pressing the Apply button writes any new parameter values to memory.

  The Cancel Button
    Pressing the Cancel button cancels changes made since the last Apply.

  The Unlearn Button
    Pressing the Unlearn button restores the parameter values to their default state.

  The Update Button
    Pressing the Update button copies the current parameter values in memory to their corresponding parameter files on disk. Users need to be aware of possible conflicts with the Xguiphot task update parameter which if activated automatically updates the parameter sets on disk termination. More on updating psets to disk can be found in the Editing the Xguiphot Task Parameter Sets and Updating the Xguiphot Parameter Sets

  The Help Button
    Pressing the Help button activates the help panel and moves the help text to the section describing the current parameter set.

  The Dismiss Button
    Pressing the Dismiss button deactivates the parameter set editing panel.

  The Parameter Set Specific Buttons
    These buttons if any are specific to a particular parameter set editing panel. For example the dispars parameter set editing panel contains a Display command button which lets the user redisplay the image quickly after editing a few parameters.

More on setting good values for the various pset parameters can be found in the Setting the Dispars Parameters, Setting the Impars Parameters, Setting the Findpars Parameters, Setting the Omarkpars Parameters, Setting the Cenpars Parameters, Setting the Skypars Parameters, and Setting the Photpars Parameters sections.

Detail descriptions of the parameter sets can be found in the The Dispars Parameters, The Impars Parameters, The Findpars Parameters, The Omarkpars Parameters, The Cenpars Parameters, The Skypars Parameters, The Photpars Parameters, The Cplotpars Parameters, and The Splotpars Parameters sections.

### The Model Fitting Panel

The model fitting panel is used to display the results of fitting an elliptical gaussian function to an object in order to determine reasonable initial guesses for quantities like the hwhm of the psf, the shape and orientation of an object, the background sky value, and the standard deviation of the sky background. The model fitting panel can be activated by moving to an object in the image display window and either selecting the "Show model plot ..." item from the Image display menu or typing the y keystroke command. The latter option is also available by selecting the "Show model plot ..." item from the Images menu. The model fitting panel consists of:

The Model Fit Display Window
  The model fit display window displays a major axis plot of the fitted object, the best fit model, the fitted hwhm of the psf and the fitted model parameters.

The Command Button Bar
  The command button bar consists of 8 command buttons:

  The Activate / Deactivate Button
    Pressing the Activate / Deactivate button activates or deactivates cursor mode in the model fitting panel. When cursor mode is active the user can access the Setwidth, Refit, Replot, Results, and Moments Command Buttons and interact with the plot via the usual builtin IRAF cursor keystroke and cursor colon commands.

  The Setwidth Button
    Pressing the Setwidth button stores the computed hwhmpsf values in the impars ihwhmpsf parameter. Ihwhmpsf controls the data region used to compute the model fit, so users should immediately execute a Refit after every Setwidth to check that the fit is stable.

  The Refit Button
    Pressing the Refit button refits the data using the current value of the impars ihwhmpsf parameter.

  The Replot Button
    Pressing the Replot Button replots the results of the current fit.

  The Results Button
    Pressing the Results button prints the results of the current model fit in the bottom of the model fit display window.

  The Moments Button
    Pressing the Moments button prints the results of the current moments analysis in the bottom of the model fit display window instead of the results of the current model fit. This can be useful if for some reason the model fit fails to converge.

  The Help Button
    Pressing the Help button activates the help panel and moves the help text to the "Model Fitting Panel" section.

  The Dismiss Button
    Pressing the Dismiss button deactivates the model fitting panel.

More information on using the model fitting panel to examine stellar objects and estimate the hwhm of the psf can be found in the section on Setting the Hwhm of the Psf.

### The Object List Panel

The object list panel permits the user to create, examine, edit, and save object lists. The object list panel can be activated by selecting the "List panel ..." item from the Lists menu, the Edit menu, or Phot menu, or by typing the l keystroke command in the image display window. The list panel consists of the following sections:

The Create New List Group
  The create new list section allows the user to create a new object list by, reading objects from an objects file, finding the objects automatically using an object detection algorithm, or creating the list interactively with the image display and the image cursor. This section duplicates much of the functionality of the Lists menu. The create new list section consists of the following elements.

  The Input Objects File Entry Box
    The input objects file entry box displays the current object file which must be an item in the input objects file list. A new object file can be entered by removing the existing entry with the BackSpace or Control k keys, typing in a new value, and pressing Return. If the new value is in the object files list a new object list will be generated.
  The Reread Button
    Pressing the Reread button causes the current objects file to be reread and the objects list to be recreated.
  The Next Button
    Pressing the Next command button causes the next objects file to be read into the objects list.
  The Prev Button
    Pressing the Prev command button causes the previous objects file to be read into the objects list.
  The Find Button
    Pressing the Find command button causes a new objects list to be created automatically from the current image using the current values of the Impars and Findpars parameters.
  The Impars Button
    Pressing the Impars command button will bring up the impars parameter editing panel. Users should make sure that the values of the ihwhmpsf, imindata, and imaxdata parameters are reasonable for the current image.
  The Findpars Command Button
    Pressing the Findpars command button will bring up the findpars parameter editing panel. Users should make sure that the value of the fthreshold parameter is reasonable for the current image.
  The Draw Command Button
    Pressing the Draw command button will activate the object list drawing routine.

  More about creating object lists can be found in the Creating Objects Lists From Objects Files, Creating Objects Lists Automatically, Setting the Impars Parameters, Setting the Findpars Parameters, Creating an Objects List with the Image Cursor, and Creating an Objects List with the Photometry Marker sections.

The View and Edit List Section
  The view and edit section allows the user to browse the object list, to mark the object list on the image display, and to edit the object list. Most of the functionality in this section of the panel is duplicated in the Lists menu and the Edit menu. The view and edit section consists of the following elements:

  The Rewind Button
    Pressing the Rewind button rewinds the object list and sets the current object to BOF.
  The Next Button
    Pressing the Next button selects the next object in the object list.
  The Prev Button
    Pressing the Prev button selects the previous object in the object list.
  The Show / Dismiss Marker Button
    Pressing the Show / Dismiss Marker button activates / deactivates the object list marker.
  The Show Button
    Pressing the Show button marks the object list on the image display window.
  The Erase Button
    Pressing the Erase button erases the object list from the image display window.
  The Omarkpars Button
    Pressing the Omarkpars command button activates the omarkpars parameter editing panel.
  The Init Button
    Pressing the Init command button deletes the current object list.
  The Delete Button
    Pressing the Delete command button deletes the currently selected object.
  The Undelete Button
    Pressing the Undelete command button undeletes the currently selected object.
  The Draw Button
    Pressing the Draw command button enters the interactive object drawing routine. The Draw button in the View and Edit section differs from the action of the Draw button in the Create List section, in that in the former case new objects are added to the end of the existing object list, while in the latter they are entered in a new list.
  The Object Geometry Entry Box
    Entering the object geometry in the object geometry entry box and pressing Return will add the object to the current object list. The simplest object is an x and y value separated by whitespace. More complicated object formats are more described in the Object Files Format section of the appendices.
  The Clear Button
    Pressing the Clear command button deletes the text in the object geometry entry box.
  The Enter Button
    Pressing the Enter command button adds the object defined in the object geometry entry box to the current object list.

  More about viewing, browsing, and editing the objects list can be found in the Viewing the Objects List, Setting the Omarkpars Parameters, Browsing the Objects List, Deleting and Undeleting Objects from the Objects List, and Adding Objects to the Objects List sections.

The Measure List Group
  The measure list section permits the user to do photometry on one or more of the objects in the objects list. Most of the functions in the measure list section are duplicated in the Phot menu and the object marker menu. The measure list section consists of the following elements:

  The Cenpars Button
    Pressing the Cenpars command button activates the cenpars parameter editing panel. The cenpars parameters should be examined and edited before doing serious photometry,
  The Skypars Button
    Pressing the Skypars command button activates the skypars parameter editing panel. These parameters should be examined and edited before doing serious photometry,
  The Photpars Button
    Pressing the Photpars command button activates the photpars parameter editing panel. These parameters should be examined and edited before doing serious photometry,
  The Log Results Button
    Pressing the log results command button will toggle the output results file logging.
  The Current Button
    Pressing the current command button measures the current object in the object list.
  The Next Button
    Pressing the Next command button measures the next object in the object list.
  The Prev Button
    Pressing the Prev command button measures the previous object in the object list.
  The Restof Button
    Pressing the Restof command button measures all the list objects from the current object on.
  The All Button
    Pressing the All command button measures the entire list regardless of which object is the current object.

  More about measuring the objects in the object list can be found in the Measuring Objects in the Objects List and Measuring Objects Through the Object List Marker sections.

The Save List Section
  The save list section permits the user to save the current object list, i.e. the list currently displayed in the object list window minus any deleted objects, to a file . It also includes the Help and Dismiss command buttons. The save list section consists of the following elements:

  The Dir Entry Box
    Entering the output objects file path and pressing Return will specify the directory for the output objects file.
  The File Entry Box
    Entering the output objects file name and pressing Return will save the current objects list to the specified file. A message will appear in the status line telling the user how many objects were written to the specified file. By default a file of the form imname.obj.# is written.
  The Save Button
    Pressing the save button saves the current object to the file specified by the Dir and File entry box values. A message will appear in the status line telling the user how many objects were written to the specified file.
  The Help Button
    Pressing the Help button activates the help panel and displays the help text for the list panel.
  The Dismiss Button
    Pressing the Dismiss button will deactivate the list panel.

More on saving objects lists to objects file can be found in the Saving the Objects List section.

### The Photometry Table Panel

The photometry table lists the quick-look photometry results for all objects measured while the panel is activated. The photometry table panel can be activated by selecting the "Photometry table ..." item from the Results menuor by typing the t keystroke command in the image display window. The results for the last measured object can be recalled to the table by selecting the "Display last result" item from the Results menu or by typing the ; keystroke command in the image display window. The photometry table panel consists of the following elements:

Text widget
  The text widget displays the results of all object measurements made while the window is active in the form of a table. The recorded measurements are those for the largest aperture defined by the photpars papertures parameter. The only way to clear the table is to press the Clear button.

Command Button Bar
  The command button bar consists of:

  The Log Results Button
    Pressing the Logresults button enables or disables results file logging. The logging status of each measurement is recorded in the photometry table.
  The Clear Button
    Pressing the Clear button clears the text from the photometry table.
  The Help Button
    Pressing the Help button activates the Help panel and moves to the help text for the photometry panel.
  The Dismiss Button
    Pressing the Dismiss button deactivates the quick-look photometry table and disables writing to the table.

More about viewing the results with the photometry table panel can be found in the The Quick-Look Photometry Table section.

### The Photometry Plots Panel

The photometry plots panel displays plots of the object and sky regions and of the results of the object and sky analysis while the panel is activated. The photometry plots panel can be activated by selecting the "Photometry plots ..." item from the Results menuor by typing the g keystroke command in the image display window. The last item measured can be recalled and displayed in the panel by selecting the "Display last result" item from the Results menu or by typing the ; keystroke command in the image display window.

A variety of object and sky region displays are available including simple image display, image display with contour overlay, image display with object or sky aperture overlay, contour plots, or surface mesh plots. Different plots can be selected using the Objdisplay and Skydisplay buttons. The default object and sky displays are image display with object or sky aperture overlays.

A variety of object and sky analysis plots are available, including major axis and position angle profile plots of the object and sky region, histogram plots of the sky region, and curve-of-growth and moments analysis plots for multi-aperture measurements. Different plots can be selected using the Objplots and Skyplots menu buttons. The defaults are major axis and histogram plots for the object and sky analysis respectively.

Cursor mode can be switched from the default image display window to any one of the plots windows in the photometry plots panel hitting the appropriate Activate button. In cursor mode users have access to all the usual IRAF builtin cursor keystroke and colon commands.

The photometry plots panel consists of the following elements:

Results text area
  The complete single object analysis results are printed in the text area including multi-aperture results if any.
Object region display window
  A zoomed up view of the last object measured is displayed in the object region display window.
Object analysis plot window
  The results of the object analysis are plotted in the object analysis plot window. The default plot is a semi-major axis plot.
Object analysis menu bar
  The object analysis menubar consists of:
  The Objdisplay Button
    Pressing the Objdisplay button will activate the object display menu.
  The Activate Button
    Pressing the Active button will activate cursor mode for the object display region plot. Press again to deactivate.
  The Objplots Button
    Pressing the Objplots button will activate the object plots menu.
  The Activate Button
    Pressing the Activate button will activate cursor mode for the object analysis plot. Press again to deactivate.
Sky region display window
  A zoomed up view of the last sky region measured is displayed in the sky region display window.
Sky analysis plot window
  The results of the last sky analysis are plotted in the sky analysis plot window. The default plot is a histogram plot.
Sky analysis menu bar
  The sky analysis menubar consists of:
  The Skydisplay Button
    Pressing the Skydisplay button will activate the sky region display menu.
  The Activate Button
    Pressing the Activate command button will activate cursor mode for the sky display region plot. Press again to deactivate.
  The Skyplots Button
    Pressing the Skyplots button will activate the sky analysis plots menu.
  The Activate Button
    Pressing the Active command button will activate cursor mode for the sky analysis plot. Press again to deactivate.

More about viewing the results can be found in the The Quick-Look Photometry Plots section.

# The Appendices

## The Object File Format

The input objects file consists of a list of object definitions. Each object definition consists of an object region definition and an optional sky region definition. If the sky definition is present it must be separated from the object definition by the string " ; " as shown below.

    object region definition [; [sky region definition]]

    e.g.

    256.23 258.31 circle 25.0
    256.23 258.31 circle 25.0 ;
    256.23 258.31 circle 25.0 ; circle 30.0 40.0

Object regions may by points, circles, ellipses, rectangles, polygons, or undefined. Each geometry has its own syntax as shown below.

        point: x y
       circle: x y circle radii
      ellipse: x y ellipse radii [axratio [pa]]
    rectangle: x y rectangle radii [axratio [pa]]
      polygon: x y polygon [[radii] {
               xver1 yver1
               xver2 yver2
               ...   ...
               xverN yverN
               }]
    undefined: x y INDEF [INDEF [axratio [pa]]

e.g.

    256.23 258.31
    256.23 258.31 circle 25.0
    256.23 258.31 ellipse 25.0 0.75 33.0
    256.23 258.31 rectangle 25.0 0.75 33.0
    256.23 258.31 polygon 5,10,15 {
        100.0 100.0
        200.0 100.0
        200.0 200.0
        100.0 200.0
    }
    356.23 358.31 polygon 5,10,15
    256.23 258.31 INDEF INDEF

The x and y coordinates are required in all cases. The radii field may define a single radius, e.g. "10.0", a list of radii, e.g. "3,6,9,12,15,18", or a range of radii, e.g. "1:20.0:2.0". If a polygon radii field is present it is treated as a width, and the polygonal aperture is extended outward by that amount. Missing or INDEF valued required radii fields will automatically have their geometries set to INDEF. All radii measurements are assumed to be in the units of the impars iscale parameter. Missing axis ratio and position angle fields are assigned the values of 1.0 and 0.0 respectively. If the vertices field of a polygonal object is ommitted the last defined object polygon is used. If no object polygon has been defined by the time the first polygonal object appears in the list, the object geometry is set to INDEF.

Sky regions may by points, circles, ellipses, rectangles, polygons, objects, or undefined. The object option means use the same geometry as the object region. Each geometry has its own syntax as shown below.

        point: [x y INDEF]
       circle: [x y] circle srin srout
      ellipse: [x y] ellipse srin srout [axratio [pa]]
    rectangle: [x y] rectangle srin srout [axratio [pa]]
      polygon: [x y] polygon [[srin srout] {
               xver1 yver1
               xver2 yver2
               ...   ...
               xverN yverN
               }]
       object: [x y] object srin srout
    undefined:

e.g.

    256.23 258.31 ; 356.23 358.31
    256.23 258.31 ; circle 30. 40.
    256.23 258.31 ; 356.23 358.31 circle 30. 40.
    256.23 258.31 ; ellipse 30. 40.
    256.23 258.31 ; 356.23 358.31 ellipse 30. 40.
    256.23 258.31 ; 356.23 358.31 ellipse 30. 40. 0.75 48.2
    256.23 258.31 ; rectangle 30. 40.
    256.23 258.31 ; 356.23 358.31 rectangle 30. 40.
    256.23 258.31 ; 356.23 358.31 rectangle 30. 40. 0.75 48.2
    256.23 258.31 ; 356.23 358.31 object
    256.23 258.31 ; polygon 10 15 {
        100.0 100.0
        200.0 100.0
        200.0 200.0
        100.0 200.0
    }
    256.23 258.31 ; 356.23 358.31 polygon 10 15 {
        100.0 100.0
        200.0 100.0
        200.0 200.0
        100.0 200.0
    }

Sky regions may be concentric with the object region, i.e. no x and y sky region coordinates are defined, or offset, i.e. the x and y coordinates are defined. If the sky geometry is "object", then the sky region inherits the geometry, axis ratio, and position angle of the object region. The inner and out sky annulus radii must be defined for all geometries except polygonal. Missing or undefined axis ratio and position fields are assigned values of 1.0 and 0.0 respectively.

## The Moment Analysis Computation

The object shape analysis is performed for each aperture using the second order moment computation shown below.

           dx = x - XCENTER
           dy = y - YCENTER
           dI = I - MSKY

           Mxx = sum (dI * dx * dx) / sum (I - MSKY)
           Mxy = sum (dI * dx * dy) / sum (I - MSKY)
           Myy = sum (dI * dy * dy) / sum (I - MSKY)

        HWIDTH = sqrt (log (2) * (Mxx + Myy))
           ELL = sqrt ((Mxx - Myy) ** 2 + 4 * Mxy ** 2) / (Mxx + Myy)
       AXRATIO = 1.0 - ELL
            PA = 0.5 * atan (2 * Mxy / (Mxx - Myy))
     SHARPNESS = HWIDTH / FWHMPSF

x, y, and I are the pixel coordinates and intensity value of each pixel contributing to the computation. XCENTER, YCENTER, and MSKY are the pixel centers and best sky value produced by the centering and sky fitting routines. Mxx, Mxy, and Myy are the second order central moments, and HWIDTH, ELL, PA, and SHARPRAT are the estimated half-width at half-maxima, ellipticity, position angle, and sharpness ratio respectively. The HWIDTH estimates are exact if the object is a perfect Gaussian. The ellipticity is defined as 1 - axratio. Position angles are measured counter-clockwise from the positive x axis. The sharpness ratio is the ratio of the measured HWIDTH to the value of the impars ihwhmpsf parameter supplied by the user.

## The Magnitude Computation

The magnitudes are computed for each aperture in the following way.

    MAG = 2.5 log10 (FLUX)
    FLUX = SUM - AREA * MSKY

## The Magnitude Error Computation

Magnitude error estimates are computed in the following way.

    MAG = -2.5 log10 (FLUX)
    ERROR(MAG) = 1.0857 * ERROR (FLUX) / FLUX
    ERROR(FLUX)^2 = FLUX / IGAIN + AREA * STDEV^2 + AREA^2 * STDEV^2 / NSKY

## Limitations of the Current GUI

The Xguiphot GUI is intended to provide a user interface for an aperture photometry application. Although it provides limited image display and image browsing capabilities, it is not and was not intended to be a general purpose image display or image browser tool, and makes no attempt to duplicate the full functionality of the XImtool image display server or the imexamine task. Instead the xguiphot image examining functions are limited to those most useful for doing photometry, with the idea that more general capabilities may be added later via the plug-in image display server currently under development.

The object list widget has a builtin upper limit of around 2200 objects, beyond which the scrollbars will not function correctly. Xguiphot will still mark and measure longer lists, but functions like select, delete, and undelete on the List panel will not be available.

Marker support for polygonal apertures is available but is not fully general. Users can draw polygons on the image display, move them around, and measure through them. Polygonal markers can be activated, rotated, and resized but it is not yet possible to alter the number of vertices from those marked on the display, except by drawing a new polygon.

Xguiphot currently contains 6 XGterm widgets, 3 for vector graphics, and 3 for image display. The 3 vector graphics widgets behave exactly like a normal IRAF XGterm widget, once their associated Activate button is pushed. So do the image display widgets with the exception that snaps and hardcopies of the displayed image do not work and will currently produce blank plots. Any overlay graphics however will be snapped.

The main image display window is also an xgterm widget, and it has the same problem with printing as the object and sky region widgets. Cursor mode is otherwise fully functional in this window, with the following limitation. If a cursor mode zoom or pan function, e.g. Z, M, P, E, 0 etc is executed in the image display window when the last graphics object displayed was not the image, then the user will get an unpleasant surprise when one of these keystrokes is executed. They will see the last plot appear in the image display window rather than the redisplayed image. A simple i keystroke will fix the problem but any overlayed graphics will be lost. This problem is due to their being only one true graphics buffer in IRAF. The problem is solved for other plots by redisplaying their contents when the plots are activated. However it is inefficient and annoying to do this for images.