Adsk Contrib - Enhanced methods to find an equivalent color space bet…

…ween configs (#1788) * - Implementation of identifyInterchangeSpace, identifyBuiltinColorSpace and AreProcessorsEquivalent. - Remove some include of Processor.h where it wasn't needed. Signed-off-by: Cédrik Fuoco <[email protected]> * Moving code from Config.cpp to ConfigUtils.cpp and using wrapper in Config.cpp instead. Fixing identations issues. Fixing styling issues. Signed-off-by: Cédrik Fuoco <[email protected]> * Typo and comments tweaks Moving the creation of the editable config into the wrapper of isColorSpaceLinear instead of doing it inside the function. Signed-off-by: Cédrik Fuoco <[email protected]> * Splitting identifyInterchangeSpace into two methods, one for source config and one for builtin. Adding back isColorSpaceLinear inside Config.cpp since we need access to getProcessorWithoutCaching. Refactor some of config utils function to return index instead of string. Creating editable config in the two wrappers to prevent processor caching. Signed-off-by: Cédrik Fuoco <[email protected]> * Tentative change to phase out isProcessorEquivalent. Signed-off-by: Cédrik Fuoco <[email protected]> * Refactor code and add tests Signed-off-by: Doug Walker <[email protected]> * Remove unused method Signed-off-by: Doug Walker <[email protected]> * Remove unused method, tk 2 Signed-off-by: Doug Walker <[email protected]> * Tweak comments Signed-off-by: Doug Walker <[email protected]> * Python binding for IdentifyInterchangeSpace and IdentifyBuiltinColorSpace methods. Adding a couple python unit tests to cover the new methods (same unit test as the C++ side, but not all of them) Signed-off-by: Cédrik Fuoco <[email protected]> * - Implementation of identifyInterchangeSpace, identifyBuiltinColorSpace and AreProcessorsEquivalent. - Remove some include of Processor.h where it wasn't needed. Signed-off-by: Cédrik Fuoco <[email protected]> * Moving code from Config.cpp to ConfigUtils.cpp and using wrapper in Config.cpp instead. Fixing identations issues. Fixing styling issues. Signed-off-by: Cédrik Fuoco <[email protected]> * Typo and comments tweaks Moving the creation of the editable config into the wrapper of isColorSpaceLinear instead of doing it inside the function. Signed-off-by: Cédrik Fuoco <[email protected]> * Splitting identifyInterchangeSpace into two methods, one for source config and one for builtin. Adding back isColorSpaceLinear inside Config.cpp since we need access to getProcessorWithoutCaching. Refactor some of config utils function to return index instead of string. Creating editable config in the two wrappers to prevent processor caching. Signed-off-by: Cédrik Fuoco <[email protected]> * Tentative change to phase out isProcessorEquivalent. Signed-off-by: Cédrik Fuoco <[email protected]> * Refactor code and add tests Signed-off-by: Doug Walker <[email protected]> * Remove unused method Signed-off-by: Doug Walker <[email protected]> * Remove unused method, tk 2 Signed-off-by: Doug Walker <[email protected]> * Tweak comments Signed-off-by: Doug Walker <[email protected]> * Python binding for IdentifyInterchangeSpace and IdentifyBuiltinColorSpace methods. Adding a couple python unit tests to cover the new methods (same unit test as the C++ side, but not all of them) Signed-off-by: Cédrik Fuoco <[email protected]> * Fixing problem with the rebase Signed-off-by: Cédrik Fuoco <[email protected]> * Make sure the unit test is using the static method Signed-off-by: Cédrik Fuoco <[email protected]> --------- Signed-off-by: Cédrik Fuoco <[email protected]> Signed-off-by: Doug Walker <[email protected]> Signed-off-by: Cédrik Fuoco <[email protected]> Co-authored-by: Doug Walker <[email protected]>
AcademySoftwareFoundation · Jun 27, 2023 · 8e801dc · 8e801dc
1 parent 6bf2dc0
commit 8e801dc
Show file tree

Hide file tree

Showing 13 changed files with 1,730 additions and 640 deletions.
diff --git a/include/OpenColorIO/OpenColorIO.h b/include/OpenColorIO/OpenColorIO.h
@@ -695,12 +695,78 @@ class OCIOEXPORT Config
      */
     bool isColorSpaceLinear(const char * colorSpace, ReferenceSpaceType referenceSpaceType) const;
 
-    //
-    // Roles
-    //
-
-    // A role is like an alias for a colorspace. You can query the colorspace
-    // corresponding to a role using the normal getColorSpace fcn.
+    /**
+     * \brief Find the name of the color space in the source config that is the same as 
+     *        a color space in the default built-in config.  For example, setting the
+     *        builtinColorSpaceName to "sRGB - Texture" (a color space name from that
+     *        config), would return the name for the corresponding sRGB texture space in
+     *        the current config (or empty if it was not found).  Note that this method
+     *        relies on heuristics which may evolve over time and which may not work on
+     *        all configs.
+     *
+     *        The method only looks at active color spaces.  If the interchange roles are
+     *        missing and heuristics are used, only scene-referred color spaces are searched.
+     * 
+     * \param srcConfig The config to search for the desired color space.
+     * \param builtinConfig The built-in config to use.  See \ref Config::CreateFromBuiltinConfig.
+     * \param builtinColorSpaceName Color space name in the built-in default config.
+     * \return Matching color space name from the source config. Empty if not found.
+     * 
+     * \throw Exception if an interchange space cannot be found or the equivalent space cannot be found.
+     */
+    static const char * IdentifyBuiltinColorSpace(const ConstConfigRcPtr & srcConfig,
+                                                  const ConstConfigRcPtr & builtinConfig, 
+                                                  const char * builtinColorSpaceName);
+
+    /**
+     * \brief Identify the two names of a common color space that exists in both the 
+     *        given config and the provided built-in config that may be used for converting
+     *        color spaces between the two configs.  If both configs have the interchange
+     *        role set, than the color spaces set to that role will be returned.  Otherwise,
+     *        heuristics will be used to try and identify a known color space in the source
+     *        config.  These are the same heuristics that are used for other methods such as
+     *        identifyBuiltinColorSpace and GetProcessorTo/FromBuiltinColorSpace.
+     *
+     *        Using this method in connection with GetProcessorFromConfigs is more efficient
+     *        if you need to call GetProcessorTo/FromBuiltinColorSpace multiple times since it 
+     *        is only necessary to run the heuristics once (to identify the interchange spaces).
+     *
+     *        The srcColorSpaceName and builtinColorSpace name are used to decide which
+     *        interchange role to use (scene- or display-referred).  However, they are not
+     *        used if the interchange roles are not present and the heuristics are used.
+     *        It is actually only the ReferenceSpaceType of the color spaces that are used,
+     *        so it is not necessary to call this function multiple times if all the spaces
+     *        are of the same type.  (These are the same arguments that would also be set if
+     *        you were instead calling GetProcessorTo/FromBuiltinColorSpace.)
+     * 
+     * \param[out] srcInterchangeName Color space name from the source config.
+     * \param[out] builtinInterchangeName Corresponding color space name from the built-in config.
+     * \param srcConfig The config to search for the desired color space.
+     * \param srcColorSpaceName Color space name in the given config to convert to/from.
+     * \param builtinConfig The built-in config to use.  See \ref Config::CreateFromBuiltinConfig.
+     * \param builtinColorSpaceName Color space name in the default built-in config.
+     * 
+     * \throw Exception if either the srcInterchange or builtinInterchange cannot be identified.
+     */
+    static void IdentifyInterchangeSpace(const char ** srcInterchangeName,
+                                         const char ** builtinInterchangeName,
+                                         const ConstConfigRcPtr & srcConfig,
+                                         const char * srcColorSpaceName,
+                                         const ConstConfigRcPtr & builtinConfig,
+                                         const char * builtinColorSpaceName);
+
+    /**
+     * \defgroup Methods related to Roles.
+     * @{
+     *    
+     * A role allows a config author to indicate that a given color space should be used
+     * for a particular purpose.  
+     *
+     * Role names may be passed to most functions that accept color space names, such as 
+     * getColorSpace.  So for example, you may find the name of the color space assigned 
+     * to the scene_linear role by getting the color space object for "scene_linear" and 
+     * then calling getName on the color space object.
+     */
 
     /**
      * \brief
@@ -1261,7 +1327,7 @@ class OCIOEXPORT Config
      * 
      * If the source config defines the necessary Interchange Role (typically "aces_interchange"), 
      * then the conversion will be well-defined and equivalent to calling GetProcessorFromConfigs
-     * with the source config and the Built-in config
+     * with the source config and the Built-in config.
      * 
      * However, if the Interchange Roles are not present, heuristics will be used to try and 
      * identify a common color space in the source config that may be used to allow the conversion 
@@ -1274,26 +1340,25 @@ class OCIOEXPORT Config
      * \param srcConfig The user's source config.
      * \param srcColorSpaceName The name of the color space in the source config.
      * \param builtinColorSpaceName The name of the color space in the current default Built-in config.
+     * 
+     * \throw Exception if either the src or builtin interchange space cannot be identified.
      */
-    static ConstProcessorRcPtr GetProcessorToBuiltinColorSpace(
-                                                                ConstConfigRcPtr srcConfig,
-                                                                const char * srcColorSpaceName, 
-                                                                const char * builtinColorSpaceName);
+    static ConstProcessorRcPtr GetProcessorToBuiltinColorSpace(ConstConfigRcPtr srcConfig,
+                                                               const char * srcColorSpaceName, 
+                                                               const char * builtinColorSpaceName);
     /**
      * \brief See description of GetProcessorToBuiltinColorSpace.
      * 
      * \param builtinColorSpaceName The name of the color space in the current default Built-in config.
      * \param srcConfig The user's source config.
      * \param srcColorSpaceName The name of the color space in the source config. 
      */
-    static ConstProcessorRcPtr GetProcessorFromBuiltinColorSpace(
-                                                                const char * builtinColorSpaceName,
-                                                                ConstConfigRcPtr srcConfig,
-                                                                const char * srcColorSpaceName);
+    static ConstProcessorRcPtr GetProcessorFromBuiltinColorSpace(const char * builtinColorSpaceName,
+                                                                 ConstConfigRcPtr srcConfig,
+                                                                 const char * srcColorSpaceName);
 
     /**
-     * \brief Get a processor to convert between color spaces in two separate
-     *      configs.
+     * \brief Get a processor to convert between color spaces in two separate configs.
      * 
      * This relies on both configs having the aces_interchange role (when srcName
      * is scene-referred) or the role cie_xyz_d65_interchange (when srcName is
@@ -1313,6 +1378,9 @@ class OCIOEXPORT Config
     /**
      * The srcInterchangeName and dstInterchangeName must refer to a pair of
      * color spaces in the two configs that are the same.  A role name may also be used.
+     *
+     * Note: For all of the two-config GetProcessor functions, if either the source or 
+     * destination color spaces are data spaces, the entire processor will be a no-op.
      */
     static ConstProcessorRcPtr GetProcessorFromConfigs(const ConstConfigRcPtr & srcConfig,
                                                        const char * srcColorSpaceName,
@@ -1330,10 +1398,13 @@ class OCIOEXPORT Config
                                                        const char * dstColorSpaceName,
                                                        const char * dstInterchangeName);
 
+    /// Get the Processor Cache flags.
+    ProcessorCacheFlags getProcessorCacheFlags() const noexcept;
+
     /// Control the caching of processors in the config instance.  By default, caching is on.  
     /// The flags allow turning caching off entirely or only turning it off if dynamic
     /// properties are being used by the processor.
-    void setProcessorCacheFlags(ProcessorCacheFlags flags) noexcept;
+    void setProcessorCacheFlags(ProcessorCacheFlags flags) const noexcept;
 
     /**
      * \brief Clears this config's cache of Processor, CPUProcessor, and GPUProcessor instances. 

diff --git a/src/OpenColorIO/CMakeLists.txt b/src/OpenColorIO/CMakeLists.txt
@@ -17,6 +17,7 @@ set(SOURCES
     ColorSpace.cpp
     ColorSpaceSet.cpp
     Config.cpp
+    ConfigUtils.cpp
     Context.cpp
     ContextVariableUtils.cpp
     CPUProcessor.cpp