Tutorial

IM - An Imaging Tool

Image Representation Guide

Raw Data Buffer

To create a raw image buffer you can simply use the utility function:

int width, height, color_mode, data_type;
int size = imImageDataSize(width, height, color_mode, data_type);
void* buffer = malloc(size);

So if the data type is IM_FLOAT, we could write:

float* idata = (float*)buffer;

Then to locate the pixel at line y, column x, component d simply write:

float value;
if (is_packed) 
value = idata[y*width*depth + x*depth + d]
else
value = idata[d*width*height + y*width + x]

But notice that this code will return values at different pixel locations for top down and bottom up orientations.

To use the imImage structure you must include the <im_image.h> header.

To create an imImage structure you can do it in several ways:

int width, height, color_space, data_type, palette_count;
long *palette;
void* buffer

imImage* image;

image = imImageCreate(width, height, color_space, data_type) 
image = imImageInit(width, height, color_space, data_type, buffer, palette, palette_count) 
image = imImageDuplicate(image) 
image = imImageClone(image) 

The imImageInit function allow you to initialize an imImage structure with an user allocated buffer. This is very useful if you use your own image structure and wants to temporally use the image processing functions of the library.

To destroy the imImage structure simply call imImageDestroy(image). If you do "data[0] = NULL" before calling the destroy function then the raw data buffer will not be destroyed.

The imImage data buffer is allocated like the raw data buffer.

The separated color components are arranged one after another, but we access the data through an array of pointers each one starting at the beginning of each color component. So image->data[0] contains a pointer to all the data, and image->data[1] is a short cut to the second component and so on. With this you can use image->data[0] as a starting point for all the data, or use it as the first component.

count = width*height;
unsigned char* idata = (unsigned char*)image->data[0];
for (int i = 0; i < count; i++)
{
  idata[i] = 255;
}

or

for (int d = 0; d < image->depth; d++)
{
  unsigned char* idata = (unsigned char*)image->data[d];

  for (int y = 0; y < height; y++)
  {
    for (int x = 0; x < width; x++)
    {
      int offset = y * width + x; 

      idata[offset] = 255;
    }
  }
}

The imImage structure contains all the image information obtained from a file, because it also has support for alpha, attributes and the palette. The palette can be used for IM_MAP images and for pseudo color of IM_GRAY images.

An important subset of images is what we call a Bitmap image. It is an image that can be directly used into the graphics display. For Bitmap images the color space must be IM_RGB, IM_MAP, IM_GRAY or IM_BINARY, and the data type must be IM_BYTE.

The conversion between image data types, color spaces and the conversion to bitmap are defined only for the imImage structure.