[python-dtcwt] 73/497: update docs with information on 3d transform

[Ghislain Vaillant]

This is an automated email from the git hooks/post-receive script.

ghisvail-guest pushed a commit to branch debian/sid
in repository python-dtcwt.

commit a471dfb690bf96268d0ff65a23d92816632e34c5
Author: Rich Wareham <rjw57 at cam.ac.uk>
Date:   Thu Aug 8 19:59:29 2013 +0100

    update docs with information on 3d transform
---
 docs/3d-complex-coeffs.png | Bin 0 -> 749418 bytes
 docs/examples.rst          |   6 ++--
 docs/gettingstarted.rst    |  74 ++++++++++++++++++++++++++++++++++++++++++++-
 docs/index.rst             |   2 +-
 docs/sphere-slice.png      | Bin 0 -> 6382 bytes
 5 files changed, 78 insertions(+), 4 deletions(-)

diff --git a/docs/3d-complex-coeffs.png b/docs/3d-complex-coeffs.png
new file mode 100644
index 0000000..e66bfee
Binary files /dev/null and b/docs/3d-complex-coeffs.png differ
diff --git a/docs/examples.rst b/docs/examples.rst
index ca4e472..7d6c34e 100644
--- a/docs/examples.rst
+++ b/docs/examples.rst
@@ -1,8 +1,10 @@
 Example scripts
 ===============
 
-Showing direcional sensitivity of 3D transform
-----------------------------------------------
+.. _3d-directional-example:
+
+Showing 3D Directional Sensitivity
+----------------------------------
 
 The
 :download:`3d_dtcwt_directionality.py<../examples/3d_dtcwt_directionality.py>`
diff --git a/docs/gettingstarted.rst b/docs/gettingstarted.rst
index f005be2..4532763 100644
--- a/docs/gettingstarted.rst
+++ b/docs/gettingstarted.rst
@@ -31,6 +31,8 @@ Once installed, you are most likely to use one of four functions:
 * :py:func:`dtcwt.dtwaveifm` -- Inverse 1D DT-CWT transform.
 * :py:func:`dtcwt.dtwavexfm2` -- 2D DT-CWT transform.
 * :py:func:`dtcwt.dtwaveifm2` -- Inverse 2D DT-CWT transform.
+* :py:func:`dtcwt.dtwavexfm3` -- 3D DT-CWT transform.
+* :py:func:`dtcwt.dtwaveifm3` -- Inverse 3D DT-CWT transform.
 
 See :doc:`reference` for full details on how to call these functions. We shall
 present some simple usage below.
@@ -121,7 +123,8 @@ wavelet coefficients::
 
     show()
 
-If the library is correctly installed and you also have matplotlib installed, you should see these three figures:
+If the library is correctly installed and you also have matplotlib installed,
+you should see these three figures:
 
 .. figure:: lena-1.png
 
@@ -129,5 +132,74 @@ If the library is correctly installed and you also have matplotlib installed, yo
 
 .. figure:: lena-3.png
 
+3D transform
+------------
+
+In the examples below I assume you've imported pyplot and numpy and, of course,
+the ``dtcwt`` library itself::
+
+    import numpy as np
+    from matplotlib.pyplot import *
+    from dtcwt import *
+
+We can demonstrate the 3D transform by generating a 64x64x64 array which
+contains the image of a sphere::
+
+    GRID_SIZE = 64
+    SPHERE_RAD = int(0.45 * GRID_SIZE) + 0.5
+
+    grid = np.arange(-(GRID_SIZE>>1), GRID_SIZE>>1)
+    X, Y, Z = np.meshgrid(grid, grid, grid)
+    r = np.sqrt(X*X + Y*Y + Z*Z)
+
+    sphere = 0.5 + 0.5 * np.clip(SPHERE_RAD-r, -1, 1)
+
+If we look at the central slice of this image, it looks like a circle::
+
+    imshow(sphere[:,:,GRID_SIZE>>1], interpolation='none', cmap=cm.gray)
+
+.. figure:: sphere-slice.png
+
+Performing the 3 level DT-CWT with the defaul wavelet selection is easy::
+
+    Yl, Yh = dtwavexfm3(sphere, 3)
+
+The function returns the lowest level low pass image and a tuple of complex
+subband coefficients::
+
+    >>> print(Yl.shape)
+    (16, 16, 16)
+    >>> for subbands in Yh:
+    ...     print(subbands.shape)
+    (32, 32, 32, 28)
+    (16, 16, 16, 28)
+    (8, 8, 8, 28)
+
+Performing the inverse transform should result in perfect reconstruction::
+
+    >>> Z = dtwaveifm3(Yl, Yh)
+    >>> print(np.abs(Z - ellipsoid).max()) # Should be < 1e-12
+    8.881784197e-15
+
+If you plot the locations of the large complex coefficients, you can see the
+directional sensitivity of the transform::
+
+    from mpl_toolkits.mplot3d import Axes3D
+
+    figure(figsize=(16,16))
+    nplts = Yh[-1].shape[3]
+    nrows = np.ceil(np.sqrt(nplts))
+    ncols = np.ceil(nplts / nrows)
+    for idx in xrange(Yh[-1].shape[3]):
+        C = np.abs(Yh[-1][:,:,:,idx])
+        ax = gcf().add_subplot(nrows, ncols, idx+1, projection='3d')
+        ax.set_aspect('equal')
+        x,y,z = np.nonzero(C > 2e-1)
+        ax.scatter(x, y, z, c=C[C > 2e-1].ravel())
+        
+For a further directional sensitivity example, see :ref:`3d-directional-example`.
+
+.. figure:: 3d-complex-coeffs.png
+
 .. vim:sw=4:sts=4:et
 
diff --git a/docs/index.rst b/docs/index.rst
index 70f20e2..afe8551 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,7 +1,7 @@
 The dtcwt library
 =================
 
-This library provides support for computing 1D and 2D dual-tree complex wavelet
+This library provides support for computing 1D, 2D and 3D dual-tree complex wavelet
 transforms and their inverse in Python.
 
 The interface is intentionally similar to the existing MATLAB dual-tree complex
diff --git a/docs/sphere-slice.png b/docs/sphere-slice.png
new file mode 100644
index 0000000..ec7903b
Binary files /dev/null and b/docs/sphere-slice.png differ

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/debian-science/packages/python-dtcwt.git