The IL allows you to access, manipulate, store, and display images. You can perform a series of operations on one or more images by creating a chain of operators and passing the image or images down this chain. An operator is a class derived from ilOpImg (the base class for all IL operators) that applies its image processing algorithm to an image. The image output from each operator becomes the input to the next operator in the chain.

An element in a chain of operators can be:

The result of a chain of operations is either a display of the processed image or a file on disk containing the processed image. Figure 2-2 illustrates this concept by showing a generalized image processing chain whose elements are raw and processed images.

Figure 2-2. An IL Chain

The ilLink class implements the chaining model by defining the mechanism for linking the image objects together. This model defines the concept of parent (input) and child (output) images.

The ilLink class also provides functions that allow you to manipulate image attributes by providing functions that keep track of whether an attribute is allowed to change or has been altered. For more information about chaining operators, see “The IL Execution Model”.

The ilImage class is the root for the majority of the IL's image class hierarchy. It provides the IL's abstract concept of what images are and how they are manipulated. The IL defines an image as a four-dimensional array of pixels, x, y, z, and c. An image has certain attributes, such as the size (in pixels) of the image, the data type of the pixel elements (for example, float or int), and the color model that should be used to interpret the data (for example, RGB or CMYK).

The ilImage class provides two main categories of functions to support this abstraction of an image:

All classes that derive from ilImage (see Figure 2-1) inherit these general capabilities for querying and setting attributes and accessing data. Thus, the IL allows you to manipulate all images in the same way, regardless of the actual source or destination of the data. The same mechanism is used for data that is associated with any type of image, for example:

Classes derived from ilImage implement their own versions of the data access functions as necessary to add specificity. For example, ilMemCacheImg defines versions of the data access functions that read data from or write data to a partial copy of the image buffered in main memory. Similarly, ilTIFFImg adds capabilities specifically for reading and writing TIFF file headers and data. The ilSharpenImg class incorporates a sharpening algorithm into its access functions.

As you read the following sections, you will note that many of the functions described return a value of data type ilStatus. This enumerated type, which is defined in the header file il/ilError.h, contains the error codes used by the IL to indicate that an unexpected result occurred. If no unexpected result occurred, an image's status is ilOKAY. The error codes and their meanings are listed in “Error Codes”.

At any point, you can query an ilImage about its current status by using getStatus(), a function defined in ilLink that takes no arguments and returns a value of type ilStatus. You can also set an image's status to ilOKAY by using clearStatus() (a function defined in and inherited from ilLink).

One key attribute of an image's its size, which is determined initially when an image is created. In Example 1-1 in Chapter 1, “Writing an ImageVision Library Program,” the size of the image data is determined when the ilFileImgOpen() function is called. An image's size can be described with an iflSize data structure, which consists of four integers that correspond to the image's size in the x, y, and z dimensions and the number of data channels, c, per pixel.

The x and y dimensions specify the width and height of the image as measured in pixels. The z dimension, or “depth,” may refer to the number of xy planes of image data. The xy planes are usually related in some way; for example, they might be a time-series of a single animation scene or a set of CAT scan images. (CAT stands for computerized axial tomography, a medical imaging technique used to create three-dimensional images.) Different image representations require different numbers of data channels to describe each pixel of data. An RGB (red, green, blue) image, for example, requires three channels, one for each of the three colors.

The ilImage class defines functions for retrieving the entire iflSize structure for an image at once and functions for returning each of the elements separately:

ilImage myImg;
iflSize imgSize;
int imgXSize, imgYSize, imgZSize, imgChans;
myImg.getSize(imgSize);
imgXSize = myImg.getXsize();
imgYSize = myImg.getYsize();
imgZSize = myImg.getZsize();
imgChans = myImg.getCsize();

You can change an image's size by applying an image operator that affects its size or by setting its size explicitly (if you are allowed to set it). For example, in most cases, the ilRotZoomImg operator produces a processed image with a size that differs from that of the original image, as shown in Figure 2-3:

Figure 2-3. Sizes of Original and Processed Images

You can set an image's size explicitly by using setSize(), which takes a reference to the desired iflSize structure as an argument. A separate function, setCsize(), allows you to restrict the number of channels associated with an image.

An image's pixel components must all be of the same data type. The IL defines an enumerated set of data types (iflDataType) and a function, getDataType(), to return the data type of an image's pixels:

iflDataType imgType;
imgType = myImg.getDataType();

The iflDataType returned can be one of the following: iflBit, iflChar, iflUChar (an unsigned char), iflShort, iflUShort, iflLong, iflULong, iflFloat, or iflDouble. (These types are defined in the il/iflDataTypes.h header file and listed in “Describing Image Attributes”.)

Use isSigned() to query an ilImage about whether its data type is signed:

int sign = myImg.isSigned();

As shown, this function takes no arguments and returns TRUE (nonzero) if the image's data type is signed and FALSE (zero) otherwise.

Operators accept input images of any data type. Internally, however, operators may use a different data type than the input data type to process the image. In this case, the data is converted as needed to perform the computation. If you know what data type you need at the end of the computation, you can use the setDataType() function to force the data type.

The channels composing an image's pixel data can be ordered in three ways: iflInterleaved, iflSequential, or iflSeparate. These are the three possible return values of the enumerated type, iflOrder. To return the data ordering, use its member function, getOrder(), as follows:

iflOrder imgOrder;
imgOrder = myImg.getOrder();

The meanings of the three orders are illustrated in Figure 2-4.

Figure 2-4. Pixel Data Ordering for an RGB Image

Thus, the order defines that dimensions that vary most rapidly relative to the others in a chunk of data. For example, in the interleaved case, the channel dimension varies most rapidly, and the z dimension varies least rapidly. Here is how the dimensions vary for each of the orders, listed from most to least rapidly: iflInterleaved (c,x,y,z), iflSequential (x,c,y,z), iflSeparate (x,y,z,c).

In the rare cases where you need to set an image's order, use the setOrder() function. Some classes derived from ilImage, such as ilFileImg, do not let you change an image's order.

An image's color model determines the meaning of the data channels from which a pixel is constructed. The IL defines an iflColorModel enumerated type (in the header file il/iflDataTypes.h) that can refer to the following color models:

The getColorModel() function allows you to query an image about its color model. If necessary, you can change the data interpretation by using the setColorModel() function.

Determining the Color Model

If an application or derived class does not use the setColorModel() function to explicitly set the color model of an ilOpImg object, the color model defaults to the lowest common ancestor of the input images as shown in Figure 2-5:

Figure 2-5. Determining Color Model Inheritance for Operator Images

All classes derived from ilOpImg have specified output data types, data ordering, working data types, and fields that can be set on an object. You can identify them by finding the following functions in each class: setValidType(), setValidOrder(), setWorkingType(), and setAllowed(), respectively. For example, the ilWarpImg operator uses an iflUChar as the output data type, can use any output ordering, uses iflFloat as the working type, and can have any of its fields set.

You can set the data type or data order explicitly to a valid type or ordering by calling the ilImage member function setValidType() or setValidOrder(), respectively. If the data type or order is not set explicitly in this manner, they default to the “smallest” of the valid types or ordering that is at least as “great” as each input type or order. Here “small” and “great” refer to the numeric values of the types and ordering, as defined in il/iflDataTypes.h.

An ilOpImg object has a “working type”, which is the data type used for calculations. The working type is often the same as the output data type. When this is not the case, the setWorkingType() function is used to define the working types.

The setAllowed() function specifies which fields can be set on an object that is an instance of a class derived from ilOpImg.

Some images include a color palette that is used to interpret their data. A color palette is also referred to as a lookup table or LUT. The most common use of such a table is to store color map values. The iflLut class, defined in the header file ifl/iflLut.h and described in “Using iflLut”, is provided for such purposes. To set an image's LUT, use setColorMap():

ilStatus setColorMap(const iflLut& lut);

The table pointed to by lut is established as the image's look-up table. This function copies the specified iflLut but not its data. The getColorMap() function returns by reference an image's LUT:

void getColorMap(iflLut& lut);

Two other functions—iflSGIColormap() and ilSGIFileLut()—create look-up tables for use in managing color map data. They are described in “Using iflLut” and in their own reference pages.

Different file formats arrange their data in different ways. By default, a TIFF file image considers its origin to be the upper left corner; if you scan through the data, you should read from left to right, working your way down the image. An SGI RGB image considers its origin to be the lower left corner; to read through its data, again read from left to right, but work your way up the image.

The IL defines an iflOrientation data type to represent the possible orientations of image data. To query an image about the orientation of its data, use getOrientation(), which returns one of the eight values listed below. (You can set an image's orientation with the setOrientation() function.) These four orientations use the traditional orientation of the x and y dimensions (the x dimension runs horizontally, and the y dimension runs vertically):

The following four orientations have the x and y dimensions transposed so that the x dimension runs vertically, and the y dimension runs horizontally.

Figure 2-6 illustrates the difference between iflUpperLeftOrigin and iflLeftUpperOrigin orientation of image data.

Figure 2-6. Image orientations

When a function tries to access pixels that are beyond an image's edge, those pixels are set to the image's fill value. By default, an image's fill value is 0, but you can set a different fill value with the setFill() function:

static float fillData[3] = {127.0, 127.0, 127.0};
myImg.setFill( iflPixel(iflFloat, 3, fillData) );

As shown, setFill() takes a reference to an iflPixel as an argument. An iflPixel defines the pixel is data type (in this case, iflFloat), the number of data channels (3), and the pixel data itself (fillData[]). (In this example, the iflPixel value is passed in-line so that the compiler automatically constructs and deletes the object.) The image makes its own copy of the pixel data.

Use getFill() to query an image about its fill value:

iflPixel theFillValue;
myImg.getFill(theFillValue);

void* allocFillData(float red, float green, float blue);
void freeFillData(void* data);

By default, no restrictions are placed on the range of allowable pixel values. However, when an image is displayed—for example, using the ABGR color model—its pixel values may need to be converted to the range that is meaningful for the framebuffers, which is 0 to 255. If you explicitly set an image's minimum and maximum allowable pixel values, they are used to color-scale the data as it is displayed.

You might want to set the allowable pixel values for a processed image so that the resulting data has certain characteristics, especially if you display the data. For example, suppose you are using an edge detection filter that theoretically produces data ranging in value from -1000 to +1000. However, you know that the images you'll be filtering will actually yield filtered data ranging from -100 to +100. If you set the allowable values to match this range and then display the filtered data, the display will be more useful, since the data will be scaled and stretched out over the framebuffer is meaningful range.

ilStatus setMinPixel(const ilPixel& pix);
ilStatus setMaxPixel(const ilPixel& pix);

void getMinPixel(ilPixel& pix);
void getMaxPixel(ilPixel& pix);

ilStatus setMinValue(double val, int c=0);
ilStatus setMaxValue(double val, int c=0);

double getMinValue(int c=-1);
double getMaxValue(int c=-1);

void initScaleMinMax(int force=0);

ilStatus setScaleMinMax(double min, double max); 
ilStatus setScaleType(iflDataType type = iflDataType(0));

double getScaleMax();
void getScaleMin();

Often, images stored in a file on disk are compressed to minimize their size. Such images need to be decompressed before they can be read. There are many different compression algorithms. Each file format (for example, TIFF) determines which algorithms it supports. See “Setting a File's Compression” for more information about which compression algorithms the IL supports. From a programmer's point of view, as data is read or written in an IL program, its compression or decompression is handled transparently.

By default, the cache size is set to 30% of the total user memory on the host system. The IL provides two functions to override the default size of the cache, ilSetMaxCacheSize() and ilSetMaxCacheFraction(), which are defined as shown below:

void ilSetMaxCacheSize(int maxBytes);
void ilSetMaxCacheFraction(float fraction);

The first function sets the cache size to the number of bytes indicated. The second function computes the size of the cache as the indicated fraction of the total user memory on the host computer.

You can change these limits without modifying an IL- based program by using the environment variables IL_CACHE_SIZE or IL_CACHE_FRACTION to set either the size in bytes or the fraction of user memory, respectively. The IL_CACHE_SIZE value overrides the value specified by IL_CACHE_FRACTION. Any value established with these environment variables is overridden by calls to ilSetMaxCacheSize() or ilSetMaxCacheFraction().

The current value of these cache size limits can be obtained with either ilGetMaxCacheSize() or ilGetMaxCacheFraction(). The current actual size of the object is cache can be retrieved with ilGetCurCacheSize(). These functions are defined as follows:

int ilGetCurCacheSize();
int ilGetMaxCacheSize();
float ilGetMaxCacheFraction();

The IL maintains the global cache in a special memory pool that allows the cache memory to be compacted to eliminate memory fragmentation problems. When fragmentation exceeds a defined threshold, the pool is automatically compacted. You can use the ilSetCompactFraction() function to set the fragmentation threshold to the maximum fraction of the pool that is allowed to be wasted space before compaction occurs. The current value of this threshold can be obtained with ilGetCompactFraction(). The default compaction fraction value is .2 or 20%.

ilSetCompactFraction(float maxWastedFraction);
float ilGetCompactFraction();

You can force compaction of the pool at any time by calling ilCompactCache(). If the pool is more fragmented than the fraction passed to this routine, it is compacted. You can pass zero to cause the pool to be unconditionally compacted.

ilCompactCache(float maxWastedFraction=0);

You can use the getCacheSize() function of ilMemCacheImg to query the cache size for an individual object:

int getCacheSize();

You can use the flush() member function of ilMemCacheImg to flush the cache for an individual object:

ilStatus flush(int discard=FALSE));

You can free the memory in the global cache to get it down to a desired maximum size with ilFlushCache(). This call also compacts the cache memory.

int ilFlushCache(int maxsize);

The IL assigns priorities to pages in the cache and uses these priorities to make decisions about which pages to discard. The priority associated with pages in cache ranges from zero (lowest) to seven (highest); the higher the priority, the greater the likelihood the page will remain resident.

The IL maintains a linked list of the pages in cache for each of priority levels 0 through 7. Figure 2-9 illustrates this concept. This simplified diagram shows a cache with three pages at priority level seven, two pages at priority level three, and three pages at level zero.

Figure 2-9. Priority Lists in Cache

The initial (default) priority level of a page is zero. The following events can cause a change to the priority level:

You can use the ilmonitor utility to monitor the activity of pages in cache. See the ilmonitor reference page or “Image Tools” for more information about ilmonitor.

The page size for each operator is defined by its input images. For an ilFileImg, the page dimensions match those used to store the image on disk. Some images also let you set the size of the pages in the cache, the data type, and the ordering of the cached data. The data type and ordering affect how data is cached, so if you change these attributes, you might also want to change the size of the cache. To set the data type or the ordering of data in the cache, use the appropriate functions defined by ilImage, setDataType() and setOrder(). These functions are described in “Image Attributes”. “Managing Cache” describes how to set the size of the cache.

Only image operators allow you to set the page size of an image. If you change the page size of an image, you should follow the suggestions in “Cache Priority”.

To set the size of the pages used in the cache for a particular image, use setPageSize(), which is defined in the ilImage class as follows:

ilStatus setPageSize(int nx, int ny, int nz, int nc)
    { return setPageSize(iflSize(nx, ny, nz, nc)); }
ilStatus setPageSize(const iflSize& pageSize);
ilStatus setPageSize(int nx, int ny);

The following functions are related:

ilStatus setPageSizeZ(int nz);
ilStatus setPageSizeC(int nc);

The arguments specify the x, y, z, and c dimensions of the page in pixels. This function calculates the number of bytes needed to store a page with the specified dimensions.

You can use any of the following functions to query an image about its page size, depending on whether you want the answer in page dimensions, bytes, or pixels:

size_t getPageSize();
size_t getPageSize(int& nx, int& ny, int& nz, int& nc);
size_t getPageSize(int& nx, int& ny)
size_t getPageSize(iflSize& pageSize, iflOrientation workOrientation);
size_t getPageDimensions(iflSize& pageSize)
int getPageSizePix();
int getPageSizeVal();

The ilImage class provides functions to support paging in a multi-threaded environment. These functions allow you to lock pages to ensure that those pages stay in memory until you unlock them. The five virtual functions that control paging are:

virtual int hasPages();
virtual ilPage* lockPage(int x, int y, int z, int c, 
          ilStatus& status, int mode=ilLMread);
virtual void unlockPage(ilPage* page);
ilStatus lockPageSet(ilLockRequest* set, 
          int mode=ilLMread, int count=1);
void unlockPageSet(ilLockRequest* set, int count=1);

These methods provide a mechanism to bypass the overhead of getTile() and setTile(), but they require that you consider all of the attributes of the page: size, data type, and order.

The two-dimensional functions you are likely to use most frequently are getTile(), setTile(), and copyTile(). As their names suggest, these functions read (get), write (set), and copy a tile of data. They assume the data buffer being read into or written from is the exact size necessary to hold the tile being read or written; if the buffer is larger use getSubTile() or setSubTile().

Another pair of functions, getPixel() and setPixel(), allow you to read and write pixels rather than tiles. The fillTile() function allows you to fill a two-dimensional tile of data with a specified constant value.

ilStatus getTile(int x, int y, int nx, int ny, 
    void* data,const ilConfig* config=NULL);
ilStatus setTile(int x, int y, int nx, int ny, void* data,
    const ilConfig* config=NULL);

copyTile()

The copyTile() function is an efficient way to copy a tile of data from one ilImage to another:

ilStatus copyTile(int x, int y, int nx, int ny, ilImage* image, int ox, int oy, int* chanList=NULL);

The tile is copied to the location (x, y). (nx, ny) specifies the size of the tile. (ox, oy) specifies the location in the source image from which the data is copied. (If the tile is at the same location in both the source and destination images, then x=ox and y=oy.) If the source and destination images have different orientations, the data is transposed automatically as necessary.

No configuration argument is needed for copyTile() because the destination image's configuration is always used. Data is automatically converted as necessary to match the destination image's data type, order, and orientation. However, you can choose a subset of the source image's channels and/or reorder them using the optional chanList argument. This argument is an int array that specifies a channel mapping between the other image and the calling image. The number of entries in the array should always match the number of channels in the calling image; a negative one (-1) in the array means that no data will be written for that channel.

As an example, suppose you have an RGB image (with red, green, and blue channels) that you want to display as an ABGR image (with alpha, blue, green, and red channels). The code for accomplishing this conversion is:

/* allocate the data buffer */ int xsize = 20; int ysize = 10; char data[xsize*ysize*3]; /* specify the channel list and configuration */ static int chans[] = {3, 2, 1}; ilConfig config(iflUChar, iflInterleaved, 3, chans); /* read the data from one image and write it to the other */ RGBImg.getTile(0, 0, xsize, ysize, data); ABGRImg.setTile(0, 0, xsize, ysize, data, &config);

---

Note: You can do this conversion most simply with the color conversion operators that derive from ilColorImg, but this example using getTile() and setTile() is presented for discussion purposes.

---

First, a buffer, data, is allocated to hold the 20-pixel by 10-pixel three-channel tile as it is copied. Next, the configuration that the data should be mapped into is specified. The channel list, chans, maps the channels of the RGB data to the channels of the ABGR image, as follows:

• Channel 0 of the RGB data (the red channel) is mapped to channel 3 of the ABGR image (also the red channel).

• Channel 1 of data (green) is mapped to channel 2 of the ABGR image (also green).

• Channel 2 of data (blue) is mapped to channel 1 of the ABGR image (blue).

• Nothing is available to map to channel 0 of the ABGR image (the alpha channel).

Finally, the data is read into the buffer from RGBImg and then it is written to ABGRImg from the buffer.

The following code performs the same task using copyTile() instead:

int xsize = 20; int ysize = 10; static int chans[] = {-1, 2, 1, 0}; ABGRImg.copyTile(0, 0, xsize, ysize, RGBImg, 0, 0, chans);

In this case, an intermediate data buffer is not needed; the tile is copied directly from RGBImg to ABGRImg. The channel list specifies how the channels of RGBImg are mapped to those of ABGRImg, as shown in Table 2-3.

Table 2-3. Channel Mapping

Channel List	RGBImg Channel	ABGRImg Channel
-1	none	0 (alpha)
2	2 (blue)	1 (blue)
1	1 (green)	2 (green)
0	0 (red)	3 (red)

The interpretation of the channel list is the same if the direction of the copy is reversed. If the same channel list were used with a call to copyTile() that specified 0 as the direction argument, data would be copied from ABGRImg to RGBImg as follows:

• Channel 0 of ABGRImg is not copied at all.

• Channel 1 of ABGRImg is copied to channel 2 of RGBImg.

• Channel 2 of ABGRImg is copied to channel 1 of RGBImg.

• Channel 3 of ABGRImg is copied to channel 0 of RGBImg.

If you need to offset channels, you must use copyTileCfg() instead of copyTile(). copyTileCfg() is discussed in “Three-dimensional Functions”. To force a two-dimensional interpretation of copyTileCfg(), specify zero values for the z, nz, and oz parameters.

destImage<<srcImage;

getSubTile() and setSubTile()

One limitation of getTile() and setTile() is that the data buffer must be the exact size needed to hold the data being read or written. If the buffer you are reading data into or writing it from is larger than the tiles being read or written, use getSubTile() or setSubTile() to specify a subtile of the larger buffer. (Be sure the buffer is at least as large as the tile being read or written and that the tile is completely contained in the buffer.) The calling sequences for these functions are as follows:

ilStatus getSubTile(int x, int y, int nx, int ny, void* data, int dx, int dy, int dnx, int dny, const ilConfig* config=NULL); ilStatus setSubTile(int x, int y, int nx, int ny, void* data, int dx, int dy, int dnx, int dny, const ilConfig* config=NULL);

The x, y, nx, ny, data, and config parameters have the same meanings as they have in getTile() and setTile(). The remaining parameters specify the origin of the data buffer (dx,dy) relative to the image and the size of the buffer (dnx and dny), as shown in Figure 2-10. (This figure assumes that the image's orientation defines the origin as the lower left corner.)

Figure 2-10. Parameters for getSubTile() and setSubTile()

With either function, if the data buffer is the same size as the source tile, then x=dx, y=dy, nx=dnx, and ny=dny.

ilStatus getPixel(int x, int y, ilPixel& pix);
ilStatus setPixel(int x, int y, ilPixel& pix);

ilStatus fillTile(int x, int y, int nx, int ny, 
              const void* data, const ilConfig* config=NULL, 
              const iflTile3Dint* fillMask=NULL);

The three-dimensional data access functions are the same as their two-dimensional counterparts, except that they take extra arguments as necessary to handle an image's z dimension. For example, getTile3D(), setTile3D(), and copyTile3D() take arguments to specify the origin and size in the z dimension:

ilStatus getTile3D(int x, int y, int z, int nx, int ny, 
        int nz, void* data, const ilConfig* config=NULL);
ilStatus setTile3D(int x, int y, int z, int nx, int ny, 
        int nz, void* data, const ilConfig* config=NULL);
ilStatus copyTile3D(int x, int y, int z, 
        int nx, int ny, int nz, 
        ilImage* image, int ox, int oy, int oz,
        int* chanList=NULL);

The copyTileCfg() function works similarly to the copyTile3D() function, except that it allows the channels of the copied data to be offset as well as reordered when it is copied:

virtual ilStatus copyTileCfg(int x, int y, int z, 
        int nx, int ny, int nz,
        ilImage* image, int ox, int oy, int oz,
        const ilConfig* config=NULL);

---

Note: This function takes an ilConfig* argument rather than an int*. Only fields in the ilConfig that refer to the number of channels, channel list, and channel offset are used during the copy; the other fields are ignored.

---

The getSubTile3D() and setSubTile3D() functions require several additional arguments to specify the origin and size of the z dimension in both the source and the destination:

ilStatus getSubTile3D(int x, int y, int z, 
        int nx, int ny, int nz,
        void* data, int dx, int dy, int dz, 
        int dnx, int dny, int dnz,
        const ilConfig* config=NULL) = 0;
ilStatus setSubTile3D(int x, int y, int z, 
        int nx, int ny, int nz,
        void* data, int dx, int dy, int dz, 
        int dnx, int dny, int dnz,
        const ilConfig* config=NULL) = 0;

The fillTile3D() function takes arguments that are similar to the two-dimensional versions:

virtual ilStatus fillTile3D(int x, int y, int z, 
        int nx, int ny, int nz, 
        void* data, const ilConfig* config=NULL, 
        const iflTile* fillMask=NULL);

This section discusses a few functions designed to perform tasks related to accessing data. getStrides() helps you step through a buffer of image data. clipTile() clips a tile to the dimensions of the image.

void getStrides(int& xs, int& ys, int& zs, int& cs,
int nx=0, int ny=0, int nz=0, int nc=0,
iflOrder ord=iflOrder(0));

ilStatus clipTile(int& x, int& y, int& z, 
        int& nx, int& ny, int& nz, int includeBorder=FALSE);

Several functions are defined to help you translate image data between different orientations:

iflOrientation mapFlipTrans(iflOrientation fromSpace, 
        iflFlip& flip, int& transXY, 
        iflOrientation workSpace=iflOrientation(0));
void mapTile(iflOrientation fromSpace, iflTile& tile,
        iflFlip& flip, int& transXY, 
        iflOrientation workSpace=iflOrientation(0));
void mapTile(iflOrientation fromSpace, iflTile& tile,
        iflOrientation workSpace=iflOrientation(0));
void mapXY();
void mapXY(iflOrientation fromSpace, int& x, int& y, 
        iflOrientation workSpace=iflOrientation(0));
void mapXY(iflOrientation fromSpace, float& x, float& y, 	
        iflOrientation workSpace=iflOrientation(0));
void mapXYSign(iflOrientation fromSpace, float& x, float& y, 
        iflOrientation workSpace=iflOrientation(0));
iflOrientation mapSpace(int flipX, int flipY, 
        int transXY=FALSE);
void getSize(iflSize &sz, iflOrientation workSpace);
int isMirrorOrientation(iflOrientation otherSpace, 
        iflOrientation workSpace=iflOrientation(0));

The mapFlipTrans() function determines the flips and/or transpositions necessary to map coordinates from the fromSpace orientation to workSpace (and returns them by reference). The mapTile() and mapXY() functions map the specified tile or (x,y) point from fromSpace to workSpace. The mapXYSign() function reverses the sign of the (x,y) values if workSpace is flipped with respect to fromSpace; it also swaps the values (that is, exchanges x for y and vice versa) if the orientations are transposed. The mapSpace() function returns the orientation that results from performing the specified flips, transpositions, or both. The other two functions return information related to an image's orientation. The getSize() function maps the image's size to the workSpace orientation and returns it by reference. The isMirrorOrientation() function returns whether otherSpace is a mirror image of workSpace.

For more information about these functions, see the ilImage reference page.

Four functions are defined in ilImage to support image processing operators that perform geometric transformations:

void mapToSource(iflXYfloat& src, const iflXYfloat& self);
void mapFromSource(iflXYfloat& self, const iflXYfloat& src);
virtual void evalXY(iflXYfloat& xy, const iflXYfloat& uv);
virtual void evalUV(iflXYfloat& uv, const iflXYfloat& xy);

mapToSource() transforms the coordinates in self into the source image's orientation and places them in src. mapFromSource() transforms the coordinates in src into the calling image's orientation and places them in self. evalXY() maps from the calling image's orientation to the immediate input image's orientation. evalUV() maps from the immediate input image's orientation to the calling image's orientation.

In the IL's execution model, image data is processed only on demand. This technique minimizes both the need to store intermediate results and the frequency of disk input and output operations so that overall program performance is optimized. IL programs that apply multiple successive image processing operators or that deal with large images especially benefit from this execution model.

---

Note: An operator is a class derived from ilOpImg that applies its image processing algorithm to the data encapsulated in an ilImage object. See Chapter 4, “Operating on an Image,” for more information.

---

An IL program implements the demand-driven execution model in two stages:

In Example 1-1, a relatively simple image chain is constructed. Figure 2-11 shows this chain with arrows indicating the path that image data follows as it is read from disk, processed (sharpened and rotated), displayed, and written to disk.

Figure 2-11. Image Chain for the Sample Program

An image processing library that uses the conventional execution model shuffles data in and out of memory at each stage of the chain. Such a program:

If the image is too large to be cached in memory, a conventional library will write at least some of the processed data to disk for each intermediate stage. This data then needs to be read back in from disk for each successive stage.

In contrast, the IL pulls one or several pages of image data at a time all the way through the chain. After a page is completely processed—in this example, read from disk, sharpened, rotated, displayed, and written to a file on disk—the next page is pulled through the chain. When multi-threading is enabled, several pages can be in process through the chain at any one time. This execution model eliminates the need to save intermediate processing results for all images, regardless of their size. The IL's model also minimizes startup time for IL programs, particularly those that allow the user to roam around a large image. The data for the entire image is not processed before startup; it is processed only as needed, which, in this case, is as the user roams.

The arrows in Figure 2-12 show how data is pulled through the image chain in Example 1-1.

Figure 2-12. Image Chain Showing Demand-driven Execution Model

In this example, the redraw() and copyTile() function calls issued by the program instigate the processing of image data. They cause successive tiles of image data to be pulled through the chain and sent to the display or back to the disk. As each tile is written, another tile is requested from the previous stage of the chain with a getTile(), copyTile(), or ilMemCacheImg::executeRequest() calls. If the tile requested does not already reside in the cache, the page containing that tile is pulled through the chain—read from disk, sharpened, and rotated. The ilDisplay class manages the transfer of data from the end of the chain to the framebuffer.

In Example 1-1 in Chapter 1, “Writing an ImageVision Library Program,” the instigating functions—ilDisplay's redraw() and ilTIFFImg's copyTile()—are actually called in the program. The other function calls are generated automatically as the program executes. Thus, only data that is actually needed is pulled through the chain.

Example 1-1 displays and writes to disk the entire processed image one tile at a time. Other image processing programs might not even process an entire image. For example, suppose that instead of simply displaying the entire final image, a program allows the user to roam around the image, viewing only a fraction of it at a time. This kind of user interface is typically provided with programs that deal with huge images. Since IL programs process data only as it is needed, only those portions of the image that the user demands to see are processed. It is often the case that the user will never view some portions of a large image; those portions are not read from disk or processed. Thus, the IL helps minimize your program's overall processing requirements.

The multi-threading part of the IL's execution model optimizes overall program performance by allowing portions of an IL program to execute in parallel. For example, when a tile covering several pages is copied from one operator to the next in a chain and the tiles are not resident in cache, they must be fetched from disk. The IL implements the parallel fetching of pages by queueing a request for each page and creating a process thread to service each request.

Figure 2-13 shows how long it takes to read in and perform computations on four pages in a non-multi-threaded application, a multi-threaded application running on a single-processor machine, and a multi-threaded application running on a multiple-processor machine. As you can see, the multi-threaded applications complete this transaction more quickly than the non-multi-threaded application.

Figure 2-13. Performance Comparison of Non-threaded, Single-processor, and Multi-processor Applications

IL supports parallel execution on single- and multiple-CPU machines by creating process threads that execute portions of an IL program simultaneously. This multi-threading facility is implemented transparently and automatically: there are no special function calls to make or header files to include. When you derive new classes from the existing classes in the library, however, you must ensure that the code you produce is reentrant, that is, able to be called from several process threads running concurrently. Chapter 7, “Optimizing Your Application,” explains how to do this.

When debugging your application or linking with other libraries that perform multi-threading, you may want to turn off IL's multi-threading facility. The preferred way to do this is to set the environment variables IL_COMPUTE_THREADS and IL_SPARE_THREADS to zero by using the convenience function ilMPSetMaxProcs(), as follows.

ilMPSetMaxProcs(0,0);

This global function does not belong to any class.

How Multi-threading Works

When the IL processes a getTile() or copyTile() call, it determines the pages needed for the requested tile and dispatches a request for each page. It then maintains these requests in a queue and creates process threads to service the queue. Figure 2-14 illustrates the concept of multi-threading as well as the on-demand processing described in the preceding section.

Figure 2-14. Operators, Requests for Pages, and Threads

The hardware acceleration facility built into the IL allows your application to automatically take advantage of specialized graphics hardware whenever possible in order to make certain IL operations more efficient. IL does this by performing one or more operations at the end of a chain in the graphics hardware instead of the CPU. On some architectures, it does this by reserving part of the framebuffer as a pixel buffer for IL. Computations are then performed on the data stored in the framebuffer and displayed more quickly than if the data were being operated on in the CPU and brought in from main memory. If the IL needs a tile that is not in the reserved part of the framebuffer, the tile is brought into the framebuffer from main memory. This model is implemented transparently and automatically; there are no header files to include or function calls to make.

Some IL programs need to construct new image chains dynamically as the program executes. For example, imagine a program with a graphical user interface that allows its user to specify input images and select operations to be performed on them. Once processing has been performed, the user can choose to operate further or to start again with new images and operators. Such a program is most easily implemented by taking advantage of the IL's facility for reconfiguring an image chain.

Each image in a chain maintains two lists, one of the images directly preceding it in the chain (its inputs or parents) and one of the images succeeding it in the chain (its children). In the chain shown in Figure 2-15, for example, the ilRotZoomImg object has one parent, the ilSharpenImg object, and two children, the ilTIFFImg and ilDisplay objects.

Figure 2-15. An Image Chain

The first item on a list is at index 0.

// set the threshold value to 127.5
float threshValue = 127.5;
iflPixel threshPixel(iflFloat, 1, &threshValue);
// create the ilThreshImg operator
ilThreshImg myThresher(inImg, threshPixel);
// replace ilSharpenImg with ilThreshImg 
rotatedImg.setInput(&myThresher);

ilImage* myInput;
ilImage* myChild;
myInput = theImg.getInput(0);
myChild = theImg.getChild(0);

ilStatus addInput(ilImage* img);
ilStatus removeInput(int index = 0);

One important property of image chains is that they propagate attribute values to succeeding stages of the chain. In other words, each stage of the chain receives some or all of the attributes of the preceding stage. The attributes that are propagated—image size, data type, order, orientation, color model, lookup table, page size, minimum and maximum pixel values, and the fill value—are defined in ilImage and discussed in “Image Attributes”.

myImg.clearSet(ilIPdataType);