Provided by: fitsh_0.9.4-1_amd64 
NAME
firandom - generates artificial object lists and simulated images
SYNOPSIS
firandom [options] [-o|--output <output>]
DESCRIPTION
The main purpose of this program is to generate artificial object lists and/or artificial (astronomical)
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.
Creating artificial object lists:
-l, --list <list>
Specifications for object list. The "list" parameter should be a set of comma separated tags,
which can either be a value declaration or a repeat count followed by an expression between square
brackets giving specifications for individual objects to be added to the list, also in the form of
value declaration. The value declaration has the sintax of <variable>=<value>, where the variables
can be the following:
f full width at half magnitude (FWHM) of the stellar profiles to be created
e ellipticity of the stellar profiles
p position angle of the stellar profiles
s sigma parameter for the stellar profile (FWHM is roughly 2.35 * sigma)
d delta (plus-shaped deviance) parameter for the stellar profile
k kappa (cross-shaped deviance) parameter for the stellar profile
S Gaussian momenum (a.k.a. profile sharpness parameter) for the stellar profile (S=1/sigma^2)
D plus-shaped momentum for the stellar profile
K cross-shaped momentum for the stellar profile
x normalized X coordinate of the profile centroid (using the standard normalization)
X absolute X coordinate of the profile centroid
y normalized y coordinate of the profile centroid (using the standard normalization)
Y absolute Y coordinate of the profile centroid
m magnitude of the stellar object
i flux of the stellar object
One can use only one of the three equivalent set of profile shape parameters (i.e. f/e/p, s/d/k or
S/D/K). See some more detailed documentation about these parameters. In the expressions which are in the
square brackets, one can use arbitrary arithmetic expressions, using the standard basic arithmetical
operators, elementary functions and the functions r(lo,hi) and g(mean,sigma) which results an uniformly
distrbuted random number between "lo" and "hi" and a Gaussian random number with the specified "mean" and
"sigma" (standard deviation), respectively. In the expressions for magnitude or intensity, one can use
the previously defined values for the centroid coordinates too. The variable "n" is increased between 0
and the repeat count during the evaluation of the square bracket expressions.
--output-list <list file>
Name of the list file where the object list created by the subsequent --list options are saved.
--fep, --fep-output
Save the shape parameters as FWHM, ellipticity and position angle to the output list file.
--sdk, --sdk-output
Save the shape parameters as sigma, delta and kappa to the output list file.
--SDK, --SDK-output
Save the shape parameters as Gaussian momenta to the output list file.
Creating artificial images:
-s, --size <sx>,<sy>
Size of the image to be created.
-b, --bitpix <bitpix>
Standard FITS output bitpix value.
-D, --data <spec>
Output pixel data format specification.
-m, --sky <sky>
Sky (background level) for the image. This can be either a constant or an arbitrary function of
the x, y, X and Y coordinates (see above) for a backgroud with shows systematic variations. One
can use the previously discussed r(lo,hi) and g(mean,sigma) functions, in order to add some sort
of noise to the background.
-d, --sky-noise <noise>
Additional Gaussian noise, equivalent to the term "+g(<noise>,0)" added after the background level
expression.
--photon-noise, --no-photon-noise
Emulate or disable the effect of photon noise on the individual stellar objects.
-l, --list <list>
Specifications for object list (see above).
-L, --input-list <list file>
Name of the input list file from which the coordinates, shape parameters and intensities are read
for the individual objects.
--col-xy <colx>,<coly>
Column indices for X and Y (absolute) centroid coordinates.
--col-flux <flux column>
Column index for flux (intensity).
--col-mag <magnitude column>
Column index for astronomical magnitude, see also --mag-flux.
--col-shape <profile width>,[<profile shape 1>,<profile shape 2>]
Column indices for stellar profile parameters. Either 1 or 3 columns should be specified following
this command line switch. One shape parameter is interpreted as a profile size parameter where the
2 additional (optional) shape parameters describe the deviation from the symmetric profile. See
also options --fep, --sdk or --SDK for more details.
--fep, --fep-input
Interpret the shape parameters read from the input list file as FWHM, ellipticity and position
angle.
--sdk, --sdk-input
Interpret the shape parameters read from the input list file as the sigma, delta and kappa
parameters.
--SDK, --SDK-input
Interpret the shape parameters read from the input list file as the Gaussian momenta parameters.
-S, --input-sky, --input-background, --input-image <sky list file>
Name of the input file containing the sky level. This file should contain at least three columns:
the two pixel coordinates and the sky vaule. See also --col-pixel and --col-value.
--col-pixel <colx>,<coly>
Column indices for X and Y (absolute) pixel coordinates.
--col-value <sky value column>
Column index for sky value (intensity).
--mag-flux <mag>,<flux>
Magnitude - flux conversion level. The specified magnitude will be equivalent to the specified
flux level.
--integral, --no-monte-carlo
Draw the stellar profiles to the image using exact integration.
--monte-carlo, --no-integral
Draw the stellar profiles to the image using a Monte-Carlo way. Note that using this Monte-Carlo
method without additional photon noise emulation would result assymetric stellar profiles even
when the profile would be symmetric. Use this option only when the --photon-noise option is also
used, therefore the profiles are strained with photon noise either.
--noise-suppression <level>
If the profiles are drawn using exact integration, the profiles would be infintely large since an
analytical Gaussian profile is positive on the whole image domain. In order to limit the
integration boundaries, this level limits the size of the integration domain, by the following
way. The expected level of the objects's own photon noise at the edges of the integration domain
is smaller by this factor at least than the flux level. Higher suppression level results larger
integration domain. In the case of additional photon noise, the default value of 10000.0 is
satisfactory. For images with no photon noise, this level should be increased appropriately.
--quantize, --no-quantize
Quantize the output images to integers or not. Note that altering this option yields somehow the
same as when the bitpix value is altered.
--adus, --no-electrons
Use the input fluxes as ADUs instead of electrons (default).
--electrons, --no-adus
Use the input fluxes as electrons insead of ADUs.
-g, --gain <gain>
Electron/ADU ratio (gain).
Random seeds:
--seed <seed>|auto
Generic random seed for `firandom`. A literal "auto" argument yields a random seed derived from
random sources available on the architecture (/dev/urandom, current time).
--seed-noise <seed>|auto
Specific random seed for creating background noise.
--seed-spatial <seed>|auto
Specific random seed for creating random spatial coordinates, i.e. the random seed for functions
in the --list arguments.
--seed-photon <seed>|auto
Specific random seed for photon noise.
Command line argument combinations:
--list <list> --output-list <list file>
This combination creates only a list file based on the --list arguments.
--input-list <list file> --output-list <list file>
This combination just filters and copies the relevant contents from the input list to the output
list. The shape parameters might be converted, for example --SDK-input --fep-output would convert
Gaussian momenta to FWHM, ellipticity and position angle.
--list <list> --output <output image> [--output-list <list file>]
This combination creates an artificial list of sources and then creates an artificial image with
this newly created set of objects. By default, the list itself (incl. the centroid coordinates,
shape parameters and intensities) is not saved unless an output list file is given.
--input-list <list file> --list <list>
This combination is invalid, the centroid list must either be read from a file or created by the
program invocation but lists cannot be merged this way. In such case, save the object list to a
separete file and merge the files using standard tools.
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>
firandom 0.9.4 (2021.01.24) January 2021 FIRANDOM(1)