;+
; NAME:
;	TVSI
; PURPOSE:
;       Image display with optional subregion viewing / zooming.
;	The name abbreviates 'TV a subimage'.
; CATEGORY:
;
; CALLING SEQUENCE:
;	TVSI, IMAGE [, LLX, LLY, URX, URY $ ]
;	            [, /NOCLEAR, WINDOW = window $
;	             , CONTOUR = contour, CTABLE = ctable $
;	             , CURSOR = cursor ]
; INPUTS:
;       IMAGE:  A two-dimensional array containing the image to be
;               displayed.  If no other inputs are supplied the
;               entire image will be displayed.
; OPTIONAL INPUTS:
;       LLX:    The column number in the original image of the
;		leftmost column to be displayed.
;       LLY:    The row number in the original image of the bottom
;		row to be displayed.
;	URX:	The column number in the original image of the
;               rightmost column to be displayed.
;       URY:    The row number in the original image of the top
;		row to be displayed.
; KEYWORD PARAMETERS:
;       /NOCLEAR: If set, defeats ERASEing the window before
;		displaying the image, axes, and colour bar.
;	WINDOW:	Determines the display window to use (default = 0).
;       CONTOUR: Contains an array of data values at which contours
;		should be overplotted on the displayed image.
;       CTABLE: Determines the colour table to use (default = 13).
;               If CTABLE = -1, the colour table is not modified,
;		so the existing colour table is used.
; OUTPUTS:
;	None.
; OPTIONAL OUTPUTS:
;       CURSOR: If set, this keyword contains, on return, the column
;               and row of a pixel in the image selected by the
;               user with the mouse.  To actuate pixel selection,
;               the keyword must be a defined variable when TVSI
;		is called.
; COMMON BLOCKS:
;	None.
; SIDE EFFECTS:
;       A display window is (usually) created or erased to hold
;       the display of the IMAGE.  The !ORDER system variable is
;       set to 0.  The colour table is (usually) modified.  The
;       image is displayed as a square, irrespective of the original
;	aspect ratio.
; RESTRICTIONS:
;	IMAGE must be a 2-d variable.
; PROCEDURE:
;       The selected region of the image is expanded to 450x450
;       pixels using CONGRID.  A data coordinate system is created
;       using PLOT,/NODATA.  The image is then TVSCL'ed into that
;	data coordinate system.
; EXAMPLE:
;	d=SHIFT(dist(100),50,50)	; create a 100x100 array
;	TVSI,d				; displays the whole array
;	TVSI,d,0,0,49,49,window=2 $	; display the lower left
;	    ,ctable=3			; quadrant in window 2 with
;					; red temperature colours
;
;	cr=1				; define the variable to hold
;					; the cursor position on return
;	TVSI,d,cursor=cr		; display the image and pick a
;					; pixel with the mouse
;	PRINT,cr			; show the pixel coordinates
;
; SEE ALSO:
;
; MODIFICATION HISTORY:
; 	Written by:	D P Steele, 1992?
;	Documented by:	D P Steele, Aug 1994.
;-
PRO tvsi,img,x0,y0,x1,y1,NOCLEAR=noclear,WINDOW=window $
	,CONTOUR=cont,CTABLE=ctable,CURSOR=cursor

IF N_PARAMS() LT 1 THEN BEGIN
    doc_library,'tvsi'
    RETURN
    ENDIF

imgsize=SIZE(img)
IF imgsize(0) LT 2 THEN BEGIN
    MESSAGE,'Image argument must be a 2-d array!',/INFORMATIONAL
    RETURN
    ENDIF

!ORDER=0

IF N_ELEMENTS(ctable) EQ 0 THEN ctable=13
IF ctable NE -1 THEN loadct,ctable,/silent

IF N_PARAMS() LT 5 THEN BEGIN	; display the whole image
    x0=0
    y0=0
    x1=imgsize(1)-1
    y1=imgsize(2)-1
    ENDIF

si=CONGRID(img(x0:x1,y0:y1),450,450)

newin=0

IF N_ELEMENTS(window) GT 0 THEN win=window ELSE win=0

newin=(!D.WINDOW NE win) OR $
      ((!D.WINDOW EQ win) AND ((!D.X_SIZE LT 640) OR (!D.Y_SIZE LT 512)))

IF newin THEN WINDOW,win ELSE $
    IF NOT KEYWORD_SET(noclear) THEN ERASE

; create the colour bar
bar=REBIN(BINDGEN(1,225),32,450,/SAMPLE)

; determine the limits of the image values
mi=MIN(img(x0:x1,y0:y1),MAX=ma)

; ensure the pixel value axis is at least 1 unit long
IF ABS(ma-mi) LT 1 THEN ma=mi+1

; show the pixel value axis next to the colour bar location
PLOT,[0,1],[mi,ma],/DEVICE,/NODATA,POSITION=[600,40,631,489] $
    ,XSTYLE=4,YRANGE=[mi,ma],YSTYLE=9,/NOERASE

TVSCL,bar,600,40,/DEVICE
TVSCL,si,80,40,/DEVICE

; determine the column and row number axis values for the (sub)image
xax=INDGEN(x1-x0+1)+x0
yax=INDGEN(y1-y0+1)+y0

; overplot an axis box showing column and row numbers
PLOT,xax,yax,/DEVICE,/NODATA,/NOERASE,POSITION=[80,40,529,489] $
    ,XRANGE=[x0,x1+1],XSTYLE=1,XTITLE='Original Column Number' $
    ,YRANGE=[y0,y1+1],YSTYLE=1,YTITLE='Original Row Number'

; overplot contours if requested
IF KEYWORD_SET(cont) THEN $
    CONTOUR,img,/OVERPLOT,POSITION=[80,40,529,489],/DEVICE $
	   ,XRANGE=[x0,x1],YRANGE=[y0,y1],LEVELS=cont;$,/FOLLOW

; let the user select a position with the cursor if requested
IF N_ELEMENTS(cursor) GT 0 THEN BEGIN
    cursor=INTARR(2)
    REPEAT BEGIN
        PRINT,'Click on an image pixel with the mouse:'
        CURSOR,col,row,/DATA,/DOWN
	interior=((col GE x0) AND (col LE x1) AND $
		  (row GE y0) AND (row LE y1))
	IF NOT interior THEN PRINT,'Not!'
        ENDREP UNTIL interior
    cursor(*)=[col,row]
    ENDIF

RETURN
END