Python API¶
This section includes information for using the pure Python API of bob.ip.gabor
.
List of Classes and Functions¶
bob.ip.gabor.Wavelet 
A class that represents a Gabor wavelet in frequency domain 
bob.ip.gabor.Transform 
A class that represents a family of Gabor wavelets that can be used to 
bob.ip.gabor.Jet 
A Gabor jet contains the responses of all Gabor wavelets of the Gabor 
bob.ip.gabor.JetStatistics 
Computes statistics of a list of Gabor jets 
bob.ip.gabor.Similarity 
A class that computes different kind of similarity function, i.a., disparity corrected Gabor phase differences. 
bob.ip.gabor.Graph 
A class to extract Gabor jets from a Gabor transformed image (see 
bob.ip.gabor.load_jets ((hdf5) > jets) 
Loads a list of Gabor jets from the given HDF5 file, which needs to be open for reading. 
bob.ip.gabor.save_jets ((jets, hdf5) > None) 
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 normallylefteye[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 placedlast
: (int, int)The position of the last (bottomright) node that will be placed; depending on thestep
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 graphhdf5
:bob.io.base.HDF5File
An HDF5 file open for reading to load the nodes of the Gabor graph fromClass 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 ofbob.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 tonumber_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 thenodes
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
¶ Bases:
object
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 lengthtrafo_image
: array_like(complex, 3D)The result of the Gabor wavelet transform, i.e., ofbob.ip.gabor.Transform.transform()
position
: (int, int)The position, where the Gabor jet should be extractedcomplex
: array_like(complex, 3D)The complexvalued representation of a Gabor jetto_average
: [bob.ip.gabor.Jet
]Computes the average of the given Gabor jetsnormalize
: 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 fromjet
:bob.ip.gabor.Jet
The Gabor jet to copyconstructClass Members:

abs
¶ array(float,1D) <– The list of absolute values of the Gabor jet
Note
These values cannot be modified. Use
jet
instead.

complex
¶ array(complex,1D) <– The complex representation of the Gabor jet
Note
The complex representation is generated on the fly and is not stored anywhere in the object.

extract
(trafo_image, position[, normalize]) → None¶ Initializes the Gabor jet with the given complexvalued data extracted from the given trafo image at the given position
Parameters:
trafo_image
: array_like(complex, 3D)The result of the Gabor wavelet transform, i.e., ofbob.ip.gabor.Transform.transform()
position
: (int, int)The position, where the Gabor jet should be extractednormalize
: bool[default: True] Should the newly generated Gabor jet be normalized to unit Euclidean length?

init
(complex[, normalize]) → None¶ Initializes the Gabor jet with the given complexvalued data
Parameters:
complex
: array_like(complex,1D)The vector of complex data to initialize the Gabor jet withnormalize
: bool[default: True] Should the newly generated Gabor jet be normalized to unit Euclidean length?

jet
¶ array(float,2D) <– The absolute and phase values of the Gabor jet
The absolute values are stored in the first row
jet[0,:]
, while the phase values are stored in the second rowjet[1,:]
Note
Use this function to modify the Gabor jet, if required.

length
¶ int <– The number of elements in the Gabor jet
Note
You can also use the len(jet) function to get the length of the Gabor jet

load
(hdf5) → None¶ Loads the Gabor jet from the given HDF5 file
Parameters:
hdf5
:bob.io.base.HDF5File
An HDF5 file opened for reading

normalize
() → old_norm¶ Normalizes the Gabor jet to unit Euclidean length and returns its old length
Note
Only the absolute values
abs
are affected by the normalizationReturns:
old_norm
: floatThe Euclidean length of the Gabor jet before normalization

phase
¶ array(float,1D) <– The list of phase values of the Gabor jet
Note
These values cannot be modified. Use
jet
instead.

save
(hdf5) → None¶ Saves the Gabor jet to the given HDF5 file
Parameters:
hdf5
:bob.io.base.HDF5File
An HDF5 file open for writing

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 sameTransform
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 readingClass 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 forReturns:
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 forestimate_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 writingsave_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 with whereJet.length
:'ScalarProduct'
'Canberra'
Other similarity funcitons make use of the absolute values (
Jet.abs
) and the phase values (Jet.phase
):'AbsPhase'
'Disparity'
'PhaseDiff'
'PhaseDiffPlusCanberra'
Some of these functions make use of the kernel vector (
Transform.wavelet_frequencies
) and the disparity vector , 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 fromClass 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 betweenReturns:
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 shiftedreference
:bob.ip.gabor.Jet
The Gabor jets, towards which the phases should be shiftedReturns:
shifted
:bob.ip.gabor.Jet
A copy ofjet
, 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 comparedReturns:
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 is created by considering several center frequencies :
where with and and
Parameters:
number_of_scales
: int[default: 5] The number of scales of Gabor wavelets that should be creatednumber_of_directions
: int[default: 8] The number of directions of Gabor wavelets that should be createdsigma
: float[default: ] The spatial resolution of the Gabor waveletsk_max
: float[default: ] The highest frequency (the lowest scale) of Gabor wavelets; the default will resemble to the smallest wavelength of 4 pixelsk_fac
: float[default: ] The (logarithmic) distance between two scales of Gabor waveletspower_of_k
: float[default: 0] The 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 0hdf5
:bob.io.base.HDF5File
An HDF5 file open for reading to load the parametrization of the Gabor wavelet transform fromClass 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 forwidth
: 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: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 transformedoutput
: 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 is created in frequency domain as a Gaussian that is shifted from the origin of the frequency domain:
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 laterfrequency
: (float, float)The location of the Gabor wavelet in frequency domain; the values should be limited between andsigma
: float[default: ] The spatial resolution of the Gabor waveletpower_of_k
: float[default: 0] The 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 0Class 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:
Note
The function __call__ is a synonym for this function.
Parameters:
input
: array_like (complex, 2D)The image in frequency domain that should be transformedoutput
: array_like (complex, 2D)The image in frequency domain that should contain the transformed image; if given, must have the same size asinput
Returns:
output
: array_like (complex, 2D)The image in frequency domain that will contain the transformed image; will have the same size asinput
; 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
:  An HDF5 file open for reading
bob.io.base.HDF5File
Returns:
jets
: [ The list of Gabor jets read from file
bob.ip.gabor.Jet
]

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
:  An HDF5 file open for writing
jets
: [ The list of Gabor jets to write to file
bob.io.base.HDF5File
bob.ip.gabor.Jet
]