[ Home | About | Tech Info & Data | Publications | References ] [ Site by Jeffrey Hall | Research funded by NSF ]
Tool is an abstract class to implement the highest-level operations associated with reducing CCD data. It allows the user to define a set of rectangular areas on a 2D image that will be used for analysis, and any data reduction or analysis object derived from it can use the Tool methods to operate on particular parts of the image. It inherits Root.
A Tool works as follows. The data are a pointer to a 2D image in memory. Data can be attached to, or detached from, a Tool via object methods; this simply means that the object's data member pointer is set to point to the image, so that any operations appled to Self.data will affect that image.
The Tool maintains a list of Rect objects that define rectangles on the image to which tool actions will be applied. Usually we only use one for the entire image, but in principle one can have as many as desired. The rectangles are stored in the RectList data member, which is an ObArray object. When a tool action is applied, it only affects one of the rectangles in the list; this is the active rectangle and is specified by the activeRect data member, which is the zero-relative index of the target rectangle in the ObArray.
Finally, for an arbitrary tool, is is probable that there are specific quantities that child objects will need to carry out the tool actions on the data. These are stored in the TData data member, which is an object of type DataList.
All Tool-derived objects should override the go method, which carries out the tool's actions. Generally, go will operate by attaching data to the object, getting the active rectangle, carrying out reduction or analysis operations using the TData, and detaching the object. A go can either modify the original data, or clone and work with an internal copy of the data, as the programmer desires.
2008 July 14 - Documentation written.
bool verbose
pointer data
int activeRect
ObArray RectList
DataList TData
argument int top
argument int left
argument int bottom
argument int right
Calls Rect::init, ObArray::add_tail
Adds a new rectangle to the end of the Tool's rectangle list. The coordinates of the rectangle on the 2D data array are specifed by the arguments.
argument pointer data
Calls Root::add_history
The argument data should be a pointer to a 2D data array. This pointer is attached to the Tool object (i.e., the object's data pointer data member is set to the argument). If a data array is already attached to the object, a warning is thrown and the argument is not attached.
Destructor. Destroys the Root object and then calls Obj_Destroy on the RectList and TData object data members. Never call this procedure directly; it is invoked by IDL's Obj_Destroy function.
Calls Root::add_history, ObArray::get_at, Rect::get_bottom_left, Rect::get_top_right, Rect::set_at
This procedure makes sure the coordinates specified for a given rectangle are valid, i.e., that they lie within the image dimensions of the currently attached data array. If the top, right, bottom, or left coordinates are negative or larger than the appropriate dimension of the array, they are set to the array size.
Structure definition. Specifies the contents of the IDL structure instantiated by the Tool class. Used by Obj_New; do not invoke directly.
Creates a new pointer for the object's data data member. It does not call Ptr_Free and release the memory allocated to the data, since under most circumstances, the data will be needed (i.e., for a successive reduction step).
Calls ObArray::get_size, DataList::get_num_arrays, Root::dump_stat
This is a standard OIL class method. For the Tool class, it dumps values of the data members (or the object validity status of the object data members), followed by the data members of the parent Root object, to the command output window. The dump will look best if the output font is fixed rather than proportional width.
Calls ObArray::get_at
Return Rect activeRect
Returns the current active rectangle.
Return int nActiveRect
Returns the zero-relative number indicating which of the defined analysis rectangles for the data array is currently "active," (i.e., will be operated upon by tool actions).
Return ObArray rectList
Returns the ObArray member object RectList.
Return DataList tData
Returns the DataList member object TData.
Calls Root::add_history, Tool::is_valid
Return bool TRUE, FALSE
Every class based on Tool has a go function that initiates that tool's action. In the case of this base class, it just checks to see if the Tool is valid. If it is not, it writes an error to the event log and returns FALSE. Otherwise, it returns TRUE. Thus, you can add a call to this function from any child object to verify validity before proceeding with the child object's actions on the data.
keyword bool verbose
keyword struct _EXTRA
Return pointer subImage
Constructor. It initializes the Root object and creates the RectList and TData object data members. Never call this function directly; it is invoked by IDL's Obj_New function.
Calls Root::add_history, Root::is_valid, ObArray::is_valid, DataList::is_valid
Return long[2] valid
Each OIL class has an is_valid function that performs class-specific tests on its data members. If all members are found to be valid, however validity is defined for that class, this funtion returns 1. Otherwise, a negative number is returned that contains a bitwise combination of all errors detected. In the case of Tool, the bitwise values of the validity state are -1 (no attached data), -2 (no rectangles specified), -4 (no rectangles in the Rect object array), -8 (no tool data specified), -16 (tool data list is invalid). The function returns a two-element array of longs, the first element containing the validity state of the Root, and the second that of the Filelink. An event is written to the log if the BasicFITSHeader is invalid.
Sets the object's verbose data member to zero.
argument int active
Calls Root::add_history, ObArray::get_size
Changes the index number of the active rectangle. It throws a warning if the argument is out of range (i.e., greater than the number of rectangles in the zero-relative list).
argument int[4] coords
argument int active
Calls Root::add_history, ObArray::get_size, ObArray::get_at, Rect::set
Sets the coordinates of rectangle active to coords, and makes the rectangle the active rectangle. The four-element coords array should specify top, left, bottom, and right of the rectangle, respectively.
argument int x
argument int y
argument int maxVal
Calls Root::add_history
Shows the data attached to the object, or throws a message if no data are attached. The data are then displayed using TvSCL, with the Top keyword to TVScl optionally specified by maxVal.
argument int which
argument var[ ] els
argument var[ ] vals
Calls Root::add_history, Datalist::get_num_arrays, Datalist::set_array_at
This procedure allows you to update the tool data values stored in the datalist TData. The which argument specifies which datalist array will be updated, and the els and vals arrays specify what values should be inserted into which array elements.
Sets the object's verbose data member to one.
obj = Obj_New( 'Tool' )
Obj_Destroy( obj )