; $Id: flick.pro,v 1.1 1993/04/02 19:43:31 idl Exp $

pro cmp_flic,im1,im2,rate,cs21,rs21,ctable,overlap=overlap,done=done
			;Flicker between the two output frames at a given rate.
			; a and b = images scaled from 0 to 255.
			;To terminate, type Q.
			;Rate = frames per second.
			; Type F to flick faster by a factor of 1.5
			;  S to flick slower by a factor of 1.5.
;+
; NAME:
;	CMP_FLIC
;
; PURPOSE:
;       Flicker between two output images at a given rate, and
;       allow user to vary column and row offsets to optimize
;	agreement between spatial structures in the two images.
;
; CATEGORY:
;	Image display, animation.
;
; CALLING SEQUENCE:
;	CMP_FLIC, A, B, Rate, Colshift, Rowshift [, CTable]
;
; INPUTS:
;	A:	Byte image number 1, scaled from 0 to 255.
;	B:	Byte image number 2, scaled from 0 to 255.
;	Rate:	The flicker rate (Hz).  The default is 1.0 frame/sec.
;
; OPTIONAL INPUT PARAMETERS:
;	CTABLE:	Gives the colour table to use (default = 0, B/W).
;
; KEYWORD PARAMETERS:
;       OVERLAP: If present and nonzero, causes display of only
;               those pixels that are non-zero in both A and (shifted
;		B).
;
; OUTPUTS:
;       Colshift: The number of columns by which B must be shifted
;                 (to the right) to 'match' A (whatever 'match'
;		  means in this context).
;       Rowshift: The number of rows by which B must be shifted
;                 (upward) to 'match' A.
;       DONE:   An output keyword parameter that has the value 1B
;               on return to the calling routine if the user pressed
;		Q to end comparison.
;
; COMMON BLOCKS:
;	None.
;
; SIDE EFFECTS:
;	X and Windows: uses two additional pixmaps.
;
; RESTRICTIONS:
;	None.
;
; PROCEDURE:
;       Two off-screen pixmaps are used to contain the images,
;       which are copied alternately to the screen using the
;       DEVICE,COPY command.  The user can control the rate of
;       image display by pressing F for faster or S for slower.
;       The second image is shifted with respect to the first as
;	follows:
;
;				K
;				|
;			     H--+--L
;				|
;				J
;
;       (analogously to cursor motion in the 'vi' editor).  Repeated
;       keypresses are not implemented until a null keypress has
;       been received, and then the net shift indicated by the
;       keypresses is made all at once, to avoid spending too much
;       time writing to pixmaps.  Pressing any other character
;       exits the image shifting loop (using a GOTO), and returns
;       the final values of the column and row shifts to the calling
;       routine.  In particular, pressing Q does the above but also
;       sets the DONE keyword, which can be used to tell the calling
;       routine to exit (this is done in MONTAGE.PRO).
;
; MODIFICATION HISTORY:
;	DMS, 3/ 88.
;	DMS, 4/92, Added X window and MS window optimizations.
;       DPSteele, 06/94.  Incorporated in CMP_FLIC.PRO and added
;       extra hotkeys.  Added OVERLAP keyword.  Added DONE keyword
;	and functionality.
;-
ON_ERROR,2                        ;Return to caller if an error occurs

IF N_ELEMENTS(rate) EQ 0 THEN rate = 1.0 ;Parameter there?
ichl = 0
sfact = 1.5		;Speed steps
IF N_PARAMS() EQ 6 THEN loadct,ctable,/silent

; Find the maximum window size needed.

s1=SIZE(im1)
s2=SIZE(im2)
cols=MAX([s1(1),s2(1)])
rows=MAX([s1(2),s2(2)])

; Open a window just big enough for the images

WINDOW,!D.WINDOW+1,XSIZE=cols,YSIZE=rows
cwin = !D.WINDOW

; Scale the two images for display

b1=BYTSCL(im1,TOP=!D.N_COLORS-1)
b2=BYTSCL(im2,TOP=!D.N_COLORS-1)
b1orig=b1
b2orig=b2

; Create the pixmaps and store the images in them.

pix = INTARR(2)		;Make 2 pixmaps
FOR i=0,1 DO BEGIN
    WINDOW, /FREE, /PIX, XSIZE = !D.X_SIZE, YSIZE = !D.Y_SIZE
    pix(i) = !D.WINDOW
    IF i EQ 0 THEN TV,b1 ELSE TV,b2
    ENDFOR

WSET, cwin
cs21=0
rs21=0
chr=""
WHILE 1 DO BEGIN	;loop infinitely over each chl
    DEVICE, COPY=[0,0,!D.X_SIZE, !D.Y_SIZE, 0, 0, pix(ichl)]
    WAIT,1./rate	;This also empties the graphics buffer
    lastchr=chr
    chr = STRUPCASE(GET_KBRD(0)) ;Read character
    CASE chr OF
"F":	rate = rate*sfact	; Faster
"S": 	rate = rate/sfact	; Slower
"H":	cs21=cs21-1		; Shift b2 left a column
"L":	cs21=cs21+1		; Shift b2 right a column
"J":	rs21=rs21-1		; Shift b2 down a row
"K":	rs21=rs21+1		; Shift b2 up a row
"":	BEGIN			; Display other image
	    ichl = 1 - ichl
	    chr="Z"
	    END
"Q":    BEGIN
	    done=1B
	    GOTO,done1
	    END
ELSE:	GOTO,done1
        ENDCASE

; Implement shift of image 2 as requested.

    IF (chr EQ "Z") AND (STRPOS(" HLJK",lastchr) GT 0) THEN BEGIN
	b2=SHIFT(b2orig,cs21,rs21)

; If only pixels common to A and (shifted B) are to be displayed,
; modify images to be displayed in pixmaps, and update first pixmap.

	IF KEYWORD_SET(overlap) THEN BEGIN
	    nonzero=WHERE((b1orig GT 0) AND (b2 GT 0))
	    mk,mask,cols,rows
	    mask(nonzero)=1
	    b2=b2*mask
	    b1=b1orig*mask
	    WSET,pix(0)
	    TV,b1
	    ENDIF

; Now update 2nd pixmap.

	WSET,pix(1)
	TV,b2
	WSET,cwin
	ENDIF

    ENDWHILE
;
done1:	WDELETE, pix(0), pix(1), cwin
	PRINT,rs21,cs21,FORMAT='(2I5)'
	RETURN
END