# Catalyst Source-Applications Directory On-Line Help

This page was created by the IDL library routine `mk_html_help`. For more information on this routine, refer to the IDL Online Help Navigator or type:

         ? mk_html_help

at the IDL command line prompt.

Last modified: Sun Oct 26 20:43:11 2008.

# List of Routines

- ANNOTATEWINDOW
- CATALYST
- IMGWIN

# Routine Descriptions

## ANNOTATEWINDOW

[Next Routine] [List of Routines]

     NAME:
           ANNOTATEWINDOW

     PURPOSE:

           The purpose of this routine is to allow the user to annotate or make
           measurements on a graphics window. A copy of the graphics window is
           created and placed into an annotation window. The user can create
           various kinds of file output from within the annotation window.

           Select the annotation tool from the tool bar at the top of the annotate
           window. Click and drag in the window to draw the annotation. (The text
           tool requires you to click in the window to start typing. Be sure to
           hit a carriage return at the end of typing to "set" the text in the
           window.) Click anywhere inside the tool to "select" it. Most tools
           allow you to move and edit the shape of the annotation after selection.
           Right click inside a selected annotation to access properties of that
           annotation, such as grouping, moving an annotation forward to backward,
           deleting the object, etc. Click the "Other Properties" button to access
           individual properties for the annotations. For example, if you mis-spelled
           some text, you would click on the text to select it. Right click to access
           it's select menu, select the Other Properties button, and find the text
           field in this pop-up dialog to change the spelling of the text.

     AUTHORS:

            FANNING SOFTWARE CONSULTING   BURRIDGE COMPUTING
            1645 Sheely Drive             18 The Green South
            Fort Collins                  Warborough, Oxon
            CO 80526 USA                  OX10 7DN, ENGLAND
            Phone: 970-221-0438           Phone: +44 (0)1865 858279
            E-mail: davidf@dfanning.com   E-mail: davidb@burridgecomputing.co.uk

     CATEGORY:

           Catalyst Applications.

     SYNTAX:

           AnnotateWindow, theBackground

     ARGUMENTS:

           theBackground:  This can either be the window index number of a graphics window,
                           or it can be an 8-bit or 24-bit image variable. If this argument
                           is undefined, the program tries to obtain a background image
                           from the current graphics window. Note that if the graphics window
                           contains a black background (the normal situation for many IDL
                           graphics windows), this will be reproduced *exactly* in PostScript
                           output. This is NOT the same as most PostScript output. If you
                           intend to create PostScript output of your annotated window, it
                           may be better to create graphics windows with white backgrounds.

                           Device, Decomposed=0, Get_Decomposed=currentState
                           TVLCT, [0, 255], [0,255], [0, 255], !D.Table_Size-3
                           Plot, findgen(11), Color=!D.Table_Size-3, Background=!D.Table_Size-2
                           Device, Decomposed=currentState
                           AnnotateWindow

     KEYWORDS:

          ADD_OBJECTS:     An object, or an array of objects to add to the Annotation Window.
                           Objects added in this fashion will be destroyed when the Annotate window
                           is destroyed.

          BG_COLOR:        The name of a background color. This is used only if there is a margin
                           around the background image. By default, "white". The background color
                           will always be "white" if the output is sent to a PostScript file. (See list
                           of color names below.)

          COLOR:           The name of the foreground color for the annotations. By default "Light Coral"
                           as something that might contrast enough with any background. (See list
                           of color names below.)

          NOMARGIN:        There is a 10% margin added to the background image, unless this keyword
                           is set, in which case the background image will fill the annotation window.

          OUTPUT_FILENAME: The base name of the output filename used in SAVE AS operations. By default, "annotation".

          XRANGE:          The TapeMeasure tool will report the distance in normalized coordinate space
                           by default. Use this keyword to specify a two-element array that represents
                           the minimum and maximum X range of the background image.

          YRANGE:          The TapeMeasure tool will report the distance in normalized coordinate space
                           by default. Use this keyword to specify a two-element array that represents
                           the minimum and maximum Y range of the background image.

         _EXTRA:           Any keywords appropriate for the ANNOTATEINTERACTION object.

     RESTRICTIONS:

           Requires the Catalyst Library from Fanning Software Consulting, Inc., or a catalyst.sav file
           to be restored prior to use. A Catalyst save file may be download from Coyote's Guide to IDL
           Programming. Be sure to download a version compatible with your IDL license.

               http://www.dfanning.com/programs/catalyst.sav (for IDL 6.1 or higher)

           The following color names can be used for the BG_COLOR and COLOR keywords:

               Active            Almond     Antique White        Aquamarine             Beige            Bisque
                 Black              Blue       Blue Violet             Brown         Burlywood        Cadet Blue
              Charcoal        Chartreuse         Chocolate             Coral   Cornflower Blue          Cornsilk
               Crimson              Cyan    Dark Goldenrod         Dark Gray        Dark Green        Dark Khaki
           Dark Orchid          Dark Red       Dark Salmon   Dark Slate Blue         Deep Pink       Dodger Blue
                  Edge              Face         Firebrick      Forest Green             Frame              Gold
             Goldenrod              Gray             Green      Green Yellow         Highlight          Honeydew
              Hot Pink        Indian Red             Ivory             Khaki          Lavender        Lawn Green
           Light Coral        Light Cyan        Light Gray      Light Salmon   Light Sea Green      Light Yellow
            Lime Green             Linen           Magenta            Maroon       Medium Gray     Medium Orchid
              Moccasin              Navy             Olive        Olive Drab            Orange        Orange Red
                Orchid    Pale Goldenrod        Pale Green            Papaya              Peru              Pink
                  Plum       Powder Blue            Purple               Red              Rose        Rosy Brown
            Royal Blue      Saddle Brown            Salmon       Sandy Brown         Sea Green          Seashell
              Selected            Shadow            Sienna          Sky Blue        Slate Blue        Slate Gray
                  Snow      Spring Green        Steel Blue               Tan              Teal              Text
               Thistle            Tomato         Turquoise            Violet        Violet Red             Wheat
                 White            Yellow

     EXAMPLE:

           To annotate a medical image:

             filename = Filepath(Subdirectory=['examples','data'], 'mr_knee.dcm')
             image = Read_DICOM(filename)
             AnnotateWindow, Rebin(image, 512, 512), XRange=[0,5], YRange=[0,5]

          Remember to right-click on any annotation object to access that objects properties.
          This is the way you would change a mis-spelled text label, add units to a measurement,
          change the color of an annotation object, etc.

          Also remember that you MUST type a carriage return when using the Text Tool to
          "set" the text into the annotation window.

     MODIFICATION_HISTORY:

           Written by: David W. Fanning, 25 July 2005.
           Improved documentation header. 11 August 2005. DWF.
           Added the ability to add annotation objects on initialization. 1 October 2008. DWF.
           Added the ability to make this a resizeable graphics window. 1 October 2008. DWF.

(See C:\IDL\Catalyst\source\applications\annotatewindow.pro)

## CATALYST

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           CATALYST

     PURPOSE:

           This program has no purpose except to test and evaluate Catalyst Library
           functionality. It can be used as examples of good programming practices
           (well, assuming your definition of "good" is pretty loose). The way it is
           used mostly is to look in the GUI method for the "names" of objects that
           generate events. Once you find a name, you look for that name in the EventHandler
           method. In this way, you slowly learn how Catalyst functionality is achieved.

     AUTHORS:

            FANNING SOFTWARE CONSULTING   BURRIDGE COMPUTING
            1645 Sheely Drive             18 The Green South
            Fort Collins                  Warborough, Oxon
            CO 80526 USA                  OX10 7DN, ENGLAND
            Phone: 970-221-0438           Phone: +44 (0)1865 858279
            E-mail: davidf@dfanning.com   E-mail: davidb@burridgecomputing.co.uk

     CATEGORY:

           Objects.

     SYNTAX:

           Catalyst

     MODIFICATION_HISTORY:

           Written by: David W. Fanning, April 17, 2003.

(See C:\IDL\Catalyst\source\applications\catalyst.pro)

## IMGWIN

[Previous Routine] [List of Routines]

     NAME:
           IMGWIN

     PURPOSE:

           This is an image display routine to allow the user to interact with
           an image. Moving the cursor in the window gives the value and location
           inside the image. The image is enclosed in a SCALEIMAGE object, so many of
           the input keywords are used to set the scaling parameters for that object.
           If axes are requested, an IMGAXIS object is added to the SCALEIMAGE object.
           Other keywords are used to set up the axis object. The entire window can
           be saved to file in various formats. The image can be scaled interactively,
           image colors can be changed, and various image and axes properties can be
           accessed directly from the File menu of the image window.

     AUTHORS:

            FANNING SOFTWARE CONSULTING   BURRIDGE COMPUTING
            1645 Sheely Drive             18 The Green South
            Fort Collins                  Warborough, Oxon
            CO 80526 USA                  OX10 7DN, ENGLAND
            Phone: 970-221-0438           Phone: +44 (0)1865 858279
            E-mail: davidf@dfanning.com   E-mail: davidb@burridgecomputing.co.uk

     CATEGORY:

           Graphics display.

     SYNTAX:

           ImgWin, image

     ARGUMENTS:

         image    An 8-bit or 24-bit image array, or the name of an image file that
                  can be opened with READ_IMAGE.

     INPUT_KEYWORDS:

         AXES:        Set this keyword to draw a set of axes around the image.

         BACKGROUND:  This keyword specifies the name of a background color. By default, 'ivory'.

         BETA:        The beta factor in a Hyperpolic Sine stretch. Default is 3.0.

         BOTTOM:      The lowest value of the scaled image.

         BREWER:      Set if the color table index number (CT) is the index of a Brewer color table.
                      To use Brewer color tables, the file fsc_brewer.tbl must be in your IDL path.

         COLOR:       Set this keyword to the name of the axis color. The name is passed to FSC_Color
                      for processing. Default is "charcoal". Used only if AXES is set.

         CTINDEX:     The index of the color table to use to display the image. Applies only to
                      2D image arrays. By default, 0, gray scale. If set to -1, uses current color table.

         EXPONENT:    The logarithm exponent in a logarithmic stretch. Default is 4.0.

         FULL_RESOLUTION: Set this keyword if you want the image to be displayed in its full, native resolution.
                       If this keyword is set, the XSIZE and YSIZE keywords set the scrollable window size.

         GAMMA:       The gamma factor in a gamma stretch. Default is 1.5.

         KEEP_ASPECT:  Normally, the image will be resized to fit the specified position in the
                       window. If you prefer, you can force the image to maintain its aspect ratio
                       in the window (although not its natural size) by setting this keyword.
                       The image width is fitted first. If, after setting the image width, the image
                       height is too big for the window, then the image height is fitted into the window.
                       The appropriate values of the POSITION keyword are honored during this fitting
                       process. Once a fit is made, the POSITION coordiates are re-calculated to center
                       the image in the window. You can recover these new position coordinates as the
                       output from the POSITION keyword. This keyword is turned ON by default. In other
                       words, to allow free positioning, set KEEP_ASPECT=0. Note that if this keyword is
                       set, and the XSIZE and YSIZE keywords are undefined, that the window will have the
                       same aspect ratio as the image.

         MEAN:         The mean factor in a logarithmic stretch. Default is 0.5.

         MISSING_COLOR: The name of the missing color. The default is "gray".

         MISSING_VALUE: The number that represents missing value in the image.

         NCOLORS:       The number of colors to scale the data into, as in this: (Default: 256)

                           displayImage = BYTSCL(image, MIN=self.sclmin, MAX=self.sclmax, TOP=self.ncolors-1)

         NOINTERP:      Setting this keyword disables the default bilinear
                        interpolation done to the image when it is resized. Nearest
                        neighbor interpolation is done instead. This is preferred
                        when you do not wish to change the pixel values of the image.
                        This keyword is turned ON by default. In other words, to allow
                        interpolation, set NOINTERP=0.

         POSITION:      The position of the image in the display window. The position is given
                        as a four-element array in normalized (0 to 1) coordinates of the form
                        [x0, y0, x1, y1], where (x0,y0) is the lower-left corner of the image and
                        (x1,y1) is the upper-right corner of the image. If the KEEP_ASPECT keyword
                        is set, the image will be located within the specified POSITION in a way
                        that preserves the aspect ratio of the image. The default is [0.075, 0.075, 0.925, 0.925].

         SCALETYPE:      The type of scaling performed prior to display. Default is 0, linear scaling.

               Number    Type of Stretch
                 0         Linear         scaled = BytScl(image, MIN=minThresh, MAX=maxThresh)
                 1         Gamma          scaled = GmaScl(image, MIN=minThresh, MAX=maxThresh, Gamma=gamma)
                 2         Log            scaled = LogScl(image, MIN=minThresh, MAX=maxThresh, Mean=mean, Exponent=exponent)
                 3         Asinh          scaled = AsinhScl(image, MIN=minThresh, MAX=maxThresh, Beta=beta)
                 4         Linear 2%      A linear stretch, with 2 percent of pixels clipped at both the top and bottom
                 5         Square Root    A linear stretch of the square root histogram of the image values.
                 6         Equalization   A linear stretch of the histogram equalized image histogram.
                 7         Gaussian       A Gaussian normal function is applied to the image histogram.

         SCLMIN:         The image data is scaled between SCLMIN and SCLMAX before display. Default = 0.

         SCLMAX:         The image data is scaled between SCLMIN and SCLMAX before display. Default = 255.

         SIGMA:          The sigma scale factor for Gaussian scaling. Default is 1.0.

         TLB_TITLE:      The title of the IMGWIN top-level base. Default: "Catalyst Image Window

         XRANGE:         If the AXES keyword is set, this keyword is a two-element vector
                         giving the X axis range. By default, [0, size of image in X].

         XSIZE:          The X size of the initial image window. If undefined, appoximately 600 pixels.
                         (Acutally size determined by the aspect ratio of the image.)

         XTICKFORMAT:    The tick formatting for the X axis, if the AXES keyword is set.

         XTILE:          The title of the X axis, if the AXES keyword is set.

         YRANGE:         If the AXES keyword is set, this keyword is a two-element vector
                         giving the Y axis range. By default, [0, size of image in Y].

         YSIZE:          The Y size of the initial image window. If undefined, appoximately 600 pixels.
                         (Acutally size determined by the aspect ratio of the image.)

         YTICKFORMAT:    The tick formatting for the Y axis, if the AXES keyword is set.

         YTILE:          The title of the Y axis, if the AXES keyword is set.

     OUTPUT_KEYWORDS:

         OUTIMAGE:        The image object that is created inside the program.

     MODIFICATION_HISTORY:

           Written by: David W. Fanning, 12 October 2008.

(See C:\IDL\Catalyst\source\applications\imgwin.pro)