IM_READ

im_read - read pixels from a KUIM image file

Synopsis

void im_read(Image, PixType, Data)
   IM_TYPE *Image;
   int PixType;
   char *Data;

Description

The im_read routine reads pixel data from an open KUIM image into a pixel buffer of the desired data type. The desired data type is specified by the PixType argument. If this type is different from the pixel type on disk, the data will be converted as it is read. The pixel buffer Data is assumed to have been previously allocated using one of the im_alloc routines (or equivalent malloc calls). No range of image dimensions need be specified, the whole image is read at once. The parameters to this routine are:

Image - This is a pointer to a IM_TYPE data structure which was previously initialized using im_open.

PixType - This is a value which specifies the type of pixel data stored in the image. Valid values for this field are: BYTE, SHORT, INT, FLOAT, DOUBLE, COMPLEX, COLOR, PSEUDO (all defined in IM.h).

Data - This is the address of the pixel buffer which is to hold the image being read. It is assumed that this space has been allocated using one of the im_alloc routines. For multidimensional images, take care to pass the address of the first pixel to the routine and NOT simply the address of the 2D or 3D access array (see example below).

Examples

To read a 1D SHORT image from file "test1.IM" use: 

   IM_TYPE *Image1;
   SHORT_TYPE *Data1;
   int PixType, Xdim,Ydim,Zdim, DimCnt;
   Image1 = im_open("test1.IM", &PixType, &Xdim, &Ydim, &Zdim, &DimCnt);
   Data1 = (SHORT_TYPE **)im_alloc1D(Image1, SHORT);
   im_read(Image1, SHORT, Data1);

To read a 2D FLOAT image from file "test2.IM" use: 

   IM_TYPE *Image2;
   FLOAT_TYPE **Data2;
   int PixType, Xdim,Ydim,Zdim, DimCnt;
   Image2 = im_open("test2.IM", &PixType, &Xdim, &Ydim, &Zdim, &DimCnt);
   Data2 = (FLOAT_TYPE **)im_alloc2D(Image2, FLOAT);
   im_read(Image2, FLOAT, &(Data2[0][0]));

Files

Source is in $KUIM/src/libIM

See Also

im_create, im_open, im_read, im_write, im_get_title, im_put_title, im_get_cmap, im_put_cmap, im_alloc1D, im_alloc2D, im_alloc3D, im_free1D, im_free2D, im_free3D.

Author

John M. Gauch
Electrical Engineering and Computer Science
University of Kansas

Diagnostics

When this routine succeeds, the Data buffer is updated. Upon occurrence of any error condition, a message is printed and the program exits.

Bugs

At present, an image can only be read once after it has been opened. To re-read an image, you must re-open the file. This is an artifact of the fact that im_read does not seek to the start of the pixels.