Provided by: fitsh_0.9.2-1_amd64 
NAME
fiphot - performing photometry on normal or subtracted images
SYNOPSIS
fiphot [options] [<input>] [-o|--output <output>]
DESCRIPTION
This program performs aperture photometry on normal or subtracted/convolved images.
OPTIONS
General options:
-h, --help
Gives general summary about the command line options.
--long-help, --help-long
Gives a detailed list of command line options.
--wiki-help, --help-wiki, --mediawiki-help, --help-mediawiki
Gives a detailed list of command line options in Mediawiki format.
--version, --version-short, --short-version
Gives some version information about the program.
-i, --input <image file>
Name of the input FITS image file.
Simple aperture photometry:
-L, --input-list <input coordinate list file>
Name of the input coordinate list file.
--col-xy <colx>,<coly>
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.
--col-ap <A1>,<A2>,...
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.
--col-id <identifier column>
Column index for object identifier.
--col-mag, --col-magnitude <magnitude column>
Column index for reference magnitude.
--col-col, --col-color <color column>
Column index for photometric color.
--col-err, --col-error <magnitude error column>
Column index for magnitude uncertainty.
-z, --zoom <zoom level>
Mutiply both the input centroid coordinates and aperture/annulusradii by the given integer factor.
--serial <serial>
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.
--nan <nan-string>
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.
-g, --gain, --gain-poly <gain polynomial>
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.
--gain-vmin <minimal gain>
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.
--mag-flux <mag>,<flux>
Magnitude - flux conversion level. The specified magnitude will be equivalent to the specified
flux level.
--sky-fit <sky fitting parameters>
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.
--aperture-mask-ignore <list of masks>
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.
-o, --output <output photometry file>
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.
--output-raw-photometry <output raw photometry>
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.
Format tags for generic object data:
I identifier
S serial identifier (set by --serial)
X X coordinate of the centroid
Y Y coordinate of the centroid
- empty column
Format tags for photometric data:
M magnitude
m uncertainty in the magnitude
B background level
b background scatter
F flux
f flux uncertainty
A same as "F"
a same as "f"
E flux in electrons
e flux uncertainty in electrons
X X coordinate of the fitted centroid
x X coordinate uncertainty
Y Y coordinate of the fitted centroid
y Y coordinate uncertainty
W Statistical profile size (S), in pixels
D Statistical profile deviation parameter (D), in pixels
K Statistical profile deviation parameter (K), in pixels
w Uncertainty of statistical profile size
- empty column
Fine tuning of aperture photometry:
-j, --disjoint-annuli, --disjoint-rings
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.
-p, --disjoint-apertures
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.
-k, --spline
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.
Photometry on subtracted/convolved images:
-P, --input-raw-photometry <input reference raw photometry>
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).
Optimal aperture determination:
--output-list <output coordinate list file>
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.
-d, --skynoise <noise>
Sky (bacground level) noise level in ADUs.
-f, --fwhm <FWHM>
Full width at half magnitude (FWHM) for the stellar objects.
Sky fitting parameters:
mean Use the mean value of the pixels in the annulus as a sky value.
median Use the median value of the pixels in the annulus as a sky value.
mode Use the mode of the pixels in the annulus as a sky value.
iterations=<iterations>
Do the specified number of iterations in order to reject outlier pixels.
lower, upper, sigma=<sigma level>
Lower, upper and generic (symmetric) outlier level in the units of standard deviations.
force=<level>
Use the forced constant level for sky background, with zero nominal scatter.
REPORTING BUGS
Report bugs to <apal@szofi.net>, see also http://fitsh.net/.
COPYRIGHT
Copyright © 1996, 2002, 2004-2008, 2010-2015; Pal, Andras <apal@szofi.net>