;+
; NAME:
;
;  plomake.pro    (Plot Make)
;
;
; LICENSE:
;
;  You may use this routine for free and alter it as you see fit. This
;  routine has been written to save me time when drawing basic
;  plots. As such, there is nothing fancy in here and there is no way
;  anyone could ever possibly sell this code. I hope it comes in handy
;  to someone who is learning IDL.
;
;  This is provided AS-IS, without warranty.
;
; PURPOSE:
;
;  Generate plots with desired layout and appearance.
;
;
; INPUTS:
;
;  x    - An array to be plotted.  Must be one dimensional. If the
;         optional y input is provided, then this will serve as the
;         x-axis. 
;
; OPTIONAL INPUTS:
;
;  y    - An array of values to be plotted versus the input x.
;
; KEYWORD PARAMETERS:
;
;  nc   - Number of Colors, if set, the value of this keyword
;         determines the number of colors used in the plot.  The
;         default value is 20.
;  pc   - Plot Color, if set, the value of this keyword corresponds to
;         the color number used for plotting the array and the
;         axes. The default is to plot either black or white, the
;         opposite of the background color.
;  nf   - Not Full, if set, this keyword cancels the default plotting
;         behavior of using the full window space and not displaying a
;         title.
;  xlab - X Label, set to a string that will serve as the label for
;         the x-axis. The default is a blank space.
;  ylab - Y Label, set to a string that will serve as the label for
;         the y-axis. The default is a blank space.
;  t    - Title, set to a string that serves as the title (above the
;         plot). Note that when using FULL, there is no room above the
;         plot and therefore the t keyword should not be used.
;  cs   - Character Size, set to a value representing the character
;         size used in the axis labels (numbers and titles). The
;         default value is 1.5, which means the characters are printed
;         1.5 times larger than the standard size IDL would produce if
;         no such setting were provided.
;  ct   - Character Thick, set to a value representing the thickness
;         of the characters (axis numbers and titles). The default
;         value is 2, which means characters are drawn with a
;         thickness 2 times that of the IDL default.
;  pt   - Plot Thickness, set to a value that represents the thickness
;         of the plotted line. The default value is 2, meaning that a
;         line with a thickness 2 times the default IDL thickness will
;         be plotted.
;  sf   - Save File, set to a string that serves as the filename for a
;         Portable Network Graphics (PNG) image that is constructed
;         from the current graphics window. The png extension is
;         automatically added, so a sampe filename is given by: 
;         sf = 'sample' 
;         NOTE: the entire path may be provided as this keyword and
;         providing only a filename will result in the file being
;         saved in the present working directory. A second example of
;         an acceptable value is:
;         sf = '~/my_dir/idl_images/sample'
;  xs   - X Style, value to be used for the IDL XSTYLE keyword. The
;         default value is 1.
;  ys   - Y Style, value to be used for the IDL YSTYLE keyword. The
;         default value is 1.
;  many - Many (Plots to Make), if set, this keyword prevents the
;         loading of the color table. This will save time if you use
;         the plomake routine in any repetitive loop (e.g. while
;         making a series of images that will be turned into a movie).
;  xr   - X Range, set as a two element array that provides the
;         boundaries for plotting of the x-axis. For example:
;         xr = [ 0, 4 ]
;         will cause the plot to be limited to the window from x = 0
;         to x = 4.
;  yr   - Y Range, set as a two element array that provides the
;         boundaries for plotting of the y-axis.
;
; OUTPUTS:
;
;  A plot is drawn to the present graphics window. If no window is
;  already open, then a new one will be created and used.
;
; OPTIONAL OUTPUTS:
;
;  If the sf keyword is set, then an image file (PNG) will be saved. 
;
; EXAMPLE:
;
;  To plot the arrays x and y:
;    plomake, x, y
;
;  To plot the arrays x and y with a white background, while taking up
;  almost all of the graphics window space and placing X as the title
;  of the x-axis:
;    plomake, x, y, /full, xlab='X'
;
; MODIFICATION HISTORY:
;
;  02/28/2006 - Created by David Pace  (www.davidpace.com)
;  03/20/2006 - Major revisions (essentially a new routine).
;-

PRO plomake, x, y, $
             nc = nc, $
             pc = pc, $
             nf = nf, $
             xlab = xlab, $
             ylab = ylab, $
             t = t, $
             cs = cs, $
             ct = ct, $
             pt = pt, $
             sf = sf, $
             xs = xs, $
             ys = ys, $
             many = many, $
             xr = xr, $
             yr = yr

  npm = N_PARAMS()

  IF ( npm EQ 0 ) THEN BEGIN
      PRINT, "Basic usage of plomake.pro"
      PRINT, "--------------------"
      PRINT, "plomake, x, y, nc = INTEGER, xlab = STRING, ylab = STRING"
  ENDIF ELSE BEGIN

      ;determine size of x array
      xsize = N_ELEMENTS( x )

      ;determine extrema values of x array
      xmax = MAX( x, MIN = xmin )

      ;set color scheme
      IF ~KEYWORD_SET( nc ) THEN nc = 20 
      
      IF ~KEYWORD_SET( many ) THEN BEGIN
          ;setup a color table (rainbow)
          LOADCT, 39, NCOLORS = nc
          DEVICE, DECOMPOSED = 0
      ENDIF

      ;set background as white
      bc = nc - 1

          ;if plot color (pc) not set,then revert to default to avoid errors
      IF ~KEYWORD_SET( pc ) THEN pc = 0

      ;set relative size of plot
      IF ~KEYWORD_SET( nf ) THEN BEGIN
          pos = [ 0.09, 0.15, 0.92, 0.98 ] ;only room for x-label
      ENDIF ELSE BEGIN
          pos = [ 0.15, 0.15, 0.85, 0.85 ] ;leaves room for labels
      ENDELSE

      ;if no labels provided, then make them blanks to avoid errors
      IF ~KEYWORD_SET( xlab ) THEN xlab = ' '
      IF ~KEYWORD_SET( ylab ) THEN ylab = ' '
      IF ~KEYWORD_SET( t ) THEN t = ' '

      ;if no character settings provided, then revert to defaults
      IF ~KEYWORD_SET( cs ) THEN cs = 1.5
      IF ~KEYWORD_SET( ct ) THEN  ct = 2.0

      ;if not plot style settings provided, then revert to defaults
      IF ~KEYWORD_SET( pt ) THEN pt = 2

      ;set line styles, default is xy-style = 1
      IF ~KEYWORD_SET( xs ) THEN xs = 1
      IF ~KEYWORD_SET( ys ) THEN ys = 1

      ;if only one array provided, then plot with standard x-axis
      IF ( npm EQ 1 ) THEN BEGIN
          ;set plotting boundaries
          IF ~KEYWORD_SET( xr ) THEN BEGIN
              xr = [ 0, xsize - 1 ]
          ENDIF

          ;recall that in this case the x input is plotted as the y values
          IF ~KEYWORD_SET( yr ) THEN BEGIN
              yr = [ xmin, xmax ]
          ENDIF

          PLOT, x, $
            CHARSIZE = cs, CHARTHICK = ct, $ ;character settings
            BACKGROUND = bc, COLOR = pc, $ ;color settings
            POSITION = pos, $   ;position settings
            XTITLE = xlab, YTITLE = ylab, $ ;axis labels
            TITLE = t, $        ;title
            THICK = pt, XSTYLE = xs, YSTYLE = ys, $ ;plot style settings
            XRANGE = xr, YRANGE = yr    ;axis ranges

      ;if two arrays, then plot as xy
      ENDIF ELSE BEGIN
          ;determine extrema of y array
          ymax = MAX( y, MIN = ymin )

          ;set plotting boundaries
          IF ~KEYWORD_SET( xr ) THEN BEGIN
              xr = [ xmin, xmax ]
          ENDIF

          ;recall that in this case the x input is plotted as the y values
          IF ~KEYWORD_SET( yr ) THEN BEGIN
              yr = [ ymin, ymax ]
          ENDIF

          PLOT, x, y, $
            CHARSIZE = cs, CHARTHICK = ct, $ ;character settings
            BACKGROUND = bc, COLOR = pc, $ ;color settings
            POSITION = pos, $   ;position settings
            XTITLE = xlab, YTITLE = ylab, $ ;axis labels
            TITLE = t, $        ;title
            THICK = pt, XSTYLE = xs, YSTYLE = ys, $ ;plot style settings
            XRANGE = xr, YRANGE = yr ;axis ranges        
      ENDELSE

      ;if set, create a png image of the plotting window
      IF KEYWORD_SET( sf ) THEN BEGIN
          WRITE_PNG, sf + '.png', TVRD( /TRUE )
      ENDIF

  ENDELSE

END