Re: [boost] Review of Generic Image Library (GIL) begins today, Oct5, 2006

From: Joel de Guzman (joel_at_[hidden])
Date: 2006-10-18 09:46:49

Hi Here's my GIL review:

> Please always explicitly state in your review, whether you think the
> library should be accepted into Boost.

I vote to accept GIL into boost.

As part of my review, I wrote an AGG (http://www.antigrain.com/)
renderer using GIL. You can get the code here:

     http://spirit.sourceforge.net/dl_more/gil/gil.zip

You will need the latest AGG library (v2.4). For the test, I opted not
to use any library other than AGG, GIL and of course Boost. The test
writes a PPM file which can be read by most image utilities. IrfanView
(http://www.irfanview.com/) is a popular and free image software.

I added a pre-compiled app for Windows users in the package. It's
interesting to note that the entire thing (app) is just 60K. This
includes the entire vertex source for the image hard-coded. This
reflects the modularity of GIL and AGG and the resulting code is
very tight. Both GIL and AGG are highly modular, generic libraries.
You pay only for features that you do not need. Here's the output
of the test:

     http://spirit.sourceforge.net/dl_more/gil/lion.png

gil_renderer.hpp is an AGG renderer for GIL views and images. AGG
has a flexible pipeline architecture:

         Vertex Source
               |
  Coordinate conversion pipeline
               |
       Scanline Rasterizer
               |
           Renderers
               |
        Rendering Buffer
               |
         Screen output

By plugging into the renderer layer, I am able to make AGG work
with the full suite of GIL views and images, including those
that AGG does not support directly such as planar images, CMYK,
LAB color-spaces etc.

By replacing the Renderers and Rendering Buffer, AGG can be greatly
simplified. And, as a result, make it even more flexible. GIL
provides more functionality at that level. AGGs real forte is in
the upper half of the library whle GIL's focus is in the lower
half.

The gil_renderer class I provided is bare bones. To take full
advantage of AGG (and GIL), a lot more functions need to be written.
For the purpose of the review, I also hard-coded the blending of
anti-aliased scan lines to RGB. It's certainly possible to make
it fully generic for all color spaces as discussed in the GIL
tutorial.

>  - What is your evaluation of the design?

A+. I like libraries that are tight and highly focused. GIL is
one of those. I see that a lot of effort has been invested on
design.

There's one issue that was discussed: that of pixel accessors.
It was argued that VIGRA's data accessors provide more flexibility
than GIL's use of plain iterators and iterator adapters. There may
be some truth in that. This is very similar to the Cursor/Property
Map Abstraction that Dave Abrahams and Dietmar Kühl advocate.
(http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1873.html).
I invite the GIL authors to investigate this angle. Yet, I see no
reason to reject GIL for their design choice whichever way they
choose. It's their call. I recall facing the same choice before
with Fusion. I chose the plain iterator approach. Yet, Dave did
not reject the library when Fusion was finally reviewed.

I'd like to see Fusion integration with GIL. I suggested, off-list,
that GIL color-spaces can and should be Fusion sequences. In
particular, they can be thought of as fusion associative
sequences (http://tinyurl.com/ymhl9q). With fusion integration, GIL
does not have to reinvent algorithms for heterogeneous types such
as GIL's pixel algorithms (e.g. for_each_channel, generate_channels
and tranform_channels). Surely, this is not enough, and Fusion
has a lot more (http://tinyurl.com/ym6n75).

A use case that I presented is a more intuitive gradient_on_luminance
algorithm, which applies the halfdiff_cast_channel function only
on channels that affect luminance. For HSV, it can selectively work
on only V, in HSL, L, in YUV, Y, in RGB, CMYK, all channels.

Pixels are n-tuples. GIL pixel algorithms work on these tuples. It
seems a lot like a work better suited for the Fusion library.
Consider this snippet:

     fusion::transform(
         fusion::filter<has_luminance<mpl::_1> >(a)
       , fusion::filter<has_luminance<mpl::_1> >(b)
       , halfdiff_cast_channel<C>());

which reads: apply halfdiff_cast_channel only on channels
that has luminance information; ignoring hue information. The end
result is still color with graduated brightness/luminance. Hence,
the result over RGB and HSL will be similar, for example.

Also, operations on fusion sequences (Again, I think color spaces
should be fully conforming fusion sequences) is darned fast. It
does the same compile time recursion you mentioned in GIL docs,
albeit more extensively and more generically (i.e. not just on
pixels but on all hetero-sequences in general). It will be fast
because no conversion ever takes place (not even a copy).

>  - What is your evaluation of the implementation?

B+. I thought I'd give some negative marks here because I was not
able to see any regression tests, but Lubomir quickly pointed out
that there are some in the ASL repository. Indeed there are tests.
However, I give this a B+ because the tests are not extensive and
do not cover a lot. I see only 6 tests. A lot more work should
be invested in this area. I also notice that GIL does not follow
Boost conventions. I expected something like this directory structure:

      + boost
          + gil
      + libs
          + gil
              + test
              + doc
              + example

I expect the authors to follow this convention if/when GIL is
accepted.

>  - What is your evaluation of the documentation?

B-. I enjoyed the tutorial and the Design guide a lot. The Breeze
presentation is a first in boost. It is entertaining and insightful.
Like other people, I too noticed some rough edges and inconsistencies.
For example, the author at the start of the presentation says "if
you don't know about STL iterators, think of them like pointers".
(or something to that effect). Then later, he shows of some MPL
and Lambda snippets without hesitation. I think the author is not
consistent with the way he thinks of his target audience. Is this
for newbies with no knowledge of STL iterators or for advanced
folks with MPL/Lambda background? Make up your mind. Be consistent.
In any case, a brief bakgrounder into MPL and Lambda would be in order.

The doxygen documentation, I have to be blunt, was not useful to me
at all. I ended up reading header files which were more informative.
Let's take an example:

     http://opensource.adobe.com/gil/html/group___channel.html

IMO, this page is totally useless. Example:

Detailed Description:

     Channel and channel operations.

C'mon, you can do better than that! Your docs do not do justice to your
otherwise elegant design! I'd say rework the docs from scratch with
more care and attention and love :)

>  - What is your evaluation of the potential usefulness of the library?

Oh man, do I have to answer this? :-)

>  - Did you try to use the library? With what compiler? Did you have
> any problems?

Yes, I invested a full weekend learning about the library. Well,
actually I had to learn 2 libraries (AGG and GIL). I am not
an expert with AGG at all. I was just a mere lurker in the AGG
mailing list until the past weekend.

>  - How much effort did you put into your evaluation? A glance? A quick
> reading? In-depth study?

In depth. I studied the code in full. Read the docs cover top cover.
Wrote an adaptor from AGG to GIL. I invested the entire weekend on
this.

>  - Are you knowledgeable about the problem domain?

I can't say I am an expert on this domain. I did have my share of
blitting and stuff, though, especially in the early years. I've
written at least 2 GUI frameworks from scratch. The first one was
pre Windows. I was inspired by GUIs and wrote one for DOS machines.
I did the blitters and the graphics engine in assembly and pascal.
One of the apps was a paint program where we designed our UI graphics.
The second was a refinement of the first, this time in C++, inspired
by fresco, minus the fat :). Then, I also did lots of low-level
graphics stuff because the graphics library we had, at the time,
was very poor: Mac's QuickDraw. Also, I wanted to do cross-platform
and the PC's GDI was also very poor.

Regards,
-- 
Joel de Guzman
http://www.boost-consulting.com
http://spirit.sf.net