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 produced 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-alpha7
  50 ~~~~~~~~~~
  51
  52 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.
  53
  54 0.1-alpha6
  55 ~~~~~~~~~~
  56 This is the first version of PyPlotSuite released as a single tarball. It
  57 includes both ImageAnalyzer and Plotfile2.
  58
  59 A new plot property dialog in Plotfile2 allows to change many plot parameters
  60 (line style and width, marker style and size). There's also the GUI for
  61 changing the colors of the various plot elements but this functions is not
  62 implemented in the underlying code yet.
  63
  64
  65 Release Notice
  66 --------------
  67
  68 Early versions of *ImageAnalyzer* and *Plotfile2* were released in separated
  69 tarballs with separated version number. Now they are released together in the
  70 same tarball with the same version number (and I plan to integrate them more).
  71 However they retain separated changelogs, so you can keep track of each
  72 application separately.
  73
  74 The development version of *PyPlotSuite* is hosted on a
  75 http://repo.or.cz/w/pyplotsuite.git[git repository]. To download the latest
  76 (possibly broken) development version just install http://git.or.cz/[git]
  77 and type:
  78
  79 -------------------
  80 $ git clone ssh://repo.or.cz/srv/git/pyplotsuite.git
  81 -------------------
  82
  83 Now you have a complete working version of PyPlotSuite to test/hack on. If git
  84 and cogito does not work on your OS (i.e. windows) look at
  85 http://bazaar-vcs.org/[bazar] that is multiplatform SCM with a git plugin too.
  86
  87
  88 Requirements
  89 ------------
  90
  91 You must have this software installed in order to be able to run the program:
  92
  93 - Any recent version of Linux, Mac OSX or Windows
  94
  95 - Python 2.4 or newer (2.3 may still work, not tested):
  96     http://www.python.org[]
  97
  98 - PyGTK 2.x:
  99     http://www.pygtk.org/[]
 100
 101 - NumPy (1.0 or newer)
 102     http://numpy.scipy.org/[]
 103
 104 - MatPlotLib (0.87 or newer):
 105     http://matplotlib.sourceforge.net/[]
 106
 107 - SciPy (only the module scipy.ndimage.filters):
 108     http://www.scipy.org/[]
 109
 110 - Python Image Library (PIL):
 111     http://www.pythonware.com/products/pil/[]
 112
 113 NOTE: Typically Numpy is a prerequisite for Matplotlib, so you may have
 114 installed it in bundle with Matplotlib.
 115
 116 NOTE: The Scipy module and the PIL library are a requirement only if you want
 117 to run ImageAnalyzer. Plotfile2 does not requires them.
 118
 119
 120 Image Analyzer
 121 --------------
 122
 123 Name::              Image Analyzer
 124 Description::       A tool to extract and make measures on scientific images.
 125
 126
 127 Description
 128 ~~~~~~~~~~~
 129
 130 ImageAnalyzer is a python[1] program written with the purpose to analyze
 131 scientific images to extract information such dimensions, and to reveal some
 132 subtle features. You can also create and save publication quality figures in a
 133 variety of hard-copy formats (using Matplotlib[5]).
 134
 135 To execute the program type:
 136
 137 -------------
 138   python imageanalyzer.py
 139 -------------
 140
 141 Remeber to check the software requirement above.
 142
 143
 144 Image formats supported
 145 ~~~~~~~~~~~~~~~~~~~~~~~
 146
 147 All format supported by the PIL[6] library, with the following pixel formats:
 148 - L (Luminance, aka black&white) 8 bit and 14 bit
 149 - RBG(A) with 8bit per channel
 150
 151
 152 Features
 153 ~~~~~~~~
 154
 155 The features currently implemented are:
 156
 157     - Load, zoom and navigate on any RBG(A) or L (Luminance, aka black&white)
 158       images.
 159     - The possibility to choose one of the following 17 interpolation algorithms:
 160           Bessel, Bicubic, Bilinear, Blackman, Catrom, Gaussian, Hamming,
 161           Hanning, Hermite, Kaiser, Lanczos, Mitchell, Nearest, Quadric, Sinc,
 162           Spline16, Spline36.
 163       The default one is Nearest which is, in a way, "absence of interpolation".
 164     - Select one of the 14 color-maps (only for L images)
 165     - Select a dynamic range either numerically and graphically through an
 166       histogram of the image (only for L images).
 167     - Grid on/off, black/white (to match various color-maps).
 168     - Calculate the distance between two points with the option to set the pixel
 169       dimension for the image (x and y separately).
 170     - Plot the pixel-precise profile of an arbitrary number of sections of the
 171       image (only for L images).
 172
 173
 174 Plotfile2
 175 ---------
 176
 177 Name::              Plotfile2
 178 Description::       A tool plot 1D data series.
 179
 180
 181 Description
 182 ~~~~~~~~~~~
 183
 184 Plotfile2 is is a python[1] program written with the purpose to quick plot data
 185 series stored in standard ascii text files. Multiple data series can be plotted,
 186 compared and the resulting plot can be saved in a variety of image file formats
 187 with a customizable size and resolution. This feature come particularly handy
 188 if you want to embed your plot in a document and you what size the final image
 189 will have.
 190
 191 Plotfile2 is written using the GTK toolkit[2] and embeds Matplotlib[5] plot
 192 facility.
 193
 194 To execute the program, enter the Plotfile2 dir and type:
 195
 196 --------
 197   python plotfile2.py
 198 ---------
 199
 200 See also the software requirements above.
 201
 202
 203 Features
 204 ~~~~~~~~
 205
 206 At the moment Plotfile2 can:
 207
 208     - Load one or more data series from a two column (spaces or tab separated)
 209       ascii file. Blank lines (only spaces or tabs) are ignored.
 210     - Detect if there is an header to automatically set axis labels. The header
 211       must be a line with two strings separated by spacing (or tabs). Blank
 212       lines before and after the header are ignored. More than two
 213       space-separated string results in an error.
 214     - Controls to change the X and Y axis range, scale (linear or log) and
 215       toggle grid.
 216     - Controls to toggle if plot shows points (markers), lines or both.
 217     - Complete customization of plot elements through a dedicated dialog
 218       (line style, marker type, colors).
 219     - Set the plot title and axis labels
 220     - Set the figure size (both in inches or in cm) and resolution (in dpi).
 221       This is useful to export a plot to be included in a document with a know
 222       size.
 223     - Navigate/explore plots (zoom, un-zoom, pan, etc) with the Matplotlib
 224       NavigationToolbar2.
 225     - Save the plot in a multitude of image formats (png, jpeg, eps, pdf, ...
 226       all the formats supported by Matplotlib)
 227
 228
 229 Plotfile2 Roadmap
 230 ~~~~~~~~~~~~~~~~~
 231
 232 - Possibility to customize plot line style, line color, line width, marker
 233   color, marker size, marker type for each series. *[COMPLETED]*
 234 - Possibility to use spline interpolation (with various orders), and
 235   exponential-spline interpolation.
 236
 237
 238 Plotfile2 Known Problems
 239 ~~~~~~~~~~~~~~~~~~~~~~~~
 240 - When you change figure size and resolution using the dedicated dialog, the
 241   main window may show a scrambled plot (or only an corner of the entire plot).
 242   This is only a visualization issue. Therefore, if you save the file (without
 243   resizing the window!) you will obtain the image file with the correct size
 244   and resolution ready to be included in your documents.
 245
 246 NOTE: If you have any suggestion to solve this problem please contact mailto:
 247 tritemio@gmail.com[me] via mail.
 248
 249
 250 Links
 251 -----
 252
 253 1. *Python*: a dynamic object-oriented programming language.
 254
 255     * http://www.python.org[]
 256
 257
 258 2. *PyGTK*: Python binding for the GTK user interface library.
 259
 260     * http://www.pygtk.org/[]
 261
 262
 263 3. *Numpy*: The fundamental package needed for numerical computing with Python.
 264     It is the successor (and unifier) of all the old projects (Numeric and
 265     Numarray) for python numerical computing.
 266
 267     * http://numpy.scipy.org/[]
 268
 269
 270 4. *SciPy*: Many modules that were not specific to Numpy are gathered under the
 271     broader project SciPy:
 272
 273     * http://numpy.scipy.org/[]
 274
 275
 276 5. *MatPlotLib*: A python 2D plotting library which produces publication quality
 277     figures in a variety of hard-copy formats and interactive environments
 278     across platforms.
 279
 280     * http://matplotlib.sourceforge.net/[]
 281
 282
 283 6. *Python Imaging Library* (PIL).
 284
 285     * http://www.pythonware.com/products/pil/[]
 286
 287
 288
 289 ***********************
 290 The html version of this README was generated from the ASCII file with:
 291
 292 ---------
 293 $ asciidoc -a toc -a icons -a badges README
 294 ---------
 295 ***********************
 296