RoiView Help
Help Topics:
Please enable JavaScript in your browser
RoiView - Explore InSAR data and moreVersion: 0.75 Created by: Ran Novitsky Nof, 2010 Web Site: http://roiview.sourceforge.net/ License:RoiView is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version. RoiView is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with RoiView; if not, see <http://www.gnu.org/licenses/>.
Usage: roiview.py [<inputfile>] [-i <intensityfile>] [-o <outputfile>] [--title '<title>']
[-f <format>] [-b <bands number>] [-w <width>] [-l <length>]
[--i0 '<formula>'] [--i1 '<formula>'] [--lut <lutfile>]
[Options: apsgdv or h]
inputfile: BIL format files (*.int, *.unw, *.cor, *.slc, *.hgt, *.dem or *.DEM) form ROI_PAC.
Make sure to have a .rsc header file or any extention with
ERDAS ER Mapper's raster .ers header file. or use manually by providing
-w or -l and -b (also optionally -f).
int & slc are expected to be of type complex 64bit
(32bit real, 32bit imaginary)
unw, cor, hgt are expected to be of type 32bit BIL
(line on 32bit magnitude interleaved by a 32bit phase line)
dem, DEM are expected to be of type 16bit integer of
elevation data, with a null value=-9999. This type of image
will be hillshaded if not using -p option.
-i intensity: a file containing the intensity for the image. parameters of
file must be the same as for inputfile. if omitted, intensity
will be taken from inputfile. the colors will be of layer 1
(if available) of the inputfile and layer 0 of the intensity.
-o outputfile: image file (image type will be determined by the
extension of the file name, if no extension,
default will be: outputfile.png. extensions supported
by the active backend. Most backends support png, pdf,
ps, eps, jpg and svg. -o is set to save only, if you whish to show image
as well, append -s option.
-f format : the format of data. can be any numpy dtypes e.g.
float32 complex64 int16 etc. (see numpy.typeDict for more types)
-b bands : number of bands in data (should be 1 or 2)
-w : width of data - number of pixels/columns in a row
-l : length of data - number of lines/rows
--title 'title' : title expression. use ' for multiple word title e.g.:
'title of multiple words'. can get mathtext expression see matplotlib mathtex tutorial
--ix 'formula' : a formula to apply on data. use ' to mark the formula start
and end. use i1 to refer to foreground data (phase) and i0 to
refer to background data. example:
--i1 'i1%(2*pi)-pi' will give the data modulu 2pi (wrapping the data between pi and -pi).
--i1 'i1+i0' will give the sum of both layers. Formulas can use any pylab function.
x in --ix can be 0 for background and 1 for foreground.
--lut lutfile: use color transformation file to set cmaps and look up table.
lut format is xml style (see more details):
<RoiView ver="0.75">
<lut>
<fgcmap>gray</fgcmap>
<x dtype="float64">0.0,1.0</x>
<y dtype="float64">0.0,255.0</y>
</lut>
</RoiView>
Options:
-a: Produce only amplitude/hilshade image.
or
-p: Produce only phase/elevation image.
-s: also show the image if -o is valid.
-g: Consider a geocoded image.
-d: Save/show only image data (no color-bar, title, etc.).
-h: Show this message.
-v: Verbose
RoiView's GUI is based on pygtk, a python api for GTK+ widgetes. If loading of RoiView's GUI fails, matplotlib default backend will be used.Main Window:
The main window has 6 areas: 1. Menubar 2. Amp/Phs toggle 3. Image Canvas 4. Data Info 5. Image Toolbar 6. Statusbar
RoiView GUI main window
1. Menubar: The menubar is the top pannel where you can load, save and export data and figures, arrange viewing properties and load different tools such as color manager, formulas and scripts and even change the title or intensity layer. 2. Amp/Phs toggle: Pressing on each of them will toggle the layer on or off. phase is the foreground layer and amplitude is the background intensity layer 3. Image Canvas: The image canvas is where the figure is being ploted. 4. Data Info: When moving the mouse on the image canvas, the data info area will show the point location and values. 5. Image Toolbar: The Image toolbar provide means for contoroling the image - zoom,pan etc. It is a matplotlib Navigation Toolbar. 6. Statusbar: The status abr provide information regarding the current stat of the image toolbar or show messages of roiview's status.
RoiView was originaly designed to replace DGX/MDX software which require bureaucracy to obtain. This software was used in order to view ROI-PAC interferometry processing results but producing an image from file was not so strait forward. In time support was added for ERDAS ER Mapper header files and for user provided parameters with or without header files. Data files format: Supported files are in a BIL format meaning Band Inteleaved by Line. Each data layer or band will apear in the binary data file line after line so if we have two layers, the first line in the data file is the first line of the first band, the second line is the first line of the second band, the third line is the second line of the first band. or even lines are for the first band and odd lines are for second band. The files are in binary format and can be in any type of numpy dtypes e.g. float32 complex64 int16 etc.File options in RoiView's GUI
Open files:
When roiview trys to open a data file, it first looks for an ER Mapper .ers raster header file
and if none is found it then looks for ROI-PAC .rsc header file. If no header file is found,the
RoiView's GUI asks for user provided parameters.
Header parameters dialog in RoiView's GUI
Where:
File : The file name.
Data Type : Select the correct data type
(default is float32).
Bands : Select the correct number of bands
(layers) in the file (default is 2).
Length : Provide number of lines.
Width : Provide number of pixels in a line.
Byte order : Select byte order (deafult is little
endien).
Y/X interval: The size of pixel in Y/X dimentions
(default is 1).
Top-Left E/N: Coordinates for the top-left corner
(Default is 0,0)
Some of the parameters can also be given on the command line in order to open a headerless file. Export Data: RoiView's GUI can export the data to an ER Mapper raster file and also creating an appropriate header file. On the GUI manue use File -> Export to in order to export the data. The data being saved is the formula results applied over the original data (no LUT applied). This function is not available using the command-line. Save image: RoiView can save the produced image to an image file. Supported image formats are determined by the active backend. Most backends support png, pdf, ps, eps, jpg and svg. Via command-line: append -o <outputFileName> to the comman line. Note: -o is setting RoiView to save only, if you whish to view the image in GUI as well, append -s to the command-line. Via GUI: On the GUI manue use File -> Save As or presson the image toolbar.
RoiView can use a different file for the intensity (background) layer.
Command line key:
-i <background file name>
GUI:
Location:
Tools -> 
Load intensity
A file chooser dialog will appear and guid you through.
Note! the layer dimentions must be same as the foreground layer.
Use formula to evaluate the data. any function of python's pylab/numpy modules is acceptable. in the formulas i1 represents the foreground layer and i0 represents the background layer. Defaults: for all type of data : --i1 'i1' : The value for the foreground is the value of layer 1. for dem type of data : --i0 'hillshade(i0)' : Calculate hillshade based on the forground data values. for other typs of data : --i0 'i0**0.35' : Calculate the background layer in the power of 0.35 . Command line key: --x1 '<Some formula for color layer (phase or elevation)>' or --x0 '<Some formula for intensity layer (amplitude or hillshade)>' GUI: Location: Tools ->Formula
Formula location
Formula Dialog
Usage:
Simply write the formula in the text areas and click 'Apply'. pressing ? will bring up this page.
Examples:
hillshade(i0) : will calculate the hillshade of the background.
cos(i1) : will calculate the cosine function of each pixel of foreground data.
i1%(2*pi)-pi : will wrap foreground data for range of pi to -pi.
i0**x : will produce (background data)^x where x can be any number
0 : will zero all pixels
Note!
the formula calculator uses python eval function.
the calculation is done over the original data not the
previously calculated formula.
use with caution!
see also: script tool
Matplotlib module (v 0.99) enables hillshade method (shade) using a LightSource class. The problem is that it uses the data itself as intensity and color. It is very useful for viewing a DEM but sometimes you would like the hillshaded DEM as an intensity layer underlying some other data. So RoiView has it's own hillshade method. hillshade(data,scale=10.0,azdeg=165.0,altdeg=45.0): input: data - a 2-d array of data scale - scaling value of the data. higher number = lower gradient azdeg - where the light comes from: 0 south ; 90 east ; 180 north ; 270 west altdeg - where the light comes from: 0 horizon ; 90 zenith output: a 2-d array of normalized hillshade This function or method can be used in RoiView's formula and is the default for DEM files.
DO NOT USE IF YOU ARE NOT FAMILIAR WITH PYTHON! RoiView GUI has the option to run a python script. using: Tools ->Script This will open a shell window. Simply write your code and press run. RoiView will then use python's function exec in order to run the code. An error will be shown on a dialog window if needed. Use with real care. This option is for very advanced users of RoiView and python. it has the ability to do virtually anything python shell can. See source code files roiviewdata.py and roiviewgtk.py for RoiView's classes and methods. - The term self referes to the appGui class object. - The term self.data referes to the roiviewdata class object (data object, containing all information about the layers).
The color manager dialog can help in controlling the image color transformation (how data values are represented as RGB colors). on the GUI main window use: Tools ->Color Manager this will upload the color manager dialog:
RoiView's color manager
At the top of the manager there is a menu with icons to control:color maps to change the foreground color map.
open and
save look up table (LUT) file which holds information regarding the color transformation. and Overlay method which determins the mixing method for foreground (color) and background (intensity). On the right side there are icons to control:
: Clip value limits to 95% of data values.
: Clip values to 100% of data values.
: Set data limits to original data limits. At the bottom of the manager, one can set the data limits of max/min values. Values above or under the limits will get the colors of the limits. On the left is the current layer color map. layers can be selected through the Forground/Background tabs. The center of the manager is showing the data histogram in a bold blue line. The black line is the look up table (LUT) which can be controled and adjust: Left mouse click on the line creates a new vertex on the line. Left mouse click and draging on a vertex (point) will adjust the line. Right mouse click on a vertex (point) will delete the vertex. Center (wheel) mouse click will reset the line and remove all vetices. Note! after a vertex is created,removed or moved, the manager will adjust the colors of the image. This procedure might take a long time on large datasets or low memory/preformance computers.
RoiView uses matplotlib color maps. These can be selected from the color manager or set by a LUT file. available color maps:gist_earth (default for DEM files)
jet (default for other files)
gray (default for intensity layer)
Accent
Accent_r
autumn
autumn_r
binary
binary_r
Blues
Blues_r
bone
bone_r
BrBG
BrBG_r
BuGn
BuGn_r
BuPu
BuPu_r
cool
cool_r
copper
copper_r
Dark2
Dark2_r
flag
flag_r
gist_earth_r
gist_gray
gist_gray_r
gist_heat
gist_heat_r
gist_ncar
gist_ncar_r
gist_rainbow
gist_rainbow_r
gist_stern
gist_stern_r
gist_yarg
gist_yarg_r
GnBu
GnBu_r
gray_r
Greens
Greens_r
Greys
Greys_r
hot
hot_r
hsv
hsv_r
jet_r
Oranges
Oranges_r
OrRd
OrRd_r
Paired
Paired_r
Pastel1
Pastel1_r
Pastel2
Pastel2_r
pink
pink_r
PiYG
PiYG_r
PRGn
PRGn_r
prism
prism_r
PuBuGn
PuBuGn_r
PuBu
PuBu_r
PuOr
PuOr_r
PuRd
PuRd_r
Purples
Purples_r
RdBu
RdBu_r
RdGy
RdGy_r
RdPu
RdPu_r
RdYlBu
RdYlBu_r
RdYlGn
RdYlGn_r
Reds
Reds_r
Set1
Set1_r
Set2
Set2_r
Set3
Set3_r
spectral
Spectral
spectral_r
Spectral_r
spring
spring_r
summer
summer_r
winter
winter_r
YlGnBu
YlGnBu_r
YlGn
YlGn_r
YlOrBr
YlOrBr_r
YlOrRd
YlOrRd_r
The look up table determines how data values are transformed into color values. The data values are normalized to a 0-1 interval and the colors to a 0-255 interval. RoiView supports a xml style file which holds the parameters for the color transformation. This lut file can be set as a command-line option: --lut <lutfile> or it can be load and save in RoiView's GUI using the color manager. The lut file format is a xml style and looks like this:
<RoiView ver="0.75"> <lut> <fgcmap>gray</fgcmap> <x dtype="float64">0.0,1.0</x> <y dtype="float64">0.0,255.0</y> </lut> </RoiView>
The fgcmap tag holds the foreground color map name. The x tag holds the data values points. Must start with 0.0 and end with 1.0 The y tag holds the color values points. Must start with 0.0 and end with 255.0 The number of x and y points must be equale.
Overlay methods can be set only using RoiView's GUI color manager. the methods are hard light and soft light. Hard light: Uses the background layer to highlight or shadow the foreground layer. (see more details on Hard light in ImageMagick pages) This method is the default for all file types except DEM. Soft light: Uses the foreground layer to color the background layer preserving any shadow or highlighting effects in the background layer. (see more details on Hard light in ImageMagick pages) This method is the default for DEM files. Both methods are actually an implementation of the pegtop soft light.
RoiView's GUI view options
The view options control what and how elements will be displayed on figure.
In GUI mode:
Full View : Checking will uncheck the title, color-bar and grid and set
the image to cover the whole figure.
Title : toggle title on/off.
Color-bar : toggle color-bar on/off.
Grid : toggle grid (coordinate system) on/off.
Best Fit : fix window size to image width-length ratio.
Rfresh : load iriginal data and reset some options.
Comman-line options:
-d : toggle full view on.
RoiView's default title is the file's name. However,
it can be changed using command-line or GUI options.
Comman-line options:
--title 'title' : title expression. use ' for multiple
word title e.g.: --title 'title of multiple words'.
In GUI mode:
Tools -> 
Edit Title
Title can get mathtext (latex style) expressions:
use $ to mark start and end of mathtext latex expression.
see matplotlib mathtex tutorial for more details.
FILES and DIRECTORIES:
roiview/ | main directory
roiview.py | main script
roiviewdata.py | classes and methods
roiviewgtk.py | GUI classes and methods
roiview.glade | GTK interface tree
README.txt | information file
setup.py | setup file for compiling
icons/ | icons directory for GUI
DOC/ | documentation directory
index.html | help pages
formula.html | formula help auxiliary file
roiview.css | style sheet file
gpl-3.0.txt | licence file
IMAGES/ | help pages images
samples/ | sample data directory
SOURCE:
Download the source code and untar it.
Since it's a python code there is no need to compile it but,
you'll need to install python <http://www.python.org/download>
(RoiView was tested with python 2.6 and 2.7)
you might need to modify the first line in the roiview.py code:
#!/usr/bin/env python
to your python environment. or run using:
> python roiview.py <options>
in addition some python modules are needed for running the code:
scipy, numpy, pylab modules. <http://www.scipy.org>
matplotlib module. <http://matplotlib.sourceforge.net>
pygtk gtk modules. <http://www.pygtk.org>
other modules might be needed depending on your python distribution.
If all modules are installed properly only roiview.py and roiviewdata.py are needed
in order to run the basic features of image creation and data values exploration.
roiviewgtk.py roiview.glade and the icons directory are needed in order to load
RoiView's graphical user interface (GUI).
The DOC directory is needed for help files and licence.
COMPILING TO BINARIES:
If one is insisting on compiling RoiView a good method will be to use cx_Freeze.
After installing cx_Freeze and making sure RoiView works, open a command shell and run in main directory:
> python setup.py build
LINUX BINARIES:
Download the binaries tar, untar it to your prefered directory (e.g. /usr/local/bin,
add the directory to your user path. you might need to modify the binary file to enable execution:
> sudo chmod +x roiview
WINDOWS BINARIES:
Download the msi file and run.
A very annoing issue deals with memory.
Since RoiView is using matplotlib and gtk python modules, the visualization
can be very memory consumming and at times very slow.
Sorry, but if you have idias on how to improve this, or report any other issue
or bug, please report to:
ran.nof@gmail.com