; docformat = 'rst'
;
; NAME:
;   cgTransparentImage
;
; PURPOSE:
; Creates a semi-transparent image for display. Optionally, a  "missing" 
; color or color index (for 2D images) can be set to a completely transparent value.
; The transparent image can be saved as a transparent PNG file.
;
;******************************************************************************************;
;                                                                                          ;
;  Copyright (c) 2012, by Fanning Software Consulting, Inc. All rights reserved.           ;
;                                                                                          ;
;  Redistribution and use in source and binary forms, with or without                      ;
;  modification, are permitted provided that the following conditions are met:             ;
;                                                                                          ;
;      * Redistributions of source code must retain the above copyright                    ;
;        notice, this list of conditions and the following disclaimer.                     ;
;      * Redistributions in binary form must reproduce the above copyright                 ;
;        notice, this list of conditions and the following disclaimer in the               ;
;        documentation and/or other materials provided with the distribution.              ;
;      * Neither the name of Fanning Software Consulting, Inc. nor the names of its        ;
;        contributors may be used to endorse or promote products derived from this         ;
;        software without specific prior written permission.                               ;
;                                                                                          ;
;  THIS SOFTWARE IS PROVIDED BY FANNING SOFTWARE CONSULTING, INC. ''AS IS'' AND ANY        ;
;  EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES    ;
;  OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT     ;
;  SHALL FANNING SOFTWARE CONSULTING, INC. BE LIABLE FOR ANY DIRECT, INDIRECT,             ;
;  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED    ;
;  TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;         ;
;  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND             ;
;  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT              ;
;  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS           ;
;  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.                            ;
;******************************************************************************************;
;
;+
; Creates a semi-transparent image for display. Optionally, a  "missing" 
; color or color index (for 2D images) can be set to a completely transparent value.
; The transparent image can be saved as a transparent PNG file.
;
; :Categories:
;    Graphics
;    
; :Params:
;    image: in, optional, type=byte
;       A 2D image or a 24-bit image with or without an alpha channel. If an alpha
;       channel is present, it will be modified by the program.
;       
; :Keywords:
;     brewer: in, optional, type=boolean, default=0
;         This keyword is used only if the `CTIndex` keyword is used to select a color table number.
;         Setting this keyword allows Brewer color tables to be used.
;         
;     ctindex: in, optional, type=integer
;         The index number of a color table. The `Brewer` and `Reverse` keywords will be checked
;         to see how to load the color table into the `Palette` keyword. This keyword will take
;         precidence over any colors that are loaded with the `Palette` keyword. 
;         
;     missing_value: in, optional, type=various
;        The "color" of a pixel that will be treated as a "missing" color or value.
;        Any pixels in the image with this color value will be set completely
;        transparent. If `Color` is a string, use cgColor to obtain a color triple. 
;        If `Color` is a non-strint scalar, this value is taken to be the missing color index
;        in a 2D image. Otherwise, this is assumed to be a color triple that indicates
;        the "missing" color or value in the output image. The alpha channel in the output image
;        is set to 0 for the "missing" color, which makes this value completely transparent.
;        
;     filename: in, optional, type=string
;         The name of an image file that can be read with READ_IMAGE. Used to
;         select the input image if the `image` parameter is not used.
;        
;     nogui: in, optional, type=boolean, default=0
;         Set this keyword if you do not wish to have the user confirm the name of
;         the output PNG file selected with the `PNGFile` keyword.
;         
;     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 transparent image is created. Such vectors can be 
;         obtained, for example, from cgLoadCT with the RGB_TABLE keyword::
;               
;                IDL> cgLoadCT, 4, /BREWER, /REVERSE, RGB_TABLE=palette
;                IDL> tImage = cgTransparentImage( cgDemoData(7), PALETTE=palette)
;                
;         The default is to use whatever colors are loaded in the current hardware color table.
;         A palette applies only to 2D input images.
;         
;     pngfile: in, optional
;         If this keyword is set, the output image is written as a transparent
;         PNG file in 4xMxN format. Optionally, this keyword can be set to the
;         name of the output PNG file. The user will have the option of confirming
;         the name of the output file, unless the `NoGUI` keyword is set.
;         
;     reverse: in, optional, type=boolean, default=0
;         Set this keyword to reverse the color table vectors selected with the `CTIndex` keyword.

;     transparent: in, optional, type=integer, default=50
;         The percentage of transparency desired in the output image. A number 
;         between 0 and 100.
;        
;     wset: in, optional, type=long
;        If image parameter is not present, make the window indicated with
;        this keyword the current graphics window for obtaining an image parameter.
;        If not passed, and no image is present, then the current graphics window is 
;        used to create the image.
;
; :Examples:
;    To create and display a transparent image::
;       cgDisplay, WID=0
;       cgImage, cgDemoData(5), CTIndex=0, /Interp
;       timage = cgTransparentImage(MISSING_VALUE='black', TRANSPARENT=50)
;       cgDisplay, WID=1
;       cgImage, cgDemoData(7), CTIndex=22
;       cgImage, timage
;
; :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, 23 October 2012 to replace Make_Transparent_Image, which was retired. DWF.
;
; :Copyright:
;     Copyright (c) 2012, Fanning Software Consulting, Inc.
;-
FUNCTION cgTransparentImage, image, $
  BREWER=brewer, $
  CTINDEX=ctindex, $
  MISSING_VALUE=missing_value, $
  FILENAME=filename, $
  NOGUI=nogui, $
  PALETTE=palette, $
  PNGFILE=pngfile, $
  REVERSE=reverse, $
  TRANSPARENT=transparent, $
  WSET=wset
  
    Compile_Opt idl2

    Catch, theError
    IF theError NE 0 THEN BEGIN 
        Catch, /CANCEL
        void = cgErrorMsg()
        RETURN, image
    ENDIF
    
    ; Check for keyword values.
    IF N_Elements(transparent) EQ 0 THEN transparent = 50
    nogui = Keyword_Set(nogui)

    ; Make sure the transparent value is between 0 and 100 initially, and between 0 and 1 finally.
    transparent = (0 > transparent < 100) / 100.0
        
    ; Did the user pass an image? If not, read an image from the display.
    IF N_Elements(image) EQ 0 THEN BEGIN
    
        ; Did the user specify a filename?
        IF N_Elements(filename) NE 0 THEN BEGIN
            image = Read_Image(filename, r, g, b)
            IF N_Elements(r) NE 0 THEN palette = [[r],[g],[b]]
        ENDIF 
        IF N_Elements(image) EQ 0 THEN BEGIN
            IF (!D.Flags AND 256) EQ 0 THEN Message, 'Current device does not support windows.'
            IF N_Elements(wset) NE 0 THEN BEGIN
                thisWindow = !D.Window
                WSet, wset
            ENDIF
            image = cgSnapshot(TRUE=3)
            IF N_Elements(thisWindow) NE 0 THEN WSet, thisWindow
        ENDIF
    ENDIF
    
    ; What kind of image are we dealing with here?
    ndims = Size(image, /N_DIMENSIONS)
    CASE ndims OF
        2: BEGIN

           ; Use a color table to create a color palette?
           IF N_Elements(ctindex) NE 0 THEN BEGIN
              cgLoadCT, ctindex, Reverse=reverse, Brewer=brewer, RGB_TABLE=palette
           ENDIF
 
           IF N_Elements(palette) NE 0 THEN BEGIN
              IF (Size(palette, /DIMENSIONS))[0] EQ 3 THEN BEGIN
                 r = Reform(palette[0,*])
                 g = Reform(palette[1,*])
                 b = Reform(palette[2,*])
              ENDIF ELSE BEGIN
                 r = palette[*,0]
                 g = palette[*,1]
                 b = palette[*,2]
              ENDELSE
           ENDIF ELSE BEGIN
              TVLCT, r, g, b, /Get
           ENDELSE
           red = r[image]
           grn = g[image]
           blu = b[image]
           alpha = Byte(image) * 0 + (255 * (1.0 - transparent))
           
           ; Handle missing color index here.
           IF (N_Elements(missing_value) EQ 1) && (Size(missing_value, /TNAME) NE 'STRING') THEN BEGIN
              missingIndices = Where(image EQ missing_value, missingCnt)
              IF missingCnt GT 0 THEN alpha[missingIndices] = 0B
           ENDIF
           END
           
        3: BEGIN
           s = Size(image, /DIMENSIONS)
           index = Where(s EQ 3, count)
           IF count GT 0 THEN BEGIN
                CASE index OF
                   0: aImage = Transpose(image, [1,2,0])
                   1: aImage = Transpose(image, [0,2,1])
                   ELSE: aImage = image
                ENDCASE
                red = aImage[*,*,0]
                grn = aImage[*,*,1]
                blu = aImage[*,*,2]
                s = Size(aImage, /DIMENSIONS)
                alpha = BytArr(s[0], s[1]) + (255 * (1.0 - transparent))
           ENDIF
           index = Where(s EQ 4, count)
           IF count GT 0 THEN BEGIN
                CASE index OF
                   0: aImage = Transpose(image, [1,2,0])
                   1: aImage = Transpose(image, [0,2,1])
                   ELSE: aImage = image
                ENDCASE
                red = aImage[*,*,0]
                grn = aImage[*,*,1]
                blu = aImage[*,*,2]
                s = Size(aImage, /DIMENSIONS)
                alpha = BytArr(s[0], s[1]) + (255 * (1.0 - transparent))    
           ENDIF
           END
                      
        ELSE: Message, 'Input variable does not appear to be an image.'
    ENDCASE
    
    ; Did the user pass a color? 
    CASE N_Elements(missing_value) OF
        0: 
        1: BEGIN
           IF Size(missing_value, /TNAME) EQ 'STRING' THEN BEGIN
               missingColor = cgColor(missing_value, /TRIPLE)
           ENDIF
           END
        2: Message, 'The COLOR keyword contains unexpected values.'
        3: missingColor = missing_value
        ELSE: Message, 'The COLOR keyword must be a color triple.'
    ENDCASE
    
    ; Find the missing color in the image, if it is defined and this is not a 2D image.
    IF (N_Elements(missingColor) NE 0) && (Size(image, /N_DIMENSIONS) NE 2) THEN BEGIN
      indices = Where((red EQ missingColor[0]) AND (grn EQ missingColor[1]) $
                  AND (blu EQ missingColor[2]), count)
      IF count GT 0 THEN alpha[indices] = 0
    ENDIF
    
    ; Create the transparent image.
    transparentImage = [ [[red]], [[grn]], [[blu]], [[alpha]] ]
    transparentImage = Transpose(transparentImage, [2,0,1])
    
    ; Write this image to a file?
    IF Keyword_Set(pngfile) THEN BEGIN
        
        IF Size(pngfile, /TNAME) EQ 'STRING' THEN outfilename = pngfile ELSE outfilename = 'transparent.png'
        IF noGUI THEN BEGIN
            Write_PNG, outfilename, transparentImage
        ENDIF ELSE BEGIN
            outfilename = Dialog_Pickfile(Title='Select PNG File For Output...', $
                FILE=outfilename, FILTER='*.png')
            IF outfilename NE "" THEN BEGIN
               Write_PNG, outfilename, transparentImage
            ENDIF
        ENDELSE
        
    ENDIF
    
    ; Return the transparent image.
    RETURN, transparentImage
    
END