Provided by: fitsh_0.9.4-1_amd64 bug

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>