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

1"""

2 SMPTE ST 2084:2014

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

4

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

6 its inverse.

7

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

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

10

11 References

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/\

16 2014-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

23 from __future__ import annotations

24

25 import typing

26

27 import numpy as np

28

29 from colour.algebra import spow

30

31 if typing.TYPE_CHECKING:

32 from colour.hints import ArrayLike, NDArrayFloat

33

34 from 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

49 CONSTANTS_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"""

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

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

59"""

60

61

62 def 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

142 def 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)