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.

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

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:

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

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.

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.

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 
 
   ITREGISTER, 'Example 1 Tool', 'example1tool' 
 
   identifier = IDLITSYS_CREATETOOL('Example 1 Tool',$ 
      VISUALIZATION_TYPE = ['Image-Contour'], $ 
      INITIAL_DATA = oParmSet, _EXTRA = _extra, $ 
      TITLE = 'First Example iTool') 
END 

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

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

We use the ITREGISTER 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.