Coverage for colour/models/rgb/transfer_functions/pivoted_log.py: 100%

1""" 

2Pivoted Log Encoding 

3==================== 

4 

5Define the *Pivoted Log* encoding. 

6 

7- :func:`colour.models.log_encoding_PivotedLog` 

8- :func:`colour.models.log_decoding_PivotedLog` 

9 

10References 

11---------- 

12- :cite:`SonyImageworks2012a` : Sony Imageworks. (2012). make.py. Retrieved 

13 November 27, 2014, from 

14 https://github.com/imageworks/OpenColorIO-Configs/blob/master/\ 

15nuke-default/make.py 

16""" 

17 

18from __future__ import annotations 

19 

20import numpy as np 

21 

22from colour.hints import ( # noqa: TC001 

23 Domain1, 

24 Range1, 

25) 

26from colour.utilities import as_float, from_range_1, to_domain_1 

27 

28__author__ = "Colour Developers" 

29__copyright__ = "Copyright 2013 Colour Developers" 

30__license__ = "BSD-3-Clause - https://opensource.org/licenses/BSD-3-Clause" 

31__maintainer__ = "Colour Developers" 

32__email__ = "colour-developers@colour-science.org" 

33__status__ = "Production" 

34 

35__all__ = [ 

36 "log_encoding_PivotedLog", 

37 "log_decoding_PivotedLog", 

38] 

39 

40 

41def log_encoding_PivotedLog( 

42 x: Domain1, 

43 log_reference: float = 445, 

44 linear_reference: float = 0.18, 

45 negative_gamma: float = 0.6, 

46 density_per_code_value: float = 0.002, 

47) -> Range1: 

48 """ 

49 Apply the *Josh Pines* style *Pivoted Log* log encoding 

50 opto-electronic transfer function (OETF). 

51 

52 Parameters 

53 ---------- 

54 x 

55 Linear data :math:`x`. 

56 log_reference 

57 Log reference that defines the pivot point in code values where 

58 the logarithmic encoding is centred. Typical value is 445. 

59 linear_reference 

60 Linear reference that establishes the relationship between linear 

61 scene-referred values and the logarithmic code values. Typical 

62 value is 0.18, representing 18% grey. 

63 negative_gamma 

64 Negative gamma that controls the slope and curvature of the 

65 logarithmic portion of the encoding curve. Lower values produce 

66 steeper curves with more contrast in the shadows. 

67 density_per_code_value 

68 Density per code value that determines the logarithmic step size 

69 and affects the overall contrast and dynamic range of the encoded 

70 values. 

71 

72 Returns 

73 ------- 

74 :class:`numpy.ndarray` 

75 Logarithmically encoded data :math:`y`. 

76 

77 Notes 

78 ----- 

79 +------------+-----------------------+---------------+ 

80 | **Domain** | **Scale - Reference** | **Scale - 1** | 

81 +============+=======================+===============+ 

82 | ``x`` | 1 | 1 | 

83 +------------+-----------------------+---------------+ 

84 

85 +------------+-----------------------+---------------+ 

86 | **Range** | **Scale - Reference** | **Scale - 1** | 

87 +============+=======================+===============+ 

88 | ``y`` | 1 | 1 | 

89 +------------+-----------------------+---------------+ 

90 

91 References 

92 ---------- 

93 :cite:`SonyImageworks2012a` 

94 

95 Examples 

96 -------- 

97 >>> log_encoding_PivotedLog(0.18) # doctest: +ELLIPSIS 

98 0.4349951... 

99 """ 

100 

101 x = to_domain_1(x) 

102 

103 y = ( 

104 log_reference 

105 + np.log10(x / linear_reference) / (density_per_code_value / negative_gamma) 

106 ) / 1023 

107 

108 return as_float(from_range_1(y)) 

109 

110 

111def log_decoding_PivotedLog( 

112 y: Domain1, 

113 log_reference: float = 445, 

114 linear_reference: float = 0.18, 

115 negative_gamma: float = 0.6, 

116 density_per_code_value: float = 0.002, 

117) -> Range1: 

118 """ 

119 Apply the *Josh Pines* style *Pivoted Log* log decoding inverse 

120 opto-electronic transfer function (OETF). 

121 

122 Parameters 

123 ---------- 

124 y 

125 Logarithmically encoded data :math:`y`. 

126 log_reference 

127 Log reference that defines the pivot point in code values where 

128 the logarithmic encoding is centred. Typical value is 445. 

129 linear_reference 

130 Linear reference that establishes the relationship between linear 

131 scene-referred values and the logarithmic code values. Typical 

132 value is 0.18, representing 18% grey. 

133 negative_gamma 

134 Negative gamma that controls the slope and curvature of the 

135 logarithmic portion of the encoding curve. Lower values produce 

136 steeper curves with more contrast in the shadows. 

137 density_per_code_value 

138 Density per code value that determines the logarithmic step size 

139 and affects the overall contrast and dynamic range of the encoded 

140 values. 

141 

142 Returns 

143 ------- 

144 :class:`numpy.ndarray` 

145 Linear data :math:`x`. 

146 

147 Notes 

148 ----- 

149 +------------+-----------------------+---------------+ 

150 | **Domain** | **Scale - Reference** | **Scale - 1** | 

151 +============+=======================+===============+ 

152 | ``y`` | 1 | 1 | 

153 +------------+-----------------------+---------------+ 

154 

155 +------------+-----------------------+---------------+ 

156 | **Range** | **Scale - Reference** | **Scale - 1** | 

157 +============+=======================+===============+ 

158 | ``x`` | 1 | 1 | 

159 +------------+-----------------------+---------------+ 

160 

161 References 

162 ---------- 

163 :cite:`SonyImageworks2012a` 

164 

165 Examples 

166 -------- 

167 >>> log_decoding_PivotedLog(0.434995112414467) # doctest: +ELLIPSIS 

168 0.1... 

169 """ 

170 

171 y = to_domain_1(y) 

172 

173 x = ( 

174 10 ** ((y * 1023 - log_reference) * (density_per_code_value / negative_gamma)) 

175 * linear_reference 

176 ) 

177 

178 return as_float(from_range_1(x))