# coyote: IMAGESELECT

- coyote/General Programming
- [Source code]

NAME

      IMAGESELECT

PURPOSE

      The purpose of this program is to allow the user to select a formatted
      image file for reading. The image data is returned as the result of the
      function. The program allows the user to see a thumbnail version of the
      image, along with information about the image, before selection. The
      program uses the file extention to determine what kind of image is to
      be read. The following image types are supported:
         TYPE      FILE EXTENSION
         BMP       *.bmp
         DICOM     *.dcm
         FITS      *.fits, *.fts (requires NASA ASTRO library on IDL Path)
         GIF       *.gif (IDL 6.2 and higher)
         JPEG      *.jpg, *.jpeg, *.jpe
         JPEG2000  *.jpf, *.jpx, *.jp2, *.j2c, *.j2k
         PICT      *.pict
         PNG       *.png
         TIFF      *.tif, *tiff

AUTHOR

      FANNING SOFTWARE CONSULTING
      David Fanning, Ph.D.
      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/

CATEGORY

      General programming.

CALLING SEQUENCE

      image = ImageSelect()

INPUT PARAMETERS

      None. All input is via keywords.

INPUT KEYWORDS

      BMP -- Set this keyword to select BMP files.
      DEMO -- If this keyword is set, the program changes directory to !DIR/examples/data.
      DICOM -- Set this keyword to select DICOM files.
      DIRECTORY -- The initial input directory name. The current directory by default.
      EXCLUDE -- A list of filenames that should excluded from the file selection list.
      FILENAME -- The initial filename. If the initial directory has image files of the
                  correct type, the default is to display the first of these files. Otherwise, blank.
      FILTER -- A string, representing the file filter. For example, '*.jpg'.
      FITS -- Set the keyword to select FITS files. (Must have NASA Astro Library on path.)
      FLIPIMAGE -- Set this keyword if you wish to flip the image from its current orientation. Setting
                   this keyword reverses the Y dimension of the image.
      GIF -- Set this keyword to select GIF files. (IDL versions before 5.4 and after 6.0, only.)
      GROUP_LEADER -- Set this keyword to a widget identifier group leader. This keyword MUST be
                      set when calling this program from another widget program to guarantee modal operation.
      J2000 -- Set this keyword to select JPEG2000 files. (May also be set as J2K.) (IDL 6.1 or above.)
      J2K -- Set this keyword to select JPEG2000 files. (May also be set as J2000.) (IDL 6.1 or above.)
      JPEG -- Set this keyword to select JPEG files.
      LISTXSIZE -- Set this keyword to the XSIZE of the list widget. Default is 30 or MAX(StrLen(filenames)), whichever is larger.
      OFFSETS -- A two-element array containing the X and Y offsets of the program, from the upper left
                 corner of the display. On dismissal of the program, if this is a named variable (passed into
                 the program by reference), then it will contain the last offsets of the program. This is
                 useful if you want to call ImageSelect again and have it positioned in exactly the same
                 location it was before.
      ONLY2D -- Set this keyword if you only want the user to be able to select 2D images. Note
                that the user will be able to browse all images, but the Accept button will only
                be sensitive for 2D images.
      ONLY3D -- Set this keyword if you only want the user to be able to select 3D or true-color images.
                Note that the user will be able to browse all images, but the Accept button will only
                be sensitive for 3D or true-color images.
      PICT -- Set this keyword to select PICT files.
      PGM -- Set this keyword to select PGM files.
      PPM -- Set this keyword to select PPM files.
      PNG -- Set this keyword to select PNG files.
      PREVIEWSIZE -- Set this keyword to the maximum size (in pixels) of the preview window. Default is 150.
      SILENT -- Set this keyword to turn off Group_Leader educational message. Use only if you
                are sure you know what you are doing. :-)
      TIFF -- Set this keyword to select TIFF files. (This is the default filter selection.)
      TITLE -- Set this keyword to the text to display as the title of the main image selection window.
      NOTE: Any extra keywords passed into the program will collected and passed along to the READ_XXX routines
      that actually do the image file reading. Using this keyword inheritance mechanism makes it impossible
      to trap misspelled or misused keywords. Please take care when using ANY keyword for this routine!

OUTPUT KEYWORDS

      CANCEL -- This keyword is set to 1 if the user exits the program in any way except hitting the ACCEPT button.
                The ACCEPT button will set this keyword to 0.
      FHEADER -- Set this keyword to a named variable that will return the FITS header information for a FITS file.
      FILEINFO -- This keyword returns information about the selected file. Obtained from the QUERY_**** functions.
      GEOTIFF --  If the file is a GeoTIFF file, this keyword will return the GeoTIFF structure containing
                  the files GeoTags.
      OUTDIRECTORY -- The directory where the selected file is found.
      OUTFILENAME -- The short filename of the selected file.
      PALETTE -- The current color table palette returned as a 256-by-3 byte array.

COMMON BLOCKS

      None.

RESTRICTIONS

      Requires other programs from the Coyote Library.
      ote: Keyword inheritance to collect undefined keywords that may be passed into the
      rogram for use in READ_XXX routines, make it impossible to trap keyword useage errors.
      lease take care when using keywords.

EXAMPLE

      To read JPEG files from the directory:
         IDL> image = ImageSelect(/JPEG)

MODIFICATION HISTORY

      Written by: David W. Fanning, 18 Jan 2001.
      Added modification to read both 8-bit and 24-bit BMP files. 27 Jan 2001. DWF.
      Fixed a problem with calculating the new size of the draw widget. 5 April 2002. DWF.
      Fixed a problem with List Widgets not sizing correctly on UNIX machines. 10 Aug 2002. DWF.
      Fixed a problem with the initial file not being selected correctly when you changed
        the file type. 10 Aug 2002. DWF.
      Added a FLIPIMAGE keyword 10 Aug 2002. DWF.
      When user chooses to Flip Image, I now reverse the Y dimension of the image,
        rather than set the !Order system variable. 10 Aug 2002. DWF.
      Added OUTDIRECTORY and OUTFILENAME keywords. 18 Aug 2002. DWF.
      Fairly extensive changes in the way this program works and selects images.
        A new version of FSC_FileSelect is also required. Because of interactions
        with the operating system with image filters, the program has probably
        become more Windows-centric. The default is now to display all image
        files the program is capable of reading. 31 October 2002. DWF.
      Added ONLY2D keyword to allow the acceptance of 2D images only. 3 Nov 2002. DWF.
      Added ability to center itself on the display. 8 Nov 2002. DWF.
      Fixed a problem caused by reading old images with short color table vectors. 26 Nov 2002. DWF.
      Fixed a problem with specifying a fully-qualified filename. 26 Nov 2002. DWF.
      Now highlights the selected file in the directory. 26 Nov 2002. DWF.
      Improved error handling. 9 Dec 2002. DWF.
      Added PALETTE keyword and improved color operation on 8-bit displays. If the image file
        contains a color palette, that palette is now loaded when the image is read from the file.
        The current color palette can be obtained with the PALETTE keyword. 4 April 2003. DWF.
      Added ONLY3D keyword. 19 April 2003. DWF.
      Added ability to read PPM and PGM files. 24 November 2003. DWF.
      Added TITLE keyword. 1 December 2003. DWF.
      Added EXAMPLES keyword. 22 December 2005. DWF.
      Added GIF and JPEG2000 file types. Rearranged and cleaned up code. 3 January 2006. DWF.
      Added LISTXSIZE keyword. 3 January 2006. DWF.
      Added file type checkmark buttons. Program now compatible with IDL 5.6 and higher. 3 January 2006. DWF.
      Improved error handling with invalid file types. 5 January 2006. DWF.
      Added OFFSETS and EXCLUDE keywords. 3 March 2006 DWF.
      Modified the program to check for FITS unsigned integer data. 3 March 2006. DWF.
      Added ability to double-click image name in list to Accept. 10 March 2006. DWF.
      Added FHEADER keyword to return FITS header information. 3 April 2006. DWF.
      Fixed a problem in which the file type was not set if the user cancelled. 10 July 2006. DWF.
      Added a "fit" file extension for FITS images. 1 April 2008. DWF.
      Added a FILTER keyword. 1 April 2008. DWF.
      Updated for reading transparent images. 13 May 2009. DWF.
      Provided check for PNG images with more than 8 bits per channel. 5 August 2009. DWF.
      Fixed a problem in which the starting directory was changed on exit. 20 Nov 2010. DWF.
      Change EXAMPLES to more easily remembered DEMO keyword. 29 Nov 2010. DWF.
      Removed NOINTERPOLATION keywords in going from TVIMAGE to cgImage. 22 Feb 2011. DWF.
      Fixed a problem reading 2D Tiff files. 20 Sept 2012. DWF.