%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%.COPYRIGHT  (c)  1990-2011 European Southern Observatory
%.IDENT      write_imag.hlq
%.AUTHOR     KB, IPG/ESO
%.KEYWORDS   MIDAS, help files, WRITE/IMAGE
%.PURPOSE    On-line help file for the command: WRITE/IMAGE
%.VERSION    1.0  06-OCT-1989 : Creation, KB
%----------------------------------------------------------------
\se
SECTION./IMAG
\es\co
WRITE/IMAGE						07-JUN-2011   KB
\oc\su
WRITE/IMAGE frame [pix_specs] data [all_flg] [process_flg]
WRITE/IMAGE CURSOR,option data [process_flg]
	update values of an image frame
\us\pu
Purpose: 
          Update values of an image frame.
\up\sy
Syntax: 
          WRITE/IMAGE frame [pix_specs] data [all_flg] [process_flg]
or
          WRITE/IMAGE CURSOR,option data [process_flg]
\ys\pa
 
          frame = name of image frame;
\ap\pa
          CURSOR,option = cursor(s) are used to define the region of the
               displayed frame in which data values will be updated;
               option = curs_spec[,nopix,nolines]
               curs_spec = 1 - if cursor is used for updating single pixel of
                  displayed frame;
               curs_spec = 2 - if cursor defined window is used to define the
                  region of the displayed frame which will be updated;
               curs_spec = C - if a window centered at single cursor is used 
		  to define the region which will be updated;
                  the size of the window can be specified via 'nopix,nolines',
		  with nopix,nolines odd and max. NPIX(1)/2, NPIX(2)/2,
                  if only 'nopix' is given a square window is used; 
		  default for nopix,nolines is 5, i.e. a 5x5 window
               the 'option' is defaulted to 2
\ap\pa
          pix_specs = string defining the frame region to be updated;
               (a) 'xs,noval', 'xs,ys,noval' or 'xs,ys,zs,noval' defining the
                   start coords in x,y,z (according to the dimensions of the
                   frame) and 'noval' the number of values to be written;
               (b) '[xs:xe]', '[xs,ys:xe,ye]' or '[xs,ys,zs:xe,ye,ze]',
                     noval will then be determined from size of region
               (c) 'tbname,TABLE' where the table 'tbname' must either 
                   contain the columns with x-, y-coords 
                   :XSTART, :YSTART, :XEND and :YEND defining the
                   regions (windows) in the frame which are updated;
                   or the columns with x-, y-pixels 
                   :X_PIX, :Y_PIX defining the single frame pixels
                   which are updated;
                   if following  param 'data' is not given, a column labeled
                   :VALUE1 or :VALUE must exist and the specified frame 
                   elements will be updated with the values in :VALUE1
                   or :VALUE (:VALUE1 is checked for first)
		   all columns are of type real; 
               defaulted to (a): 
               '<,20', '<,<,20' or '<,<,<,20' for 1-, 2- or
               3-dim frame, i.e. write 20 values at beginning of frame.
\ap\pa
          data = data values separated by commas, will be interpreted as
               floating point data;
               for CURSOR, a single value is written to all pixels in the 
               specified region of the frame
\ap\pa
          all_flg = if set to ALL, all pixels defined by the parameter 
               'pix_specs' above are updated with the first value given in 
                the parameter 'data' ;
               implicitely set to ALL for table specified frame windows
\ap\pa
          process_flg = flag specifying how the image frame is updated;
               S(tore) to set the frame pixels to given data values,
               A(dd) to add given data values to values of frame pixels,
               M(ultiply) to multiply given data values with values of frame 
               pixels;
               defaulted to S
\ap\sa
See also:
          READ/IMAGE, PRINT/IMAGE, REPLACE/IMAGE, COMPUTE/IMAGE, 
          MODIFY/PIXEL, MODIFY/AREA, GET/CURSOR
\as\no
Note: 
          For the MIDAS standard of specifying coordinates see the help of
          READ/IMAGE.
          If no. of values given in 3rd parameter is less than 'noval' of
          parameter 'pix_spec' only that many values are written.
          The columns required with the table option are exactly the ones 
          of a table created either via
          1) GET/CURSOR with cursor-rectangle option 
             (x-,y-coords windows are written)
          or via 
          2) FIND/PIXELS or FIND/PXPOS 
             (single x-,y-pixels are written)
\on\exs
Examples:
\ex
          WRITE/IMAGE becerra <,<,4 1.0,2.0,3.0,4.0
            Write values 1.0,2.0,3.0,4.0 into 2-dim image 'becerra.bdf',
            starting at 1st pixel in x and y.
\xe\ex
          WRITE/IMAGE becerra [@1,@1:@4,@1] 1.0,2.0,3.0,4.0
            Exactly the same command as above, with just another syntax for
            pixel specifications.
\xe\ex
          WRITE/IMAGE vaca @20,@100,20 2.3 ALL
            Starting with pixel no. 20 in line no. 100, set 20 pixels of frame
            'vaca.bdf' to the constant 2.3
\xe\ex
          WRITE/IMAGE cursor 22.2
            Use the cursor rectangle to define interactively the region 
            where all pixels of the currently displayed frame are set to 22.2
\xe\ex
          WRITE/IMAGE cursor 0.6 M
            As above but multiply all pixels in the defined region by the 
            given constant (i.e. 0.6).
\xe\ex
          WRITE/IMAGE cursor,c 22.2
            Use a 5x5 window centered at single cursor to define 
            the region where all pixels of the displayed frame are updated.
\xe\ex
          WRITE/IMAGE cursor,c,11,3 22.2
            As above but use a 11x3 window centered at single cursor.
\xe\ex
          WRITE/IMAGE perro raton,table 33.3
            Use the table 'raton.tbl' to specify intervals or single pixels
            in the frame 'perro.bdf' and fill the specified pixel(s) with 
            the value 33.3, i.e. in this case the value columns, :VALUE1 or
            :VALUE, do not need to exist in the table.
\xe\ex
          WRITE/IMAGE perro gato,table ? ? ADD
            Use the table 'gato.tbl' to specify intervals (pixels) in the 
            frame 'perro.bdf' and add to all specified pixel(s) the value 
            stored in column :VALUE1 or :VALUE of table 'gato.tbl'.
\xe \sxe
