Coverage for src/bob/bio/base/preprocessor/Preprocessor.py: 89%

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 

5 

6import warnings 

7 

8from .. import utils 

9 

10 

11class Preprocessor(object): 

12 """This is the base class for all preprocessors. 

13 It defines the minimum requirements for all derived proprocessor classes. 

14 

15 **Parameters:** 

16 

17 writes_data : bool 

18 Select, if the preprocessor actually writes preprocessed images, or if it is simply returning values. 

19 

20 read_original_data: callable or ``None`` 

21 This function is used to read the original data from file. 

22 It takes three inputs: A :py:class:`bob.bio.base.database.BioFile` (or one of its derivatives), the original directory (as ``str``) and the original extension (as ``str``). 

23 If ``None``, the default function :py:func:`bob.bio.base.read_original_data` is used. 

24 

25 min_preprocessed_file_size: int 

26 The minimum file size of a saved preprocessd data in bytes. If the saved 

27 preprocessed data file size is smaller than this, it is assumed to be a 

28 corrupt file and the data will be processed again. 

29 

30 kwargs : ``key=value`` pairs 

31 A list of keyword arguments to be written in the `__str__` function. 

32 """ 

33 

34 def __init__( 

35 self, 

36 writes_data=True, 

37 read_original_data=None, 

38 min_preprocessed_file_size=1000, 

39 **kwargs, 

40 ): 

41 # Each class needs to have a constructor taking 

42 # all the parameters that are required for the preprocessing as arguments 

43 self.writes_data = writes_data 

44 if read_original_data is None: 

45 read_original_data = utils.read_original_data 

46 self.read_original_data = read_original_data 

47 self.min_preprocessed_file_size = min_preprocessed_file_size 

48 self._kwargs = kwargs 

49 

50 warnings.warn( 

51 "`bob.bio.base.preprocessor.Preprocessor` will be deprecated in 01/01/2021. " 

52 "Please, implement your biometric algorithm using `bob.pipelines` (https://gitlab.idiap.ch/bob/bob.pipelines).", 

53 DeprecationWarning, 

54 ) 

55 

56 # The call function (i.e. the operator() in C++ terms) 

57 def __call__(self, data, annotations): 

58 """__call__(data, annotations) -> data 

59 

60 This is the call function that you have to overwrite in the derived class. 

61 The parameters that this function will receive are: 

62 

63 **Parameters:** 

64 

65 data : object 

66 The original data that needs preprocessing, usually a :py:class:`numpy.ndarray`, but might be different. 

67 

68 annotations : {} or None 

69 The annotations (if any) that belongs to the given ``data``; as a dictionary. 

70 The type of the annotation depends on your kind of problem. 

71 

72 **Returns:** 

73 

74 data : object 

75 The *preprocessed* data, usually a :py:class:`numpy.ndarray`, but might be different. 

76 """ 

77 raise NotImplementedError( 

78 "Please overwrite this function in your derived class" 

79 ) 

80 

81 def __str__(self): 

82 """__str__() -> info 

83 

84 This function returns all parameters of this class (and its derived class). 

85 

86 **Returns:** 

87 

88 info : str 

89 A string containing the full information of all parameters of this (and the derived) class. 

90 """ 

91 return utils.pretty_print(self, self._kwargs) 

92 

93 ############################################################ 

94 # Special functions that might be overwritten on need 

95 ############################################################ 

96 

97 def write_data(self, data, data_file): 

98 """Writes the given *preprocessed* data to a file with the given name. 

99 In this base class implementation, we simply use :py:func:`bob.bio.base.save` for that. 

100 If you have a different format (e.g. not images), please overwrite this function. 

101 

102 **Parameters:** 

103 

104 data : object 

105 The preprocessed data, i.e., what is returned from `__call__`. 

106 

107 data_file : str or :py:class:`h5py.File` 

108 The file open for writing, or the name of the file to write. 

109 """ 

110 utils.save(data, data_file) 

111 

112 def read_data(self, data_file): 

113 """read_data(data_file) -> data 

114 

115 Reads the *preprocessed* data from file. 

116 In this base class implementation, it uses :py:func:`bob.bio.base.load` to do that. 

117 If you have different format, please overwrite this function. 

118 

119 **Parameters:** 

120 

121 data_file : str or :py:class:`h5py.File` 

122 The file open for reading or the name of the file to read from. 

123 

124 **Returns:** 

125 

126 data : object (usually :py:class:`numpy.ndarray`) 

127 The preprocessed data read from file. 

128 """ 

129 return utils.load(data_file)