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 \(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 \(8\times 8\) vectorial (3D) patches on the region of interest \([600, 1428] \times [600, 1333]\) in a \(2048 \times 2048 \times 81\) volume. The learning process focuses on the values inside \([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.