colour_hdri.models.dng Module

Adobe DNG SDK Colour Processing

Defines various objects implementing Adobe DNG SDK colour processing:

The Adobe DNG SDK defines the following tags relevant for the current implementation:

  • CalibrationIlluminant1 : The illuminant used for the first set of colour calibration tags.
  • CalibrationIlluminant2 : The illuminant used for an optional second set of colour calibration tags.
  • ColorMatrix1 : ColorMatrix1 defines a transformation matrix that converts XYZ values to reference camera native colour space values, under the first calibration illuminant.
  • ColorMatrix2 : ColorMatrix2 defines a transformation matrix that converts XYZ values to reference camera native colour space values, under the second calibration illuminant.
  • CameraCalibration1 : CameraCalibration1 defines a calibration matrix that transforms reference camera native space values to individual camera native space values under the first calibration illuminant. This matrix is stored separately from the matrix specified by the ColorMatrix1 tag to allow raw converters to swap in replacement colour matrices based on UniqueCameraModel tag, while still taking advantage of any per-individual camera calibration performed by the camera manufacturer.
  • CameraCalibration2 : CameraCalibration2 defines a calibration matrix that transforms reference camera native space values to individual camera native space values under the second calibration illuminant. This matrix is stored separately from the matrix specified by the ColorMatrix2 tag to allow raw converters to swap in replacement colour matrices based on UniqueCameraModel tag, while still taking advantage of any per-individual camera calibration performed by the camera manufacturer.
  • ReductionMatrix1 : ReductionMatrix1 defines a dimensionality reduction matrix for use as the first stage in converting colour camera native space values to XYZ values, under the first calibration illuminant. This tag may only be used if ColorPlanes is greater than 3.
  • ReductionMatrix2 : ReductionMatrix2 defines a dimensionality reduction matrix for use as the first stage in converting colour camera native space values to XYZ values, under the second calibration illuminant. This tag may only be used if ColorPlanes is greater than 3.
  • AnalogBalance : Normally the stored raw values are not white balanced, since any digital white balancing will reduce the dynamic range of the final image if the user decides to later adjust the white balance; however, if camera hardware is capable of white balancing the colour channels before the signal is digitized, it can improve the dynamic range of the final image. AnalogBalance defines the gain, either analog (recommended) or digital (not recommended) that has been applied the stored raw values.
  • AsShotNeutral : AsShotNeutral specifies the selected white balance at time of capture, encoded as the coordinates of a perfectly neutral colour in linear reference space values. The inclusion of this tag precludes the inclusion of the AsShotWhiteXY tag.
  • AsShotWhiteXY : AsShotWhiteXY specifies the selected white balance at time of capture, encoded as x-y chromaticity coordinates. The inclusion of this tag precludes the inclusion of the AsShotNeutral tag.
  • ForwardMatrix1 : This tag defines a matrix that maps white balanced camera colours to XYZ D50 colours.
  • ForwardMatrix2 : This tag defines a matrix that maps white balanced camera colours to XYZ D50 colours.

Notes

  • At least one of the ColorMatrix1 or ColorMatrix2 tags must be included in the camera profile, the current implementation expects them to be passed as identity matrices if not included.
  • If the ForwardMatrix1 or ForwardMatrix2 tags are not included in the camera profile, the current implementation expects them to be passed as identity matrices.
  • The ReductionMatrix1 and ReductionMatrix2 tags are ignored by the current implementation which expects cameras with 3 colour planes.
  • DNG 1.2.0.0 and later supports different companies creating the camera calibration tags using different reference cameras. When rendering a DNG file using a camera profile, it is important to know if the selected camera profile was designed using the same reference camera used to create the camera calibration tags. If so, then the camera calibration tags should be used. If not, then it is preferable to ignore the camera calibration tags and use identity matrices instead in order to minimize the worse case calibration mismatch error. This matching is done by comparing the CameraCalibrationSignature tag and the ProfileCalibrationSignature tag for the selected camera profile. If they match, then use the camera calibration tags. If not, then use identity matrices.
  • The Hue/Saturation/Value Mapping Table is ignored by the current implementation because deemed unsuitable. [3]
  • The various matrices used in this module are extracted from a Canon EOS 5D Mark II camera.

References

[1]Adobe Systems. (2012). Digital Negative (DNG) Specification, 1–101.
[2]Adobe Systems. (2015). Adobe DNG SDK 1.4. Retrieved from http://download.adobe.com/pub/adobe/dng/dng_sdk_1_4.zip
[3]McGuffog, S. (2012). Hue Twists in DNG Camera Profiles. Retrieved October 29, 2016, from http://dcptool.sourceforge.net/Hue%20Twists.html
colour_hdri.models.dng.interpolated_matrix(CCT, CCT_1, CCT_2, M_1, M_2)[source]

Computes the matrix interpolated from \(CCT_1\) and \(CCT_2\) correlated colour temperatures to respectively \(M_1\) and \(M_2\) colour matrices using given correlated colour temperature \(CCT\) interpolation value.

Parameters:
  • CCT (numeric) – Correlated colour temperature \(CCT\).
  • CCT_1 (numeric) – Correlated colour temperature \(CCT_1\).
  • CCT_2 (numeric) – Correlated colour temperature \(CCT_2\).
  • M_1 (array_like) – \(M_1\) colour matrix.
  • M_2 (array_like) – \(M_2\) colour matrix.
Returns:

Interpolated colour matrix \(M_i\).
Return type:

ndarray

Notes

  • The computation is performed in mired (MIcro REciprocal Degree, reciprocal megakelvin) \(MK^{-1}\).

Examples

>>> CCT = 5000
>>> CCT_1 = 2850
>>> CCT_2 = 6500
>>> M_1 = np.array([
...     [0.5309, -0.0229, -0.0336],
...     [-0.6241, 1.3265, 0.3337],
...     [-0.0817, 0.1215, 0.6664]])
>>> M_2 = np.array([
...     [0.4716, 0.0603, -0.0830],
...     [-0.7798, 1.5474, 0.2480],
...     [-0.1496, 0.1937, 0.6651]])
>>> interpolated_matrix(CCT, CCT_1, CCT_2, M_1, M_2)  # doctest: +ELLIPSIS
array([[ 0.4854908...,  0.0408106..., -0.0714282...],
       [-0.7433278...,  1.4956549...,  0.2680749...],
       [-0.1336946...,  0.1767874...,  0.6654045...]])
colour_hdri.models.dng.xy_to_camera_neutral(xy, CCT_calibration_illuminant_1, CCT_calibration_illuminant_2, M_color_matrix_1, M_color_matrix_2, M_camera_calibration_1, M_camera_calibration_2, analog_balance)[source]

Converts given xy white balance chromaticity coordinates to Camera Neutral coordinates.

Parameters:
  • xy (array_like) – xy white balance chromaticity coordinates.
  • CCT_calibration_illuminant_1 (numeric) – Correlated colour temperature of CalibrationIlluminant1.
  • CCT_calibration_illuminant_2 (numeric) – Correlated colour temperature of CalibrationIlluminant2.
  • M_color_matrix_1 (array_like) – ColorMatrix1 tag matrix.
  • M_color_matrix_2 (array_like) – ColorMatrix2 tag matrix.
  • M_camera_calibration_1 (array_like) – CameraCalibration1 tag matrix.
  • M_camera_calibration_2 (array_like) – CameraCalibration2 tag matrix.
  • analog_balance (array_like) – AnalogBalance tag vector.
Returns:

Camera Neutral coordinates.
Return type:

ndarray

References

[4]Adobe Systems. (2012). Translating White Balance xy Coordinates to Camera Neutral Coordinates. In Digital Negative (DNG) Specification (p. 80).

Examples

>>> M_color_matrix_1 = np.array([
...     [0.5309, -0.0229, -0.0336],
...     [-0.6241, 1.3265, 0.3337],
...     [-0.0817, 0.1215, 0.6664]])
>>> M_color_matrix_2 = np.array([
...     [0.4716, 0.0603, -0.0830],
...     [-0.7798, 1.5474, 0.2480],
...     [-0.1496, 0.1937, 0.6651]])
>>> M_camera_calibration_1 = np.identity(3)
>>> M_camera_calibration_2 = np.identity(3)
>>> analog_balance = np.ones(3)
>>> xy_to_camera_neutral(  # doctest: +ELLIPSIS
...     np.array([0.32816244, 0.34698169]),
...     2850,
...     6500,
...     M_color_matrix_1,
...     M_color_matrix_2,
...     M_camera_calibration_1,
...     M_camera_calibration_2,
...     analog_balance)
array([ 0.4130699...,  1...        ,  0.646465...])
colour_hdri.models.dng.camera_neutral_to_xy(camera_neutral, CCT_calibration_illuminant_1, CCT_calibration_illuminant_2, M_color_matrix_1, M_color_matrix_2, M_camera_calibration_1, M_camera_calibration_2, analog_balance, epsilon=<Mock name='mock.EPSILON' id='139671442442560'>)[source]

Converts given Camera Neutral coordinates to xy white balance chromaticity coordinates.

Parameters:
  • camera_neutral (array_like) – Camera Neutral coordinates.
  • CCT_calibration_illuminant_1 (numeric) – Correlated colour temperature of CalibrationIlluminant1.
  • CCT_calibration_illuminant_2 (numeric) – Correlated colour temperature of CalibrationIlluminant2.
  • M_color_matrix_1 (array_like) – ColorMatrix1 tag matrix.
  • M_color_matrix_2 (array_like) – ColorMatrix2 tag matrix.
  • M_camera_calibration_1 (array_like) – CameraCalibration1 tag matrix.
  • M_camera_calibration_2 (array_like) – CameraCalibration2 tag matrix.
  • analog_balance (array_like) – AnalogBalance tag vector.
  • epsilon (numeric, optional) – Threshold value for computation convergence.
Returns:

xy white balance chromaticity coordinates.
Return type:

ndarray
Raises:

RuntimeError – If the given Camera Neutral coordinates did not converge to xy white balance chromaticity coordinates.

References

[5]Adobe Systems. (2012). Translating Camera Neutral Coordinates to White Balance xy Coordinates. In Digital Negative (DNG) Specification (pp. 80–81).

Examples

>>> M_color_matrix_1 = np.array([
...     [0.5309, -0.0229, -0.0336],
...     [-0.6241, 1.3265, 0.3337],
...     [-0.0817, 0.1215, 0.6664]])
>>> M_color_matrix_2 = np.array([
...     [0.4716, 0.0603, -0.0830],
...     [-0.7798, 1.5474, 0.2480],
...     [-0.1496, 0.1937, 0.6651]])
>>> M_camera_calibration_1 = np.identity(3)
>>> M_camera_calibration_2 = np.identity(3)
>>> analog_balance = np.ones(3)
>>> camera_neutral_to_xy(  # doctest: +ELLIPSIS
...     np.array([0.413070, 1.000000, 0.646465]),
...     2850,
...     6500,
...     M_color_matrix_1,
...     M_color_matrix_2,
...     M_camera_calibration_1,
...     M_camera_calibration_2,
...     analog_balance)
array([ 0.3281624...,  0.3469816...])
colour_hdri.models.dng.XYZ_to_camera_space_matrix(xy, CCT_calibration_illuminant_1, CCT_calibration_illuminant_2, M_color_matrix_1, M_color_matrix_2, M_camera_calibration_1, M_camera_calibration_2, analog_balance)[source]

Returns the CIE XYZ to Camera Space matrix for given xy white balance chromaticity coordinates. [4]

Parameters:
  • xy (array_like) – xy white balance chromaticity coordinates.
  • CCT_calibration_illuminant_1 (numeric) – Correlated colour temperature of CalibrationIlluminant1.
  • CCT_calibration_illuminant_2 (numeric) – Correlated colour temperature of CalibrationIlluminant2.
  • M_color_matrix_1 (array_like) – ColorMatrix1 tag matrix.
  • M_color_matrix_2 (array_like) – ColorMatrix2 tag matrix.
  • M_camera_calibration_1 (array_like) – CameraCalibration1 tag matrix.
  • M_camera_calibration_2 (array_like) – CameraCalibration2 tag matrix.
  • analog_balance (array_like) – AnalogBalance tag vector.
Returns:

CIE XYZ to Camera Space matrix.
Return type:

ndarray

Notes

  • The reference illuminant is D50 as defined per ADOBE_DNG_XYZ_ILLUMINANT attribute.

Examples

>>> M_color_matrix_1 = np.array([
...     [0.5309, -0.0229, -0.0336],
...     [-0.6241, 1.3265, 0.3337],
...     [-0.0817, 0.1215, 0.6664]])
>>> M_color_matrix_2 = np.array([
...     [0.4716, 0.0603, -0.0830],
...     [-0.7798, 1.5474, 0.2480],
...     [-0.1496, 0.1937, 0.6651]])
>>> M_camera_calibration_1 = np.identity(3)
>>> M_camera_calibration_2 = np.identity(3)
>>> analog_balance = np.ones(3)
>>> XYZ_to_camera_space_matrix(  # doctest: +ELLIPSIS
...     np.array([0.34510414, 0.35162252]),
...     2850,
...     6500,
...     M_color_matrix_1,
...     M_color_matrix_2,
...     M_camera_calibration_1,
...     M_camera_calibration_2,
...     analog_balance)
array([[ 0.4854908...,  0.0408106..., -0.0714282...],
       [-0.7433278...,  1.4956549...,  0.2680749...],
       [-0.1336946...,  0.1767874...,  0.6654045...]])
colour_hdri.models.dng.camera_space_to_XYZ_matrix(xy, CCT_calibration_illuminant_1, CCT_calibration_illuminant_2, M_color_matrix_1, M_color_matrix_2, M_camera_calibration_1, M_camera_calibration_2, analog_balance, M_forward_matrix_1, M_forward_matrix_2, chromatic_adaptation_transform='Bradford')[source]

Returns the Camera Space to CIE XYZ matrix for given xy white balance chromaticity coordinates.

Parameters:
  • xy (array_like) – xy white balance chromaticity coordinates.
  • CCT_calibration_illuminant_1 (numeric) – Correlated colour temperature of CalibrationIlluminant1.
  • CCT_calibration_illuminant_2 (numeric) – Correlated colour temperature of CalibrationIlluminant2.
  • M_color_matrix_1 (array_like) – ColorMatrix1 tag matrix.
  • M_color_matrix_2 (array_like) – ColorMatrix2 tag matrix.
  • M_camera_calibration_1 (array_like) – CameraCalibration1 tag matrix.
  • M_camera_calibration_2 (array_like) – CameraCalibration2 tag matrix.
  • analog_balance (array_like) – AnalogBalance tag vector.
  • M_forward_matrix_1 (array_like) – ForwardMatrix1 tag matrix.
  • M_forward_matrix_2 (array_like) – ForwardMatrix2 tag matrix.
  • chromatic_adaptation_transform (unicode, optional) – {‘CAT02’, ‘XYZ Scaling’, ‘Von Kries’, ‘Bradford’, ‘Sharp’, ‘Fairchild’, ‘CMCCAT97’, ‘CMCCAT2000’, ‘CAT02_BRILL_CAT’, ‘Bianco’, ‘Bianco PC’}, Chromatic adaptation transform.
Returns:

Camera Space to CIE XYZ matrix.
Return type:

ndarray

Notes

  • The reference illuminant is D50 as defined per ADOBE_DNG_XYZ_ILLUMINANT attribute.

References

[6]Adobe Systems. (2012). Camera to XYZ (D50) Transform. In Digital Negative (DNG) Specification (p. 81).

Examples

>>> M_color_matrix_1 = np.array([
...     [0.5309, -0.0229, -0.0336],
...     [-0.6241, 1.3265, 0.3337],
...     [-0.0817, 0.1215, 0.6664]])
>>> M_color_matrix_2 = np.array([
...     [0.4716, 0.0603, -0.0830],
...     [-0.7798, 1.5474, 0.2480],
...     [-0.1496, 0.1937, 0.6651]])
>>> M_camera_calibration_1 = np.identity(3)
>>> M_camera_calibration_2 = np.identity(3)
>>> analog_balance = np.ones(3)
>>> M_forward_matrix_1 = np.array([
...     [0.8924, -0.1041, 0.1760],
...     [0.4351, 0.6621, -0.0972],
...     [0.0505, -0.1562, 0.9308]])
>>> M_forward_matrix_2 = np.array([
...     [0.8924, -0.1041, 0.1760],
...     [0.4351, 0.6621, -0.0972],
...     [0.0505, -0.1562, 0.9308]])
>>> camera_space_to_XYZ_matrix(  # doctest: +ELLIPSIS
...     np.array([0.32816244, 0.34698169]),
...     2850,
...     6500,
...     M_color_matrix_1,
...     M_color_matrix_2,
...     M_camera_calibration_1,
...     M_camera_calibration_2,
...     analog_balance,
...     M_forward_matrix_1,
...     M_forward_matrix_2)
array([[ 2.1604087..., -0.1041...    ,  0.2722498...],
       [ 1.0533324...,  0.6621...    , -0.1503561...],
       [ 0.1222553..., -0.1562...    ,  1.4398304...]])