OpenCV Region of Interest (ROI)

Region of Interest is a rectangular area in an image, to segment object for further processing. The ilustration is shown in Figure 1 below.

Fig 1. An image with Region of Interest defined

In the image above, a Region of Interest is defined at near top left of the image. Once the ROI defined, most OpenCV functions will performed only on that particular location. This is useful, for example when we want to crop an object from an image, or when we want to perform template matching within subimage. Note that the Region of Interest has to be inside the image.
To define Region of Interest, use the function:
cvSetImageROI( IplImage* img, CvRect rect )
Where img is the source image and rect is the area within the source image. To reset Region of Interest, use the function:
cvResetImageROI( IplImage* img )
Below are some samples where ROI is useful.

1. Crop an Object

Listing 1: Crop an object and save to new image

1. /* load image */
2. IplImage *img1 = cvLoadImage("elvita.jpg", 1);
4. /* sets the Region of Interest
5.    Note that the rectangle area has to be __INSIDE__ the image */
6. cvSetImageROI(img1, cvRect(10, 15, 150, 250));
8. /* create destination image
9.    Note that cvGetSize will return the width and the height of ROI */
10. IplImage *img2 = cvCreateImage(cvGetSize(img1),
11.                                img1->depth,
12.                                img1->nChannels);
14. /* copy subimage */
15. cvCopy(img1, img2, NULL);
17. /* always reset the Region of Interest */
18. cvResetImageROI(img1);

2. Adding Two Images with Different Size

Listing 2: Adding two images with different size

1. /* load images
2.    Note that both images have different width & height */
3. IplImage *img1 = cvLoadImage("elvita.jpg", 1);  /* bigger image  */
4. IplImage *img2 = cvLoadImage("fifi.jpg", 1);    /* smaller image */
6. /* define rectangle for ROI */
7. CvRect rect = cvRect(25, 25, img2->width, img2->height);
9. /* sets Region of Interest */
10. cvSetImageROI(img1, rect);
12. /* Add both images
13.    Note that now both images have 'same' width & height */
14. cvAdd(img1, img2, img1, NULL);
16. /* always reset the region of interest */
17. cvResetImageROI(img1);

3. Performing Template Matching in a Specific Area

Listing 3: Template Matching with Region of Interest defined

1. IplImage *img = cvLoadImage("myphoto.jpg", 1);
2. IplImage *tpl = cvLoadImage("eye.jpg", 1);
4. CvRect rect = cvRect(25, 25, 120, 120);
6. cvSetImageROI(img, rect);
8. IplImage *res = cvCreateImage(cvSize(rect.width  - tpl->width  + 1,
9.                                      rect.height - tpl->height + 1),
10.                               IPL_DEPTH_32F, 1);
12. /* perform template matching */
13. cvMatchTemplate(img, tpl, res, CV_TM_SQDIFF);
15. /* find best matches location */
16. CvPoint    minloc, maxloc;
17. double    minval, maxval;
18. cvMinMaxLoc(res, &minval, &maxval, &minloc, &maxloc, 0);
20. /* draw rectangle */
21. cvRectangle(img,
22.             cvPoint(minloc.x, minloc.y),
23.             cvPoint(minloc.x + tpl->width, minloc.y + tpl->height),
24.             CV_RGB(255, 0, 0), 1, 0, 0 );
26. cvResetImageROI(img);

In the example above, we define Region of Interest before performing Template Matching. This will increase the speed since computation only performed on small area. For more information about template matching, read my tutorial about Template Matching in OpenCV.
In this article, I have explained Region of Interest in OpenCV and provided some usage examples. There are many more problems in Image Processing where we find ROI is useful.
The morals:

1. ROI segments object in an image.
2. ROI respected by most of OpenCV functions.
3. Always reset Region of Interest when it is no longer needed. This will saves you from hours of debugging.

Update on October 26, 2009:
Some readers asked me about accessing the image pixels in the ROI. The simplest method would be copying the subimage to another image, then you can access this new image as usual.

Listing 4: Accessing ROI pixels #1

/* assuming that you have 8-bit 3-channels img*/

/* here's the ROI */
CvRect rect = cvRect(10, 20, 50, 60);

/* dst image */
IplImage* subimg;

/* copy ROI to subimg */
cvSetImageROI(img, rect);
cvCopy(img, subimg, NULL);
cvResetImageROI(img);

/* now you have the ROI in subimg. access the pixels as usual */

Or you can access the image directly using the ROI boundaries:

Listing 5: Accessing ROI pixels #2

/* assuming that you have 8-bit 3-channels img*/

/* here's the ROI */
CvRect rect = cvRect(10, 20, 50, 60);

cvSetImageROI(img, rect);

/* say you want to set all pixels in the ROI to 0 */
for (i = rect.y; i < (rect.y + rect.height); i++) {
    for (j = rect.x; j < (rect.x + rect.width); j++) {
        ((uchar*)(img->imageData + i * img->widthStep))[j*3] = 0;
        ((uchar*)(img->imageData + i * img->widthStep))[j*3+1] = 0;
        ((uchar*)(img->imageData + i * img->widthStep))[j*3+2] = 0;
    }
}

cvResetImageROI(img);