Do aperture photometry on a list of objects


This program performs photometry of a list of objects. It is designed to be used non-interactively (i.e. by the GAIA - SUN/214- photometry tool or script). It provides more flexibility than the automated mode of the PHOTOM program by allowing the specification of sky regions other than in annular regions. The results of the measurements are recorded in another file which has the same format as the input file (and can therefore be passed back to this routine and the same measurements can be repeated on a new frame). The format of this file is different for aperture and optimal extraction and is described in the relevant sections.




The level in data units per pixel of any constant offset in the image. This should be defined if the errors are to be calculated from photon statistics. If the true value is unknown then return 0.
Centre the object before measurement or accept the given position as the centre of the aperture. This parameter is forced to be true for optimal extraction.

If this is TRUE the aperture is centered around the object of interest before the measurement is taken. The position supplied to the program is taken as a starting point and the position of maximum flux is located within a search box of fixed size.

If this is FALSE the position supplied to the program is used as the centre of the aperture.

CLIP = _REAL (Read)
The clipping radius used for the weight mask if optimal photometry is selected. Not to be confused with the mask used to exclude regions from the background estimate (USEMASK parameter)
The “source” of the image exposure time supplied via the ETIME parameter. This can take one of the values, HDS, CONSTANT or HEADER, with the following meanings:
HDS: indicates that the exposure value is stored in an HDS object somewhere in the image (this presumes that the image is an NDF and corresponds to the original behaviour of PHOTOM, prior to the introduction of this parameter).
CONSTANT: indicates that a simple floating point value will be supplied for the image exposure time.
HEADER: indicates that the value to be used is stored in the image header (i.e. FITS headers).


A string that, according to the value returned for parameter EXSOURCE, allows the exposure time of the image to be determined. If EXSOURCE is defined as:
then a fully qualified HDS path to the required object within the NDF should be given. For instance if the exposure time is stored in the CCDPACK extension of an NDF, under the item ETIME then a suitable return would be:

The HDS structure of an NDF can be viewed using the HDSTRACE utility (see SUN/102).

then a floating point value should be given.
then the name of the associated item should be given (e.g. the FITS item EXPOSURE).


If TRUE then any annular regions in the input description file are interpreted as radii (in pixels) along the aperture major axis, otherwise they are interpreted as scale factors of the major axis. [FALSE]
Name of the file containing the descriptions of the objects to measure and the positions and nature of any sky regions associated with them. See the notes section for the format of this file.
IN = IMAGE (Read)
Name of the image on which aperture photometry will be performed.
If TRUE then the output values are converted into magnitudes. If FALSE the output values MAG and MAGERR are modified to be a mean photon count and the error in this count, the other values remain the same, i.e. the sum of sky corrected photons and the mean sky value. Note the SKYMAG value is not used when this is FALSE. [TRUE]
An ARD description of any regions to be excluded from the image before any calculations of sky and object are performed. The ARD language is described in SUN/183. A filename can be given using the indirection character “^
The maximum number of iteration steps to be used in locating the object centroid.
The maximum allowable shift in pixels between the initial object position and the calculated centroid.
If this is TRUE then optimal rather than aperture extraction is used for photometric measurement. The default, for backward compatibility reasons, is FALSE.
Name of the file to contain the updated descriptions of the measured objects. See the notes section for the format of this file.
PADU = _REAL (Read)
The number of photons for each interval of the data. If the true value is unknown use a value of 1, in which case the quoted measurement errors will be wrong by the unknown factor SQRT(PADU).
Select the method for calculating the measurement errors. There are three possible choices selected by the integers 1 to 4 which have the following bindings:
The errors are estimated from the photon statistics in the sky and object apertures. The parameters PADU and BIASLE should be set to their appropriate values to convert the data units to photon numbers.
The errors are estimated from the measured variance in the sky aperture. This method assumes that the measured variance is due to photon statistics and estimates the error in the object aperture accordingly. The PADU parameter should be set to its appropriate value to convert the data units to photon numbers.
The errors are estimated from the variance component of the data array.
The errors are estimated from the measured variance in the sky aperture. This method assumes that the errors are Gaussian (same value per object and sky pixel), and thus requires no knowledge of the values of PADU and BIASLE, but can only be considered an upper limit on the error in a measurement.


Find the object centroid for image features which are positive or negative with respect to the background. This should be set to TRUE.
The saturation level in data units for the image. If any pixels in the object aperture have values greater than this then the measurement is flagged with an ‘S’ in the output record.
The size of the search box in pixels to be used in locating the object centroid.
SEE = _REAL (Read)
Approximate seeing in pixels, used to estimate the FWHM of the point spread function (PSF) by the optimal extraction algorithm.
SKY = _REAL (Read)
A constant value to be used as the sky estimate for subsequent measurements. This defines the sky level in data units per pixel. This value is used until another estimator is chosen.
Select the estimator to be used to evaluate the background level in the sky aperture. There are four possible choices selected by the integers 1 to 4 which have the following bindings:
Mean. All pixels in the sky aperture are averaged.
Mean with 2 sigma rejection. All pixels with data values within 2 standard deviations of the mean are averaged.
Mode. The peak of the histogram of pixel values (the most likely value) in the sky aperture is estimated.
A constant. A single value to be used for all measurements. A sky variance (standard deviation) is also requested so that a realistic error can be assigned to the measurements if the error is calculated from the variance in the sky aperture.


The magnitude assigned to the sky level when calculating the magnitude of the object using the relation OBJMAG = SKYMAG - 2.5 LOG10( SIGNAL ) where SIGNAL is the brightness of the object minus sky in photons.

Not used if USEMAGS is FALSE.

A constant value for the sky variance. This is an estimate of the standard deviation in the sky level in data units and is used when SKYEST is 4.

TOLER = _REAL (Read)

The required positional accuracy in pixels to terminate the centroiding iterations.
Define a mask to exclude regions from the background estimate. If this is TRUE an ARD description is requested. Contaminating objects, such as bright stars, can thus be removed from the background estimate.