PRO FITSRGB_to_TIFF, path, rgb_files, tiff_name, BY_PIXEL=by_pixel, $
                      PREVIEW=preview, RED=r_mix, GREEN=g_mix, BLUE=b_mix
;+
; NAME:
;       FITSRGB_to_TIFF
; PURPOSE:
;       Read three separate image files (red, green, blue image components)
;       stored as FITS files and write out as a TIFF (class R) file which
;       has colours interleaved by either pixel or image.  The colour mix
;       is also adjustable.
;
; CALLING SEQUENCE:
;       FITSRGB_to_TIFF, path, rgb_files, tiff_name [,/BY_PIXEL, /PREVIEW,
;                         R=red_mix, G=green_mix, B=blue_mix]
;
; INPUTS:
;       path = file system directory path to the RGB files required.
;       rgb_files = string array with three components - the red FITS file
;                   filename, the blue FITS file filename and the green FITS
;                   file filename
;
; OUTPUTS:
;       tiff_name = string containing name of tiff file to be produced
;
; OPTIONAL OUTPUT:
;       Header = String array containing the header from the FITS file.
;
; OPTIONAL INPUT KEYWORDS:
;       BY_PIXEL = This causes TIFF file RGB to be interleaved by pixel
;                  rather than the default of by image.
;       PREVIEW  = Allows a 24 bit image to be displayed on the screen
;                  to check the colour mix.
;       RED = Real number containing the fractional mix of red
;       GREEN = Real number containing the fractional mix of green
;       BLUE = Real number containing the fractional mix of blue
;
; EXAMPLE:
;       Read three FITS files, 'red.fits', 'blue.fits' and 'green.fits' from
;       the directory '/data/images/space' and output a TIFF file named
;       'colour.tiff'
;
;               IDL> FITSRGB_to_TIFF, '/data/images/space', ['red.fits', $
;                    'blue.fits', 'green.fits'], 'colour.tiff'
;
;       Read three FITS files, 'red.fits', 'blue.fits' and 'green.fits' from
;       the current directory and output a TIFF file named '/images/out.tiff'
;       In this case, the red image is twice as strong as the green and the
;       blue is a third more intense.  A preview on screen is also wanted.
;
;               IDL> FITSRGB_to_TIFF, '.', ['red.fits', $
;                    'blue.fits', 'green.fits'], '/images/out.tiff', $
;                    /PREVIEW, RED=0.5, GREEN=1.0, BLUE=0.666
;
;
; RESTRICTIONS:
;       (1) Limited to the ability of the routine READFITS
;
; NOTES:
;       None
;
; PROCEDURES USED:
;       Functions:   SXPAR, WHERENAN, READFITS, STRNUMBER, CONCAT_DIR
;       Procedures:  IEEE_TO_HOST, SXADDPAR, TIFF_WRITE
;
; MODIFICATION HISTORY:
;       16th January 1995 - Written by Carl Shaw, Queen's University Belfast
;	27 Jan 1995 - W. Landsman, Add CONCAT_DIR for VMS, Windows compatibility
;-
;
;  Make sure user has supplied valid parameters
;
 IF N_PARAMS() LT 3 THEN $
  MESSAGE, 'Calling sequence : FITSRGB_to_TIFF, path, rgb_files, tiff_name'
;
 IF N_ELEMENTS(rgb_files) LT 3 THEN $
  MESSAGE, 'Three filenames for the colour components have not been supplied'
;
 IF KEYWORD_SET(BY_PIXEL) THEN $
  by_pixel = 1 $
 ELSE $
  by_pixel = 0
;
 IF NOT KEYWORD_SET(r_mix) THEN r_mix = 1.0
 IF NOT KEYWORD_SET(g_mix) THEN g_mix = 1.0
 IF NOT KEYWORD_SET(b_mix) THEN b_mix = 1.0
;
;  Now load the colour components
;
 fname = CONCAT_DIR( path, rgb_files )
 red = READFITS( fname(0), /SILENT)
 green = READFITS( fname(1), /SILENT)
 blue = READFITS( fname(2), /SILENT)
;
;  Data now needs to be scaled to the same byte range (0-255) and also
;  scaled according to the RGB mix values supplied by the user
;
 red = red(*,*) * r_mix
 green = green(*,*) * g_mix
 blue = blue(*,*) * b_mix          ;scale intensity by supplied mix
;
 maxlim = MAX(red) > MAX(green) > MAX(blue)   ;max intensity
 minlim = MIN(red) < MIN(green) < MIN(blue)   ;min intensity
 red = BYTSCL(red, MIN=minlim, MAX=maxlim)
 green = BYTSCL(green, MIN=minlim, MAX=maxlim)
 blue = BYTSCL(blue, MIN=minlim, MAX=maxlim)  ;scale colours to same byte range
;
;  Preview image on window system if required
;
 IF keyword_set(PREVIEW) THEN BEGIN
  window, 0, colors=256
  wset, 0
  tv, color_quan(red, green, blue, r, g, b, colors=255)
  tvlct, r, g, b
 ENDIF
;
; Now write out result as a tiff file
;
 IF by_pixel THEN BEGIN
  ;
  ;  Interleave by pixel
  ;
  extent = SIZE(red)
  xsize = extent(1)
  ysize = extent(2)                       ;get image size
  interarr = FLTARR(3, xsize, ysize, /NOZERO)      ;make interleaved array
  interarr(0, *, *) = red
  interarr(1, *, *) = green
  interarr(2, *, *) = blue
  ;
  TIFF_WRITE, tiff_name, interarr
  ;
 ENDIF ELSE BEGIN
  ;
  ;  Interleave by image
  ;
  TIFF_WRITE, tiff_name, RED=red, BLUE=blue, GREEN=green, PLANARCONFIG=2
  ;
 ENDELSE
;
 END