Appendix F. Auxiliary Classes, Functions, and Definitions

This appendix describes IL classes not fully discussed elsewhere in this guide. It also lists all the error codes and enumerated types used by the IL. This appendix has the following major sections:

Auxiliary Classes

All of the classes described in this section have their own reference pages; refer to them for more specific information about using these classes.

  • The iflBitArray class implements a subscriptable bit array of limited functionality for conveniently operating on bit data.

  • ilBuffer (allocated from the heap) and ilStackAlloc (allocated from the stack) are standalone objects that provide support for accessing a buffer in up to four dimensions. The call operator, (), is overloaded to operate on either type of buffer and returns a pointer to the specified element in the buffer. In addition, the an ilBuffer can be resized after being created. An ilStackAlloc is recommended for use in derived operators, since it tends to fragment the memory less than an ilBuffer does, thus resulting in better performance for an application. However, an ilStackAlloc cannot be resized.

  • The iflConfig class is used in ilImage functions such as getTile() and setTile() to describe the configuration of pixel data. You can also use it when constructing an ilSubImage to map the configuration of the input image to that of the subimage. This class is described in more detail in “iflConfig”.

  • ilKernel is the base class for a three-dimensional kernel. The kernel elements are stored in row-major form. An ilKernel is defined by x, y, and z dimensions, the kernel data, the kernel origin, and the data type of its elements. ilKernel also provides functions to access kernel attributes and data. ilSepKernel is derived from ilKernel for representing separable kernels. ilSepKernel enables access to x, y, and z kernels separately.

  • The iflLut class is used to access and manipulate lookup tables. This class is described in more detail in “Using iflLut”.

  • The ilPage class is used to describe rectangular regions of an image in a cache (that is, pages). This class groups the eight values describing the origin (x,y,z,c) and size (nx,ny,nz,nc) of a page together in a convenient way.

  • The iflPixel class abstracts the concept of a pixel of image data. It contains the data type, the number of channels, and a list of component values. Pixels are used as arguments to a number of ilImage functions and to some operator image constructors and functions.

  • iflSize is used to describe the size of an IL image. This class groups the four values describing the size (x,y,z,c) of an image together in a convenient way.

  • The iflTile class is used to describe arbitrary rectangular regions of an image (that is, tiles). This class groups the six values describing the origin (x,y,z) and size (nx,ny,nz) of a rectangle together in a convenient way.


The header file ifl/iflConfig.h defines the class iflConfig, which is a structure used to describe the configuration of pixel data on getTile() and setTile() calls. The fields of iflConfig describe the data type, pixel ordering, number of data channels, ordering of data channels, channel offset, coordinate space, and color model (the color model field is currently ignored by functions such as getTile() and setTile()). The code in Example F-1 shows the iflConfig constructors and fields.

Example F-1. iflConfig Constructors and Fields

iflDataType dtype;
iflOrder order;
iflOrientation orientation;
int nchans;
int choff;
int* channels;

iflConfig() {}
iflConfig(iflDataType type, iflOrder ord=iflInterleaved, int nchan=0, 
            int* chanList=NULL,int chanOff=0, 
            iflOrientation ori=iflOrientation(0));

~iflConfig() {}

void invert(int nc, int* chanList) const;
int isInvertable() const;
void compose(int nc, int* in, int* out) const;

int mapChan(int idx) const
        { return (idx<0||idx>=nchans)? -1:
          (channels!=NULL? channels[idx+choff]:idx+choff); }
int operator[](int idx) const
        { return mapChan(idx); }

The fields of an iflConfig are set with its constructor. The data type argument is required; the other arguments are optional. The channel list defines what channels of a source image are mapped into a destination image; the channel offset defines where to start counting the source channels as zero. For example, consider a source image with 11 channels (0...10) and suppose you wish to map channels 4, 5, and 6 to a destination image. You can do this by setting the number of channels to 3 and the channel offset to 4 (so that the first channel mapped is 4, and the next 3 channels in the source define all 3 channels). No channel list is necessary. Alternatively, you can set the number of channels to 3, the channel offset to 0, and the channel list to 3, 4, 5. The hints field is reserved for internal IL use only.

invert() is used to create a channel list of nc channels (written into chanList) that describes an inverse mapping between two images. For example, a source image defines three channels (0, 1, 2) and you have mapped 0 to 2, 1 to 0, and 2 to 1 in a destination image (the channel list to do this is 1, 2, 0). To map the destination to the source instead, use invert(). (This is useful to avoid creating a temporary buffer when copying from an ilDisplayImg to an ilOpImg, for example.) In the above example, the resulting channel list is 2, 0, 1. isInvertable() is used to determine whether the channel mapping has an inverse.

compose() is used to compose a channel list from a subset of another; you supply the number of channels, nc, and the subchannel list, in, and compose() writes its result to out. For example, a source image defines three channels (0, 1, 2) and you have mapped 0 to 2, 1 to 0, and 2 to 1 in a destination image (the channel list to do this is (1, 2, 0). However, the source image is actually an ilSubImg (a subimage of another ilImage) that contains no data itself. It specifies a subset of its parent image's channels; they are 2, 4, and 6 (so it uses an iflConfig with channel list 2, 4, 6). To map directly from the source's parent image to the destination image, you need a composed channel list. The ilSubImg's channel list is specified as in, and the 3 values mapped to out are 4, 6, 2.

The member function mapChan() returns the contents of channels (the channel list) at the specified index added to the channel offset specified by choff. The index operator, [], is overloaded to perform the same function as mapChan(); both indicate what channel in the source maps to the specified channel in the destination. Both return -1 if the supplied index is less than 0 or greater than the number of channels.

Using iflLut

The header file ifl/iflLut.h defines a class, iflLut, used to describe lookup tables. The elements used to define an iflLut are the number of channels, the data type, the table length, and the table data. The code in Example F-2 shows the constructors and member functions for iflLut.

Example F-2. iflLut Constructors and Member Functions

        { init(NULL, 0, iflDataType(0), 0, 0); }

iflLut(int numChan, iflDataType dtype, double min, double max, int length=0)
        { init(NULL, numChan, dtype, min, max, length); }

iflLut(void* table, int numChan, iflDataType dtype, 
           double min, double max, int length=0) 
        { init(table, numChan, dtype, min, max, length); }

virtual ~iflLut();

int getNumChans() const { return numChannels; }
iflDataType getDataType() const { return type; }
int getLength() const { return tabLength; }

double getVal(double domainIdx, int chan=0) const;
iflStatus setVal(double val, double domainIdx, int chan=0);

void* getOrigin(int chan) const;
void* getChan(int chan) const;
void* getData() const { return data; }
void setData(void* dataPnt); 

void getDomain(double& min, double& max) const
        { min = domainMin; max = domainMax; }
double getDomainMin() const
        { return domainMin; }
double getDomainMax() const
        { return domainMax; }
double getDomainStep() const
        { return 1/scale; }
void getRange(double& min, double& max) const;
iflStatus setDomain(double min, double max);

int isDiff(const iflLut& from) const;

The first constructor takes a NULL argument and is only useful with assignment operators.

The second constructor allocates a lookup table (LUT) and takes control of the data. The minimum and maximum values specify the domain of values that the LUT maps. You can use the length argument to constrain the resolution of the LUT. The default value for length, if you do not specify it, is the maximum value minus the minimum value plus one (max. - min. + 1). This formula creates a one-to-one mapping of LUT index to LUT entry.

The third constructor wraps an iflLut object around user-specified data. The object does not copy the user data, however, it just retains a pointer to it.

The getNumChans(), getDataType(), and getLength() functions return basic attributes of the lookup table. The length reflects the actual number of entries in the table, not necessarily the domain of accepted values.

The getVal() and setVal() functions are the primary methods to access table entries. The domanIdx is scaled appropriately based on the minimum or maximum range and length of the table to access the corresponding table entry

The getOrigin() function returns a pointer to the first (0) entry in the LUT (even it if is off the physical table). getChan() returns a pointer to the beginning of the physical table for a specified channel. getData() returns a pointer to the beginning of the tables for all of the channels. The internal layout of the tables is channel sequential, not interleaved. setData() enables you to set table values.

The domain functions return and set information on the domain and range of the lookup table. You specify the minimum and maximum values of the domain in the constructor or by calling setDomain(). You can return the minimum and maximum values by calling getDomainMin() or getDomainMax(), respectively.

A table domain is defined by the minimum and maximum values specified in an iflLut constructor or in a setDomain() function. The domain step, returned by getDomainStep(), is the stepping factor used to read physical table values sequentially. The range value, returned by getRange(), is calculated by finding the difference between the maximum and minimum table entry values.

The isDiff() function compares two lookup tables an returns TRUE if there are any differences.

Useful Functions

This section describes utility functions defined by the IFL. These functions do not belong to any particular class, so they can be used anywhere in an IL program.

Computing the Size of Data Types

The IFL defines constants that correspond to the data types it uses; it also defines a related set of functions for determining the sizes and possible values for these types. These constants are defined as the iflDataType enumerated type in the header file ifl/iflTypes.h:

enum iflDataType {
    iflBit      = 1,    /* single-bit */
    iflUChar    = 2,    /* unsigned character (byte) */
    iflChar     = 4,    /* signed character (byte) */
    iflUShort   = 8,    /* unsigned short integer (nominally 16 bits)*/
    iflShort    = 16,   /* signed short integer */
    iflULong    = 32,   /* unsigned long integer */
    iflLong     = 64,   /* long integer */
    iflFloat    = 128,  /* floating point */
    iflDouble   = 256   /* double precision floating point */

The following two functions perform computations using the above data types. They are defined in the header file ifl/iflDataSize.h and described in the iflDataSize reference page.

size_t iflDataSize(iflDataType type, int count = 1);
iflDataType iflDataTypeFromRange(double minVal, double maxVal, 
    int typeMask=-1);
iflDataType iflDataClosestType(iflDataType desired, int allowed, 
    int flags=0);
double iflDataMin(iflDataType);
double iflDataMax(iflDataType);
int iflDataIsSigned(iflDataType);
int iflDataIsIntegral(iflDataType);

The first function, iflDataSize(), returns the number of bytes needed to store count elements of data type. By default, count is 1. Conversely, iflDataTypeFrom Range() returns the first IL data type that is large enough to hold the range of values specified by minVal and maxVal.

iflDataClosestType() returns an allowable data type that most closely resembles the input data type.

iflDataMax() and iflDataMin() return the maximum and the minimum possible values, respectively, for the specified data type.

If you pass one of the iflDataTypes as an argument for iflDataIsSigned(), this function returns TRUE if the type is signed and FALSE (zero) otherwise. Remember that ilImage defines a similar function for an image, isSigned(), that returns TRUE if the image's data type is signed.

If you pass one of the iflDataTypes as an argument for iflDataIsIntegral(), this function returns TRUE if the type is integral or FALSE (zero) otherwise.

Minimum and Maximum Comparisons

The header file ifl/iflMinMax.h defines several in-line functions that determine the minimum and the maximum of two to four input values, as shown below:

template<class T> inline T iflMin(T a, T b);
template<class T> inline T iflMax(T a, T b);

template<class T> inline T iflMin(T a, T b, T c); 
template<class T> inline T iflMax(T a, T b, T c);

template<class T> inline T iflMin(T a, T b, T c, T d);
template<class T> inline T iflMax(T a, T b, T c, T d);

The iflMin() function returns the lesser of the input values, and iflMax() returns the greater of the input values.

Converting to Color-index Mode

iflColorModelFromChans(), in ifl/iflColor.h., converts a channel to the closest corresponding value in the standard color map that is used in color-index mode.

iflColorModel iflColorModelFromChans(int nc);
int iflColorModelHasAlpha(iflColorModel cm);
int iflColorModelChans(iflColorModel cm);

iflColorModelChans() determines the number of channels for a given color model cm.

iflColorModelHasAlpha() determines whether or not alpha information is present in the image data.

Convenient Structures

This section lists the definitions of the iflCoord and various coefficient data structures.

Coordinate Data Structures

The structures listed in Table F-1 hold two- (x,y), three- (x,y,z), and four-dimensional (x,y,z,c) coordinates of various data types; they are defined in the ifl/iflCoord.h header file. iflXYC**, iflXYZC**, and iflXYZC** are simple structures without any constructors, destructors, or convenience operators.

Table F-1. Coordinate Data Structures




iflXYchar, iflXYCchar

iflXYZchar, iflXYZCchar

iflXYZCchar, iflXYZCchar

iflXYint, iflXYCint

iflXYZint, iflXYZCint

iflXYZCint, iflXYZCint

iflXYfloat, iflXYCfloat

iflXYZfloat, iflXYZCfloat


iflXYdouble, iflXYCdouble

iflXYZdouble, iflXYZCdouble


These structures are defined in ifl/iflCoord.h as follows:

struct iflXYchar        { char   x, y; };
struct iflXYint         { int    x, y; };
struct iflXYfloat       { float  x, y; };
struct iflXYdouble      { double x, y; };
struct iflXYZchar       { char   x, y, z; };
struct iflXYZint        { int    x, y, z; };
struct iflXYZfloat      { float  x, y, z; };
struct iflXYZdouble     { double x, y, z; };
struct iflXYZCchar      { char   x, y, z, c; };
struct iflXYZCint       { int    x, y, z, c; };
struct iflXYZCfloat     { float  x, y, z, c; };
struct iflXYZCdouble    { double x, y, z, c; };

Error Codes

Error codes are contained in il/ilStatus.h and ifl/iflStatus.h. The function getStatus() returns an ilImage's current status. Many other functions return the type ilStatus or iflStatus.

This section describes all of the error codes.

ilStatus Error Codes

Table F-2 describes the error messages found in ilStatus.h.

Table F-2. ilStatus Error Codes

Erro Message



Successful operation


Error reading from file


Error writing to file


malloc() or new returned NULL


Bad image file format


Bad dimensions


Bad object on construction


Bad attributes


Unsupported file format


Bad pixel type


Unsupported configuration


Cannot do random seek


Error seeking on file


Failure on decompression


Object is not writable


Failed to set field in file header


Invalid image compression


NULL object passed as parameter


Invalid input passed


Bad color format


Bad operation attempted


Error opening file


Invalid magic number in file


File is empty


Data has been clipped


Parameter(s) out of bounds


Too many pages locked in image cache


Incompatible number of channels in lut and image


Attempted to divide by zero


Attempted operation is unsupported


Used old limits for histogram calculation


TIFF page dimensions must be multiples of 8


Could not index into TIFF directory


Page is not resident in cache


Unable to complete hardware accelerated operation


Unable to complete hardware acceleration operation


Request has been parked




IFL error


Operation failed


Unlocked ilLockRequest


Input image has bad status


Operation was aborted


Result is not exact

iflStatus Error Codes

Table F-3 describes the error messages found in iflStatus.h.

Table F-3. iflStatus Error Codes

Error Messages



Successful operation


Image file is read-only


Image file is write-only


Bad parameters


Non-IFL library call.


Unsupported image format


Bad magic number, unrecognizable file type


Bad image


Failed to set field in file header


Failed to get field in file header


Configuration error


File index out of bounds


Malloc failed


Error in opening file


Error in closing file


Error in reading file


Error in writing file


Error seeking on file


Error in state


Failed when opening file format database, ifl_database


Script failed

Enumerated Types and Constants

The IL uses enumerated types and defined constants extensively; they are defined in header files such as ifl/iflDefs.h and il/ilDisplayDefs.h. This section lists these types and constants in the following functional groups, according to what they are used for: describing image attributes, controlling the effect of operators, and controlling the display facility. All of these types are described in more detail in the relevant chapters of this guide.

Also note that NULL, TRUE, and FALSE have been defined as follows in the header file ifl/iflDefs.h:

#ifndef NULL
#define NULL 0
#undef TRUE
#define TRUE 1
#undef FALSE
#define FALSE 0

Describing Image Attributes

ilDisplayDefs.h contains the remaining definitions used when describing image attributes.

 * Display mode bit fields (subject to change)
 * 0xDDCCBBAA where:
 * AA = Wipe/Align/Split Modes
 * BB = Param/Del Modes
 * CC = Defer/Clip/Stop Modes
 * DD = Paint/Display Modes
 * ilWipeMode passed as mode for display and wipe, and returned from
 * findView and findViewEdge
enum ilWipeMode {   
    ilNoView        = 0x00, /* No view found by findView()                  */
    ilTopEdge       = 0x01, /* wipe top edge, display image from top edge   */ 
    ilBottomEdge    = 0x02, /* wipe bottom edge, display from bottom edge   */ 
    ilLeftEdge      = 0x04, /* wipe left edge, display image from left edge */ 
    ilRightEdge     = 0x08, /* wipe right edge, display image from right edge*/ 
    ilAllEdge       = 0x0f, /* wipe operated as inset, display at center    */ 
    ilNoEdge        = 0x10, /* No edge found by findViewEdge()              */
    ilWipeMask      = 0x1F

 * ilAlignMode specifies the display() operator specific modes.
 * Combinations of ilWipeMode can alternatively be used for the first 5 values
enum ilAlignMode {      
    ilTopLeft       = 0x05, /* align view/image to top left corner      */ 
    ilBottomLeft    = 0x06, /* align view/image to bottom left corner   */ 
    ilTopRight      = 0x09, /* align view/image to top right corner     */ 
    ilBottomRight   = 0x0a, /* align view/image to bottom right corner  */ 
    ilCenter        = 0x0f, /* align view/image to center of image      */ 
    ilNoAlign       = 0x10, /* do not re-align (unchanged)              */
    ilAlignMask     = 0x1F

 * ilParamMode specifies how to interpret passed parameters
enum ilParamMode   {
    ilDelVal        = 0x00000100,   /* Delta relative to current            */
    ilAbsVal        = 0x00000200,   /* Absolute value                       */
    ilRelVal        = 0x00000400,   /* Relative to start xy                 */
    ilOldRel        = 0x00000800,   /* ilRelVal but start xy not updated    */              
    ilParamMask     = 0x00000f00

 * Specifies various display modes such as whether to clip or defer painting
enum ilDispMode    {
    ilDefault       = 0x00000000,   /* no clip, no defer, swap  */
    ilClip          = 0x00001000,   /* clip to display/image    */
    ilDefer         = 0x00002000,   /* defer painting           */
    ilNoSwap        = 0x00004000,   /* don't swap buffers       */
    ilDop           = 0x00008000,   /* override Nop flag        */
    ilDispMask      = 0x0000f000, 
    ilDspCoord      = 0x00010000,   /* ilDisplayImg coordinates passed   */
    ilScrCoord      = 0x00020000,   /* screen coordinates passed         */ 
    ilCoordMask     = 0x00030000,   /* for internal use only             */
    ilDefaultCmap   = 0x00040000,   /* use default colormap              */
    ilDestroy       = 0x00080000    /* internal use only                 */

 * ilSplitMode specifies how to split the views in ilDisplay. 
enum ilSplitMode            {
    ilRelSplit      = 0x00010000,   /* Split & pos image relative to view pos*/ 
    ilAbsSplit      = 0x00020000,   /* Split & pos image at origin              */ 
    ilRowSplit      = 0x00040000,   /* Split into rows                  */ 
    ilColSplit      = 0x00080000,   /* Split into columns                       */
    ilPackSplit     = 0x00100000,   /* Split views and pack together (if clipped) */
    ilSplitMask     = 0x001f0000

 * ilLocMode is used by getLoc() and setLoc() to find xy location
 * of a pixel in image and move image or view to specified location.
enum ilLocMode {
    ilLocIn         = 0x00100000, /* locate xy in image's input space   */
    ilLocOut        = 0x00200000, /* locate xy in image's output space  */
    ilLocImg        = 0x00400000, /* locate by moving image                 */
    ilLocView       = 0x00800000, /* locate by moving view                  */
    ilLocMask       = 0x00f00000

 * Image Render Modes 
enum ilRender {
    ilGLRender   = 1,       /* Render image using GL */
    ilXRender    = 2        /* Render image using X  */

#ifndef __cplusplus
typedef enum ilRender ilRender;

 * Miscellaneous 
enum ilDispMisc {
    ilLast              = -1,   /* add view to bottom of viewStack */
    ilDefaultMargin     = 15,   /* default margin width for findEdge etc */
    ilHighlight         = 0x10  /* find view and highlight its borders      */ 

 * ilViewer modes

enum ilAreaOption { 
    ilBadArea       = 0,    /* invalid */
    ilViewedImage   = 1,    /* the area of the image the selected view covers */
    ilFullImage     = 2,    /* the entire image associated with selected view */
    ilFullWindow    = 3     /* the entire window, all views */

#ifndef __cplusplus
typedef enum ilAreaOption ilAreaOption;