Embed Size (px)
Citation preview
About BeamLab – a Toolbox for New MultiscaleMethodologies
http://www-stat.stanford.edu/~beamlab
Sou Cheng Choi1, David L. Donoho1, Ana Georgina Flesia1,Xiaoming Huo2, Ofer Levi1, Danzhu Shi1
1Stanford University, Stanford, CA 943052Georgia Institute of Technology, Atlanta, GA 30332
October 7, 2002
Abstract
BeamLab is a collection of Matlab functions that have been used by the au-thors and collaborators to implement a variety of computational algorithms relatedto beamlet, curvelet and ridgelet analysis. The library is available free of charge overthe Internet. Versions are provided for Macintosh, UNIX and Windows operatingsystems. Downloading and installation instructions are given here.
BeamLab has around 500 .m files which are documented, indexed and cross-referenced in various ways. In this document we suggest several ways to get startedwhile using BeamLab: (a) trying out a point-and-click browser, which allows a userto interactively select datasets and compute the multiscale transforms; (b) runningvarious demonstrations and (c) browsing the extensive collection of source files, whichare self-documenting.
BeamLab makes available, in one package, all the code to reproduce all thefigures in our recently published articles on beamlets, curvelets, ridgelets. The in-terested reader can inspect the source code to see what algorithms were used, andhow parameters were set in producing our figures, and will then be able to modifythe source codes to produce variations on our results. BeamLab is inspired by thesuccess of WaveLab, which had been developed, in part, because of exhortationsby Jon Claerbout at Stanford. The key philosophy is that computational scientistsshould engage in “really reproducible” research.
This document helps with installation and getting started, as well as describingthe philosophy, limitations and rules of the road for this software.
Acknowledgment of Support. This work was partially supported by NSF DMS0072661 and 0140698, CSE 0085984 (Stanford), and DMS 0140587 (Georgia Tech.), byDARPA, and by various other sponsors.
1
Contents
1 Introduction 3
2 Showcases 32.1 Demos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.2.1 2-D Beamlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42.2.2 3-D Beamlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62.2.3 Digital Curvelet Transform . . . . . . . . . . . . . . . . . . . . . . . 72.2.4 Digital Ridgelet Transform . . . . . . . . . . . . . . . . . . . . . . . 72.2.5 Fast Slant Stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.2.6 Ridgelet Packets . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.3 Summary of Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3 Access and Installation 113.1 Platform-Specific Information . . . . . . . . . . . . . . . . . . . . . . . . . 113.2 Secure SCP Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113.3 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123.4 Pathnames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123.5 Checklists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
3.5.1 UNIX Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123.5.2 Macintosh Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . 143.5.3 PC Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
3.6 Success . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
4 Snooping 154.1 Contents Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164.2 Help for Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174.3 Source Browsing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174.4 Documentation Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
5 Philosophy 185.1 Reproducible Research . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195.2 Freeware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
6 Fine Print 206.1 Dependence on Matlab . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216.2 Registration – BeamLab Registration . . . . . . . . . . . . . . . . . . . . 216.3 Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216.4 Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216.5 No Charge – No Charge for BeamLab Software . . . . . . . . . . . . . . . 216.6 No Warranty – No Warranty on BeamLab software . . . . . . . . . . . . . 226.7 Copyright – BeamLab Copying Permissions . . . . . . . . . . . . . . . . . 226.8 Thanks – Thanks to contributors . . . . . . . . . . . . . . . . . . . . . . . 23
7 Conclusion 23
2
1 Introduction
BeamLab is a library of Matlab routines for beamlet, curvelet and ridgelet analysis.The library is the basis for these multiscale system research pioneered by the authors, andcan be used to reproduce the figures in their published articles, and to recompute for thosefigures with variations in the parameters.
The library is available free of charge over the Internet by SCP and WWW access;instructions are given below. The material is, however, copyrighted, so that advance per-mission is required for any commercial use.
The package can be considered an extension of WaveLab [7, 8, 9]. In fact, the structureof BeamLab is very similar to WaveLab and some functions actually depend on scripts inWaveLab. We believe that by studying these scripts, one can quickly learn the practicalaspects of various multiscale analysis systems.
In this guide we give information which will help readers to access and install thesoftware on their machines and get started in exploring the resources contained in theBeamLab distribution. We also explain the philosophy which underlies our distributionof this software, and some of the fine print associated with the software.
There are other resources for obtaining information about BeamLab. There is a Beam-Lab Architecture guide, which gives details about how BeamLab is constructed and main-tained. We also provide updated electronic version of papers by the authors [1, 2, 3, 4, 5, 6].
The body of software is under continuing development by a team of researchers. Themain aim is research – to develop specific tools for specific goals in adaptive multiresolutionanalysis. We conduct our research with the idea, then we will implement our tools inBeamLab. We believe that the discipline that this software entails makes our research ofa higher quality than otherwise possible.
We welcome your suggestions for further enhancements, and any contributions youmight make.
The rest of this article is organized as follows. In Section 2, a graphical user interfaceprovided by BeamLab is reviewed. In Section 3, we explain how to obtain and install theBeamLab. In Section 4, ways to study the implementation in more details are described.In Section 5, a philosophy that guide this project is described. In Section 6, some miscella-neous issues regarding publishing a software package are addressed. Finally, we make someconcluding marks in Section 7.
2 Showcases
2.1 Demos
The purpose of publishing this software is to give readers the possibility of reproduce whathave been published in the papers by authors. Here is an up-to-date listing of demos inversion 0.200, and the articles to which they correspond:
• DCRTDemo - demo for paper ‘‘Digital Curvelet Transform:
Strategy, Implementation and Experiments" [6]
• BMIADemo - demo for paper "Beamlets and Multiscale Image
3
Analysis" [1].
• BL3DDemo - demo for paper "3D Beamlets" [5].
• DRTDemo - demo for paper "Digital Ridgelet Transform" [3].
• FSSDemo - demo for paper "Fast Slant Stack" [2].
• RPDemo - demo for paper "Ridgelet Packets" [4].
After download and install BeamLab, by following the instruction in Section 3, youcan browse around to see what files BeamLab contains. These demos will tell readerswhat BeamLab can do.
For readers who want to locate the files that are used for demos, the subdirectoryBeamLab/Papers contains several subdirectories; each one of these contains scripts thatwere used to produce figures in published articles.
As new articles are written by members of our group, new subdirectories will be added.Each subdirectory contains a “demo” file (e.g. BMIADemo.m in directory BMIA, BL3DDemo.m
in directory BL3D, and so on). This file generates figures for a corresponding article.When you invoke that file in Matlab by typing its name (without the .m extension)
in the command line, a menu bar will appear on the screen. By mouse-clicking the menubutton Run All Fig, you will see, in sequence, each figure in the corresponding article.As each figure appears in Matlab’s figure window, the command window will containnarrative explaining what you see in the figure window.
2.2 Examples
We strongly recommend obtaining the articles corresponding to these demos, readingthrough them and inspecting the figures in hard-copy form, and then asking yourself ques-tions: what would happen if I changed the parameters in this algorithm. Then delve intothe scripts, creating slightly modified ones that recreate the figures with modified parame-ters.
Most of these papers are available at
http://www-stat.stanford.edu/∼donoho/reports.html.
2.2.1 2-D Beamlets
To illustrate the power of this Graphical User Interface (GUI), we provide a few examples.If you run ‘BMIADemo’ in a Matlab command line, the following window (Figure 1) willpop up.
At the beginning, a large proportion of the figure is empty. By clicking the numbers inthe Figure column, one can reproduce the figure that are used in the paper [1]. For example,if number ‘11’ is clicked in the right bar, the plot in Figure 1 will show. These picturesillustrate how to utilize a new tool — beamlets — to study the roughness of curves. Theslopes of the graphs in the right column are associated with the roughness of the curves inthe left column. More technical details are documented in [1]. Users can exam the source
4
5 1010
20
30
40
50
60Beta Thickness
0 5 100
50
100
150Beta Thickness
0 5 100
100
200
300
400Beta Thickness
Figure 1: A demo window for Beamlets and its application of measuring roughness forcurves.
5
code by clicking the button See Code. If they have knowledge on Matlab programming,they can rerun this algorithm for other curves.
Note that the computing time associated with this paper is long (several hours on a1GHz PC), so the default option of the demo is to prompt the user to download the mat filesnecessary to reproduce the chosen figure from the URL http://www.isye.gatech.edu/ beam-lab/data/. If the user wants to create the figure from scratch, the Compute box should bechecked prior to the selection of the figure.
A workout was also provided to illustrate Beamlet Decorated Partition for other imagesthan “Picasso”. Typing the command ’Beamlets Decorated Partition Demo’, selecting animage on the window (like ‘Daubechies’) and clicking the Draw button will show a Beamletdecorated Partition on that image. The parameters that select the beamlets accepted inthe partition have been fixed in this demo for all figures, but we will provide more flexibilityin new releases of BeamLab.
2.2.2 3-D Beamlets
As another example, if one types ‘BL3DDemo’ in Matlab, a corresponding window willshow. Suppose the Figure 15 in the paper [5] is of interests, one can redo this figure byclicking the number 15 in the Figure window. After a few seconds of computing, theFigure 2 will appear.
Figure 2: Some examples of 3-D beamlets.
These are some 3D beamlets. Suppose we want to see how they are generated, we can
6
click the button See Code. A new window will pop up with the function Beamlet3Dfig15.m
in. This is the script that is used to generate the above figure. After examining all theinteresting figures, users can close the demo by clicking the button Close All.
2.2.3 Digital Curvelet Transform
We have included a preliminary version of Digital Curvelets written by Dave Donoho on1998. This version of Curvelets was described on a technical report written by DaveDonoho and Marc Duncan [6] on 1999. The code is a little outdated, since it is based ona old ridgelets code, but it still illustrates the point that curvelets can be discretized andcodified, preserving most of its nice theoretical qualities. The curvelets demo is still underconstruction, but a pick of it has been included in the current release. Typing ‘DCTdemo’in the command promt and selecting 4 or 5 it will show a description of the Analysis andSynthesis of the figure BigMac, as shown in the left and right panels of Figure 3.
Ridgelet Coeff, s=3Bandpass, s=3 Partitioned, s=3
Ridgelet Coeff, s=2Bandpass, s=2 Ridgelet Coeff, s=2
Bandpass, s=1
(a) Curvelet Analysis of Bigmac
Ridgelet Coeff, s=3 Squares, s=3
Ridgelet Coeff, s=2 Squares, s=2 Recon, s=2
Recon, s=3
Overall Recon
Recon, s=1
(b) Curvelet Synthesis of Bigmac
Figure 3: An example of digital curvelet transform of the Bigmac image.
2.2.4 Digital Ridgelet Transform
For someone who is interested in studying digital ridgelet transform, the demo ‘DRTDemo’is written for this purpose. Orthonormal ridgelets can be shown by selecting the number8 on the left side of the Demo window. The user can choose to load the data to reproducethe figure or to compute the transform by checking the box Compute. Several wait barswill appear while computing each of the panels of the figure.
Some of the figures in this demo are computational expensive, so we recomend to loadthe data while exploring the figures for the first time.
2.2.5 Fast Slant Stack
The Figure 5 is to illustrate the idea of shearing that is reported in the paper [2]. It canbe evoked by typing FSSDemo in Matlab.
7
Figure 4: Several ortho-ridgelets.
Figure 5: An illustration of a method that is used in the paper about Fast Slant Stack [2].
8
Several workouts have also been devised for the illustration of the Slant Stack construc-tion, and may be run by typing guiparFSSFig1 to
guiparFSSFig4 in the command prompt of Matlab.
2.2.6 Ridgelet Packets
In paper [4], Ridgelet Packets are introduced. A key idea is to implement a repartition inthe Fourier domain. Figure 6 provides a graphical illustration. This is part of RPDemo.
Disc
Figure 6: A new way to partition in the Fourier domain. A figure that is used in the paper[4].
The Figure 7 shows some results by running the algorithm that is reported in [4], witha fixed type of entropy, taking several values. A workout was written to allow the user toexplore all the parameters of the Ridgelet Packets algorithm provided in BeamLab, whichcan be called by typing BestPartitionDemo in the command line. The Figure 8 showsan example of the Gui from this demo.
2.3 Summary of Examples
The purpose of showing these figures is to demonstrate the functionality of the interface.Due to the limit of space, we choose not to get into details. The ability of reproducingall of these figures that is made available by this software package is the emphasis of ourdescription.
9
Entropy = 31 Entropy = 40
Entropy = 29 Entropy = 35
Figure 7: Results of running an algorithm of Ridgelet Packets [4] with different algorithmicparameters.
Figure 8: Results of running BestPartitionDemo on Phone.
10
3 Access and Installation
The BeamLab library contains .m files (Matlab code), .mex files (compiled dynami-cally loadable code), datasets, documentation, scripts and workouts (both also .m files) forreproducing the figures in articles by the authors.
The whole library consists of over 500 files and 50 subdirectories. It requires more than16 Mb on disk once it is downloaded, decompressed and installed and takes up possibly upto 180 Mb disk space for output data. We recommends running the system on a machinewith a minimum of 64 Mb RAM.
This documentation refers to Version 0.200 of BeamLab.
3.1 Platform-Specific Information
BeamLab is available for use in Matlab 5.X and 6.X on three different platforms: MS-Windows (NT 5.0, 98, 2000), UNIX and Macintosh. The package is made available asa compressed .zip archive. By and large the versions are the same, with the followingdifferences:
• .mex files (i.e. dynamically loaded compiled algorithms) are different on differentplatforms. Since the Unix version of BeamLab can run on as many as seven differenthardware platforms, Unix users will compile their .mex files as part of the installationprocess.
• Pathname conventions are different on different platforms. This only affects the fileBeamPath.m.
Other than this, the code is the same across platforms. By accessing the version foryour platform, you never have to know about all this.
You do have to know about one convention used in the documentation. We always usethe UNIX pathname conventions rather than PC or Macintosh, e.g. Matlab/Toolbox/BeamLab/rather than matlab\toolbox\beamlab or Matlab:Toolbox:BeamLab. You have to trans-late what we say into the version appropriate for your platform.
3.2 Secure SCP Access
The archives may be accessed by scp to the user account beamlab on the host
rgmiller.stanford.edu
The filename is:
beamlab200.zip
When a new version becomes available, the file name will be update accordingly.
11
3.3 Installation
In this section we first describe the installation process in narrative form, and later give astep-by-step checklist.
Once the appropriate compressed archive has been transferred to your machine, it shouldbe decompressed and installed. On a PC you will need WinZip to do this; on a Mac, Stuffit,; and on UNIX, unzip.
On a personal computer (Macintosh or Windows), the archives should be decompressedand installed as a subdirectory of the Toolbox directory inside the matlab folder. Ona UNIX workstation or server, the archives could either be installed in the system-widematlab directory, if you have permission to do this, or in your own personal matlab direc-tory, if not.
Once the actual files are installed, you should have a number of files and subdirectoriesin the directory BeamLab/. If you look in the files Contents.m inside of the BeamLab/
directory, you will see a plan of what is inside.Make an actual directory listing to see if your hard disk actually has these files and
subdirectories.
3.4 Pathnames
Matlab can automatically, at startup time, make all the BeamLab software available.The script BeamPath.m is provided as part of BeamLab to enable this feature. It shouldbe invoked from the user’s startup.m file.
PC startup.m is located in the matlab/toolbox/local directory on MS-Windows. In-sert the line BeamPath in that file, and put a copy of BeamPath.m in that directory.
Mac startup.m may be located anywhere inside the Matlab directory on Macintosh. Insertthe line BeamPath in that file. Since BeamLab contains a startup.m file, if you haveno other startup.m file, there is nothing to do once BeamLab is installed.
Unix This file is located in the matlab subdirectory of your home directory on UNIX. Ifyou don’t have such a subdirectory, use mkdir ∼/matlab to make one. Create afile named startup.m and insert the line BeamPath in that file. Then put a copy ofBeamPath.m in that directory.
Check the file BeamPath.m in the BeamLab/ main directory, and edit it to reflect theactual pathname situation on your computer, e.g. the full pathname of the directory whereBeamLab actually resides, etc.
3.5 Checklists
To reinforce the above points, we furnish here step-by-step installation checklists.
3.5.1 UNIX Checklist
1. Binary download the archive to the directory you want BeamLab to reside.
12
2. Uncompress the archive: unzip BeamLab200.zip
3. Decide where you want the BeamLab directory to reside. It will have a number ofsubdirectories and occupy at least 16 Mb MB disk space.
4. After you unzip the file for your machine, you should have the following directorystructure:
BeamLab200
BeamLab200/Beamlets
BeamLab200/Beamlets/Beamlet2D
BeamLab200/Beamlets/Beamlet3D
BeamLab200/Browsers
BeamLab200/Datasets
BeamLab200/MexSource
BeamLab200/Papers
BeamLab200/Papers/BMIAPaper
BeamLab200/Papers/RidgePaper
BeamLab200/Papers/SlantPaper
BeamLab200/Ridgelets
BeamLab200/SlantStack
BeamLab200/Utilities
5. Edit the file BeamPath.m, put the lines
if strcmp(Friend,’<YourMachineType>’),
WAVELABPATH =’<AbsolutePathNameforBeamLabMainDirectory>’ ;
PATHNAMESEPARATOR = ’<YourMachine*sPathSeparator>’;
end
in the appropriate place (this will be evident). Here Friend has been predefined bythe Matlab command Friend = computer;
6. In the matlab subdirectory of your home directory, put a copy of the files startup.mand BeamPath.m, both from the BeamLab/ directory.
7. cd to BeamLab/MEXSource
8. Type installMEX to compile and install the .mex files. If you have an older ver-sion of MATLAB, this command may yield compilation errors; in this case try “in-stallMEX.old” instead.
Trouble-Shooting UNIX: Compare the output of ls -r BeamLab with Documentation/WLFiles
to see if you have all the files. Compare the output of the Matlab command path withthe list above to see if you have all the directories in your path.
13
3.5.2 Macintosh Checklist
1. Binary Download the file BeamLab200.sea.hqx to your Macintosh.
2. un-BinHex the file, creating a self-extracting archive BeamLab200.sea.
3. Double-click on the self-extracting archive and install it in the Toolbox folder of yourMatlab folder.
4. Using Find File from the Mac Finder, determine if you have any files named startup.m
(besides the one contained in BeamLab/) in the hierarchy rooted at Matlab. If youdon’t, skip to step 6.
5. If you do have more than one startup.m file, copy the contents of the startup.m inMatlab/Toolbox/BeamLab to the startup.m, and rename the one in Matlab/Toolbox/BeamLab.
6. Edit BeamPath.m if your Matlab directory has a different pathname reference thanthe one supplied at the top of this file.
3.5.3 PC Checklist
1. Binary download the file beamlab200.zip to your PC.
2. cd to your toolbox folder in the matlab folder.
3. pkunzip -d <PREFIX>wlab200.zip, where <PREFIX> is the prefix making <PREFIX>wlab200.zipan absolute pathname reference.
After you unzip you should have the following subdirectory structure:
beamlab beamlab\browsers\one-d beamlab\cont beamlab\datasets
beamlab\denoise beamlab\doc beamlab\fastalg beamlab\interp
beamlab\meyer beamlab\ortho beamlab\packets beamlab\packets2
beamlab\papers beamlab\papers\adapt beamlab\papers\asymp
beamlab\papers\blocky beamlab\papers\ideal beamlab\papers\mentseg
beamlab\papers\shortcrs beamlab\papers\spincycl
beamlab\papers\tour beamlab\papers\vdl beamlab\pursuit
beamlab\station beamlab\symm beamlab\util beamlab\wigner
beamlab\workouts beamlab\workouts\bob beamlab\workouts\mp
beamlab\workouts\multfrac beamlab\workouts\toons
4. copy c:\matlab\toolbox\beamlab\wlpath.mc:\ matlab\bin
5. Create a startup file in c:\matlab\bin which runs wavepath at startup time.
6. (Alternate Steps 4-5) Edit matlabrc.m to insert in the path all the directories refer-enced in wavepath.m.
Trouble-Shooting DOS: To check that you have every file that you should, look atdoc\wlfiles.txt; see if everything is there! Check that while in Matlab, the path
function returns a list that looks like the one under item 3 above.
14
3.6 Success
When you have a successful installation, you should see something like the following whenyou invoke Matlab:
Welcome to BeamLab v 200
Setting Global Variables:
global MATLABVERSION = 6
global BEAMLABVERSION = 200
global BEAMLABPATH = D:\matlabR12\toolbox\BeamLab200\
global PATHNAMESEPARATOR = "\"
global PREFERIMAGEGRAPHICS = 1
BeamLab 200 Setup Complete
Currently available browsers for figures from the following
papers:
DCRTDemo - demo for paper ‘‘Digital Curvelet Transform:
Strategy, Implementation and Experiments"
BMIADemo - new demo for paper "Beamlets and Multiscale Image
Analysis."
BL3DDemo - demo for paper "3D Beamlets."
DRTDemo - demo for paper "Digital Ridgelet Transform"
FSSDemo - demo for paper "Fast Slant Stack"
RPDemo - demo for paper "Ridgelet Packets"
For more information, please visit:
http://www-stat.stanford.edu/~beamlab
Please ignore the following message if WaveLab has been installed.
There are BeamLab functions which call WaveLab functions.
Recommend download WaveLab from
http://www-stat.stanford.edu/~wavelab
and install to
D:\MATLABR12\toolbox
4 Snooping
If you just snoop around in the BeamLab file structure, you will notice many directoriesand a great range of different information about the system itself and what it can do. Welist here some basic facts.
15
4.1 Contents Files
Each directory has a Contents.m file, which explains the contents and purpose of thatdirectory. The directory SlantStack contains the central wavelet transform tools; itsContents.m file looks as follows:
% SlantStack: Contents v.200 -- Digital Radon Transform
%
% The routines in this directory perform digital radon transforms
% and associated functions (e.g. ridgelet transforms). Some
% of these tools and examples require Wavelab .80X to run properly.
%
%
% Fast Radon Transforms
%
% FastSlantStack - Digital Radon Transform
% Inv_FastSlantStack - Inverse Radon Transform
% Adj_FastSlantStack - Adjoint Radon Transform
%
% Slow Radon Transform
%
% SlowSlantStack - Digital Radon Transform
% Inv_SlowSlantStack - Inverse Radon Transform
% Adj_SlowSlantStack - Adjoint Radon Transform
%
% Pseudopolar FFT
%
% PseudopolarFFT - Fast, Pseudopolar FFT
% Inv_PseudopolarFFT - Inverse Pseudopolar FFT
% Adj_PseudopolarFFT - Adjoint Pseudopolar FFT
%
% Support for Pseudopolar FFT (PPFT)
%
% PtP - Gram operator of PPFFT
% Inv_PtP - Inverse Gram Operator
% PrecondPPFT - Preconditioner for PPFT
%
% Ridgelet Transform
%
% FastRidgeletTransform - Digital Ridgelet Transform
% Inv_FastRidgeletTransform - Inverse Ridgelet Transform
% Adj_FastRidgeletTransform - Adjoint Ridgelet Transform
% FastOrthoRidgeTransform - Ortho Ridgelet Transform
% Inv_FastOrthoRidgeTrans - Inverse Fast Ortho Ridgelet
% Transform
%
% Utilities Supporting all This
16
%
% FractionalFFT_mid0 - centered Fractional FFT
% fft_mid0 - centered fft
% ifft_mid0 - centered ifft
% fftshift1d - fftshift on columns
% Shift1dSignal - interpolate 1d signal
% UFWT_CDJV - unpreconditioned boundary wavelet
% analysis
% UIWT_CDJV - unpreconditioned boundary wavelet
% synthesis
%
4.2 Help for Functions
Each function in BeamLab has help documentation. For example, FastSlantStack is abasic transform routine in BeamLab. If you are in Matlab and type help FastSlantStack,Matlab will type out the following documentation:
FastSlantStack: Radon Transform for Discrete Data
Usage:
S = FastSlantStack(X)
Inputs:
X n*n matrix (x,y)
Outputs:
S 2n*2n matrix (t,theta)
Description:
Sums array along lines.
4.3 Source Browsing
Most of the algorithms in BeamLab are available for inspection – inluding some of thosethat are actually implemented by fast complied C code as .mex files. For example, if youare in Matlab and type type FastSlantStack you get the following documentation:
function S = FastSlantStack(X)
% FastSlantStack: Radon Transform for Discrete Data
% Usage:
% S = FastSlantStack(X)
% Inputs:
% X n*n matrix (x,y)
% Outputs:
% S 2n*2n matrix (t,theta)
% Description:
% Sums array along lines.
%
Pre = 0; % No preconditioning
17
P = PseudopolarFFT(X,Pre).’;
P = fftshift1d(P);
S = fftshift1d(ifft(P));
%
% Copyright (c) 2000. Amir Averbuch and David Donoho
%
%
% Part of BeamLab Version: 200
% Built:Thursday,14-June-2002 00:00:00
% This is Copyrighted Material
% For Copying permissions see COPYING.m
% Comments? e-mail [email protected]
%
Notice that the source contains information about the author and date of compilation,as well as copyright of the routine. Also, the help information is built in as the first thingfollowing the function header. Notice also that the wavelet transform routine depends onother routines, such as DownDyadHi and dyad, which are also part of BeamLab and canalso be inspected at source level.
4.4 Documentation Directory
The BeamLab system also has extensive built-in documentation about the system itself.If you look in the directory Documentation, you will find several files of general interest:
ADDINGNEWFEATURES - How to Add New Features to BeamLab
BUGREPORT - How to report bugs about BeamLab
COPYING - BeamLab Copying Permissions
DATASTRUCTURES - Basic data structures in BeamLab
FEEDBACK - Give feedback about BeamLab
GETTINGSTARTED - Ideas for getting started with BeamLab
INSTALLATION - Installation of BeamLab
LIMITATIONS - BeamLab known limitations
PAYMENT - No Charge for BeamLab Software
REGISTRATION - BeamLab Registration
SUPPORT - BeamLab Support
THANKS - Thanks to contributors
VERSION - Part of BeamLab Version v200
WARRANTY - No Warranty on BeamLab software
5 Philosophy
We briefly describe in this section some underlying philosophical ideas which have guidedus in the construction of this software library. The content of this section also was includedin [9]
18
5.1 Reproducible Research
Jon Claerbout, a distinguished exploration geophysicist at Stanford, has in recent yearschampioned the concept of really reproducible research in the “Computational Sciences.”
The “Computational Sciences” he has in mind are fields in which mathematical andcomputer science heuristics may suggest algorithms to be tried on scientific signal processingand imaging problems, but mathematical analysis alone is not able to predict fully thebehavior and suitability of algorithms for specific datasets. Therefore experiments arenecessary and such experiments ought, in principle, to be reproducible, just as experimentsin other fields of science.
Some background information may help the reader. Suppose we are working in an arealike exploration seismology where the goal is an image of the sub-surface, and computationalscience aims to produce better images. However, the deliverable is not an image itself, butinstead the software environment that, applied in the right way, produces the image, andwhich, hopefully, could be applied to other datasets to produce equally nice images. Thescientific findings may turn out to be a knowledge of parameter settings for this complexsoftware environment that seem to lead to good results on real datasets.
With this as background, reproducibility of experiments requires having the completesoftware environment available in other laboratories and the full source code available forinspection, modification, and application under varied parameter settings.
Reducing this to a slogan: An article about computational science in a scientific pub-lication is not the scholarship itself, it is merely advertising of the scholarship. Theactual scholarship is the complete software development environment and the complete setof instructions which generated the figures.
The advantage of reproducibility for the progress of the discipline is clear. When a reallygood idea is found, everyone else can be using it right away. When a mistaken finding isreported, it is rooted out almost immediately, etc.
The barriers to sharing complete software environments are also clear: if you are thedeveloper of a nice piece of software, you may not want to give other people the benefitof your investment of time simply for the benefit of an abstract principle such as scientificprogress. Even if you are altruistic enough to make your work available to others in thisway, it’s a lot of extra work to generate code clean enough for others to look at; most peopleprefer to make the figures for their articles using quick-and-dirty undocumented code, andmove on to the next project.
Claerbout and his colleagues have developed a discipline for building their own soft-ware, so that from the start, they expect it to be made available to others as part of thepublication of their work. Specifically, they publish CD-ROMs (available from StanfordUniversity Press) which contain the text of their books along with a special viewer thatmakes those books interactive documents, where as one reads the document, each figureis accompanied by the possibility of pop-up windows which allow one to interact with thecode that generated the figure, to “burn” the illustration (i.e., erase the postscript file sup-plied with the distribution), and to rebuild the figure from scratch on one’s own machine.By following the discipline of planning to publish in this way from the beginning, theymaintain all their work in a form which is easy to make available to others at any point intime.
The idea of reproducible research has been well known in the wavelet community, even
19
though we are not sure that many people are actively following it. WaveLab is an incar-nation of this principle. It is our perception that as we approach specific applicationsusing wavelets, we are becoming a computational science like seismic imaging. Argu-ments over data compression have everything to do with specifics: exactly what was done(which wavelets, which coders, which corpus of data was compressed) with exactly whatparameters. In this setting, publishing figures or results without the complete software en-vironment could be compared to publishing an announcement of a mathematical theoremwithout giving the proof.
With Internet facilities and the standardization of scientific computing on about fivemachine architectures, it becomes feasible to actually experiment with protocols implement-ing the goal of reproducible research. We may forget that in other sciences, the canonicalform for scientific articles was arrived at incrementally. For example, it has been said thatPasteur introduced the notion of publishing a full description of methods, materials andlaboratory procedures.
5.2 Freeware
Richard Stallman and others associated with the GNU project have pioneered the idea offree software – software that can freely be redistributed by users. (This does not mean freeof cost; it means the rights any one person has over the software are the same as those ofany other). We have been influenced by this, but obviously cannot completely follow themsince we require of users that they have Matlab, which is not freely re-distributable.
In our opinion, the Freeware concept is useful and has had a major impact. However, theFreeware concept has limits, and the Matlab example shows this clearly. Modern scien-tific computing depends on quantitative programming environments like Matlab, S-Plus,Mathematica, X-Math, IDL and so on. These are widely available, widely understoodhigh-level languages in which key concepts of scientific discourse (Fast Fourier Transform,etc.) are available as built-in, easily usable features. At the moment, a complete Freewareimplementation of one’s computational experiments requires, more or less, emulating JonClaerbout’s example and writing all one’s tools from scratch in C or Fortran. Claerboutis forced to do this because of the massive size of the datasets he uses, which exceed thebounds of Matlab or other QPE’s. Most working scientists have smaller-scale datasetsthan Claerbout, and so they can use modern QPE’s. Moreover they are busy, and viewscientific computing only as a sideshow. They cannot be expected to start from scratch anddevelop all their code in C when they can get, much more quickly and reliably, the sameresults in a very high-level language. Thus the temptation to work in a QPE is almostirresistible.
Nowadays, the use of high-level language for prototyping is well accepted by both the re-search community and in industrial development. For example, in Digital Signal Processing(DSP), workers are constantly using MatLab to experiment on new methodologies.
6 Fine Print
In making available our software, the authors have tried to follow some simple guidelines.We spell them out in this section to avoid misunderstandings about what we are offering,
20
why we are offering it, what rights we give you, and what rights we retain for ourselves.Some useful files have been included in the directory BeamLab/Documentation. For a
list of the file names, please see Section 4.4.These files describe the philosophy and limitations of our package. The key points are
summarized here, by reprinting the contents of some of those files in BeamLab.
6.1 Dependence on Matlab
Matlab is a product of The Mathworks, a successful company based in Natick, Massa-chusetts. You need to get MatLab before installing BeamLab.
6.2 Registration – BeamLab Registration
Please Register yourself as a user of BeamLab so that we can send you e-mail aboutupgrades and enhancements. To Register: e-mail
[email protected] with the subject line “registration.” If you like,please include information about the version of Matlab you are using and about the typeof machines you are using.
6.3 Limitations
This package has been designed to reproduce the figures in our research. Accordingly, itmay not solve the problems you have in mind. Please see the file LIMITATIONS.m beforecomplaining. Perhaps we are already aware of the problem you have and are seeking to fixit!
6.4 Support
This software has been developed as part of the research effort of the authors under variousfederally supported grants. If you find that it does not work correctly, please e-mail a noti-fication of your problem to BeamLab. Use the format indicated in the file BUGREPORTS.m.
To the extent that we can isolate the problem and develop a solution, and to the extentthat it fits in with our schedule with releasing a new version, we will attempt to fix theproblem.
6.5 No Charge – No Charge for BeamLab Software
BeamLab software is available at NO CHARGE. It is available for download at
http://www-stat.stanford.edu/∼beamlab
The software is copyrighted. For permissions to copy, see the file COPYING.m or youmay e-mail [email protected]. If you use this software to produce scientificarticles, we would appreciate being informed of the article’s title, authors, topic, and placeof appearance. If this software played a major enabling role in your scientific work, andyou are so moved, you might acknowledge us in your article.
21
6.6 No Warranty – No Warranty on BeamLab software
There is no warranty attached to the BeamLab software.If you find that it does not work correctly, use the file BUGREPORTS.m as a template to
compile a description of the problem, including as far as possible a complete m-file scriptthat generates the error. E-mail the description to: [email protected] permitting, an effort will be made to correct the problem for a future release.
FORMAL LEGAL DISCLAIMER OF WARRANTYWe make no warranties, explicit or implicit, that the programs contained in this collec-
tion are free of error, or are consistent with any particular standard of accuracy, or thatthey will meet your requirements for any particular application. They should not be re-lied on for any purpose where incorrect results could result in loss of property or personalinjury. If you do use programs for any such purpose it is at your own risk. The authorsdisclaim all liability of any kind, either direct or consequential, resulting from your use ofthese programs.
6.7 Copyright – BeamLab Copying Permissions
This software was developed with supports of the National Science Foundation, DARPA,and various other sponsors. Contributors to this effort include all the coauthors, togetherwith many others, whom due to the limit of space, can not be enumerated here.
In EVERY case, the software is COPYRIGHTED by the original author. For permis-sions, e-mail [email protected].
COPYLEFT NOTICEPermission is granted to make and distribute verbatim copies of this entire software
package, provided that all files, directories, and subdirectories are copied together as aunit.
Here copying as a unit means: all the files listed in the file WLFiles are copied, so thatamong other things the THANKS.m notice, and this permission notice accompany all copiesof the full software, and every “.m” file continues to contain a copy of the file VERSION.m
inside it.Permission is granted to make and distribute modified copies of this software, under
the conditions for verbatim copying, provided that the entire resulting derived work isdistributed under the terms of a permission notice identical to this one. Names of newauthors, their affiliations and information about their improvements may be added to thefiles COPYING.m and THANKS.m.
The purpose of this permission notice is to allow you to make copies of the softwareand distribute them to others subject to the constraint that you maintain the collectionof tools here as a unit. This enables people to whom you give the software to be aware ofits origins, to ask questions of us by e-mail, to request improvements, obtain later releases,etc.
If you seek permission to copy and distribute translations of this software into anotherlanguage, please e-mail a specific request to [email protected]. If you seek
22
permission to excerpt a part of the software library for example to appear in a scientificpublication, please e-mail a specific request to [email protected].
6.8 Thanks – Thanks to contributors
This software was developed with support of the US National Science Foundation andDARPA. Contributors to this software include Achi Brandt, Weizmann Institute of Science;Amir Averbuch, Tel Aviv University; Emmanuel Candes, California Institute of Technol-ogy; Scott S. Chen; Raphy Coifman, Yale University; Davi Geiger, New York University;David Horn, Tel Aviv University; Hiroshi Ishikawa, New York University; Ian Jermyn, NewYork University; Peter Jones, Yale University; Gilad Lerman, New York University; FrankNatterer, University of Muenster; Michael Saunders, Stanford University; Stephen Semmes,Rice University; Boaz Shaanan, Hebrew University; Yoel Shkolnisk; Jean-Luc Starck, Cen-tre dEtudes Nucleaires de Saclay (CENS); Arne Stoschek; Martin Vetterli, Swiss FederalInstitute of Technology; and Leonid Yaroslavsky, Tel Aviv University. We also thank thefollowing institutions for their hospitality during the pursuit of our work: Sacklet Institute,Tel Aviv University; Mathematics and Computer Science Department, Tel Aviv University;and Mortimer and Raymond Sackler Institute of Advanced Studies at Tel Aviv University.
Further contributions are welcome, for info e-mail [email protected].
7 Conclusion
BeamLab is a toolbox, which allows users to reproduce computational results that areused in papers by authors and their collaborators. With adequate knowledge on MatLablanguage, users can rerun most of the experiments with variations of algorithmic parame-ters. BeamLab provides a graphical user interface, which gives users an easy way to locaterelated functions and scripts. For researchers who want to study recent developments inmultiscale analysis, BeamLab provides a valuable tool.
References
[1] D. Donoho and X. Huo (2001). “Beamlets and Multiscale Image Processing.” In Multi-scale and Multiresolution Methods. Eds T.J. Barth, T. Chan, and R. Haimes, SpringerLecture Notes in Computational Science and Engineering, Vol. 20, pp. 149-196.
[2] A. Averbuch, R. Coifman, D. Donoho, M. Israeli and J. Walden (2001). “Fast SlantStack: A notion of Radon Transform for data on a Cartesian grid which is Rapidly Com-putable,Algebraically Exact, Geometrically Faithful, and Invertible.” Technical Report,Department of Statistics, Stanford University, Stanford, CA 94305. May.
[3] D. Donoho and A. Flesia (2001). “Digital Ridgelet Transform Based on True RidgeFunctions.” Technical Report, Department of Statistics, Stanford University, Stanford,CA 94305. To appear in Beyond Wavelets. J. Stoeckler and G. Welland (Eds). AcademicPress, December.
23
[4] A. Flesia, H. Hel-Or, A. Averbuch, E. Candes, R. Coifman, D. Donoho, (2002). “Dig-ital Implementation of Ridgelet Packets.” Technical Report, Department of Statistics,Stanford University, Stanford, CA 94305. To appear in Beyond Wavelets. J. Stoecklerand G. Welland (Eds). Academic Press, December.
[5] D. Donoho and O. Levi (2002). “Fast X-Ray and Beamlet Transforms for Three-Dimensional Data.” Technical Report, Department of Statistics, Stanford University,Stanford, CA 94305. March. In Modern Signal Processing, D. Rockmore and D. Healy,eds., Mathematical Sciences Research Institute Publications, Cambridge UniversityPress. To appear.
[6] D. Donoho and M.R. Duncan (2000). “Digital Curvelet Transform: Strategy, Implemen-tation, Experiments.” Technical Report, Department of Statistics, Stanford University,Stanford, CA 94305. March.
[7] J.B. Buckheit and D.L. Donoho (1995). “WaveLab Architecture.”http://www-stat.stanford.edu/∼wavelab/WaveLabArch.ps.
[8] J.B. Buckheit, S. Chen, D.L. Donoho, I.M. Johnstone, and J.D. Scargle (1995). “Wave-Lab Reference Manual.”http://www-stat.stanford.edu/∼wavelab/WaveLabRef.ps.
[9] J.B. Buckheit, and D.L. Donoho (1995). “WaveLab and Reproducible Research.” InA. Antoniadis and G. Oppenheim (Eds.), Wavelets and Statistics (pp. 55-81). NewYork: Springer-Verlag.
[10] J. Claerbout (1994). “Hypertext Documents about Reproducible Research.”http://sepwww.stanford.edu.
24
