Commit b9af7a82 authored by André Anjos's avatar André Anjos 💬

Re-estructured Preprocessor to simplify experimentation and configuration

parent a0aed3f5
......@@ -20,8 +20,23 @@ or the attribute ``sub_directory`` in a configuration file loaded **after**
this resource.
"""
from ..preprocessor import FingerCrop
preprocessor = FingerCrop()
from ..preprocessor import Padder, TomesLeeMask, HuangNormalization, NoFilter
from ..preprocessor import Preprocessor
# Filter sizes for the vertical "high-pass" filter
FILTER_HEIGHT = 4
FILTER_WIDTH = 40
# Padding (to create a buffer during normalization)
PAD_WIDTH = 5
PAD_CONST = 51
preprocessor = Preprocessor(
mask=TomesLeeMask(filter_height=FILTER_HEIGHT, filter_width=FILTER_WIDTH),
normalize=HuangNormalization(padding_width=PAD_WIDTH,
padding_constant=PAD_CONST),
filter=NoFilter(),
)
"""Preprocessing using gray-level based finger cropping and no post-processing
"""
......
......@@ -20,8 +20,23 @@ or the attribute ``sub_directory`` in a configuration file loaded **after**
this resource.
"""
from ..preprocessor import FingerCrop
preprocessor = FingerCrop()
from ..preprocessor import Padder, TomesLeeMask, HuangNormalization, NoFilter
from ..preprocessor import Preprocessor
# Filter sizes for the vertical "high-pass" filter
FILTER_HEIGHT = 4
FILTER_WIDTH = 40
# Padding (to create a buffer during normalization)
PAD_WIDTH = 5
PAD_CONST = 51
preprocessor = Preprocessor(
mask=TomesLeeMask(filter_height=FILTER_HEIGHT, filter_width=FILTER_WIDTH),
normalize=HuangNormalization(padding_width=PAD_WIDTH,
padding_constant=PAD_CONST),
filter=NoFilter(),
)
"""Preprocessing using gray-level based finger cropping and no post-processing
"""
......
......@@ -20,8 +20,23 @@ or the attribute ``sub_directory`` in a configuration file loaded **after**
this resource.
"""
from ..preprocessor import FingerCrop
preprocessor = FingerCrop()
from ..preprocessor import Padder, TomesLeeMask, HuangNormalization, NoFilter
from ..preprocessor import Preprocessor
# Filter sizes for the vertical "high-pass" filter
FILTER_HEIGHT = 4
FILTER_WIDTH = 40
# Padding (to create a buffer during normalization)
PAD_WIDTH = 5
PAD_CONST = 51
preprocessor = Preprocessor(
mask=TomesLeeMask(filter_height=FILTER_HEIGHT, filter_width=FILTER_WIDTH),
normalize=HuangNormalization(padding_width=PAD_WIDTH,
padding_constant=PAD_CONST),
filter=NoFilter(),
)
"""Preprocessing using gray-level based finger cropping and no post-processing
"""
......
#!/usr/bin/env python
# vim: set fileencoding=utf-8 :
'''Database definitions for Vein Recognition'''
import numpy
class AnnotatedArray(numpy.ndarray):
"""Defines a numpy array subclass that can carry its own metadata
Copied from: https://docs.scipy.org/doc/numpy-1.12.0/user/basics.subclassing.html#slightly-more-realistic-example-attribute-added-to-existing-array
"""
def __new__(cls, input_array, metadata=None):
obj = numpy.asarray(input_array).view(cls)
obj.metadata = metadata if metadata is not None else dict()
return obj
def __array_finalize__(self, obj):
if obj is None: return
self.metadata = getattr(obj, 'metadata', dict())
......@@ -4,80 +4,93 @@
import numpy
from bob.bio.base.database import BioFile, BioDatabase
from . import AnnotatedArray
class File(BioFile):
"""
Implements extra properties of vein files for the Vera Fingervein database
"""
Implements extra properties of vein files for the Vera Fingervein database
Parameters:
f (object): Low-level file (or sample) object that is kept inside
"""
def __init__(self, f):
Parameters:
super(File, self).__init__(client_id=f.finger.unique_name, path=f.path,
file_id=f.id)
self.__f = f
f (object): Low-level file (or sample) object that is kept inside
"""
def mask(self, shape):
"""Returns the binary mask from the ROI annotations available"""
def __init__(self, f):
return poly_to_mask(shape, self.__f.roi())
super(File, self).__init__(client_id=f.finger.unique_name, path=f.path,
file_id=f.id)
self.__f = f
def load(self, *args, **kwargs):
"""(Overrides base method) Loads both image and mask"""
def load(self, *args, **kwargs):
"""(Overrides base method) Loads both image and mask"""
image = super(File, self).load(*args, **kwargs)
roi = self.__f.roi()
image = super(File, self).load(*args, **kwargs)
# calculates the 90 degrees anti-clockwise rotated RoI points
h, w = image.shape
roi = [(x,-y+h) for k in roi]
# image is upside, whereas this package requires fingers to be horizontal
return numpy.rot90(image)
return ImageWithAnnotation(numpy.rot90(image), metadata=dict(mask=roi))
class Database(BioDatabase):
"""
Implements verification API for querying Vera Fingervein database.
"""
"""
Implements verification API for querying Vera Fingervein database.
"""
def __init__(self, **kwargs):
def __init__(self, **kwargs):
super(Database, self).__init__(name='fv3d', **kwargs)
from bob.db.fv3d.query import Database as LowLevelDatabase
self.__db = LowLevelDatabase()
super(Database, self).__init__(name='fv3d', **kwargs)
from bob.db.fv3d.query import Database as LowLevelDatabase
self.__db = LowLevelDatabase()
self.low_level_group_names = ('train', 'dev', 'eval')
self.high_level_group_names = ('world', 'dev', 'eval')
self.low_level_group_names = ('train', 'dev', 'eval')
self.high_level_group_names = ('world', 'dev', 'eval')
def groups(self):
def groups(self):
return self.convert_names_to_highlevel(self.__db.groups(),
self.low_level_group_names, self.high_level_group_names)
return self.convert_names_to_highlevel(self.__db.groups(),
self.low_level_group_names, self.high_level_group_names)
def client_id_from_model_id(self, model_id, group='dev'):
"""Required as ``model_id != client_id`` on this database"""
def client_id_from_model_id(self, model_id, group='dev'):
"""Required as ``model_id != client_id`` on this database"""
return self.__db.finger_name_from_model_id(model_id)
return self.__db.finger_name_from_model_id(model_id)
def model_ids_with_protocol(self, groups=None, protocol=None, **kwargs):
def model_ids_with_protocol(self, groups=None, protocol=None, **kwargs):
groups = self.convert_names_to_lowlevel(groups,
self.low_level_group_names, self.high_level_group_names)
return self.__db.model_ids(groups=groups, protocol=protocol)
groups = self.convert_names_to_lowlevel(groups,
self.low_level_group_names, self.high_level_group_names)
return self.__db.model_ids(groups=groups, protocol=protocol)
def objects(self, groups=None, protocol=None, purposes=None,
model_ids=None, **kwargs):
def objects(self, groups=None, protocol=None, purposes=None,
model_ids=None, **kwargs):
groups = self.convert_names_to_lowlevel(groups,
self.low_level_group_names, self.high_level_group_names)
retval = self.__db.objects(groups=groups, protocol=protocol,
purposes=purposes, model_ids=model_ids, **kwargs)
groups = self.convert_names_to_lowlevel(groups,
self.low_level_group_names, self.high_level_group_names)
retval = self.__db.objects(groups=groups, protocol=protocol,
purposes=purposes, model_ids=model_ids, **kwargs)
return [File(f) for f in retval]
return [File(f) for f in retval]
def annotations(self, file):
return None
def annotations(self, file):
return None
......@@ -42,7 +42,7 @@ class Database(BioDatabase):
model_ids=None, **kwargs):
retval = self._db.objects(groups=groups, protocol=protocol,
purposes=purposes, model_ids=model_ids, **kwargs)
purposes=purposes, model_ids=model_ids, **kwargs)
return [File(f) for f in retval]
......
......@@ -5,6 +5,8 @@
from bob.bio.base.database import BioFile, BioDatabase
from . import AnnotatedArray
class File(BioFile):
"""
......@@ -20,23 +22,17 @@ class File(BioFile):
def __init__(self, f):
super(File, self).__init__(client_id=f.unique_finger_name, path=f.path,
file_id=f.id)
file_id=f.id)
self.__f = f
def mask(self):
"""Returns the binary mask from the ROI annotations available"""
from ..preprocessor.utils import poly_to_mask
# The size of images in this database is (250, 665) pixels (h, w)
return poly_to_mask((250, 665), self.__f.roi())
def load(self, *args, **kwargs):
"""(Overrides base method) Loads both image and mask"""
image = super(File, self).load(*args, **kwargs)
return image, self.mask()
roi = self.__f.roi()
mask = poly_to_mask(image.shape, roi)
return AnnotatedArray(image, metadata=dict(mask=mask, roi=roi))
class Database(BioDatabase):
......@@ -56,28 +52,32 @@ class Database(BioDatabase):
def groups(self):
return self.convert_names_to_highlevel(self._db.groups(),
self.low_level_group_names, self.high_level_group_names)
self.low_level_group_names, self.high_level_group_names)
def client_id_from_model_id(self, model_id, group='dev'):
"""Required as ``model_id != client_id`` on this database"""
return self._db.finger_name_from_model_id(model_id)
def model_ids_with_protocol(self, groups=None, protocol=None, **kwargs):
groups = self.convert_names_to_lowlevel(groups,
self.low_level_group_names, self.high_level_group_names)
self.low_level_group_names, self.high_level_group_names)
return self._db.model_ids(groups=groups, protocol=protocol)
def objects(self, groups=None, protocol=None, purposes=None,
model_ids=None, **kwargs):
groups = self.convert_names_to_lowlevel(groups,
self.low_level_group_names, self.high_level_group_names)
self.low_level_group_names, self.high_level_group_names)
retval = self._db.objects(groups=groups, protocol=protocol,
purposes=purposes, model_ids=model_ids, **kwargs)
purposes=purposes, model_ids=model_ids,
**kwargs)
return [File(f) for f in retval]
def annotations(self, file):
return None
from .FingerCrop import FingerCrop
from .mask import Padder, Masker, NoMask, AnnotatedRoIMask
from .mask import KonoMask, LeeMask, TomesLeeMask
from .normalize import Normalizer, NoNormalization, HuangNormalization
from .filters import Filter, NoFilter, HistogramEqualization
from .preprocessor import Preprocessor
# gets sphinx autodoc done right - don't remove it
def __appropriate__(*args):
"""Says object was actually declared here, an not on the import module.
Parameters:
*args: An iterable of objects to modify
Resolves `Sphinx referencing issues
<https://github.com/sphinx-doc/sphinx/issues/3048>`
"""
for obj in args: obj.__module__ = __name__
__appropriate__(
Padder,
Masker,
NoMask,
AnnotatedRoIMask,
KonoMask,
LeeMask,
TomesLeeMask,
Normalizer,
NoNormalization,
HuangNormalization,
Filter,
NoFilter,
HistogramEqualization,
Preprocessor,
)
__all__ = [_ for _ in dir() if not _.startswith('_')]
#!/usr/bin/env python
# vim: set fileencoding=utf-8 :
'''Base utilities for mask processing'''
import numpy
import scipy.ndimage
from .utils import poly_to_mask
class Padder(object):
"""A class that pads the input image returning a new object
Parameters:
padding_width (:py:obj:`int`, optional): How much padding (in pixels) to
add around the borders of the input image. We normally always keep this
value on its default (5 pixels). This parameter is always used before
normalizing the finger orientation.
padding_constant (:py:obj:`int`, optional): What is the value of the pixels
added to the padding. This number should be a value between 0 and 255.
(From Pedro Tome: for UTFVP (high-quality samples), use 0. For the VERA
Fingervein database (low-quality samples), use 51 (that corresponds to
0.2 in a float image with values between 0 and 1). This parameter is
always used before normalizing the finger orientation.
"""
def __init__(self, padding_width = 5, padding_constant = 51):
self.padding_width = padding_width
self.padding_constant = padding_constant
def __call__(self, image):
'''Inputs an image, returns a padded (larger) image
Parameters:
image (numpy.ndarray): A 2D numpy array of type ``uint8`` with the
input image
Returns:
numpy.ndarray: A 2D numpy array of the same type as the input, but with
the extra padding
'''
return numpy.pad(image, self.padding_width, 'constant',
constant_values = self.padding_constant)
class Masker(object):
"""This is the base class for all maskers
It defines the minimum requirements for all derived masker classes.
"""
def __init__(self):
pass
def __call__(self, image):
"""Overwrite this method to implement your masking method
Parameters:
image (numpy.ndarray): A 2D numpy array of type ``uint8`` with the
input image
Returns:
numpy.ndarray: A 2D numpy array of type boolean with the caculated
mask. ``True`` values correspond to regions where the finger is
situated
"""
raise NotImplemented('You must implement the __call__ slot')
class NoMask(object):
"""Implements no masking - i.e. returns a mask the same size as input
"""
def __init__(self):
pass
def __call__(self, image):
"""Returns a big mask
Parameters:
image (numpy.ndarray): A 2D numpy array of type ``uint8`` with the
input image
Returns:
numpy.ndarray: A 2D numpy array of type boolean with the caculated
mask. ``True`` values correspond to regions where the finger is
situated
"""
return numpy.ones(image.shape, dtype='bool')
class AnnotatedRoIMask(object):
"""Devises the mask from the annotated RoI"""
def __init__(self):
pass
def __call__(self, image):
"""Returns a mask extrapolated from RoI annotations
Parameters:
image (bob.bio.vein.database.AnnotatedArray): A 2D numpy array of type
``uint8`` with the input image containing an attribute called
``metadata`` (a python dictionary). The ``metadata`` object just
contain a key called ``roi`` containing the annotated points
Returns:
numpy.ndarray: A 2D numpy array of type boolean with the caculated
mask. ``True`` values correspond to regions where the finger is
situated
"""
return poly_to_mask(image.shape, image.metadata['roi'])
class KonoMask(Masker):
"""Estimates the finger region given an input NIR image using Kono et al.
This method is based on the work of M. Kono, H. Ueki and S. Umemura.
Near-infrared finger vein patterns for personal identification, Applied
Optics, Vol. 41, Issue 35, pp. 7429-7436 (2002).
Parameters:
sigma (:py:obj:`float`, optional): The standard deviation of the gaussian
blur filter to apply for low-passing the input image (background
extraction). Defaults to ``5``.
padder (:py:class:`Padder`, optional): If passed, will pad the image before
evaluating the mask. The returned value will have the padding removed and
is, therefore, of the exact size of the input image.
"""
def __init__(self, sigma=5, padder=None):
self.sigma = sigma
self.padder = padder
def __call__(self, image):
'''Inputs an image, returns a mask (numpy boolean array)
Parameters:
image (numpy.ndarray): A 2D numpy array of type ``uint8`` with the
input image
Returns:
numpy.ndarray: A 2D numpy array of type boolean with the caculated
mask. ``True`` values correspond to regions where the finger is
situated
'''
image = image if self.padder is None else self.padder(image)
img_h,img_w = image.shape
# Determine lower half starting point
if numpy.mod(img_h,2) == 0:
half_img_h = img_h/2 + 1
else:
half_img_h = numpy.ceil(img_h/2)
#Construct filter kernel
winsize = numpy.ceil(4*self.sigma)
x = numpy.arange(-winsize, winsize+1)
y = numpy.arange(-winsize, winsize+1)
X, Y = numpy.meshgrid(x, y)
hy = (-Y/(2*math.pi*self.sigma**4)) * \
numpy.exp(-(X**2 + Y**2)/(2*self.sigma**2))
# Filter the image with the directional kernel
fy = scipy.ndimage.convolve(image, hy, mode='nearest')
# Upper part of filtred image
img_filt_up = fy[0:half_img_h,:]
y_up = img_filt_up.argmax(axis=0)
# Lower part of filtred image
img_filt_lo = fy[half_img_h-1:,:]
y_lo = img_filt_lo.argmin(axis=0)
# Fill region between upper and lower edges
finger_mask = numpy.ndarray(image.shape, numpy.bool)
finger_mask[:,:] = False
for i in range(0,img_w):
finger_mask[y_up[i]:y_lo[i]+image.shape[0]-half_img_h+2,i] = True
if not self.padder:
return finger_mask
else:
w = self.padder.padding_width
return finger_mask[w:-w,w:-w]
class LeeMask(Masker):
"""Estimates the finger region given an input NIR image using Lee et al.
This method is based on the work of Finger vein recognition using
minutia-based alignment and local binary pattern-based feature extraction,
E.C. Lee, H.C. Lee and K.R. Park, International Journal of Imaging Systems
and Technology, Volume 19, Issue 3, September 2009, Pages 175--178, doi:
10.1002/ima.20193
This code is based on the Matlab implementation by Bram Ton, available at:
https://nl.mathworks.com/matlabcentral/fileexchange/35752-finger-region-localisation/content/lee_region.m
In this method, we calculate the mask of the finger independently for each
column of the input image. Firstly, the image is convolved with a [1,-1]
filter of size ``(self.filter_height, self.filter_width)``. Then, the upper and
lower parts of the resulting filtered image are separated. The location of
the maxima in the upper part is located. The same goes for the location of
the minima in the lower part. The mask is then calculated, per column, by
considering it starts in the point where the maxima is in the upper part and
goes up to the point where the minima is detected on the lower part.
Parameters:
filter_height (:py:obj:`int`, optional): Height of contour mask in pixels,
must be an even number
filter_width (:py:obj:`int`, optional): Width of the contour mask in pixels
"""
def __init__(self, filter_height = 4, filter_width = 40, padder=None):
self.filter_height = filter_height
self.filter_width = filter_width
self.padder = padder
def __call__(self, image):
'''Inputs an image, returns a mask (numpy boolean array)
Parameters:
image (numpy.ndarray): A 2D numpy array of type ``uint8`` with the
input image
Returns:
numpy.ndarray: A 2D numpy array of type boolean with the caculated
mask. ``True`` values correspond to regions where the finger is
situated
'''
image = image if self.padder is None else self.padder(image)
img_h,img_w = image.shape
# Determine lower half starting point
half_img_h = int(img_h/2)
# Construct mask for filtering
mask = numpy.ones((self.filter_height,self.filter_width), dtype='float64')
mask[int(self.filter_height/2):,:] = -1.0
img_filt = scipy.ndimage.convolve(image.astype(numpy.float64), mask,
mode='nearest')
# Upper part of filtered image
img_filt_up = img_filt[:half_img_h,:]
y_up = img_filt_up.argmax(axis=0)
# Lower part of filtered image
img_filt_lo = img_filt[half_img_h:,:]
y_lo = img_filt_lo.argmin(axis=0)
# Translation: for all columns of the input image, set to True all pixels
# of the mask from index where the maxima occurred in the upper part until
# the index where the minima occurred in the lower part.
finger_mask = numpy.zeros(image.shape, dtype='bool')
for i in range(img_filt.shape[1]):
finger_mask[y_up[i]:(y_lo[i]+img_filt_lo.shape[0]+1), i] = True
if not self.padder:
return finger_mask
else:
w = self.padder.padding_width
return finger_mask[w:-w,w:-w]
class TomesLeeMask(Masker):
"""Estimates the finger region given an input NIR image using Lee et al.
This method is based on the work of Finger vein recognition using
minutia-based alignment and local binary pattern-based feature extraction,
E.C. Lee, H.C. Lee and K.R. Park, International Journal of Imaging Systems
and Technology, Volume 19, Issue 3, September 2009, Pages 175--178, doi:
10.1002/ima.20193
This code is a variant of the Matlab implementation by Bram Ton, available
at:
https://nl.mathworks.com/matlabcentral/fileexchange/35752-finger-region-localisation/content/lee_region.m
In this variant from Pedro Tome, the technique of filtering the image with
a horizontal filter is also applied on the vertical axis.
Parameters:
filter_height (:py:obj:`int`, optional): Height of contour mask in pixels,