From: Øyvind Kolås Date: Wed, 19 Jun 2019 12:04:26 +0000 (+0200) Subject: docs: add section about symmetric alpha transforms X-Git-Tag: archive/raspbian/1%0.1.106-3+rpi1^2~15^2~11^2~100 X-Git-Url: https://dgit.raspbian.org/?a=commitdiff_plain;h=3ebf0dfb3eff341f3471cffecbdd7e087d5b8893;p=babl.git docs: add section about symmetric alpha transforms --- diff --git a/docs/index-static.html.in b/docs/index-static.html.in index 207a620..17c33a0 100644 --- a/docs/index-static.html.in +++ b/docs/index-static.html.in @@ -69,14 +69,12 @@

Contents

@@ -119,19 +118,15 @@
  • ANSI C without external dependencies, works on win32, linux and mac, 32bit and 64bit systems.
  • Stable, small API, with singleton objects returned.
    • -
  • Extendable with new formats, color models, components - and datatypes.
    • +
  • Extendable with new formats, color models, components and datatypes.
  • Can load   Color -Spaces
    • rom ICC v2 and v4 profiles containing RGB matrix + TRC, or from ICC v2 and v4 profiles containing RGB matrix + TRC, or CMYK profiles.
  • Symmetric-Alpha no loss of color fidelity due to asymptotic behavior near alpha 0.0 in floating point.
  • Reference 64bit floating point conversions for datatypes and color models, with 32bit floating point reference speed-ups in some places.
    • -
  • Self profiling/validating and optimizing, optimizing accuracy and -performance at runtime when the best performing single or multi-step conversion -path is chosen. This permits additional SIMD optimiations paths to be added and -to ones supported are competing with each other.
    • +
  • Runtime profiling/validating and code-path optimizing with persistence of profiling data across runs, with caching of results.

    • GEGL through For more news see git log. - -

    Documentation

    + + +

    Color Management

    + +

    All pixel formats in babl have a specified color space, if NULL is passed +as a space constants for (unbounded) linear sRGB data is assumed, data being +sRGB defines the conversion to and from gray-scale as well as the gamma + - or Transfer Response Curve, TRC, used for converting between linear and + non-linear variants of the data.

    + +

    babl has API for creating a format for a specific space: +babl_format_with_space("R'G'B' u16", babl_space ("Rec2020")) creates a +16 bit integer format for the Rec2020 color space. Babl knows internally about +"sRGB", "Rec2020", "Adobe", "Apple", "ProPhoto", "ACEScg" and "ACES2065-1" +spaces, as they are defined with constants on their wikipedia pages or similar upstream references.

    + +

    Additional spaces can be loaded from monitor-class matrix+TRC ICC v2 and + v4 profiles. Using babl_icc_make_space (see babl.h for details). The space of + a babl format can also be queried with babl_format_get_space. +

    + + +

    Symmetric transformations for floating point alpha

    + + +

    babl clamps the alpha used when going from separate alpha to associated +alpha or from associated alpha to separate alpha to BABL_ALPHA_FLOOR. This +replaces asymptotic behavior and direct precision loss of color precision when +multiplying or dividing by alphas near 0.0 with a consistent symmetric +transformation.

    + +

    Original intent of data as well as non-asymptotic precision loss is thus +maintained when the processing chain might temporarily use the other alpha +representation.

    + +
    +    #define BABL_ALPHA_FLOOR    (1.0/65536.0)
+    #define BABL_ALPHA_FLOOR_F  (1.0f/65536.0f)
+
    + +

    The deviation from not clamping near 0.0 is within the quantization margin +of 16bit integer alpha, thus no adaptations for any SIMD or and similar 8bit +and 16bit extensions of pixel format conversions are needed. +

    + +

    This is the clamping function in use:

    +
    +static inline float
+babl_epsilon_for_zero_float (float value)
+{
+ if (value <= BABL_ALPHA_FLOOR_F)
+ {
+   /* for performance one could directly retun BABL_ALPHA_FLOOR_F here
+      and dropping handling negative values consistently. */
+   if (value >= 0.0f)
+     return BABL_ALPHA_FLOOR_F;
+   else if (value >= -BABL_ALPHA_FLOOR_F)
+     return -BABL_ALPHA_FLOOR_F;
+ }
+ return value;  /* most common case, return input value */
+}
+
    +

    And an example use of this clamping function that is consistent with babls behavior:

    +
    +static inline void
+associated_to_separate_rgba (const float *associated_rgba,
+                                   float *separate_rgba)
+{
+  float alpha = associated_rgba[3];
+  float clamped_alpha = babl_epsilon_for_zero_float (alpha);
+  float reciprocal_alpha = 1.0f / clamped_alpha;
+
+  separate_rgba[0] = associated_rgba[0] * reciprocal_alpha;
+  separate_rgba[1] = associated_rgba[1] * reciprocal_alpha;
+  separate_rgba[2] = associated_rgba[2] * reciprocal_alpha;
+  separate_rgba[3] = alpha;
+}
+
    + + +

    For more detils see the commit message of the most recent refinement as well as blog post with further background.

    + + + +

    CMYK

    + +

    CMYK handling is done using babl-spaces created with ICC profiles +containing CMYK profiles. BablSpaces for these ICC profiles handle color conversions using lcms2 - or if compiled without lcms2 support a naive profile independent fallback.

    +

    When a babl space derived from a CMYK ICC profile is used to instantiate +RGB formats, the resulting formats are using the default/NULL space for +primaries and TRCs.

    + +

    The CMYK formats that use lcms2 for color interchange with the rest of +babl are the following, which are available for all data types, u8, u16, half +and float:

    +
    +
    CMYK
    Cyan Magenta Yellow Key, with 0 being white and 1.0 full ink coverage.
    +
    CMYKA
    as previous, with separate alpha channel
    +
    CaMaYaKaA
    as previous but associated alpha
    +
    cmyk
    inverted CMYK, where 0.0 is full ink coverage and 1.0 is none
    +
    cmykA
    as previous, with separate alpha channel
    +
    camayakaA
    as previous but associated alpha
    +
    + + +

    Usage

    When using BablFishes to do your conversions, you request a fish to convert between two formats, and an optimal fish to babls capability is provided that you can use to do your conversions. Babl also provides @@ -195,9 +294,6 @@ conversion when constructing BablFishes for other conversions. not take much time and will speed up babl for other users as well.

    - -

    Usage

    - 
    babl_process (babl_fish (source_format, destination_format),
               source_buffer, destination_buffer,
@@ -261,107 +357,6 @@ lab_buffer  = malloc (pixel_count * 3 * sizeof (float));
    --> - -

    Color Management

    - -

    All pixel formats in babl have a specified color space, if NULL is passed -as a space constants for (unbounded) linear sRGB data is assumed, data being -sRGB defines the conversion to and from gray-scale as well as the gamma - - or Transfer Response Curve, TRC, used for converting between linear and - non-linear variants of the data.

    - -

    babl has API for creating a format for a specific space: -babl_format_with_space("R'G'B' u16", babl_space ("Rec2020")) creates a -16 bit integer format for the Rec2020 color space. Babl knows internally about -"sRGB", "Rec2020", "Adobe", "Apple", "ProPhoto", "ACEScg" and "ACES2065-1" -spaces, as they are defined with constants on their wikipedia pages or similar upstream references.

    - -

    Additional spaces can be loaded from monitor-class matrix+TRC ICC v2 and - v4 profiles. Using babl_icc_make_space (see babl.h for details). The space of - a babl format can also be queried with babl_format_get_space. -

    - - -

    Symmetric transformations for floating point alpha

    - - -

    - babl clamps the alpha used when going from separate alpha to associated alpha -or from associated alpha to separate alpha to BABL_ALPHA_FLOOR. This avoids -asymptotic behavior and direct precision loss of color precision when multiplying or dividing by alphas near 0.0.

    - -

    Original intent of data as well as non-asymptotic precision loss is thus -maintained when the processing chain might temporarily use the other alpha -representation.

    - -
    -    #define BABL_ALPHA_FLOOR    (1.0/65536.0)
-    #define BABL_ALPHA_FLOOR_F  (1.0f/65536.0f)
-
    - -

    The deviation from not clamping near 0.0 is within the quantization margin -of 16bit integer alpha, thus no adaptations of are introduced for the 8bit and 16bit versions of pixel format conversions were needed. -

    - -

    This is the clamping function:

    -
    -
-    static inline float
-    babl_epsilon_for_zero_float (float value)
-    {
-     if (value <= BABL_ALPHA_FLOOR_F)
-     {
-       /* for performance one could directly retun BABL_ALPHA_FLOOR_F here
-          and dropping handling negative values consistently. */
-       if (value >= 0.0f)
-         return BABL_ALPHA_FLOOR_F;
-       else if (value >= -BABL_ALPHA_FLOOR_F)
-         return -BABL_ALPHA_FLOOR_F;
-     }
-     return value;  /* most common case, return input value */
-    }
-
    -

    And an example use of this clamping function that is consistent with babls behavior:

    -
    -    static inline void
-    associated_to_separate_rgba (const float *associated_rgba,
-                                       float *separate_rgba)
-    {
-      float alpha = associated_rgba[3];
-      float clamped_alpha = babl_epsilon_for_zero_float (alpha);
-      float reciprocal_alpha = 1.0f / clamped_alpha;
-
-      separate_rgba[0] = associated_rgba[0] * reciprocal_alpha;
-      separate_rgba[1] = associated_rgba[1] * reciprocal_alpha;
-      separate_rgba[2] = associated_rgba[2] * reciprocal_alpha;
-      separate_rgba[3] = alpha;
-    }
-
    - - -

    For more detils see the commit message of the most recent refinement as well as blog post with further background.

    - - - -

    CMYK

    - -

    CMYK handling is done using babl-spaces created with ICC profiles -containing CMYK profiles. BablSpaces for these ICC profiles handle color conversions using lcms2 - or if compiled without lcms2 support a naive profile independent fallback.

    -

    When a babl space derived from a CMYK ICC profile is used to instantiate -RGB formats, the resulting formats are using the default/NULL space for -primaries and TRCs.

    - -

    The CMYK formats that use lcms2 for color interchange with the rest of -babl are the following, which are available for all data types, u8, u16, half -and float:

    -
    -
    CMYK
    Cyan Magenta Yellow Key, with 0 being white and 1.0 full ink coverage.
    -
    CMYKA
    as previous, with non-associated alpha channel
    -
    CaMaYaKaA
    as previous but premultiplied/associated alpha
    -
    cmyk
    inverted CMYK, where 0.0 is full ink coverage and 1.0 is none
    -
    cmykA
    as previous, with non-associated alpha channel
    -
    camayakaA
    as previous but premultiplied/associated alpha
    -