From: Øyvind Kolås Date: Mon, 22 Jul 2019 02:06:26 +0000 (+0200) Subject: docs: add separate pages for CMYK, ColorManagement and alpha X-Git-Tag: archive/raspbian/1%0.1.106-3+rpi1^2~15^2~11^2~85 X-Git-Url: https://dgit.raspbian.org/?a=commitdiff_plain;h=0476f8b8fee2019c54d2302d6009dfa6d07f1dc5;p=babl.git docs: add separate pages for CMYK, ColorManagement and alpha --- diff --git a/docs/CMYK-static.html b/docs/CMYK-static.html new file mode 100644 index 0000000..27cbe66 --- /dev/null +++ b/docs/CMYK-static.html @@ -0,0 +1,61 @@ + + + + + + + + CMYK - babl + + + + + + + +
+
+

Babl-0.1.67

+
+
+ + +
+
+ +

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
+
+ + + /babl-0.1.67 +
+
+ +
+
+ +
+
+ + + diff --git a/docs/CMYK.html b/docs/CMYK.html new file mode 100644 index 0000000..6a8539a --- /dev/null +++ b/docs/CMYK.html @@ -0,0 +1,87 @@ + + + + + + + + CMYK - babl + + + + + + + +
+
+

Babl-0.1.67

+
+
+ +
+
+

Contents

+
+ +
+ +
+
+ +

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
+
+ + + /babl-0.1.67 +
+
+ +
+
+ +
+
+ + + diff --git a/docs/ColorManagement-static.html b/docs/ColorManagement-static.html new file mode 100644 index 0000000..57c5516 --- /dev/null +++ b/docs/ColorManagement-static.html @@ -0,0 +1,64 @@ + + + + + + + + babl color management + + + + + + + + + + + +
+
+

Color Management

+ +

By default the babl API is assuming data to be (unbounded) sRGB data, 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" and "ProPhoto" spaces, as they are + defined with constants on their wikipedia pages. +

+ +

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. +

+ +

The conversions babl does with ICC profiles are according to what is known + as the relative-colorimetric intent, monitor profiles containing both the + matrices used by babl and 3d CLUTs (color look up tables) sometimes also do + relative-colorimetric transfer for the "perceptual" intent CLUTs, but with + a more flexible and possibly higher accuracy conversions.

+ +

Handling of CMYK is in a separate document.

+ + /babl-0.1.67 +
+
+ +
+
+ +
+
+ + + diff --git a/docs/ColorManagement.html b/docs/ColorManagement.html new file mode 100644 index 0000000..5bb8482 --- /dev/null +++ b/docs/ColorManagement.html @@ -0,0 +1,90 @@ + + + + + + + + babl color management + + + + + + + + + +
+
+

Contents

+
+ +
+ + +
+
+

Color Management

+ +

By default the babl API is assuming data to be (unbounded) sRGB data, 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" and "ProPhoto" spaces, as they are + defined with constants on their wikipedia pages. +

+ +

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. +

+ +

The conversions babl does with ICC profiles are according to what is known + as the relative-colorimetric intent, monitor profiles containing both the + matrices used by babl and 3d CLUTs (color look up tables) sometimes also do + relative-colorimetric transfer for the "perceptual" intent CLUTs, but with + a more flexible and possibly higher accuracy conversions.

+ +

Handling of CMYK is in a separate document.

+ + /babl-0.1.67 +
+
+ +
+
+ +
+
+ + + diff --git a/docs/Makefile.am b/docs/Makefile.am index bea1654..4a0e2cc 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -13,16 +13,20 @@ DIST_SUBDIRS= graphics # # HTML_FILES = index-static.html \ - index.html + index.html \ + CMYK.html \ + ColorManagement.html \ + SymmetricAlpha.html \ + Vocabulary.html EXTRA_DIST= \ babl.css \ tools/xml_insert.sh \ tools/changelog2rss \ index-static.html.in \ - ColorManagement.html \ - CMYK.html \ - SymmetricAlpha.html \ + ColorManagement-static.html \ + CMYK-static.html \ + SymmetricAlpha-static.html \ COPYING \ toc \ COPYING.LESSER \ @@ -35,8 +39,25 @@ DISTCLEANFILES = index-static.html $(BUILT_EXTRA_DIST) all: $(HTML_FILES) +SymmetricAlpha.html: SymmetricAlpha-static.html toc + echo -n "HTML: $@" + cp $< $@ + $(SHELL) $(top_srcdir)/docs/tools/xml_insert.sh $@ TOC $(top_srcdir)/docs/toc + echo " [OK]" + +CMYK.html: CMYK-static.html toc + echo -n "HTML: $@" + cp $< $@ + $(SHELL) $(top_srcdir)/docs/tools/xml_insert.sh $@ TOC $(top_srcdir)/docs/toc + echo " [OK]" + +ColorManagement.html: ColorManagement-static.html toc + echo -n "HTML: $@" + cp $< $@ + $(SHELL) $(top_srcdir)/docs/tools/xml_insert.sh $@ TOC $(top_srcdir)/docs/toc + echo " [OK]" + index.html: index-static.html \ - $(babl_html_dump) \ $(top_srcdir)/AUTHORS \ $(top_srcdir)/TODO \ $(top_srcdir)/NEWS \ @@ -44,14 +65,24 @@ index.html: index-static.html \ Makefile.am echo -n "HTML: $@" cp $< $@ + $(SHELL) $(top_srcdir)/docs/tools/xml_insert.sh $@ AUTHORS $(top_srcdir)/AUTHORS + $(SHELL) $(top_srcdir)/docs/tools/xml_insert.sh $@ TODO $(top_srcdir)/TODO + $(SHELL) $(top_srcdir)/docs/tools/xml_insert.sh $@ NEWS $(top_srcdir)/NEWS + $(SHELL) $(top_srcdir)/docs/tools/xml_insert.sh $@ TOC $(top_srcdir)/docs/toc + echo " [OK]" + + +Vocabulary.html: Vocabulary-static.html \ + $(babl_html_dump) \ + toc \ + Makefile.am + echo -n "HTML: $@" + cp $< $@ (which mktemp > /dev/null 2>&1 && TMPFILE=`mktemp` || TMPFILE="/tmp/babl_build_tempfile" ;\ export BABL_PATH="$(top_builddir)/extensions:$(top_builddir)/extensions/.libs"; $(babl_html_dump) > $$TMPFILE;\ $(SHELL) $(top_srcdir)/docs/tools/xml_insert.sh $@ BablBase $$TMPFILE;\ rm -f $$TMPFILE ) echo -n "." - $(SHELL) $(top_srcdir)/docs/tools/xml_insert.sh $@ AUTHORS $(top_srcdir)/AUTHORS - $(SHELL) $(top_srcdir)/docs/tools/xml_insert.sh $@ TODO $(top_srcdir)/TODO - $(SHELL) $(top_srcdir)/docs/tools/xml_insert.sh $@ NEWS $(top_srcdir)/NEWS $(SHELL) $(top_srcdir)/docs/tools/xml_insert.sh $@ TOC $(top_srcdir)/docs/toc echo " [OK]" diff --git a/docs/SymmetricAlpha-static.html b/docs/SymmetricAlpha-static.html new file mode 100644 index 0000000..4aca2d3 --- /dev/null +++ b/docs/SymmetricAlpha-static.html @@ -0,0 +1,102 @@ + + + + + + + + Symmetric Alpha - babl + + + + + + + +
+
+

Babl-0.1.67

+
+
+ + +
+
+ +

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.

+ + + + /babl-0.1.67 +
+
+ +
+
+ +
+
+ + + diff --git a/docs/SymmetricAlpha.html b/docs/SymmetricAlpha.html new file mode 100644 index 0000000..26ef6df --- /dev/null +++ b/docs/SymmetricAlpha.html @@ -0,0 +1,128 @@ + + + + + + + + Symmetric Alpha - babl + + + + + + + +
+
+

Babl-0.1.67

+
+
+ +
+
+

Contents

+
+ +
+ +
+
+ +

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.

+ + + + /babl-0.1.67 +
+
+ +
+
+ +
+
+ + + diff --git a/docs/Vocabulary-static.html b/docs/Vocabulary-static.html new file mode 100644 index 0000000..34b7b8c --- /dev/null +++ b/docs/Vocabulary-static.html @@ -0,0 +1,107 @@ + + + + + + + + babl-0.1.67 + + + + + + + + + + + +
+
+

Babl-0.1.67

+
+
+ + + +
+
+
+ + +

Vocabulary

+ + + + + /babl-0.1.67 +
+
+
+
+ +
+
+ + + diff --git a/docs/index-static.html.in b/docs/index-static.html.in index 5ffe554..e5ad863 100644 --- a/docs/index-static.html.in +++ b/docs/index-static.html.in @@ -1,7 +1,6 @@ - @@ -11,50 +10,10 @@ - + - - @@ -234,10 +193,6 @@ lab_buffer = malloc (pixel_count * 3 * sizeof (float)); - -

Vocabulary

- - +
  •   Usage
    • +
  •   Vocabulary
    • + + +
  •   Environment
    • +
  •   Extending
    • +
  •   Directory Overview
    • +
  •   Todo
    • + +
  •   Copyright
    • +
  •   Authors
    • + + diff --git a/tools/babl-html-dump.c b/tools/babl-html-dump.c index b685889..079b2d7 100644 --- a/tools/babl-html-dump.c +++ b/tools/babl-html-dump.c @@ -37,8 +37,8 @@ each_item (Babl *babl, void *user_data); static int - show_item (Babl *babl, - void *user_data); +show_item (Babl *babl, + void *user_data); static int hide_item (Babl *babl,