RoiView - Explore InSAR data and more
Version: 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 GUIWhere: 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 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
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: firstname.lastname@example.org