img.alg
 Image Processing Algorithms¶
Applying algorithms¶
While image properties are usually manipulated using method of the
ImageHandle
class, their data content is manipulated using
image algorithms. Image algorithms are objects. Each of them is a class, and its
methods are used to handle the algorithm parameters. Applying an algorithm to an
image is then conceptually a twostep process. First, an instance of an
algorithm class is created, yielding an algorithm object. In a second step, the
algorithm object is applied to an image. An algorithm can be applied inplace
(using the ApplyIP()
method), modifying the image, or
outofplace, (using Apply()
), leaving the original image
untouched, and returning the result as a new image.
Here is an example. All the algorithms used in the following are described in the Selected Algorithms section.
# creates an algorithm object
rand_alg = img.alg.Randomize()
# applies algorithm object in place, overwriting the image
im.ApplyIP( rand_alg )
Sometimes, there is no need to create a permanent instance of an algorithm object. A temporary object enough:
# applies temporary algorithm object inplace
im.ApplyIP( img.alg.GaussianFilter(4.0) )
When used this way, the algorithm class will cease to exist as soon as the
algorithm is applied. However, some algorithm are stateful and store
information. One good example is the Stat
algorithm, which does not
modify the image when applied, but change its internal state to store
information extracted from the image, which can be recovered later. For example:
# creates and applies an algorithm object
stat=img.alg.Stat()
im.ApplyIP(stat)
# extracts information from the algorithm
mean=stat.GetMean()
It is important to remember that when the algorithms ceases to exist, all information it stores is lost.
Fourier Transforming Images¶
An image can be Fouriertransformed using either the FFT
algorithm or
the DFT
algorithm. The difference between the two is that the
DFT
algorithm honors the The spatial origin of the image, and
applies the corresponding phase shift in Fourier space. The FFT
does
not follow this behavior.
# create an instance of the Dft algorithm object
dft=img.alg.DFT()
# do the actual Fourier transformation
im_ft=im.Apply(dft)
# backtransform
im2 = im_ft.Apply(dft)
The FFT
and DFT
algorithms do not require a direction to be
given (forward or back transform). This is implicitly determined by the current
The data domain of the image being transformed. The following rules apply.
SPATIAL
>HALF_FREQUENCY
HALF_FREQUENCY
>SPATIAL
FREQUENCY
>COMPLEX_SPATIAL
COMPLEX_SPATIAL
>FREQUENCY
Filters¶
OpenStructure makes several image filters available. Most of them are Fourier
space filters, others are real space ones. However, since the
ImagerHandle
class is aware of its own The data domain,
the user does not need to convert the image to Fourier space or to real space.
Irrespective of which domain the filter applies to, OpenStructure will
internally convert the image to the appropriate domain, apply the filter, and
then return the image to its original conditions.
The following filters are available (their are described in the Selected Algorithms section below)
Fourier space filters:
LowPassFilter
HighPassFilter
GaussianLowPassFilter
GaussianHighPassFilter
FermiLowPassFilter
FermiHighPassFilter
ButterworthLowPassFilter
ButterworthHighPassFilter
FermiLowPassFilter
Real space filters:
Selected Algorithms¶
Many algorithms are available for image manipulation. What follows is a description of the most important ones.

class
DFT
¶ This algorithm performs a Fourier Transform of the image, honoring its The spatial origin, thus applying the corresponding phase shift in Fourier space.

class
DiscreteShrink
(block_size)¶ The algorithm performs a scaling of the original image by merging adjacent blocks of pixels. The block size is passed in the constructor in the form of a
Size
but can be changed later using the relevant method. TheSize
and theExtent
of the image are changed when the algorithm is applied. The Pixel sampling of the image is also adjusted according to the scaling, so that the size of the image in the absolute reference system used by OpenStructure stays constant.Parameters: block_size ( Size
) – Size of the blocks to be merged

class
FFT
¶ This algorithm performs a Fourier Transform of the image, without honoring its The spatial origin (See
DFT
)

class
LowPassFilter
(cutoff=1.0)¶ This algorithm applies a Fourier low pass filter to the image. The filter cutoff frequency needs to be provided in sampling units (for example 8 Angstrom). Please notice that this filter features a sharp dropoff.
Parameters: cutoff (float) – Frequency cutoff in sampling units 
GetLimit
()¶ Returns the current value of the filter cutoff frequency (in sampling units).
Return type: float

SetLimit
(cutoff)¶ Sets the value of the filter cutoff frequency to the specified value (in sampling units).
Parameters: cutoff (float) – Frequency cutoff in sampling units


class
HighPassFilter
(cutoff=1.0)¶ This algorithm applies a Fourier high pass filter to the image. The filter cutoff frequency needs to be provided in sampling units (for example 8 Angstrom). Please notice that this filter features a sharp dropoff.
Parameters: cutoff (float) – Frequency cutoff in sampling units 
GetLimit
()¶ Returns the current value of the filter cutoff frequency (in sampling units).
Return type: float

SetLimit
(cutoff)¶ Sets the value of the filter cutoff frequency to the specified value (in sampling units).
Parameters: cutoff (float) – Frequency cutoff in sampling units


class
GaussianLowPassFilter
(cutoff=1.0)¶ This algorithm applies a Fourier Gaussian low pass filter to the image. The filter cutoff frequency needs to be provided in sampling units (for example 8 Angstrom).
Parameters: cutoff (float) – Frequency cutoff in sampling units 
GetLimit
()¶ Returns the current value of the filter cutoff frequency (in sampling units).
Return type: float

SetLimit
(cutoff)¶ Sets the value of the filter cutoff frequency to the specified value (in sampling units).
Parameters: cutoff (float) – Frequency cutoff in sampling units


class
GaussianHighPassFilter
(cutoff=1.0)¶ This algorithm applies a Fourier Gaussian High pass filter to the image. The filter cutoff frequency needs to be provided in sampling units (for example 8 Angstrom).
Parameters: cutoff (float) – Frequency cutoff in sampling units 
GetLimit
()¶ Returns the current value of the filter cutoff frequency (in sampling units).
Return type: float

SetLimit
(cutoff)¶ Sets the value of the filter cutoff frequency to the specified value (in sampling units).
Parameters: cutoff (float) – Frequency cutoff in sampling units


class
FermiLowPassFilter
(cutoff=1.0, t=1.0)¶ This algorithm applies a Fourier Fermi low pass filter to the image. The filter cutoff frequency and the temperature parameter T need to be provided in sampling units (for example 8 Angstrom).
Parameters:  cutoff (float) – Frequency cutoff in sampling units
 t (float) – Temperature factor in sampling units

GetLimit
()¶ Returns the current value of the filter cutoff frequency in sampling units.
Return type: float

SetLimit
(cutoff)¶ Sets the value of the filter cutoff frequency to the specified value (in sampling units).
Parameters: cutoff (float) – Frequency cutoff in sampling units

GetT
()¶ Returns the current value of the filter’s T factor (in sampling units).
Return type: float

SetT
(t_factor)¶ Sets the value of the filter’s T factor to the specified value (in sampling units).
Parameters: t_factor (float) – Frequency cutoff in sampling units

class
FermiHighPassFilter
(cutoff=1.0, t=1.0)¶ This algorithm applies a Fourier Fermi high pass filter to the image. The filter cutoff frequency and the temperature parameter T need to be provided in sampling units (for example 8 Angstrom).
Parameters:  cutoff (float) – Frequency cutoff in sampling units
 t (float) – Temperature factor in sampling units

GetLimit
()¶ Returns the current value of the filter cutoff frequency in sampling units.
Return type: float

SetLimit
(cutoff)¶ Sets the value of the filter cutoff frequency to the specified value (in sampling units).
Parameters: cutoff (float) – Frequency cutoff in sampling units

GetT
()¶ Returns the current value of the filter’s T factor (in sampling units).
Return type: float

SetT
(t_factor)¶ Sets the value of the filter’s T factor to the specified value (in sampling units).
Parameters: t_factor (float) – Frequency cutoff in sampling units

class
ButterworthLowPassFilter
(passband=1.0, stopband=1.0)¶ This algorithm applies a Fourier Butterworth low pass filter to the image. The filter passband and stopband frequencies need to be provided in sampling units (for example 8 Angstrom). The default values of the Epsilon and Maximum Passband Gain parameters are set to 0.882 and 10.624 respectively.
Parameters:  passband (float) – Passband frequency in sampling units
 stopband (float) – Stopband frequency in sampling units

GetLimit
()¶ Returns the current value of the filter passband frequency in sampling units.
Return type: float

SetLimit
(passband)¶ Sets the value of the filter passband frequency to the specified value (in sampling units).
Parameters: passband (float) – Frequency cutoff in sampling units

GetStop
()¶ Returns the current value of the filter’s stopband frequency (in sampling units).
Return type: float

SetStop
(stopband)¶ Sets the value of the filter’s stopband frequency to the specified value (in sampling units).
Parameters: stopband (float) – Frequency cutoff in sampling units

GetEps
()¶ Returns the current value of the filter’s Epsilon parameter.
Return type: float

SetEps
(epsilon)¶ Sets the value of the filter’s epsilon parameter to the specified value.
Parameters: eps (float) – Epsilon parameter

GetA
()¶ Returns the current value of the filter’s Maximum Passband Gain parameter.
Return type: float

SetA
(gain)¶ Sets the value of the filter’s Maximum Passband Gain parameter to the specified value.
Parameters: gain (float) – Maximum Passband Gain parameter

class
ButterworthHighPassFilter
(passband=1.0, stopband=1.0)¶ This algorithm applies a Fourier Butterworth high pass filter to the image. The filter passband and stopband frequencies need to be provided in sampling units (for example 8 Angstrom). The default values of the Epsilon and Maximum Passband Gain parameters are set to 0.882 and 10.624 respectively.
Parameters:  passband (float) – Passband frequency in sampling units
 stopband (float) – Stopband frequency in sampling units

GetLimit
()¶ Returns the current value of the filter passband frequency in sampling units.
Return type: float

SetLimit
(passband)¶ Sets the value of the filter passband frequency to the specified value (in sampling units).
Parameters: passband (float) – Frequency cutoff in sampling units

GetStop
()¶ Returns the current value of the filter’s stopband frequency (in sampling units).
Return type: float

SetStop
(stopband)¶ Sets the value of the filter’s stopband frequency to the specified value (in sampling units).
Parameters: stopband (float) – Frequency cutoff in sampling units

GetEps
()¶ Returns the current value of the filter’s Epsilon parameter.
Return type: float

SetEps
(epsilon)¶ Sets the value of the filter’s epsilon parameter to the specified value.
Parameters: eps (float) – Epsilon parameter

GetA
()¶ Returns the current value of the filter’s Maximum Passband Gain parameter.
Return type: float

SetA
(gain)¶ Sets the value of the filter’s Maximum Passband Gain parameter to the specified value.
Parameters: gain (float) – Maximum Passband Gain parameter

class
GaussianFilter
(sigma=1.0)¶ This algorithm applies a real space Gaussian filter to the image, as defined in the following publication:
I.T.Young, L.J. van Vliet,”Recursive implementation of the Gaussian filter”,Signal Processing, 44(1995), 139151
Parameters: sigma (float) – Width of the Gaussian filter 
GetSigma
()¶ Returns the current value of the filter’s width.
Return type: float

SetSigma
(width)¶ Sets the value of the filter’s width to the specified value.
Parameters: sigma (float) – Width of the Gaussian filter

SetQ
(q_param)¶ Sets the value of the filter’s Q parameter (see publication) to the specified value.
Parameters: q_param (float) – Filter’s Q parameter


class
Histogram
(bins, minimum, maximum)¶ This algorithm performs an histogram analysis of the image. The minimum and maximum pixel values of the histogram representation must be provided when the algorithm object is created, as well as the number of bins in the histogram. Bins are equally spaced and minimum and maximum values for each bin are automatically computed.
When the algorithm is applied to an image, the analysis is carried out. A python ‘list’ object containing in sequence the pixel counts for all the bins can the be recovered from the algorithm object.
Parameters:  bins (int) – Number of bins in the histogram
 minimum (float) – Minimum value in the histogram
 maximum – Maximum value in the histogram

GetBins
()¶ Returns the bins of the histogram representation
Return type: list of ints

GetBins
()