Commit d8baa460 authored by Manuel Günther's avatar Manuel Günther

New README and documentation strategy.

parent 4164be6e
......@@ -2,8 +2,7 @@
*.swp
*.pyc
*.so
*.so.*
CMakeLists.txt
*.dylib
bin
eggs
parts
......@@ -18,4 +17,3 @@ dist
build
*.egg
src/
opsnr.stt
......@@ -6,6 +6,7 @@ matrix:
env:
- secure: Ck4YRyeroQhNFEUe2UOs0xtvsgXlqHFUtJCvHV8doXowXHp9aHRJqQZRJyPrDLERxqzWr6q4L1NIJnjOKALiKN0UrmoVOhRrbblu3FS1W9RmjLVkzohsgzA+zp2C1PdrYwSMS8FFp1SmXORYCB1E2VMNdoBhfKZjAWwLobrxUiU=
- secure: h0vO8a9n55lXgKTIRFb2WFWpIAzgLfV9OLUaTynbTZBROAzK1M6D2uxA9hnE7tSaxn8jp8Hg7LeyPctn8GRubFMU+P5HxeOhNfkXz8GNv1bUUbwULCt15mTG9ioksvWqg2hTWf4OTGpTiTttPzgIrM/F2/daD/lMhKwHjaJ9YUg=
- BOB_DOCUMENTATION_SERVER=https://www.idiap.ch/software/bob/docs/latest/bioidiap/%s/master
- python: 3.2
env:
- NUMPYSPEC===1.8.0
......@@ -15,7 +16,7 @@ matrix:
before_install:
- sudo add-apt-repository -y ppa:biometrics/bob
- sudo apt-get update -qq
- sudo apt-get install -qq --force-yes texlive-latex-base texlive-latex-extra texlive-math-extra libboost-all-dev libblitz1-dev libatlas-dev libatlas-base-dev liblapack-dev libhdf5-serial-dev libvl-dev
- sudo apt-get install -qq --force-yes libboost-all-dev libblitz1-dev libatlas-dev libatlas-base-dev liblapack-dev libhdf5-serial-dev libvl-dev texlive-latex-base texlive-latex-extra texlive-math-extra texlive-latex-recommended texlive-fonts-recommended
- if [ -n "${NUMPYSPEC}" ]; then sudo apt-get install -qq gfortran; fi
- if [ -n "${NUMPYSPEC}" ]; then pip install --upgrade pip setuptools; fi
- if [ -n "${NUMPYSPEC}" ]; then pip install --find-links http://wheels.astropy.org/ --find-links http://wheels2.astropy.org/ --use-wheel numpy$NUMPYSPEC; fi
......
......@@ -2,79 +2,36 @@
.. Laurent El Shafey <Laurent.El-Shafey@idiap.ch>
.. Mon Apr 14 20:31:18 CEST 2014
.. image:: https://travis-ci.org/bioidiap/bob.ip.base.svg?branch=master
:target: https://travis-ci.org/bioidiap/bob.ip.base
.. image:: http://img.shields.io/badge/docs-stable-yellow.png
:target: http://pythonhosted.org/bob.ip.base/index.html
.. image:: http://img.shields.io/badge/docs-latest-orange.png
:target: https://www.idiap.ch/software/bob/docs/latest/bioidiap/bob.ip.base/master/index.html
.. image:: https://travis-ci.org/bioidiap/bob.ip.base.svg?branch=master
:target: https://travis-ci.org/bioidiap/bob.ip.base
.. image:: https://coveralls.io/repos/bioidiap/bob.ip.base/badge.png
:target: https://coveralls.io/r/bioidiap/bob.ip.base
.. image:: http://img.shields.io/github/tag/bioidiap/bob.ip.base.png
:target: https://github.com/bioidiap/bob.ip.base
.. image:: https://img.shields.io/badge/github-master-0000c0.png
:target: https://github.com/bioidiap/bob.ip.base/tree/master
.. image:: http://img.shields.io/pypi/v/bob.ip.base.png
:target: https://pypi.python.org/pypi/bob.ip.base
.. image:: http://img.shields.io/pypi/dm/bob.ip.base.png
:target: https://pypi.python.org/pypi/bob.ip.base
=================================
Python bindings for bob.ip.base
=================================
======================================
Basic Image Processing tools for Bob
======================================
This package contains a set of Pythonic bindings for Bob's Image Processing
tools.
This package contains Bob's Basic Image Processing tools.
Installation
------------
Install it through normal means, via PyPI or use ``zc.buildout`` to bootstrap
the package and run test units.
To install this package -- alone or together with other `Packages of Bob <https://github.com/idiap/bob/wiki/Packages>`_ -- please read the `Installation Instructions <https://github.com/idiap/bob/wiki/Installation>`_.
For Bob_ to be able to work properly, some dependent packages are required to be installed.
Please make sure that you have read the `Dependencies <https://github.com/idiap/bob/wiki/Dependencies>`_ for your operating system.
Documentation
-------------
For further documentation on this package, please read the `Stable Version <http://pythonhosted.org/bob.ip.base/index.html>`_ or the `Latest Version <https://www.idiap.ch/software/bob/docs/latest/bioidiap/bob.ip.base/master/index.html>`_ of the documentation.
For a list of tutorials on this or the other packages ob Bob_, or information on submitting issues, asking questions and starting discussions, please visit its website.
The latest version of the documentation can be found `here <https://www.idiap.ch/software/bob/docs/latest/bioidiap/bob.ip.base/master/index.html>`_.
Otherwise, you can generate the documentation for this package yourself, after installation, using Sphinx::
$ sphinx-build -b html doc sphinx
This shall place in the directory ``sphinx``, the current version for the
documentation of the package.
Testing
-------
You can run a set of tests using the nose test runner::
$ nosetests -sv
.. warning::
If Bob <= 1.2.1 is installed on your python path, nose will automatically
load the old version of the insulate plugin available in Bob, which will
trigger the loading of incompatible shared libraries (from Bob itself), in
to your working binary. This will cause a stack corruption. Either remove
the centrally installed version of Bob, or build your own version of Python
in which Bob <= 1.2.1 is not installed.
You can run our documentation tests using sphinx itself::
$ sphinx-build -b doctest doc sphinx
You can test overall test coverage with::
$ nosetests --with-coverage --cover-package=bob.ip.base
The ``coverage`` egg must be installed for this to work properly.
Development
-----------
To develop this package, install using ``zc.buildout``, using the buildout
configuration found on the root of the package::
$ python bootstrap.py
...
$ ./bin/buildout
Tweak the options in ``buildout.cfg`` to disable/enable verbosity and debug
builds.
.. _bob: https://www.idiap.ch/software/bob
......@@ -160,8 +160,7 @@ static auto blockOverlap = bob::extension::VariableDoc(
"block_overlap",
"(int, int)",
"The block overlap in both vertical and horizontal direction of the Multi-Block-DCTFeatures extractor, with read and write access",
".. note:: The ``block_overlap`` must be smaller than the :py:attr:`block_size`. "
"To set both the block size and the block overlap at the same time, use the :py:func:`set_block_and_overlap` function."
".. note:: The ``block_overlap`` must be smaller than the :py:attr:`block_size`."
);
PyObject* PyBobIpBaseDCTFeatures_getBlockOverlap(PyBobIpBaseDCTFeaturesObject* self, void*){
TRY
......
......@@ -253,7 +253,7 @@ PyObject* PyBobIpBaseFaceEyesNorm_getLastOffset(PyBobIpBaseFaceEyesNormObject* s
static auto geomNorm = bob::extension::VariableDoc(
"geom_norm",
":py:class:`bob.ip.base.GeonNorm`",
":py:class:`bob.ip.base.GeomNorm`",
"The geometric normalization class that was used to compute the last normalization, read access only"
);
PyObject* PyBobIpBaseFaceEyesNorm_getGeomNorm(PyBobIpBaseFaceEyesNormObject* self, void*){
......@@ -344,12 +344,12 @@ static auto extract = bob::extension::FunctionDoc(
.add_prototype("input, output, right_eye, left_eye")
.add_prototype("input, input_mask, output, output_mask, right_eye, left_eye")
.add_parameter("input", "array_like (2D)", "The input image to which FaceEyesNorm should be applied")
.add_parameter("output", "array_like (2D, float)", "The output image, which must be of size :py:attr:`cropped_size`")
.add_parameter("output", "array_like (2D, float)", "The output image, which must be of size :py:attr:`crop_size`")
.add_parameter("right_eye", "(float, float)", "The position of the right eye (or another landmark) in ``input`` image coordinates.")
.add_parameter("left_eye", "(float, float)", "The position of the left eye (or another landmark) in ``input`` image coordinates.")
.add_parameter("input_mask", "array_like (2D, bool)", "An input mask of valid pixels before geometric normalization, must be of same size as ``input``")
.add_parameter("output_mask", "array_like (2D, bool)", "The output mask of valid pixels after geometric normalization, must be of same size as ``output``")
.add_return("output", "array_like(2D, float)", "The resulting normalized face image, which is of size :py:attr:`cropped_size`")
.add_return("output", "array_like(2D, float)", "The resulting normalized face image, which is of size :py:attr:`crop_size`")
;
template <typename T>
......
......@@ -20,7 +20,7 @@ PyTypeObject PyBobIpBaseGSSKeypoint_Type = {
static auto GSSKeypoint_doc = bob::extension::ClassDoc(
BOB_EXT_MODULE_PREFIX ".GSSKeypoint",
"Structure to describe a keypoint on the :py:class:`GaussianScaleSpace`",
"Structure to describe a keypoint on the :py:class:`bob.ip.base.GaussianScaleSpace`",
"It consists of a scale sigma, a location (y,x) and an orientation."
).add_constructor(
bob::extension::FunctionDoc(
......
......@@ -244,7 +244,7 @@ static auto process = bob::extension::FunctionDoc(
.add_prototype("input, input_mask, output, output_mask, center")
.add_prototype("position, center", "transformed")
.add_parameter("input", "array_like (2D or 3D)", "The input image to which GeomNorm should be applied")
.add_parameter("output", "array_like (2D or 3D, float)", "The output image, which must be of size :py:attr:`cropped_size`")
.add_parameter("output", "array_like (2D or 3D, float)", "The output image, which must be of size :py:attr:`crop_size`")
.add_parameter("center", "(float, float)", "The transformation center in the given image; this will be placed to :py:attr:`crop_offset` in the output image")
.add_parameter("input_mask", "array_like (bool, 2D or 3D)", "An input mask of valid pixels before geometric normalization, must be of same size as ``input``")
.add_parameter("output_mask", "array_like (bool, 2D or 3D)", "The output mask of valid pixels after geometric normalization, must be of same size as ``output``")
......
......@@ -159,7 +159,7 @@ static int PyBobIpBaseGLCMProperty_init(PyObject* self, PyObject*, PyObject*) {
static auto GLCM_doc = bob::extension::ClassDoc(
BOB_EXT_MODULE_PREFIX ".GLCM",
"Objects of this class, after configuration, can compute Grey-Level Co-occurence Matrix of an image"
"Objects of this class, after configuration, can compute Grey-Level Co-occurence Matrix of an image",
"This class allows to extract a Grey-Level Co-occurence Matrix (GLCM) [Haralick1973]_. "
"A thorough tutorial about GLCM and the textural (so-called Haralick) properties that can be derived from it, can be found at: http://www.fp.ucalgary.ca/mhallbey/tutorial.htm. "
"A MatLab implementation can be found at: http://www.mathworks.ch/ch/help/images/ref/graycomatrix.html"
......
......@@ -321,7 +321,7 @@ static auto blockOverlap = bob::extension::VariableDoc(
"(int, int)",
"The block overlap in both vertical and horizontal direction of the Multi-Block-LBP extractor, with read and write access",
".. note:: The ``block_overlap`` must be smaller than the :py:attr:`block_size`. "
"To set both the block size and the block overlap at the same time, use the :py:func:`set_block_and_overlap` function."
"To set both the block size and the block overlap at the same time, use the :py:func:`set_block_size_and_overlap` function."
);
PyObject* PyBobIpBaseLBP_getBlockOverlap(PyBobIpBaseLBPObject* self, void*){
TRY
......@@ -346,7 +346,7 @@ static auto points = bob::extension::VariableDoc(
"int",
"The number of neighbors (usually 4, 8 or 16), with read and write access",
".. note:: The ``block_overlap`` must be smaller than the :py:attr:`block_size`. "
"To set both the block size and the block overlap at the same time, use the :py:func:`set_block_and_overlap` function."
"To set both the block size and the block overlap at the same time, use the :py:func:`set_block_size_and_overlap` function."
);
PyObject* PyBobIpBaseLBP_getPoints(PyBobIpBaseLBPObject* self, void*){
TRY
......
......@@ -250,36 +250,10 @@ autoclass_content = 'both'
autodoc_member_order = 'bysource'
autodoc_default_flags = ['members', 'undoc-members', 'inherited-members', 'show-inheritance']
def smaller_than(v1, v2):
"""Compares scipy/numpy version numbers"""
c1 = v1.split('.')
c2 = v2.split('.')[:len(c1)] #clip to the compared version
for i, k in enumerate(c2):
n1 = c1[i]
n2 = c2[i]
try:
n1 = int(n1)
n2 = int(n2)
except ValueError:
n1 = str(n1)
n2 = str(n2)
if n1 > n2: return False
return True
# Some name mangling to find the correct sphinx manuals for some packages
numpy_version = __import__('numpy').version.version
if smaller_than(numpy_version, '1.5.z'):
numpy_version = '.'.join(numpy_version.split('.')[:-1]) + '.x'
else:
numpy_version = '.'.join(numpy_version.split('.')[:-1]) + '.0'
numpy_manual = 'http://docs.scipy.org/doc/numpy-%s/' % numpy_version
# For inter-documentation mapping:
intersphinx_mapping = {
'http://docs.python.org/%d.%d/' % sys.version_info[:2]: None,
numpy_manual: None,
}
from bob.extension.utils import link_documentation
intersphinx_mapping = link_documentation()
def setup(app):
pass
......@@ -46,7 +46,7 @@ first creating the image and then initializing the larger image:
[4 5 6]]
>>> B = numpy.ndarray( (3, 5), dtype = numpy.float64 ) # A larger image of size 3x5
the scale function of |project| is then called to up-scale the image:
the :py:func:`bob.ip.base.scale` function of |project| is then called to up-scale the image:
.. doctest:: iptest
:options: +NORMALIZE_WHITESPACE
......@@ -137,7 +137,7 @@ Two types of Sobel filters exist: The vertical filter :math:`S_y` and the horizo
S_y = \left\lgroup\begin{array}{ccc} -1 & -2 & -1 \\ 0 & 0 & 0 \\ 1 & 2 & 1 \end{array}\right\rgroup \qquad
S_x = \left\lgroup\begin{array}{ccc} -1 & 0 & 1 \\ -2 & 0 & 2 \\ -1 & 0 & 1 \end{array}\right\rgroup
Both filters can be applied at the same time using the :py:func:`bob.ip.base.sobel` function, where the result of :math:`S_y`will be put to the first layer and :math:`S_x` to the second layer.
Both filters can be applied at the same time using the :py:func:`bob.ip.base.sobel` function, where the result of :math:`S_y` will be put to the first layer and :math:`S_x` to the second layer.
.. doctest:: iptest
:options: +NORMALIZE_WHITESPACE
......@@ -157,12 +157,12 @@ To compute rotation-dependent results, use the rotation matrix on the gradient v
:include-source: True
Normalizing images according to eye positions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Normalizing face images according to eye positions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For many biometric applications, for instance face recognition, the images are
For many face biometrics applications, for instance face recognition, the images are
geometrically normalized according to the eye positions. In such a case, the
first thing to do is to create an object of the class defining the image
first thing to do is to create an object of the :py:class:`bob.ip.base.FaceEyesNorm` class defining the image
properties of the geometrically normalized image (that will be generated when
applying the object):
......@@ -182,7 +182,12 @@ left eye usually has a higher x-coordinate than the right eye:
>>> face_image = bob.io.base.load( image_path )
>>> cropped_image = numpy.ndarray( (128, 128), dtype = numpy.float64 )
>>> face_eyes_norm( face_image, cropped_image, right_eye = (67, 47), left_eye = (62, 71) )
>>> face_eyes_norm( face_image, cropped_image, right_eye = (66, 47), left_eye = (62, 70) )
Now, let's have a look at the original and normalized face:
.. plot:: plot/face_eyes_norm.py
:include-source: True
Simple feature extraction
......@@ -206,10 +211,10 @@ position:
>>> lbp_local = lbp_extractor ( cropped_image, (69, 62) )
>>> # print the binary representation of the LBP
>>> print(bin ( lbp_local ))
0b11110000
0b1111000
or you can extract the LBP features for all pixels in the image. In this case
you need to get the required shape of the output image:
you need to get the required shape of the output image using the :py:class:`bob.ip.base.LBP` feature extractor:
.. doctest:: iptest
:options: +NORMALIZE_WHITESPACE
......@@ -222,7 +227,7 @@ you need to get the required shape of the output image:
>>> # print the binary representation of the pixel at the same location as above;
>>> # note that the index is shifted by 1 since the lbp image is smaller than the original
>>> print(bin ( lbp_output_image [ 68, 61 ] ))
0b11110000
0b1111000
.. Place here your external references
.. include:: links.rst
......@@ -4,14 +4,13 @@
..
.. Copyright (C) 2014 Idiap Research Institute, Martigny, Switzerland
=================================
Bob's Image Processing Routines
=================================
=======================================
Bob's Basic Image Processing Routines
=======================================
.. todolist::
This module contains base functionality from Bob bound to Python, available in
the C++ counter-part ``bob::ip``.
This Python module contains base functionality from Bob bound to Python, available in the C++ counter-part ``bob::ip::base``.
Documentation
-------------
......
import numpy
import math
import bob.io.base
import bob.ip.base
from bob.io.base.test_utils import datafile
# load a test image
face_image = bob.io.base.load(datafile('image_r10.hdf5', 'bob.ip.base', 'data/affine'))
# create FaceEyesNorm class
face_eyes_norm = bob.ip.base.FaceEyesNorm(eyes_distance = 65, crop_size = (128, 128), eyes_center = (32, 63.5))
# normalize image
normalized_image = face_eyes_norm( face_image, right_eye = (66, 47), left_eye = (62, 70) )
# plot results, including eye locations in original and normalized image
from matplotlib import pyplot
pyplot.figure(figsize=(8,4))
pyplot.subplot(121) ; pyplot.imshow(face_image, cmap='gray') ; pyplot.plot([47, 70], [66, 62], 'rx', ms=10, mew=2); pyplot.axis('tight'); pyplot.title('Original Image')
pyplot.subplot(122) ; pyplot.imshow(normalized_image, cmap='gray') ; pyplot.plot([31, 96], [32, 32], 'rx', ms=10, mew=2); pyplot.axis('tight'); pyplot.title('Cropped Image')
pyplot.show()
......@@ -180,7 +180,8 @@ setup(
},
classifiers = [
'Development Status :: 3 - Alpha',
'Framework :: Bob',
'Development Status :: 4 - Beta',
'Intended Audience :: Developers',
'License :: OSI Approved :: BSD License',
'Natural Language :: English',
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment