/score

Shape COnstraint REstoration

Primary LanguageJupyter Notebook

SCORE

The Shape COnstraint REstoration algorithm (SCORE) is a proximal algorithm based on sparsity and shape constraints to restore images. Its main purpose is to restore images while preserving their shape information. The chosen shape information here, is the ellipticity which is used to study galaxies for cosmological purposes. In practice, SCORE give an estimation of the ground truth image, , of the inverse problem :

with

where are respectively the observation, the convolution kernel and a white additive Gaussian of standard deviation , is the shape constraint operator, is trade-off between the datafidelity and the shape constraint, is the positivity constraint operator (under the assumption that all the entries of are non-negative values) and finally, is the sparsity constraint (assuming that is sparse).

Getting Started

Prerequisites

These instructions will get you a copy of the project up and running on your local machine. One easy way to install the prerequisites is using Anaconda. To install Anaconda see : https://docs.conda.io/projects/conda/en/latest/user-guide/install/

  • Numpy
conda install -c anaconda numpy
  • Scipy
conda install -c anaconda scipy
  • Skimage
conda install -c conda-forge scikit-image
  • α-shearlet Transform

    Clone the library (https://github.com/dedale-fet/alpha-transform) and run the commands below to get the approriate version :

git clone https://github.com/dedale-fet/alpha-transform.git
cd alpha-transform/
git checkout adcf993

    Then add the path of the α-shearlet Transform library to the PYTHONPATH variable in the bash profile

export PYTHONPATH="$HOME/path/to/alpha-transform-master:$PYTHONPATH"

        Replace path/to by the corresponding path

  • GalSim [optional] (for research reproducibility)
conda install -c conda-forge galsim
  • Matplotlib [optional]
conda install -c conda-forge matplotlib

Installing

After install the prerequisites, clone or download score repository. And to be able to access from any working directory, use the following command to add the path to score to PYTHONPATH variable in the bash profile :

export PYTHONPATH="$HOME/path/to/score:$PYTHONPATH"

        Replace path/to by the corresponding path

Running the examples

This repository contains two examples. They respectively illustrate a denoising and a deconvolution case.

Example 1

In this simple denoising case, we restore a galaxy image corrupted by noise. The core of the code is:

#instantiate score and, for example, set the value of gamma the other parameters will take their default values
denoiser = score(gamma=0.5)
#denoise
denoiser.denoise(obs=gal_obs) #the result will be in denoiser.solution

It is also possible to change other parameters in score.

Example 2

In this deconvolution case, we compare the score algorithm with a value of γ = 1 (which is close to its optimal computed value) and the Sparse Restoration Algorithm (γ = 0 and no Removal of Isolated Pixels). We loop on a stack of galaxy images and perfom both deconvolution operation on each image:

#loop
for obs, psf, gt in zip(gals_obs,psfs,gals):
    #deconvolve
    g1.deconvolve(obs=obs,ground_truth=gt,psf=psf)
    g0.deconvolve(obs=obs,ground_truth=gt,psf=psf)
    #update ellipticity error lists
    g1_error_list += [g1.relative_ell_error]
    g0_error_list += [g0.relative_ell_error]

Parameters

The following is an exhaustive list of parameters of score :

Parameter Type Information
obs 2D Numpy Array observation (required)
psf 2D Numpy Array convolution kernel (required for deconvolution)
ground_truth 2D Numpy Array (none by default) ground_truth image (optional)
sigma positive scalar noise standard deviation (optional)
beta_factor positive scalar < 1 (0.95 by default) multiplicative factor to ensure that beta is not too big (optional)
epsilon positive scalar error upperbound for the Lipschitz constant estimation (optional)
n_maps positive integer threshold estimation parameter for hard thresholding (optional)
n_shearlet positive integer (3 by default) number of scales for the shearlet transform (optional)
n_starlet positive integer (4 by default) number of scales for the starlet transform (optional)
starlet_gen positive integer (either 1 or 2) starlet generation (optional)
beta positive scalar gradient step size (optional)
k positive integer (3 by default) threshold parameter for hard thresholding (optional)
rip boolean (true by default) activate Removal of Isolated Pixels after restoration (optional)
gamma non-negative scalar (1 by default) trade-off between data-fidelity and shape constraint (optional)
n_itr positive integer maximum number of iterations (optional)
tolerance positive scalar < 1 (1e-6 by default) threshold of the convergence test for deconvolution (optional)
verbose boolean (true by default) to activate verbose (optional)

Reproducible Research

The code generate_dataset.py allows to recreate the exactly the same dataset used for the numerical experiments of the original paper of score. To be able to run this code, the catalog COSMOS_25.2_training_sample is required. It is available as a compressed file, COSMOS_25.2_training_sample.tar.gz, on this link.

Authors

See also the list of contributors who participated in this project.

License

This project is licensed under the MIT License - see the LICENSE.md file for details

Acknowledgments

We would like to thank the following researchers :