readme.txt

Edge detection in microscopy images using curvelets

****************************************
* CurveletUtils                        
* version: 0.1 (Dec 17, 2007)          
* 	first version
* version: 0.2 (Feb 11, 2008)
*	major changes to EdgeDetect GUI with many options/thresholds to be set
*	extraction of sheets and edges, and measurements of length and area
* 	crvlt_getmagnitude mex file extracts total magnitudes
* version: 0.3 (Jul 2, 2008)
* 	added batch mode to EdgeDetect GUI and CViewer GUI
****************************************

The CurveletUtils package contains MATLAB utilities to use curvelets
and display results in GUIs. 
Developed on Mac OS X with MATLAB (R2008a). Other platforms have
not been tested, but it should work.

The software is free for non-commercial purposes, but see section 5 on
citation information. For commercial use, please contact the address below.

Copyright 2008 Tobias Gebaeck, ETH Zurich
For info, suggestions and bug reports contact: [e-mail]

1. Contents

The CurveletUtils contain three MATLAB GUI:s for visualising and experimenting 
with curvelets:
* cviewer: general tool for thresholding and visualisation of curvelet 
  transformed images, predefined shapes and single curvelets.
* cmoviemaker: a tool to make movies out of several images, applying a curvelet 
  or wavelet transform to each frame.
* edgedetect: a tool for experimenting with the crvlt_extractdirs utility, 
  finding edges in images using the curvelet transform. 

In addition, there are a few useful tools in the utils/ directory, and some 
example programs named crvlt_*.m.


2. Installation

* Download and Install CurveLab (www.curvelet.org) (latest tested
  version is 2.1.2) according to the instructions (including installing
  FFTW ver 2 from www.fftw.org), including the matlab mex-functions
  (write "make matlab" in the CurveLab directory).
* Edit the makefile in the 'src' subdirectory of your CurveletUtils
  directory and set the directories to the proper CurveLab and FFTW
  directories, as well as the path to MATLAB's 'mex' utility.
* Run "make"
* Edit "setpath.m" and set the proper paths to CurveLab and CurveletUtils
* Start MATLAB, change directory to your CurveletUtils directory, and
  type "cviewer" at the prompt to start the CViewer GUI, or
  "edgedetect" to start the EdgeDetect GUI, or start using 
  the other tools.


3. Quick start

3.1 CViewer

To view the reconstruction of an image using only levels 3 and 4 of
the curvelet transform, do the following:

* Start CViewer by writing "cviewer" at the MATLAB command prompt.
* Ensure that the "Display mode" radio button is set to "Image". 
* Click the "Show an image" drop-down list and select "Load
   image...". In the dialog box that appears, browse to the image you
   want to display and click "Open". It is advisable to use an image
   with resolution less than 1000 x 1000 pixels to ensure reasonable
   computation times when trying out the GUI.
* In the "Domain" drop-down next to the bottom image, select
  "Reconstr. - physical space".
* In "Levels to show", select levels 3 and 4 (using Shift to select
  multiple levels).
* Click the "GO!" button. After a while, the reconstructed image will
   appear as the bottom image.


3.2 EdgeDetect

To detect edges in an image using the curvelet-based scheme, do the
following: 

* Start EdgeDetect by writing "edgedetect" at the MATLAB command prompt.
* Select "Open file..." in the "File" menu and select an image
  file. It is advisable to use an image with less than 1000 x 1000
  pixels to ensure reasonable computation times.
* Select for example level 4 in the "Levels" list box.
* Check the "Edges" check box at the bottom.
* The detected edges on the specified level should now show up in
  green. If no edges are shown, try lowering the "Canny thresholds"
  on the left (the left value must be lower than the right value),
  until some edges are seen.


4. Features

4.1 CViewer

CViewer uses the fast discrete curvelet transform with default number
of levels and directions, and with wavelets on the finest level.


4.1.1 Basic features

The CViewer GUI has the following features:

* View single curvelets: Select "single curvelet" in the "Display
  mode" box, select desired levels and directions on the right and click
  "GO!"

* View predefined images and their curvelet transforms: Select a shape
  from the "Show an image" menu, select levels and directions on the
  right, click "GO!", select desired view in "Domain" and "Values"	
  menus, pan and zoom using the tools in the toolbar

* Load images from files: Select "Load image..." from the "Show an
  image" menu, then proceed as above.

* Threshold curvelet coefficients: On the right, select Threshold and
  enter a value in the box to use a fixed threshold, select Number and
  enter the number of the largest coefficients to keep, or select Percentage and
  enter a fraction between 0 and 1 to keep the largest fraction of the nonzero
  coefficients (applied after the level and direction selection). Then
  click "GO!" to apply the extraction.

* Link the axes when zooming: Click the up/down arrow in the toolbar
  to link/unlink the top and bottom axes.

* Show positions of nonzero curvelet coefficients: Select an item in
  "Show curvelet positions" menu (only useful if thresholding is
  applied). Different levels get different colors.

* View directions of curvelets: Click the rightmost image in the
  toolbar, then click on the top axes (when an image is loaded) to see
  the directions and magnitudes of the curvelet coefficients at that	
  point. Select levels on the right. Choose polar/rectangular plot,
  running average, summing across levels at will.

* Export data: click this button to export the current data to the
  main window (in the variable 'cviewdata')

* Show axes in new window: Click "Show in separate window" to 
  open a new figure and show the current plot in that figure. From here
  you can edit, print and export the plot.

* Make movies: Select the menu item "Tools->Make movie..." to open the
  CMovieMaker GUI, which enables you to make a movie out of a series
  of images, showing curvelet reconstructions, errors, wavelet
  reconstructions etc with similar features as above. Choose layout of
  the figure on bottom right, click Preview to see what it looks like,
  and click "Make movie!" to create a movie and save as an AVI-file.


4.1.2 Description of each button/selection in CViewer

4.1.2.1 Buttons / drop-down menus

Display mode: Image/Single curvelet. The "Image" mode lets the user
display an image or shape using the "Show an image" drop down, and
view reconstructions using selected curvelet levels and directions,
and threshold the curvelet coefficients. The "Single curvelet" mode
lets the user select curvelet levels and directions on the right and
view the resulting curvelet image (obtained by setting one
curvelet coefficient in the center of the image on each selected level
and direction to 1, and computing the inverse curvelet transform).

Show an image: This drop-down box lets the user select a pre-defined
shape for display and for viewing its curvelet decomposition. When
selecting "Load image...", a dialog box appears for opening an image
file. Any image format recognized by MATLAB can be opened, but only
gray-scale images and images with one non-zero color channel are
treated correctly (since the curvelet transform only works for one
color channel at a time).

Smooth shapes: Checking this checkbox applies some smoothing to the
shapes selected in the "Show an image" drop-down.

Colormap: provides a set of colormaps for displaying the images.

Invert colormap: when checked, inverts the colormap,
i.e. white-to-black instead of black-to-white for the gray colormap

Show curvelet positions: Selecting one of the options here displays
the position of the active curvelet positions, i.e. the curvelets
selected using the "Levels to show" and "Directions to show" list
boxes, and that pass any applied thresholding. Selecting "Large dots"
or "Small dots" shows every curvelet as a dot, with different color
for different detail levels, while selecting "Scaled arrows" or
"Same-size arrows" shows a small arrow instead, indicating the
direction of the curvelet. The arrow points in the direction of the
short axis of the curvelet in physical space, i.e. in the oscillating
direction. No distinction is made between directions separated by 180
degrees, and only one of these directions is shown.

Levels to show: In this list box one or several detail levels of the
curvelet transform may be selected for inclusion in the reconstructed
image. Use Shift and/or Ctrl/Command to select multiple
levels. Changes appear when the "GO!" button is clicked. Only the
levels that exist in the curvelet transform of the current image are
displayed. 

Directions to show: In this list box, the curvelet directions included
in the reconstruction may be selected, just as for the "Levels to
show" list box. The directions available on the coarsest selected
curvelet level are shown, and curvelets on finer levels with more
directions are included if they belong to a subdivision of the
selected direction. Thus, if levels 2 to 4 are selected, and 16