Babl-0.1.62

babl is a dynamic, any to any, pixel format translation library.

It allows converting between different methods of storing pixels known as pixel formats that have with different bitdepths and other data representations, color models, color spaces and component permutations.

A vocabulary to formulate new pixel formats from existing primitives is provided as well as the framework to add new color models, spaces and data types.

Features

• 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.
• Can load color spaces from ICC v2 and v4 profiles containing RGB matrix + TRC, or CMYK profiles.
• 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.

GEGL through GeglBuffer provides tiled buffers with on disk storage as well as linear buffers with accessor functions for efficient data access transparently using babl fishes for translation to the desired pixel formats.

Download

The latest versioned development version of babl can be found in https://download.gimp.org/pub/babl/.

Babl uses git. The main repository is hosted by GNOME. It can be browsed online and cloned with:

git clone git://git.gnome.org/babl

NEWS

The following is a list of the major changes that have gone into each babl release. If there are significant improvements to babl when a GEGL release is done a babl release is most often put out just prior to the GEGL release.

2019-02-01 babl-0.1.62

Continuous integration with gitlab. Initial CMYK spaces with lcms2 based ICC support, much room for optimization. Improved custom space support for palette formats. scRGB space, works like sRGB but always with linear TRCs. Model introspection API permitting low overhead checks whether a format/model is RGB, CMYK type of alpha and similar.

2018-10-05 babl-0.1.60

Improved thread safety, acceleration for R'G'B'A u8 -> cairo-ARGB32 conversion.

2018-10-05 babl-0.1.58

Preserve color of transparent pixels in conversion to premultiplied alpha, Added single precision code-paths for faster fallback/reference conversions. New BABL_ICC_INTENT_PERFORMANCE bitflag for combining with intent as bitflags, use of matrix+trc when relative colorimetric CLUT is present. New color model and formats, CIE xyY.

2018-08-14 babl-0.1.56

Improvements to the caching of profiled conversion chains between invocations by ignoring unknown bits in cache file and remember which conversions yielded reference fishes. 2018-07-23 babl-0.1.54

Export babl_space_get_icc, babl_space_get, babl_model_with_space, babl_space_with_trc, babl_format_get_encoding, babl_model_is, SSE2 versions of YA float and Y float to CIE L float.

2018-06-02 babl-0.1.52

Concurrency fixes and fixes to handling of 0/1 entry palettes, do not pre-equalize XYZ conversion matrices for sRGB, internal clean-ups, pre-define ACES2065-1 and ACEScg BablSpaces, add R~G~B~ set of spaces, which for all BablSpaces mean use sRGB TRC.

2018-05-20 babl-0.1.50

Improvements to speed and precision of indexed code, improvements to meson build.

2018-05-15 babl-0.1.48

fix u8 <-> double conversions for chroma, SSE2 version of RGBA float to CIE L / Lab. Build with -Ofast by default.

2018-04-10 babl-0.1.46

added extensions with more coverage for u32, half and other utilit fast paths improving fast path coverage.

2018-02-18 babl-0.1.44

Fix bug in custom primaries/ICC fast paths, improve meson build

2018-01-23 babl-0.1.42

Fully initialize fishes when loading from cache.

2018-01-16 babl-0.1.40

Added format "CIE XYZ alpha" color model and formats. New API babl_process_rows for reduced overhead in some scenarios; though bigger gains seen also for regular babl_process with reimplemented branch-free dispatch, and faster cbrt. Added meson build; being tested in parallel with auotmake, Improved reference conversions for formats skipping some of models components, Fixed gamma handling in indexed/palettized formats and improved gamma precision consistenct in sse2 conversions.

2017-11-15 babl-0.1.38

Added format "CIE L float", a couple of protections against division by 0.0

2017-11-10 babl-0.1.36

Optimized customized primary aware code paths for CIE Lab<->RGB conversions, improved accuracy of gamma approximations. New API babl_format_exists() for checking validity of babl format name, crash proofing of cache handling and use of environment variables.

2017-10-06 babl-0.1.34

Brown paper bag release, Fix indexed / custom primaries conflict, and re-export a symbol used by old GEGL/GIMPs.

2017-10-03 babl-0.1.32

Added custom primaries and TRC support through ICC parsing, improved float<->half performance, rewrite of all conversions functions to adhere to new signature.

2017-07-15 babl-0.1.30

Thread stability for palette modes, stricter alpha preservation, now cross-compilable on android.

2017-05-30 babl-0.1.28

Fast paths for Lav <-> Lch, release triggered by pending GIMP release.

2017-05-09 babl-0.1.26

Build and install HCY color space, platform independences fixes to fish cache.

2017-02-01 babl-0.1.24

Improvements to profile cache persistance, fast paths that improve actual GIMP use on various precisions, use single precision constants for some more of CIE computions.

2016-11-05 babl-0.1.22

Added cache of profiled conversions, added HCY color model, some precision and performance updated for fast paths.

2016-11-05 babl-0.1.20

Fix run-time errors, leaks, and race conditions. Add conditional fast paths.

2016-06-13 babl-0.1.18

Bugfix: take alpha threshold in consideration when processing floats in SSE2.

2016-02-12 babl-0.1.16

Improvements to half float reference, SIMD, and fast-paths, and CIE float fast paths; cleanups of fast path extensions.

2015-11-19 babl-0.1.14

sRGB precision tuning, stability fixes, locale fix for setting error tolerance.

2015-02-03 babl-0.1.12

optimizations for floating point conversions, HSV and HSL color models, removal of dead code, fixed CIE Lab conversions.

2012-03-30 babl-0.1.10

LUT based speedups for gamma correction / uncorrection.

2012-03-30 babl-0.1.8

Added support for indexed/pallette based formats, constified API.

2011-11-18 babl-0.1.6

Build improvements, remove blatantly wrong conversions from extensions, made it possible to distinguish format_n formats from others, improvements to vala/gobject introspection support.

2011-01-20 babl-0.1.4

Improved cross platform build ability, added code to handle n-component formats, remove extraenous runtime profiling that impacted performance.

2010-01-15 babl-0.1.2

Made babl mostly threadsafe (sufficient for GIMP/GEGLs needs). Streamlined core functionality, reducing number of function calls and removing overeager instrumentation.

2009-05-20 babl-0.1.0

Support for RGBA representation in the frequency domain, un-pre-multiply close-to-zero alpha values to complete black instead of slightly brighter than black, add a BABL_ALPHA_THRESHOLD constant to the API, do a complete overhaul of the babl API and do some changes to increase portability of the library.

2008-06-12 babl-0.0.22

Speed improvements due to: coalesced hashing, early bail out upon creation of duplicate formats, caching of non existing paths. Large amounts of the core has also been reviewed and refactored. Improved conversion coverage in the matrix.

2008-02-27 babl-0.0.20

Builds on OSX Check <0.0 and >1.0 values conversions for accuracy as well.

For more news see git log.

Documentation

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 the capability to describe new formats based on a vocabulary of user registered color models and data types.

Babl provides a base vocabulary in BablBase and some extensions that are thought to be generally useful.

When performing further extensions to the vocabulary of babl, the internal consistency is governed by reference conversions that operate on double (64 bit floating point values). The only color model created during BablCore bootstrap is RGBA (linear light RGB, 0.0 - 1.0, with a linear 0.0 - 1.0 opacity channel) backed by the double datatype. Defined similarily to scRGB using 64bit floating point.

If babls conversion isn't fast enough, you can provide your own conversion shortcut between two formats. The registered shortcut might also be used by babl as an intermediate conversion when constructing BablFishes for other conversions.

Babl extensions are shared objects. If you have already developed some fast conversion functions, wrapping them as babl extensions should 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,
              pixel_count);

The processing operation that babl performs is copying including conversions if needed between linear buffers containing the same count of pixels, with different pixel formats.

int width = 123, height = 581, pixel_count = width * height;

const Babl *srgb             = babl_format ("R'G'B' u8");
const Babl *lab              = babl_format ("CIE Lab float");
const Babl *srgb_to_lab_fish = babl_fish (srgb, lab);

float         *lab_buffer;
unsigned char *srgb_buffer;

babl_init ();

srgb_buffer = malloc (pixel_count * babl_format_get_bytes_per_pixel (srgb));
lab_buffer  = malloc (pixel_count * 3 * sizeof (float));

...... load data into srgb_buffer .......

babl_process (srgb_to_lab_fish, srgb_buffer, lab_buffer, pixel_count);

...... do operation in lab space ........

babl_process (babl_fish(lab, srgb),
              lab_buffer, srgb_buffer, pixel_count);

/* the data has now been transformed back to srgb data */

If the existing pixel formats are not sufficient for your conversion needs, new ones can be created on the fly. The constructor will provide the prior created one if duplicates are registered.

const Babl *format = babl_format_new (babl_model ("R'G'B'"),
                                      babl_type ("u16"),
                                      babl_component ("B'"),
                                      babl_component ("G'"),
                                      babl_component ("R'"),
                                      NULL);

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.

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

Vocabulary

+-

Environment

Through the environment variable BABL_TOLERANCE you can control a speed/performance trade off that by default is set very low (0.000001) values in the range 0.01-0.1 can provide reasonable preview performance by allowing lower numerical accuracy

.

BABL_PATH contains the path of the directory, containing the .so extensions to babl.

Extending

For samples of how the current internal API specification of data types, color models, and conversions look in the extensions/ directory. The tables in this HTML file is directly generated based on the data registered by BablCore (double and RGBA), BablBase (core datatypes, and RGB models), extensions (CIE Lab, naive CMYK, various shortcut conversions).

Directory Overview

babl-dist-root
 │
 ├──babl       the babl core
 │   └──base   reference implementations for RGB and Grayscale Color Models,
 │             8bit 16bit, and 32bit and 64bit floating point.
 ├──extensions CIE-Lab color model as well as a naive-CMYK color model.
 │             also contains a random cribbage of old conversion optimized
 │             code from gggl. Finding more exsisting conversions in third
 │             part libraries (hermes, lcms?, liboil?) could improve the
 │             speed of babl.
 ├──tests      tests used to keep babl sane during development.
 └──docs       Documentation/webpage for babl (the document you are reading
               originated there.

Pre-multiplied alpha

babl stores color information in transparent pre-multiplied or associated alpha pixels in floating point formats. With floating point pixel formats standard way of handling alpha maintains color information very near fully transparent pixels - by introducing a limit: BABL_ALPHA_FLOOR which is 1/65536.0, and treating all alphas beteen zero and this value as this value we maintain color information while the discrepancy in behavior gets concealed by quantization in 16bit and 8bit formats.

For images that already are in a premultiplied format on import, this change has no impact on its use for pre-multiplied arithmetic, meaning that superluminous colors are still supported, it also opens up to GEGL more widely expect premultiplied data in more operations which will become a speedup when more filters want to integrate in the layer processing pipeline.

There is a post on patreon with further details about the implementation.

TODO

• Support for datatypes that are not a multiple of 8bit.

Copyright

Babl is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

Authors

Øyvind Kolås pippin at gimp.org

Original author.

Sven Neumann sven at gimp.org

Build sanity and optimizations.

Michael Natterer mitch at gimp.org

Build sanity.

Kevin Cozens kcozens at cvs.gnome.org

Build sanity.

Tim Mooney

Portability fixes.

Michael Schumacher schumaml at cvs.gnome.org

win32 support for dynamic extensions.

Portability fixes.

Jan Heller jheller at svn.gnome.org

Optimizations, refactoring and documentation.

Mukund Sivaraman muks at mukund.org

Sparse fixes and sanity.

dmacks at netspace.org

Build sanity

Sam Hocevar

Build sanity.

Zhang Junbo

Frequency domain color model.

Martin Nordholts

Optimizations and API overhaul.

Gary V. Vaughan

Multiplatform build support.

Stanislav Brabec

Portability patch.

Hubert Figuiere

C++ friendliness patch.

Danny Robson

Code cleanups.

Fryderyk Dziarmagowski freetz at gmx.net

Code cleanups.

Daniel Paredes García danipga at gmail.com

Initial work to make babl threadsafe

Rupert Weber gimp at leguanease.org

Documentation and other improvements

Jehan jehan at girinstud.io

win32 portabilitiy

Sven Claussner

Update DOAP file

Alexander Larsson

Math optimizations

Nils Philippsen

code cleanups

Simon Budig

cleanups

Micheal Muré

portability fixes

Edward E

win32 platform adaptations

Maxime Nicco

HSV color model extension

Teo Mazars

Color spaces/models in extensions

Daniel Sabo

Dead code elimination, general cleanups,

Michael Henning

Conversion fixes

Elle Stone

Verification and improvements to accuracy of color space conversions.

Thomas Manni

CIE related fixups

Roman Lebedev

Stability/crasher fixes

Jon Nordby

Portability, Stability and more

Massimo Valentini

stability fixes

Ell

fast paths

Félix Piédallu

Initial meson build