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 perform a Gabor wavelet transform
`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
`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.Transform.transform()`)
`bob.ip.gabor.load_jets`(hdf5)	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)	Saves the given list of Gabor jets to the given HDF5 file, which needs to be open for writing.

Detailed Information¶

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:

hdf5bob.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:

hdf5bob.io.base.HDF5File
An HDF5 file open for writing

jets[bob.ip.gabor.Jet]
The list of Gabor jets to write to file

bob.ip.gabor.get_config()[source]¶: Returns a string containing the configuration information.

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 complex-valued 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 complex-valued 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 copy-construct

Class Members:

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 : int

The number of nodes that should be placed between the eyes (excluding both eye nosed)

along : int

The 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 : int

The number of nodes that should be placed above the eyes (excluding the eye positions)

below : int

The number of nodes that should be placed below the eyes (excluding the eye positions)

first : (int, int)

The position of the first (top-left) node that will be placed

last : (int, int)

The position of the last (bottom-right) node that will be placed; depending on the step parameter, the actual bottom-right node might be before last

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 correct bob.ip.gabor.Jet.length.

Returns:

jets : [bob.ip.gabor.Jet]

The list of Gabor jets extracted at the nodes from the given trafo_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 like graph.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.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 Gabor Jets. 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 jet Similarity, it allows to compute disparities of a given Gabor jet to the average location that this JetStatistics incorporate.

The statistics of Gabor jets is computed element-wise. 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 according Jet constructor, while the phase variance is computed by computing the variances of Jet.phase to the mean phase. Finally, the Statistics of a given Jet can be computed using the log_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, the gwt parameter has to be set to that Transform class. This can be done here in the constructor, or by setting gwt.

Particularly, when save_gwt = False was set in the save() function and, hence, it is not read by the constructor taking the bob.io.base.HDF5File, it will not be available (and gwt is None).

Parameters:

jets : [bob.ip.gabor.Jet]

The list of Gabor jets to compute statistics from, must all be extracted using the same Transform class

gwt : bob.ip.gabor.Transform or None

[Default: None] The Gabor wavelet family with which the Gabor jets were extracted

hdf5 : 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 or None <– The Gabor transform class with which the Gabor jets were extracted; can be None if the transform class is not stored in this object.

log_likelihood(jet[, estimate_phase][, offset]) → score¶

Computes the log-likelihood for the given Gabor jet

This function estimates the log-likelihood 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 sub-pixel 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 sub-pixel 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)] Sub-pixel location offset, where the Gabor jet should have been extracted

Returns:

score : float

The 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 same Transform are written to the same file, it might be useful to write the transform only once. In this case, you can set the save_gwt parameter to False.

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 : str

The 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 disparity-based 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() or disparity().

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 the reference 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 towards reference

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 by last_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 : float

The similarity between the two Gabor jets; more similar Gabor jets will get higher similarity values

transform¶: bob.ip.gabor.Transform or None <– The Gabor wavelet transform used in the similarity class; can be None 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: 1e-10] 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 : int

The height of the image to generate the wavelets for

width : int

The 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 or complex, whereas the output needs to be of 3 dimensions with complex 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 the output 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 transform

Note

The wavelets will be generated either by a call to generate_wavelets() or by a call to transform(). 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: 1e-10] 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 the output parameter, if given

wavelet¶

2D-array 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.