# coyote: CGZIMAGE

- coyote/Graphics
- [Source code]

Description

      Allows the user to interactively zoom into an image. Program controls are available
      by right-clicking in the full-sized image window. Zoom factors from 2x to 16x are
      available. Use the left mouse button to draw a box on the full-sized image to locate
      the region of the image to zoom.

Categories

      Graphics

Examples

      Code examples::
         IDL> image = cgDemoData(7)
         IDL> cgZImage, image ; 2D image
         IDL> image = cgDemoData(16)
         IDL> cgZImage, image ; True-Color image

Author

      FANNING SOFTWARE CONSULTING::
         David W. Fanning
         1645 Sheely Drive
         Fort Collins, CO 80526 USA
         Phone: 970-221-0438
         E-mail: david@idlcoyote.com
         Coyote's Guide to IDL Programming: http://www.idlcoyote.com

History

      Change History::
         Written, 20 September 2012 from previous FSC_ZImage program. DWF.
         Modernized the info structure handling to reflect modern sensibilities. 3 Oct 2012. DWF.
         Changes to allow this to work with very large images. Can now zoom to actual pixel values.
            Also fixed a problem that left zoom windows lying around unused if scroll bars were
            needed. 18 October 2012. DWF.
         The color palette was not always being included when images were zoomed. Fixed. 17 Nov 2012. DWF.
         Added ZoomFactor keyword to allow the zoom factor to be set on start-up. 28 Nov 2012. DWF.
         Fixed a typo that caused bringing controls into the window to fail. 13 Jan 2014. DWF.

Copyright

      Copyright (c) 2012-2014, Fanning Software Consulting, Inc.
      t handler for the motion events coming from the zoom window. Find the location
      value of the image at the cursor location and report it to the status bar in the
       image window.

Params

      image: in, required, type=any
          A 2D or true-color image of any normal data type. If not a BYTE array,
          cgImage keywords for proper image scaling must be used to provide image
          scaling parameters.

Keywords

      beta: in, optional, type=float, default=3.0
           The beta factor in a Hyperpolic Sine stretch. Available only with 2D images.
      bottom: in, optional, type=integer, default=0
           If the SCALE keyword is set, the image is scaled before display so that all
           displayed pixels have values greater than or equal to BOTTOM and less than
           or equal to TOP. Available only with 2D images.
      boxcolor: in, optional, type=string, default='gold'
           The name of the color of the rubber-band selection box.
      clip: in, optional, type=float, default=2
           A number between 0 and 50 that indicates the percentage of pixels to clip
           off either end of the image histogram before performing a linear stretch.
           Available only with 2D images.
      exclude: in, optional, type=numeric
           The value to exclude in a standard deviation stretch.
      exponent: in, optional, type=float, default=4.0
           The logarithm exponent in a logarithmic stretch. Available only with 2D images.
      filename: in, optional, type=string
           The name of a file that IDL can read with READ_IMAGE (e.g, GEOTIFF, TIF, JPEG, PNG, etc.).
      gamma: in, optional, type=float, default=1.5
           The gamma factor in a gamma stretch. Available only with 2D images.
      group_leader: in, optional, type=long
           The widget identifier of the group leader for this program. When the group leader
           dies, this program will be destroyed, too.
      interpolate: in, optional, type=boolean, default=0
           Set this keyword to interpolate with bilinear interpolation the display image as it
           is sized to its final position in the display window. Interpolation will potentially
           create image values that do not exist in the original image. The default is to do no
           interpolation, so that image values to not change upon resizing. Interpolation can
           result in smoother looking final images.
      map: in, optional, type=structure
           A cgMap object for navigating the input image.
      maxvalue: in, optional, type=varies
           If this value is defined, the data is linearly scaled between MINVALUE
           and MAXVALUE. MAXVALUE is set to MAX(image) by default. Setting this
           keyword to a value automatically sets `SCALE` to 1. If the maximum value of the
           image is greater than 255, this keyword is defined and SCALE=1.
      mean: in, optional, type=float, default=0.5
           The mean factor in a logarithmic stretch. Available only with 2D images.
      minvalue: in, optional, type=varies
           If this value is defined, the data is linearly scaled between MINVALUE
           and `MAXVALUE`. MINVALUE is set to MIN(image) by default. Setting this
           keyword to a value automatically sets SCALE=1. If the minimum value of the
           image is less than 0, this keyword is defined and SCALE=1.
      missing_color: in, optional, type=string, default='white'
           The color name of the missing value. Available only with 2D images.
      missing_index: in, optional, type=integer, default=255
           The index of the missing color in the final byte scaled image. Available only with 2D images.
      missing_value: in, optional, type=integer
           The number that represents the missing value in the image. Available only with 2D images.
      multiplier: in, optional, type=float
           The multiplication factor in a standard deviation stretch. The standard deviation
           is multiplied by this factor to produce the thresholds for a linear stretch.
      ncolors: in, optional, type=integer, default=256
           If this keyword is supplied, the `TOP` keyword is ignored and the TOP keyword
           is set equal to  NCOLORS-1. This keyword is provided to make cgImage easier
           to use with the color-loading programs such as cgLOADCT::
                cgLoadCT, 5, NColors=100, Bottom=100
                cgImage, image, NColors=100, Bottom=100
           Setting this keyword to a value automatically sets SCALE=1. Available only with 2D images.
      negative: in, optional, type=boolean, default=0
           Set this keyword if you want to display the image with a negative or reverse stretch.
           Available only with 2D images.
      palette: in, optional, type=byte
           Set this keyword to a 3x256 or 256x3 byte array containing the RGB color
           vectors to be loaded before the image is displayed. Such vectors can be
           obtained, for example, from cgLoadCT with the RGB_TABLE keyword::
                  cgLoadCT, 4, /BREWER, /REVERSE, RGB_TABLE=palette
                  cgImage, cgDemoData(7), PALETTE=palette
      scale: in, optional, type=boolean, default=0
           Set this keyword to byte scale the image before display. If this keyword is not set,
           the image is not scaled before display. This keyword will be set automatically by using
           any of the keywords normally associated with byte scaling an image. Available only with
           2D images. If set, STRETCH is set to 1, unless it is set to another value.
      stretch: in, optional, type=integer/string, default=1
           The type of scaling performed prior to display. May be specified as a number
           or as a string (e.g, 3 or "Log"). Available only with 2D images.
             Number   Type of Stretch
               0         None           No scaling whatsoever is done.
               1         Linear         scaled = BytScl(image, MIN=minValue, MAX=maxValue)
               2         Clip           A histogram stretch, with a percentage of pixels clipped at both the top and bottom
               3         Gamma          scaled = cgGmaScl(image, MIN=minValue, MAX=maxValue, Gamma=gamma)
               4         Log            scaled = LogScl(image, MIN=minValue, MAX=maxValue, Mean=mean, Exponent=exponent)
               5         Asinh          scaled = AsinhScl(image, MIN=minValue, MAX=maxValue, Beta=beta)
               6         SquareRoot     A linear stretch of the square root histogram of the image values.
               7         Equalization   A linear stretch of the histogram equalized image histogram.
               8         Gaussian       A Gaussian normal function is applied to the image histogram.
               9         MODIS          Scaling done in the differential manner of the MODIS Rapid Response Team
                                        and implemented in the Coyote Library routine ScaleModis.
      sigma: in, optional, type=float, default=1.0
           The sigma scale factor in a Gaussian stretch. Available only with 2D images.
      title: in, optional, type=string, default=""
           Set this keyword to the title of the plot window.
      top: in, optional, type=integer, default=255
           If the SCALE keyword is set, the image is scaled before display so that all
           displayed pixels have values greater than or equal to BOTTOM and less than
           or equal to TOP. Available only with 2D images.
      zoomfactor: in, optional, type=string, default=3
           Use this keyword to set the starting zoom factor. The values you can use are as follows::
                0: 'Actual'
                1: '2x'
                2: '3x'
                3: '4x'
                4: '5x'
                5: '6x'
                6: '7x'
                7: '8x'
                8: '12x'
                9: '16x'