Coverage for src/bob/bio/base/extractor/Extractor.py: 82%
22 statements
« prev ^ index » next coverage.py v7.6.0, created at 2024-07-12 22:34 +0200
1#!/usr/bin/env python
2# vim: set fileencoding=utf-8 :
3# @author: Manuel Guenther <Manuel.Guenther@idiap.ch>
4# @date: Tue Oct 2 12:12:39 CEST 2012
6import warnings
8from .. import utils
11class Extractor(object):
12 """This is the base class for all feature extractors.
13 It defines the minimum requirements that a derived feature extractor class need to implement.
15 If your derived class requires training, please register this here.
17 **Parameters**
19 requires_training : bool
20 Set this flag to ``True`` if your feature extractor needs to be trained.
21 In that case, please override the :py:meth:`train` and :py:meth:`load` methods
23 split_training_data_by_client : bool
24 Set this flag to ``True`` if your feature extractor requires the training data to be split by clients.
25 Ignored, if ``requires_training`` is ``False``
27 min_extractor_file_size : int
28 The minimum file size of a saved extractor file for extractors that
29 require training in bytes. If the saved file size is smaller than this, it
30 is assumed to be a corrupt file and the extractor will be trained again.
32 min_feature_file_size : int
33 The minimum file size of extracted features in bytes. If the saved file
34 size is smaller than this, it is assumed to be a corrupt file and the
35 features will be extracted again.
37 kwargs : ``key=value`` pairs
38 A list of keyword arguments to be written in the `__str__` function.
39 """
41 def __init__(
42 self,
43 requires_training=False, # enable, if your extractor needs training
44 split_training_data_by_client=False, # enable, if your extractor needs the training files sorted by client
45 min_extractor_file_size=1000,
46 min_feature_file_size=1000,
47 **kwargs, # the parameters of the extractor, to be written in the __str__() method
48 ):
49 # Each class needs to have a constructor taking
50 # all the parameters that are required for the feature extraction as arguments
51 self.requires_training = requires_training
52 self.split_training_data_by_client = split_training_data_by_client
53 self.min_extractor_file_size = min_extractor_file_size
54 self.min_feature_file_size = min_feature_file_size
55 self._kwargs = kwargs
57 warnings.warn(
58 "`bob.bio.base.extractor.Extractor` will be deprecated in 01/01/2021. "
59 "Please, implement your biometric algorithm using `bob.pipelines` (https://gitlab.idiap.ch/bob/bob.pipelines).",
60 DeprecationWarning,
61 )
63 ############################################################
64 # functions that must be overwritten in derived classes
65 ############################################################
67 def __call__(self, data):
68 """__call__(data) -> feature
70 This function will actually perform the feature extraction.
71 It must be overwritten by derived classes.
72 It takes the (preprocessed) data and returns the features extracted from the data.
74 **Parameters**
76 data : object (usually :py:class:`numpy.ndarray`)
77 The *preprocessed* data from which features should be extracted.
79 **Returns:**
81 feature : object (usually :py:class:`numpy.ndarray`)
82 The extracted feature.
83 """
84 raise NotImplementedError(
85 "Please overwrite this function in your derived class"
86 )
88 def __str__(self):
89 """__str__() -> info
91 This function returns all parameters of this class (and its derived class).
93 **Returns:**
95 info : str
96 A string containing the full information of all parameters of this (and the derived) class.
97 """
98 return utils.pretty_print(self, self._kwargs)
100 ############################################################
101 # Special functions that might be overwritten on need
102 ############################################################
104 def write_feature(self, feature, feature_file):
105 """Writes the given *extracted* feature to a file with the given name.
106 In this base class implementation, we simply use :py:func:`bob.bio.base.save` for that.
107 If you have a different format, please overwrite this function.
109 **Parameters:**
111 feature : object
112 The extracted feature, i.e., what is returned from `__call__`.
114 feature_file : str or :py:class:`h5py.File`
115 The file open for writing, or the name of the file to write.
116 """
117 utils.save(feature, feature_file)
119 def read_feature(self, feature_file):
120 """Reads the *extracted* feature from file.
121 In this base class implementation, it uses :py:func:`bob.bio.base.load` to do that.
122 If you have different format, please overwrite this function.
124 **Parameters:**
126 feature_file : str or :py:class:`h5py.File`
127 The file open for reading or the name of the file to read from.
129 **Returns:**
131 feature : object (usually :py:class:`numpy.ndarray`)
132 The feature read from file.
133 """
134 return utils.load(feature_file)
136 def load(self, extractor_file):
137 """Loads the parameters required for feature extraction from the extractor file.
138 This function usually is only useful in combination with the :py:meth:`train` function.
139 In this base class implementation, it does nothing.
141 **Parameters:**
143 extractor_file : str
144 The file to read the extractor from.
145 """
146 pass
148 def train(self, training_data, extractor_file):
149 """This function can be overwritten to train the feature extractor.
150 If you do this, please also register the function by calling this base class constructor
151 and enabling the training by ``requires_training = True``.
153 **Parameters:**
155 training_data : [object] or [[object]]
156 A list of *preprocessed* data that can be used for training the extractor.
157 Data will be provided in a single list, if ``split_training_features_by_client = False`` was specified in the constructor,
158 otherwise the data will be split into lists, each of which contains the data of a single (training-)client.
160 extractor_file : str
161 The file to write.
162 This file should be readable with the :py:meth:`load` function.
163 """
164 raise NotImplementedError(
165 "Please overwrite this function in your derived class, or unset the 'requires_training' option in the constructor."
166 )