Provided by: fitsh_0.9.4-1_amd64 bug

NAME

       fistar - detecting and characterizing point-like sources

SYNOPSIS

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

DESCRIPTION

       The main purpose of this program is to detect and extract sources (i.e. star-like objects)
       from astronomical images. The source detection and extraction are  based  on  three  major
       steps.  First,  pixel  groups  are derived which are possibly belong to the sources (these
       preliminary detections are callad  source  "candidates").  Second,  these  candidates  are
       modelled  with  some  sort  of  analytic  model  funcion,  in order to derive more precise
       centroid coordinates and shape parameters. The last step is to  extract  the  point-spread
       function  (PSF)  for the image, based on the detected and modelled sources. Basically, the
       input for this program must be an astronomical image while  the  output  is  the  list  of
       detected and extracted sources and their respective characteristics.

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 input file from which the sources are extracted.

       -o, --output <data file>
              Name  of the data file where the list of the extracted sources and their respective
              characteristics are written.

   Basic source detection and characterization options:
       -t, --threshold <threshold>
              Detection peak threshold, in ADUs.

       -f, --flux-threshold <flux threshold>
              Detection flux threshold, in ADUs.

       --algorithm <algorithm>
              Source  cadidate  extraction  algorithm.  It   can   be   "uplink"   (default)   or
              "parabolapeak".

       -p, --prominence <prominence>
              Critical  relative prominence parameter used in the "uplink" algorithm. The default
              is to use no prominence based pixel grouping.

       -r, --shrink <shrink factor>
              Shrink factor applied before star candidate detection. The image is shrunk by  this
              specific  factor  and after the detection, the candidate coordinates are multiplied
              by this value.

       --only-candidates
              Do not involve any analitic model funcion during the  derivation  of  the  centroid
              coordinates  and  shape parameters, but derive these from some sort of simple pixel
              statistics.

       --model <model>[order=<order>]
              Analytic model function used in the second stage of source extraction. This can  be
              "gauss"  (symmetic  Gaussian profile), "elliptic" (assymetric Gaussian profile) and
              "deviated" (Gaussian profile multiplied by a polynomial up to the specified order).

       --iterations symmetric=<n>,general=<n>
              The number of Levenberg-Marquardt iterations during the analytic model fit. The fit
              is  done  in two substeps, first the symmetric profile parameters are derived only,
              which step is followed by the fit for all of the shape parameters.

       -s, --sort {x|y|peak|fwhm|amp|flux|noise|s/n}
              Sort the output list of extracted sources by X  or  Y  coordinate,  peak  flux  (no
              background  level  subtracted),  profile  FWHM, peak intensity (background level is
              subtracted), total flux, noise level or signal-to-noise ratio; respectively.

       --mag-flux <mag>,<flux>
              Magnitude - flux conversion level. The specified magnitude will  be  equivalent  to
              the specified flux level.

       -M, --input-mask <image file>
              Input mask file to co-add to the mask of the input image. Useful for marking pixels
              to be excluded from source extraction process beyond the ones which are  previously
              marked in the input image.

       -F, --format <format>
              Comma  separated  list  of format tags, for formatting the output list of extracted
              sources. Each row represents an extracted source while the  format  specified  here
              defines the quantities listed in each row of the output file. See "Format tags" for
              more details.

   Format tags:
       id     An unique identifier for the source (an integer number, in fact).

       ix     Integer X coordinate for the centroid pixel

       iy     Integer Y coordinate for the centroid pixel

       x      Centroid X coordinate in native coordinate convention.

       y      Centroid Y coordinate in native coordinate convention.

       bg     Background level

       amp    Peak amplitude

       S      Gaussian momenum for the stellar profile (S=1/sigma^2)

       D      plus-shaped momentum for the stellar profile

       K      cross-shaped momentum for the stellar profile

       sigma  sigma parameter for the stellar profile (FWHM is roughly 2.35 * sigma)

       delta  delta (plus-shaped deviance) parameter for the stellar profile

       kappa  kappa (cross-shaped deviance) parameter for the stellar profile

       fwhm   full width at half magnitude (FWHM) of the stellar profile

       ellip  ellipticity of the stellar profile

       pa     position angle of the stellar profile

       flux   Total flux of the source

       nosie  Noise level of the source

       s/n    Signal-to-noise ratio of the detection

       magnitude
              Brightness of the source in magnitudes (see also --mag-flux)

       cx     Candidate centroid X coordinate (derived from pixel flux statistics).

       cy     Candidate centroid Y coordinate (derived from pixel flux statistics).

       cbg    Background level for the source candidate

       camp   Peak amplitude of the source candidate

       cmax   Maximum intensity on the source cadidate

       cs     Gaussian momenum for the source cadidate, derived from pixel flux statistics

       cd     plus-shaped momentum for the source cadidate, derived from pixel flux statistics

       ck     cross-shaped momentum for the source cadidate, derived from pixel flux statistics

       npix   number of pixels assigned to the detetcted source

   Obtaining the point-spread function (PSF):
       --psf <parameters>
              Comma-separated list of parameters related to the PSF fitting:

       grid=<grid>
              subgrid size for the PSF

       halfsize=<half size>
              half-size of the PSF stamp, the full size of  the  stamp  will  always  be  2*<half
              size>+1 and the PSF itself is centered at the center of the central pixel.

       order=<order>
              order of spatial variations in the PSF

       symmetrize
              symmetrize the resulting PSF (i.e. fit a symmetric PSF instead of a normal one)

       spline use a spline interpolation during the determination of the PSF

       --output-psf <output PSF FITS file>
              Name of the output file where the PSF is saved in FITS format. The PSF is stored in
              a 3 dimensional (a.k.a. "data cube") structure where the z-axis is for the  various
              polynomial coefficients describing the spatially varied PSF.

   Alternate sources for object candidates:
       -C, --input-cadidates <cadidate list file>
              Name  of  input  cadidate list file. If such a file is defined in the command line,
              the cadidates are not searched by the build-in algorithms. Instead,  the  centroids
              are read from this file and the pixels for each object are defined within a certain
              radius from this centroid (see -r|--cadidate-radius also). The role of this  option
              is  twofold.  First, it is suitable if only some of the sources have to be modelled
              with an analytic function; second, PSF determination can be done only a  previously
              cleaned list of sources, in the case when there might be contaminating sources too.

       -r, --candidate-radius <radius>
              This  option  defines  a  distance,  where  pixels  within this are assigned to the
              candidate.

       --col-xy <colx>,<coly>
              Column indices for X and Y centroid coordinates.

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>