% @(#)write_imag.hlq	17.1.1.1 (ESO-IPG) 01/25/02 17:44:03 
%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%.COPYRIGHT  (c)  1990 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
%.VERSION    1.1  08-OCT-1991 : Update, KB
%----------------------------------------------------------------
\se
SECTION./IMAG
\es\co
WRITE/IMAGE						08-OCT-1991   KB
\oc\su
WRITE/IMAGE frame [pix_specs] data [all_flg] [process_flg]
WRITE/IMAGE CURSOR,option data [process_flg]
	update values of image frame
\us\pu
Purpose: 
          Update values of image frame.
\up\sy
Syntax: 
          WRITE/IMAGE frame [pix_specs] data [all_flg] [process_flg]
          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,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 (5 pixels wide) centered at single
               cursor is used to define the region which will be updated;
\\
               if curs_spec = C, the no. of lines of that window can be
               specified via `nolines', defaulted to 5
\\
               `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 contain the
                   columns :XSTART, :YSTART, :XEND and :YEND defining the
                   regions (windows) in the frame which are updated;
\\
                   if following  param `data' is not given, a column labeled
                   :VALUE1 must exist and the regions will be updated with the 
                   values in :VALUE1, 
\\
               defaulted to: `<,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 via GET/CURSOR (with cursor-rectangle option).
\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,c 22.2
            As above but 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 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 perro raton,table 33.3
            Use the table `raton.tbl' to specify intervals in the frame
            `perro.bdf' and fill all pixels in these intervals with 33.3 .
\xe\ex
          WRITE/IMAGE perro gato,table ? ? ADD
            Use the table `gato.tbl' to specify intervals in the frame
            `perro.bdf' and add to all pixels in these intervals the 
            value stored in column :VALUE1 of table `gato.tbl'.
\xe \sxe