Synopsis:
--------
Panorama is a program to display a list of high resolution images as a movie.
Optional support for viewing in stereo, as well as allowing multiple data channels.
These channels can be tiled (viewed side by side) or "stacked" into a sandwich in
which every channel/layer has a certain level of transparency to allow layers below
to show through.



Homepage:
--------
http://lmsal.com/~seguin/panorama



Requirements:
------------
A unix box (Mac OS/X i386 or PPC, Linux, Solaris, IRIX) with decent OpenGL graphics hardware acceleration.
512M of RAM (more is better)



Usage:
-----
From the command prompt:
For command line help:
panorama -h

panorama [global options] [channel options] file1.fits [file2.fits ...]
panorama [global options] [-datamin value] [-datamax value] file1.fits [file2.fits ...]


For multiple channels:
panorama [chanoptions] <1st channel files> -channel [chanoptions] <2nd channel files> -channel [chanoptions] <3rd channel files> 

Examples:
(monoscopic, 1 channel, auto datamin/datamax, all fits files in the directory)
panorama *.fits


(monoscopic, 3 channels, varying datamin/max for each channel)
panorama -datamin 220 -datamax 4000 a1.fits a2.fits a3.fits -channel -datamax 1800 b1.fits b2.fits b3.fits -channel -datamin 350 -datamax 2500 c1.fits c2.fits c3.fits


(passive/side-by-side stereoscopic, 1 channel)
panorama -passivestereo -datamin 220 -datamax 2500 -left left*.fits -right right*.fits


(passive/side-by-side stereoscopic, 2 channels)
panorama -passivestereo -left l1*.fits -right r1*.fits -channel -left l2*.fits -right r2*.fits


(active/shutterglass stereoscopic, 1 channel)
panorama -activestereo -left left*.fits -right right*.fits



Global options include:
----------------------
    -width <npixels>              Initial window width in pixels
    -height <npixels>             Initial window height in pixels
    -playtime <nseconds>          Run for nseconds and then quit
    -cycleviews <nseconds>        Cycle between views every nseconds
    -cyclecolors <nseconds>       Cycle channel coloring/modulation every nseconds
    -nocursor                     Turn off any mouse cursor display
    -fullscreen                   Start up in fullscreen, instead of a window
    -activestereo                 Run in active-stereo mode where left eye and right
                                  eye are time-interleaved (shutterglasses)
    -dualstereo                   Run in dual-screen stereo mode where left eye and right
                                  are side-by-side for polarized glasses

Per-channel options include:
---------------------------
    -channel                      Declares a new data channel into which files will be
                                  placed (until the next -channel arg).
    -datamin <minval>             Minimum (black) data threshold value
    -datamax <maxval>             Minimum (black) data threshold value
    -reverse                      Reverses/inverts intensities/colors
    -left, -right                 Stereo modes only.
                                  Files following -left or -right are placed into the
                                  left and right eye accordingly.



Features currently available:
----------------------------
-runtime help overlay  ('h' or '?' keys toggle help overlay)
-pause/resume, step time (forward and backward)
-realtime, interactive panning, zooming, scaling and rotation of all channels
 as the movie plays
-realtime, interactive colorization/color-modulation of channels
-view all channels in either side-by-side, or stacked
-blending of channels while stacked/sandwiched
-show or hide channels while blending
-read standard FITS 2D files, and associated headers
-has support for JPEG, PNG, GIF, PPM, PNM, PGM file formats (NetPBM tools must be installed for  JPEG, PNG and GIF formats).  Also supports embedding of FITS header in PNG, PNM, PPM and PGM formats.
-realtime display of channel information for each frame (time, pointing, datamin, datamax, ...)  ('i' key)
-image snapshot of current display, as well as record all frames (to make a movie)
-auto-resize and zoom of windows.  Aspect ratio preservation
-overlay of different resolution imagery



Features to be implemented:
--------------------------
-IDL launcher .pro to enable multiple channels, datamin, datamax
-automatically figure out the channels based upon FITS header  Just throw a list of FITS files at it and it will sort into channels and time
-auto time correlation between all data channels
-auto position correlation between data channels (allow overlaying insets into full-disc imagery, ...) based upon FITS pointing and plate scale header keywords.
-switchable playback timestep mode between stepping frames and stepping in time
-3D FITS file support  (FGIV, SP4D, ...)
-3D FITS data cube support
-autodetect # of processors on machine, and thread certain operations that would benefit
-support for streaming
-anaglyph red/blue stereo support    Makes it much more accessible to the masses.
-control socket/port and protocol so commands can be sent remotely.  This will allow for multiple, synced viewers and collaboration.
-external GUI application to launch and control the software




Keyboard navigation:
-------------------
Here is a short list of keys to use in navigating and using the panorama software.
I am currently working on implementing a Java based GUI for controlling panorama.


   Key                  Description
-----------------       ------------------------------------------------------
[h] or [?]              Display the help overlay
[q] or [Esc]            Quit the application
[Spacebar]              Pauses/resumes playback
[Return]                Reset the zoom/translation/rotation to init settings
[>] or [Z]              Zoom in   (uppercase Z)
[<] or [z]              Zoom out  (lowercase z)
Arrow keys              Pan/translate display when movie is playing
                        left/right arrow step time when movie is paused
                        up/down arrow adjust alpha/blending for current channel
                        when movie is paused
[  or  ]                Roll




File formats:
------------
FITS       Panorama will load standard 2D FITS files and read in the header
           keywords.  It is best that the keywords conform to the SolarSoft
           standard keyword set, as specified here:
              http://lmsal.com/solarsoft/ssw_standards.html




Bugs:
----

Item                  Description
-------------------   --------------------------------------------------------
OpenGL/texture        There is a bug in the OS/X OpenGL implementation that
                      causes textures to come up white if a large amount of
                      textures are uploaded.  I am working on resolving this
                      with Apple and trying to come up with a simple/small
                      test case and example for them.

time correlation      Currently it is the responsibility of the user to
                      make certain that the same number of files/images are
                      specified for each channel and for each eye,
                      otherwise you see strange behavior, flashing (missing
                      images).
                      The time is based upon the earth-adjust UTC time
                      of the observation.
                      FITS keyword:   DATE_OBS
                      This will be fixed soon with the advent of time
                      correlation code that I am working on.

plate scale           Images need to be properly scaled to their relative
and transforms        sizes, rotated and overlaid given the FITS header keywords.
                      Using CDELT1, CDELT2, CRPIX1, CRPIX2, CRVAL1, CRVAL2,
                      CROTA2, ...



Author:
------
The panorama software was created and is maintained by Ralph Seguin at the Lockheed Martin Solar and Astrophysics Laboratory.
http://lmsal.com
http://lmsal.com/~seguin/panorama



----
$Date: 2007/03/08 19:22:15 $
$Id: README.txt,v 1.3 2007/03/08 19:22:15 seguin Exp $