README

   1 PyPlotSuite README File
   2 =======================
   3
   4 .Copyright and License
   5 *************************************************
   6 Copyright (C) 2006-2007 Antonino Ingargiola <tritemio@gmail.com>
   7
   8 This program is free software; you can redistribute it and/or modify
   9 it under the terms of the GNU General Public License as published by
  10 the Free Software Foundation; either version 2 of the License, or
  11 (at your option) any later version.
  12
  13 This program is distributed in the hope that it will be useful,
  14 but WITHOUT ANY WARRANTY; without even the implied warranty of
  15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16 GNU General Public License for more details.
  17
  18 For more information read the file LICENSE.txt in the source directory.
  19 *************************************************
  20
  21
  22 Project Description
  23 -------------------
  24
  25 *PyPlotSuite* is a set of graphical tools to quick visualize and explore/analyze
  26 monodimentional and bidimensional data. The plot created can be saved in a
  27 variety of image formats to produce publication quality graphs.
  28
  29 At the moment the project is composed by two little stand alone applications:
  30 *ImageAnalyzer* and *Plotfile2*. ImageAnalyzer is focused towards images (or any
  31 2D data, such as arrays) visualization, analysis, and measurement. Plotfile2
  32 focus is towards simple data series visualization, with the possibility to
  33 quick modify many plot characteristics. Both applications can save the result
  34 on a multitude of image file formats (png, eps, jpeg, pdf, and more).
  35
  36 PyPlotSuite is written in python, using the GTK gui toolkit (through the python
  37 binding pygtk, and using Glade-2 to layout the windows). All plots are created
  38 with the great Matplotlib python 2D graphic library. Matplotlib is such a good
  39 tool that the PyPlotSuite applications are only tiny wrapper around Matplotlib
  40 functionality. Also some Numpy functionality are used both through Matplotlib
  41 (which requires Numpy) and both directly.
  42
  43 Home Page::         http://pyplotsuite.sourceforge.net[]
  44 *Latest Version*::  0.1-alpha7
  45
  46
  47 NEWS
  48 ----
  49 0.1-alpha8
  50 ~~~~~~~~~~
  51 * Added multiplatform installer using distutils. Now to install the pyplotsuite
  52   system-wide just do "python setup.py install" form the source tree with
  53   administrative privileges.
  54 * Various bug-fixes thanks to David Trémouilles' bug reports and patches (now
  55   the open dialog remebers the last dir).
  56 * scipy.filters is now only optional to run ImageAnalyzer
  57 * ImageAnalyzer: Allow to change aspect ratio for images in ImageAnalyzer (via
  58   the pixel dimesion dialog)
  59 * ImageAnalyzer: Zemax file format loading fixes and autodetection improvements.
  60
  61
  62 0.1-alpha7
  63 ~~~~~~~~~~
  64 Only Plotfile2 changes in this release. Various speed-up and code optimization, and the support for changing also the color for all line-plot elements.
  65
  66 0.1-alpha6
  67 ~~~~~~~~~~
  68 This is the first version of PyPlotSuite released as a single tarball. It
  69 includes both ImageAnalyzer and Plotfile2.
  70
  71 A new plot property dialog in Plotfile2 allows to change many plot parameters
  72 (line style and width, marker style and size). There's also the GUI for
  73 changing the colors of the various plot elements but this functions is not
  74 implemented in the underlying code yet.
  75
  76
  77 Release Notice
  78 --------------
  79
  80 Early versions of *ImageAnalyzer* and *Plotfile2* were released in separated
  81 tarballs with separated version number. Now they are released together in the
  82 same tarball with the same version number (and I plan to integrate them more).
  83 However they retain separated changelogs, so you can keep track of each
  84 application separately.
  85
  86 Installation
  87 ------------
  88 You can decompress the archive where you want and then execute PyPloSuite in
  89 place, entering the directory and typing:
  90
  91 --------
  92   python imageanalyzer
  93 --------
  94
  95 or
  96
  97 --------
  98   python plotfile2
  99 --------
 100
 101 You can install PyPlotSuite system wide with this command:
 102
 103 --------
 104   python setup.py install
 105 --------
 106
 107
 108 Development Version
 109 -------------------
 110
 111 The development version of *PyPlotSuite* is hosted on a
 112 http://repo.or.cz/w/pyplotsuite.git[git repository]. To download the latest
 113 development version just install http://git.or.cz/[git]
 114 and type:
 115
 116 -------------------
 117   $ git clone ssh://repo.or.cz/srv/git/pyplotsuite.git
 118 -------------------
 119
 120 Now you have a complete working tree of PyPlotSuite to test/hack on. If git
 121 and cogito does not work on your OS (I think only windows is affected) look at
 122 http://bazaar-vcs.org/[bazar] that is multiplatform SCM with a git plugin too.
 123
 124
 125 Requirements
 126 ------------
 127
 128 You must have this software installed in order to be able to run the program:
 129
 130 - Any recent version of Linux, Mac OSX or Windows
 131
 132 - Python 2.4 or newer (2.3 may still work, not tested):
 133     http://www.python.org[]
 134
 135 - PyGTK 2.x:
 136     http://www.pygtk.org/[]
 137
 138 - NumPy (1.0 or newer)
 139     http://numpy.scipy.org/[]
 140
 141 - MatPlotLib (0.87 or newer):
 142     http://matplotlib.sourceforge.net/[]
 143
 144 - SciPy (only the module scipy.ndimage.filters):
 145     http://www.scipy.org/[]
 146
 147 - Python Image Library (PIL):
 148     http://www.pythonware.com/products/pil/[]
 149
 150 NOTE: Typically Numpy is a prerequisite for Matplotlib, so you may have
 151 installed it in bundle with Matplotlib.
 152
 153 NOTE: The Scipy module and the PIL library are a requirement only if you want
 154 to run ImageAnalyzer. Plotfile2 does not requires them.
 155
 156
 157 Image Analyzer
 158 --------------
 159
 160 Name::              Image Analyzer
 161 Description::       A tool to extract and make measures on scientific images.
 162
 163
 164 Description
 165 ~~~~~~~~~~~
 166
 167 ImageAnalyzer is a python[1] program written with the purpose to analyze
 168 scientific images to extract information such dimensions, and to reveal some
 169 subtle features. You can also create and save publication quality figures in a
 170 variety of hard-copy formats (using Matplotlib[5]).
 171
 172 To execute the program type:
 173
 174 -------------
 175   python imageanalyzer
 176 -------------
 177
 178 Remeber to check the software requirement above.
 179
 180
 181 Image formats supported
 182 ~~~~~~~~~~~~~~~~~~~~~~~
 183
 184 All format supported by the PIL[6] library, with the following pixel formats:
 185 - L (Luminance, aka black&white) 8 bit and 14 bit
 186 - RBG(A) with 8bit per channel
 187
 188
 189 Features
 190 ~~~~~~~~
 191
 192 The features currently implemented are:
 193
 194     - Load, zoom and navigate on any RBG(A) or L (Luminance, aka black&white)
 195       images.
 196     - The possibility to choose one of the following 17 interpolation
 197       algorithms:
 198           Bessel, Bicubic, Bilinear, Blackman, Catrom, Gaussian, Hamming,
 199           Hanning, Hermite, Kaiser, Lanczos, Mitchell, Nearest, Quadric, Sinc,
 200           Spline16, Spline36.
 201       The default one is Nearest which is "no interpolation".
 202     - Select one of the 14 color-maps (only for L images).
 203     - Select a dynamic range either numerically and graphically through an
 204       histogram of the image (only for L images).
 205     - Grid on/off, black/white (to match various color-maps).
 206     - Calculate the distance between two points with the option to set the pixel
 207       dimension for the image (x and y separately).
 208     - Plot the pixel-precise profile of an arbitrary number of sections of the
 209       image (only for L images).
 210
 211
 212 ImageAnalyzer TODO
 213 ~~~~~~~~~~~~~~~~~~
 214
 215 To-do list in no particular order:
 216
 217     - Allow to save modified images.
 218     - Allow to save/load plot properties (colormap, interpolation, zoom).
 219       Handle this as explained in Plotfile2 TODO (below).
 220     - Allow to choose font size for title and labels (separately).
 221     - Fix axis apect ratio in histogram window.
 222     - Better handling of failure on file load.
 223     - Use Plotfile2 (instead of the current custom window) to show image
 224       sections.
 225     - More image filtering options.
 226     - Add pixel-value picker tool.
 227     - Peak integration tool (2d integration on an elliptical area).
 228     - Noise removal tools (dithering, noise shaping, 2D matched filter, you
 229       name it! :D)
 230
 231
 232 Plotfile2
 233 ---------
 234
 235 Name::              Plotfile2
 236 Description::       A tool plot 1D data series.
 237
 238
 239 Description
 240 ~~~~~~~~~~~
 241
 242 Plotfile2 is is a python[1] program written with the purpose to quick plot data
 243 series stored in standard ascii text files. Multiple data series can be plotted,
 244 compared and the resulting plot can be saved in a variety of image file formats
 245 with a customizable size and resolution. This feature come particularly handy
 246 if you want to embed your plot in a document and you what size the final image
 247 will have.
 248
 249 Plotfile2 is written using the GTK toolkit[2] and embeds Matplotlib[5] plot
 250 facility.
 251
 252 To execute the program, enter the Plotfile2 dir and type:
 253
 254 --------
 255   python plotfile2
 256 ---------
 257
 258 See also the software requirements above.
 259
 260
 261 Features
 262 ~~~~~~~~
 263
 264 At the moment Plotfile2 can:
 265
 266     - Load one or more data series from a two column (spaces or tab separated)
 267       ascii file. Blank lines (only spaces or tabs) are ignored.
 268     - Detect if there is an header to automatically set axis labels. The header
 269       must be one line with two strings separated by spacing (or tabs). Blank
 270       lines before and after the header are ignored. More than two
 271       space-separated string results in an error.
 272     - Controls to change the X and Y axis range, scale (linear or
 273       log) and  toggle grid.
 274     - Controls to toggle if plot shows points (markers), lines or both.
 275     - Complete customization of plot elements through a dedicated dialog
 276       (line style, marker type, colors, etc...).
 277     - Set the plot title and axis labels
 278     - Set the figure size (both in inches or in cm) and resolution (in dpi).
 279       This is useful to export a plot to be included in a document with a know
 280       size.
 281     - Navigate/explore plots (zoom, un-zoom, pan, etc) thanks to the Matplotlib
 282       NavigationToolbar2 (try to click on the crossed arrows icon and then
 283       click and dragg with the right mouse button).
 284     - Save the plot in a multitude of image formats (png, jpeg, eps, pdf, ...
 285       all the formats supported by Matplotlib). Just click on the floppy icon.
 286
 287
 288 Plotfile2 TODO
 289 ~~~~~~~~~~~~~~
 290
 291 - Possibility to customize plot line style, line color, line width, marker
 292   color, marker size, marker type for each series. *[COMPLETED]*
 293 - Possibility to use spline interpolation (with various orders), and
 294   exponential-spline interpolation '[Work in progress]'.
 295 - Add dialogs to choose an arbitrary color for plot elements in
 296   the "Plot Properties" dialog.
 297 - Allow font size (and if possible) font style change for labels and title.
 298 - Save plots as data (two columns ascii file or csv). This is useful for
 299   new data generated by the interpolation.
 300 - Allow to save and load plot properties associated with a set of data. This
 301   would allow to load a dataset with associated plot style. To maintain the
 302   data in a compatible format this metadata will be saved in a new file with
 303   same name but different extension (f.e. ".plot"). Maybe the file should
 304   be hidden... (in the same dir of the data of course).
 305 - Add basic operators (spectrum, intergrate, differentiate: which make sense?).
 306 - Embed an (optional) [i]python shell.
 307
 308
 309 Plotfile2 Known Problems
 310 ~~~~~~~~~~~~~~~~~~~~~~~~
 311 - When you change figure size and resolution using the dedicated dialog, the
 312   main window may show a scrambled plot (or only an corner of the entire plot).
 313   This is only a visualization issue. Therefore, if you save the file (without
 314   resizing the window!) you will obtain the image file with the correct size
 315   and resolution ready to be included in your documents.
 316
 317 NOTE: If you have any suggestion to solve this problem please contact
 318 mailto:tritemio@gmail.com[me] via mail.
 319
 320
 321 Links
 322 -----
 323
 324 1. *Python*: a dynamic object-oriented programming language.
 325
 326     * http://www.python.org[]
 327
 328
 329 2. *PyGTK*: Python binding for the GTK user interface library.
 330
 331     * http://www.pygtk.org/[]
 332
 333
 334 3. *Numpy*: The fundamental package needed for numerical computing with Python.
 335     It is the successor (and unifier) of all the old projects (Numeric and
 336     Numarray) for python numerical computing.
 337
 338     * http://numpy.scipy.org/[]
 339
 340
 341 4. *SciPy*: Many modules that were not specific to Numpy are gathered under the
 342     broader project SciPy:
 343
 344     * http://numpy.scipy.org/[]
 345
 346
 347 5. *MatPlotLib*: A python 2D plotting library which produces publication quality
 348     figures in a variety of hard-copy formats and interactive environments
 349     across platforms.
 350
 351     * http://matplotlib.sourceforge.net/[]
 352
 353
 354 6. *Python Imaging Library* (PIL).
 355
 356     * http://www.pythonware.com/products/pil/[]
 357
 358
 359
 360 ***********************
 361 The html version of this README was generated from the ASCII file with:
 362
 363 ---------
 364 $ asciidoc -a toc -a icons -a badges README
 365 ---------
 366 ***********************
 367