Image Reconstruction Software Project Page

How to ...

This documentation is aimed at being a quick reference. The subsections below are loosely arrange in the same order as the specifications document. I plan to explain how to achieve each of the tasks in that document here (extension tasks are excluded for the moment). If the sub-section is blank, that probably means I haven't added that functionally yet. Let me know if there's anything you think needs to be added.

Get Started Quickly

If you are not familiar with Linux or c and want to quickly use the software without the hassle of installing many packages, the simplest way is by logging into osiris and use it there. This will also be useful to know how to do in the long run because the computing power available there is more than your laptop/desktop. The first step is to ask for an account on osiris if you don't already have one.

Then follow the steps below for logging in, and for setting up and running the software.

Logging into Osiris from a Linux/Unix/Mac Machine

Open a terminal and type:
ssh -X11 -2 osiris.ph.unimelb.edu.au
The "-X11 -2" enables you to view graphics on osiris.

Logging into Osiris from Windows

On Windows, you will need to install an ssh client. Most people (including me) recommend the program putty for this.

After you install it, test it works by logging into osiris:
Open putty
In the host name field type "@osiris.ph.unimelb.edu.au"
Make sure the connection type is set to "ssh"
Save these setting by typing in a saved session name. e.g "osiris" and clicking on "Save". Nex time to open putty to can load these setting by clicking on "osiris" and then "Load".
Now click on "Open". A terminal should open with a prompt asking for you password. After you enter it correctly you are logged into osiris.
End your session by typing "exit"

You are now half way there. You can log in, but you won't be able to view any images which are stored on osiris yet. To be able to do this, you need to install an X-windows server (graphical information can be passed back to your computer once you have this). I found Xming to be good. I installed it with the default options ("normal Putty").

I also found that I need to install Xming-fonts in order for the "emacs" text editor to disply fonts correctly. During the set-up I ticked all the boxes so that all the fonts were installed.

Now, each time you want to log into osiris you will need to run Xming first. It will run in the background, so all you'll see when it's running is a small icon on the tool bar. You can close it once you've finished with your putty session.

Finally go into putty again, and load your "osiris" session. Configure it for X windows by clicking on "SSH" under "Connection" in the tree on the left hand side of the screen.
click on "X11"
On the right hand side of the screen click on "Enable X11 forwarding".
Click on "session" in the left-hand tree.
And save these settings.
You are now ready to test it out. Click on "Open" and log in. type "emacs test" and you hopefully a window will pop up. Don't worry too much about what this is for now. Close the window and you are ready to start.

Set up your environment on Osiris

Once you have successfully logged in, append your PATH variable to the directory where the NADIA programs are located. This can be done by typing:
export PATH=$PATH:/data/nadia/NADIA.0.5/NADIA/bin
You now have available all of the command line tools listed here . Note that this will only work for your current session on osiris. To make it permanent, open the file ".bash_profile" in your home area:
emacs .bash_profile
add the line above to the end of the file, save and then close it (use the menu or type "xs" followed by "xc" while holding down the Ctrl key).

If you plan to work with IDL you will also need to update your LD_LIBRARY_PATH with the wrapper library path:
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/data/nadia/NADIA_dev/NADIA/interfaces/idl/
and update the IDL_PATH with the IDL module location:
export IDL_PATH="${IDL_PATH}:\:/data/nadia/NAIDA_dev/NADIA/interfaces/idl/"

Run some examples on Osiris

To see how to run the software, copy some examples to your local directory:
cp -r /data/nadia/NADIA.0.5/NADIA/examples/ ./
and change into this directory:
cd examples
Type ls to see a list of the files in this directory.

Running the Commandline Tool

The simplest way to run reconstruction is to use the CDI_reconstruction.exe command line tool. It takes three arguements as input:

If you don't give the seed value, "0" is used as the default, and if you don't give the reconstuction type, "planar" is assumed.

Test out the program by running it with one of the example configuration files:
CDI_reconstruction.exe planar_example.config
You should see output telling you the iteration number and the error. The error is a measure of the difference between the diffraction data and the reconstructed diffraction (the usual chi squared given in the literature). You can kill the process at any time by typing Ctrl-C or you can wait for it to finish if you like.

Now look into the configuration file by typing:
emacs planar_example.config
You can see that the data and support file names are given. Type:
gthumb image_files/planar_support.tiff
to view the support. The data file can't be viewed with gthumb because it's in binary format, however you can convert it to a .ppm file using one of the other command line tools and then view it:
dbin2ppm.exe image_files/planar_data.dbin planar_data.ppm 1024 1024
gthumb planar_data.ppm

The CDI_reconstruction.exe program outputs a .ppm file of the current magnitude of the estimated exit surface wave every 40 iterations. Type ls again to see a list of these files (they should look something like planar_x.ppm, where x is the iteration number). View them using gthumb. The reconstruction is slowly converging. Note that it may not completely converge as the number of iterations performed in this example is a lot less than usually used. The exit surface wave of the final iteration is saved as a complex binary file (with the file extension .cplx). You can view the magnitude and phase of the wave, by using the cplx2ppm.exe command, followed by the gthumb command. You can also use this file as the starting point for another reconstruction (see planar_example.config for instructions).

Now, try editing the configuration file:
emacs planar_example.config
e.g. with a different combination of reconstuction algorithms, a different output rate, support file or shrink-wrap parameters etc. and see what happends.

A similar example exists for the Fresnel case. This can be run by first reconstructing the white field using 3-plane propogation:
CDI_reconstruction.exe fresnel_example.config fresnel_wf
Then reconstruct the sample:
CDI_reconstruction.exe fresnel_example.config fresnel

Using the C/C++ Library

The command line tools are useful to get started quickly, but if you want full flexibility with the code, it's best to learn a little bit of "c" and examples are provided for this as well. The same reconstruction as planar.config performs can be done using PlanarCDI_example.c. Compile this code using the Makefile:
make Now when you type ls you should see a filenamed PlanarCDI_example.exe. Run this.
./PlanarCDI_example.exe You should find it gives almost exactly the same output as the CDI_reconstuction program did. Have a look at the source code:
emacs PlanarCDI_example.c
edit it and recompile using make to see what happens. Similarly, have a look at and Frsnel example: FresnelCDI_WF_example.c and FresnelCDI_example.c, and a simulation of the object from the planar example: PlanarCDI_simulation_example.c.

Later, if you write your own "c" code, it's easy to compile and link it with the libraries using the "Makefile" from the examples directory. Edit the "EXAMPLE_SRC" variable in the Makefile with the name of your ".c" file, then type "make" on the command line to compile it.

Using the Library in IDL

Some IDL wrapper have been written for the C++ library. This is useful for people who are more familiar with IDL than C. It will give greater flexibility than the command line program but doesn't allow to you use all the features of the C++ library.

Begin by copying the IDL examples to your working directory,
cp /data/nadia/NADIA_dev/NADIA/interfaces/idl/*_example.pro ./
and run them:
idl planar_example.pro

Look at the .pro files to see what they do. This link gives some details about each of the routines provided.

How to install

On osiris

To work in osiris, simply follow the instructions given above in "Getting Started". There will generally not be a need to install the software yourself on osiris as I've already installed it there.

If you do want to install it yourself on osiris, it's quite easy. Follow the general instructions provided below for Linux and unix from downloading the source code onwards (you do not need to install the extra packages such as fftw as there are already on osiris). Just replace the "./configure" command with:
./configure --with-mfhdf_lib=/usr/lib64/hdf CXXFLAGS="$CXXFLAGS -fPIC"

On Linux/unix

Currently the code depends on a few other libraries which will need to be installed prior to installing this package:

and it requires g++ to be installed for compilation (I've been using version 4.4.3).

On Ubuntu you can easily install the extra packages using the synaptic package manager. Look for libfftw3-dev, libtiff4-dev and libhdf4-dev.

Download our source code from here (when it becomes available) and put it into an appropriate directory. unzip and untar the code:
gunzip NADIA.0.5.tar.gz
tar -xvf NADIA.0.5.tar

Now change to the directory NADIA and compile the source code:
cd NADIA
./configure
make

If ./configure doesn't finish by making a set of "Makefiles", you probably haven't installed all the dependent libraries correctly or told ./configure where they are.

The result of compiling (if successful) are libraries and header files (in the \lib and \include directories) and some example programs which are ready to execute.

The Makefile in examples/ shows how the libraries can be linked and the source files in this directory e.g. real_example.c shows how the libraries can be used.

On Windows with Cygwin

Cygwin provides a Linux/unix type environment for Windows (the interface is basically a unix style terminal). Installing the NADIA source code in this environment is very similar to installing it in linux/unix and (in my opinion) makes modifying and recompiling the code a bit easier than it would be in Windows otherwise. First you will need to install Cygwin. You can do this by going to http://www.cygwin.com/, scrolling to the bottom of the page and clicking on "Install or update now! (using setup.exe)". Open setup.exe and follow the installation instructions. Apart from the "Package Selection" screen, I used the default options. When you get to the "Package Selection" screen leave "All" on "Default" and add the additional packages by searching for them and then clicking on them: Note that you can update the packages which are installed after you've installed Cygwin just by clicking on setup.exe again (it remembers which are installed). Initially I had some trouble during the post-installation phase (error code 128). In my case this was caused by old unwanted virus checkers interfering. I had to remove these packages from windows to get Cygwin to install properly. Hopefully you won't need to do this.

Install the HDF4 libraries. There is no package for this in the package manager so go to and download their Windows binary for your system (32 or 64 bit). Unzip the file using the standard Windows tool and install to a directory without any spaces (Cygwin sometimes struggles with spaces) Some of the HDF files are named in such a way that the NADIA software cannot find them. So go in to the bin directory of your HDF install (something like c:\HDF_Group\HDF\4.2.8\bin) and create some dynamic links: ln -sf mfhdfdll.dll libmfhdf.dll ln -sf hdfdll.dll libdf.dll ln -sf szip.dll libsz.dll

Next, download NADIA here and put it into your home directory on Cygwin (C:\cygwin\home\your_user_name). Open Cygwin and unzip and untar the package:
$ gunzip NADIA.0.5.tar.gz
$ tar -xvf NADIA0.5.tar
When you type ls you should see the directory "NADIA" plus a few others. Change into the NADIA directory:
$ cd NADIA
Tell the package where your hdf and szip libraries files are located (replace the "user_name" with your Cygwin user name):
$ ./configure --with-mfhdf_lib=/home/"user_name"/hdf4.2.8-cygwin-szip/lib --with-mfhdf_inc=/home/"user_name"/hdf4.2.8-cygwin-szip/include i--with-sz_lib=c:/HDF_Group/HDF/4.2.8/bin --with-df_lib=c:/HDF_Group/HDF/4.2.8/bin
If you get an error, check that the paths given to configure are correct; the lib directories should have files starting with "lib" and the include directory should have files ending in ".h". If configure worked okay, then compile the libraries and examples:
$ make

Hopefully you won't get any errors and when you look in the lib/ and include/ directories you will see some files. The libraries can be useful if you ever need to create your own code (similar to the examples). The examples show how the libraries can be used. Change into the example directory:
$ cd examples
and run one of the examples. e.g.:
$ ./PlanarCDI_example.exe

If everything is working correcting, you should see some text output (counting the iterations). If you look at this directory in the windows browser you should see that some .ppm images files are created which give you the object estimation for various number of iterations.

Have a look at the code in more detail to see what's going on:
$ xemacs PlanarCDI_example.c
and edit some variables to see what happens (eg. change the reconstruction algorithm).
Then recompile and rerun the example:
$ make
$ ./PlanarCDI_example.exe

On Windows (general) - using IDL (not C)

Download the package (binary files) from the main webpage. Executing the .msi file should automatically start the installation. Select which directory you want the files to be installed in (if it's not you're own machine you probably won't have permission to install into Program Files). Once installed you can start using the library and command line executable files. Look at the README file which comes with the distribution to find out more. To uninstall, do to "Control Panel", go to "Add/Remove program", find NADIA and remove it.

On a Mac

Thanks to Michael for providing some instructions on how to install and configuring the code on OS X 10.6:

Step 1. Install Xcode. This is a BIG download, you first have to register as a developer. Once installed, this is a nice text editor too.

Step 2. Install fink. Do it exactly as it says and its easy. You use fink like apt get on linux to install the fftw and hdf packages. Make sure you select the correct releases of these.

Step 3. Get and build the fftw, libtiff, lapack and hdf packages using fink

Step 4. Download the source code from this website

Step 5. Follow the install instruction for linux, EXCEPT, replace ./configure with
./configure --with-fftw_inc=/sw/include --with-fftw_lib=/sw/lib CXX="g++ -arch i386" --with-mfhdf_inc=/sw/include --enable-checking

The --withThe CXX="g++ -arch i386" bit related to your computers architecture. This is for a late 2010 macbook pro running 10.6, try this, if it doesn't work, try looking up the relevant information for your computer. --enable-checking is just in case!

Step 6. Type make, as in the linux instructions.

View HDF files

A tool already exists for quickly viewing the content of an HDF file, HDF File Navigator, however, it does not appear to be easy to extract the data as a tiff/ppm or lossless image file type using this tool.

Look at data on a log scale

Viewing data on a log scale has not be implemented yet, however, if you are running your own c code, it's possible to output the data to file in log scale. Add "true" as the 3rd parameter of the file writing functions. e.g.
write_ppm("my_file_name",my_Double_2D_object, true)

Plot the average intensity versus frame number, full-frame and ROI

Check for saturation/dead pixels

Run correlations on data and white-fields

Convert HDF files and extract header info

hdf2ppm.exe can be used to extract 16 bit/pixel data to a ppm image file. See here for usage details.

Extraction of header information has not been implemented yet.

Convert between different file formats

Raw data processing

Subtract the darkfield

Check the beam stability in data over time

Check correlations after dark-field subtraction

Merge (add or average) data files together

Determine the normalisation of the white-field to data

Get the autocorrelation function

Reconstruction

Reconstruct the phase of the white-field using 3-plane propogation

Perform reconstruction

Carry out holographic 1 step reconstruction

Update the support or use the shrink-wrap algorithm

How to stop a reconstuction, save the result and restart at the same place

How to modify the reconstruction algorithm by adding a new constraint

Refine the experimental parameters during reconstuction

Use the software in other languages

IDL

A description of each of the functions and procedures which are provided in IDL can be found here. Two example are provided which should help you to get started; one is for planar reconstruction and the other is for fresnel reconstruction.

Below, some description of how to set up you system for IDL is given.

On Osiris

Create the directory you wish you work in, eg:
mkdir nadia_idl
and change into this directory
cd nadia_idl

Now update your LD_LIBRARY_PATH with the wrapper library path:
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/data/nadia/NADIA_dev/NADIA/interfaces/idl/
and update the IDL_PATH with the IDL module location:
export IDL_PATH="${IDL_PATH}::/data/nadia/NADIA_dev/NADIA/interfaces/idl/"
You will need to add these two lines to the end of your .bashrc or .bash_profile file to make them permanent. Do this by opening the file in a text editor and copying and pasting the lines above into the end of the file,
emacs ~/.bash_profile

You are now ready to begin working. Copy some examples to your working directory,
cp /data/nadia/NADIA_dev/NADIA/interfaces/idl/*_example.pro ./
and run them:
idl planar_example.pro

If Installing from the Source Code (Unix/Linux/Mac/Cygwin/Mingw)

See the instruction provided above on how to install from the source code . The IDL interface is compiled by default.

Now follow the instructions given for osiris, but everwhere you see "/data/nadia/NADIA_dev/NADIA" put the path to the base directory of your NADIA installation.

On Windows (general)

Download and install the binary files for windows. You can import the NADIA library routines into IDL by simply executing:

.Compile NADIA_interface.pro

Documentation for each of the routines can be found on this website and examples are provided in the "examples" subdirectory of the installed distribution.

To run the IDL examples:

...
email me if you would like other examples posted