Coverage for models/rgb/transfer_functions/st_2084.py: 60%

1""" 

2SMPTE ST 2084:2014 

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

4 

5Define the *SMPTE ST 2084:2014* electro-optical transfer function (EOTF) and 

6its inverse. 

7 

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

9- :func:`colour.models.eotf_ST2084` 

10 

11References 

12---------- 

13- :cite:`Miller2014a` : Miller, S. (2014). A Perceptual EOTF for Extended 

14 Dynamic Range Imagery (pp. 1-17). 

15 https://www.smpte.org/sites/default/files/\ 

162014-05-06-EOTF-Miller-1-2-handout.pdf 

17- :cite:`SocietyofMotionPictureandTelevisionEngineers2014a` : Society of 

18 Motion Picture and Television Engineers. (2014). SMPTE ST 2084:2014 - 

19 Dynamic Range Electro-Optical Transfer Function of Mastering Reference 

20 Displays (pp. 1-14). doi:10.5594/SMPTE.ST2084.2014 

21""" 

22 

23from __future__ import annotations 

24 

25import typing 

26 

27import numpy as np 

28 

29from colour.algebra import spow 

30 

31if typing.TYPE_CHECKING: 

32 from colour.hints import ArrayLike, NDArrayFloat 

33 

34from colour.utilities import Structure, as_float, as_float_array, optional 

35 

36__author__ = "Colour Developers" 

37__copyright__ = "Copyright 2013 Colour Developers" 

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

39__maintainer__ = "Colour Developers" 

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

41__status__ = "Production" 

42 

43__all__ = [ 

44 "CONSTANTS_ST2084", 

45 "eotf_inverse_ST2084", 

46 "eotf_ST2084", 

47] 

48 

49CONSTANTS_ST2084: Structure = Structure( 

50 m_1=2610 / 4096 * (1 / 4), 

51 m_2=2523 / 4096 * 128, 

52 c_1=3424 / 4096, 

53 c_2=2413 / 4096 * 32, 

54 c_3=2392 / 4096 * 32, 

55) 

56""" 

57Constants for *SMPTE ST 2084:2014* inverse electro-optical transfer function 

58(EOTF) and electro-optical transfer function (EOTF). 

59""" 

60 

61 

62def eotf_inverse_ST2084( 

63 C: ArrayLike, 

64 L_p: float = 10000, 

65 constants: Structure | None = None, 

66) -> NDArrayFloat: 

67 """ 

68 Apply the *SMPTE ST 2084:2014* perceptual quantizer (PQ) inverse 

69 electro-optical transfer function (EOTF). 

70 

71 Parameters 

72 ---------- 

73 C 

74 Target optical output :math:`C` in :math:`cd/m^2` of the ideal 

75 reference display. 

76 L_p 

77 System peak luminance in :math:`cd/m^2`. This parameter should remain 

78 at its default value of :math:`10000 cd/m^2` for practical 

79 applications. It is exposed to enable the definition's use as a 

80 fitting function. 

81 constants 

82 *SMPTE ST 2084:2014* constants. 

83 

84 Returns 

85 ------- 

86 :class:`numpy.ndarray` 

87 Colour value abbreviated as :math:`N`, directly proportional to the 

88 encoded signal representation and not directly proportional to the 

89 optical output of a display device. 

90 

91 Warnings 

92 -------- 

93 *SMPTE ST 2084:2014* is an absolute transfer function. 

94 

95 Notes 

96 ----- 

97 - *SMPTE ST 2084:2014* is an absolute transfer function; thus, the 

98 domain and range values for the *Reference* and *1* scales are only 

99 indicative that the data is not affected by scale transformations. 

100 The effective domain of the *SMPTE ST 2084:2014* inverse 

101 electro-optical transfer function (EOTF) is [0.0001, 10000]. 

102 

103 +------------+-----------------------+---------------+ 

104 | **Domain** | **Scale - Reference** | **Scale - 1** | 

105 +============+=======================+===============+ 

106 | ``C`` | ``UN`` | ``UN`` | 

107 +------------+-----------------------+---------------+ 

108 

109 +------------+-----------------------+---------------+ 

110 | **Range** | **Scale - Reference** | **Scale - 1** | 

111 +============+=======================+===============+ 

112 | ``N`` | ``UN`` | ``UN`` | 

113 +------------+-----------------------+---------------+ 

114 

115 References 

116 ---------- 

117 :cite:`Miller2014a`, 

118 :cite:`SocietyofMotionPictureandTelevisionEngineers2014a` 

119 

120 Examples 

121 -------- 

122 >>> eotf_inverse_ST2084(100) # doctest: +ELLIPSIS 

123 0.5080784... 

124 """ 

125 

126 C = as_float_array(C) 

127 constants = optional(constants, CONSTANTS_ST2084) 

128 

129 c_1 = constants.c_1 

130 c_2 = constants.c_2 

131 c_3 = constants.c_3 

132 m_1 = constants.m_1 

133 m_2 = constants.m_2 

134 

135 Y_p = spow(C / L_p, m_1) 

136 

137 N = spow((c_1 + c_2 * Y_p) / (c_3 * Y_p + 1), m_2) 

138 

139 return as_float(N) 

140 

141 

142def eotf_ST2084( 

143 N: ArrayLike, 

144 L_p: float = 10000, 

145 constants: Structure | None = None, 

146) -> NDArrayFloat: 

147 """ 

148 Apply the *SMPTE ST 2084:2014* perceptual quantizer (PQ) electro-optical 

149 transfer function (EOTF). 

150 

151 Parameters 

152 ---------- 

153 N 

154 Colour value abbreviated as :math:`N`, directly proportional to the 

155 encoded signal representation and not directly proportional to the 

156 optical output of a display device. 

157 L_p 

158 System peak luminance in :math:`cd/m^2`. This parameter should remain 

159 at its default value of :math:`10000 cd/m^2` for practical 

160 applications. It is exposed to enable the definition's use as a 

161 fitting function. 

162 constants 

163 *SMPTE ST 2084:2014* constants. 

164 

165 Returns 

166 ------- 

167 :class:`numpy.ndarray` 

168 Target optical output :math:`C` in :math:`cd/m^2` of the ideal 

169 reference display. 

170 

171 Warnings 

172 -------- 

173 *SMPTE ST 2084:2014* is an absolute transfer function. 

174 

175 Notes 

176 ----- 

177 - *SMPTE ST 2084:2014* is an absolute transfer function, thus the 

178 domain and range values for the *Reference* and *1* scales are only 

179 indicative that the data is not affected by scale transformations. 

180 

181 +------------+-----------------------+---------------+ 

182 | **Domain** | **Scale - Reference** | **Scale - 1** | 

183 +============+=======================+===============+ 

184 | ``N`` | ``UN`` | ``UN`` | 

185 +------------+-----------------------+---------------+ 

186 

187 +------------+-----------------------+---------------+ 

188 | **Range** | **Scale - Reference** | **Scale - 1** | 

189 +============+=======================+===============+ 

190 | ``C`` | ``UN`` | ``UN`` | 

191 +------------+-----------------------+---------------+ 

192 

193 References 

194 ---------- 

195 :cite:`Miller2014a`, 

196 :cite:`SocietyofMotionPictureandTelevisionEngineers2014a` 

197 

198 Examples 

199 -------- 

200 >>> eotf_ST2084(0.508078421517399) # doctest: +ELLIPSIS 

201 100.0000000... 

202 """ 

203 

204 N = as_float_array(N) 

205 constants = optional(constants, CONSTANTS_ST2084) 

206 

207 c_1 = constants.c_1 

208 c_2 = constants.c_2 

209 c_3 = constants.c_3 

210 m_1 = constants.m_1 

211 m_2 = constants.m_2 

212 

213 m_1_d = 1 / m_1 

214 m_2_d = 1 / m_2 

215 

216 V_p = spow(N, m_2_d) 

217 n = np.maximum(0, V_p - c_1) 

218 L = spow((n / (c_2 - c_3 * V_p)), m_1_d) 

219 C = L_p * L 

220 

221 return as_float(C)