The task firandom generates artificial object lists and/or artificial (astronomical) images. It has two purposes:
firandom can be used to create a model for astronomical images, i.e. an ideal image expecting zero noise and quantization artifacts.
firandom can be used to create simulated images in which various detector effects (such as readout noise, background noise, ADC quantization, ...), intrinsic effects (such as photon noise due to the finite photon count) as well as uncertainties in the input source positions.
List of sources to be drawn to the image or an arithmetic expression that describes how the list of sources is to be created.
List of sources and/or a single FITS image.
One of the simplest call to firandom is create an empty image with some fixed background level:
firandom -s 128,128 -m 100 -o x.fits
This call above creates an image with a size of 128×128 pixels and adds a background level of 100. To add some noise, use the option -d ...
firandom -s 128,128 -m 100 -d 10 -o y.fits
As one can see, this image is quantized, although the background noise is clearly close to 10 ADUs. In order to have a continuous intensity level, one should both turn off the quantization (which is turned on by default) and change the output format (i.e. the FITS BITPIX value) to -32 instead of the default 16:
firandom -s 128,128 -m 100 -d 10 --no-quantize -b -32 -o z.fits
It is more useful when someone is calling firandom from a script to use the long option variants instead of the short ones (-s, -m, ...):
firandom --size 128,128 --sky 100 --sky-noise 10 --no-quantize --bitpix -32 --output z.fits
Such a format is equivalent to the call with short option switches (see above), but certainly more descriptive.
In fact, the argument of the -m (or --sky) is an expression of the pixel values, hence one can create a spatially varying background using the various built-in functions and operators. For instance, to create an effect similar to vignetting, use
firandom --size 128,128 --sky "100-40*(x^2+y^2)" --sky-noise 10 --no-quantize --bitpix -32 --output x.fits
In this expression, capital X and Y refer to the actual pixel coordinates (where 0 <= X < 128 and 0 <= Y < 128 here)
and lowercase x and y refer to a normalized position which is (0,0) at the center of the image and (1,0) at the center of the right edge (in other words, x and y are both scaled to the horizontal size of the image).
In order to implant sources on the image, one should specify some input list or catalog which contains the related information. In fact, these lists must include
of these sources. The task firandom is capable to read these input catalogs (and the corresponding information related to the positions, brightness and shape parameters) from an input file as well as it is capable to generate these input catalogs on the fly, either in a deterministic or random manner. In this latter case, firandom can also save these mock catalogs into separate files.
Thus, let's put a single source at the lower-right corner of the image:
echo 97.3 33.4 10 4 0 0 | \ firandom --size 128,128 --sky 100 --sky-noise 10 \ --input-list - --col-xy 1,2 --col-mag 3 --col-shape 4,5,6 --fep \ --mag-flux 10,10000 --no-quantize --bitpix -32 --output x.fits
In this call, the source is centered at x=97.3,y=33.4, it has a brightness of 10 magnitudes (where a magnitude of 10 is equivalent of 10000 ADUs), and an FWHM of 4 with zero ellipticity and position angle. According to the definition of astronomical magnitudes, the --mag-flux 10,10000 option is equivalent to --mag-flux 15,100 or --mag-flux 20,1. By making the input list longer, one can add more sources:
( echo 97.3 33.4 10 4 0 0;
echo 38.7 54.3 11 4 0 0;
echo 61.2 92.1 12 4 0 0;
echo 58.5 25.8 13 4 0 0
) | \
firandom --size 128,128 --sky 100 --sky-noise 10 \
--input-list - --col-xy 1,2 --col-mag 3 --col-shape 4,5,6 --fep \
--no-quantize --bitpix -32 --output x.fits
Of course, the input list can be read from a file instead of the standard input:
( echo 97.3 33.4 10 4 0 0;
echo 38.7 54.3 11 4 0 0;
echo 61.2 92.1 12 4 0 0;
echo 58.5 25.8 13 4 0 0
) > x.list
# [...]
firandom --size 128,128 --sky 100 --sky-noise 10 \
--input-list x.list --col-xy 1,2 --col-mag 3 --col-shape 4,5,6 --fep \
--no-quantize --bitpix -32 --output x.fits
The output of the actual firandom can highly be tweaked in order to have a realistic image which can be readout from the CCD. To ensure the appropriate configuration, one might consider to specify following command line options:
( echo 97.3 33.4 10 4 0 0;
echo 38.7 54.3 11 4 0 0;
echo 61.2 92.1 12 4 0 0;
echo 58.5 25.8 13 4 0 0
) | \
firandom --size 128,128 --sky 100 --sky-noise 10 \
--input-list - --col-xy 1,2 --col-mag 3 --col-shape 4,5,6 --fep \
--quantize --photon-noise --gain 1.0 --integral --noise-suppression 1000 \
--bitpix 16 --output x.fits
This call above produces an output image that highly resembles to a CCD output image:
--monte-carlo method that might be slower for longer lists with numerous sources);