PRO MTV, image, x, y, device=device, low=low, high=high, $
         Inches=inches, Order=order, $
         Res=res, Help=help, Temp=temp
;+
; NAME:
;
;   MTV
;
; PURPOSE:
;
;   TV and TVSCL wrapper that is independent of the screen and
;   postscript devices. Use just as you would TV or TVSCL.  It
;   automatically scales if the data is not byte data. Also allows the
;   specification of an absolute scale.
;   
; CATEGORY:
;
;   Image, Printer
;
; CALLING SEQUENCE:
;
;   MTV,Image,X,Y
;   MTV,Image,Position   
; 
; INPUTS:
;
;   Image - 2D array to be displayed. MTV only works with 2D arrays
;           (not with vectors).
;
;
; OPTIONAL INPUTS:
;
;   X,Y - Position of image lower left corner in image pixels, unless
;         the inches keyword is set, in which case they are in inches.
;         Defaults to (0,0).
;
;   Position - Same as for the TV routine. (The position of the image
;              on the screen as an integer. The screen is divided into
;              an integral number of segments of size equal to Image.)
;
; KEYWORD PARAMETERS:
;
;       Keywords equivalent to the TV keywords (see the description
;       for the TV routine):
;
;   DEVICE - all positions and sizes given in pixel coordinates. (default)
;   
;   INCHES - all positions and sizes given in inches.
;   
;   ORDER 
;   
;      New keywords:
;   
;   RES - The resolution for a device with scalable pixels (e.g.
;         postscript printer). Default = 75dpi (dots per inch).  When
;         the device does not have scalable pixels, the resolution is
;         fixed and this parameter is ignored.
;
;   LOW - The minimum value for the image scale. Values less than LOW
;         will be set to LOW. Defaults to Image minimum. The LOW value
;         is mapped to the 0 value of the color table.
;
;   HIGH - The maximum value for the image scale. Values greater than
;          HIGH will be set to HIGH. Defaults to Image maximum. The
;          HIGH value is mapped to the maximum index of the color
;          table, which is !D.N_COLORS - 1 (!D.N_COLORS is the number
;          of colors available).
;
;   HELP - Provide help (this information). No other action is performed.
;
;   TEMP - Modify the input image rather than working with a copy.
;          This option saves virtual memory.
;
; OUTPUTS:
;
;   None
;
; RESTRICTIONS:
;
;   Only works with 2D arrays.
;
;   Only tested with 8bit devices. Does not support TRUE color or
;   CHANNEL options of TV routine. Does NOT support DATA, T3D, WORD, 
;   NORMAL or Z keywords of TV routine.
;
;   It is recommended that you use the TV or TVSCL routines directly
;   if you want to scale an image to fit a display (e.g. plot or
;   contour). On the other hand this routine would be appropriate for
;   scaling a plot or contour display to overlay an image.
;
; PROCEDURE:
;
;   Scales the data according to the number of colors and the LOW,
;   HIGH keywords using the byscl procedure.
;
; EXAMPLE:
;
;   image=SIN(DIST(200,200)*(4*!Pi/200.))
;   MTV,image,50,50,RES=100,HIGH=2.,LOW=-2.
;   
;   ; If the device does not have scalable pixels (e.g. 'X') then the
;   ; RES keyword has no effect. If the current device has scalable
;   ; pixels (e.g. 'PS') then image pixels will map to 100 dots per
;   ; inch. If my screen resolution is 100dpi my images have the
;   ; same displayed size independent of the current device.
;   ; Typically, one would just use the default value for RES.
;
;
; MODIFICATION HISTORY:
;	
;	Wed Aug 17 11:52:12 MDT 1994, David Steele (steele@aragorn)
;               Image is only byte-scaled if it is not already a
;		byte array.
;
;       Mon Mar 22 13:36:05 1993, Chris Chase <chase@johnston>
;               Added low,high keywords. Scaled the data according to
;               the number of colors and the low, high keywords. No
;               longer uses tvscl. Instead uses bytscl and tv.
;
;               Added documentation header.   
;
;       Wed Mar  3 17:34:16 1993, Chris Chase <chase@johnston>
;               Initial Version. Added proper header.   
;
;-
IF KEYWORD_SET(help) THEN BEGIN
   doc_library, 'mtv'
   RETURN  
ENDIF

IF NOT KEYWORD_SET(low) THEN low = MIN(image)
IF NOT KEYWORD_SET(high) THEN high = MAX(image)

; Get rid of trivial leading dimensions (i.e. dimension size = 1)
; nimage = reform(image)

s = SIZE(image)
IF s(0) NE 2 THEN BEGIN
   PRINT, 'MTV ERROR: The image is not a 2D array'
   RETURN
ENDIF

; Don't scale the image if it's a byte array.
IF KEYWORD_SET(temp) THEN BEGIN	; added DPS 950605
    IF s(s(0)+1) NE 1 $
	THEN image = BYTSCL(TEMPORARY(image) $
			   , MIN = low, MAX = high, TOP = !D.n_colors-1)
    cmd_str = 'TV,IMAGE'
    ENDIF ELSE BEGIN
    IF s(s(0)+1) EQ 1 THEN bimage = image ELSE $	; added DPS 940817
    bimage = BYTSCL(image, MIN = low, MAX = high, TOP = !D.n_colors-1)

    cmd_str = 'TV,BIMAGE'
    ENDELSE
   
IF N_ELEMENTS(x) EQ 1 THEN BEGIN
   cmd_str = cmd_str + ',xd'
   xd = x
ENDIF ELSE xd = 0
IF N_ELEMENTS(y) EQ 1 THEN BEGIN
   cmd_str = cmd_str + ',yd'
   yd = y
ENDIF ELSE yd = 0

;
; Use a default pixel size of 75 dots per inch for scalable device pixels.
; Otherwise, for fixed size device pixels use the actual size
; 
IF NOT KEYWORD_SET(res) THEN res = 75.0 $
  ELSE res = FLOAT(res)

;; check for scalable pixels.
;; scl has units of device pixels per image pixel (dots).
IF (!D.flags AND 1) THEN BEGIN
   scl = 2.54*!D.X_PX_CM/res    ; 2.54 cm/inch
ENDIF ELSE BEGIN
   ;; Fixed size device pixels
   scl = 1.0
   res = 2.54*!D.X_PX_CM
ENDELSE

;; Convert to device pixel units when x,y offset given
IF (N_PARAMS() EQ 3) THEN BEGIN
   if KEYWORD_SET(inches) THEN BEGIN
      ;; convert from inches into image pixels
      xd = xd*res
      yd = yd*res
   ENDIF
   xd = xd*scl
   yd = yd*scl
ENDIF

IF KEYWORD_SET(order) THEN cmd_str = cmd_str + ',/ORDER'

;; Using the size keywords only affects the devices with scalable
;; device pixels
xsize = s(1)*scl
ysize = s(2)*scl
cmd_str = cmd_str + ',XSIZE=xsize,YSIZE=ysize'
ans = EXECUTE(cmd_str+',/DEVICE')
RETURN
END