Re: [boost] Review of Generic Image Library (GIL)

From: rasmus ekman (m11048_at_[hidden])
Date: 2006-10-14 00:58:07

Lubomir Bourdev wrote:

>>-----Original Message-----
>>From:  rasmus ekman
>>
>>I vote that GIL is rejected this time.
>>
>>This is not because I doubt the usefulness or quality of 
>>implementation, more due to the fact that there is at least 
>>one other generic library (Vigra), which covers much of the 
>>same field, that has been around longer, and supplies many 
>>more algorithms.
> 
> First of all, as far as we know we don't have a formal proposal from
> Vigra on the table, so we feel it is unfair to reject for this reason.

As I said later on, my review is less based on detailed experience
with all the libraries I mention, and more on an end-user perspective.
As end user I unashamedly ask, "what can this library do for me"
and: "is there anything better around?"
I want to rewrite a middlesized graphics app, and the libraries used
have major impact. Today I would choose some other library than GIL,
and wish that it was submitted to Boost so the authors would fix up
the interfaces (and docs).

I did not hold back since it seems from here that you (the authors of GIL)
have very robust skills and can trust your own judgment also in the face of
somewhat whiny criticism.
I absolutely do not intend to seem dismissive, more posing challenges
I'm near-certain that you (and GIL) can meet.

The worries I try to express are:
(1) Will the design work out in the long run? - GIL is not proven yet.
(2) Where is GIL going? - If it is accepted, this gives more or less
blank cheque to make additions - or not.
Until we see the additions made, there's no knowing if they will work out,
and how rich the library will end up being.

So, is GIL finished now? Are there only a few technotes to add?
And if not, was the submission premature?

Note: The last is a trick question. You can also use the review to get
input on the library, make the changes you can, and resubmit quite soon.
I believe this is a valid and accepted way of using the review process.
Other boosters can tell if I got that wrong.

> [snip] Will the current job
> candidate be interested in interviewing for your job again once
> rejected? Often not.

No, and it's maybe a problem. Boost reviews seem to have burned several people,
leaving them feeling unfairly treated. This is not (just) recent, I've noted
it in some cases over the last 5 years. There are boosters better placed
to tell you whether there might be problems with the review process
- or with the pre-review process.

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

>> [snip]  GIL lacks support for signal processing.
> 
> FYI, we do have image processing algorithms in our GIL numeric extension. 
>  [snip]
> It is not currently part of the review, but if GIL makes it into boost
> one day we may have a follow-up proposal. Why not submit together? Aside
> from the fact that the numeric extension is far from being comprehensive
> and well optimized, we want to see GIL used extensively and make sure
> the fundamentals are absolutely solid 

Exactly. Can I say it now? Me too!

> before making heavy-duty
> algorithms, because it is much harder to change your foundations after
> you have built the house

>>So a merge with or reimplementation of Vigra/AGG 
>>functionality seems in order.
> 
> Merging between GIL/Vigra or especially GIL/AGG would be interesting.
> But how is your rejection helping here? If anything, it makes this
> possibility less likely.

I hope I have covered this above: Review rejection is often not final.
The embrace is often just two steps behind it, if most worries are addressed.
- sometimes just if motivation is provided: You are after all the domain experts.

>>Oh, I saw just now that some more algorithms were posted recently.
>>Good, but late. Were they included in the review submission?
>>Or more like proof of concept sketches?
> 
> Why is it late? The review period is not over.
> And I am not sure which algorithms you are referring to. The numeric
> extension is not part of the submission for the above-listed reasons,
> and it was posted before the review began.

 From the download page:
"It is in a very early stage of development; it is not documented and has not
been optimized for performance."

I'm sure you're partly just being modest here, but I didn't consider
downloading it when the review was first announced, then didn't look back
until yesterday.

>>Concept docs looks as if copied verbatim from header files, 
>>though now I know it isn't so. They look cluttered.
>>Documentation is often scanty, or inane repetition of 
>>class/concept names.
>>Perhaps the authors trust that naming is so good that code 
>>will be self-explaining.
> 
> 
> Not at all.

Oh, but it almost is! Problem is that the generated docs are less
clear than reading the header files. This speaks well for your headers,
less so for the docs.

Btw, I think I've seen comments on this list to the effect that generated
(eg Doxygen) documentation is not good enough for Boost libraries;
good documentation must be designed in itself.

> In addition to the design guide and tutorial, we have
> Doxygen documentation for every public interface and lots of private
> ones. Which part of the code you feel is not well documented?

The ones where the comment just repeats the class or concept name.
Eg, the full documentation for MutablePixelIteratorAdaptorConcept
reads: "Pixel iterator adaptor that is mutable."
Actually I'm suggesting they be removed to save us from skimming repetitions.

At the top levels of models and concepts there is hardly any documentation.
It might be forgiven that Point, Pixel and Color have brief oneliners,
but see Channel: "Concept for channel and mutable channel."
Most users getting this far will know what it is, but having the word "color"
somewhere on the page would not be affrontery would it?
Even if we know what the "usual" meaning is, the syntax supported in this
library could be outlined. Interaction with other concepts might be mentioned,
there and then.

Two or three levels down in the doc tree occasional substantial information appears.
This is the reverse from what I expect. Bottom-up design should not result
in bottom-up documentation.

And the oneliners are offputting. After clicking ten links and finding
one or two pages with more info than the link text, I had to decide
whether to click *all* links, or give up. I went for the header files.
This is a friendly turn mind you, I think many potential end users wouldn't.

>>Links in the tutorial point to places that don't help 
>>understanding at all, whereas the places where something 
>>substantial is said are buried 2-4 links away from the TOC of 
>>reference docs.
>>(Eg class image_view. I posted about this a while ago.)
> 
> 
> Rasmus - these links are automatically generated by Doxygen, which might
> explain why some of them may not feel logically placed. We could look
> into suppressing some of these links that don't make sense. Thanks for
> the suggestion.

Of course - just put a % sign before a name to suppress the link.
But I'm not asking for suppresion here, I'm asking for more links,
to places of interest in the context.

Oh, did I forget to say thanks? Dash, where are my manners... Sorry.
Thanks for GIL and for putting it through the Boost review!

Regards,

        rasmus