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 , with contributions from Nathan Weeks , Andrew Johnson , Derek R. Ploor , and Brian Harring . BUGS No known bugs at this time. Please send bug reports to the author. April 2 2004 VIEWER(1)