Knight AstroContrib Library

This page is a listing of the entire contents of this library for IDL. This listing is the long version. Viewing the much more compact listing may be handier.

[Go Back to Main IDL Libraries Search Page]


Last modified: Thu Dec 21 21:17:15 2000.

List of Routines


Routine Descriptions

LOOK

[Next Routine] [List of Routines]
 Name:
	look
 Purpose:
       This procedure produces a widget to view an image or series of images.
         o You roam in a grid of 2x2 windows with menus on three sides.
         o The plots are dynamic: horizontal and vertical cuts are updated
           as you move the mouse over the full and zoom images.
         o Zoom by dragging the left mouse over the full image.
         o Select numerous options in the Options menu,
           - blink compare (between 2 or more images)
           - movies (all or selected images)
           - catalogs (all or selected images)
           - enlargements (to window and to entire screen)
           - plots (surface, shade_surf, show3, etc.)
           - regions of interest
           - spatial filters, and ...
         o Look is extensible: you can define
           - one loading function, and
           - procedures and functions for display and image processing, e.g.,
               look_fourier - to filter square images
               lego, image_cont, threed, etc. - any IDL pro using 2-D param
               roberts, sin, alog10, etc. - any IDL function using 2-D arg
         o Read more on operation below.  Here's a rendition:
              -----------------------------------------------------
              | Done  | cuts:           |                 | full  |
              |       |   vertical ---> |      plot/      |   &   |
              |xloadct|   horizontal    |   zoom region   | zoom  |
              |switch |            |    |            /|\  | stats |
              |       |------------|------------------|---|       |
              |Options|           \|/   | cuts:       |   |Incre* |
              | menu  |    tv/roam      |    horizontal   |Select*|
              |       |   full image    | <--- vertical   |       |
              |filter |                 |                 |       |
              | slider|-----------------------------------|       |
              | dim3  | plot min slider | plot max slider |       |
              | ...   | =======|======= | =======|======= |       |
              | dim7  | Autoscale/Fixed | Autoscale/Fixed |       |
              -----------------------------------------------------
              | instructions or comments                          |
              -----------------------------------------------------
 Examples:
       look                    ; 1) Test with test images
       images = randomu(seed,10,10,100)
       look,images             ; 2) Display series of 2-D images
       look,/noload            ; 3) Use existing images from common
       common look             ; 4) To access the stored images at main level
       look,/help              ; 5) Just display the look.pro header
       look,/assoc		; 6) Use an associate variable; prompt for
       			;    file and definition of variable.
       			; OR
       file = 'existing_file'
       definition = 'intarr(128,128)'
       look,/assoc,file=file,definition=definition
       			;    The associate variable can have 
       			;    additional variables---with a tag.
       definition = '{struct,header:bytarr(100),data:intarr(128,128)}'
       			;    Up to v3.6, the structure has to be named!
       look,/assoc,tag=1,file=file,definition=definition
       			;   use tag #1 (data) in the structure
       look,loader_name='getdata',d imensions=[3,4,5]
       			; 7) Use getdata.pro to obtain the set of
       			;    3x4x5 images,
       			;    each of size returned by getdata.
       			;    Here 3 dimension sliders will be used.
       look,procedures='process'
       			; 8) Add processing procedures, e.g., to use
       			;    YOUR OWN process.pro to 
       			;    modify the current image.
       look,functions=['roberts','sobel']
       			; 9) Add edge filters to Options menu
       look,options=['db','look_fourier','tv'],types=['f','p','p']
       			; 10)Add functions and procedures together.
       			;    Specifying types avoids search of !path.
       look,userscalefunc=['bytscl','myfunc']
                               ; 11)Add custom functions to auto scaling menu
       look,axes=['frame','index','a,b,c,d,e']
                               ; 12) Replace 'dim 3' label with 'frame', etc.
       look,dim5marks=['raw counts','scaled counts','temperature','radiance']
                               ; 13) Replace 'dim 5' label with a pulldown
                               ;     menu to select the dim5 index.
       tmp = {mark,mark:0l,tag:''}
       look,dim5marks=[{mark,3500,'slew start'},{mark,3650,'slew stop'}]
                               ; 14) Same result as 13) but input is a
                               ;     structure array.  This allows
                               ;     quick-access marks to be placed in the
                               ;     data, so the user can jump to them.
                               ;     The tagsname and structure name are
                               ;     arbitrary, but you need two tags:
                               ;     (0)=int/long and (1)=string
       look,units=['azimuth (200 !3m!5rad pixels)','elevation','counts']
                               ; 15) Replace image dimensions and image value
                               ;     names with the 3 elements of units,
                               ;     e.g. 'y (pixels)' --> 'elevation'
                               ;     These are stored in common look_common
                               ;     in the 'all' structure, so they can be
                               ;     altered by the routine to fetch images,
                               ;     see units in Keywords section below.
 Loading Images:
	There are four ways to load data into look:
         1. Pass images as a parameter: look,images
         2. Load images into common look and call: look,/noload
         3. Access images in a file via associate variable: look,/assoc,...
         4. Give look a function that returns images: look,loader='getdata',...
 Operation:
       1. The basic thing is to roam around the image and look at cuts.
          Buttons, sliders and lists control other features.
       2. The mouse buttons control the following, on the full image.
                  \        ______
                   \______/      \
                                  |   __________ 
                     ____   ______|__/___       Middle button:
          Left button:   \ |        /    |       Click to recenter
           Click & drag   \|  _   _/  _  |       the zoom region.
           on full image   \ |l| | | | | |
           to define       |\|e| |m| |r|\|
           the zoom        | |f| |i| |t| \
           window.         | |t| |d| | | |\____
           Select options. | |_| |_| |_| |     Right button:
                           |             |      Click to do controlled move
                           |             |      of one quantity (*'d), 
                           |             |      e.g., the zoom center
                           |_____________|      in the x direction.

       3. The plot buttons can be selected at any time.
          The plots appear in the zoom window (by default) or both windows.
          Toggle the "Use Full & Zoom" button to get either
            a. the plot of the full image in the zoom window or
            b. the plot of the zoom image in the full window or
            c. 2 plots: zoom and full in the 2 windows.
       4. To zoom, click and drag the left mouse over the region of interest.
          Then you can roam in the zoom image also, looking at cuts.
       5. To change the center of the zoom region, click the middle mouse
          button.  To move the zoom region in a controlled manner, 
          use the right button.
       6. Moving the sliders at the bottom changes the plot and tv scales.
          You can use auto scaling or set the min & max, within the limits
          shown.
       7. There are guards against choosing out-of-range quantities.
       8. If you give a series of 2-D images, the sliders at the left allow
          you to move through the images---one slider per dimension.
          A catalog option allows display of multiple images.
       9. The right mouse button allows controlled increments and decrements
          of the zoom center and width, selected by using the Increment type
          menu.
       10.An options menu lists available processing and image display operators.
          The menu can contain user-supplied procedures or functions;
          see keywords options, types, procedures, and functions.  Most of the
          options appear in pull-down sub-menus in the followiing categories:
            - xloadct
            - enlargement: on the window or the entire screen
            - catalog: all or selective
            - plot types: contour, histogram, surface, show3, etc.
            - region of interest
            - filters: smooth, median, leefilt
            - write Postscript file
       11.There are more detailed notes below.
 Usage:
       look[,image][,/help][,options]
 Optional Inputs:
       image = one or more 2-D images
 Keywords:
       /assoc = flag to say the parameter is an associate variable
         Then the slider for dim3 becomes an index into the associated file.
         Related keywords are "filename" "definition" "dimensions" and "offset".
       axes = string array of names to replace dim 3, dim4, ...
       definition = string used to define the associate variable
       dimensions = the 3rd and higher dimensions for a series of images and
         the /assoc or loader= options, also needed for optical disks where
         only part of the disk has been written on
       dim3marks = string array or structure array of names used to create
         a pulldown menu for selecting the dim 3 index.  The pulldown menu
         is labeled as "dim 3" or the 1st element of the axes keyword if
         present.  The marks are values along the 3rd dimension and can be
         selected via the pulldown menu.  The string array provides tags, each
         with the mark set to its index in the array.  The structure array
         consists of a named structure with two tags, an int or long and a
         string, here called mark and tag:
           tmp = {look_mark,mark:0l,tag:''}
           dim3marks = [{look_mark,3600,'start'},{look_mark,3800,'end'}]
       dim4marks = ditto for dim 4
       dim5marks = ditto for dim 5
       dim6marks = ditto for dim 6
       dim7marks = ditto for dim 7
       filename = name of the file associated with the associate variable
       functions = synonym for options that are functions, cf. options
       /help = flag to print the header only and return
       interval = time in seconds between timer events (D=0.3s)
	kernel_width = the initial width of the smooth and median filters
       lines = # of lines in the comment/help scrollable widget (D=2)
       loader_name = name of an IDL function to return the ith image for
         display.  It needs one parameter, a vector of the indices for the
         current image, and returns one parameter, the image.  The
         important point is that allowing a function to return the image gives
         the user freedom to grab an image in a variety of ways---not tied
         directly to look.pro.  A prototype function, returning a 10x10 array,
         is the following:
         	function getdata,higherdims,comment
         	comment = 'This is an 2-D Gaussian random image with non-zero mean.'
         	return,randomn(seed,10,10)+higherdims(0)
         	end
         To use this function with 100 images, the call to look is:
         	look,...,loader='getdata',dimensions=100
         If the dimensions keyword is omitted, the user is asked to specify
         the # of images.
         Another example would be returning the magnitude, phase, real, or,
         imaginary part of a complex array:
         	function getcomplex,higherdims,comment
         	c= complex(dist(10),dist(10)*higherdims(0))
         	case higherdims(1) of	; flag is the 2nd dimension
         	0: return,abs(c)
         	1: return,atan(imaginary(c),float(c))*!radeg
         	2: return,float(c)
         	3: return,imaginary(c)
         	endcase
         	end
         Then the dim4 slider would control the return value and the dim3
         slider would control the image index.  In this example the call is:
         	look,...,loader='getcomplex',dimensions=[...,4]
       /noload = flag to say the input comes directly from common look
       offset = byte offset pointing to the start of the associated data,
         the third argument to the assoc call.
       options = names of IDL functions or pros to process the current image for
         display or other action, e.g., to define a region of interest or to
         scale nonlinearly.  The option names appear in the options menu.
         Each function accepts one parameter, the current image, and returns
         the modified image.  You can use any idl function that
         operates on images or make your own.  A prototype function is the
         following:
         	function db,image
         	return,alog10(image)*10
         	end
         A procedure accepts one parameter, the current image scaled with look_scl.
         You can use any idl procedure that operates on images or make your own.  
         A prototype procedure is the following:
         	pro dbscl,image
         	tvscl,db(image)
         	return
         	end
         To use this procedure, the call to look is:
         	look,...,options='dbscl'
	  Multiple options are easy, just make an array:
         	look,...,options=['dbscl','lego','image_cont','slide_image']
         look has to determine whether the option is a function or a procedure
         and does a search for each option to find its source code.  These
         searches are time-consuming if !path has many entries.  You can
         shorten the search by including another keyword types; see below.
       procedures = synonym for options that are procedures, cf. options
       range = range of values to be displayed (D=3x range of images)
       tag = tag # if the associate variable is a (named) structure
         e.g., a = assoc(lun,{struct,hdr:0l,data:intarr(128,128)}).
         Then tag=1 references the data tag; see examples above.
       types = types of options, either 'pro' or 'function', corresponding to the
         options keyword to obviate the need for look to determine the option
         type, e.g., look,options=['sin','blob'],types=['function','pro']
       units = 3-element string array to replace labels on images and plots
         x (pixels) --> units(0)
         y (pixels) --> units(1)
         z (value) --> units(2)
         common look_common contains a structure ws that has the units tag
         and can be manipulated by the function used to fetch images, e.g.,
           function get_an_image,indices,comment
           common look_common
           ws.units = ['longitude (deg)','latitude (deg)','pressure (mbar)']
           ...
           return,image
           end
       userscalefunc = array of custom scaling function names, e.g.,
         .r
         - function myfunc, image
         - return, 4 * bytscl (image)
         - end
         look,...,userscalefunc=['bytscl','myfunc']
       /verbose = flag to print informational messages (debug mostly)
       viewers = array of names of procedures to call each time the display
         is updated by a mouse event.  Procedures can do anything, e.g.,
         display other images, calculate statistics, or keep track of what
         has occurred in the program.  The action of each viewer can be
         set to one of three states using the options menu:
           off: procedure not called
           on/all mouse: called for all mouse clicks AND movements
           on/click only: called for mouse clicks and drags only.
         You would choose "on/all mouse" if your procedure shows cuts but
         "on/click only" if your procedure shows images only.  The
         "on/all mouse" option takes more time, so there will be 
         delayed updates on cuts.  Each viewer procedure
         takes no parameters but can obtain information from the two
         common blocks and should have two keywords: create and destroy.
         Whenever the viewer is toggled on (off), the procedure will be
         called with /create (/destroy).  Here's an example.
           PRO my_display,create=create,destroy=destroy
           COMMON look
           COMMON look_common
           COMMON look_viewer,viewer_window
           IF keyword_set(create) THEN BEGIN
             window,/free,xsize = 256,ysize = 256, title = 'Sobel window'
             viewer_window = !d.window
           ENDIF
           IF keyword_set(destroy) THEN BEGIN
             wdelete,viewer_window
             return
           ENDIF
           wset,viewer_window
           tvscl,sobel(thisimage) ; example
           return
           END
         In addition the call to look would be:
           look,viewers='my_display',...
 Outputs:
       widget as rendered above
 Common blocks:
       look = images copied from the input parameter or loaded externally,
         declared and filled by user as one alternative to loading images:
           common look,images,catalog,index
           images = ...
         Note that catalog is another variable; it is loaded by look with
         the images selected by catalog/movie/blink.  The same is true for
         index, which is a 2-D array of indices corresponding to the images.
       look_common = variables that need to be passed between routines,
         not likely to be needed by the user, except units (see above).
 Procedure:
       There are two top-level routines: one to initialize (look) and an
       event handler (look_event).  There are a number of lower-level
       routines to perform specific tasks.  After creating the widgets,
       look places the full image in the tv window and a zoom image
       in the optional plots window.  The cut windows are left blank
       until the mouse is moved over the image in the tv window.
       The event loop does all the dynamic processing.
 Restrictions:
       All the images in a series have to have the same 2-D dimensions.
       All the sliders use whole numbers because IDL's cw_fslider lacks the
         ability to specify an increment.
       Slider value for the maximum slider may be incorrect, even though the
         the proper values are being sent.  I don't understand this one.
 Future Additions:
       Report pixel values when scanning over the cut plots?
       Add a display of the actual values in the array.
       Add a color bar.
       Fourier filtering (A version for square images is look_fourier.pro.)
       Add a comment keyword, like the 2nd parameter of the loader.
 Modification history:
       Write, 21-26 Feb 95, FKKnight (knight@Ll.mit.edu)
       Add roaming in the zoom image, 27 Feb-1 Mar 95, FKK
       Fix bug if middle mouse is pressed first, 1 Mar 95, FKK
       Add xloadct and rescale plot min and max sliders when a new image is
         is accessed, 5 Mar 95, FKK
       Clean up, make fixes, add manual scale limits, 11-12 Mar 95, FKK
       Add dynamic help messages, 11 Mar 95, FKK
       Change common to allow input of images via common.  This avoids
         copying a large number of images to the internal common block from
         the input parameter, 13 Mar 95, FKK
       Add search of path for "look.pro" in !PATH + current directory
         when the HELP button is selected, 09 Mar 95, GGA (gga@otl.sma.ch)
       Change timer interval from 0.1 to 0.3 [s],
         insert some code comments, 15 Mar 95, GGA.
       Add interval keyword to override the default, 15 Mar 95, FKK
       Add scroll increments (range/!d.n_colors) to sliders, 17 Mar 95, FKK
       Add function to right mouse: increase/decrease selected quantities
         by a selected increment (-10 to +10), 18 Mar 95, FKK
       Add switch to plot zoom and full images or just full image using
         the plot menu, 19 Mar 95, FKK
       Add a guard against out-of-range sliders, e.g., int's with
         imrange = (0:32767) would make range = (-32767:-2),
         but the guard may not be sufficient, 20 Mar 95, FKK
       Omit controlled mouse increments because there is no way to shift
         the mouse position in software---it has to be moved, 21 Mar 95, FKK
       Make the allowed range of increments larger, up to half the size of
         the image, which is probably more than enough, 21 Mar 95, FKK
       Add guards against not having images and not having Bill Thompson's
         routines available, 21 Mar 95, FKK
       Exchange the text on the toggle button 'Plot Zoom Only', 23 Mar 95, FKK
       Call setflag,/noscale to avoid rescaling data, 28 Mar 95, FKK
       Reset flags /noscale & /noexact on exit, 19 Jun 95, FKK
       Add range keyword to preselect a slider range, 3 Jul 95, FKK
       Add the associate variable code, 17 Jul 95, FKK
       Add catalog of associate variable, 18-19 Jul 95, FKK
       Add byte offset to start of assoc data, 30 Jul 95, FKK
       Add function keyword to give the ability to grab images from outside
         of look.pro and bring them in, e.g., from a frame grabber or an
         associate variable, 4 Aug 95, FKK
       Tried to fix scaling problem of imrange outside srange with another
         guard, 4 Aug 95, FKK
       Add an optional comment to the function return, 5 Aug 95, FKK
       Add the enlargement button and a keyword lines to tell the
         number of lines in the help/comment widget, 8 Aug 95, FKK
       Add a guard against calling widget_slider with small srange (using
         cw_fslider requires a mod to have a scroll keyword), 11 Aug 94, FKK
       Add a keyword, option_names, to name functions to process an image.  This
         allows user-specified functions in the process menu, 11 Aug 95, FKK
       Revamp:
         change keyword option_names --> options
         change keyword last --> dimensions
         add smooth and median filters and a slider for filter width
         rearrange menus to group items better
         add restore image button to undo processing effects
         omit help button because xdisplayfile can't cope with >1000 lines
         change help text to reflect new widget arrangement
         13 Aug 95, FKK
       Alter the min and max sliders, so they're easy to use, 15 Aug 95, FKK
       Revamp:
         change keyword options --> process_names
         change keyword function_name --> loader_name
         add keyword display_name to allow user-supplied display procedures
         retool the pull_down menu code
         20 Aug 95, FKK
       Add selective catalog for large datasets.  Change the catalog item to
         a pull-down menu with two options: all and selective, which,
         if chosen, brings up a widget to select first, last, and step values
         for the catalog display, 24 Aug 95, FKK
       Move look_fourier to a separate file with a new name: fourier.pro,
         24 Aug 95, FKK
       Change menu names AGAIN to combine the two menus into one:
         display menu --> options menu		; for procedures and functions
         process menu --> options menu		; for procedures and functions
       Add code to distinguish between pro and function, but also add a
         keyword types to allow user to distinguish between pros and
         functions and synonyms for options, procedures=... and
         functions=..., 24 Aug 95, FKK
       Decouple from Bill Thompson's routines, needed three procedures so I
         mimicked them with only the options look needs:
           plot_image --> look_image
           exptv --> look_exptv
           put --> look_put
         ,26 Aug 95, FKK
       Revamp catalog, incl. proper index, processing, 27 Aug 95, FKK
       Allow even zoom width (odd only before), 30 Aug 95, FKK
       Add the region of interest processing using IDL's cw_defroi.pro.  Had
         to block the timers during the cw_defroi life; cf. look_event,
         31 Aug 95, FKK
       Replace cw_defroi.pro with look_defroi.pro, an augmented version,
         including roi selection by threshold.  Keep look_defroi.pro in a
         separate file.  3 Sep 95, FKK
       Omit timers; add /motion_events to draw windows.  Add crosshairs.  Add
         drag box during zoom.  Alter substitute test images, 8-10 Sep 95, FKK
       Replace border.pro with hard-coded border, 12 Sep 95, FKK
       Omit testimages (hassles betw IDL3.6 and IDL4.0);
         just use calculated ones, 14 Sep 95, FKK
       Add blink compare and fixed increments, 15-16 Sep 95, FKK, with advice
         from Vincent Coude' de Foresto and code from David Stern
       Add movies using xinteranimate, 16 Sep 95, FKK
       Make cuts smoother, per Andrew Cool's suggestion, 17-19 Sep 95, FKK
       Make press of Set Min= and Set Max= buttons work, 28 Sep 95, FKK
       Reorder subroutines and make image updates faster by relying on
         color table modifications where possible.  See look_span_update.
         8 Oct 95, FKK
       Add _extra keyword to allow non-look keywords, 13 Oct 95, FKK
       Add optional names of axes to replace dim 3, dim 4,... 18 Oct 95, FKK
       Add ability to input specific values for dim 3, dim 4,..., 30 Oct 95, FKK
       Replace each dim slider with 2 buttons (+ and -) and two editable
         text boxes for the dim value and an increment, 1 Nov 95, FKK
       Fix bugs in catlim 1) if min and max are equal, 2) bad defaults,
         3) out of range integers, 5-7 Dec 95, FKK
       Improve the catalog/movie/blink options by adding a new mechanism
         for choosing frames that allows aborting and easy frame selection,
         11-18 Dec 95, FKK
       Add a Laplacian filter, i.e., a high-pass filter, 24 Feb 96, FKK
       Guard against !d.n_colors = 2^24 in look_span_update, 2 Apr 96, FKK
       Change all !d.n_colors to (!d.n_colors look', 7-9 Dec 97, FKK
       Change the export capability in common look: catalog changed to 3-D
         array, index array added, option to store only indices, append
         capability, 10-12 Dec 97, FKK
       Add a button to determine whether the increment is updated when a new
         image is read.  Update is nice if images span widely different ranges
         but frustrating if the images only vary slightly.  22 Dec 97, FKK
       Fix problem in catalog where index variable didn't exist at the
         beginnning: add extra test (n_elements(index) EQ 0), 9 Jan 98, FKK
       Fix movie for "Use Zoom Only" case.  The ZOOM structure in LOOK_COMMON 
         was being replaced by the zoom factor in look_catalog.  5 Mar 98, DSR
       Add viewers keyword to allow user to add procedures to do things
         triggered by mouse events (similar to procedures and functions
         keywords but automatic instead of being chosen from options
         menu), 26 Mar 98, FKK
       Improved code for display of vertical crosscuts (histogram case).
         22 Jul 98, FKK
       Repair movie mode: allow zoomed movie for full and zoom images with
         default size to fill 1/4 of smaller screen dimension and range up
         full screen, guard against single frame sent to xinteranimate
         (slider error).  Still can't do full & zoom movies together
         (xinteranimate restriction). 9 Sep 98, FKK
       look_auto_minmax changed to use fix / auto slider setting; catalog
         now auto scales each image separately.  20 Oct 98, DSR
       fixed catalog indexing scheme.  16 Jun 99, DSR
       Replace stdev calls (obsolete) with calls to moment.  14 Dec 99, DSR
       Fix to avoid calling moment with structure elements as keyword
         arguments.  14 Mar 00, DSR
       Added option to catalog to generate indices without displaying
         images.  22 Jun 00, DSR
       Changed catalog default to display images.  12 Jul 00, DSR

(See /host/bluemoon/usr2/idllib/astron/contrib/knight/look.pro)


LOOK_CUT

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       look_cut
 PURPOSE:
       This procedure updates the horizontal and vertical cuts.
 INPUTS:
       tmp = structure containing state information, either all or zoom
       xn,yn = device coordinates of the mouse
       xincr,yincr = increments, in data coordinates, to be added to
         the converted values of xn,yn
 MODIFICATION HISTORY:
       add xn,yn,xincr,yincr, 21 Mar 95, FKK
       xincr, yincr not used anymore so remove them, 9 Sep 95, FKK
       add crosshairs code and docrosshairs flag, 9 Sep 95, FKK

(See /host/bluemoon/usr2/idllib/astron/contrib/knight/look.pro)


LOOK_DEFROI

[Previous Routine] [List of Routines]
 NAME:
	look_defroi
 PURPOSE:
   This function returns a where vector of the pixels in a region of interest,
   selected via a number of methods from within a draw widget. 
 CATEGORY:
   Regions of interest, graphics.
 CALLING SEQUENCE:
   Result = look_defroi(draw[,options])
 INPUTS:
   Draw = id of drawable to draw the region, not the window number.
 KEYWORD PARAMETERS:
   CONTRAST = flag to select positive (/contrast, the default) or negative
       (contrast=0) for the threshold method of definiing the roi
   IMAGE = the real image that is displayed with the zoom factor in the
       drawable.  Passing it in allows the threshold to be calculated exactly,
       even for non-unity zooms.  Without it, a congrid is necessary and
       the resulting image is only an approximation.
   MODE = integer code for initial method of selecting pixels:
       0=polygon, 1=point, 2=rectangle, 3=circle, 4=threshold
   OFFSET = offset of lower left corner of image within the
       drawable.  Default = [0,0].
   ORDER = if set, return inverted subscripts, as if the array
       were output from top to bottom.
   RESTORE = Set to restore the drawable to its previous appearance
       on exit.  Otherwise, the regions remain on the drawable.
   SIZE = the size of the underlying array, expressed
       as a two element vector: [columns, rows].  Default =
       (drawable_size-offset) / zoom.
   ZOOM = if the image array was expanded (via REBIN for example)
       specify this two element vector containing the expansion
       factor in X and Y.  Default = [1,1].  Must be integer.
 OUTPUTS:
      Result = 1-D vector of subscripts of points within the region[s] defined.
       If no region was defined, a scalar -1 is returned.
 COMMON BLOCKS:
       None.
 SIDE EFFECTS:
       The regions are drawn within the drawable.  Set the RESTORE
       keyword to undo the damage.  
 RESTRICTIONS:
   This is a MODAL widget.  No other widget applications will be
   responsive while this widget is in use.  The draw widget should
   have the /motion and /button.  For the threshold method, the
   return value can be off due to the congrid employed, unless the actual
   image is passed in.
 PROCEDURE:
   Defining the roi is interective: you select the method(s) and use the mouse.
   The left mouse button selects points (click or drag); the right deletes points.
   The methods are:
     - polygon: click on vertices
     - point: click on single pixels
     - rectangle: drag from lower left to upper right or vice versa
     - circle: drag from center to point on circumference
     - threshold: select positive or negative contrast and adjust slider.
   When you change the method, the current points are added to the total, so
   you can combine methods, except for the threshold method.  The event loop
   is inside the main function, but mouse events in the drawable are processed
   in an event procedure.  Some important points about the code are the
   following.
     - There are two pixel coordinate lists that are stored as uvalues.
     - Except for the threshold method, the displayed image is not needed.
       Instead the XOR graphics mode is used to draw and fill on top of
       the image.
     - For the threshold mode, the image is read using tvrd, so it is a
       scaled copy.
     - A structure, s, which holds the state information, is passed to the
       subroutines:
         look_defroi_draw: overlay outline or fill on drawable.
         look_defroi_nmode: concatenate current points with old ones
         look_defroi_event: process mouse events
 EXAMPLE:
   To obtain the average of the counts of a region within a drawable:
   Assume A = the array of interest, n columns, m rows, and that
   it is displayed in drawable D, at offset X=20, Y=100, and zoomed
   with a factor of 2:
       TV, REBIN(A, M*2, N*2), 20, 100     ;Display the image
       q = look_defroi(D, ZOOM=[2,2], OFFSET=[20,100], IMAGE_SIZE=[m,n])
       if q(0) ne -1 then print,'Average = ', total(a(q))/n_elements(q)
       
 MODIFICATION HISTORY:
   DMS, RSI, December, 1993.  Written.
   modify for incorporating into look.pro:
     - change name from cw_defroi to look_defroi
     - add another mode, threshold with positive or negative contrast
     - allow floating zoom factors
     - allow a timer to be active in the drawable by only processing events
       with 8 tags (mouse events)  Timer events have 3 tags.
     - add mode-specific instructions
     31 Aug-1 Sep 95, FKKnight (knight@ll.mit.edu)
   add the image keyword and change image_size keyword to size.  This allows
     an exact calculation of the return value.  See notes above. 3 Sep 95, FKK

(See /host/bluemoon/usr2/idllib/astron/contrib/knight/look.pro)