VELVIEW: an editor for IMCORR vectors
User Documentation for version 0.9.1
Bruce H. Raup (email@example.com)
This document is part of the VELVIEW software distribution. VELVIEW is an application for editing the vectors output by the IMCORR program. IMCORR is an image-to-image cross-correlation program that generates a grid of displacement vectors for trackable features in the images. Because the correlation process is error-prone (a feature in one image can match on the wrong feature in the other image), the vectors must be visually inspected and checked for quality. VELVIEW is a tool designed for that task. The application has a graphical user interface, programmed in the C++ toolkit called "Qt", and can be compiled on Linux/UNIX, Windows, and Mac OS X. This document describes how to run the program.
Getting the software
Download the tar file for the VELVIEW distribution (tar file compressed using gzip):
An executable binary version of VELVIEW, compiled for Linux running on an Intel x86 processor, is provided in the distribution. We do not currently provide compiled binaries for other platforms, but you may be able to build the software yourself there. To install the included binary on a Linux/x86 system, change to your home directory and unpack the tar file. This will create a subdirectory called 'velview'. By default, the software expects to be in $HOME/velview, where '$HOME' is your home directory. The file 'velview.sh', included in the tar file, can be moved to some other location (for example, you might want it in $HOME/bin so that it is in your execution path). The variable called 'velview_dir', defined in 'velview.sh', should contain the full path of the directory where the unpacked files are ($HOME/velview by default). You will run velview by typing 'velview.sh' at the command line, or setting up an icon to run that file when clicked.
For example, assuming I have the tar file in my home directory, I would install the program into my environment like this (note that the '$' is the Linux prompt, and should not by typed):
$ cd $ tar zxvf velview_0-9-1.tar.gz [If your preferred location is not $HOME/velview, edit velview.sh to reflect this.]
To run the program, type
$ cp velview/velview.sh ~/bin $ velview.sh # from anywhere, assuming ~/bin is in your path
VELVIEW can be run from the command line, as described above, or a link can be created for it on the desktop. Inputs to the program include the two coregistered images, and one or more IMCORR output files. The images must be in one of these formats: BMP, GIF, JPEG, PBM, PGM, PNG, PPM, XBM, or XPM. To convert from a raw binary format to, say PNG, you can use the "convert" program from Imagemagick (http://www.imagemagick.org/script/index.php). For example, to convert a raw binary 768 by 512 pixel image with a 56 byte header to PNG, you might try
convert -depth 8 -size 768x512+56 gray:raw_image.bin image.png
VELVIEW can be run from the command line in two ways: with or without arguments. In Linux, run as
velview.sh image_one.png image_two.png or velview.sh image_one.png image_two.png vectorfile1 [vectorfile2 ...]
The first method brings up the VELVIEW main window with no images loaded, and you must load the images using the File > Open Images menu option. The second method starts VELVIEW and loads the two images specified on the command line. The third method loads the images and one or more vector files specified on the command line.
In KDE on Linux, you can create a link to VELVIEW on the desktop by right-clicking on the desktop, then selecting "Create New...", then "Link to application". In the "General" tab, you can enter "VELVIEW". In the "Application" tab, enter the command in the "Command:" field, either by typing in the complete path, or by using the browse button.
After the images are loaded, you can read in one or more IMCORR vector files using File > Open IMCORR Vector File.
Vectors in the VELVIEW program are shown in green or red --- green for a vector that will be saved (a keeper), and red for one that will not be saved. Initially, all vectors are green. A left mouse button click on a vector will display all the IMCORR fields for that vector at the bottom of the main window. Toggle between the first and second images by pressing either of the SHIFT keys. The representation of the vectors changes accordingly. Editing should take place in this sequence.
Use one of the threshold tools if you want to accept vectors with correlation strength stronger than a certain threshold, or alternatively, an error in X or Y below a certain threshold. The threshold tools are under the Edit menu. As you move the slider on a threshold tool, the threshold is displayed, and the vectors are updated immediately. NOTE: this will disregard any manual editing you have done previously, so this should be done first.
Alternatively, you can use Edit > Delete all vectors (CTRL-D) to mark all vectors for deletion, then use steps below to undelete the ones you want to keep. This too should be done first, if you choose to use this tool.
Use the mouse to delete or undelete vectors.
Right click: toggle a single vector
Right drag: delete a rectangular selection of vectors
Left drag: undelete a rectangular selection of vectors
To remove deleted (red) vectors from the display, choose "Remove 'deleted' vectors" (CTRL-R) from the Edit menu.
When the images are first loaded, they are displayed so that one grid cell in the image corresponds to one pixel on the screen. The magnification can be changed using the options under the View menu. At present, this is probably most useful for zooming out and seeing a larger area than what fits on the screen. Zooming in tends to slow the response of the application.
All green vectors can be saved to a file by selecting the File > Save Vector File option, or CTRL-S. If you try to quit the application before you have saved your changes, you will be asked whether you want to save your work first.
Version 0.9.1 Added ability to specify vector files on the command line, in addition to image files. Added two more threshold tools, for x- and y-error. Added "Delete all vectors" and "Undelete all vectors" functions to the Edit menu. Version 0.9 Original version.