Per-Track and Per-Clip Color (#1887)

Item and Composition now have optional color attributes so that Clips, Tracks and Stacks can have user-assigned colors. A new serializable Color class is introduced for storing assigned user interface colors.

Signed-off-by: Spencer Magnusson <[email protected]>

Author: semagnum

docs/tutorials/otio-serialized-schema-only-fields.md

@@ -40,6 +40,7 @@ parameters:
 ### Composition.1
 
 parameters:
+- *color*
 - *effects*
 - *enabled*
 - *markers*
@@ -50,6 +51,7 @@ parameters:
 ### Item.1
 
 parameters:
+- *color*
 - *effects*
 - *enabled*
 - *markers*
@@ -132,6 +134,7 @@ parameters:
 
 parameters:
 - *active_media_reference_key*
+- *color*
 - *effects*
 - *enabled*
 - *markers*
@@ -169,6 +172,7 @@ parameters:
 ### Gap.1
 
 parameters:
+- *color*
 - *effects*
 - *enabled*
 - *markers*
@@ -237,6 +241,7 @@ parameters:
 ### Stack.1
 
 parameters:
+- *color*
 - *effects*
 - *enabled*
 - *markers*
@@ -263,6 +268,7 @@ parameters:
 ### Track.1
 
 parameters:
+- *color*
 - *effects*
 - *enabled*
 - *kind*

docs/tutorials/otio-serialized-schema.md

@@ -88,6 +88,7 @@ Should be subclassed (for example by :class:`.Track` and :class:`.Stack`), not u
 ```
 
 parameters:
+- *color*: 
 - *effects*: 
 - *enabled*: If true, an Item contributes to compositions. For example, when an audio/video clip is ``enabled=false`` the clip is muted/hidden.
 - *markers*: 
@@ -106,6 +107,7 @@ None
 ```
 
 parameters:
+- *color*: 
 - *effects*: 
 - *enabled*: If true, an Item contributes to compositions. For example, when an audio/video clip is ``enabled=false`` the clip is muted/hidden.
 - *markers*: 
@@ -290,6 +292,7 @@ Contains a :class:`.MediaReference` and a trim on that media reference.
 
 parameters:
 - *active_media_reference_key*: 
+- *color*: 
 - *effects*: 
 - *enabled*: If true, an Item contributes to compositions. For example, when an audio/video clip is ``enabled=false`` the clip is muted/hidden.
 - *markers*: 
@@ -363,6 +366,7 @@ None
 ```
 
 parameters:
+- *color*: 
 - *effects*: 
 - *enabled*: If true, an Item contributes to compositions. For example, when an audio/video clip is ``enabled=false`` the clip is muted/hidden.
 - *markers*: 
@@ -591,6 +595,7 @@ None
 ```
 
 parameters:
+- *color*: 
 - *effects*: 
 - *enabled*: If true, an Item contributes to compositions. For example, when an audio/video clip is ``enabled=false`` the clip is muted/hidden.
 - *markers*: 
@@ -641,6 +646,7 @@ None
 ```
 
 parameters:
+- *color*: 
 - *effects*: 
 - *enabled*: If true, an Item contributes to compositions. For example, when an audio/video clip is ``enabled=false`` the clip is muted/hidden.
 - *kind*: 

src/opentimelineio/CMakeLists.txt

@@ -4,6 +4,7 @@
 set(OPENTIMELINEIO_HEADER_FILES
     anyDictionary.h
     anyVector.h
+    color.h
     clip.h
     composable.h
     composition.h
@@ -38,7 +39,8 @@ set(OPENTIMELINEIO_HEADER_FILES
     vectorIndexing.h
     version.h)
 
-add_library(opentimelineio ${OTIO_SHARED_OR_STATIC_LIB} 
+add_library(opentimelineio ${OTIO_SHARED_OR_STATIC_LIB}
+    color.cpp
     clip.cpp
     composable.cpp
     composition.cpp

src/opentimelineio/clip.cpp

@@ -15,8 +15,9 @@ Clip::Clip(
     AnyDictionary const&            metadata,
     std::vector<Effect*> const&     effects,
     std::vector<Marker*> const&     markers,
-    std::string const&              active_media_reference_key)
-    : Parent{ name, source_range, metadata, effects, markers }
+    std::string const&              active_media_reference_key,
+    std::optional<Color> const&     color)
+    : Parent{ name, source_range, metadata, effects, markers, /*enabled*/ true, color }
     , _active_media_reference_key(active_media_reference_key)
 {
     set_media_reference(media_reference);

src/opentimelineio/clip.h

@@ -46,7 +46,8 @@ class Clip : public Item
         AnyDictionary const&            metadata        = AnyDictionary(),
         std::vector<Effect*> const& effects             = std::vector<Effect*>(),
         std::vector<Marker*> const& markers             = std::vector<Marker*>(),
-        std::string const& active_media_reference_key   = default_media_key);
+        std::string const& active_media_reference_key   = default_media_key,
+        std::optional<Color> const&     color           = std::nullopt);
 
     /// @name Media References
     ///@{

src/opentimelineio/color.cpp

@@ -0,0 +1,165 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright Contributors to the OpenTimelineIO project
+
+#include <iomanip>
+#include <sstream>
+
+#include "opentimelineio/color.h"
+
+namespace opentimelineio { namespace OPENTIMELINEIO_VERSION {
+
+Color::Color(
+    double const         r,
+    double const         g,
+    double const         b,
+    double const         a,
+    std::string const&   name)
+    : _name(name),
+    _r(r),
+    _g(g),
+    _b(b),
+    _a(a) {}
+
+Color::Color(Color const& other) : _name(other.name()),
+                                   _r(other.r()),
+                                   _g(other.g()),
+                                   _b(other.b()),
+                                   _a(other.a()) {}
+
+const Color Color::pink(1.0, 0.0, 1.0, 1.0, "Pink");
+const Color Color::red(1.0, 0.0, 0.0, 1.0, "Red");
+const Color Color::orange(1.0, 0.5, 0.0, 1.0, "Orange");
+const Color Color::yellow(1.0, 1.0, 0.0, 1.0, "Yellow");
+const Color Color::green(0.0, 1.0, 0.0, 1.0, "Green");
+const Color Color::cyan(0.0, 1.0, 1.0, 1.0, "Cyan");
+const Color Color::blue(0.0, 0.0, 1.0, 1.0, "Blue");
+const Color Color::purple(0.5, 0.0, 0.5, 1.0, "Purple");
+const Color Color::magenta(1.0, 0.0, 1.0, 1.0, "Magenta");
+const Color Color::black(0.0, 0.0, 0.0, 1.0, "Black");
+const Color Color::white(1.0, 1.0, 1.0, 1.0, "White");
+const Color Color::transparent(1.0, 1.0, 1.0, 0.0, "Transparent");
+
+Color*
+Color::from_hex(std::string const& color)
+{
+    std::string temp = color;
+    if (temp[0] == '#')
+    {
+        temp = temp.substr(1);
+    }
+    else if (temp[0] == '0' && (temp[1] == 'x' || temp[1] == 'X'))
+    {
+        temp = temp.substr(2);
+    }
+
+    double _r, _g, _b, _a;
+    // 0xFFFFFFFF (rgba, 255)
+    int BASE_16 = 16;
+    double BASE_16_DIV = 255.0;
+    double BASE_8_DIV = 15.0;
+    if (temp.length() == 8)
+    {
+        _r = std::stoi(temp.substr(0, 2), nullptr, BASE_16) / BASE_16_DIV;
+        _g = std::stoi(temp.substr(2, 2), nullptr, BASE_16) / BASE_16_DIV;
+        _b = std::stoi(temp.substr(4, 2), nullptr, BASE_16) / BASE_16_DIV;
+        _a = std::stoi(temp.substr(6, 2), nullptr, BASE_16) / BASE_16_DIV;
+    }
+    // 0xFFFFFF (rgb, 255)
+    else if (temp.length() == 6)
+    {
+        _r = std::stoi(temp.substr(0, 2), nullptr, BASE_16) / BASE_16_DIV;
+        _g = std::stoi(temp.substr(2, 2), nullptr, BASE_16) / BASE_16_DIV;
+        _b = std::stoi(temp.substr(4, 2), nullptr, BASE_16) / BASE_16_DIV;
+        _a = 1.0;
+    }
+    // 0xFFF (rgb, 16)
+    else if (temp.length() == 3)
+    {
+        _r = std::stoi(temp.substr(0, 1), nullptr, BASE_16) / BASE_8_DIV;
+        _g = std::stoi(temp.substr(1, 1), nullptr, BASE_16) / BASE_8_DIV;
+        _b = std::stoi(temp.substr(2, 1), nullptr, BASE_16) / BASE_8_DIV;
+        _a = 1.0;
+    }
+    // 0xFFFF (rgba, 16)
+    else if (temp.length() == 4)
+    {
+        _r = std::stoi(temp.substr(0, 1), nullptr, BASE_16) / BASE_8_DIV;
+        _g = std::stoi(temp.substr(1, 1), nullptr, BASE_16) / BASE_8_DIV;
+        _b = std::stoi(temp.substr(2, 1), nullptr, BASE_16) / BASE_8_DIV;
+        _a = std::stoi(temp.substr(3, 1), nullptr, BASE_16) / BASE_8_DIV;
+    }
+    else {
+        throw std::invalid_argument("Invalid hex format");
+    }
+    return new Color(_r, _g, _b, _a);
+}
+
+Color*
+Color::from_int_list(std::vector<int> const& color, int bit_depth)
+{
+    double depth = pow(2, bit_depth) - 1.0;  // e.g. 8 = 255.0
+    if (color.size() == 3)
+        return new Color(color[0] / depth, color[1] / depth, color[2] / depth, 1.0);
+    else if (color.size() == 4)
+        return new Color(color[0] / depth, color[1] / depth, color[2] / depth, color[3] / depth);
+
+    throw std::invalid_argument("List must have exactly 3 or 4 elements");
+}
+
+Color*
+Color::from_agbr_int(unsigned int agbr) noexcept
+{
+    auto conv_r = (agbr & 0xFF) / 255.0;
+    auto conv_g = ((agbr >> 16) & 0xFF) / 255.0;
+    auto conv_b = ((agbr >> 8) & 0xFF) / 255.0;
+    auto conv_a = ((agbr >> 24) & 0xFF) / 255.0;
+    return new Color(conv_r, conv_g, conv_b, conv_a);
+}
+
+Color*
+Color::from_float_list(std::vector<double> const& color)
+{
+    if (color.size() == 3)
+        return new Color(color[0], color[1], color[2], 1.0);
+    else if (color.size() == 4)
+        return new Color(color[0], color[1], color[2], color[3]);
+
+    throw std::invalid_argument("List must have exactly 3 or 4 elements");
+}
+
+std::string
+Color::to_hex()
+{
+    auto rgba = to_rgba_int_list(8);
+    std::stringstream ss;
+    ss << "#";
+
+    ss << std::hex << std::setfill('0');
+    ss << std::setw(2) << rgba[0];
+    ss << std::setw(2) << rgba[1];
+    ss << std::setw(2) << rgba[2];
+    ss << std::setw(2) << rgba[3];
+    return ss.str();
+}
+
+std::vector<int>
+Color::to_rgba_int_list(int base)
+{
+    double math_base = pow(2, base) - 1.0;
+    return {int(_r * math_base), int(_g * math_base), int(_b * math_base), int(_a * math_base)};
+}
+
+unsigned int
+Color::to_agbr_integer()
+{
+    auto rgba = to_rgba_int_list(8);
+    return (rgba[3] << 24) + (rgba[2] << 16) + (rgba[1] << 8) + rgba[0];
+}
+
+std::vector<double>
+Color::to_rgba_float_list()
+{
+    return {_r, _g, _b, _a};
+}
+
+}} // namespace opentimelineio::OPENTIMELINEIO_VERSION

src/opentimelineio/color.h

@@ -0,0 +1,91 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright Contributors to the OpenTimelineIO project
+
+#pragma once
+
+#include <cmath>
+#include <vector>
+
+#include "opentimelineio/version.h"
+
+namespace opentimelineio { namespace OPENTIMELINEIO_VERSION {
+
+
+/// @brief Color consists of red, green, blue,
+/// and alpha double floating point values,
+/// allowing conversion between different formats.
+/// To be considered interoperable,
+/// the sRGB transfer function encoded values,
+/// ranging between zero and one, are expected to be accurate
+/// to within 1/255 of the intended value.
+/// Round-trip conversions may not be guaranteed outside that.
+/// This class is meant for use in user interface elements,
+// like marker or clip coloring, NOT for image pixel content.
+class Color
+{
+public:
+    struct Schema
+    {
+        static auto constexpr name   = "Color";
+        static int constexpr version = 1;
+    };
+
+    Color(
+        double const         r        = 1.f,
+        double const         g        = 1.f,
+        double const         b        = 1.f,
+        double const         a        = 1.f,
+        std::string const&   name     = "");
+
+    Color(Color const& other);
+
+    static const Color pink;
+    static const Color red;
+    static const Color orange;
+    static const Color yellow;
+    static const Color green;
+    static const Color cyan;
+    static const Color blue;
+    static const Color purple;
+    static const Color magenta;
+    static const Color black;
+    static const Color white;
+    static const Color transparent;
+
+    static Color* from_hex(std::string const& color);
+    static Color* from_int_list(std::vector<int> const& color, int bit_depth);
+    static Color* from_agbr_int(unsigned int agbr) noexcept;
+    static Color* from_float_list(std::vector<double> const& color);
+
+    friend bool
+    operator==(Color lhs, Color rhs) noexcept
+    {
+        return lhs.to_hex() == rhs.to_hex() && lhs.to_agbr_integer() == rhs.to_agbr_integer();
+    }
+
+    std::string to_hex();
+    std::vector<int> to_rgba_int_list(int base);
+    unsigned int to_agbr_integer();
+    std::vector<double> to_rgba_float_list();
+
+    double r() const { return _r; }
+    double g() const { return _g; }
+    double b() const { return _b; }
+    double a() const { return _a; }
+    std::string name() const { return _name; }
+
+    void set_r(double r) { _r = r; }
+    void set_g(double g) { _g = g; }
+    void set_b(double b) { _b = b; }
+    void set_a(double a) { _a = a; }
+    void set_name(std::string const& name) { _name = name; }
+
+private:
+    double _r;
+    double _g;
+    double _b;
+    double _a;
+    std::string _name;
+};
+
+}} // namespace opentimelineio::OPENTIMELINEIO_VERSION