Instructions for using KSVD
==========================

This page explains how to use KSVD to learn a dictionary over a slice or a volume.
Using an adapted dictionary for a volume can yield a significant improvement of the reconstruction quality.


Installation of KSVD
---------------------

Create a directory where KSVD will be installed. Go in this directory and retrieve the repository ::

      git clone https://gitlab.esrf.fr/mirone/ksvd
      
Then, install this package ::

      cd ksvd
      python setup.py install --prefix=<path to your KSVD folder>

Set the environment variables ::

      export PATH=<path to your KSVD folder>/packages/bin/:$PATH
      export PYTHONPATH=<path to your KSVD folder>/packages/lib/python2.7/site-packages/:$PYTHONPATH


Parameter file
--------------

All parameters for generating a dictionary are given in yaml format. The lines are in the form ``key: value``.

The retrieved repository should already contain an example of parameter file ``input_coupe.yaml``.

In this file, you must specify :
  * The file from which the patches are extracted
  * The number of extracted patches : ``n_comps``
  * The width of the patches : ``patchwidth``
  * The region of the slice (region of interest) where KSVD will extract the patches : ``START_X``, ``END_X``, ``START_Y``, ``END_Y`` (also ``START_Z`` and ``END_Z`` for a volume).
   Beware that if you are using a volume, you have to specify the volume size ``VDIMZ``.
  * The minimum and maximum grey values : ``VAL_MIN`` and ``VAL_MAX``. Any value outside this range will be cliped.
  * For a volume, the starting and ending slices to take into account : ``START_Z`` and ``END_Z``
  * If you want a set of vectorial (3D) patches , specify `DERIVATIVES: 1`

Example 1
*********
This example generates 200 :math:`8\times 8` patches on a single slice. All the slice area and all possible values are taken. ::

      patchwidth: 8
      NPURSUIT:    4
      n_comps:   200
      nitersksvd:  5
      files:
       - !ImageFile
          START_X: 0
          END_X: 100000
          START_Y: 0
          END_Y: 100000
          VAL_MIN: -1.0e+30
          VAL_MAX: +1.0e+30
          FILE_TYPE: edf
          FILE:  coupe.edf
          DERIVATIVES: 0
          N_PATCHES: 40000

Example 2
*********
This example generates 200 :math:`8\times 8` vectorial (3D) patches on the region of interest :math:`[600, 1428] \times [600, 1333]` in a :math:`2048 \times 2048 \times 81` volume. The learning process focuses on the values inside :math:`[0.1 ; \, 0.29]` ::

      files:
       - !VolumeFile
          START_X: 600
          END_X: 1428
          START_Y: 600
          END_Y: 1333
          START_Z: 31
          END_Z: 51
          VDIMX: 2048
          VDIMY: 2048
          VDIMZ: 81
          VAL_MIN: 0.1
          VAL_MAX: 0.29
          FILE_TYPE: vol
          FILE:  rabbit.vol
          DERIVATIVES: 1
          N_PATCHES: 40000


Code execution
---------------

Once you are done with the parameter file, just execute ::

      ksvd input_coupe.yaml

The patches extraction may take some time.

To visualize the patches, just run ::

      ksvd
and wait for the prompt to enter the patches name.