The Solar-Stellar Spectrograph

[ 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 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.

Version History

2008 July 14 - Documentation written.


Data Members

bool verbose

pointer data

int activeRect

ObArray RectList

DataList TData


Method List








get_active_rect( )

get_active_rect_num( )

get_rect_array( )

get_tdata( )

go( )

init( )

is_valid( )








Method Descriptions


PRO add_active_rect

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.


PRO attach_data

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.


PRO cleanup

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.


PRO crop_active_rect

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.


PRO define

Structure definition. Specifies the contents of the IDL structure instantiated by the Tool class. Used by Obj_New; do not invoke directly.


PRO detach_data

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).


PRO dump_stat

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.


FUNCTION get_active_rect

Calls ObArray::get_at

Return Rect activeRect

Returns the current active rectangle.


FUNCTION get_active_rect_num

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).


FUNCTION get_rect_array

Return ObArray rectList

Returns the ObArray member object RectList.


FUNCTION get_tdata

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.


FUNCTION is_valid

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.


PRO nonverbose

Sets the object's verbose data member to zero.


PRO rect_active_rect

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).


PRO set_rect

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.


PRO show_data

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.


PRO update

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.


PRO verbose

Sets the object's verbose data member to one.


Sample Usage

obj = Obj_New( 'Tool' )

Obj_Destroy( obj )


[Back to contents]

Supported by grants from the National Science Foundation.
[ Back to my home page | Email me: jch [at] lowell [dot] edu ]
The SSS is publicly funded. Unless explicitly noted otherwise, everything on this site is in the public domain.
If you use or quote our results or images, we appreciate an acknowledgment.
This site is best viewed with Mozilla Firefox.