ClassesClassesClassesClasses | | | | Operators

rank_rectrank_rectRankRectrank_rectRankRectRankRect (Operator)

Name

rank_rectrank_rectRankRectrank_rectRankRectRankRect — Compute a rank filter with rectangular masks.

Signature

rank_rect(Image : ImageRank : MaskWidth, MaskHeight, Rank : )

Herror rank_rect(const Hobject Image, Hobject* ImageRank, const Hlong MaskWidth, const Hlong MaskHeight, const Hlong Rank)

Herror T_rank_rect(const Hobject Image, Hobject* ImageRank, const Htuple MaskWidth, const Htuple MaskHeight, const Htuple Rank)

Herror rank_rect(Hobject Image, Hobject* ImageRank, const HTuple& MaskWidth, const HTuple& MaskHeight, const HTuple& Rank)

HImage HImage::RankRect(const HTuple& MaskWidth, const HTuple& MaskHeight, const HTuple& Rank) const

HImageArray HImageArray::RankRect(const HTuple& MaskWidth, const HTuple& MaskHeight, const HTuple& Rank) const

void RankRect(const HObject& Image, HObject* ImageRank, const HTuple& MaskWidth, const HTuple& MaskHeight, const HTuple& Rank)

HImage HImage::RankRect(Hlong MaskWidth, Hlong MaskHeight, Hlong Rank) const

void HOperatorSetX.RankRect(
[in] IHUntypedObjectX* Image, [out] IHUntypedObjectX*ImageRank, [in] VARIANT MaskWidth, [in] VARIANT MaskHeight, [in] VARIANT Rank)

IHImageX* HImageX.RankRect(
[in] Hlong MaskWidth, [in] Hlong MaskHeight, [in] Hlong Rank)

static void HOperatorSet.RankRect(HObject image, out HObject imageRank, HTuple maskWidth, HTuple maskHeight, HTuple rank)

HImage HImage.RankRect(int maskWidth, int maskHeight, int rank)

Description

rank_rectrank_rectRankRectrank_rectRankRectRankRect performs a rank filter on the input image ImageImageImageImageImageimage with a rectangular mask of size MaskWidthMaskWidthMaskWidthMaskWidthMaskWidthmaskWidth × MaskHeightMaskHeightMaskHeightMaskHeightMaskHeightmaskHeight and returns the filtered image in ImageRankImageRankImageRankImageRankImageRankimageRank.

Conceptually, the rank filter sorts all gray values within the mask in ascending order and then selects the gray value with rank RankRankRankRankRankrank. The rank 1 corresponds to the smallest gray value and the rank MaskWidthMaskWidthMaskWidthMaskWidthMaskWidthmaskWidth * MaskHeightMaskHeightMaskHeightMaskHeightMaskHeightmaskHeight corresponds to the largest gray value within the mask. For RankRankRankRankRankrank = (MaskWidthMaskWidthMaskWidthMaskWidthMaskWidthmaskWidth * MaskHeightMaskHeightMaskHeightMaskHeightMaskHeightmaskHeight - 1) / 2 + 1, rank_rectrank_rectRankRectrank_rectRankRectRankRect returns the median gray value (see median_rectmedian_rectMedianRectmedian_rectMedianRectMedianRect). For RankRankRankRankRankrank = 1, rank_rectrank_rectRankRectrank_rectRankRectRankRect performs a gray value erosion (see gray_erosion_rectgray_erosion_rectGrayErosionRectgray_erosion_rectGrayErosionRectGrayErosionRect, gray_erosion_shapegray_erosion_shapeGrayErosionShapegray_erosion_shapeGrayErosionShapeGrayErosionShape, and gray_erosiongray_erosionGrayErosiongray_erosionGrayErosionGrayErosion), while for RankRankRankRankRankrank = MaskWidthMaskWidthMaskWidthMaskWidthMaskWidthmaskWidth * MaskHeightMaskHeightMaskHeightMaskHeightMaskHeightmaskHeight rank_rectrank_rectRankRectrank_rectRankRectRankRect performs a gray value dilation (see gray_dilation_rectgray_dilation_rectGrayDilationRectgray_dilation_rectGrayDilationRectGrayDilationRect, gray_dilation_shapegray_dilation_shapeGrayDilationShapegray_dilation_shapeGrayDilationShapeGrayDilationShape, and gray_dilationgray_dilationGrayDilationgray_dilationGrayDilationGrayDilation).

rank_rectrank_rectRankRectrank_rectRankRectRankRect can be used, for example, to suppress noise or to suppress unwanted objects that are smaller than the mask. Furthermore, rank_rectrank_rectRankRectrank_rectRankRectRankRect is less sensitive to noise than the correponding gray value morphology operators. Therefore, to obtain a more robust version of the gray value morphology, instead of using 1 or MaskWidthMaskWidthMaskWidthMaskWidthMaskWidthmaskWidth * MaskHeightMaskHeightMaskHeightMaskHeightMaskHeightmaskHeight, slightly larger or smaller values should be selected for RankRankRankRankRankrank.

Attention

If even values instead of odd values are passed in MaskHeightMaskHeightMaskHeightMaskHeightMaskHeightmaskHeight or MaskWidthMaskWidthMaskWidthMaskWidthMaskWidthmaskWidth, rank_rectrank_rectRankRectrank_rectRankRectRankRect uses the next larger odd values instead.

rank_rectrank_rectRankRectrank_rectRankRectRankRect uses an algorithm with constant runtime per pixel, i.e., the runtime only depends on the size of the input image and not on the mask size. Therefore, for large mask sizes rank_rectrank_rectRankRectrank_rectRankRectRankRect is the fastest implementation of the rank filter in HALCON. Depending on the computer architecture (processor type, availability of SIMD instructions like SSE2 or MMX, cache size and throughput, memory throughput), for small mask sizes the implementation used in rank_imagerank_imageRankImagerank_imageRankImageRankImage is faster than rank_rectrank_rectRankRectrank_rectRankRectRankRect. Typically, this is the case for MaskHeightMaskHeightMaskHeightMaskHeightMaskHeightmaskHeight <= 15, but can also happen for larger mask sizes, e.g., if SIMD instructions are unavailable and memory throughput is low.

Furthermore, it should be noted that rank_rectrank_rectRankRectrank_rectRankRectRankRect uses a recursive implementation, which internally computes the filter response on the smallest enclosing rectangle of the domain of the input image. Therefore, if the domain of the input image only covers a small fraction of the smallest enclosing rectangle, it can happen that rank_imagerank_imageRankImagerank_imageRankImageRankImage is faster than rank_rectrank_rectRankRectrank_rectRankRectRankRect even for larger values of MaskHeightMaskHeightMaskHeightMaskHeightMaskHeightmaskHeight.

rank_rectrank_rectRankRectrank_rectRankRectRankRect should neither be used with RankRankRankRankRankrank = 1 to perform a gray value erosion nor with RankRankRankRankRankrank = MaskWidthMaskWidthMaskWidthMaskWidthMaskWidthmaskWidth * MaskHeightMaskHeightMaskHeightMaskHeightMaskHeightmaskHeight to perform a gray value dilation. In these cases, the operators gray_erosion_rectgray_erosion_rectGrayErosionRectgray_erosion_rectGrayErosionRectGrayErosionRect or gray_erosion_shapegray_erosion_shapeGrayErosionShapegray_erosion_shapeGrayErosionShapeGrayErosionShape and gray_dilation_rectgray_dilation_rectGrayDilationRectgray_dilation_rectGrayDilationRectGrayDilationRect or gray_dilation_shapegray_dilation_shapeGrayDilationShapegray_dilation_shapeGrayDilationShapeGrayDilationShape, respectively, are faster than rank_rectrank_rectRankRectrank_rectRankRectRankRect for almost all mask sizes.

Parallelization

Parameters

ImageImageImageImageImageimage (input_object)  (multichannel-)image(-array) objectHImageHImageHImageHImageXHobject (byte)

Image to be filtered.

ImageRankImageRankImageRankImageRankImageRankimageRank (output_object)  (multichannel-)image(-array) objectHImageHImageHImageHImageXHobject * (byte)

Filtered image.

MaskWidthMaskWidthMaskWidthMaskWidthMaskWidthmaskWidth (input_control)  integer HTupleHTupleHTupleVARIANTHtuple (integer) (int / long) (Hlong) (Hlong) (Hlong) (Hlong)

Width of the filter mask.

Default value: 15

Suggested values: 3, 5, 7, 9, 11, 13, 15, 17, 19, 21, 31, 49, 51, 61, 71, 81, 91, 101

Typical range of values: 3 ≤ MaskWidth MaskWidth MaskWidth MaskWidth MaskWidth maskWidth ≤ 4095

Minimum increment: 2

Recommended increment: 2

MaskHeightMaskHeightMaskHeightMaskHeightMaskHeightmaskHeight (input_control)  integer HTupleHTupleHTupleVARIANTHtuple (integer) (int / long) (Hlong) (Hlong) (Hlong) (Hlong)

Height of the filter mask.

Default value: 15

Suggested values: 3, 5, 7, 9, 11, 13, 15, 17, 19, 21, 31, 49, 51, 61, 71, 81, 91, 101

Typical range of values: 3 ≤ MaskHeight MaskHeight MaskHeight MaskHeight MaskHeight maskHeight ≤ 4095

Minimum increment: 2

Recommended increment: 2

RankRankRankRankRankrank (input_control)  integer HTupleHTupleHTupleVARIANTHtuple (integer) (int / long) (Hlong) (Hlong) (Hlong) (Hlong)

Rank of the output gray value.

Default value: 5

Suggested values: 3, 5, 7, 9, 11, 13, 15, 17, 19, 21, 31, 49, 51, 61, 71, 81, 91, 101

Minimum increment: 1

Recommended increment: 2

Restriction: 1 <= Rank && Rank <= MaskWidth * MaskHeight

Complexity

For each pixel: O(1).

Result

If the parameter values are correct the operator rank_rectrank_rectRankRectrank_rectRankRectRankRect returns the value 2 (H_MSG_TRUE). The behavior in case of empty input (no input images available) is set via set_system('no_object_result',<Result>)set_system("no_object_result",<Result>)SetSystem("no_object_result",<Result>)set_system("no_object_result",<Result>)SetSystem("no_object_result",<Result>)SetSystem("no_object_result",<Result>). If necessary, an exception is raised.

Possible Predecessors

read_imageread_imageReadImageread_imageReadImageReadImage

Possible Successors

thresholdthresholdThresholdthresholdThresholdThreshold, dyn_thresholddyn_thresholdDynThresholddyn_thresholdDynThresholdDynThreshold, regiongrowingregiongrowingRegiongrowingregiongrowingRegiongrowingRegiongrowing

Alternatives

rank_imagerank_imageRankImagerank_imageRankImageRankImage, median_rectmedian_rectMedianRectmedian_rectMedianRectMedianRect, median_imagemedian_imageMedianImagemedian_imageMedianImageMedianImage

See also

gray_erosion_rectgray_erosion_rectGrayErosionRectgray_erosion_rectGrayErosionRectGrayErosionRect, gray_dilation_rectgray_dilation_rectGrayDilationRectgray_dilation_rectGrayDilationRectGrayDilationRect, gray_erosion_shapegray_erosion_shapeGrayErosionShapegray_erosion_shapeGrayErosionShapeGrayErosionShape, gray_dilation_shapegray_dilation_shapeGrayDilationShapegray_dilation_shapeGrayDilationShapeGrayDilationShape, gray_erosiongray_erosionGrayErosiongray_erosionGrayErosionGrayErosion, gray_dilationgray_dilationGrayDilationgray_dilationGrayDilationGrayDilation

References

S. Perreault, P. Hébert; “Median Filtering in Constant Time”; IEEE Transactions on Image Processing, vol. 16, no. 9, pp. 2389-2394, 2007.
D. Cline, K.B. White, P.K. Egbert; “Fast 8-Bit Median Filtering Based On Separability”; International Conference on Image Processing, vol. V, pp. 281-284, 2007.

Module

Foundation


ClassesClassesClassesClasses | | | | Operators