Provided by: fitsh_0.9.4-1_amd64 
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>
fistar 0.9.4 (2021.01.24) January 2021 FISTAR(1)