building viewer:
----------------

Building viewer should now work on many platforms due to the use of 
autoconf and automake. To build viewer do the following:

LINUX BUILD INSTRUCTIONS:

./configure
make
make install

MAC OSX BUILD INSTRUCTIONS:

Generally, builds on OSX are the same as with linux, however some
versions of the GLUT libraries have the problem that the program will
not get focus when started. To fix this issue OSX users can use a
resource patch (mac.r). For all versions of OSX you should do the 
following two steps:

./configure
make

Then you can test out the viewer binary to see if you need to apply the 
resource patch before you install:

./viewer -m testimage.ppm

if the application gets focus you will be able to move the image around 
with the arrow keys. In this case you don't need the resource patch and 
you can just install:

make install

Otherwise, you need to apply the resouce patch before you install. This 
can be done by:

make mac
make install

OS 10.2 is known to require the resource patch, but my testing on OS 
10.3 did not require the resource patch. If you have results different 
than this (or if you test on another OS version) please let me know and 
I'll update this document.

Another mac-specific item is the detection of desktop size. When viewer
probes the OpenGL system to find out the desktop size, it is told the
same thing regardless of whether you have a single desktop or a
horizontally spanning pair of desktops. As a result, viewer will double 
the width it is told (assuming that you are using viewer on a dual head 
system). One slight drawback to this is that when using viewer in a 
single headed configuration (as I often do when testing), it will only 
half fit on the screen. To resolve this issue, you will need to use the 
'-g' option to specify the size of your desktop. For example, 

viewer -g 1024x768 -i left.ppm right.ppm

WINDOWS BUILD INSTRUCTIONS:

In windows there are two build options: opening the viewer.vcproj file 
in visual studio or using the command line 'nmake' tool to build using 
the supplied Makefile.win file. To use the makefile you need to open a 
command prompt that knows about the visual studio programs (there is 
usually an option for this in the visual studio portion of the menu) and 
change to the directory where you have uncompressed viewer. Typing 
"nmake /file Makefile.win" should build everything.

if for some reason the above instructions dont 'just work' for you,
please let me know so that i can fix it.

usage:
------

this usage information is taken straight from the manpage.

VIEWER(1)                                               VIEWER(1)

NAME
       viewer - stereo pair viewer/aligner

SYNOPSIS
       viewer [ options ] [ file(s) ]

       viewer [ basename ]

DESCRIPTION
       viewer  is an OpenGL based stereo pair viewer and aligner.
       At present it only accepts images in the PPM image  format
       but work is in progress to allow use of other image types.
       viewer is known to  work  on  various  systems,  including
       Linux and OSX, but should work on anything with OpenGL and
       a compiler. Besides being useful as a stereo  pair  viewer
       it  is  also  possible  to  view  a  mono image and easliy
       pan/drag around within the image.

       There are three modes in which to use viewer : as  a  mono
       viewer  (with the -m option), as a stereo viewer (with the
       -i, -v, -f, or -p option), or as  a  stereo  pair  aligner
       (with  the  -a option). There is an additional special way
       that viewer can be run: if no arguments are given and only
       an  image  'basename' is given the program will load base
       name-l.ppm and basename-r.ppm and enter viewer mode.  This
       can  be  very convenient for viewing already aligned image
       pairs using the default configuration. If the  program  is
       not  run in with a basename then one of the -m , -v , -i ,
       or -a options must be used. The -o , -l , and  -r  options
       are only useful when running in aligner mode. If viewer is
       run using basename it enters aligner mode.

       Additionally it is possible to pass the -g option to spec
       ify  the  window  size. If this option is omitted then the
       window will cover the entire desktop.

       Depending upon which mode the program is  running  in  the
       cursor  keys  will vary. In viewer mode it is assumed that
       both images will be moved together and that not much 'fine
       tuning'  will be necessary, so by default movement is over
       the image in the specified direction in increments  of  10
       pixels.  If  SHIFT is used in combination with cursor keys
       then movement will be in increments of 1 pixel.  In  addi
       tion,  the  user  can  press  a to temporarily enter 'fine
       alignment' mode. In this mode the cursor key behavior acts
       as  if  the program were in aligner mode until this key is
       hit again to return to the standard viewer behaviour.

       The keyboard behavior of mono viewer mode is identical  to
       standard  viewer  mode with the exception that there is no
       fine alignment mode.

       In alignment mode the cursor key interaction  is  slightly
       more  complicated  due to the extra flexibility necessary.
       It is known that some window managers (notably  KDE)  will
       intercept  some  of  these keyboard commands. The user may
       wish to redefine the behaviour of the  window  manager  to
       avoid this. Future plans for viewer include the ability to
       use user-defined keyboard commands to avoid this  problem.

       The  mouse can be used to drag images in all viewer modes.
       In alignment mode left clicking and dragging will move the
       particular  image (left or right), whereas middle clicking
       and dragging will move both images.  In  viewer  and  mono
       modes  clicking either the left or middle button and drag
       ging will move both images, and clicking the right  button
       and dragging will zoom in/out.

OPTIONS
       The options are:

       -h, --help
              Display usage and version information and exit

       -i, --input [leftimage.ppm rightimage.ppm]
              Display a pair of images in viewer mode

       -v, --view [fullimage.ppm]
              Display  a  combined pair of images in viewer mode.
              assumes left half of image is left  eye  image  and
              right half of image is right eye image.

       -m, --mono [monoimage.ppm]
              Display a mono image in viewer mode

       -a, --align [leftinfile.ppm rightinfile.ppm]
              Display a pair of images in aligner mode

       -o, --output [fulloutfile.ppm]
              Specify  the  output file for a joined stereo pair.
              Default value is fullout.ppm. This option  is  only
              useful in aligner mode.

       -l, --left [leftoutfile.ppm]
              Specify  the  output  file  for  the left half of a
              stereo pair. Default  value  is  leftout.ppm.  This
              option is only useful in aligner mode.

       -r, --right [rightoutfile.ppm]
              Specify  the  output  file  for the right half of a
              stereo pair. Default value  is  rightout.ppm.  This
              option is only useful in aligner mode.

       -p, --import [file(s)]
              Specifies  files  to import. viewer will attempt to
              find pairs based on  the  filenames  given  to  it,
              ignoring  files  that it can't find a match for. It
              will look for filenames that are  identical  except
              with  one having a "L" and the other having an "R",
              or with one having "left" and  the  other  "right".
              Both  are  case  insensitive, so "rIgHT" and "LEft"
              would also work.  Only  works  in  standard  viewer
              mode.

       -g, --geom [WIDTH]x[HEIGHT]
              Forces  viewer  to use a specified window geometry.
              The default behavior is to cover the  entire  desk
              top.

       -x, --off [x_offset][y_offset]
              Specifies  the offset of the right hand image rela
              tive to the left hand  image.  this  option  should
              only be used AFTER a filename has been specified on
              teh command line (ie: viewer -i left.ppm  right.ppm
              -x -2+4).

       -t, --thumbsize [size]
              Specifies  the  size  that  should  be used for the
              thumbnail view. The default is 100 pixels  (so  the
              thumbnail  view of image and screen will be at most
              100x100 pixels).

       -n, --nothumb
              Disables thumbnail view

       -z, --nofac
              Disables zoom percentage view

       -f, --file [filename]
              Specifies a file which contains a  list  with  four
              entries  per line, the first representing the file
              name of the left hand image, the second  represent
              ing the filename of the right hand image, the third
              representing the x offset of the  right  image  and
              the  fourth  representing the y offset of the right
              image. The 'n' (or next) and 'p' (or prev) keys can
              be used to view multiple pairs as a slideshow.

       -s, --stereo
              Enables  hardware stereo mode (also known as "clone
              stereo" mode or "quad buffered stereo mode").  This
              option  is  valid  for  both  viewer  and alignment
              modes, but if specified with mono mode it  will  be
              ignored.

       -u, --fullscreen
              Enables  fullscreen  mode.  This  is  valid for all
              viewing modes, but if the window geometry is forced
              this option will be ignored.

       -w, --show [time]
              Starts  the  viewer in slideshow mode. this is just
              viewer mode with  automatic  pair  switching  every
              'time' seconds.

viewer mode commands
       these  are  the  commands  available while in viewer mode.
       starting with version 0.8.0 this includes most of the com
       mands found in WallView.

       q, ESC quit

       a      toggle  'fine  alignment'  mode  on/off.  this will
              cause the cursor keys  to  temporarily  act  as  in
              aligner mode.

       x, f   zoom out

       z, k   zoom in

       b      small zoom out

       v      small zoom in

       n, SPACE, PAGEUP
              next image

       p, BACKSPACE, PAGEDOWN
              previous image

       c      center images

       h      home image (center and default zoom)

       d      double size

       1      actual size

       2      half size

       3      quarter size

       4      eighth size

       5      sixteenth size

       LEFT, g
              move images left 10 pixels

       SHIFT+LEFT
              move images left 1 pixel

       RIGHT, j
              move images right 10 pixels

       SHIFT+RIGHT
              move images right 1 pixel

       UP, y  move images up 10 pixels

       SHIFT+UP
              move images up 1 pixel

       DOWN   move images down 10 pixels

       SHIFT+DOWN
              move images down 1 pixel

       CTRL+g move right image left 1 pixel

       CTRL+j move right image right 1 pixel

       CTRL+y move right image up 1 pixel

       CTRL+n move right image down 1 pixel

mono viewer mode commands
       the  commands  for mono viewer mode are identical to stan
       dard viewer mode, however there is no fine alignment since
       there is only a single image.

aligner mode commands
       these are the commands available in aligner mode:

       q, ESC quit

       n, SPACE, PAGEDOWN
              next image

       p, BACKSPACE, PAGEUP
              previous image

       ENTER  crop  images  to  screen and write left, right, and
              joined images

       SHIFT+ENTER
              crop images to screen and write  left,  right,  and
              joined images, then immediately exit

       LEFT, RIGHT, UP, DOWN
              move left image 1 pixel in specified direction

       CTRL+(LEFT, RIGHT, UP, DOWN)
              move left image 10 pixels in specified direction

       SHIFT+(LEFT, RIGHT, UP, DOWN)
              move right image 1 pixel in specified direction

       SHIFT+CTRL+(LEFT, RIGHT, UP, DOWN)
              move right image 10 pixels in specified direction

       ALT+(LEFT, RIGHT, UP, DOWN)
              move both images 1 pixel in specified direction

       ALT+CTRL+(LEFT, RIGHT, UP, DOWN)
              move both images 10 pixels in specified direction

EXAMPLES
            viewer pair0611b

       will read pair0611b-l.ppm as the left image and pair0611b-
       r.ppm as the right image. when the image  is  cropped  (by
       pressing    enter)   the   files   pair0611b-leftcrop.ppm,
       pair0611b-rightcrop.ppm, and  pair0611b-pair.ppm  will  be
       written.

            viewer -a pair0611b-l.ppm pair0611b-r.ppm

       is  equivalent  to  the above command in that it will read
       the same two files, however the default  output  filenames
       will  be leftout.ppm, rightout.ppm, and fullout.ppm rather
       than the above.

            viewer   -a   pair0611b-l.ppm   pair0611b-r.ppm    -l
       cropleft.ppm -r cropright.ppm -o stereoimage.ppm

       this  again reads the same two images, however rather than
       using the default  output  filenames  it  will  write  the
       cropped  and  stereo images to the specified filenames. if
       any of the output options are omitted the default will  be
       used.

            viewer -v pair0611b-pair.ppm

       this will simply allow you to view the cropped and aligned
       stereo pair which was created in the first example  above.

            viewer -m monoimage.ppm

       this will read a single image in mono viewer mode.

            viewer -i lefty.ppm righty.ppm -g 1024x384

       will  load  the  specified pair in viewer mode in a window
       covering the upper half of a 1024x768 desktop.

            viewer -i  left1.ppm  right1.ppm  -off  +3-5  --input
       left2.ppm right2.ppm -i left3.ppm right3.ppm -x -3+0

       this  will  load a series of three images for a slideshow.
       the first and third are not quite aligned so an offset  is
       speciified,  but  the second pair is already aligned so no
       offset information is  necessary.  note  that  the  offset
       option applies to the PREVIOUS file input option.

            viewer -f slideshow

       this  will  load a series of images with the filenames and
       offets being taken from the file. each line  of  the  file
       should  contain exactly four items: left image name, right
       image name, x offset, y offset. these items are  separated
       by  spaces and all four options must be present.  comments
       may be inserted into the file for  better  readability  by
       using  a  #  sign at the start of a line. blank lines will
       also be ignored.

            viewer --nothumb -p ../images/*.ppm

       this will turn off the thumbnail view and attemp to import
       pairs  from "../images/*.ppm", ignoring images that do not
       form pairs.

ENVIRONMENT
       No special environment variables.

LICENSE
       This software is covered under the GNU Public  License  as
       outlined  in the COPYING file included with this distribu
       tion.

AUTHORS
       Russ  Burdick  <wburdick@cs.umn.edu>,  with  contributions
       from   Nathan   Weeks   <weeks@usgs.gov>,  Andrew  Johnson
       <aej@evl.uic.edu>,   Derek    R.    Ploor    <drploor@stu
       dents.wisc.edu>, and Brian Harring <bdharring@wisc.edu>.

BUGS
       No known bugs at this time. Please send bug reports to the
       author.

                           April 2 2004                 VIEWER(1)

