RoiView Home at SourceForge.net.
RoiView Help
Help Topics:
Please enable JavaScript in your browser

RoiView - Explore InSAR data and more
Version: 0.75
Created by: Ran Novitsky Nof, 2010 
Web Site: http://roiview.sourceforge.net/
License:


<GPL-v3>


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
<Graphical user Interface image>

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 on toolbar image>

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 image>

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 press disk icon on 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 on toolbar image>

Formula location

<Formula dialog image>

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:
<Color Manager image>

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.
<View options image>

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