;+
; NAME:
;	SHOWFLIC
;	
; PURPOSE:
;       Display of Polar Camera images, mapped to PACE geomagnetic
;	coordinates, as a movie.
;	
; CATEGORY:
;	
; CALLING SEQUENCE:
;	SHOWFLIC, NAME [, COLOUR_TABLE] [, /WAIT] [, /AUTOSCALE] [, /NOPRINT]
;	
; INPUTS:
;       NAME:   The filename of a {.geo|.pgm} file that contains
;               multiple Polar Camera images transformed to geographic
;		or PGM coordinates.
;       COLOUR_TABLE:   If specified, gives the number of the colour
;                       table to be used in displaying the images.
;                       If not specified, the default B/W colour
;			table is used.
;	
; KEYWORD PARAMETERS:
;       /WAIT:   If present and non-zero, the procedure displays
;               an image and waits for a keypress before displaying
;               another image.  The possible results of pressing
;               a key are displayed if the user presses the '?'
;               key.  If not present or equal to 0, the images are
;               displayed in sequence as fast as they can be read
;		from the file and written to the screen.
;       /AUTOSCALE: If present and non-zero, each image is scanned
;               for the byte value at the 99th percentile of the
;               non-zero byte values, and this value is taken as
;               the upper limit in displaying the image.  This
;               brings out features of images that otherwise would
;		be too dark to be useful.
;	/NOPRINT: IF set, defeats the automatic printing of the
;		PostScript image file.
;
; OUTPUTS:
;	None.
;	
; COMMON BLOCKS:
;	None.
;	
; SIDE EFFECTS:
;       A set of images from the specified file are displayed in
;	sequence according to the user's keypresses.
;
; RESTRICTIONS:
;       The .pgm file must exist.  If images are selected for hard
;       copy, the PostScript file produced must not be deleted nor
;	moved until the file has printed out.
;
; PROCEDURE:
;       The file is opened as an associated file and the images
;       are read out and displayed sequentially.  After displaying
;       an image the procedure checks whether a key has been pressed
;       (wait=0) or waits for a keypress (wait=1), and then performs
;       the action specified by the keypress, if any.  When the
;       end of the file is reached, image display resumes at the
;       beginning of the file.  If images are selected for hard
;       copy, the selected images are written, 12 to a page, to a
;       PostScript file with a name supplied by the user.  When
;       all images have been written to the file, it is closed and
;       queued for printing on either the B/W PostScript printer
;	or the long-page colour printer.
;
; MODIFICATION HISTORY:
;	Written 94/05 by D P Steele.
;       Modified and documented 94/06 by D P Steele. '?' key
;	added as useful keypress.  Added AUTOSCALE keyword.
;	Modified 941109 by D P Steele: halved pixel size for hardcopy 
;	to fit 12 images on a page.
;	
;-
PRO showflic,name,colour_table,wait=wait,autoscale=autoscale,noprint=noprint

IF N_PARAMS() EQ 0 THEN BEGIN
    doc_library,'showflic'
    RETURN
    ENDIF

; Account for differences between Unix and DOS platforms.

@isitdos
IF dos THEN SET_PLOT,'WIN' ELSE SET_PLOT,'X'

; Set up the associated file and the plot window.

edge=383L
OPENR,unit,pgmroot+dd+name,/GET_LUN
f=FSTAT(unit)
n=FIX(f.SIZE/(edge^2))
IF N_PARAMS() EQ 2 THEN loadct,colour_table,/silent
im=ASSOC(unit,BYTARR(edge,edge))
WINDOW,0,XSIZE=edge,YSIZE=edge

; Loop through the images.

IF KEYWORD_SET(wait) THEN PRINT,'Type ? for help'
i=-1
ps_plot=[-1]
REPEAT BEGIN
    i=FIX((i+1) MOD n)

; Display the next image, either raw or scaled to the 99th percentile.

    IF KEYWORD_SET(autoscale) THEN BEGIN
	img=im(i)
	p99=pcentile(img(WHERE(img)),0.99)
	TVSCL,img<p99
	ENDIF ELSE TVSCL,im(i)

; Get and interpret the next keypress.

    k=STRUPCASE(GET_KBRD(KEYWORD_SET(wait)))
    CASE k OF 
   '?': BEGIN
	    PRINT,FORMAT='()'
	    PRINT,'-|b|p: go back 1 image'
	    PRINT,'i    : show the current image number'
	    PRINT,'n    : show the total number of images'
	    PRINT,'f    : enter free-running mode (equivalent to WAIT=0)'
	    PRINT,'s    : enter single-step mode (equivalent to /WAIT)'
	    PRINT,'v    : skip forward 5 images'
	    PRINT,'w    : skip backward 5 images'
	    PRINT,'x    : skip forward 10 images'
	    PRINT,'y    : skip backward 10 images'
	    PRINT,'g    : go to a specified image'
	    PRINT,'h    : get hard copy of this image'
	    PRINT,'q    : quit the procedure'
	    PRINT,'?    : print this information'
	    i=FIX(i-1)
	    END
   '-': i=FIX((i-2)>(-1))
   'B': i=FIX((i-2)>(-1))
   'P': i=FIX((i-2)>(-1))
   'I': BEGIN
	    PRINT,STRTRIM(i,2)
	    i=FIX(i-1)
	    END
   'N': BEGIN
	    PRINT,STRTRIM(n,2)
	    i=FIX(i-1)
	    END
   'F': BEGIN
	    wait=0B
	    i=FIX(i-1)
	    END
   'S': BEGIN
	    wait=1B
	    i=FIX(i-1)
	    END
   'V': i=FIX(i+4)
   'W': i=FIX((i-6)>(-1))
   'X': i=FIX(i+9)
   'Y': i=FIX((i-11)>(-1))
   'G': BEGIN
	    READ,'Enter image number to skip to: ',g
	    i=FIX(((g-1)>(-1))<(n-2))
	    END
   'H': BEGIN	; tag this image for later PostScript plotting
	    ps_plot=[ps_plot,i]
	    i=FIX(i-1)
	    END
   'Q': GOTO,DONE
  ELSE:
	ENDCASE
    ENDREP UNTIL 0 EQ 1

; Image display done; were images tagged for hardcopy output?

DONE:
IF N_ELEMENTS(ps_plot) GT 1 THEN BEGIN
    PRINT,'Outputting the following images to a PostScript file:'
    PRINT,STRTRIM(ps_plot(1:*),2)
    psname=''
    READ,'Enter a name for the PostScript file (no suffix): ',psname
    bwc=''
    REPEAT BEGIN
	READ,'Do you want a black-and-white or colour plot? [B/C] ',bwc
	bwc=STRUPCASE(bwc)
	ENDREP UNTIL (bwc EQ 'B') OR (bwc EQ 'C')

; Open PostScript file for the type of output requested by the user.

    CASE bwc OF
   'B': BEGIN
	    psname=psname+'.ps'
	    psopen,psname,/long;,/land
	    END
   'C': BEGIN
	    psname=psname+'.cps'
	    psopen,psname,/long,/color;,/land
	    END
	ENDCASE
    IF N_PARAMS() EQ 2 THEN loadct,colour_table,/silent
    jmax=N_ELEMENTS(ps_plot)-1

; Plot each 383x383 image in a 400x400 space to provide white borders.

    img=BYTARR(400,400)+!D.N_COLORS-1
    FOR j=1,jmax DO BEGIN
	img(0,0)=BYTSCL(im(ps_plot(j)))
	jp=(j-1) MOD 6
	mtv,img,jp,res=135.
	IF (j LT jmax) AND ((j MOD 6) EQ 0) THEN ERASE
	ENDFOR
    psclose,/normps3

; If this is Unix, go ahead and print the file.

    IF NOT dos THEN BEGIN
	p=rstrpos(psname,dd)
	ps_root=STRMID(psname,0,p)
	nameonly=STRMID(psname,p+1,STRLEN(psname)-p-1)
	CD,ps_root,CURRENT=nowdir
	SPAWN,'/jasper/cnsr3_data1/scripts/rmps3 '+nameonly+' n'
	IF NOT KEYWORD_SET(noprint) $
	    THEN CASE bwc OF
               'B': SPAWN,'lpr -l -s -Pps '+nameonly
               'C': SPAWN,'lpr -l -s -Pqms '+nameonly
	            ENDCASE
	CD,nowdir
	ENDIF
    ENDIF
FREE_LUN,unit
RETURN
END