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