PRO CROAM, image, xsize=xs, ysize=ys, quiet=quiet
;+
; NAME:
;	CROAM
; PURPOSE:
;	To allow a user to roam around an image using the mouse cursor.
;       Works on SparcStations but not on VaxStations (see restrictions).
; CALLING SEQUENCE:
;	croam, image, xsize=window-x-size, ysize=window-y-size, quiet=printflag
; INPUTS:
;	image  The array containing the image to examine.
;    KEYWORDS:
;	xsize  The x-axis size of the display window.  Defaults to 512.
;	ysize  The y-axis size of the display window.  Defaults to 512.
;	quiet  A flag indicating whether or not to print positional
;	       information.  If present and non-zero, the printing of
;	       positional information is suppressed.
; RESTRICTIONS:
;	This procedure can only be used on a workstation which allows pixmaps
;	larger than the screen size to be defined.     It will work on a 
;       SUN but not on a VAX.
;
;	There is an as yet undetermined upper limit to the size of the image.
;
;	Unlike the Deanza version of this routine, this procedure cannot
;	zoom in on an image.
; SIDE EFFECTS:
;	The current window (or window 0 if no window is current) is resized
;	and redisplayed.
; PROCEDURE:
;	The image is "displayed" in a pixmap (a window which is not displayed).
;	Then, as the cursor is moved around the window, portions of this
;	pixmap are copied into the displayed window.
;
;	The procedure terminates once a mouse button has been struck.
; MODIFICATION HISTORY:
;	Written for SUN workstations by Michael R. Greason, STX, 
;		11 January 1991.
;       Fixed free window allocation, outer bounds while roaming
;               W. Landsman April 1992
;-
;			Common block definitions.
;
COMMON TV, chan, zoom, xroam, yroam
;
;			Check parameters.
;
IF (n_params(0) LT 1) THEN BEGIN
	print, 'Incorrect number of arguments specified.'
	print, 'Syntax:  croam, image'
	return
ENDIF
siz = size(image)
IF (siz(0) NE 2) THEN BEGIN
	print, 'The image arguement must be two-dimensional.'
	return
ENDIF
IF (NOT keyword_set(xs)) THEN xs = 512
IF (NOT keyword_set(ys)) THEN ys = 512
xs = xs < siz(1)
ys = ys < siz(2)
prnt = NOT keyword_set(quiet)
;
;			Create and fill the pixmap.
;
pixind = 20
window, pixind, /pixmap, xsize=siz(1), ysize=siz(2)
tvscl, image, channel=pixind
;
;			Display the central part of the image in the
;			current window.
;
device,window_state = opnd
IF ((chan LT 0) OR (!D.WINDOW EQ -1)) THEN chan = 0
window, chan, retain=2, xsize=xs, ysize=ys
zoom(chan) = 1
xlim = siz(1) - (xs / 2) - 1
ylim = siz(2) - (ys / 2) - 1
xroam(chan) = (((siz(1) - xs) / 2) > 0) < xlim
yroam(chan) = (((siz(2) - ys) / 2) > 0) < ylim
xs1 = xs < ( siz(1) - xroam(chan))
ys1 = ys < ( siz(2) - yroam(chan))
dev = [xroam(chan), yroam(chan), xs, ys, 0, 0, pixind]
device, copy=dev
tvcrs, (xs / 2), (ys / 2), /device
;
;			Print instructions to the user.
;
print, 'CROAM -- Moving the mouse around will display different portions of'
print, '         the image.  Pressing any mouse button will terminate the'
print, '         program.  This version of CROAM is not capable of zooming.'
;
;			Set up a loop, continuing until a mouse
;			button is pressed.
;
wait = 0				; Cursor proc. to return immediately.
IF (prnt) THEN BEGIN
	cr = string(13B)
	print, ' '
	print, ' '
	fmt = "(A1,'Lower left corner array index = (',I5,',',I5,')',$)"
ENDIF
REPEAT BEGIN
;
;				Print last xroam and yroam.
;
	IF (prnt) THEN print, format=fmt, cr, xroam(chan), yroam(chan)
;
;				Get the cursor position and status.
;
	cursor, x, y, wait, /device
	bstat = !err
	tvcrs, (xs / 2), (ys / 2), /device
;
;				If a button was pressed, don't do anything.
;
	IF ((bstat EQ 0) AND ((x GE 0) AND (y GE 0))) THEN BEGIN
;
;				No button was pressed.  Use the just-read
;				cursor position to select the portion of
;				the image to display.
;
		xroam(chan) = ((xroam(chan) + (x - (xs / 2))) > 0) < xlim
		yroam(chan) = ((yroam(chan) + (y - (ys / 2))) > 0) < ylim
                xs1 = xs < (siz(1) - xroam(chan) )
                ys1 = ys < (siz(2) - yroam(chan) )
		dev = [xroam(chan), yroam(chan), xs1, ys1, 0, 0, pixind]
		device, copy=dev
	ENDIF
;
ENDREP UNTIL (bstat NE 0)
;
;			Finished.  Delete the pixmap.
;
IF (prnt) THEN print, format="(/)"
wdelete, pixind
xroam(chan) = 0
yroam(chan) = 0
;
RETURN
END