updating imageseries developer docs

docs/source/dev/.gitignore

@@ -0,0 +1,2 @@
+# .rst files in here are hand-generated.
+!*.rst

docs/source/dev/imageseries-overview.rst

@@ -0,0 +1,68 @@
+ImageSeries
+------------
+Originally, hexrd could only process GE images. We developed the imageseries
+package to allow for other image formats. The imageseries package provides a
+standard interface for images coming from different sources. The idea is that
+we could be working with a large number of images that we don't want to keep
+in memory. Instead we load the images from a file or generate them dynamically,
+but the interface is independent of the source.
+
+See :ref:`examples` for an example of usage.
+
+**Open and Write.**
+The imageseries package has two main functions: open and save.
+
+.. code-block:: python
+
+    ims = imageseries.open(file, format, **kwargs)
+    imageseries.write(ims, file, format, **kwargs):
+
+The format refers to the source of the images; file and kwargs depend on the
+format. Possible formats currently are:
+
+* ``hdf5`` - the images are stored in an HDF5 file and loaded on demand.
+  ``file`` is the name of the HDF5 file.
+* ``frame-cache`` - the images are stored sparse matrices in a numpy .npz
+  file; all of the sparse arrays are loaded on open, and a full (not sparse)
+  array is delivered on request for a frame. There are two ways this can be
+  done. In one, ``file`` is the name of the npz, and metadata is stored in the
+  npz file. In the other, ``file`` is a YAML file that includes the name of
+  the npz file as well as the metadata.
+* ``image-files`` - the images are stored as one or more regular image files on
+  the file system. ``file`` is a YAML file describing listing a sequence of
+  image files and metadata.
+* ``array`` - images are stored as a 3D numpy array; used for testing.
+
+See also [load options](https://github.com/donald-e-boyce/hexrd/wiki/ims-load-options).
+
+**Processed Imageseries.**
+This is a subclass of imageseries. It has a number of built-in operations, such as flipping, dark subtraction, restriction to a sub-rectangle. It was intended to be further subclassed by adding more operations. It is instantiated with an existing imageseries and a list of operations. When a frame is requested, the processed imageseries gets the frame from the original image series and applies the operations in order. It can then be saved as a regular imageseries and loaded as usual.
+
+For more detail, see [processed imageseries](https://github.com/donald-e-boyce/hexrd/wiki/processed-ims).
+
+**Interface.**
+The imageseries provides a standard interface, somewhat like a 3D array.
+
+If `ims` is an imageseries instance:
+* `len(ims)` is the number of frames
+* `ims[j]` returns the j'th frame
+* `ims.shape` is the shape of each frame
+* `ims.dtype` is the numpy.dtype of each frame
+* `ims.metadata` is a dictionary of metadata
+
+**Stats module.**
+This module delivers pixel by pixel stats on the imageseries. Functions are:
+
+* `max(ims, nframes=0)` gives a single image that is the max over all frames
+* `average(ims, nframes=0)` gives the mean pixel value over all the frames
+* `median(ims, nframes=0)` gives median
+* `percentile(ims, pct, nframes=0)` gives the percentile over all frames
+
+The median is typically used to generate background images, but percentile could also be used too.
+
+**Omega module.**
+For the hexrd work, we usually have a sequence of rotations about the vertical axis. Omega refers to the angle of rotation. The OmegaImageSeries is a subclass that has metadata for the rotation angles.
+
+See [omega](https://github.com/donald-e-boyce/hexrd/wiki/imageseries-omega).
+
+.. include:: imageseries-usage.rst

docs/source/dev/imageseries-usage.rst

@@ -0,0 +1,58 @@
+.. _examples:
+
+Example of Imageseries Usage
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Here is an example of how the imageseries is used. One thing we commonly do is
+to process the raw image files by adding flips and subtract off the background.
+Then we save it as a new imageseries. This example saves it into a HDF5 file,
+but it is more common to use the frame-cache (sparse matrices), which is way
+smaller.
+
+.. code-block:: python
+
+    import numpy as np
+
+    from hexrd import imageseries
+    from hexrd.imageseries.omega import OmegaWedges
+
+    # Inputs
+    DarkFile = 'dark-50pct-100f'
+    H5File = 'example.h5'
+    fname = 'example-images.yml'
+    mypath = '/example'
+
+    # Raw image series: directly from imagefiles
+    imgs = imageseries.open(fname, 'image-files')
+    print "number of frames: ", len(imgs),
+          "\ndtype: ", imgs.dtype,
+          "\nshape: ", imgs.shape
+
+    # Make dark image from first 100 frames
+    pct = 50
+    nf_to_use = 100
+    dark = imageseries.stats.percentile(imgs, pct, nf_to_use)
+    np.save(DarkFile, dark)
+
+
+    # Now, apply the processing options
+    ProcessedIS = imageseries.process.ProcessedImageSeries
+    ops = [('dark', dark), ('flip', 'h')]
+    pimgs = ProcessedIS(imgs, ops)
+
+
+    # Save the processed imageseries in HDF5 format
+    print "writing HDF5 file (may take a while): %s" % H5File
+    imageseries.write(pimgs, H5File, 'hdf5', path=mypath)
+
+Here is the YAML file for the raw image-series.
+
+.. code-block:: yaml
+
+    image-files:
+      directory: GE
+      files: "ti7_*.ge2"
+    options:
+      empty-frames: 0
+      max-frames: 2
+    meta:
+      omega: "! load-numpy-array example-omegas.npy"

docs/source/dev/index.rst

@@ -7,4 +7,4 @@ Contents:
 .. toctree::
    :maxdepth: 1
 
-   imageseries
+   imageseries-overview