Provided by: fitsh_0.9.2-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 http://fitsh.net/.

COPYRIGHT

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