Feature/mace

[dyang37]

This is my first attempt to merge mace into master branch. This PR contains the minimal code for a mace3D reconstruction demo using simulated data (bottle cap).

I set up the mace module in the way that no extra requirements (specifically keras and tensorflow) are needed for the mbircone library. All keras/tensorlow dependent part are moved into demo script. The reason for this setting is that ideally we want the user to be able to install mbircone without the dependencies of tensorflow and keras.

Scripts:

• demo/demo_mace3D.py: demo script for 3D mace recon. This file demonstrates the usage of mace3D reconstruction algorithm by downloading phantom and denoiser data from a url, generating sinogram by projecting the phantom and adding transmission noise, and finally performing a 3D MACE reconstruction.
• mbircone/mace/mace.py: script for mace3D function.
• mbircone/mace/denoiser.py: script for denoiser functions.

Tests performed:

• Start from a clean conda env and a freshly cloned mbircone repo, test that qGGMRF recon works by running demo_3D_shepp_logan.py without installing mace specific requirements. Make sure that the reconstructed images look correct.
• Start from a clean conda env and a freshly cloned mbircone repo, install mace specific requirements, and test mace3D demo by running demo_mace3D.py, and make sure that we obtain good mace reconstructions.

Phantom (axial slice):

MACE reconstruction:

[DamonLee5]

I tested the code in the Purdue Brown cluster. I got the same result as Diyu shown in the pull request.

However, here are 2 suggestions:

1. In the demo, we should print out download information.
2. Iterations stopped by max iterations=20. Maybe we should adjust the stop threshold.

[DamonLee5]

When I tested in Lilly's Cluster, it failed to download the tarball file since the compute nodes are not connected to the internet. To test the code, I first downloaded the dataset in an interactive node that can connect to the internet, then use the computed nodes to run the demo.

After that, the code runs successfully and the results look exactly the same as the results above.

Based on the above issue, here is a suggestion,

1. We can separate demo_mace3D.py into two scripts: download dataset and mace demo.

[dyang37]

10/14 update log. The following updates are made based on our discussion in today's meeting:

1. Before downloading data from url, check if ./demo_data folder exists. If so ask user if it is desired to download and overwrite the existing data.

2. Add exception handling for URLError and HTTPErrors when downloading data from url, and raise exceptions with more human readable error messages: HTTP errors:

   • 401: URL authentication failed! Currently we do not support downloading data from a url that requires authentication.
   • 403: URL forbidden! Please make sure the provided URL is public.
   • 404: URL not Found! Please check and make sure the download URL provided is correct.
   • else: print out error code and message, and give user a link to HTTP status code wiki page.

   URL error: This is most likely due to internet connection issue. In this case we ask the user to check his/her internet connection.

3. Move mbircone/mace/denoiser.py to demo/denoiser_utils.py so that cnn denoiser is not part of mbircone module.
4. Add optional argument data_format in cnn_denoiser function so that it supports a wider variety of deep neural network denoiser models.
5. In demo file add detailed explanation of the content in the downloaded data folder, and how to replace the contents with customized data from user.
6. In demo file add comments to specify the legit choice of denoiser functions for mace3D.

[dyang37]

Pull request ready to merge. Here are the summary of the major updates:

1. Modified the print messages inside MACE. Changed the verbose parameter in MACE to be the following:

   • verbose (int, optional): [Default=1] Possible values are {0,1,2}, where 0 is quiet, 1 prints MACE reconstruction progress information, and 2 prints the MACE reconstruction as well as qGGMRF/proximal-map reconstruction progress information.

2. Modified sphinx docs scripts and mace doctoring style. Here is the built mace docs: mace-docs.pdf Note that by default sphinx docs do not support arguments grouping (Required args/args specific to MACE/optional args). As a result I have to hard code some of the formatting in the source code of the docstring. See the mace docstring inside mace/mace.py for more details.

3. Added a faster MACE demo demo_mace3D_fast.py. This demo is mostly the same as demo_mace3D.py except that the phantom is 2x downsampled in all directions, and num_det_rows and num_det_channels are also halved to match up with the downsampled phantom size. The downsampling in xy plane is performed with resize function from PIL. The downsampling in z direction (slices) is performed by simply taking first half of the slices. Original phantom:

Downsampled phantom:

MACE Reconstruction:

Testing on an iMac, MACE reconstruction takes a total of about 2 minutes (40 sec for qGGMRF recon + 10* (6.5 sec/mace_iteration)) on the downsampled dataset.

4. Miscellaneous changes
   • Made downloading mechanism a function download_and_extract(download_url, extract_path='./demo_data/') inside demo_utils.py.
   • Fixed incorrect printing message of image size in cone3D.project() function.
   • Deleted abundant print messages in mbircone/cone3D/src/interface.c and mbircone/cone3D/src/recon3DCone.c