%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%.COPYRIGHT  (c)  1990-2006 European Southern Observatory
%.IDENT      createimag.hlq
%.AUTHOR     KB, IPG/ESO
%.KEYWORDS   MIDAS, help files, CREATE/IMAGE
%.PURPOSE    On-line help file for the command: CREATE/IMAGE
%.VERSION    1.0  03-JAN-1986 : Creation, KB
%.VERSION    1.1  17-SEP-1991 : merge syntax description, KB
%----------------------------------------------------------------
\se
SECTION./IMAG
\es\co
CREATE/IMAGE					30-MAY-2006   KB
\oc\su
CREATE/IMAGE frame [dim_specs] [frame_specs] [func_type] [coefs] [data_type]
	create an image
\us\pu
Purpose:
          Create a new image frame.
\up\sub
Subject:  
          Artificial frames, models, simulation.
\bus\sy
Syntax:  
          CREATE/IMAGE frame [dim_specs] [frame_specs] [func_type] 
	               [coefs] [data_type]
\ys\pa
          frame = name of new image frame, 
		  pixels will be of type `data_type'
\ap\pa
          dim_specs = specification of dimensions of new frame
              (a) NAXIS, NPIX(1),...,NPIX(NAXIS)
              (b) "=" (equal sign) to indicate that new frame shall inherit
                  dimensions from an existing frame or interactively via the
                  graphics cursor;
               defaulted to 1,512 (i.e. to option (a))
\ap\pa
          frame_specs = more specifications for the new frame
               for case (a) above this param. has the form:
               starts,steps = START(1),...,START(NAXIS),STEP(1),...,STEP(NAXIS);
               for case (b) this parameter has two possibilities:
               (b1) ref_frame = reference frame, take START, STEP and all other
                    standard descriptors from that frame;
               (b2) GCURSOR to indicate interactive input via graphics cursor
               defaulted to 0.0 for START(i) and 1.0 for STEP(i)
\ap\pa
          func_type = function/mode used to calculate the pixel values of the
               new frame;
               - for option (a) and (b1) the functions are:
               ASCII_FILE if data is read in from an ASCII file,
               CIRCLE  for frame with centered circle,
               ELLIPS for frame with centered ellips,
               EXPO_DISK for exponential disk function
               GAUSS for gaussian function
               LIST for building a frame from a list of frames with dimension
                    which is one less than the result frame
               NODATA for a "reference" or "empty" frame without any data,
               POLY for polynomial of max. degree 2
               RADIUS_LAW for radius**(1/4) law
               SEQUENCE for linear scale in specified interval,
               TABLE_FILE if data from a table is used,
               - for option (b2) the functions are:
               INIT initiates table (default mode, if option(b2))
               ADD add new points to table
               DEL delete points from table.
               Defaulted to POLY.
\ap\pa
          coefs = coefficients for the functions listed above, only applicable
               to options (a) and (b1);
               number and type depend on the parameter func_type - see below;
               defaulted to 0.0, i.e. all pixels of the result image will be
               set to 0.0 if default func_type used.
\ap\pa
          data_type = type of image data if `func_type' = POLY;
		I1 for bytes,
		I2 for 16bit integer, UI2 for unsigned 16bit integer,
		I4 for 32bit integer,
		R4 for 32bit real, R8 or D for 64bit real (double precision);
		defaulted to R4
		for all other func_types this parameter is ignored and
		image data will be created as real values
\ap\no
Note: 
          Using the GCURSOR option (specified as (b2) above), an intermediate
          table is created with the graphics cursor positions. The positions
          can be entered in any order.
          Note, that modes ADD and DELETE only permit editing of the latest
          file created with this command!
          The following notes apply to options (a) and (b1) only:
          for POLY, the coefficients represent a,b,c,d,e,f; up to 6 coeffs.
            of a polynomial, all missing coeffs. are defaulted to 0.0;
            for 1-dim frames: result(x) = a + bx + cx**2;
            for 2-dim frames: result (x,y) = a + bx + cy + dxy + ex**2 + fy**2;
            for higher dim frames: only result(x,y,...) = a is supported;
          for GAUSS the coefficients represent m,s (mean and sigma) for
            1-dim. images;
            and mx,sx,my,sy (mean, sigma in x, mean, sigma in y) for 2-dim.
            images;
            defaults for mean and sigma are center of image and 3 pixels;
          for EXPO_DISK the coefficients represent: amp,scal,pa,i;
            the amplitude, the scale length of exponential disk (positive), 
            the position and inclination angle in degrees; pa is calculated 
            from the x-axis, positive is clockwise;
            default is 200.,4.,0.,0.
          for RADIUS_LAW the coefficients represent amp,er,pa,i;
            the amplitude, effective radius, position and inclination angle in
            degrees, pa is calculated from the x-axis, positive is clockwise;
            default is 200.,4.,0.,0.
          for CIRCLE, the coefficients represent r,in,out;
            radius of circle, value inside and value outside of circle;
          for ELLIPS, the coefficients represent a,b,in,out;
            the major + minor half-axis of the ellips, value inside and value
            outside of ellips;
          for ASCII_FILE this parameter is the name of the file holding the
            data in free format;
            if the ASCII file holds less pixels than required, the pixels of
            the newly created image are set to NULL(2), the user defined null
            value;
          for TABLE_FILE this parameter is the name of the table;
            this only works for 1-dim images.
            The columns :X, :Y are used, the x-values should be non decreasing;
            intermediate points are calculated via linear interpolation. 
          for SEQUENCE, the coefficients represent a,b;
            specifying an interval [a,b]. The frame will contain a linear scale
            with first pixel = a and last pixel = b. This option only valid for
            1-dim frames; start + step will be 0. and 1.
          for NODATA an image frame is created with no data, i.e. this frame
            consists only of descriptors to be used as a reference frame in
            MIDAS commands where applicable (the coefficients are irrelevant!)
            for this func_type, NAXIS can also be set to 0 to create an
            empty frame (useful for the command OUTDISK/SFITS to construct a
            FITS file with empty prime header or extension)
          for LIST this parameter is the name of a list_file or the actual
            list of frames separated by a comma; the list_file is either a
            Midas image catalog, indicated by the type .cat (e.g. luna.cat) or
            an ASCII file holding the frame names, one per line (e.g. sol.dat)
\on\sa
See also:
          CREATE/FILTER, CREATE/RANDOM, GROW/IMAGE, ROTATE/1DIM, @a func2d
\as\exs
Examples:
\ex
          CREATE/IMAGE new 2,100,100 -200.,-180.,22.,22. POLY 0.,1.
            Create the frame  `new.bdf'  with 100*100 pixels,
            start values = -200.,-180. and stepsize = 22.,22.
            `new.bdf' will hold a ramp in x in each line, since it is created
            as: new(x,y) = 0. + 1.*x .
\xe\ex
          CREATE/IMAGE new = sombrero EXPO_DISK
            Create the image `new.bdf' with same size and standard descriptors
            as the frame `sombrero.bdf'.
            The pixels of `new.bdf' will have values according to a function
            generating an exponential disk (with the default values)
\xe\ex
          CREATE/IMAGE new 2,400,4000 ? ? 27 ui2
            Create the image  `new.bdf'  with 16bit pixels of type 
	    "unsigned int" and set all pixels to 27.
\xe\ex
          CREATE/IMAGE new 3,512,512,22 ? list ab001,cd,efghj
            Create the cube  `new.bdf'  with 512*512*22 pixels and set all
            pixels to 0.0. Then insert the 2-dim frames `ac001.bdf', `cd.bdf'
            and `efghj.bdf' into the first 3 planes of `new.bdf'.
\xe\ex
          CREATE/IMAGE new = GCURSOR
            Use graphics cursor to create the 1-dim frame `new.bdf'.
\xe\ex
          CREATE/IMAGE new 1,1022 -12.3,0.5 nodata
            Create the image `new.bdf' which will be used as a reference
            frame only in commands, like e.g. REBIN/LINEAR.
            Despite the settings of its descriptors does `new.bdf' NOT contain
            1022 data values!
\xe \sxe
