Provided by: fitsh_0.9.4-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.
--correlation-length <background correlation length>
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.
--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).
--normalize-kernel
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.
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 https://fitsh.net/.
COPYRIGHT
Copyright © 1996, 2002, 2004-2008, 2010-2016, 2018-2020; Pal, Andras <apal@szofi.net>