pro frestore, file, interpolate = interpolate, help = help

;+
;  PURPOSE:
;    Restore a set of FSET frames from a portable XDR file created by FSAVE.
; 
;  USAGE:
;    FRESTORE,FILE
; 
;  ARGUMENTS:
;    FILE            Name of file containing frame information (created by FSAVE)
; 
;  OPTIONAL KEYWORDS:
;    /INTERPOLATE    If set, interpolate color tables (default=no interpolation)
;    /HELP           Print help information only (default=do not print)
; 
;  USAGE NOTES:
;    (1) The file created by FSAVE is in XDR format, and thus is *portable*
;        between different IDL platforms. Each platform must however run
;        the same version of IDL (e.g. FSAVE files created in IDL 5.0
;        cannot be read in IDL 4.0.1).
;    (2) The following items are stored for each frame:
;          - The contents of the graphics window,
;          - The plot-related system variables (!P,!X,!Y,!Z,!MAP),
;          - The color table.
;        This means that the frames can be restored later (in another IDL
;        session, or even on another platform), and all overplotting commands
;        (e.g. OPLOT, PLOTS) will work normally. Map overplotting commands may
;        also be used on restored frames (e.g. MAP_GRID), as long as
;        .COMPILE MAP_SET
;        is done before the map overplotting commands are executed.
; 
;  AUTHOR: Liam Gumley, CIMSS/SSEC, 19-SEP-1997 (liam.gumley@ssec.wisc.edu)
;          Added color table interpolation keyword INTERPOLATE
; 
;  RELATED COMMANDS:
;    FSET    Set up frames in memory
;    FSAVE   Save frames created with FSET
; 
;  EXAMPLE:
; 
;  Create four frames with a graphic in each, save the frames to a file, 
;  exit IDL, and then restore the frames and start looping.
; 
; FSET
; LOADCT,13 & TV,BYTSCL(DIST(256),TOP=!D.TABLE_SIZE-1) & AF
; PLOT,INDGEN(10) & AF
; CONTOUR,DIST(32) & AF
; LOADCT,30 & MAP_SET,/CONTINENTS
; FSAVE,FILE='test.xdr'
; EXIT
; ;(restart IDL)
; FRESTORE,'test.xdr'
; LF
;-

;- return to caller if an error occurs

on_error, 2

;- print help message

if keyword_set( help ) then begin
  print, " PURPOSE:
  print, "   Restore a set of FSET frames from a portable XDR file created by FSAVE.
  print, "
  print, " USAGE:
  print, "   FRESTORE,FILE
  print, "
  print, " ARGUMENTS:
  print, "   FILE            Name of file containing frame information (created by FSAVE)
  print, "
  print, " OPTIONAL KEYWORDS:
  print, "   /INTERPOLATE    If set, interpolate color tables (default=no interpolation)
  print, "   /HELP           Print help information only (default=do not print)
  print, "
  print, " USAGE NOTES:
  print, "   (1) The file created by FSAVE is in XDR format, and thus is *portable*
  print, "       between different IDL platforms. Each platform must however run
  print, "       the same version of IDL (e.g. FSAVE files created in IDL 5.0
  print, "       cannot be read in IDL 4.0.1).
  print, "   (2) The following items are stored for each frame:
  print, "         - The contents of the graphics window,
  print, "         - The plot-related system variables (!P,!X,!Y,!Z,!MAP),
  print, "         - The color table.
  print, "       This means that the frames can be restored later (in another IDL
  print, "       session, or even on another platform), and all overplotting commands
  print, "       (e.g. OPLOT, PLOTS) will work normally. Map overplotting commands may
  print, "       also be used on restored frames (e.g. MAP_GRID), as long as
  print, "       .COMPILE MAP_SET
  print, "       is done before the map overplotting commands are executed.
  print, "
  print, " AUTHOR: Liam Gumley, CIMSS/SSEC, 19-SEP-1997 (liam.gumley@ssec.wisc.edu)
  print, "         29-SEP-1997 Added color table interpolation keyword INTERPOLATE
  print, "
  print, " RELATED COMMANDS:
  print, "   FSET    Set up frames in memory
  print, "   FSAVE   Save frames created with FSET
  print, "
  print, " EXAMPLE:
  print, "
  print, " Create four frames with a graphic in each, save the frames to a file, 
  print, " exit IDL, and then restore the frames and start looping.
  print, "
  print, "FSET
  print, "LOADCT,13 & TV,BYTSCL(DIST(256),TOP=!D.TABLE_SIZE-1) & AF
  print, "PLOT,INDGEN(10) & AF
  print, "CONTOUR,DIST(32) & AF
  print, "LOADCT,30 & MAP_SET,/CONTINENTS
  print, "FSAVE,FILE='test.xdr'
  print, "EXIT
  print, ";(restart IDL)
  print, "FRESTORE,'test.xdr'
  print, "LF
  goto, finish
endif

;- check arguments

if n_elements( file ) eq 0 then message, 'FILE argument was missing'
if not keyword_set( interpolate ) then interpolate = 0

;- common block to hold handle id

common frame_info, handle_id

;- restore state information from saved file and store using handle
;- (variables restored are STATE and IMAGE)

restore, file = file

;- create frames

if state.x_scroll_size gt 0 or state.y_scroll_size gt 0 then begin
  fset, frames = state.frames, xsize = state.xsize, ysize = state.ysize, $
    x_scroll_size = state.x_scroll_size, y_scroll_size = state.y_scroll_size
endif else begin
  fset, frames = state.frames, xsize = state.xsize, ysize = state.ysize
endelse

;- restore contents of each frame

sz = size( state.red )
nx = sz( 1 )
ncolors = nx < !d.table_size
for i = 0, state.frames - 1 do begin
  !x = state.xstate( i )
  !y = state.ystate( i )
  !z = state.zstate( i )
  !p = state.pstate( i )
  !map = state.mstate( i )
  if not interpolate then begin
    tvlct, state.red( 0 : ncolors - 1, i ), $
      state.green( 0 : ncolors - 1, i ), $
      state.blue( 0 : ncolors - 1, i )
  endif else begin
    tvlct, congrid( state.red( *, i ), !d.table_size ), $
      congrid( state.green( *, i ), !d.table_size ), $
      congrid( state.blue( *, i ), !d.table_size )
  endelse  
  tv, image( *, *, i )
  af, /quiet
endfor

;- let user know what happened

print, strcompress( 'Restored ' + string( state.frames ) + $
  ' frames from ' + file )

finish:

end