Coverage for src/bob/bio/face/database/meds.py: 100%

1#!/usr/bin/env python 

2# vim: set fileencoding=utf-8 : 

3# Tiago de Freitas Pereira <tiago.pereira@idiap.ch> 

4 

5""" 

6 MEDS database implementation 

7""" 

8 

9from clapper.rc import UserDefaults 

10from sklearn.pipeline import make_pipeline 

11 

12import bob.io.base 

13 

14from bob.bio.base.database import CSVDatabase, FileSampleLoader 

15from bob.bio.face.database.sample_loaders import EyesAnnotations 

16 

17rc = UserDefaults("bobrc.toml") 

18 

19 

20class MEDSDatabase(CSVDatabase): 

21 """ 

22 The MEDS II database was developed by NIST to support and assists their biometrics evaluation program. 

23 It is composed by 518 identities from both men/women (labeled as M and F) and five different race annotations (Asian, Black, American Indian, Unknown and White) 

24 (labeled as A, B, I, U and W. 

25 

26 Unfortunately, the distribution of gender and race is extremely unbalanced as it can be 

27 observed in their statistics. Furthermore, only 256 subjects has 

28 more than one image sample (obviously it is not possible to do a biometric evaluation with one sample per subject). 

29 For this reason, this interface contains a subset of the data, which is composed only by 383 subjects (White and Black men only). 

30 

31 This dataset contains three verification protocols and they are: 

32 `verification_fold1`, `verification_fold2` and `verification_fold1`. 

33 Follow below the identities distribution in each set for the for each protocol: 

34 

35 

36 +--------------------+---------------+-----------+-----------+-----------+ 

37 | | Training set | Dev. Set | Eval. Set | 

38 +--------------------+---------------+-----------+ + + 

39 | | T-References | Z-Probes | | | 

40 +====================+===============+===========+===========+===========+ 

41 | verification_fold1 | 80 | 80 | 111 | 112 | 

42 +--------------------+---------------+-----------+-----------+-----------+ 

43 | verification_fold2 | 80 | 80 | 111 | 112 | 

44 +--------------------+---------------+-----------+-----------+-----------+ 

45 | verification_fold3 | 80 | 80 | 111 | 112 | 

46 +--------------------+---------------+-----------+-----------+-----------+ 

47 

48 Example 

49 ------- 

50 

51 Fetching biometric references:: 

52 

53 >>> from bob.bio.face.database import MEDSDatabase 

54 >>> database = MEDSDatabase(protocol="verification_fold1") 

55 >>> database.references() 

56 

57 

58 Fetching probes:: 

59 

60 >>> from bob.bio.face.database import MEDSDatabase 

61 >>> database = MEDSDatabase(protocol="verification_fold1") 

62 >>> database.probes() 

63 

64 

65 Fetching references for T-Norm normalization:: 

66 

67 >>> from bob.bio.face.database import MEDSDatabase 

68 >>> database = MEDSDatabase(protocol="verification_fold1") 

69 >>> database.treferences() 

70 

71 

72 Fetching probes for Z-Norm normalization:: 

73 

74 >>> from bob.bio.face.database import MEDSDatabase 

75 >>> database = MEDSDatabase(protocol="verification_fold1") 

76 >>> database.zprobes() 

77 

78 

79 .. warning:: 

80 Use the command below to set the path of the real data:: 

81 

82 $ bob config set bob.db.meds.directory [PATH-TO-MEDS-DATA] 

83 

84 Parameters 

85 ---------- 

86 

87 protocol: str 

88 One of the database protocols. Options are `verification_fold1`, `verification_fold2` and `verification_fold3` 

89 

90 """ 

91 

92 name = "meds" 

93 category = "face" 

94 dataset_protocols_name = "meds.tar.gz" 

95 dataset_protocols_urls = [ 

96 "https://www.idiap.ch/software/bob/databases/latest/face/meds-b74e3c3a.tar.gz", 

97 "http://www.idiap.ch/software/bob/databases/latest/face/meds-b74e3c3a.tar.gz", 

98 ] 

99 dataset_protocols_hash = "b74e3c3a" 

100 

101 def __init__( 

102 self, 

103 protocol, 

104 annotation_type="eyes-center", 

105 fixed_positions=None, 

106 dataset_original_directory=rc.get("bob.db.meds.directory", ""), 

107 dataset_original_extension=rc.get("bob.db.meds.extension", ".jpg"), 

108 ): 

109 super().__init__( 

110 name=self.name, 

111 protocol=protocol, 

112 transformer=make_pipeline( 

113 FileSampleLoader( 

114 data_loader=bob.io.base.load, 

115 dataset_original_directory=dataset_original_directory 

116 if dataset_original_directory 

117 else "", 

118 extension=dataset_original_extension, 

119 ), 

120 EyesAnnotations(), 

121 ), 

122 templates_metadata=["sex", "race"], 

123 annotation_type=annotation_type, 

124 fixed_positions=fixed_positions, 

125 )