Merge pull request #88 from ampas/feature/prelinearized

Pre Linearised Camera & Fix For Formatting Of CLF

Author: KelSolaar

aces/idt/core/common.py

@@ -420,6 +420,7 @@ def clf_processing_elements(
     multipliers: ArrayLike,
     k_factor: float,
     use_range: bool = True,
+    include_white_balance_in_clf: bool = False,
 ) -> Et.Element:
     """
     Add the *Common LUT Format* (CLF) elements for given *IDT* matrix,
@@ -437,6 +438,8 @@ def clf_processing_elements(
     use_range
         Whether to use the range node to clamp the graph before the exposure
         factor :math:`k`.
+    include_white_balance_in_clf
+        Whether to include the white balance multipliers in the *CLF*.
 
     Returns
     -------
@@ -445,15 +448,24 @@ def clf_processing_elements(
     """
 
     def format_array(a: NDArrayFloat) -> str:
-        """Format given array :math:`a`."""
+        """Format given array :math:`a` into 3 lines of 3 numbers."""
+        # Reshape the array into a 3x3 matrix
+        reshaped_array = a.reshape(3, 3)
 
-        return re.sub(r"\[|\]|,", "", "\n".join(map(str, a.tolist())))
+        # Convert each row to a string and join them with newlines
+        formatted_lines = [" ".join(map(str, row)) for row in reshaped_array]
 
-    et_RGB_w = Et.SubElement(root, "Matrix", inBitDepth="32f", outBitDepth="32f")
-    et_description = Et.SubElement(et_RGB_w, "Description")
-    et_description.text = "White balance multipliers *b*."
-    et_array = Et.SubElement(et_RGB_w, "Array", dim="3 3")
-    et_array.text = f"\n{format_array(np.diag(multipliers))}"
+        # Join all the lines with newline characters
+        formatted_string = "\n\t\t".join(formatted_lines)
+
+        return formatted_string
+
+    if include_white_balance_in_clf:
+        et_RGB_w = Et.SubElement(root, "Matrix", inBitDepth="32f", outBitDepth="32f")
+        et_description = Et.SubElement(et_RGB_w, "Description")
+        et_description.text = "White balance multipliers *b*."
+        et_array = Et.SubElement(et_RGB_w, "Array", dim="3 3")
+        et_array.text = f"\n\t\t{format_array(np.diag(multipliers))}"
 
     if use_range:
         et_range = Et.SubElement(
@@ -474,13 +486,13 @@ def format_array(a: NDArrayFloat) -> str:
         "the scene producing ACES values [0.18, 0.18, 0.18]."
     )
     et_array = Et.SubElement(et_k, "Array", dim="3 3")
-    et_array.text = f"\n{format_array(np.ravel(np.diag([k_factor] * 3)))}"
+    et_array.text = f"\n\t\t{format_array(np.ravel(np.diag([k_factor] * 3)))}"
 
     et_M = Et.SubElement(root, "Matrix", inBitDepth="32f", outBitDepth="32f")
     et_description = Et.SubElement(et_M, "Description")
     et_description.text = "*Input Device Transform* (IDT) matrix *B*."
     et_array = Et.SubElement(et_M, "Array", dim="3 3")
-    et_array.text = f"\n{format_array(matrix)}"
+    et_array.text = f"\n\t\t{format_array(matrix)}"
 
     return root
 

aces/idt/core/constants.py

@@ -397,6 +397,14 @@ class ProjectSettingsMetadataConstants:
         ui_category=UICategories.HIDDEN,
     )
 
+    INCLUDE_WHITE_BALANCE_IN_CLF = Metadata(
+        default_value=False,
+        description="Whether to include the White Balance Matrix in the CLF",
+        display_name="Include White Balance in CLF",
+        ui_type=UITypes.BOOLEAN_FIELD,
+        ui_category=UICategories.STANDARD,
+    )
+
     ALL: ClassVar[tuple[Metadata, ...]] = (
         SCHEMA_VERSION,
         CAMERA_MAKE,
@@ -427,4 +435,5 @@ class ProjectSettingsMetadataConstants:
         FILE_TYPE,
         EV_WEIGHTS,
         OPTIMIZATION_KWARGS,
+        INCLUDE_WHITE_BALANCE_IN_CLF,
     )

aces/idt/framework/project_settings.py

@@ -166,6 +166,10 @@ def __init__(self, **kwargs: Dict):
             "optimization_kwargs",
             IDTProjectSettings.optimization_kwargs.metadata.default_value,
         )
+        self._include_white_balance_in_clf = kwargs.get(
+            "include_white_balance_in_clf",
+            IDTProjectSettings.include_white_balance_in_clf.metadata.default_value,
+        )
 
     @metadata_property(metadata=MetadataConstants.SCHEMA_VERSION)
     def schema_version(self) -> str:
@@ -544,6 +548,18 @@ def optimization_kwargs(self) -> Dict:
 
         return self._optimization_kwargs
 
+    @metadata_property(metadata=MetadataConstants.INCLUDE_WHITE_BALANCE_IN_CLF)
+    def include_white_balance_in_clf(self) -> bool:
+        """
+        Getter property for whether to include the white balance in the *CLF*.
+
+        Returns
+        -------
+        :class:`bool`
+            Whether to include the white balance in the *CLF*.
+        """
+        return self._include_white_balance_in_clf
+
     def get_reference_colour_checker_samples(self) -> NDArrayFloat:
         """
         Return the reference colour checker samples.

aces/idt/generators/__init__.py

@@ -1,8 +1,13 @@
 from .base_generator import IDTBaseGenerator
+from .prelinearized_idt import IDTGeneratorPreLinearizedCamera
 from .prosumer_camera import IDTGeneratorProsumerCamera
 
-GENERATORS = {IDTGeneratorProsumerCamera.GENERATOR_NAME: IDTGeneratorProsumerCamera}
+GENERATORS = {
+    IDTGeneratorProsumerCamera.GENERATOR_NAME: IDTGeneratorProsumerCamera,
+    IDTGeneratorPreLinearizedCamera.GENERATOR_NAME: IDTGeneratorPreLinearizedCamera,
+}
 
 __all__ = ["IDTBaseGenerator"]
 __all__ += ["IDTGeneratorProsumerCamera"]
+__all__ += ["IDTGeneratorPreLinearizedCamera"]
 __all__ += ["GENERATORS"]

aces/idt/generators/base_generator.py

@@ -692,7 +692,7 @@ def to_clf(self, output_directory: Path | str) -> str:
         def format_array(a):
             """Format given array :math:`a`."""
 
-            return re.sub(r"\[|\]|,", "", "\n".join(map(str, a.tolist())))
+            return re.sub(r"\[|\]|,", "", "\n\t\t".join(map(str, a.tolist())))
 
         et_input_descriptor = Et.SubElement(root, "InputDescriptor")
         et_input_descriptor.text = f"{camera_make} {camera_model}"
@@ -712,21 +712,32 @@ def format_array(a):
             )
             sub_element.text = str(value)
 
-        et_lut = Et.SubElement(
-            root,
-            "LUT1D",
-            inBitDepth="32f",
-            outBitDepth="32f",
-            interpolation="linear",
-        )
         LUT_decoding = self._LUT_decoding
-        channels = 1 if isinstance(LUT_decoding, LUT1D) else 3
-        et_description = Et.SubElement(et_lut, "Description")
-        et_description.text = f"Linearisation *{LUT_decoding.__class__.__name__}*."
-        et_array = Et.SubElement(et_lut, "Array", dim=f"{LUT_decoding.size} {channels}")
-        et_array.text = f"\n{format_array(LUT_decoding.table)}"
+        if LUT_decoding:
+            et_lut = Et.SubElement(
+                root,
+                "LUT1D",
+                inBitDepth="32f",
+                outBitDepth="32f",
+                interpolation="linear",
+            )
 
-        root = clf_processing_elements(root, self._M, self._RGB_w, self._k, False)
+            channels = 1 if isinstance(LUT_decoding, LUT1D) else 3
+            et_description = Et.SubElement(et_lut, "Description")
+            et_description.text = f"Linearisation *{LUT_decoding.__class__.__name__}*."
+            et_array = Et.SubElement(
+                et_lut, "Array", dim=f"{LUT_decoding.size} {channels}"
+            )
+            et_array.text = f"\n\t\t{format_array(LUT_decoding.table)}"
+
+        root = clf_processing_elements(
+            root,
+            self._M,
+            self._RGB_w,
+            self._k,
+            False,
+            self.project_settings.include_white_balance_in_clf,
+        )
 
         clf_path = (
             f"{output_directory}/"

aces/idt/generators/prelinearized_idt.py

@@ -0,0 +1,132 @@
+"""
+IDT Prosumer Camera Generator
+=============================
+
+Define the *IDT* generator class for a *Prosumer Camera*.
+"""
+
+import logging
+
+import matplotlib as mpl
+from colour import LUT3x1D
+from colour.utilities import as_float_array
+
+from aces.idt import DirectoryStructure
+from aces.idt.generators.prosumer_camera import IDTGeneratorProsumerCamera
+
+# TODO are the mpl.use things needed in every file?
+mpl.use("Agg")
+
+__author__ = "Alex Forsythe, Joshua Pines, Thomas Mansencal, Nick Shaw, Adam Davis"
+__copyright__ = "Copyright 2022 Academy of Motion Picture Arts and Sciences"
+__license__ = "Academy of Motion Picture Arts and Sciences License Terms"
+__maintainer__ = "Academy of Motion Picture Arts and Sciences"
+__email__ = "acessupport@oscars.org"
+__status__ = "Production"
+
+__all__ = [
+    "IDTGeneratorPreLinearizedCamera",
+]
+
+LOGGER = logging.getLogger(__name__)
+
+
+class IDTGeneratorPreLinearizedCamera(IDTGeneratorProsumerCamera):
+    """
+    Define an *IDT* generator for a *PreLinearized Camera*.
+
+    Parameters
+    ----------
+    project_settings : IDTProjectSettings, optional
+        *IDT* generator settings.
+
+    Attributes
+    ----------
+    -   :attr:`~aces.idt.IDTBaseGenerator.GENERATOR_NAME`
+
+    Methods
+    -------
+    -   :meth:`~aces.idt.IDTBaseGenerator.generate_LUT`
+    -   :meth:`~aces.idt.IDTBaseGenerator.filter_LUT`
+    """
+
+    GENERATOR_NAME = "IDTGeneratorPreLinearizedCamera"
+    """*IDT* generator name."""
+
+    def __init__(self, project_settings):
+        super().__init__(project_settings)
+
+    def generate_LUT(self) -> LUT3x1D:
+        """
+        Generate an unfiltered linearisation *LUT* for the camera samples.
+
+        The *LUT* generation process is worth describing, the camera samples are
+        unlikely to cover the [0, 1] domain and thus need to be extrapolated.
+
+        Two extrapolated datasets are generated:
+
+            -   Linearly extrapolated for the left edge missing data whose
+                clipping likelihood is low and thus can be extrapolated safely.
+            -   Constant extrapolated for the right edge missing data whose
+                clipping likelihood is high and thus cannot be extrapolated
+                safely
+
+        Because the camera encoded data response is logarithmic, the slope of
+        the center portion of the data is computed and fitted. The fitted line
+        is used to extrapolate the right edge missing data. It is blended
+        through a smoothstep with the constant extrapolated samples. The blend
+        is fully achieved at the right edge of the camera samples.
+
+        Returns
+        -------
+        :class:`LUT3x1D`
+            Unfiltered linearisation *LUT* for the camera samples.
+        """
+        # size = self.project_settings.lut_size
+        # LOGGER.info('Generating unfiltered "LUT3x1D" with "%s" size...', size)
+        # self._LUT_unfiltered = LUT3x1D(size=size, name="LUT - Unfiltered")
+        # return self._LUT_unfiltered
+        return None
+
+    def filter_LUT(self) -> LUT3x1D:
+        """
+        Filter/smooth the linearisation *LUT* for the camera samples.
+
+        The *LUT* filtering is performed with a gaussian convolution, the sigma
+        value represents the window size. To prevent that the edges of the
+        *LUT* are affected by the convolution, the *LUT* is extended, i.e.
+        extrapolated at a safe two sigmas in both directions. The left edge is
+        linearly extrapolated while the right edge is logarithmically
+        extrapolated.
+
+        Returns
+        -------
+        :class:`LUT3x1D`
+            Filtered linearisation *LUT* for the camera samples.
+        """
+        # LOGGER.info('No Filtering Simply Copying "LUT3x1D"')
+        #
+        # self._LUT_filtered = self._LUT_unfiltered.copy()
+        # self._LUT_filtered.name = "LUT - Filtered"
+        # return self._LUT_filtered
+        return None
+
+    def decode(self) -> None:
+        """
+        Decode the camera samples.
+
+        The camera samples are decoded using the camera's *IDT* and the
+        *IDT* generator settings.
+
+        Returns
+        -------
+        None
+        """
+        LOGGER.info("Decoding camera samples...")
+        self._samples_decoded = {}
+        for EV in sorted(self._samples_analysis[DirectoryStructure.COLOUR_CHECKER]):
+            self._samples_decoded[EV] = as_float_array(
+                self._samples_analysis[DirectoryStructure.COLOUR_CHECKER][EV][
+                    "samples_median"
+                ]
+            )

tests/resources/example_from_folder.json

@@ -5,6 +5,7 @@
     "aces_user_name": "",
     "camera_make": "",
     "camera_model": "",
+    "include_white_balance_in_clf": false,
     "iso": 800,
     "temperature": 6000,
     "additional_camera_settings": "",

tests/test_application.py

@@ -1226,3 +1226,15 @@ def test_prosumer_generator_from_archive_zip(self):
             self.get_test_output_folder(), archive_serialised_generator=False
         )
         self.assertEqual(os.path.exists(zip_file), True)
+
+    def test_prelinearized_idt_generator_from_archive_zip(self):
+        """Test the prosumer generator from archive with a json file"""
+        idt_application = IDTGeneratorApplication()
+        idt_application.generator = "IDTGeneratorPreLinearizedCamera"
+
+        archive = os.path.join(self.get_test_resources_folder(), "FULL_STOPS_EXR.zip")
+        idt_application.process(archive)
+        zip_file = idt_application.zip(
+            self.get_test_output_folder(), archive_serialised_generator=False
+        )
+        self.assertEqual(os.path.exists(zip_file), True)