IG_IP_NR_ROI_to_HIGEAR

This function is a non-rectangular ROI (region on interest) support function whose purpose is to build a non-rectangular ROI mask from a set of segment descriptors that you pass in, and to return a pointer to a non-rectangular ROI mask data structure.

Declaration:

	Copy Code
AT_ERRCOUNT ACCUAPI IG_IP_NR_ROI_to_HIGEAR_mask( AT_MODE nSimpleAreaTypeID, LPVOID lpAreaSegmentDesc, LPAT_NR_ROI_MASK lpNR_ROI );

Arguments:

Name	Type	Description
nSimpleAreaTypeID	AT_MODE	Set to an AT_MODE constant that describes what kind of non-rectangular region of interest (ROI) you will be passing in. See supported AT_MODE constants below.
lpAreaSegmentDesc	LPVOID	Pass in an array of segment descriptors which will be used to reproduce/render the non-rectangular ROI as a mask. These segment descriptors can be points in the case of polygons, points and angles in the case of ellipses and so on. The segment descriptors use image coordinates to describe the mask.
lpNR_ROI	LPAT_NR_ROI_MASK	ImageGear returns you a structure of type AT_NR_ROI_MASK which contains the HIGEAR handle of the new mask HIGEAR and the "reference point" for its placement within HIGEAR.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Supported Raster Image Formats:

This function does not process image pixels.

Example:

	Copy Code
AT_ERRCOUNT nErrcount; HIGEAR hIGear; AT_NR_ROI_MASK region; AT_POINT ROI[]; nErrcount = IG_IP_NR_ROI_to_HIGEAR_mask(IG_ROI_IS_POLYGON, &ROI[0], &region);

Remarks:

This non-rectangular ROI mask data structure (of type AT_NR_ROI_MASK) is then used in conjunction with other API functions to create, associate, modify, and apply the non-rectangular ROI to the source image.

The AT_NR_ROI_MASK structure, shown below, contains two important pieces of information. ptMaskOffset describes the coordinates for reference point for the mask HIGEAR. ptMaskOffset is the (x,y) position in the original HIGEAR at which the upper left corner of the mask HIGEAR should be placed. The mask HIGEAR is actually a rectangle which is calculated by determining the smallest rectangular area that can encompass the entire non-rectangular ROI. We refer to this area as the "bounding rectangle". Within the mask, which represents the bounding rectangle, a pixel value of 1 indicates that the pixel is within the non-rectangular ROI; a pixel value of 0 indicates that the pixel is outside the non-rectangular ROI.

	Copy Code
typedef struct tag AT_NR_ROI_MASK { AT_POINT ptMaskOffet; HIGEAR hMask; } AT_NR_ROI_MASK, FAR* LPAT_NR_ROI_MASK;

The second member of the mask structure is a HIGEAR handle to the actual mask image. The mask HIGEAR is a run length-encoded binary image.

You must also pass this function an argument that specifies whether the region of interest is elliptical, polygonal, or rectangular (the default), using one of the following constants:

IG_ROI_IS_RECTANGLE
IG_ROI_IS_ELLIPSE
IG_ROI_IS_POLYGON

The default ROI type, which is IG_ROI_IS_RECTANGLE means that when this mask is associated with and activated for an image, all affected API should use the AT_RECT argument that is part of their argument list. If nSimpleAreaTypeID is set to IG_ROI_IS_ELLIPSE or IG_ROI_IS_POLYGON, all affected API will override their AT_RECT arguments and instead look for an associated AT_NR_ROI_MASK.

The lpNR_ROI parameter will store the mask HIGEAR information structure when the function return value is IGE_SUCCESS.

Use IG_IP_NR_ROI_mask_associate() function to associate the mask HIGEAR with a HIGEAR image.