;+
; NAME: plot2png
;
;
;
; PURPOSE: 
;          Takes a plotting command (a procedure) and sends the result
;          to a PNG file of the user's choosing.  This is accomplished
;          by plotting to the z-buffer device, tvrd()ing the result
;          and saving that image to the PNG file.  The device is set
;          back to the original plotting device when the routine
;          exits.  Note that if the plot command fails, no PNG file is
;          created and an error message is generated.
;
;
;
; CATEGORY:
;          Plotting
;
;
; CALLING SEQUENCE: 
;            plot2png, filename, command[, vars, xsize=xsize,
;              ysize=ysize, /ignoreerror, extra keywords for z-buffer
;              device call]
;
;
;
; INPUTS:
;        filename:
;                   Filename of resulting PNG (string)
; 
;        command:

;                    The exact command to be execute to make the plot,
;                    with any variables defined at the main level 
;                    referrenced as "var.variable_name".  See below.  (String)

;
;
;
; OPTIONAL INPUTS:
;        var:        
;            Structure containing any variables used which are defined
;            at the main level.  (Rather than defined or read-in in the
;            plotting procedure.)  Any such variables are then called as
;            "var.variable_name" in the command string.
;
;
; KEYWORD PARAMETERS:
;        xsize, ysize: 
;                     x and y sizes of the z-buffer and therefore of
;                     the resulting PNG. Default is 640x480 pixels.
;
;        ignoreerror:
;                     If an error occurs in plotting, produce the PNG anyway.
;
;        /noclobber:
;                     If the file, filename, already exists, do NOT overwrite 
;                     it.  Instead, append _1, _2, ... to the end of the 
;                     file's base name.  (But before the extension.)
;                     Note that by default, plot2ps WILL clobber, or overwrite, 
;                     a pre-existing file!;
;        Extra keywords:  
;                    Any additional keywords to be used by the
;                    z-buffer device call.  "z-buffering" is always 
;                    set to 1 and "set_resolution" is set with xsize 
;                    and yzise.
;
; OUTPUTS:
;        None
;
;
; OPTIONAL OUTPUTS:
;        None
;
;
; COMMON BLOCKS:
;         Definitely none
;
;
; SIDE EFFECTS:
;
;
;
; RESTRICTIONS:
;
;
;
; PROCEDURE:
; 
;
;
; EXAMPLE:
;   IDL> x = findgen(101)/10.0          ; Create x-array
;   IDL> y = x^2                        ; Create y-array
;   IDL> plot, x, y                     ; Plots to screen (presumably)
;   IDL> plot2png, 'test.png', 'plot, var.x, var.y', {x:x, y:y}
;
;   Alternately, we can create the structure before calling plot2png:
;   IDL> var = {x:x, y:y}               ; Create the structure
;   IDL> plot, var.x, var.y             ; Test the plotting
;   IDL> plot2png, 'test.png', 'plot, var.x, var.y', var
; MODIFICATION HISTORY:
;
;    Created: 30 June 2005 by John Weiss
;
;-
pro plot2png, filename, command, var, xsize=xsize, ysize=ysize, noclobber=noclobber, ignoreerror=ignoreerror, _EXTRA=_EXTRA

; Check to make sure that the two required parameters are passed.  If
; not, exit.
if(n_params() LT 2) then begin
    print, "Syntax: plot2png, filename, command[, struct with variables used, xsize=xsize, ysize=ysize, other keywords for z-buffer device]"
    return
endif

; If this is set to use noclobber, see if the file exits.  If it does,
; use a modified name
if(keyword_set(noclobber)) then begin
                                ; The extension:
    extname = stregex(filename, "\.([A-Za-z]*)$", /extract)
    basename = file_basename(filename, extname) ; Get the basename (no path, no 
                                ; extension) of the file
    dirname = file_dirname(filename, /mark_directory) ; Name of the directory

    num = 0
    while(file_test(filename)) do begin
        num = num + 1
                                ; The new candidate name
        filename = dirname + basename+"_" + $
                   strcompress(string(num, format="(I)"), /remove_all) + $
                   extname
    endwhile
endif

; Save the current device
original_device = !d.name

; Set any unset, necessary keywords
if(not keyword_set(xsize)) then xsize=640
if(not keyword_set(ysize)) then ysize=480

; Change to the z-buffer and set the device parameters
set_plot, 'z'
device, z_buffering=1, $
        set_resolution = [xsize, ysize], $
        _EXTRA=_EXTRA
; Get the color table information
tvlct, r,g,b, /get

; Execute the command and record if it is successful.
success=execute(command)

; If the command failed, we might as well exit.  But tell the user
; we're doing so and clean up our mess.
if((not success) and (not keyword_set(ignoreerror))) then begin
    print, "Plot command did not execute successfully.  No PNG created."
    set_plot, original_device
    return
endif

; We succeeded in plotting, so read the plot in
img = tvrd()

; Reset the plotting device
set_plot, original_device

; Set the colors for each channel
ii=bytarr(3,xsize,ysize)
ii(0,*,*)=r[img]
ii(1,*,*)=g[img]
ii(2,*,*)=b[img]

; Write the PNG
write_png, filename, img, r, g, b

; We're done.

end