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>