Coverage for src/bob/bio/face/database/pola_thermal.py: 94%

1#!/usr/bin/env python 

2# vim: set fileencoding=utf-8 : 

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

4 

5""" 

6 PolaThermal dataset: 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 PolaThermalDatabase(CSVDatabase): 

21 """ 

22 Collected by USA Army, the Polarimetric Thermal Database contains basically VIS and Thermal face images. 

23 

24 Follow bellow the description of the imager used to capture this device. 

25 

26 The **polarimetric** LWIR imager used to collect this database was developed by Polaris Sensor Technologies. 

27 The imager is based on the division-of-time spinning achromatic retarder (SAR) design that uses a spinning phase-retarder mounted in series with a linear wire-grid polarizer. 

28 This system, also referred to as a polarimeter, has a spectral response range of 7.5-11.1, using a Stirling-cooled mercury telluride focal plane array with pixel array dimensions of 640×480. 

29 A Fourier modulation technique is applied to the pixel readout, followed by a series expansion and inversion to compute the Stokes images. 

30 Data were recorded at 60 frames per second (fps) for this database, using a wide FOV of 10.6°×7.9°. Prior to collecting data for each subject, a two-point non-uniformity correction (NUC) was performed using a Mikron blackbody at 20°C and 40°C, which covers the range of typical facial temperatures (30°C-35°C). 

31 Data was recorded on a laptop using custom vendor software. 

32 

33 An array of four Basler Scout series cameras was used to collect the corresponding **visible spectrum imagery**. 

34 Two of the cameras are monochrome (model # scA640-70gm), with pixel array dimensions of 659×494. 

35 The other two cameras are color (model # scA640-70gc), with pixel array dimensions of 658×494. 

36 

37 

38 The dataset contains 60 subjects in total. 

39 For **VIS** images (considered only the 87 pixels interpupil distance) there are 4 samples per subject with neutral expression (called baseline condition **B**) and 12 samples per subject varying the facial expression (called expression **E**). 

40 Such variability was introduced by asking the subject to count orally. 

41 In total there are 960 images for this modality. 

42 For the **thermal** images there are 4 types of thermal imagery based on the Stokes parameters (:math:`S_0`, :math:`S_1`, :math:`S_2` and :math:`S_3`) commonly used to represent the polarization state. 

43 The thermal imagery is the following: 

44 

45 - :math:`S_0`: The conventional thermal image 

46 - :math:`S_1` 

47 - :math:`S_2` 

48 - DoLP: The degree-of-linear-polarization (DoLP) describes the portion of an electromagnetic wave that is linearly polarized, as defined :math:`\\frac{sqrt(S_{1}^{2} + S_{2}^{2})}{S_0}`. 

49 

50 Since :math:`S_3` is very small and usually taken to be zero, the authors of the database decided not to provide this part of the data. 

51 The same facial expression variability introduced in **VIS** is introduced for **Thermal** images. 

52 The distance between the subject and the camera is the last source of variability introduced in the thermal images. 

53 There are 3 ranges: R1 (2.5m), R2 (5m) and R3 (7.5m). 

54 In total there are 11,520 images for this modality and for each subject they are split as the following: 

55 

56 +----------------+----------+----------+----------+ 

57 | Imagery/Range | R1 (B/E) | R2 (B/E) | R3 (B/E) | 

58 +================+==========+==========+==========+ 

59 | :math:`S_0` | 16 (8/8) | 16 (8/8) | 16 (8/8) | 

60 +----------------+----------+----------+----------+ 

61 | :math:`S_1` | 16 (8/8) | 16 (8/8) | 16 (8/8) | 

62 +----------------+----------+----------+----------+ 

63 | :math:`S_2` | 16 (8/8) | 16 (8/8) | 16 (8/8) | 

64 +----------------+----------+----------+----------+ 

65 | DoLP | 16 (8/8) | 16 (8/8) | 16 (8/8) | 

66 +----------------+----------+----------+----------+ 

67 

68 

69 

70 .. warning:: 

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

72 

73 $ bob config set bob.db.pola-thermal.directory [PATH-TO-RAW-DATA] 

74 

75 

76 

77 Parameters 

78 ---------- 

79 

80 protocol: str 

81 One of the database protocols. 

82 """ 

83 

84 name = "polathermal" 

85 category = "face" 

86 dataset_protocols_name = "polathermal.tar.gz" 

87 dataset_protocols_urls = [ 

88 "https://www.idiap.ch/software/bob/databases/latest/face/polathermal-09a724b6.tar.gz", 

89 "http://www.idiap.ch/software/bob/databases/latest/face/polathermal-09a724b6.tar.gz", 

90 ] 

91 dataset_protocols_hash = "09a724b6" 

92 

93 def __init__( 

94 self, protocol, annotation_type="eyes-center", fixed_positions=None 

95 ): 

96 directory = rc.get("bob.db.pola-thermal.directory", "") 

97 

98 def load(path): 

99 """ 

100 Images in this dataset are stored as 16-bit PNG [0-65535] 

101 and bob.bio.face assumes images are between 0 and 255, 

102 so we divide by 257: 65535 / 255 = 257 

103 """ 

104 return bob.io.base.load(path) / 257 

105 

106 super().__init__( 

107 name=self.name, 

108 protocol=protocol, 

109 transformer=make_pipeline( 

110 FileSampleLoader( 

111 data_loader=load, 

112 dataset_original_directory=directory, 

113 extension=rc.get("bob.db.pola-thermal.extension", ".png"), 

114 ), 

115 EyesAnnotations(), 

116 ), 

117 annotation_type=annotation_type, 

118 fixed_positions=fixed_positions, 

119 )