CLASS_NAME:
itool
PURPOSE (one line):
To display an image and provide tools for its visualization.
CATEGORY:
Widgets
SUPERCLASSES:
SUBCLASSES:
CREATION:
See itool::init
METHODS:
itool::apdraw
itool::cleanup
itool::close
itool::cstr
itool::display
itool::draw
itool::getproperty
itool::newprofile
itool::nextimage
itool::oneph
itool::phact
itool::setproperty
itool::tpdraw
itool::trk
itool::realize
itool::init
2004, Mar and Apr, DWL,
This version of itool was derived from a major overhaul of cw_itool
and related routines. It was implemented as an object class
named 'itool.' Multiple instances may be realized and managed by host
applications.
All of the widget applications that may be launched from itool have
been re-written using object-oriented techniques and using a standard
interface that allows simple and efficient communication of data between
them and itool. The object-oriented approach simplifies operation on
data, via method routines. With this approach and the standard
interface, it should be simple to maintain itool and its related
applications, as well as to add other widget applications in the
future.
All of the itool object-oriented widget applications are named with
"itoolwa" as the prefix. The "wa" in the name stands for "widget
application." The portion of the file names before the two "underscore"
characters are the object-class names. The itool widget applications are:
itoolwacpmgr__define.pro ; The Comet Photometry Manager.
itoolwaimparms__define.pro ; The Image Parameters Editor.
itoolwaphparms__define.pro ; The Photometry Parameters Editor.
itoolwapixed__define : The Pixel Editor.
itoolwaprofile__define.pro ; The Profiles Tool.
itoolwatpmgr__define : The Template Manager.
itool widget-application details:
First, each object-oriented widget application, including itool itself,
have the following "properties" available within their respective
object classes:
tlb : the top-level-base of the widget application.
pstate : a pointer to the widget application's state structure.
In addition, each of the widget applications listed above have the
following property in their respective object classes:
oitool : The object reference of the instance of itool from which
the application was launched.
Other properties are defined for each object class, including
the "itool" object class.
Finally, each object-oriented widget application, including itool,
stores a copy of its own object reference in the UVALUE of its
top-level base. Every event handler may retrieve a copy of the application's
object reference by calling
widget_control, event.top, get_uvalue=oref
Then, a copy of the pointer to the state structure may be obtained by calling
oref->getproperty, PSTATE=pstate
Method routines have direct access to the pointer to the state structure,
via their intrinsic "self" arguments (self.pstate).
When one of the above widget applications is launched from an instance
of itool, itool passes a copy of its object reference to that application.
In return, itool receives a copy of the object reference for the new
instance of that application. The object class for itool defines
"properties" for storing object references of each of the applications
listed above. The Profiles Tool is allowed more than one instance
to be active; object references for it are maintained within an object
array.
Additional comments:
Fixed old bugs. Cleaned up event handling and data-storage techniques.
Some of the external routines called are:
itool_pplod.pro Loads photometry parameters into a
structure, from a file.
-----------------------------------------------------------------------------
-----------------------------------------------------------------------------
-----------------------------------------------------------------------------
METHOD NAME:
itool::apdraw
PURPOSE:
To draw a photometric aperture in the zoom window.
CALLING SEQUENCE:
oref->apdraw,x,y
-----------------------------------------------------------------------------
METHOD NAME:
itool::cleanup
PURPOSE:
Self-explanatory
CALLING SEQUENCE:
obj_destroy, oref
INPUTS:
oref : An itool object reference.
-----------------------------------------------------------------------------
METHOD NAME:
itool::close
PURPOSE:
Self-explanatory
CALLING SEQUENCE:
oref->close
INPUTS:
oref : An itool object reference.
-----------------------------------------------------------------------------
METHOD NAME:
itool::cstr
PURPOSE:
To compute a stretch range for the image.
CALLING SEQUENCE:
oref->cstr, frame
INPUTS:
frame : The image frame number (the image may be a "cube" of images).
Always 1 for 2-D images.
OPTIONAL INPUTS:
KEYWORD PARAMETERS:
SILENT : Set this keyword to suppress display of the stretch range.
-----------------------------------------------------------------------------
METHOD NAME:
itool::display
PURPOSE:
To refresh the itool label and text widgets.
CALLING SEQUENCE:
oref->display
-----------------------------------------------------------------------------
METHOD NAME:
itool::draw
PURPOSE:
To refresh the draw itool widgets (full, zoom, and work).
CALLING SEQUENCE:
oref->draw
INPUTS:
OPTIONAL INPUTS:
KEYWORD PARAMETERS:
ALT_WORKWIN : Set this keyword to a valid window number. It will be
used instead of the window number of the local work
window.
FULL : Set this keyword to draw the full window.
WORK : Set this keyword to draw the work window.
ZOOM : Set this keyword to draw the zoom window.
ZXCEN : The x-coordinate of the center of the zoom array.
ZYCEN : The y-coordinate of the center of the zoom array.
-----------------------------------------------------------------------------
METHOD NAME:
itool::getproperty
PURPOSE:
To retrieve "properties" defined for the itool object class. Properties
are specified as keyword arguments.
CALLING SEQUENCE:
oref->getproperty
INPUTS:
OPTIONAL INPUTS:
KEYWORD PARAMETERS:
NO_BLOCK : Set this keyword to a named variable in which to return the
value of the NO_BLOCK property. It is passed to all of the
itool widget applications. If itool is running in non-blocked
mode, all of its widget applications will run in non-blocked
mode.
OIMAGE : Set this keyword to a named variable in which to return the
object reference of the current image object that is active.
OITOOLWACPMGR : Set this keyword to a named variable in which to return
the object reference for an active Comet Photometry
Manager.
OITOOLWAIMPARMS : Set this keyword to a named variable in which to return
the object reference for an active Image Parameters
tool.
OITOOLWAPHPARMS : Set this keyword to a named variable in which to return
the object reference for an active Photometry Parameters
tool.
PPH_PARMS : Set this keyword to a named variable in which to return
a pointer to the ph_parms structure.
PSTATE : Set this keyword to a named variable in which to return
a pointer to the state structure.
STATUS : Set this keyword to a named variable in which to return
the itool status structure. The status structure is
defined as:
status = {flag:flag, msg:msg, lasttype:lasttype,
lastpos:lastpos, object:object,
lastfwhm:lastfwhm, lastmag:lastmag}
where
flag = true if photometry parameters or if templates
have been modified.
msg = A message string, indicating which have been
modified.
lasttype, lastpos, object, lastfwhm, and lastmag are
from the im_parms structure.
-----------------------------------------------------------------------------
METHOD NAME:
itool::newprofile
PURPOSE:
To launch a new instance of the Profiles widget application.
CALLING SEQUENCE:
oref->newprofile
INPUTS:
-----------------------------------------------------------------------------
METHOD NAME:
itool::nextimage
PURPOSE:
To display another image.
CALLING SEQUENCE:
oref->nextimage, oimage
INPUTS:
oimage : An object reference of class itoolimage.
OPTIONAL INPUTS:
KEYWORD PARAMETERS:
FIRST : Set this keyword if nextimage is called from a fresh start-up
of itool. Otherwise, assume that nextimage is being called
directly from the host application that launched this instance
of itool.
-----------------------------------------------------------------------------
METHOD NAME:
itool::oneph
PURPOSE:
To do one single-object photometry operation.
CALLING SEQUENCE:
oref->oneph, x, y
INPUTS:
x, y : the work-window coordinates from a mouse-button event.
-----------------------------------------------------------------------------
METHOD NAME:
itool::phact
PURPOSE:
To perform template photometry.
CALLING SEQUENCE:
oref->phact, x, y
INPUTS:
x, y : the work-window coordinates from a mouse-button event.
-----------------------------------------------------------------------------
METHOD NAME:
itool::setproperty
PURPOSE:
To set "properties" defined for the itool object class. Properties
are specified as keyword arguments.
CALLING SEQUENCE:
oref->setproperty
INPUTS:
OPTIONAL INPUTS:
KEYWORD PARAMETERS:
OITOOLWACPMGR : the object reference for the newly-launched Comet
Photometry manager.
OITOOLWAIMPARMS : the object reference for the newly_launched Image
Parameters tool.
OITOOLWAPHPARMS : the object reference for the newly_launched Photometry
Parameters tool.
OITOOLWATPMGR : the object reference for the newly_launched Template
Manager.
-----------------------------------------------------------------------------
METHOD NAME:
itool::tpdraw
PURPOSE:
To plot the current template in the work window.
CALLING SEQUENCE:
oref->tpdraw
KEYWORD PARAMETERS:
ALT_TPLATE : Set this keyword to a valid {itool_templatelist} structure.
It will be used as the template to draw, instead of the
currently-selected template from The Template Manager.
ALT_WORKWIN : Set this keyword to a valid window number. It will be
used instead of the window number of the local work
window.
-----------------------------------------------------------------------------
METHOD NAME:
itool::trk
PURPOSE:
To refresh the cursor tracking display widgets.
CALLING SEQUENCE:
oref->trk, x, y
INPUTS:
x, y : the coordinates from a motion event in the work or zoom window.
-----------------------------------------------------------------------------
METHOD NAME:
itool::realize
PURPOSE:
To realize a new, managed instance of the itool object class.
CALLING SEQUENCE:
oref->realize
INPUTS:
OPTIONAL INPUTS:
KEYWORD PARAMETERS:
NO_BLOCK : Set this keyword to cause the widget application to run
in non-blocked mode.
-----------------------------------------------------------------------------
METHOD NAME:
itool::init
PURPOSE:
To initialize a new instance of the itool object class (the itool GUI).
CALLING SEQUENCE:
oref = obj_new('itool', oimage)
INPUTS:
oimage : An object reference of class itoolimage.
OPTIONAL INPUTS:
KEYWORD PARAMETERS:
EXPERT : Set this keyword to turn on certain "expert" modes of
operation.
FVISIBLE : Set this keyword to the desired size, in pixels, of the
full window (default is 128).
GROUP_LEADER : Set this keyword to the group leader for this instance.
NODISMISS : Set this keyword, to de-sensitize the Dismiss button on
the file menu and sensitize the Exit button. Otherwise,
the Dismiss button will be sensitive and the Exit button
will be insensitive.
PHOTPARMFILE : Set this keyword to a string containing the name of
a photometry-parameters file.
SCLMIN : Set this keyword to a minimum stretch-range value.
SCLMAX : Set this keyword to a maximum stretch-range value.
TMPLFILE : Set this keyword to a string containing the name of
a template file.
WXVISIBLE : Set this keyword to the size, in pixels, of the width
of the work window (default is 500).
WYVISIBLE : Set this keyword to the size, in pixels, of the height
of the work window (default is 500).
WZOOMFACT : Set this keyword to the ceiling of the zoom factor
(default is unlimited).
XSIZE : Set this keyword to the width, in pixels, of the image
(required).
YSIZE : Set this keyword to the height, in pixels, of the image
(required).
ZVISIBLE : Set this keyword to the desired size, in pixels, of the
zoom window (default is 128).
OUTPUTS:
oref = The object reference of the new instance of the itool
object class.
OPTIONAL OUTPUTS:
COMMON BLOCKS:
SIDE EFFECTS:
RESTRICTIONS:
PROCEDURE:
After creating a new instance of this object-oriented widget application,
it must be realized.
EXAMPLE:
oref = obj_new('itool', oimage, GROUP_LEADER=group_leader)
oref->realize
-----------------------------------------------------------------------------
MODIFICATION HISTORY:
Note: Adapted from cw_itool.pro. The following history has been copied
from cw_itool:
Written by Doug Loucks, Lowell Observatory, June 1994.
This version is a major re-write, employing the compound widget design
introduced in Version 3 of IDL.
94/10/27, MWB, Lowell Observatory, fixed ZOOM bug on line 1144.
95/01/24, MWB, xcen,ycen size mismatch storing back to template if array is
3-d. Fixed to copy *last* position from Basphote return.
95/06/12, MWB, Fixed bug in stretch range computation for large cubes of
small images.
95/09/07, MWB, Changed auto-stretch computation to make it more robust.
95/10/31, MWB, Fixed widget layout problem caused by IDL v4.0 changes.
96/01/06, MWB, Changed W*VISIBLE default to recognize smaller screens.
96/01/16, MWB, Fixed !order=1 bug in mouse event handling.
Fixed Stretch Menu operational bugs for handling image cubes.
96/06/25, MWB, Added autophot support
97/12/12, MWB, changed display to include more image info on main window.
99/08/31, MWB (with help from John Mattox), added a
feature that overplots the aperture on the zoom window
image after template or single-object photometry measurement.
2001/4/3, MWB, added plotting of active template in work window
2001/9/18, MWB, fixed color error in plots with 8-bit display.
2002/11/17, MWB, fixed !order=1 bug for overplotting templates.
Replaced image scaling with updated skysclim routine.
2004/04/15, DWL, Major overhaul of the entire program.
2004/05/28, DWL. Added a 'Save Image to FITS' button to the File Menu.
Added a 'Save Thumbnail Window to JPEG' button to the
File Menu.
Added a 'Save Work Window to JPEG' button to the
File Menu.
Added a 'Save Zoom Window to JPEG' button to the
File Menu.
2005/11/01, DWL. Added method routine itool::close. This method allows
an instance of itool to be closed, from an application
that is managing the instance.
2006/03/15 - DWL, Created a new object class named 'itoolimage' (see
itoolimage__define.pro for details).
An instance of this object class is now passed as the
argument to this init method, instead of the former "pim_parms"
argument.
The changes to the itool GUI involve the places where the
"pim_parms" argument is required. Now, "pim_parms" is acquired
via the "getproperty" method of the 'itoolimage' object class,
using the object reference provided via the "oimage"
argument.
Since it has always been necessary to generate and store
information (im_parms) about the image to be displayed in the
itool GUI, I felt that this was a good argument in favor of
combining the image data and the initialization requirements
for those data. Obviously, this suggested object-oriented
techniques. With this new object class, calling routines
that use the itool GUI benefit from the built-in
initialization and cleanup when an instance is created or
destroyed. It is no longer necessary for callers of the itool
GUI to invoke separate code segments to handle initialization
and cleanup of image data; they need only create and destroy
instances of the 'itoolimage' object class (obj_new and
obj_destroy).
Note that the old procedure named itool_init is no longer
needed; the duties of that procedure are now handled by the
"init" method of the 'itoolimage' object class.
2006/04/4, MWB, fixed auto-scaling bug when looking at image cubes.
2006/5/22, Peter L. Collins, Lowell Observatory
added ccd readout noise as photometric parameter.
2019/12/20, MWB, incorporated new routine, mkxyarr