Python API¶
This section includes information for using the pure Python API of bob.ip.gabor
.
List of Classes and Functions¶
A class that represents a Gabor wavelet in frequency domain 

A class that represents a family of Gabor wavelets that can be used to perform a Gabor wavelet transform 

A Gabor jet contains the responses of all Gabor wavelets of the Gabor wavelet family at a certain position in the image 

Computes statistics of a list of Gabor jets 

A class that computes different kind of similarity function, i.a., disparity corrected Gabor phase differences. 

A class to extract Gabor jets from a Gabor transformed image (see 


Loads a list of Gabor jets from the given HDF5 file, which needs to be open for reading. 

Saves the given list of Gabor jets to the given HDF5 file, which needs to be open for writing. 
Detailed Information¶
 class bob.ip.gabor.Graph¶
Bases:
object
A class to extract Gabor jets from a Gabor transformed image (see
bob.ip.gabor.Transform.transform()
)The graph structure stores a list of nodes, where Gabor jets will be extracted from the images. These nodes are stored with absolute positions, so please assure that the image is large enough.
Constructor Documentation:
bob.ip.gabor.Graph (righteye, lefteye, between, along, above, below)
bob.ip.gabor.Graph (first, last, step)
bob.ip.gabor.Graph (nodes)
bob.ip.gabor.Graph (hdf5)
Creates a the Gabor graph
There are three different ways to create a Gabor graph. The first two ways will generate nodes in regular grid positions, while the third can specify the positions as a list of tuples.
Parameters:
righteye, lefteye
: (int, int)The position of the left and the right eye of the face in the image; the positions are with respect to the person in the image, so normally
lefteye[1] > righteye[0]
between
: intThe number of nodes that should be placed between the eyes (excluding both eye nosed)
along
: intThe number of nodes that should be placed to the left of the right eye and to the right of the left eye (excluding the eye positions)
above
: intThe number of nodes that should be placed above the eyes (excluding the eye positions)
below
: intThe number of nodes that should be placed below the eyes (excluding the eye positions)
first
: (int, int)The position of the first (topleft) node that will be placed
last
: (int, int)The position of the last (bottomright) node that will be placed; depending on the
step
parameter, the actual bottomright node might be beforelast
step
: (int, int)The distance between two each nodes (in vertical and horizontal direction)
nodes
: [(int, int)]The node positions that should be stored in the graph
hdf5
:bob.io.base.HDF5File
An HDF5 file open for reading to load the nodes of the Gabor graph from
Class Members:
 extract()¶
extract(trafo_image, jets) > None
extract(trafo_image) > jets
This function extracts all Gabor jets from the given trafo image for all nodes of the graph
The trafo image should have been created by a call to
bob.ip.gabor.Transform.transform()
. It must be assured that all nodes of the graph are inside the image boundaries of the trafo image.Note
The function __call__ is a synonym for this function.
Parameters:
trafo_image
: array_like (complex, 3D)The Gabor wavelet transformed image, e.g., the result of
bob.ip.gabor.Transform.transform()
jets
: [bob.ip.gabor.Jet
]The list of Gabor jets that will be filled during the extraction process; The number of jets must be identical to
number_of_nodes
, and the jets must have the correctbob.ip.gabor.Jet.length
.Returns:
jets
: [bob.ip.gabor.Jet
]The list of Gabor jets extracted at the
nodes
from the giventrafo_image
.
 load(hdf5) None ¶
Loads the list of node positions of the Gabor graph from the given HDF5 file
Parameters:
hdf5
:bob.io.base.HDF5File
An HDF5 file opened for reading
 nodes¶
[(int, int)] <– The list of node positions extracted by this graph
Warning
You can use this variable to reset the nodes in this graph, but only by using the
=
operator. Something likegraph.nodes[0] = (1,1)
will not have the expected outcome!
 number_of_nodes¶
int <– The number of nodes that this Graph will extract
 save(hdf5) None ¶
Saves the the list of node positions of the Gabor graph to the given HDF5 file
Parameters:
hdf5
:bob.io.base.HDF5File
An HDF5 file open for writing
 class bob.ip.gabor.Jet[source]¶
Bases:
bob.ip.gabor.Jet
A Gabor jet contains the responses of all Gabor wavelets of the Gabor wavelet family at a certain position in the image
The Gabor jet represents the local texture at a certain offset point of an image that it was extracted from. Commonly, the complexvalued Gabor jet is stored as a vector of absolute values and a vector of phase values. Also, usually the Gabor jet is normalized to unit Euclidean length.
Constructor Documentation:
bob.ip.gabor.Jet ([length])
bob.ip.gabor.Jet (trafo_image, position, [normalize])
bob.ip.gabor.Jet (complex, [normalize])
bob.ip.gabor.Jet (to_average, [normalize])
bob.ip.gabor.Jet (hdf5)
bob.ip.gabor.Jet (jet)
Creates a Gabor jet from various sources of data
The first constructor will create an uninitialized Gabor jet of the desired size
The second constructor will extract a Gabor jet from the given Gabor transformed image at the specified location
The third constructor will create a Gabor jet from a list of complex values
The fourth constructor will average the complex values of the given Gabor jets
The fifth constructor will load the Gabor jet from the given
bob.io.base.HDF5File
The last constructor will copy the information stored in the given
Jet
Parameters:
length
: int[default: 0] Creates an empty Gabor jet of the given length
trafo_image
: array_like(complex, 3D)The result of the Gabor wavelet transform, i.e., of
bob.ip.gabor.Transform.transform()
position
: (int, int)The position, where the Gabor jet should be extracted
complex
: array_like(complex, 3D)The complexvalued representation of a Gabor jet
to_average
: [bob.ip.gabor.Jet
]Computes the average of the given Gabor jets
normalize
: bool[default: True] Should the newly generated Gabor jet be normalized to unit Euclidean length?
hdf5
:bob.io.base.HDF5File
An HDF5 file open for reading to load the Gabor jet from
jet
:bob.ip.gabor.Jet
The Gabor jet to copyconstruct
Class Members:
 class bob.ip.gabor.JetStatistics¶
Bases:
object
Computes statistics of a list of Gabor jets
JetStatistics
compute the mean and variances of absolute and phase values of the given set of GaborJet
s. Usually, they are used to capture the average structure of a given key point in several images. Since the jet statistics are computed using disparity correction of the training jets, they don’t have to be 100% aligned to the keypoint location. Similarly to the Gabor jetSimilarity
, it allows to compute disparities of a given Gabor jet to the average location that thisJetStatistics
incorporate.The statistics of Gabor jets is computed elementwise. The mean and variance of the absolute values is computed assuming univariate Gaussian distribution of
Jet.abs
from all given Gabor jets. The mean phase is computed differently, i.e., by computing the average jet (using the accordingJet
constructor, while the phase variance is computed by computing the variances ofJet.phase
to the mean phase. Finally, the Statistics of a givenJet
can be computed using thelog_likelihood()
function. More details about the Gabor jet statistics can be found in section 3.3.3 of [Guenther2011].Constructor Documentation:
bob.ip.gabor.JetStatistics (jets, [gwt])
bob.ip.gabor.JetStatistics (hdf5)
Creates a JetStatistics from a list of Gabor jets, or reads it from file
When creating from a list of Gabor jets, all jets must have the same length and they should be extracted using the same
Transform
class. To be able to compute the disparity, thegwt
parameter has to be set to thatTransform
class. This can be done here in the constructor, or by settinggwt
.Particularly, when
save_gwt = False
was set in thesave()
function and, hence, it is not read by the constructor taking thebob.io.base.HDF5File
, it will not be available (andgwt
isNone
).Parameters:
jets
: [bob.ip.gabor.Jet
]The list of Gabor jets to compute statistics from, must all be extracted using the same
Transform
classgwt
:bob.ip.gabor.Transform
orNone
[Default:
None
] The Gabor wavelet family with which the Gabor jets were extractedhdf5
:bob.io.base.HDF5File
An HDF5 file open for reading
Class Members:
 disparity(jet) disp ¶
Computes the disparity for the given Gabor jet
The disparity calculation works only, when these statistics were calculated from Gabor jets of the same object at the same landmark. Then, the disparity estimates a distance vector from the given
jet
towards this location. The disparity estimation works well only in a limited area around the correct offset.For more information on how the disparity is computed, please read Appendix B.2 of [Guenther2011].
Parameters:
jet
:bob.ip.gabor.Jet
The Gabor jet to compute the disparity for
Returns:
disp
: (float,float)The disparity for the given jet
 gwt¶
bob.ip.gabor.Transform
orNone
<– The Gabor transform class with which the Gabor jets were extracted; can beNone
if the transform class is not stored in this object.
 log_likelihood(jet[, estimate_phase][, offset]) score ¶
Computes the loglikelihood for the given Gabor jet
This function estimates the loglikelihood of the given Gabor jet to fit to these statistics. It computes the disparity of the given
jet
, and estimates the probability of the absolute values and the disparity corrected phase values.When the Gabor jet should have been extracted with subpixel accuracy (which obviously isn’t possible), you can set this offset here, so that it is removed from the disparity estimate. In fact, you can directly pass the subpixel location of the Gabor jet, and the offset will be estimated automatically. This value can be left out, when not required.
Note
The function __call__ is a synonym for this function.
Parameters:
jet
:bob.ip.gabor.Jet
The Gabor jet to compute the likelihood for
estimate_phase
: bool[Default:
True
] Should the phase be included into the estimation?offset
: (float, float)[Default:
(0,0)
] Subpixel location offset, where the Gabor jet should have been extractedReturns:
score
: floatThe likelihood score for the given jet
 mean_abs¶
array(float,1D) <– The mean of absolute values of the Gabor Jets, read only
 mean_phase¶
array(float,1D) <– The mean of phase values of the Gabor jets, read only
 save(hdf5[, save_gwt]) None ¶
Saves the JetStatistics to the given HDF5 file
If several
JetStatistics
with the sameTransform
are written to the same file, it might be useful to write the transform only once. In this case, you can set thesave_gwt
parameter toFalse
.Parameters:
hdf5
:bob.io.base.HDF5File
An HDF5 file open for writing
save_gwt
: bool[Default:
True
] Should the Gabor wavelet transform class be written to the file as well?
 var_abs¶
array(float,1D) <– The variances of absolute values of the Gabor jets, read only
 var_phase¶
array(float,1D) <– The variances of phase values of the Gabor jets, read only
 class bob.ip.gabor.Similarity¶
Bases:
object
A class that computes different kind of similarity function, i.a., disparity corrected Gabor phase differences.
The implementation is according to [Guenther2011] and [Guenther2012], where all similarity functions are explained in more details. There are several types of Gabor jet similarity functions implemented. Some of them make use of the absolute values
Jet.abs
of the Gabor jets values, which are coded as \(a_j\) with \(j=1\dots J\) where \(J =\)Jet.length
:'ScalarProduct'
\[S_a(\mathcal J, \mathcal J') = \sum\limits_j a_j \cdot a_j'\]'Canberra'
\[S_C(\mathcal J, \mathcal J') = \sum\limits_j \frac{a_j  a_j'}{a_j + a_j'}\]
Other similarity funcitons make use of the absolute values \(a_j\) (
Jet.abs
) and the phase values \(\phi_j\) (Jet.phase
):'AbsPhase'
\[S_{\phi}(\mathcal J, \mathcal J') = \sum\limits_j a_j \cdot a_j' \cdot \cos(\phi_j  \phi_j')\]'Disparity'
\[S_D(\mathcal J, \mathcal J') = \sum\limits_j a_j \cdot a_j' \cdot \cos(\phi_j  \phi_j'  \vec k_j^T\vec d)\]'PhaseDiff'
\[S_P(\mathcal J, \mathcal J') = \sum\limits_j \cos(\phi_j  \phi_j'  \vec k_j^T\vec d)\]'PhaseDiffPlusCanberra'
\[S_{P+C}(\mathcal J, \mathcal J') = \sum\limits_j \left[ \frac{a_j  a_j'}{a_j + a_j'} + \cos(\phi_j  \phi_j'  \vec k_j^T\vec d) \right]\]
Some of these functions make use of the kernel vector \(\vec k_j\) (
Transform.wavelet_frequencies
) and the disparity vector \(\vec d\), which is estimated based on the given two Gabor jets. This procedure is described in more detail in Appendix B of [Guenther2011].Constructor Documentation:
bob.ip.gabor.Similarity (type, [transform])
bob.ip.gabor.Similarity (hdf5)
Creates a Gabor wavelet similarity function of the given type
Currently, several types of Gabor jet similarity functions are implemented. Please refer to [Guenther2012] for details.
Parameters:
type
: strThe type of the Gabor jet similarity function; might be one of (
'ScalarProduct'
,'Canberra'
,'AbsPhase'
,'Disparity'
,'PhaseDiff'
,'PhaseDiffPlusCanberra'
)transform
:bob.ip.gabor.Transform
The Gabor wavelet transform class that was used to generate the Gabor jets; only required for disparitybased similarity functions (‘Disparity’, ‘PhaseDiff’, ‘PhaseDiffPlusCanberra’)
hdf5
:bob.io.base.HDF5File
An HDF5 file open for reading to load the parametrization of the Gabor wavelet similarity from
Class Members:
 disparity(jet1, jet2) disparity ¶
This function computes the disparity vector for the given Gabor jets
This function is only available for convenience, it does not need to be called before
similarity()
is called.Parameters:
jet1, jet2
:bob.ip.gabor.Jet
The two Gabor jets to compute the disparity between
Returns:
disparity
: (float, float)The disparity vector estimated from the given Gabor jets
 last_disparity¶
(float, float) <– The disparity that was computed during the last call to
similarity()
ordisparity()
.
 load(hdf5) None ¶
Loads the parametrization of the Gabor jet similarity from the given HDF5 file
Parameters:
hdf5
:bob.io.base.HDF5File
An HDF5 file opened for reading
 save(hdf5) None ¶
Saves the parametrization of this Gabor jet similarity to the given HDF5 file
Parameters:
hdf5
:bob.io.base.HDF5File
An HDF5 file open for writing
 shift_phase(jet, reference) shifted ¶
This function returns a copy of the Gabor jet, for which the Gabor phases are shifted towards the reference Gabor jet
It uses the disparity estimation to compute the avarage disparity between the two Gabor jets. Afterwards, the phases of the given
jet
are adapted such that the disparity to thereference
jet is equaled out.Parameters:
jet
:bob.ip.gabor.Jet
The Gabor jets, whose phases should be shifted
reference
:bob.ip.gabor.Jet
The Gabor jets, towards which the phases should be shifted
Returns:
shifted
:bob.ip.gabor.Jet
A copy of
jet
, where the phases are shifted towardsreference
 similarity(jet1, jet2) sim ¶
This function computes the similarity between the two given Gabor jets
Depending on the
type
, different kinds of similarities are computed (see [Guenther2011] for details). Some of them will also compute the disparity from the first to the second Gabor jet, which can be retrieved bylast_disparity
.Note
The function __call__ is a synonym for this function.
Parameters:
jet1, jet2
:bob.ip.gabor.Jet
The two Gabor jets that should be compared
Returns:
sim
: floatThe similarity between the two Gabor jets; more similar Gabor jets will get higher similarity values
 transform¶
bob.ip.gabor.Transform
orNone
<– The Gabor wavelet transform used in the similarity class; can beNone
for similarity functions that do not compute disparities
 type¶
str <– The type of the Gabor jet similarity function
 class bob.ip.gabor.Transform¶
Bases:
object
A class that represents a family of Gabor wavelets that can be used to perform a Gabor wavelet transform
The implementation is according to [Guenther2011], where the whole procedure is explained in more detail.
Note
In opposition to the
Wavelet
class, here all input and output images are considered to be in spatial domain.Constructor Documentation:
bob.ip.gabor.Transform ([number_of_scales], [number_of_directions], [sigma], [k_max], [k_fac], [power_of_k], [dc_free], [epsilon])
bob.ip.gabor.Transform (hdf5)
Creates a Gabor wavelet transform for the given parametrization
The family of Gabor wavelets \(\check\psi_{\vec k_j}\) is created by considering several center frequencies \(\vec k_j\):
\[\begin{split}\vec k_j = k_{\zeta} \left\{ \begin{array}{c} \cos \vartheta_{\nu} \\ \sin \vartheta_{\nu} \end{array}\right\}\end{split}\]where \(k_{\zeta} = k_{max} \cdot k_{fac}^{\zeta}\) with \(\zeta = \{0,\dots,\zeta_{max}1\}\) and \(\vartheta_{\nu} = \frac{\nu \cdot 2\pi}{\nu_{max}}\) and \(\nu = \{0,\dots,\nu_{max}1\}\)
Parameters:
number_of_scales
: int[default: 5] The number of scales \(\zeta_{max}\) of Gabor wavelets that should be created
number_of_directions
: int[default: 8] The number of directions \(\nu_{max}\) of Gabor wavelets that should be created
sigma
: float[default: \(2\pi\)] The spatial resolution \(\sigma\) of the Gabor wavelets
k_max
: float[default: \(\pi/2\)] The highest frequency (the lowest scale) of Gabor wavelets; the default will resemble to the smallest wavelength of 4 pixels
k_fac
: float[default: \(\sqrt{\frac12}\)] The (logarithmic) distance between two scales of Gabor wavelets
power_of_k
: float[default: 0] The \(\lambda\) factor to regularize the Gabor wavelet prefactor to generate comparable results for images, see Appendix C of [Guenther2011]
dc_free
: bool[default: True] Should the Gabor wavelet be without DC factor (i.e. should the integral under the wavelet in spatial domain vanish)?
epsilon
: float[default: 1e10] For speed reasons: all wavelet pixels in frequency domain with an absolute value below this should be considered as 0
hdf5
:bob.io.base.HDF5File
An HDF5 file open for reading to load the parametrization of the Gabor wavelet transform from
Class Members:
 dc_free¶
bool <– Are the Gabor wavelets DC free?
 generate_wavelets(height, width) None ¶
This function generates the Gabor wavelets for the given image resolution
This function is only available for convenience, it does not need to be called before
transform()
is called.Parameters:
height
: intThe height of the image to generate the wavelets for
width
: intThe width of the image to generate the wavelets for
 k_fac¶
float <– The logarithmic distance between two levels of Gabor wavelets
 k_max¶
float <– The highest frequency of Gabor wavelets
 load(hdf5) None ¶
Loads the parametrization of the Gabor wavelet transform from the given HDF5 file
Parameters:
hdf5
:bob.io.base.HDF5File
An HDF5 file opened for reading
 number_of_directions¶
int <– The number of directions (orientations) of Gabor wavelets
 number_of_scales¶
int <– The number of scales (levels) of Gabor wavelets
 number_of_wavelets¶
int <– The number of Gabor wavelets (i.e, the number of directions times the number of scales) of this class
 power_of_k¶
float <– The adaptation of the Gabor wavelet scales to get homogeneous values
 save(hdf5) None ¶
Saves the parametrization of this Gabor wavelet transform to the given HDF5 file
Parameters:
hdf5
:bob.io.base.HDF5File
An HDF5 file open for writing
 sigma¶
float <– The extend of the Gabor wavelets
 transform(input[, output]) output ¶
This function transforms the given input image to the output trafo image
The input image must be of two dimensions and might be of any supported type:
uint8
,float
orcomplex
, whereas the output needs to be of 3 dimensions withcomplex
type and of shape (number_of_wavelets
, input.shape[0], input.shape[1]). The transform is defined as:\[\forall j \forall \vec \omega : \mathcal T_{\vec k_j}(\vec \omega) = \mathcal I(\vec \omega) \cdot \psi_{\vec k_j}(\vec \omega)\]Both the input image and the output are expected to be in spatial domain, so don’t perform an FFT on the input image before calling this function.
Note
The function __call__ is a synonym for this function.
Parameters:
input
: array_like (2D)The image in spatial domain that should be transformed
output
: array_like (complex, 3D)The transformed image in spatial domain that should contain the transformed image; if given, must have shape (
number_of_wavelets
, input.shape[0], input.shape[1])Returns:
output
: array_like (complex, 3D)The transformed image in spatial domain that will contain the transformed image; will have shape (
number_of_wavelets
, input.shape[0], input.shape[1]); identical to theoutput
parameter, if given
 wavelet_frequencies¶
[(float, float), …] <– The central frequencies of the Gabor wavelets, in the same order as in
wavelets
 wavelets¶
[
Wavelet
] <– The list of Gabor wavelets used in this transformNote
The wavelets will be generated either by a call to
generate_wavelets()
or by a call totransform()
. Before one of these functions is called, no wavelet will be generated.
 class bob.ip.gabor.Wavelet¶
Bases:
object
A class that represents a Gabor wavelet in frequency domain
The implementation is according to [Guenther2011], where the whole procedure is explained in more detail.
Note
In this class, all input and output images are considered to be in frequency domain.
Constructor Documentation:
bob.ip.gabor.Wavelet (resolution, frequency, [sigma], [power_of_k], [dc_free], [epsilon])
Creates a Gabor wavelet in frequency domain for the given parametrization
The Gabor wavelet \(\check\psi_{\vec k}\) is created in frequency domain as a Gaussian that is shifted from the origin of the frequency domain:
\[\check\psi_{\vec k}(\vec \omega) = k^{\lambda} \left\{ e^{\frac{\sigma^2(\vec \omega  \vec k)^2}{2\vec k^2}}  {e^{\frac{\sigma^2(\vec \omega^2 + \vec k^2)}{2\vec k^2}}}\right\}\]Parameters:
resolution
: (int, int)The resolution (height, width) of the Gabor wavelet; this must be the same resolution as the image that the Gabor wavelet is applied on later
frequency
: (float, float)The location \(\vec k = (ky, kx)\) of the Gabor wavelet in frequency domain; the values should be limited between \(\pi\) and \(\pi\)
sigma
: float[default: \(2\pi\)] The spatial resolution \(\sigma\) of the Gabor wavelet
power_of_k
: float[default: 0] The \(\lambda\) factor to regularize the Gabor wavelet prefactor to generate comparable results for images, see Appendix C of [Guenther2011]
dc_free
: bool[default: True] Should the Gabor wavelet be without DC factor (i.e. should the integral under the wavelet in spatial domain vanish)?
epsilon
: float[default: 1e10] For speed reasons: all wavelet pixels in frequency domain with an absolute value below this should be considered as 0
Class Members:
 transform(input[, output]) output ¶
This function transforms the given input image to the output image
Both images are considered to be in frequency domain and need to have the same resolution and to be of complex type. The resolution must be the same as the one defined in the constructor. The transform is defined as:
\[\forall \vec \omega : \mathcal T_{\vec k}(\vec \omega) = \mathcal I(\vec \omega) \cdot \psi_{\vec k}(\vec \omega)\]Note
The function __call__ is a synonym for this function.
Parameters:
input
: array_like (complex, 2D)The image in frequency domain that should be transformed
output
: array_like (complex, 2D)The image in frequency domain that should contain the transformed image; if given, must have the same size as
input
Returns:
output
: array_like (complex, 2D)The image in frequency domain that will contain the transformed image; will have the same size as
input
; is identical to theoutput
parameter, if given
 wavelet¶
2Darray complex <– The image representation of the Gabor wavelet in frequency domain
The image representation is generated on the fly (since the original data format is different), the data format is float. To obtain the image representation in spatial domain, please perform a
bob.sp.ifft()
on the returned image.
 bob.ip.gabor.load_jets(hdf5) jets [source]¶
Loads a list of Gabor jets from the given HDF5 file, which needs to be open for reading.
Parameters:
hdf5
bob.io.base.HDF5File
An HDF5 file open for reading
Returns:
jets
[bob.ip.gabor.Jet
]The list of Gabor jets read from file
 bob.ip.gabor.save_jets(jets, hdf5) None [source]¶
Saves the given list of Gabor jets to the given HDF5 file, which needs to be open for writing.
Parameters:
hdf5
bob.io.base.HDF5File
An HDF5 file open for writing
jets
[bob.ip.gabor.Jet
]The list of Gabor jets to write to file