PyStretch is a public domain license python package for the manipulation and analysis of single and multiband raster data sets. This code was originally designed and implemented to handle large planetary (Mars, Moon) data sets which far exceed the available RAM of a desktop machine. PyStretch maintains the original dataset and copies all of the georeferencing, transformation, and projection information from the source file to the modified destination file. This package can be utilized in two ways, either as an imported module from which developers can leverage the code in their own work, or as a stand alone script accessible via the bin/ directory. For a more detailed description of the package and the capabilities see:
PyStretch depends on:
Optionally, PyStretch can provide basic visualization of the dataset histogram. This requires:
Windows users should use the executable installer, which installs PyStretch into their python site-packages directory and the PyStretcher script into their python script directory.
For more detailed windows installation instructions see:
On all other platforms PyStretch can be installed from the python package index:
$ pip install PyStretch
or:
$ easy_install PyStretch
or from a source distribution with the setup script:
$python setup.py install
Here is a canonical example of performing a linear stretch, dividing the input image into 5 vertical segments:
$ pystretcher.py -l -v 5 <some_input_file>
Here is a canonical example of filtering the input image using a gaussian filter. The image is segmented into 3 horizontal segments:
$ pystretcher.py --gf -t 3 <some_input_file>
Finally, here is a canonical example of performing naive histogram equalization while segmenting the image into rectangles:
$ pystretcher.py -q -v 3 -t 6 <some_input_file>
Note
Reading against the intrinsic block size of the input dataset will cause GDAL to load larger than necessary segments into memory. This will cause memory thrashing which significantly slows the script. Unless absolutely necessary, you should be segmenting horizontally, as most, but not all data formats, utilize some horizontal block size schema.
For those developers who wish to integrate this package into their own code, here is a brief example importing PyStretch modules.
Note
The decision was made to generate empty __init__.py files. This means that from pystretch import *will not function as all = [] has not been defined at the directory level. This decision was made to ensure that imports are explicit and not implicit. Contact the author if this functionality is frustrating and you wish to be able to import using *notation.
For example:
>>> from pystretch.core import ArrayConvert
>>> from pystretch.linear import Linear
>>> from pystretch.plot import Plot
PyStretch is currently implementing canonical unittests. In the interim users are advised to utilize pystretch_test.py located in the bin/ directory for the source or the Scripts/ directory of the windows installation to test the functionality of the image analysis tools on a subset of their data.
pystretch_test.py Usage:
$ pystretch_test.py - srcwin 0 0 500 500 <some_input_file>
where, srcwin is origin x, origin y, width, height in pixel space
or
$ pystretch_test.py - projwin 0 0 0.25 0.25 <some_input_file>
where, projwin is ulx uly lrx lry in map project space
The numpy implementation of ndarray.std(), which calculates the standard deviation, creates an in memory copy of the array. Be aware of this when deciding on image segmentation size. The standard deviation of the image or image segment is only calculated when performing a standard deviation or gaussian stretch. In all other cases this calculation is omitted.
Bugs may be reported and questions asked via https://github.com/jlaura/PyStretch
PyStretch is written by:
With help from:
Major portions of this work were supported by the USGS Astrogeology department.