% @(#)createrand.hlq	17.1.1.1 (ESO-IPG) 01/25/02 17:43:28 
%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%.COPYRIGHT  (c)  1990 European Southern Observatory
%.IDENT      createrand.hlq
%.AUTHOR     MR,FM,KB, IPG/ESO
%.KEYWORDS   MIDAS, help files, CREATE/RANDOM_IMAGE
%.PURPOSE    On-line help file for the command: CREATE/RANDOM_IMAGE
%.VERSION    1.0  03-JAN-1986 : Creation, MR,FM,KB
%----------------------------------------------------------------
\se
SECTION./RAND
\es\co
CREATE/RANDOM					       02-JUL-1997  PB,KB
\oc\su
CREATE/RANDOM name [dims] [starts,steps] [func_type] [coefs] [seed]
CREATE/RANDOM name = ref_frame [func_type] [coefs] [seed]
	create a random image
\us\pu
Purpose:      
           Create a new image (= bulk data frame + standard descriptors)
           with pixel values drawn from a random distribution.
\up\sy
Syntax:       
           CREATE/RANDOM name [dims] [starts,steps] [func_type] [coefs] [seed]
           CREATE/RANDOM name = ref_frame [func_type] [coefs] [seed]
\ys\pa
           name = name of new frame
\ap\pa
           ref_frame = reference frame,
                       i.e. take all descriptors from that frame
\ap\pa
           dims      = NAXIS, NPIX(1),...,NPIX(NAXIS) (NAXIS max. 3);
\\
                       defaulted to 2,64,64
\ap\pa
           starts,steps = START(1),...,START(NAXIS),STEP(1),...,STEP(NAXIS)
\\
                       default: = 0. for START(i), = 1. for STEP(i)
\ap\pa
           func_type = type of function used for image creation\\
                       U(NIFORM) for uniform probability function\\
                       G(AUSS) for Gaussian p.f.\\
                       E(XPONENTIAL) for exponential p.f.\\
                       L(OGNORMAL) for lognormal p.f.\\
                       B(INOMIAL) for binomial p.f.\\
                       P(OISSON) for Poisson p.f.\\
                       C(AUCHY) for Cauchy p.f.\\
                       F(ibonacci) for lagged Fibonacci random no. generator;
\\
                       func_type is defaulted to UNIFORM
\ap\pa
           coefs = coefficients for the function above (not used for F),
\\
                   number and meaning depends on the parameter func_type;
\\
                   defaulted to 0.,1.
\ap\pa
           seed  = Integer number used as root of the pseudo-random
                   series. Defaulted to the current time in seconds,
                   as provided by M$SECS().
\ap\sa
See also:
           CREATE/IMAGE
\as\no
Note:        
           For `funct_type' GAUSS the coefficients represent m,s (mean and
           sigma), for UNIFORM the coefficients represent a,b the endpoints
           of the interval [a,b].
\\
           For POISSON the coefficient represents m the mean
\\
           Except for `funct_type' FIBONACCI the relevant functions of the
           NAG library are used, i.e. without NAG they don't work!
\\
           FIBONACCI produces random numbers similar to UNIFORM. Besides that
           it does not need NAG and is also much faster (more than a factor 5).
\on\exs
Examples:
\ex
           CREATE/RANDOM new 2,100,100 -200.,-180.,22.,22.
             Will create the frame `new.bdf' with 100*100 pixels,
             start values -200.,-180., stepsize 22.,22.
             the pixel values of `new.bdf' will be determined according
             to a uniform distribution over the interval [0,1].
\xe\ex
           CREATE/RANDOM new 2,100,100 -200.,-180.,22.,22. f
             As above but use Fibonacci based random no. generator (which
             does not need the NAG library and is faster).
\xe\ex
           CREATE/RANDOM new = sombrero GAUSS 12.5,1.25
             Will create the image `new.bdf' with same size and standard
             descriptors as the frame `sombrero.bdf'.
             The pixel values of `new.bdf' will be determined according
             to a Gaussian distribution with mean = 12.5 and 
             standard deviation = 1.25.
\xe \sxe