;+
; 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 ELSE BEGIN            ; check requested image bounds
    x0=x0>0
    y0=y0>0
    x1=x1<(imgsize(1)-1)
    y1=y1<(imgsize(2)-1)
    ENDELSE

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,XSIZE=640,YSIZE=512 ELSE $
    IF NOT KEYWORD_SET(noclear) THEN ERASE

; Determine available space for image plot
avail_x = !D.X_SIZE-TOTAL(!X.MARGIN)*!D.X_CH_SIZE
avail_y = !D.Y_SIZE-TOTAL(!Y.MARGIN)*!D.Y_CH_SIZE
avail=2*((avail_x<avail_y)/2)

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

; create the colour bar
bar=REBIN(BINDGEN(1,avail/2),32,avail,/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
bar_lly=490-avail
PLOT,[0,1],[mi,ma],/DEVICE,/NODATA,POSITION=[600,bar_lly,631,489] $
    ,XSTYLE=4,YRANGE=[mi,ma],YSTYLE=9,/NOERASE

TVSCL,bar,600,bar_lly,/DEVICE
TVSCL,si,80,bar_lly,/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,bar_lly,80+avail-1,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,bar_lly,80+avail-1,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