DOKK / manpages / debian 11 / fitsh / firandom.1.en
FIRANDOM(1) User Commands FIRANDOM(1)

firandom - generates artificial object lists and simulated images

firandom [options] [-o|--output <output>]

The main purpose of this program is to generate artificial object lists and/or artificial (astronomical) images.

Gives general summary about the command line options.
Gives a detailed list of command line options.
Gives a detailed list of command line options in Mediawiki format.
Gives some version information about the program.

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:
full width at half magnitude (FWHM) of the stellar profiles to be created
ellipticity of the stellar profiles
position angle of the stellar profiles
sigma parameter for the stellar profile (FWHM is roughly 2.35 * sigma)
delta (plus-shaped deviance) parameter for the stellar profile
kappa (cross-shaped deviance) parameter for the stellar profile
Gaussian momenum (a.k.a. profile sharpness parameter) for the stellar profile (S=1/sigma^2)
plus-shaped momentum for the stellar profile
cross-shaped momentum for the stellar profile
normalized X coordinate of the profile centroid (using the standard normalization)
absolute X coordinate of the profile centroid
normalized y coordinate of the profile centroid (using the standard normalization)
absolute Y coordinate of the profile centroid
magnitude of the stellar object
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.

Name of the list file where the object list created by the subsequent --list options are saved.
Save the shape parameters as FWHM, ellipticity and position angle to the output list file.
Save the shape parameters as sigma, delta and kappa to the output list file.
Save the shape parameters as Gaussian momenta to the output list file.

-s, --size <sx>,<sy>
Size of the image to be created.
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.
Emulate or disable the effect of photon noise on the individual stellar objects.
Specifications for object list (see above).
Name of the input list file from which the coordinates, shape parameters and intensities are read for the individual objects.
Column indices for X and Y (absolute) centroid coordinates.
Column index for flux (intensity).
Column index for astronomical magnitude, see also --mag-flux.
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.
Interpret the shape parameters read from the input list file as FWHM, ellipticity and position angle.
Interpret the shape parameters read from the input list file as the sigma, delta and kappa parameters.
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.
Column indices for X and Y (absolute) pixel coordinates.
Column index for sky value (intensity).
Magnitude - flux conversion level. The specified magnitude will be equivalent to the specified flux level.
Draw the stellar profiles to the image using exact integration.
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.
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 the output images to integers or not. Note that altering this option yields somehow the same as when the bitpix value is altered.
Use the input fluxes as ADUs instead of electrons (default).
Use the input fluxes as electrons insead of ADUs.
Electron/ADU ratio (gain).

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).
Specific random seed for creating background noise.
Specific random seed for creating random spatial coordinates, i.e. the random seed for functions in the --list arguments.
Specific random seed for photon noise.

This combination creates only a list file based on the --list arguments.
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.
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.
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.

Report bugs to <apal@szofi.net>, see also https://fitsh.net/.

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

January 2021 firandom 0.9.4 (2021.01.24)