VIEWPIX LITE V 1.0 B
Copyright 2017 by Glen E. Gardner Jr.
glen.gardner@gridtoys.com
About VIEWPIX....
Installation for the impatient...
Place viewpix_lite_1.0B.tar.gz in your home directory ($HOME)
Extract the tar file: tar -xzvf viewpix_lite_1.0B.tar.gz
Read the instructions below before continuing...
Software/Hardware dependencies:
Hardware:
You need an x86_64 compatible computer with a multi core processor,
at least 8 GB ram, and a big hard drive.
ie: 64 bit processor, little endian, with lots of memory and
room to store big files.
The monitor and screen resolution MUST be large enough to fit
a 1024 X 1024 window. For most modern desktop computers this
should not be a problem.
mouse stuff:
A big four button trackball is suggested, but a high resolution 2 button
or 3 button mouse will work. The little thumb operated trackballs are
not so good for this application. If in doubt, use what you have.
At present I am using viewpix with a kensington slim blade trackball
and it works well. These scenes are so large that scrolling with
a mouse is tedious, so a big trackball is a really good idea.
The operating system and software:
You need a recent version of Linux. So far viewpix is known to work on
Ubuntu 14.04, Ubuntu 16.04, CentOS 6 and CentOS 7. Viewpix should work with most current
versions of Linux.
There are quite a few software dependencies to install...
Install Mesa. Be sure to install the libs, tools,
and development stuff.
Install freeglut. Make sure you install libs. tools, development,
everything.
Install gdal. Make sure you install everything, libs, tools,
development, etc.
Install image magick. As always, install everything.
About Directory Structure....
The present directory structure is as follows:
$HOME/landsat is the top level directory for this project.
$HOME/landsat/geotiff/src/glview
This directory contains the source code for viewpix, this README.TXT
file, some accesory scripts, and a txt directory with the file;
paths.txt in it.
$HOME/landsat/geotiff/src/glview/txt/paths.txt This is the only
configuration file.
It contains two single line entries in the following order:
The path to the "nfo" directory where the parsed landsat 8
metadata .NFO files should be.
and
The path to the "bsq" directory where the binary data for each
band should be.
The entries in paths.txt should not contain any blank lines,
leading spaces, or non-printable characters.
$HOME/landsat/geotiff contains the scripts for extracting the data as
well as the following directories;
$HOME/landsat/geotiff/tar The tar files containing the landsat
data sets.
$HOME/landsat/geotiff/src leads to the source code and executable.
$HOME/landsatgeotiff/gtif contains the extracted geotiff files.
$HOME/landsat/geotiff/nfo contains the extracted landsat metadata files.
$HOME/landsat/geotiff/bsq contains the ENVI BSQ format (raw, single
band binary data) files extracted from the geotiff files.
$HOME/landsat/geotiff/hdr contains the ENVI and TIF header files for
the BSQ files (not needed, but we keep them anyway).
$HOME/landsat/geotiff/xml contains xml files from the geotiff and ENVI
files (not needed, but we keep those too).
$HOME/landsat/geotiff/incoming/tar Is the directory for importing
new incoming landsat 8 scenes from tar.gz files.
The scripts in $HOME/landsat/geotiff will need to be edited if you
choose to do something different.
how it works:
To bring in new scenes, place the landsat 8 tar.gz files
in $HOME/landsat/geotiff/incoming/tar
cd $HOME/landsat/geotiff
Then execute get_new_data.sh
The script extracts the geotiff files and moves the components into
the gtif, txt, and hdr directories.
The script also calls gdal to extract the binary data from the
geotiff files and moves the resulting data into the bsq directory,
the header files into the hdr directory, and the xml files into the
xml directory.
The script parses the landsat 8 MTL files in the txt directory for
geolocation and scene resolution data then places the results in .NFO
files in the nfo directory.
The script then moves the tar.gz file to $HOME/landsat/geotiff/tar
To rebuild EVERYTHING in $HOME/landsat/geotiff/tar;
The landsat 8 tar.gz files must be in $HOME/landsat/geotiff/tar
rebuild_all.sh must be executed (you must be in $HOME/landsat/geotiff).
The operation of this script is similar to that of get_new_data.sh
To compile viewpix;
Make sure all hardware and software dependencies are satisfied.
To compile;
cd $HOME/landsat/geotiff/src/glview
gcc -o viewpix viewpix.c -lGL -lglut
To run viewpix: cd to $HOME/landsat/geotiff/src/glview and run viewpix.
./viewpix <landsat 8 product identifier>
for example: ./viewpix LC08_L1TP_233083_20170509_20170509_01_RT
will load all bands of LC08_L1TP_233083_20170509_20170509_01_RT and create
a 30m panchromatic scene at band 12.
using viewpix:
use: viewpix <landsat 8 product identifier>
Viewpix starts with a low resolution view of the scene. Positioning the
cursor over a desired target and clicking the lower left trackball
button will zoom into full resolution at the position of the target.
Moving the trackball will scroll the scene along x/y coordinates.
Left click again to stop scrolling and enter measurement mode.
In measurement mode, position the cursor over a target pixel and
click on the lower right trackball button. The latitude, longitude,
x and y position of the cursor, as well as brightness value of
the pixel will be printed to the console window.
Clicking on the lower left trackball button again will reload
the scene at the current position and resume scrolling.
Scrolling with the trackball will redraw the scene as the
position changes.
Filters are applied to the area in view only. Moving the mouse, or
switching into scrolling mode will force the screen to redraw from
the original unfiltered scene, erasing the filtered view. Filters may
be reapplied by using the buffer replay function. Click on
the upper right trackball button or press 'r' to reapply the filters
from the buffer.
changing bands is a matter of pressing the corresponding function key
on the keyboard. (ie: pressing key F5 will switch to band 5.)
Band 8 is a 15 meter resolution panchromatic scene. All other bands
are 30 meter resolution. Band 12 is a 30m panchromatic scene created
by averaging data from bands 2, 3, and 4 (blue,green,red).
A simple histogram can be printed at the console window at any time by
pressing 'h'. Pixels with a value of zero (0) are not accounted for in
the histogram, because only non-data pixels have a value of zero in
these data sets. The histogram only accounts for data from the scene
in view.
about the histogram:
The histogram is simplified. The values given are arrived at using
integer math rounded by truncation. The value for median pixel value
is estimated, and might, or might not exist in the data set.
The reported mode is simply the first mode found. There is likely
more than one mode in a data set of this size. The histogram is
adequate for the purpose and is left as-is.
MOUSE FUNCTIONS:
LEFT MOUSE BUTTON: Enters full resolution mode with scrolling.
Also switches between scrolling and measurement mode.
RIGHT MOUSE BUTTON: prints the latitude, longitude and brightness value
at the cursor position when the cursor is visible).
UPPER LEFT TRACKBALL BUTTON (MIDDLE MOUSE BUTTON): Returns to the
low resolution view.
UPPER RIGHT TRACKBALL BUTTON: Replays buffered filter commands.
KEYBOARD FUNCTIONS:
r replays buffered filter commands.
c clears the filter command buffer.
l returns to the low resolution view.
h shows some histogram information.
F saves the current screen to a binary file (enter a file name).
? shows the help info.
q quits viewpix.
RIGHT ARROW: Increases contrast range by 1000.
LEFT ARROW: Decreases contrast range by 1000.
UP ARROW: Increases brightness by 1000.
DOWN ARROW: Decreases brightness by 1000.
F1-F12 changes the band in view.
Pixel brightness values are limited to the range of 1 to 65535.
Pixel values of zero are considered "no data" and are not acted upon.
The brightness and contrast adjustments will "clip" brightness values
at 1 or 65535 if the adjustment exceeds these limits.
About the filter command buffer:
Viewpix has a 1024 character buffer that automatically stores
keystrokes. If the brightness, or contrast
are adjusted, these keystrokes are recorded for later use.
The unsharp mask filter keystroke is not played back.
The keystrokes can be replayed by clicking the upper right trackball
button or by pressing the 'r' key.
Pressing the 'c' key will clear the filter command buffer.
Saving the current screen;
Pressing 'F' will result in a prompt for a file name in the console
window. Type in a file name and press enter. The file will be
saved as 16 bit unsigned integer data with 1024 x 1024 resolution.
The file can be converted to an 8 bit gray scale jpeg using
Image Magick. The script bsq2jpg.sh contains an example of
the command line needed to do this.
errata & insanity:
Mouse sensitivity.
Mouse sensitivity can make measuring latitude and longitude accurately
difficult. It may be helpful to slow the mouse down to get better
pointing accuracy when trying to get latitude and longitude on a pixel.
Here are the settings that I use for a kensignton slim blade trackball
on ubuntu 14.04:
to slow it down: xinput set-prop 11 276 3
to restore it to normal: xinput set-prop 11 276 1
Your individual settings may vary, and other pointing devices will
be very different. You probably want to check the man pages for xinput.
It is a pretty sophisticated tool, and there will be device differences
from one installation to the next.
Resolution of the latitude and longitude measurement mode.
The latitude and longitude for the corners of the scene as supplied
with the data set resolves to five decimal places to the right of the
decimal point. The latitude and longitude values for each pixel are
interpolated using double precision floating point math. The get_ll()
function results are displayed to six decimal places to the right of
the decimal point. Using the kensington trackball on Ubuntu 14.04
Linux with the mouse speed set to minimum allowed for resolution
of a point in the scene to a confidence of three decimal places
with repeated measurements.
Using xinput to further slow the trackball by a factor of three allows
three decimal places to be easily resolved, and four decimal places
with some care using repeated measurements.
As far as accuracy relative to a known geodetic datum is concerned,
multiple mountian tops have been checked with good accuracy. I get
the expected numbers. The trouble with measuring mountians is that
many of the reported positions are not commonly reported with more
than two or three decimal places to the right of the decimal point
such that the accuracy of viewpix lat/lon measurements has yet to
be fully determined.
Make sure the cursor is "off" when changing bands.
If you change bands when in measurement mode (the cursor is visible),
you may experience a change in x/y coordinates when flipping between
bands. In order to avoid this, left click on the mouse to shut the
cursor off before changing bands.
The window MUST be 1024 x 1024 pixels.
If x windows tries to resize the viewpix window, viewpix will attempt
to restore it to the proper dimensions. On some flavors of Linux
X will frequently overeride opengl and resize the window anyway, which
throws off the accuracy of latitude and longitude measurements.
On some gnome desktops you can try setting the upper and lower toolbars
to "autohide" in order to get a little more room for the window.
Since the viewpix window will reset its size when resized, sometmes
just grabbing the upper edge of the window with the resize cursor and
pulling it down to resize it will cause it to snap back into the
proper dimensions when the mouse button is released.
Docking the window to the task bar will force the window into full
screen mode. This should be avoided as it will cause the latitude
and longitude tracking to be off by quite a lot.
Scrolling is not one-pixel-at-a-time.
When scrolling, the screen scrolls in 16 pixel groups when viewing
a 15 meter resolution scene and in 8 pixel groups when viewing a
30 meter resolution scene. This is normal and how viewpix works.
Measurement mode operates at 1 pixel resolution, and is unaffected
by the method used for scrolling.
Scan Line Limit?
The maximum number of scan lines is 16K (16384) for a 15m resolution
scene, and 8K (8192) for a 30m resolution scene. Viewpix will drop
scan lines beyond these limits. Likewise, the length of a scan line
may not exceed the limits. Behavior past the limit is untested.
About the source code:
The source code is comprised of four files:
variables.h The global variables (yes, viewpix is very stateful!)
functions.c The source code for the functions used by viewpix.
bilinear_interp.c The source code for the billinear interpolation
used to get latitude and longitude.
viewpix.c This is the main body where variables are initialized,
data is buffered, configuration is done, and the opengl rendering
is set up.
Theory of operation:
The windowing is based on a main loop which drives glut callback
functions to handle redrawing the window, keyboard, mouse events, and
window resize events. The callback functions are reentrant,
hence there is extensive use of global variables to keep things
synchronized and stateful. Most things in viewpix are driven by
these callback functions.
Rendering is accomplished using glDrawPixels() which provides for
direct rendering to hardware frame buffers in Mesa. Window and event
management are provided by glut functions.
Viewpix buffers the entire scene into a buffer such that the scene
dimensions become square and an integer multiple of 1024 in size. At
startup a copy of the scene scaled to fit the 1M pixel window is placed
in the viewing buffer, flipped on the Y axis, then rendered to the
window.
When scrolling at full resolution, an initial 1M pixel portion of
the scene is copied to the viewing buffer, flipped on the Y axis,
then rendered to the window. To accomplish scrolling, mouse movements
are tracked and memory pointers to the scene buffer are adjusted
accordingly. The new 1M pixel portion of the scene pointed to by
scrolling is then copied to the viewing buffer, flipped on the
Y axis, and rendered to the window.
Viewpix buffers keystrokes. Calls to filters are stored there
and can be recalled by a single keystroke.
In all cases, if the pixel being modified by the filter has a value of zero,
no operation is performed on that pixel. For all operations in viewpix,
a zero pixel value is "no data", and operations are not performed on
those pixels.
Download Latest Version
viewpix_lite_1.0B.tar.gz (39.1 kB)
