Provided by: fitsh_0.9.4-1_amd64 bug

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>