;+
; NAME:
;        SHOWFLIC
;        
; PURPOSE:
;       Display of Polar Camera images, mapped to PACE geomagnetic
;        coordinates, as a movie.
;        
; CATEGORY:
;        
; CALLING SEQUENCE:
;        SHOWFLIC, NAME [, COLOUR_TABLE] $
;              [, /BIG] [, /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:
;        /BIG:        If set, enlarges the images a factor of 2 before
;                displaying them, for improved visibility.  If 
;                selected for PostScript plotting, images are still
;                plotted as 383x383 pixels.
;       /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.
;        Modified 960301 by D P Steele: added /BIG keyword to increase 
;        displayed image size.
;        
;-
PRO showflic,name,colour_table $
            ,big=big,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 to display enlarged images, if needed.

IF KEYWORD_SET(big) THEN factor=2 ELSE factor=1

; 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=factor*edge,YSIZE=factor*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)
    img=im(i)

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

    IF KEYWORD_SET(autoscale) THEN BEGIN
        p99=pcentile(img(WHERE(img)),0.99)
        img=img<p99
        ENDIF
        
    IF KEYWORD_SET(big) $
        THEN img=REBIN(img,factor*edge,factor*edge,/SAMPLE)
        
    TVSCL,img

; 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
    psname=psroot+dd+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