You should implement qGetSubTile3D() so that it retrieves an arbitrary tile of data from the source image and puts it into the location indicated by data. The tile is located at position (x, y, z) in the source image and has the size indicated by nx, ny, and nz. The dx, dy, and dz parameters specify the data buffer's origin relative to the image; dnx, dny, and dnz specify the buffer's size. The optional config argument indicates how the data should be configured in the buffer. See “Three-dimensional Functions” for more information about qGetSubTile3D().

This function has a default implementation that returns ilUNSUPPORTED.

Your version of the qSetSubTile3D() function should write the tile of data pointed to by data into the destination image. The arguments for qSetSubTile3D() have analogous meanings to those for qGetSubTile3D(): (x,y,z) and (nx, ny, nz) indicate the desired origin and size of the tile in the destination image; dx, dy, and dz specify the data buffer's origin relative to the image; and dnx, dny, and dnz specify the size of the data buffer. The optional config argument describes the configuration of the tile being passed or written; if it is NULL, assume that the tile's configuration matches that of the destination image. See “Three-dimensional Functions” for more information about qSetSubTile3D().

This function has a default implementation that returns ilUNSUPPORTED.

The default implementation of qCopyTileCfg() copies a tile of data from one image to another. This implementation is not as efficient as possible, since it allocates a temporary buffer for holding the data as it performs the copy and then deletes the buffer when it completes the copy. You might want to override this function to provide a more efficient version.

The default versions of qFillTile3D() and qFillTileRGB() do nothing; you will need to override them if you want their functionality. Your implementations should fill a specified tile with the specified pixel value or color.

Your implementation of qLockPageSet() should set a read-only lock for a set of pages when accessing image data. A pointer to each page in the set is deposited in each corresponding ilLockRequest. As a result, the image data for all of the pages is computed. If all of the requests succeed, ilOKAY is returned. If one or more fail, an error code will be returned and the ilLockRequest structures will contain individual status codes.

This function places the destination of a tile, pointed at by data, at coordinates, x, y, z using the size of the source image defined by dx, dy, dz.

Your class must overwrite qGetTile3D(). Its default function returns ilUNSUPPORTED.

This function allows the source buffer to have a different position and size, specified by dx, dy, dnx, dny, dz, and dnz.

Your class must overwrite qGetTile3D(). Its default function returns ilUNSUPPORTED.

The outOfBound() support functions are provided to help implement the data access functions:

int outOfBound(int x, int y); 
int outOfBound(int x, int y, int z); 

These functions return TRUE if the specified point lies outside the image.

If you implement any of the data access functions, you need to hook them into the reset mechanism, which is described next.

An important virtual function in ilImage that you must be concerned with is reset():

virtual void reset(); // inherited from ilLink

This function is designed to adjust or validate an image's attributes if they have been altered, for example, by applying an operator or by setting an attribute explicitly. This function plays a key role in IL's execution model, which propagates image attribute values down an operator chain. (See “Propagating Image Attributes” for more information on propagating image attributes.)

The reset mechanism is triggered whenever an image is queried about its attributes or when its data is accessed. The query and access functions all call resetCheck() (which is inherited from ilLink) to initiate the reset process. If you implement qGetSubTile3D(), qSetSubTile3D(), qCopyTileCfg(), qFillTile3D(), qFillTileRGB(), qLockPageSet(), qGetTile3D(), qSetTile3D() or any attribute query, you need to call resetCheck() before you do anything else in your versions of these functions. This ensures that correct information about an image's attributes is returned and that image data is always valid before it is read, written, copied, filled, or updated.

The reset() function must be defined by derived classes to perform any necessary reset tasks. For example, the ilMemCacheImg class's version of reset() throws out any existing data in the cache since it is invalid; ilOpImg performs several chores in its reset() function and then calls resetOp(), which needs to be implemented by derived classes to perform more specific reset tasks.

Not every image attribute can be changed; by default, the fill value and the maximum and minimum pixel values are allowed to change. Each ilImage derived class can choose which attributes it allows to be modified by using the setAllowed() function (inherited from ilLink), typically in the constructor:

setAllowed(ilIPcolorModel|ilIPorientation);

The argument passed to setAllowed() is a mask composed of a logical combination of the enumerated type, ilImgParam, which is defined in the header file il/ilImage.h. The ilImgParam constants defined in IL are listed in Table 6-2. Each image attribute listed in the table is described elsewhere in this guide. Derived classes can add members to this structure to trace whether particular parameter values have changed and to control whether they can be explicitly modified.

An image can explicitly disallow any of these attributes to be modified. For this, it uses the clearAllowed() function (from ilLink) and passes in a logical combination of the ilImgParam parameters that should be disallowed.

Another function, isAllowed() (inherited from ilLink), checks whether a particular attribute can be modified:

canChange = myImg.isAllowed(ilIPsize);

This function takes the same sort of argument as clearAllowed() and returns TRUE if the attributes specified are not allowed to be modified.

When an attribute's value is changed by the user (by calling the appropriate attribute setting function), setAltered() (from ilLink) should be called to set a flag indicating that a reset is needed. Thus, you must call setAltered() within any attribute setting functions you define. This function takes a mask of ilImgParam parameters as an argument and sets the altered flags for the specified attributes.

You can check whether any particular attributes have been altered with isAltered() (inherited from ilLink). This function takes an ilImgParam mask as an argument and returns TRUE if any of the specified attributes have been altered.

As explained in “Propagating Image Attributes”, IL programs need to keep track of attributes that have been explicitly set by the user so that they remain fixed during the reset process. To keep track of these attributes, you should call markSet() (inherited from ilLink) with an ilImgParam mask as an argument. This function marks the specified attributes with a stuck flag (yet another item inherited from the ilLink class), which indicates that their values should not be changed during a reset operation. markSet() is invoked automatically for you when setAltered() is called, so generally you do not need to call markSet() yourself.

You can determine whether any attributes are fixed with isSet() (inherited from ilLink). This function returns TRUE if any of the attributes specified in the mask passed in have been explicitly set.

Sometimes within a derived class's implementation, you may want to change an attribute's value without triggering the reset mechanism and without causing the value to become fixed. You have already seen one situation where you want to do this: within a constructor, when attributes are being initialized. Another case is when you are computing attribute values during the reset operation itself. In these situations, you do not use a attribute setting function since it calls setAltered(), which in turn calls markSet(). Since derived classes have access to protected data members, simply set the value of the desired attribute directly:

dtype = iflFloat;     // changes value; no flag set

The initMinMax(), initColorModel(), and setStatus() functions described earlier in this section all set attributes directly.

It is quite easy to add attributes to a newly derived class. You can use the header files for the already existing IL classes for examples. This an example is from the il/ilOpImg.h header file:

enum ilOpImgParam {
  ilIPbias = ilImgParamLast<<1,
  ilIPclamp = ilImgParamLast<<2,
  ilIPworkingType = ilImgParamLast<<3,
  ilOpImgParamLast = ilIPworkingType
};

The pattern is simple. Suppose you were to derive a new class from ilOpImg and add parameters to it. You might do the following:

enum ilMyClassParam {
  ilIPparam1 = ilOpImgParamLast<<1,
  ilIPparam2 = ilOpImgParamLast<<2,
  ilIPparam5 = ilOpImgParamLast<<5,
  ilMyClassParamLast = ilIPparam5
};

The constructor takes a pointer to the source ilImage(s) and additional arguments as needed to provide parameters to control the operator's processing algorithm (for example, param1). If you do use additional parameters, you might want to define corresponding functions that allow the user to alter and retrieve the value of those parameters (such as setParam1() and getParam1()). These functions should probably take advantage of IL's reset mechanism by calling setAltered() and resetCheck(), respectively. (See “The reset() Function” for more information about how IL's reset mechanism works.) Example 6-2 shows you what a simple constructor might look like.

myOperator::myOperator(ilImage* img=NULL, float param1=Param1Default) 
{
    setValidType(iflFloat|iflDouble);
    setValidOrder(iflInterleaved|iflSequential|iflSeparate);
    setWorkingType(iflDouble);
    setNumInputs(1);
    setInput(img);
    setParam1(param1);
}

In this example, myOperator can produce output of either iflFloat or iflDouble data type; the output has the same pixel ordering as the input image. Input image data that is of type iflFloat is cast to iflDouble before it is processed; this is the meaning of an operator's working type. Some operators can handle multiple inputs, but the setNumInputs() function is used here to limit myOperator to one input. The setInput() function sets the input to be the ilImage passed in; this step chains myOperator to the input image. Finally, param1's value is initialized.

The setValidType(), setValidOrder(), and setWorkingType() functions are all defined as protected in ilOpImg. They are discussed in more detail in ilOpImg's reference page. The ilImage class defines setNumInputs() (protected) and setInput().

The constructor should not contain any calculations that are based on the value of arguments passed in, since these arguments might change. Most operators that require arguments other than the input image in their constructors define functions for dynamically changing the value of those arguments (like setParam1()). Such calculations should be done in the resetOp() function described below. The resetOp() function is declared in ilOpImg, but its implementation is left to derived operators. Note that when any ilImage is created, it is considered “altered,” so resetOp() is always called before any data is computed.

Since resetOp() is guaranteed to be called before prepareRequest(), executeRequest(), and finishRequest(), it can—and should—be used to calculate the values of variables needed by these methods, particularly if those variables depend on arguments passed in the operator's constructor. The resetOp() function also needs to reset any image attributes that change as a result of the image's data being processed, so that the proper attribute values can be propagated down an operator chain. As an example, imagine an operator that defined the following variables (probably as protected) in its header file (ilMonadicImg defines these variables):

iflXYZCint str;         // output (page) buffer strides
iflXYZCint istr;        // input image strides
int bufferSize;        // size of input buffer in bytes
int cBuffSize;         // number of channels in input buffer

As you might expect, these variables are used to determine the size of the internal buffer needed for reading in the image's data that is to be processed. This buffer is actually allocated in prepareRequest(), but the values for these variables are calculated in resetOp(), since they depend on the input image's page size and data type attributes. Example 6-3 illustrates this with ilMonadicImg's implementation of resetOp(). (The iflXYZCint struct holds four integers, one for each of an image's dimensions; see “Convenient Structures” for more information.)

ilMonadicImg::resetOp()
{
    // make sure we have a valid input
    ilImage* img = getInput();
    if (img==NULL || getOrder() == iflSeparate && getCsize() != img->getCsize())
        { setStatus(ilStatusEncode(ilBADINPUT)); return; }

    // make sure page size info is in sync with color model/number channels
    checkColorModel();

    // determine whether or not we can use lockPage on our input
    int cps, icps;
    iflXYZint pgSize, pgDel, ipgSize, ipgDel;
    getPageSize(pgSize.x, pgSize.y, pgSize.z, cps);
    getPageDelta(pgDel.x, pgDel.y, pgDel.z, cps);
    img->getPageSize(ipgSize.x, ipgSize.y, ipgSize.z, icps);
    img->getPageDelta(ipgDel.x, ipgDel.y, ipgDel.z, icps);
    iflOrder inord = img->getOrder();
    usesIstr = 0; // XXX not supported yet
    useLock = !inPlace && (usesIstr || pgSize == ipgSize && pgDel == ipgDel) &&
              (cps == icps || cps == size.c && icps == img->getCsize()) && 
              img->getDataType() == wType && 
              img->getOrientation() == orientation &&
              (order == inord || 
               usesIstr && (order == iflSeparate) == (inord == iflSeparate));

    // get buffer strides
    getStrides(str.x, str.y, str.z, str.c);
    if (useLock) 
        img->getStrides(istr.x, istr.y, istr.z, istr.c);
    else 
        img->getStrides(istr.x, istr.y, istr.z, istr.c, 
                        pgSize.x, pgSize.y, pgSize.z, icps, getOrder());
}

As shown, the resetOp() function performs three tasks:

The size of the internal buffer depends on the operator's working data type, on its page size, and on the input image's channel stride. Note that for this operator, the input and output buffers are the same size. (All the functions used in this example are described in Chapter 2, “The ImageVision Library Foundation,” except for iflDataSize(), which is described in the reference pages.) In this example, none of the image's attributes change as a result of this operator's image processing algorithm. An example of an operator that does change attributes is ilRotZoomImg, which changes the image's size, unless the user has explicitly specified a desired size:

if (!isSet(ilIPsize)) {
    // calculate newXsize and newYsize
    size.x = newXsize;
    size.y = newYsize;
}

Notice that the attributes are set directly; the setSize() function is not used since it would flag the size attribute as having been altered. You can use isDiff() to determine whether any parameters changed as a result of propagation. This function takes a mask of ilImgParam values and returns TRUE if any of the specified attributes changed.

When keepPrecision() is enabled, the data type of an operator's input is maintained. If it is not enabled, the data type of the operator's input is translated into the smallest possible data type. If you disable this function, it is possible that non-integral operator input, such as float, will be cast into an integral data type, such as char. For example, if keepPrecision() is disabled, and the operator's input is really float values in the range of 0.0 and 1.0, the operator will change the data type of the range to char.

keepPrecision() is enabled by default.

To determine whether or not an operator maintains non-integral data types, use the isPrecisionKept() function.

In your derived operator, you must override the prepareRequest() method so that it

There are two ways to read the image data into a buffer:

If the page size of the stored, input image matches that of the output image, and the operator can use the data type of the stored, input image directly, you can use qLockPageSet() to directly fill the buffer. qLockPageSet() returns a pointer to the page of the input image in cache. The advantage of using qLockPageSet() is that it avoids copying the image data.

If you cannot use qLockPageSet(), you use the asynchronous methods qGetTile3D() or qGetSubTile3D() to fill the buffer. These methods get a tile, change the data type, allocate the buffer, and fill it.

---

Note: Do not use the synchronous versions of these methods, GetTile3D() and GetSubTile3D() in the prepareRequest phase.

---

You only use qGetSubTile3D() if the page of image data to be operated on extends beyond the boundary of the image, as shown in Figure 6-3.

Figure 6-3. Using qgetSubTile3D()

Each rectangle in the figure represents a page of image data. The pages on the right-side border spill beyond the image boundary. Loading the part of the page that lies outside of the image boundary is unnecessary and time consuming. Rather than loading the entire page, you use qGetSubTile3D() to load only that portion of the page that lies within the image boundary.

Whether you use qLockPageSet() or qGetSubTile3D() to read in the data, you pass them the cache request mentioned in the argument of prepareRequest() as the parent, for example:

ilMonadicImg::prepareRequest(ilMpCacheRequest* req)
...
ilMpMonadicRequest* r = (ilMpMonadicRequest*)req;
...
sts = im->qGetSubTile3D(r, r->x, r->y, r->z, r->nx, r->ny, r->nz,
                                r->in, r->x, r->y, r->z, 
                                pageSize.x, pageSize.y, pageSize.z,                                 &cfg);

You override the ilOpImg::executeRequest() method to perform the image operation on the loaded image data. If, for example, you were writing a new sharpen operator, the executeRequest() method would implement the sharpening of the image data.

You override the ilOpImg::finishRequest() method to deallocate the buffer space used by the image data and to unlock any pages locked (set by qLockPageSet()) in the prepareRequest() method. You enter the finishRequest phase either because the executeRequest() method completes or because the operation was aborted.

Image Processing Example

Example 6-4 shows what a request-processing implementation might look like under this model.

ilStatus
ilMonadicImg::prepareRequest(ilMpCacheRequest* req)
{
    // do not proceed if things look bad
    if (status != ilOKAY) return status;

    // get the input image to read data from
    ilImage* im = getInput(0);
    assert(im != NULL);

    ilMpMonadicRequest* r = (ilMpMonadicRequest*)req;

    // queue request for the input data, either lockPage or getTile
    ilStatus sts;
    if (useLock) {
        // doing lockPage, the page in the input image is the input buffer
        r->lck.init(r->x, r->y, r->z, r->c);
        sts = im->qLockPageSet(r, &r->lck);
    }
    else {
        // doing getTile: if in place use our own page as destination, otherwise
        //                allocate an input buffer
        int nc = im->getCsize();
        if (order == iflSeparate && nc == getCsize()) nc = getPageSizeC();
        ilConfig cfg(wType, order, nc, NULL, r->c, getOrientation());
        if (inPlace) r->in = r->getData();
        sts = im->qGetSubTile3D(r, r->x, r->y, r->z, r->nx, r->ny, r->nz,
                                r->in, r->x, r->y, r->z, 
                                pageSize.x, pageSize.y, pageSize.z, &cfg);
    }

    return sts;
}

ilStatus
ilMonadicImg::executeRequest(ilMpCacheRequest* req)
{
    // do not proceed if things look bad
    if (status != ilOKAY) return status;

    ilMpMonadicRequest* r = (ilMpMonadicRequest*)req;

    // find the input buffer, 
    void* src;
    if (useLock) {
        // doing lock page, input page is the input buffer
        if (!r->lck.isLocked()) return r->lck.getStatus();
        src = r->lck.getData();
    }
    else
        // normal getTile, data was read into allocated buffer (or in place)
        src = r->in;

    // let the real operator code in derived class do it is thing
    return calcPage(src, r->getData(), *r);
}

ilStatus
ilMonadicImg::finishRequest(ilMpCacheRequest* req)
{
    ilMpMonadicRequest* r = (ilMpMonadicRequest*)req;

    // free up any allocations or locks
    
    if (r->in && !inPlace) {
        // junk the input buffer
        delete r->in;
    }
    else if (r->lck.getPage() != NULL) {
        // unlock the page
        ilImage* im = getInput(0);
        assert(im != NULL);
        im->unlockPageSet(&r->lck);
    }
        
    return ilOKAY;
}

The calcPage() function implements the image processing algorithm, taking care to handle each valid data type appropriately. For example, Example 6-5 shows how ilAddImg computes the pixelwise sum of two images.

#define doAdd(type) \
if (1) { \
    type tb = type(bias); \
    if (numIn == 2) { \
        void *ib0 = ib[0], *ib1 = ib[1]; \
        for (; idx < lim; idx += sx) \
            ((type*)ob)[idx] = ((type*)ib0)[idx]+((type*)ib1)[idx] + tb; \
    } else \
        for (; idx < lim; idx += sx) { \
            type sum = tb; \
            for (int in=0; in < numIn; in++) \
                sum += ((type*)ib[in])[idx]; \
            ((type*)ob)[idx] = sum; \
        } \
} else


ilStatus
ilAddImg::calcPage(void** ib, int numIn, void* ob, ilMpCacheRequest& req)
{
    // for interleaved case: combine x/c loops to improve performance
    int nc = req.nc, sc = str.c, nx = req.nx, sx = str.x;
    if (sc == 1 && sx == nc) { nx *= nc; nc = 1; sx = 1; sc = 0; }

    for (int z = 0; z < req.nz; z++) {
        for (int y = 0; y < req.ny; y++) {
            for (int c = 0; c < nc; c++) {
                int idx = z*str.z + y*str.y + c*sc, lim = idx + nx*sx;
                switch (dtype) {
                    case iflUChar:   doAdd(u_char); break;
                    case iflUShort:  doAdd(u_short); break;
                    case iflShort:   doAdd(short); break;
                    case iflLong:    doAdd(long); break;
                    case iflFloat:   doAdd(float); break;
                    case iflDouble:  doAdd(double); break;
                }
            }
        }
    }

    return ilOKAY;
}

Since ilAddImg is derived from ilPolyadicImg, this function uses ilPolyadicImg's stride data members—str.x, str.y, str.z, and str.c—to step through the data.

Because IL programs can be multi-threaded, the prepareRequest(), executeRequest(), finishRequest(), and calcPage() functions should not alter any member variables or do anything else that would make the algorithm non-reentrant. For example, the input buffer used by prepareRequest() is allocated locally and stored as a member of the request, rather than as a member in resetOp() so that concurrent execution of prepareRequest() uses unique buffers for the different portions of the input image at the same time.

Some operators might trigger overflow or underflow conditions as they process data. To solve this potential problem, you should set clamp values that will then be used automatically when overflow or underflow arises, as described below.

In your implementation of resetOp(), call setClamp():

void setClamp(iflDataType type = numilTypes); 
void setClamp(double min, double max);

This function sets the values that pixels will be clamped to if underflow or overflow occurs. The first version sets the clamp values to be the minimum and maximum values allowed for the data type type; the default value of numilTypes means to use the operator's current data type. The second version allows you to specify actual clamp values.

In the calcPage() function, use the initClamp() macro, passing in the operator's data type (for example, int or float). This macro initializes two temporary variables to hold the minimum and maximum clamp values. Then, after you process each pixel of data, call the clamp() macro and pass in the processed pixel value. This function clamps the pixel value, if necessary, to the minimum or maximum clamp value.

To allow a user to set clamp values, you need to add ilIPclamp to the ilImgParam mask passed to setAllowed() in the constructor.

Another problem that might arise as a result of processing data is that the processed values might exceed the range of values. For example, if you multiply two images (the pixel values of which fall in the 0 to 255 range) and then display the result, you might end up with pixel data that appears to be invalid if the pixel values exceed 255. To solve this potential problem, operators that alter the data range of their inputs need to set the minValue and maxValue data members (inherited from ilImage) to ensure that the processed data can be displayed. When the data is displayed using ilDisplay, it is automatically scaled between these values so that a meaningful display is produced.

Here is how ilAddImg computes minValue and maxValue in its resetOp() function (ilAddImg performs pixelwise addition on two images; a user-specified bias value can also be added to each pixel of the output):

// compute worst case min/max values
double min = getInputMin(0) + getInputMin(1);
double max = getInputMax(0) + getInputMax(1);
setStatus(checkMinMax(min+bias, max+bias));

The getInputMin() and getInputMax() functions return the minimum and maximum pixel value attributes of the input image. The argument for these functions is the index of the desired image in the list of inputs (the first input is at index 0). These values are added (since that is what ilAddImg does), combined with the bias value, and then passed to checkMinMax(). This function first attempts to set the operator's data type to the smallest supported data type that can hold the range specified by its arguments. If the data type is explicitly set by the user, however, it will not be changed. Then, if minValue and maxValue are not explicitly set, they are set to the values passed to checkMinMax(). If checkMinMax() returns ilUNSUPPORTED, it is not able to change the data type to support the range; in this case, minValue and maxValue are set to the maximum range of the current data type.

As an abstract class, ilArithLutImg defines how to use look-up tables when performing arithmetic or radiometric operations. To derive from it, you implement your algorithm in calcRow() rather than in calcPage():

void calcRow(iflDataType intype, void *inBuf, void *outBuf, 
              int sx, int lim, int idx);

The intype parameter indicates the input image's data type. The next two arguments are the input buffer of data that needs to be processed and the output buffer into which processed data should be written. The next three arguments specify how to step through the data: sx is the x stride of the output buffer, lim is the maximum x stride, and idx is the starting index. The calcRow() function contains the algorithm for processing one row of input data. For efficiency, you can use the defined macro doRow() to obtain the proper data type and feed it to the macro doCalc(). (The doRow() macro is defined in ilArithLutImg's header file.) If you use these macros, your calcRow() definition would be just a call to doRow():

ilMyOpImg::calcRow(iflDataType inType, void* inBuf, 
               void* outBuf,int sx, int lim, int idx)
{ doRow(); }

and you would actually implement the computation algorithm in the macro doCalc(), as ilPowerImg does, for example, as shown in Example 6-6.

#define ilArithDoCalc(outype, intype) \
if (1) { \
    if (inType == iflDouble || dtype == iflDouble)  { \
        for (; x < lim; x += sx) \
            ((outype*)outBuf)[x] = \
                (outype)pow((double)((intype*)inBuf)[x]*scale+bias, power); \
    } \
    else { \
        for (; x < lim; x += sx) \
            ((outype*)outBuf)[x] = \
                (outype)powf((double)((intype*)inBuf)[x]*scale+bias, power); \
    } \
} else

You also need to implement loadLut() to compute and load the appropriate values into the LUT. Example 6-7 shows ilPowerImg's version of loadLut().

void
ilPowerImg::loadLut()
{
    double low, high;
    lut->getDomain(low,high);
    double dstep = lut->getDomainStep();
    double lim = high+dstep/2;
    for (double i = low; i < lim; i += dstep)
        lut->setVal(pow(i*scale + bias, power), i);
}

For your convenience, ilArithLutImg has functions for scaling and biasing the input data before the LUT is applied:

void setScale(double scale);
double getScale();
void setBias(double bias);
double getBias();

The ilHistLutImg class provides support for operators that compute a look-up table from the histogram of the source image and then apply this table to the source image. It derives from ilArithLutImg and implements its own versions of calcPage(), calcRow(), and loadLut(). The only pure virtual function in ilHistLutImg is calcBreakpoints(), which all derived classes must implement:

virtual ilStatus calcBreakpoints(ilImage *src, ilImgStat *imgstat, 
    double **brPoints) = 0;

This function computes the breakpoints (brPoints) of a piecewise LUT. You can think of it as a pointer to a two-dimensional array whose members can be accessed by

double val = brPoints[i][j] where:
    i = 0,1,2,...,nc-1 
    j = 0,1,2,...,nbinsi 
    nc = number of channels in the source image
    nbinsi = number of bins in the histogram of channel i 

You can obtain the number of bins by using imgstat's getNbins() function. The variable val in the example shown above represents what the pixel intensity represented by the jth bin of the histogram for channel i maps to. For example, to invert pixel intensities of an image containing unsigned char data, you can use

brPoints[i][j] = 255-j;

All the members of brPoints need to be evaluated in calcBreakpoints(), using both the source image and a pointer to its associated data as inputs. Derived classes do not need to allocate and manage memory for brPoints, since ilHistImg does this for them. In addition, ilHistImg provides convenience functions for setting the ilImgStat and ilRoi objects:

void setImgStat(ilImgStat *imgstat);
void setRoi(ilRoi *roi, int xoffset=0, int yoffset=0);

If you implement resetOp() in a derived class, be sure to explicitly call ilHistLutImg's version of resetOp().

An example of a class derived from ilHistLutImg might be an operator called ilPixelCountImg, which replaces each pixel intensity by the number of times it occurs in that particular channel. Such an operator might be implemented as shown in Example 6-8.

class ilPixelCountImg:public ilHistLutImg {
    private: 
        ilStatus calcBreakpoints (ilImage *src, 
               ilImgStat *imgstat, double **brPoints);
    public: 
        ilPixelCountImg(ilImage *src);
}
ilPixelCountImg::ilPixelCountImg(ilImage *src)
:ilHistLutImg(src)
{
}
ilStatus calcBreakpoints (ilImage *src, ilImgStat *imgstat, 
        double **brPoints)
{
    if (src==NULL) return ilBADINPUT;
    int nch=src->getNumChans();
    for (int i=0; i<nch ; i++) {
        int *hist = imgstat->getHist(i);
        int nbins = imgstat->getNbins(i);
        int total = imgstat->getTotal(i);
        double max = src->getMaxValue(i);
        for (int j=0; j<nbins; j++) {
            brPoints[i][j]=(hist[j]*max)/total;
        }
    }
    return ilOKAY;
}

The ilConvImg class performs general convolution on an image, and the ilSepConvImg class performs separable convolution. You might want to derive from these classes if kernel values are not available at the time the operator is constructed because they depend on certain input parameters. In this case, you would define a resetOp() function in the derived class that computes the x and y kernel values from input parameters. Then you could use the inherited functions setXKernel(), setYKernel(), and setKernelSize() to specify the kernel and its size, after which you would need to explicitly call ilConvImg's or ilSepConvImg's version of resetOp(). Remember that the kernel for ilConvImg should be a two-dimensional matrix, while that for ilSepConvImg should be two separate vectors. You should also set the edge mode and bias value.

The ilWarp class encapsulates general 3D coordinate transformations for use by ilWarpImg and its subclasses. A particular warp is defined by overriding the x(), y(), and z() virtual functions:

virtual float x(float u, float v=0,float w=0);
virtual float y(float u, float v=0, float w=0);
virtual float z(float u, float v=0, float w=0);

The x() function evaluates the x component of the warp function at a point. The default implementation is to return u.

The y() virtual function evaluates the y component of the warp function at a point. The default implementation is to return v.

The z() virtual function evaluates the y component of the warp function at a point. The default implementation is to return w.

Any derived warp class that transforms any of the x, y, or z components should overwrite the corresponding virtual function.