Digital

NAME

XieCompare − This routine relationally compares 2 source images, or 1 source image and a constant image, and creates a new image based on the comparison. 

C Format

dst_photo_id = XieCompare(src_id1, src_id2, constant, idc_id, operator, combine)

C Argument Information

XiePhoto    dst_photo_id;
XiePhoto    src_id1;
XiePhoto    src_id2;
unsigned long ∗constant;
XieIdc     idc_id;
unsigned long  operator;
unsigned long  combine;

RETURN VALUES

If the first source image is an unbound photomap, the routine returns the identifier of the newly created photomap in the dst_photo_id argument. Otherwise, the routine returns the identifier of the processing element to which this routine is appended.  You can free the photomap using the XieFreeResource routine. 

PARAMETERS

src_id1The src_id1 argument specifies the first source image.  If the image is an unbound photomap, the operation is performed immediately. Otherwise the routine is appended to the processing element with execution pending a call to the routine. The photoflo is specified explicitly if the source image is a photoflo, or implicitly if the source image is a photomap or a phototap bound to the photoflo. 

src_id2The src_id2 argument specifies the second source image. If you specify a value of 0, the routine uses the constant image you specify for the constant argument as the second source image. If the first source image is a photoflo, the second source image must be bound to the photoflo using the XieBindMapToFlo routine. 

constantThe constant argument specifies the address of an array containing one constant value per component the routine uses to compare with the first source image. If you specify a value that is not 0 for the src_id2 argument, the routine ignores the constant argument. Each point of a component has the value supplied in the corresponding element of the constant image. 

idc_idThe idc_id argument specifies the optional IDC of type CPP or ROI that defines the region of the image or images the routine compares. If you specify a value of 0, the routine performs the comparison across the entire intersection of the 2 source images. 

operatorThe operator argument specifies the comparison operation the routine performs. Only XieK_EQ and XieK_NE are valid for multispectral images. 

combineThe Boolean combine argument specifies whether or not the resulting image, created by comparing 2 multispectral images, has 1 component or multiple components. The routine applies to this argument only when the 2 source images are multispectral. If you specify a value of False, the resulting photomap contains multiple components, each representing the results of comparing like components of the 2 source images.  If you specify a value of True, the routine compares each component for equality, and the results are logically ANDed to obtain a single-component result. If you specified a value of XieK_NE for the operator argument, the routine logically complements the logically ANDed result. 

DESCRIPTION

This routine relationally compares 2 source images, or 1 source image and a constant image, and creates a new image based on the comparison.  The 2 source images must have the same number of components and are assumed to be spatially aligned. If 1 of the source images is unconstrained, the routine first converts the other source image to unconstrained before performing the comparison. 

The resulting image has the same spatial dimensions as those of the first source image. The routine performs the comparison over the region defined by the intersection of the 2 source images and the IDC, if you specify 1. 

The resulting image is always bitonal. If the specified comparison between the 2 pixel values is True, the corresponding output pixel is set to a logical 1. If the comparison is False, the corresponding output pixel is set to a logical 0. Output pixels are also set to a logical 0 if they are located outside the region being compared. 

If the operation is performed immediately and you selected computation events using the XieSelectEvents routine, the routine adds an XieK_ComputationEvent to the X11 event queue when the routine is completed. 

XIE Events and Error Messages

Protocol Messages: X_ieCompare

X_ieQueryResource if the constant array is null

XIE event returned: XieK_ComputationEvent if immediate execution and computation events are selected

XieLib errors: Returns a null if the constant array argument is null and the second source image identifier is invalid

XieServer errors: BadIDChoice -- Invalid identifier

BadAlloc -- Insufficient server resources

BadAccess -- 1 source image is a photoflo and the other is not bound to it

BadValue -- The IDC does not intersect the source images

BadMatch -- The source images do not have the same number of components or the source images are multispectral and the compare operator is not either XieK_EQ or XieK_NE