Example: Simple iTool

This example creates a very simple iTool named example1tool that incorporates standard functionality from the iTools distribution, along with other example iTool features created in other chapters of this manual.

Example Code
The class definition code for this example iTool is included in the file example1tool__define.pro in the examples/doc/itools subdirectory of the IDL distribution. Run the example procedure by entering exampletool__define at the IDL command prompt or view the file in an IDL Editor window by entering .EDIT exampletool__define.pro.

Class Definition File

The class definition for the example1tool consists of an Init method and a class structure definition routine. As with all object class definition files, the class structure definition routine is the last routine in the file, and the file is given the same name as the class definition routine (with the suffix .pro appended).

Class Definition

PRO example1tool__Define 
 
struct = { example1tool,              $ 
           INHERITS IDLitToolbase     $ ; Provides iTool interface 
         } 
 
END

Discussion

Our class definition routine is very simple. We create an IDL structure variable with the name example1tool, specifying that the structure inherits from the IDLitToolbase class.

Init Method

FUNCTION example1tool::Init, _REF_EXTRA = _extra 
 
   ; Call our super class 
   IF ( self->IDLitToolbase::Init(_EXTRA = _extra) EQ 0) THEN $ 
      RETURN, 0 
 
   ;*** Visualizations 
   ; Here we register a custom visualization type described in 
   ; the "Creating Visualizations" chapter of this manual. 
 
   self->RegisterVisualization, 'Image-Contour', $ 
      'example1_visImageContour', ICON = 'image', /DEFAULT 
 
   ;*** Operations menu 
   ; Here we register a custom operation described in the "Creating 
   ; Operations" chapter of this manual. 
 
   self->RegisterOperation, 'Example Resample', $ 
      'example1_opResample', $ 
      IDENTIFIER = 'Operations/Examples/Resample' 
 
   ;*** File Readers 
   ; Here we register a custom file reader described in the 
   ; "Creating File Readers" chapter of this manual. 
    
   self->RegisterFileReader, 'Example TIFF Reader', $ 
      'example1_readTIFF', ICON='demo', /DEFAULT 
 
   ;*** File Writers 
   ; Here we unregister one of the standard file writers used 
   ; by the iTools, replacing it with a custom file writer 
   ; described in the "Creating File Writers" chapter of this 
   ; manual. 
 
   self->UnRegisterFileWriter, 'Tag Image File Format' 
 
   self->RegisterFileWriter, 'Example TIFF Writer', $ 
      'example1_writetiff', ICON='demo', /DEFAULT 
 
   RETURN, 1 
 
END

Discussion

The first item in our class definition file is the Init method. The Init method's function signature is defined first, using the class name example1tool. Note the use of the _REF_EXTRA keyword inheritance mechanism; this allows any keywords specified in a call to the Init method to be passed through to routines that are called within the Init method even if we do not know the names of those keywords in advance.

Next, we call the Init method of the superclass. In this case, we are creating a subclass of the IDLitToolbase class; this provides us with all of the standard iTool functionality automatically. Any "extra" keywords specified in the call to our Init method are passed to the IDLitToolbase::Init method via the keyword inheritance mechanism.

Because our iTool class will inherit from the IDLitToolbase class, our tool will automatically provide all of the standard features of the iTools. In addition, we register the following custom items:

A custom visualization type: Image-Contour. This visualization type is described in Creating a Visualization.

A new operation: Example Resample. This operation is described in Creating an Operation.

A new file reader: Example TIFF Reader. This file reader is described in Creating a File Reader.

We unregister the standard TIFF file writer, and register our a new filewriter: Example TIFF Writer. This file reader is described in Creating a File Writer.

Finally, we return the value 1 to indicate successful initialization.

Launch Routine

Our iTool launch routine also uses the class name example1tool. It accepts a single data argument, which we assume will contain an image array.

Example Code
The code for this example iTool launch routine is included in the file example1tool.pro in the examples/doc/itools subdirectory of the IDL distribution. Run the example procedure by entering example1tool at the IDL command prompt or view the file in an IDL Editor window by entering .EDIT example1tool.pro.

The code is shown below:

PRO example1tool, data, IDENTIFIER = identifier, 
_EXTRA = _extra 
 
IF (N_PARAMS() gt 0) THEN BEGIN 
   oParmSet = OBJ_NEW('IDLitParameterSet', $ 
      NAME = 'example 1 parameters', $ 
      ICON = 'image', $ 
      DESCRIPTION = 'Example tool parameters') 
 
   IF (N_ELEMENTS(data) GT 0) THEN BEGIN 
      oData = OBJ_NEW('IDLitDataIDLImagePixels') 
      result = oData->SetData(data, _EXTRA = _extra) 
      oParmSet->Add, oData, PARAMETER_NAME = 'ImagePixels' 
 
      ; Create a default grayscale ramp. 
      ramp = BINDGEN(256) 
      oPalette = OBJ_NEW('IDLitDataIDLPalette', $ 
         TRANSPOSE([[ramp], [ramp], [ramp]]), $ 
         NAME = 'Palette') 
      oParmSet->Add, oPalette, PARAMETER_NAME = 'PALETTE' 
 
   ENDIF 
 
ENDIF 
 
   IREGISTER, 'Example 1 Tool', 'example1tool' 
 
   identifier = IDLITSYS_CREATETOOL('Example 1 Tool',$ 
      VISUALIZATION_TYPE = ['Image-Contour'], $ 
      INITIAL_DATA = oParmSet, _EXTRA = _extra, $ 
      TITLE = 'First Example iTool') 
END

Launch Routine Discussion

Our iTool launch routine accepts a single data argument. We also specify that our launch routine should accept the IDENTIFIER keyword; we will use the variable specified as the value of this keyword (if any) to return the iTool identifier of the new iTool we create.

First, we check the number of non-keyword arguments that were supplied using the N_PARAMS function. If an argument was supplied, we create an IDLitParameterSet object to hold the data.

Next, we check to make sure the supplied data argument is not empty using the N_ELEMENTS function. If the supplied argument contains data, we create an IDLitDataIDLImagePixels object to contain the image data and add the object to our parameter set object, assigning the parameter name 'ImagePixels'.

Note
In the interest of brevity, we do very little data verification in this example. We could, for example, verify that the data argument contains a two-dimensional array of a specified type.

We next create a default grayscale ramp in an IDLitDataIDLPalette object, and assign this the parameter name 'Palette'.

We use the IREGISTER procedure to register our iTool class with the name "Example 1 Tool".

Finally, we call the IDLITSYS_CREATETOOL function with the registered name of our iTool class, specifying the visualization type as 'Image-Contour', which is the name of our custom visualization.