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

1""" 

2Digital Cinema Distribution Master (DCDM) 

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

4 

5Define the *DCDM* electro-optical transfer function (EOTF) and its 

6inverse. 

7 

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

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

10 

11References 

12---------- 

13- :cite:`DigitalCinemaInitiatives2007b` : Digital Cinema Initiatives. (2007). 

14 Digital Cinema System Specification - Version 1.1. 

15 http://www.dcimovies.com/archives/spec_v1_1/\ 

16DCI_DCinema_System_Spec_v1_1.pdf 

17- :cite:`SocietyofMotionPictureandTelevisionEngineers2019` : Society of 

18 Motion Picture and Television Engineers. (2019). ST 428-1:2019 - D-Cinema 

19 Distribution Master — Image Characteristic. doi:10.5594/SMPTE.ST428-1.2019 

20""" 

21 

22from __future__ import annotations 

23 

24import typing 

25 

26import numpy as np 

27 

28from colour.algebra import spow 

29 

30if typing.TYPE_CHECKING: 

31 from colour.hints import ArrayLike, NDArrayFloat, NDArrayReal 

32 

33from colour.utilities import as_float, as_float_array, as_int 

34 

35__author__ = "Colour Developers" 

36__copyright__ = "Copyright 2013 Colour Developers" 

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

38__maintainer__ = "Colour Developers" 

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

40__status__ = "Production" 

41 

42__all__ = [ 

43 "eotf_inverse_DCDM", 

44 "eotf_DCDM", 

45] 

46 

47 

48def eotf_inverse_DCDM(XYZ: ArrayLike, out_int: bool = False) -> NDArrayReal: 

49 """ 

50 Apply the *DCDM* inverse electro-optical transfer function (EOTF). 

51 

52 Parameters 

53 ---------- 

54 XYZ 

55 *CIE XYZ* tristimulus values. 

56 out_int 

57 Whether to return value as integer code value or float equivalent 

58 of a code value at a specified bit-depth. 

59 

60 Returns 

61 ------- 

62 :class:`numpy.ndarray` 

63 Non-linear *CIE XYZ'* tristimulus values. 

64 

65 Warnings 

66 -------- 

67 *DCDM* is an absolute transfer function. 

68 

69 Notes 

70 ----- 

71 - *DCDM* is an absolute transfer function, thus the domain and range 

72 values for the *Reference* and *1* scales are only indicative that 

73 the data is not affected by scale transformations. 

74 

75 +----------------+-----------------------+---------------+ 

76 | **Domain \\*** | **Scale - Reference** | **Scale - 1** | 

77 +================+=======================+===============+ 

78 | ``XYZ`` | ``UN`` | ``UN`` | 

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

80 

81 +----------------+-----------------------+---------------+ 

82 | **Range \\*** | **Scale - Reference** | **Scale - 1** | 

83 +================+=======================+===============+ 

84 | ``XYZ_p`` | ``UN`` | ``UN`` | 

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

86 

87 \\* This definition has an output int switch, thus the domain-range 

88 scale information is only specified for the floating point mode. 

89 

90 References 

91 ---------- 

92 :cite:`DigitalCinemaInitiatives2007b` 

93 

94 Examples 

95 -------- 

96 >>> eotf_inverse_DCDM(0.18) # doctest: +ELLIPSIS 

97 0.1128186... 

98 >>> eotf_inverse_DCDM(0.18, out_int=True) 

99 462 

100 """ 

101 

102 XYZ = as_float_array(XYZ) 

103 

104 XYZ_p = spow(XYZ / 52.37, 1 / 2.6) 

105 

106 if out_int: 

107 return as_int(np.round(4095 * XYZ_p)) 

108 

109 return as_float(XYZ_p) 

110 

111 

112def eotf_DCDM( 

113 XYZ_p: ArrayLike, 

114 in_int: bool = False, 

115) -> NDArrayFloat: 

116 """ 

117 Apply the *DCDM* electro-optical transfer function (EOTF). 

118 

119 Parameters 

120 ---------- 

121 XYZ_p 

122 Non-linear *CIE XYZ'* tristimulus values. 

123 in_int 

124 Whether to treat the input value as integer code value or float 

125 equivalent of a code value at a specified bit-depth. 

126 

127 Returns 

128 ------- 

129 :class:`numpy.ndarray` 

130 *CIE XYZ* tristimulus values. 

131 

132 Warnings 

133 -------- 

134 *DCDM* is an absolute transfer function. 

135 

136 Notes 

137 ----- 

138 - *DCDM* is an absolute transfer function, thus the domain and range 

139 values for the *Reference* and *1* scales are only indicative that 

140 the data is not affected by scale transformations. 

141 

142 +----------------+-----------------------+---------------+ 

143 | **Domain \\*** | **Scale - Reference** | **Scale - 1** | 

144 +================+=======================+===============+ 

145 | ``XYZ_p`` | ``UN`` | ``UN`` | 

146 +----------------+-----------------------+---------------+ 

147 

148 +----------------+-----------------------+---------------+ 

149 | **Range \\*** | **Scale - Reference** | **Scale - 1** | 

150 +================+=======================+===============+ 

151 | ``XYZ`` | ``UN`` | ``UN`` | 

152 +----------------+-----------------------+---------------+ 

153 

154 \\* This definition has an input int switch, thus the domain-range 

155 scale information is only specified for the floating point mode. 

156 

157 References 

158 ---------- 

159 :cite:`DigitalCinemaInitiatives2007b` 

160 

161 Examples 

162 -------- 

163 >>> eotf_DCDM(0.11281860951766724) # doctest: +ELLIPSIS 

164 0.18... 

165 >>> eotf_DCDM(462, in_int=True) # doctest: +ELLIPSIS 

166 0.18... 

167 """ 

168 

169 XYZ_p = as_float_array(XYZ_p) 

170 

171 if in_int: 

172 XYZ_p = XYZ_p / 4095 

173 

174 XYZ = 52.37 * spow(XYZ_p, 2.6) 

175 

176 return as_float(XYZ)