DOKK / manpages / debian 11 / fitsh / fiphot.1.en
FIPHOT(1) User Commands FIPHOT(1)

fiphot - performing photometry on normal or subtracted images

fiphot [options] [<input>] [-o|--output <output>]

This program performs aperture photometry on normal or subtracted/convolved images.

Gives general summary about the command line options.
Gives a detailed list of command line options.
Gives a detailed list of command line options in Mediawiki format.
Gives some version information about the program.
Name of the input FITS image file.

Name of the input coordinate list file.
Column indices for centroid coordinates. The coordinates read from this file follows the native coordinating scheme (which is not the same as e.g. in IRAF), namely the lower-left corner of the lower-left pixel has the coordinate of (0,0) while the center of the lower-left pixel has the coordinate of (0.5,0.5). Programs like IRAF use the coordinate (1,1) for the center of the lower-left pixel.
Column indices for various apertures. In each such column, there must be three colon-separated number, for the radius of the aperture, inner radius for the background annulus and the thickness of the annulus, respectively. This option is not mandatory, all of the objects can be measured with the same set of apertures, see also -a|--apertures for more details.
Column index for object identifier.
Column index for reference magnitude.
Column index for photometric color.
Column index for magnitude uncertainty.
Mutiply both the input centroid coordinates and aperture/annulusradii by the given integer factor.
Serial identifier for the whole photometry procedure. Can be any arbitrary string and used only in the formatted output (see -F|--format for more details).
-F, --format, --format-output <objecttags>,<photometrytags>
List of output format tags. The formatted (user-friendly) output photometry contains a few columns containing the data related to the object, which followed by a the per-aperture photometry results. See "Format tags" for the list of format tags used here.
String which is used to denote bad photometry. By default, objects on which photometry cannot be performed (due to various reasons, e.g. the object is off from the image, the background level cannot be determined or there are bad pixels in the aperture itself), are marked by a simple dash ('-') in the output file.
-M, --input-mask <image file>
Input mask file to co-add to the mask of the input image. Useful for marking pixels to be ignored from the photometry process beyond the ones which are previously marked in the input image.
-a, --aperture, --apertures <list of circular apertures>
List of circular apertures to be involved in the photometry. Each circular aperture is defined by three numbers: the radius of the aperture, and the inner radius and "thickness" of the annulus used for sky background estimation. The aperture specifications must be spearated by commas while these three numbers must be separated by colons. E.g. to perform aperture photometry on a series of apertures with a radius of 1.5, 2.0 and 2.5 pixels, where all of the annuli have an inner and outer radius of 6.5 and 12 pixels (i.e. the thickness is 5.5 pixels), one should write 1.5:6.5:5.5,2.0:6.5:5.5,2.5:6.5:5.5 as an argument for this option.
-a, --aperture, --apertures <list of simple polygon apertures>
List of polygon shaped apertures. Polygons can only be simple (i.e. non-intersection) or weakly simple polygons which are defined throughout the form of P[x1,y1,...,xn,yn] or polygon[x1,y1,...,xn,yn]. The (x,y)=(0,0) point always refer to the aperture centroid as read from the input list (see --input-list above). There are two types of pre-defined simple polygons which is useful in astronomical image processing. The first definition is Q[R,n,alpha] or regular[R,n,alpha] which implies a regular polygon having n sides and an area equivalent to a circle with a radius of R and the polygon is rotated w.r.t the xy-plane by "alpha" degrees. In the asymptotic limit of n -> infinity, this aperture is equivalent to a circular aperture. The second type is T[R,n,dx,dy] or trail[R,n,dx,dy] where this definition implies a nearly oval racetrack-shaped aperture with a curvature radius of R, a net length of L=sqrt(dx^2+dy^2), the round part is approximated by a regular n-gon and the whole shape is rotated w.r.t the x+ axis as defined by the (dx,dy) vector. In the limit of L -> 0, this shape is equivalent to the aperture definition of regular[R,n,alpha]. The trail[....] shape is useful to perform photometry on asteroid or meteoroid trails. One should note that circular and polygon aperture definitions cannot be mixed. In addition, it should be noted that in case of polygon-shaped apertures, the second definition implies the inner edge of the background area and the third definition implies the outer edge of the background area. For instance, the aperture 3:5:5 can be ideal for point sources, the aperture trail[3,16,3.0,4.0]:trail[5,16,3.0,4.0]:trail[10,16,3.0,4.0] can be optimal for a asteroid trail on the same image that has a net length of 5.0 pixels and parallel with the vector (3.0,4.0). In this case, the equivalent radius of the third part is set to 10 which is equivalent to the 5+5=10 pixels of the radius of the outer annulus in the definition of 3:5:5.
The polynomial describing the gain level throughout the image. Altough during the image readout process, the electron <-> ADU conversion ratio has a fixed value, during the calibration process when the vignetting is strong, the ADU levels may substantially change. The comma-separated numbers in the gain polynomial should denote the coefficients for the monomials 1, x, y, 1/2x^2, xy, ... (the standard order for 2 dimensional polynomial coefficients), where x and y are the normalized coordinates (i.e. zero at the center of the image, x = +/- 1 at the right/left edge of the image and y is scaled appropriately keeping the aspect ratio). Note that the number of coefficients should be 1, 3, 6, 10, ... and so on, for zeroth, first, second, third... order variations, respectively.Specifying zero or negative gain will imply an "infinitely large" gain, thus data are treated as being affected only by instrumental noise and lack intrinsic photon noise.
The minimal value for the gain level. If the polynomial describing the spatial gain variations is evaluated on the regular image domain and yielded a smaller value than this given number, this will be used as gain level. In certain optical systems, the vignetting can be well described by second-order polynomial coefficients except at the very corners of the image. In such a situation this minimal gain is quite useful.
Correlation length of the image. This number is used as an estimator for background noise in the case of images where the background shows correlation. By default, this parameter is unity (1.0). If the image is magnified during processing, then one should specify this magnification ratio here. For instance, if an image is created with `fitrans --zoom 4`, then specify `fiphot --correlation-length 4 ...` as well.
Magnitude - flux conversion level. The specified magnitude will be equivalent to the specified flux level.
This argument is followed by a set of parameters for the sky (i.e. background level) fitting algorithm. See "Sky fitting parameters" below for more details.
This switch is followed by a space separated list of standard masks which should be ignored if such a pixel is marked so in the aperutre. In practice, it might be useful to put saturated objects into the set of "good" stars.
Name of the output file containing the results of the aperture photometry. The format and content of this file can be arbitrarily set, see -F|--format.
Name of the output file containing the all of the low-level photometric information in a fixed format. From this file, one can derive all of the quantities which are written to the "normal" output photometry file. The main purpose of this file is to be an input for image subtraction based photometry, i.e. the photometric information for the reference image is supposed to be stored in this format and the successive calls of `fiphot` on the subtracted residual images read this information in order to derive the final photometric information. See the subsection "Photometry on subtracted/convolved images" about more details on the image subtraction based photometry.

Note that the literal "auto" argument can also be used after the -g|--gain switch. In this case, `fiphot` tries to figure out the gain polynomial from the GAINPOLY and GAIN keywords (in this order) as well as the minimal value for the gain from the GAINVMIN keyword.

identifier
serial identifier (set by --serial)
X coordinate of the centroid
Y coordinate of the centroid
-
empty column

magnitude
uncertainty in the magnitude
background level
background scatter
flux
flux uncertainty
same as "F"
same as "f"
flux in electrons
flux uncertainty in electrons
X coordinate of the fitted centroid
X coordinate uncertainty
Y coordinate of the fitted centroid
Y coordinate uncertainty
Statistical profile size (S), in pixels
Statistical profile deviation parameter (D), in pixels
Statistical profile deviation parameter (K), in pixels
Uncertainty of statistical profile size
-
empty column

During the bacground determination on the aperture annuli, omit the pixels which belongs to the annuli of other centriods. On very dense fields this might make the aperture photometry impossible since for some or many of the target centroids, the bacground level cannot be derived due to the lack of sufficient number of background pixels.
During the bacground determination on the aperture annuli, omit the pixels which belongs to the apertures of other centriods.
-x, --disjoint-radius <radius>
During the bacground determination on the aperture annuli, omit the pixels which are closer to the other centroids than the specified radius.
Use a flux-conserving biquadratic spline interpolation surface for photometry purposes. This surface yields some sort of weighting within each pixel due to the properties of the spline interpolation.
-m, --magfit orders=<c0>[:<c1>[:<c2>[:<c3>]]],iterations=<d>,sigma=<s>
Perform a magnitude transformation after the photometry. Currently impleneted only in the case of image subtraction photometry and always use the reference photometry (see --input-raw-photometry) as a reference for magnitude transformation too. This command line option must be followed by the parameters of the magnitude fit, namely the list the of spatial polynomial orders for the subsequent color orders (colon-separated list), and the number of (optional) outlier rejection iterations and its limit in standard deviation (sigma) units.

Name of the file containing the coordinate lists and the raw photometric information for the reference image.
-K, --input-kernel <input file with kernel solution>
The kernel solution which resulted during the creation of the convolved and/or subtracted image. This information is also required for the proper self-consistent aperture photometry on subtracted images. Omitting this file will result an assumption for identical convolution transformation, which only appropriate if the subtracted image is created by a literal arithmetic subtraction (and not convolution based subtraction).
Normalize kernel solution on each point to unity. Useful for space-borne photometry with high variations in the PSF shape in the cases where the kernel solution is derived empirically and there are many variable sources in the field.

The name of the output centroid list file, in which the radius of the optimal aperture is also stored. The optimal aperture is derived from the object flux itself, the gain level, the background noise and the FWHM of the objects. The background noise can be specified using the -d|--sky-noise argument (see there). The FWHM is given by the option -f|--fwhm.
Sky (bacground level) noise level in ADUs.
-f, --fwhm <FWHM>
Full width at half magnitude (FWHM) for the stellar objects.

Use the mean value of the pixels in the annulus as a sky value.
Use the median value of the pixels in the annulus as a sky value.
Use the mode of the pixels in the annulus as a sky value.
Do the specified number of iterations in order to reject outlier pixels.
Lower, upper and generic (symmetric) outlier level in the units of standard deviations.
Use the forced constant level for sky background, with zero nominal scatter.

Report bugs to <apal@szofi.net>, see also https://fitsh.net/.

Copyright © 1996, 2002, 2004-2008, 2010-2016, 2018-2020; Pal, Andras <apal@szofi.net>

January 2021 fiphot 0.9.4 (2021.01.24)