Channel - Boost.GIL documentation

###  | #  |

# Channel

## Overview

A channel indicates the intensity of a color component (for example, the red channel in an RGB pixel). Typical channel operations are getting, comparing and setting the channel values. Channels have associated minimum and maximum value. GIL channels model the following concept:

    concept ChannelConcept<typename T> : EqualityComparable<T>
    {
        typename value_type      = T;        // use channel_traits<T>::value_type to access it
        where ChannelValueConcept<value_type>;
        typename reference       = T&;       // use channel_traits<T>::reference to access it
        typename pointer         = T*;       // use channel_traits<T>::pointer to access it
        typename const_reference = const T&; // use channel_traits<T>::const_reference to access it
        typename const_pointer   = const T*; // use channel_traits<T>::const_pointer to access it
        static const bool is_mutable;        // use channel_traits<T>::is_mutable to access it

        static T min_value();                // use channel_traits<T>::min_value to access it
        static T max_value();                // use channel_traits<T>::min_value to access it
    };

    concept MutableChannelConcept<ChannelConcept T> : Swappable<T>, Assignable<T> {};

    concept ChannelValueConcept<ChannelConcept T> : Regular<T> {};

GIL allows built-in integral and floating point types to be channels. Therefore the associated types and range information are defined in `channel_traits` with the following default implementation:

    template <typename T>
    struct channel_traits
    {
        typedef T         value_type;
        typedef T&        reference;
        typedef T*        pointer;
        typedef T& const  const_reference;
        typedef T* const  const_pointer;

        static value_type min_value() { return std::numeric_limits<T>::min(); }
        static value_type max_value() { return std::numeric_limits<T>::max(); }
    };

Two channel types are compatible if they have the same value type:

    concept ChannelsCompatibleConcept<ChannelConcept T1, ChannelConcept T2>
    {
        where SameType<T1::value_type, T2::value_type>;
    };

A channel may be convertible to another channel:

    template <ChannelConcept Src, ChannelValueConcept Dst>
    concept ChannelConvertibleConcept
    {
        Dst channel_convert(Src);
    };

Note that `ChannelConcept` and `MutableChannelConcept` do not require a default constructor. Channels that also support default construction (and thus are regular types) model `ChannelValueConcept`. To understand the motivation for this distinction, consider a 16-bit RGB pixel in a “565” bit pattern. Its channels correspond to bit ranges. To support such channels, we need to create a custom proxy class corresponding to a reference to a sub-byte channel. Such a proxy reference class models only `ChannelConcept`, because, similar to native C++ references, it may not have a default constructor.

Note also that algorithms may impose additional requirements on channels, such as support for arithmetic operations.

See also

- ChannelConcept<T>

- ChannelValueConcept<T>

- MutableChannelConcept<T>

- ChannelsCompatibleConcept<T1,T2>

- ChannelConvertibleConcept<SrcChannel,DstChannel>

## Models

All C++11 fundamental integer and float point types are valid channels.

The minimum and maximum values of a channel modeled by a built-in type correspond to the minimum and maximum physical range of the built-in type, as specified by its `std::numeric_limits`. Sometimes the physical range is not appropriate. GIL provides `scoped_channel_value`, a model for a channel adapter that allows for specifying a custom range. We use it to define a `[0..1]` floating point channel type as follows:

    struct float_zero { static float apply() { return 0.0f; } };
    struct float_one  { static float apply() { return 1.0f; } };
    typedef scoped_channel_value<float,float_zero,float_one> bits32f;

GIL also provides models for channels corresponding to ranges of bits:

    // Value of a channel defined over NumBits bits. Models ChannelValueConcept
    template <int NumBits> class packed_channel_value;

    // Reference to a channel defined over NumBits bits. Models ChannelConcept
    template <int FirstBit,
            int NumBits,       // Defines the sequence of bits in the data value that contain the channel
            bool Mutable>      // true if the reference is mutable
    class packed_channel_reference;

    // Reference to a channel defined over NumBits bits. Its FirstBit is a run-time parameter. Models ChannelConcept
    template <int NumBits,       // Defines the sequence of bits in the data value that contain the channel
            bool Mutable>      // true if the reference is mutable
    class packed_dynamic_channel_reference;

Note that there are two models of a reference proxy which differ based on whether the offset of the channel range is specified as a template or a run-time parameter. The first model is faster and more compact while the second model is more flexible. For example, the second model allows us to construct an iterator over bit range channels.

## Algorithms

Here is how to construct the three channels of a 16-bit “565” pixel and set them to their maximum value:

    using channel16_0_5_reference_t  = packed_channel_reference<0, 5, true>;
    using channel16_5_6_reference_t  = packed_channel_reference<5, 6, true>;
    using channel16_11_5_reference_t = packed_channel_reference<11, 5, true>;

    std::uint16_t data=0;
    channel16_0_5_reference_t  channel1(&data);
    channel16_5_6_reference_t  channel2(&data);
    channel16_11_5_reference_t channel3(&data);

    channel1 = channel_traits<channel16_0_5_reference_t>::max_value();
    channel2 = channel_traits<channel16_5_6_reference_t>::max_value();
    channel3 = channel_traits<channel16_11_5_reference_t>::max_value();
    assert(data == 65535);

Assignment, equality comparison and copy construction are defined only between compatible channels:

    packed_channel_value<5> channel_6bit = channel1;
    channel_6bit = channel3;

    // compile error: Assignment between incompatible channels
    //channel_6bit = channel2;

All channel models provided by GIL are pairwise convertible:

    channel1 = channel_traits<channel16_0_5_reference_t>::max_value();
    assert(channel1 == 31);

    bits16 chan16 = channel_convert<bits16>(channel1);
    assert(chan16 == 65535);

Channel conversion is a lossy operation. GIL’s channel conversion is a linear transformation between the ranges of the source and destination channel. It maps precisely the minimum to the minimum and the maximum to the maximum. (For example, to convert from uint8_t to uint16_t GIL does not do a bit shift because it will not properly match the maximum values. Instead GIL multiplies the source by 257).

All channel models that GIL provides are convertible from/to an integral or floating point type. Thus they support arithmetic operations. Here are the channel-level algorithms that GIL provides:

    // Converts a source channel value into a destination channel.
    // Linearly maps the value of the source into the range of the destination.
    template <typename DstChannel, typename SrcChannel>
    typename channel_traits<DstChannel>::value_type channel_convert(SrcChannel src);

    // returns max_value - x + min_value
    template <typename Channel>
    typename channel_traits<Channel>::value_type channel_invert(Channel x);

    // returns a * b / max_value
    template <typename Channel>
    typename channel_traits<Channel>::value_type channel_multiply(Channel a, Channel b);