digikam/digikam/libs/dimg

---------------------------------------------------------------------------
WHAT'S DIMG FRAMEWORK ?


Original post from Renchi Raju on digiKam mailing list :

[Digikam-devel] Imaging Library
Renchi Raju renchi at pooh.tam.uiuc.edu 
Sun Jun 19 23:15:20 CEST 2005 

as you all know, we have been using imlib2 library for the 0.7 series. we 
have had a fairly large number of bugreports because of imlib2 (not 
imlib2's fault, but because of tdelibs's handling of ltdl). In addition, 
some imlib2 bugreports I reported to upstream have gone unfixed for long 
time now.

Also, we need to think about 16bit imaging support. this won't come from 
imlib2 and neither from qt. with qt4 there was hope of 16bit image 
support, but trolltech has made it clear that imaging apps forms only 0.1% 
of their customer base and they are not interested in providing custom 
support for them. so the only solution  I see (without depending on 
imagemagick) is to roll our own library.

i have been working on a imaging library for digikam, its called DImg. 
it doesn't aim to be a complete imaging library; it uses QImage for 
rendering and for loading files which are not supported natively by it. 
some of the working/planned features:

* Native Image Loaders, for some imageformats which are of interest to 
us: JPEG (complete), TIFF (a rudimentary one currently), PNG (planned), PPM 
(planned). for the rest qt's qimage is used.

* Metadata preservation: when a file is loaded, its metadata like XMP, 
IPTC, EXIF, JFIF are read and held in memory. now when you save back the 
file to the original file or to a different file, the metadata is 
automatically written (How, we have been handling it currently with 
imlib2 is on saving a file: we save the file to a temporary file, reread 
the exif info from the original file and then write to a second temporary 
file.)

* Explicitly Shared Container format (see qt docs): this is necessary for 
performance reasons.

* 8bit and 16bit support: if the file format is 16 bit, it will load up 
the image in 16bit format (currently only 16bit tiff support) and all 
operations are done in 16 bit format, except when the rendering to screen 
is done, when its converted on the fly to a temporary 8bit image and then 
rendered.

* Basic image manipulation: rotate, flip, color modifications, crop, 
scale (this has been ported from Imlib2 - originally ported by Mosfet, I 
added 16 bit scaling support and support for scaling of only a section of 
the image)

* Rendering to Pixmap: using QImage/QPixmap. (see above for rendering of 
16bit images).

* Pixel format: the pixel format is different from QImage/Imlib2 pixel 
format. In QImage/Imlib2 the pixel data is stored as unsigned ints and to 
access the individual colors you need to use bit-shifting to ensure 
endian correctness. in DImg, the pixel data is stored as unsigned char. 
the color layout is B,G,R,A (blue, green, red, alpha)

for 8bit images: you can access individual color components like this:

uchar* pixels = image.bits();
for (int i=0; i<image.width()*image.height(); i++)
{
   pixel[0] // blue
   pixel[1] // green
   pixel[2] // red
   pixel[3] // alpha

   pixel += 4; // go to next pixel
}

and for 16bit images:

ushort* pixels = (ushort*)image.bits();
for (int i=0; i<image.width()*image.height(); i++)
{
   pixel[0] // blue
   pixel[1] // green
   pixel[2] // red
   pixel[3] // alpha

   pixel += 4; // go to next pixel
}

the above is true for both big and little endian platforms. What this also 
means is that the pixel format is different from that of QImage for big 
endian machines. Functions are provided if you want to get a copy of the 
DImg as a QImage.