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” briefly discusses the iflBitArray, ilBuffer and ilStackAlloc, iflConfig, ilKernel, iflLut, ilMatrix, ilPage, iflPixel, iflSize, and iflTile classes.
“Useful Functions” describes several functions that does not belong to any particular class. They are useful for such tasks as computing the size of IL data types and for performing minimum and maximum comparisons.
“Convenient Structures” lists the definitions of the ilCoord, iflSize, and various coefficient data structures.
“Error Codes” lists the error codes used by the IL.
“Enumerated Types and Constants” gives an annotated list of the enumerated types and constants defined in the IL.
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.
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.
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.
iflLut()
{ 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.
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.
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.
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.
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.
This section lists the definitions of the iflCoord and various coefficient 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
Two-dimensional | Three-dimensional | Four-dimensional |
|---|---|---|
iflXYchar, iflXYCchar | iflXYZchar, iflXYZCchar | iflXYZCchar, iflXYZCchar |
iflXYint, iflXYCint | iflXYZint, iflXYZCint | iflXYZCint, iflXYZCint |
iflXYfloat, iflXYCfloat | iflXYZfloat, iflXYZCfloat | iflXYZCfloat, |
iflXYdouble, iflXYCdouble | iflXYZdouble, iflXYZCdouble | 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 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.
Table F-2 describes the error messages found in ilStatus.h.
Table F-2. ilStatus Error Codes
Erro Message | Description |
|---|---|
ilOKAY | Successful operation |
ilBADFILEREAD | Error reading from file |
ilBADFILEWRITE | Error writing to file |
ilBADMALLOC | malloc() or new returned NULL |
ilBADIMGFMT | Bad image file format |
ilBADDIMS | Bad dimensions |
ilBADOBJ | Bad object on construction |
ilBADATTR | Bad attributes |
ilFMTUNSUP | Unsupported file format |
ilBADPIXTYPE | Bad pixel type |
ilBADCONFIG | Unsupported configuration |
ilNORANDOMSEEK | Cannot do random seek |
ilBADSEEK | Error seeking on file |
ilBADDECODE | Failure on decompression |
ilREADONLY | Object is not writable |
ilBADFIELDSET | Failed to set field in file header |
ilBADCOMPRESSION | Invalid image compression |
ilNULLOBJ | NULL object passed as parameter |
ilBADINPUT | Invalid input passed |
ilBADCOLFMT | Bad color format |
ilBADOP | Bad operation attempted |
ilBADFILEOPEN | Error opening file |
ilBADMAGIC | Invalid magic number in file |
ilEMPTYFILE | File is empty |
ilDATACLIPPED | Data has been clipped |
ilOUTOFBOUND | Parameter(s) out of bounds |
ilTOOMANYLOCKED | Too many pages locked in image cache |
ilLUTSIZEMISMATCH | Incompatible number of channels in lut and image |
ilZERODIVIDE | Attempted to divide by zero |
ilUNSUPPORTED | Attempted operation is unsupported |
ilUSEDOLDLIMITS | Used old limits for histogram calculation |
ilBADPAGEDIMS | TIFF page dimensions must be multiples of 8 |
ilBADTIFFDIR | Could not index into TIFF directory |
ilNOTRESIDENT | Page is not resident in cache |
ilHWACCELFAIL | Unable to complete hardware accelerated operation |
ilHWACCELNEVER | Unable to complete hardware acceleration operation |
ilPARKED | Request has been parked |
ilUNIMPLEMENTED | Unimplemented |
ilIFL_ERROR | IFL error |
ilFAILED | Operation failed |
ilNOTLOCKED | Unlocked ilLockRequest |
ilBADINPUTSTATUS | Input image has bad status |
ilABORTED | Operation was aborted |
ilAPPROXIMATE | Result is not exact |
Table F-3 describes the error messages found in iflStatus.h.
Table F-3. iflStatus Error Codes
Error Messages | Description |
|---|---|
iflOKAY | Successful operation |
iflREADONLY | Image file is read-only |
iflWRITEONLY | Image file is write-only |
iflBADPARAMS | Bad parameters |
iflUNSUPPORTEDBYLIBRARY | Non-IFL library call. |
iflUNSUPPORTEDBYFORMAT | Unsupported image format |
iflBADMAGIC | Bad magic number, unrecognizable file type |
iflBADIMGFMT | Bad image |
iflBADFIELDSET | Failed to set field in file header |
iflBADFIELDGET | Failed to get field in file header |
iflSYSTEM_CONFIGURATION_ERROR | Configuration error |
iflFILEINDEXOOB | File index out of bounds |
iflMALLOCFAILED | Malloc failed |
iflOPENFAILED | Error in opening file |
iflCLOSEFAILED | Error in closing file |
iflREADFAILED | Error in reading file |
iflWRITEFAILED | Error in writing file |
iflSEEKFAILED | Error seeking on file |
iflSTATFAILED | Error in state |
iflDBOPENFAILED | Failed when opening file format database, ifl_database |
iflSCRIPTFAILED | Script failed |
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 #endif #undef TRUE #define TRUE 1 #undef FALSE #define FALSE 0 |
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;
#endif
/*
* 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;
#endif
;}
|