inpystem.restore.LS_3D module

This module implements regularized least square restoration methods adapted to 3D data.

The two methods it gathers are

  • Smoothed SubSpace (3S) algorith,

  • Smoothed Nuclear Norm (SNN) algorithm.

inpystem.restore.LS_3D.SSS(Y, Lambda, mask=None, PCA_transform=True, PCA_th='auto', PCA_info=None, scale=1, init=None, Nit=None, verbose=True)

Smoothed SubSpace algorithm.

The 3S algorithm denoise or reconstructs a multi-band image possibly spatially sub-sampled in the case of spatially smooth images. It is well adapted to intermediate scale images.

This algorithm performs a PCA pre-processing operation to estimate:

  • the data subspace basis \(\mathbf{H}\),

  • the subspace dimension \(R\),

  • the associated eigenvalues in decreasing order \(\mathbf{d}\),

  • the noise level \(\hat{\sigma}\).

After this estimation step, the algorithm solves the folowing regularization problem in the PCA space:

\[\gdef \S {\mathbf{S}} \gdef \Y {\mathbf{Y}} \gdef \H {\mathbf{H}} \gdef \I {\mathcal{I}} \begin{aligned} \hat{\S} &= \underset{\S\in\mathbb{R}^{m \times n \times R}}{\arg\min} \frac{1}{2R}\left\|\S \mathbf{D}\right\|_\mathrm{F}^2 + \frac{\lambda}{2}\sum_{m=1}^{R} w_{m} |\S_{m,:}|_2^2\\ &\textrm{s.t.}\quad \frac{1}{R}|\H_{1:R}^T\Y_{\I(n)}-\S_{\mathcal{I}(n)}|^2_2 \leq\hat{\sigma}^2,\ \forall n \in \{1, \dots,\ m*n\} \end{aligned}\]

where \(\mathbf{Y}\) are the corrupted data, \(\mathbf{D}\) is a spatial finite difference operator and \(\mathcal{I}\) is the set of all sampled pixels.

Caution

It is strongly recomended to perform PCA before running the algorithm core. This operation is integrated in this function.

In case this pre-processing step has already been done, set the PCA_transform parameter to False to disable the PCA step included in the SSS function. If PCA_transform is set to False, the PCA_info parameter is required.

Parameters

  • (m, n, l) numpy array (Y) – A 3D multi-band image.

  • Lambda (float) – Regularization parameter.

  • mask (optional, None, (m, n) numpy array) – A sampling mask which is True if the pixel is sampled. Default is None for full sampling.

  • PCA_transform (optional, bool) – Enables the PCA transformation if True, otherwise, no PCA transformation is processed. Default is True.

  • PCA_th (optional, int, str) – The desired data dimension after dimension reduction. Possible values are ‘auto’ for automatic choice, ‘max’ for maximum value and an int value for user value. Default is ‘auto’.

  • PCA_info (optional, dict) –

    In case PCA_transform is False, some extra info should be given to SSS. The required keys for PCA_info are:

    • ’d’ which are the PCA eigenvalues.

    • ’sigma’ which is an estimate of the data noise std.

  • scale (optional, float) – Scales the prox operator sphere radius. Should lay in ]0, +inf[. Default is 1.

  • init (optional, None, (m, n, l) numpy array) – The algorithm initialization. Default is None for random initialization.

  • Nit (optional, None, int) – Number of iteration in case of inpainting. If None, the iterations will stop as soon as the functional no longer evolve. Default is None.

  • verbose (optional, bool) – Indicates if information text is desired. Default is True.

Returns

  • (m, n, l) numpy array – The reconstructed/denoised multi-band image.

  • dict – A dictionary containing some extra info

Note

Infos in output dictionary:

  • E: in the case of partial reconstruction, the cost function evolution over iterations.

  • H : the basis of the chosen signal subspace

References

Monier, E., Oberlin, T., Brun, N., Tencé, M., de Frutos, M., & Dobigeon, N. (2018). Reconstruction of Partially Sampled Multiband Images—Application to STEM-EELS Imaging. IEEE Trans. Comput. Imag., 4(4), 585–598.

inpystem.restore.LS_3D.SNN(Y, Lambda, Mu, mask=None, PCA_transform=True, PCA_th='auto', init=None, Nit=None, verbose=True)

Smoothed Nuclear Norm algorithm.

The SNN algorithm denoise or reconstructs a multi-band image possibly spatially sub-sampled in the case of spatially smooth images. It is well adapted to intermediate scale images.

This algorithm solves the folowing optimization problem:

\[\gdef \X {\mathbf{X}} \gdef \Y {\mathbf{Y}} \gdef \H {\mathbf{H}} \gdef \I {\mathcal{I}} \hat{\X} = \underset{\X\in\mathbb{R}^{m \times n \times B}}{\arg\min} \frac{1}{2}||\Y_\I - \X_\I||_\mathrm{F}^2 + \frac{\lambda}{2}\left\|\X \mathbf{D}\right\|_\mathrm{F}^2 + \mu ||\X||_*\]

where \(\mathbf{Y}\) are the corrupted data, \(\mathbf{D}\) is a spatial finite difference operator and \(\mathcal{I}\) is the set of all sampled pixels.

This algorithm can perform a PCA pre-processing operation to estimate:

  • the data subspace basis \(\mathbf{H}\),

  • the subspace dimension \(R\).

This is particularly usefull to reduce the data dimension and the execution time and to impose a data low-rank property.

Caution

It is strongly recomended to perform PCA before running the algorithm core. This operation is integrated in this function.

In case this pre-processing step has already been done, set the PCA_transform parameter to False to disable the PCA step included in the CLS function.

Parameters

  • (m, n, l) numpy array (Y) – A 3D multi-band image.

  • Lambda (float) – Regularization parameter #1.

  • Mu (float) – Regularization parameter #2.

  • mask (optional, None, (m, n) numpy array) – A sampling mask which is True if the pixel is sampled. Default is None for full sampling.

  • PCA_transform (optional, bool) – Enables the PCA transformation if True, otherwise, no PCA transformation is processed. Default is True.

  • PCA_th (optional, int, str) – The desired data dimension after dimension reduction. Possible values are ‘auto’ for automatic choice, ‘max’ for maximum value and an int value for user value. Default is ‘auto’.

  • init (optional, None, (m, n, l) numpy array) – The algorithm initialization. Default is None for random initialization.

  • Nit (optional, None, int) – Number of iteration in case of inpainting. If None, the iterations will stop as soon as the functional no longer evolve. Default is None.

  • verbose (optional, bool) – Indicates if information text is desired. Default is True.

Returns

  • (m, n, l) numpy array – The reconstructed/denoised multi-band image.

  • dict – A dictionary containing some extra info

Note

Infos in output dictionary:

  • E: in the case of partial reconstruction, the cost function evolution over iterations.

  • H : the basis of the chosen signal subspace

References

Monier, E., Oberlin, T., Brun, N., Tencé, M., de Frutos, M., & Dobigeon, N. (2018). Reconstruction of Partially Sampled Multiband Images—Application to STEM-EELS Imaging. IEEE Trans. Comput. Imag., 4(4), 585–598.