Tutorial

Guide

Getting Started

It is important to understand that IM is based in 4 concepts: Image Representation, Image Storage, Image Processing and Image Capture. The following picture illustrates the relation between theses concepts.

IM does not have support for Image Visualization, because we think this is a task for a graphics library like OpenGL, Windows GDI or CD.

Image Representation describes the image model and its details. Which color systems are going to be used, which data types, how the data is organized in memory, and how other image characteristics are accessed.

Image Storage describers the file format model and how images are obtained or saved. Image Capture describes the access to a capture device and obtaining an image from it. Image Processing describes the image processing operations.

There are infinite ways to implement these concepts. There is no common definition in the literature, but there is a standard called Programmer's Imaging Kernel System (PIKS) published at the ISO/IEC 12087. PIKS is a very complete and also complex standard, very hard to implement. There are only a few implementations available, and the one that I know is commercial software, Pixel Soft of William Pratt http://www.pixelsoft.com/, also author of several books on the subject.

But we want something easier to implement and understand. The free available libraries that we found where sometimes close to what we want, sometimes very far. So we developed our own.

The documentation is divided into two major parts: Guide and Reference.

The Guide is where you are going to find the explanation about the concepts and decisions made during the library design. It is the best place to understand how things works.

The Reference contains pure essential information for function and structure usage. But there is no information on how to put the functions to work together. It is generated automatically from the source code using Doxygen, this means also that the include files (*.h) are very well commented.

You should read at least the Guide / Basics section. There are all the important concepts developed and used in the library, as many samples on how to combine the available functions to obtain the desired results.

Building Applications

Inside you code you should at least include the <im.h> file and link with the "im.a/im.lib" file. This includes all the Image Representation functions and all the Image Storage functions (with the exception of the external SDK formats: AVI, JP2 and WMV).

For imImage structure you should include the <im_image.h> file. There are several other utilities that needs different header files, check the Reference documentation.

For the Image Capture you should include the <im_capture.h> file and link with the "im_capture.lib" file. The same for Image Processing, <im_process.h> file and "im_process.a/im_process.lib" file.

Each external format or processing usually needs a <im_xx.h> file and a "im_xx.a/im_xx.lib" file.

The WMV format is available only for the Visual C++ compiler, you will also need the file "wmvcore.lib". But when using the DLL you may try to generate an import library for other compilers. To compile the format source code you will need the Windows Media Format SDK.

The AVI format is available for gcc 3 and Mingw 3, but to link your application you will need the files "libvfw_ms32.a and libvfw_avi32.a".

To link with the capture library in Windows using Visual C you will need the file "strmiids.lib". To compile the capture source code you will need the Direct X 9 SDK. To link it using Dev-C++ or Mingw 3 you will need the "im_capture.dll".

Even if your applicattion is only in C, you must link with a C++ capable linker. Using Tecmake set "LINKER := g++" in your "config.mak" when compiling with gcc (UNIX and Windows).

Building the Library

The easiest way to build the library is to install the Tecmake tool into your system. It is easy and helps a lot. The Tecmake configuration files (*.mak) available at the "src" folder are very easy to understand also. But we also provide a makefile for Linux systems and a Visual Studio workspace with the respective projects.

Tecmake is a command line multi compiler build tool available at http://www.tecgraf.puc-rio.br/tecmake. Tecmake is used by all the Tecgraf libraries and many applications.

About File Formats

TIFF is still the most complete format available. It could be better if Adobe releases the revision 7, but it is on stand by. TIFF supports all the IM image representation concepts. In fact we were partially inspired by the TIFF specification. My suggestion is whenever possible use TIFF.

But TIFF may not be the ideal format for many situations. The W3C standards include only JPEG, GIF and PNG for Web browsers. JPEG forces the image to be RGB or Gray with a lossy compressed. GIF forces the image to be MAP with LZW compression. PNG forces the image to be RGB, MAP, Gray or Binary, with Deflate compression. So these characteristics are necessary to force small values for faster downloads.

JPEG is to be used for photographic content, PNG should be used for the remaining cases, but GIF is still the best to do simple animated images.

Except for some specific cases where a format is needed for compatibility, the other formats are less important. TGA, PCX, RAS, SGI and BMP have almost the same utility.

JP2 must be used for JPEG-2000 compression, would be nice if a new TIFF specification includes this standard.

Since PNM has a textual header it is very simple to teach for students so they can actually "see" the header. It is also a format easy to share images, but it does not do much more than that.

The TIFF and the GIF format also have support for multiple images. This does not necessarily defines an animation, pyramid nor a volume, but some times they are used in these ways.

GIF became very popular to build animations for the Web, and since the LZW patent expired Unisys realized that charging the usage isn't going to work and so they did not renew it. LZW is fully supported at IM.

IM also supports video formats like AVI and WMV as external libraries. In these cases the frames are also loaded as a sequence of individual images. Sound is not supported.

TIFF, JPEG and PNG have an extensive list of attributes, most of them are listed in the documentation, but some custom attributes may come up when reading an image from file.

CD Compatibility

IM version 2 was designed to perfectly work with the CD - Canvas Draw toolkit. Version 3 has many more options and only for a subset of the images called Bitmaps can be used with the CD functions. Theses images have data type IM_BYTE, and color mode IM_RGB, IM_GRAY, IM_MAP or IM_BINARY. They can not have the flags IM_TOPDOWN and IM_PACKED. But it can have the flag IM_ALPHA for IM_RGB images.

You can convert an image to a bitmap version of it using the function imConvertToBitmap, see Reference / Image Representation / Conversion.

Function cdGetImageRGB captures an image from the active canvas. Functions cdPutImageRGB and cdPutImageMap place an RGB image or an indexed image, respectively, on the active canvas. These functions allow reducing or increasing the image when placing it on the canvas.

For applications in systems with only 256 colors available, we recommend the use of function cdPalette before drawing the image, to improve its quality.

When using the imImage structure the macro cdPutBitmap can be used. It is defined as:

#define cdPutBitmap(_image, _x, _y, _w, _h, _xmin, _xmax, _ymin, _ymax) \
{                                                                       \
  if (_image->color_space == IM_RGB)                                    \
    cdPutImageRectRGB(_image->width, _image->height,                    \
                      (unsigned char*)_image->data[0],                  \
                      (unsigned char*)_image->data[1],                  \
                      (unsigned char*)_image->data[2],                  \
                      _x, _y, _w, _h, _xmin, _xmax, _ymin, _ymax);      \
  else                                                                  \
    cdPutImageRectMap(_image->width, _image->height,                    \
                      (unsigned char*)_image->data[0], _image->palette, \
                      _x, _y, _w, _h, _xmin, _xmax, _ymin, _ymax);      \
}

CD Library is the Tecgraf 2D graphics library available at http://www.tecgraf.puc-rio.br/cd.

OpenGL Compatibility

The function glDrawPixels accepts several data types and color modes. Here are the format and type mapping for OpenGL usage:

           IM             <->  OpenGL

        color_mode             format
IM_RGB|IM_ALPHA|IM_PACKED  = GL_RGBA               
IM_RGB|IM_PACKED           = GL_RGB
IM_GRAY                    = GL_LUMINANCE
IM_GRAY|IM_ALPHA|IM_PACKED = GL_LUMINANCE_ALPHA

        data_type              type
IM_BYTE                    = GL_UNSIGNED_BYTE
IM_BINARY                  = GL_BITMAP
IM_USHORT                  = GL_UNSIGNED_SHORT
IM_INT                     = GL_INT
IM_FLOAT                   = GL_FLOAT

There is no mapping for non IM_PACKED images so if you use unpacked planes (ex: you use the imImage structure) then you have to convert one data into another, the function imConvertPacking does this, so you just have to keep an extra buffer for the display image and call this function only when your original image has changed. See Reference / Image Representation / Conversion. For example:

imConvertPacking(image->data[0], gl_data, image->width, image->height, image->depth, image->data_type, 0);
glPixelStorei(GL_UNPACK_ALIGNMENT, 1); /* data alignment must be 1 */
glDrawPixels(image->width, image->height, GL_RGB, GL_UNSIGNED_BYTE, gl_data);

When loading color image data you can use the function imConvertMapToRGBPacked to convert in-place IM_MAP image data into IM_RGB after loading it from file. For example:

if (imColorSpace(color_mode) == IM_MAP)
{
  long palette[256];
  int palette_count;
  imFileGetPalette(ifile, palette, &palette_count);
  imConvertMapToRGBPacked(gl_data, width*height, depth, palette, palette_count);
}

IM 2.x Compatibility

In version 3.0 the library was completely rewritten. And we changed the main API to allow more powerful features. But the old API is still available for backward compatibility. Version 3 is also binary compatible with version 2.

The only change that must be updated in old applications if they where recompiled is some error code definitions. If you use them in a case there will cause a compiler error because IM_ERR_READ and IM_ERR_WRITE are now defined as IM_ERR_ACCESS both.

Migrating OLD Code

The old API is very inefficient because the file is opened and close three times, for: imFileInfo, imImageInfo and imLoadRGB/imLoadMap. There is no room for attributes, so we use the callbacks. And we can not load sequences of images. For these reasons we change the API.

If you would like to migrate your code using the old API the most important thing to change is the memory allocation. For RGB images instead of allocating 3 separate pointers you should allocate only one pointer with room for all three planes. If you still want to keep the three pointers, just do green = red + width*height and blue = red + 2*width*height.

Also you should change your callbacks usage for attributes access using imFileGetAttribute and imFileSetAttribute. IM_RESOLUTION_CB is replaced by the attributes "XResolution", "YResolution", "ResolutionUnit". IM_GIF_TRANSPARENT_COLOR_CB is replaced by "TransparencyIndex" and IM_TIF_IMAGE_DESCRIPTION_CB by "Description".

Except IM_COUNTER_CB that is not an attribute, still works with a callback, but now we implement a counter system for all the library including loading, saving and processing. The user just use the imCounterSetCallback (like before) to register it counter callback, now there are a few more parameters and a user data pointer. See Reference / Utilities / Counter.

The function calls to imImageInfo and imLoadRGB/imLoadMap will be replaced by a sequence of function calls to imFileOpen/imFileNew,  imFileReadImageInfo/imFileWriteImageInfo, imFileReadImageData/imFileWriteImageData and imFileClose. See Reference / Image Storage.