ClassesClassesClassesClasses | | | | Operators

rank_imagerank_imageRankImagerank_imageRankImageRankImage (Operator)


rank_imagerank_imageRankImagerank_imageRankImageRankImage — Compute a rank filter with arbitrary masks.


rank_image(Image, Mask : ImageRank : Rank, Margin : )

Herror rank_image(const Hobject Image, const Hobject Mask, Hobject* ImageRank, const Hlong Rank, const char* Margin)

Herror T_rank_image(const Hobject Image, const Hobject Mask, Hobject* ImageRank, const Htuple Rank, const Htuple Margin)

Herror rank_image(Hobject Image, Hobject Mask, Hobject* ImageRank, const HTuple& Rank, const HTuple& Margin)

HImage HImage::RankImage(const HRegion& Mask, const HTuple& Rank, const HTuple& Margin) const

HImageArray HImageArray::RankImage(const HRegion& Mask, const HTuple& Rank, const HTuple& Margin) const

void RankImage(const HObject& Image, const HObject& Mask, HObject* ImageRank, const HTuple& Rank, const HTuple& Margin)

HImage HImage::RankImage(const HRegion& Mask, Hlong Rank, const HTuple& Margin) const

HImage HImage::RankImage(const HRegion& Mask, Hlong Rank, const HString& Margin) const

HImage HImage::RankImage(const HRegion& Mask, Hlong Rank, const char* Margin) const

void HOperatorSetX.RankImage(
[in] IHUntypedObjectX* Image, [in] IHUntypedObjectX* Mask, [out] IHUntypedObjectX*ImageRank, [in] VARIANT Rank, [in] VARIANT Margin)

IHImageX* HImageX.RankImage(
[in] IHRegionX* Mask, [in] Hlong Rank, [in] VARIANT Margin)

static void HOperatorSet.RankImage(HObject image, HObject mask, out HObject imageRank, HTuple rank, HTuple margin)

HImage HImage.RankImage(HRegion mask, int rank, HTuple margin)

HImage HImage.RankImage(HRegion mask, int rank, string margin)


rank_imagerank_imageRankImagerank_imageRankImageRankImage performs a rank filter on the input image ImageImageImageImageImageimage with a mask that is specified by the region MaskMaskMaskMaskMaskmask and returns the filtered image in ImageRankImageRankImageRankImageRankImageRankimageRank. The shape of the mask can be chosen arbitrarily and can, for example, be created with operators like gen_circlegen_circleGenCirclegen_circleGenCircleGenCircle or draw_regiondraw_regionDrawRegiondraw_regionDrawRegionDrawRegion. The position of the mask does not influence the result since the center of gravity of the mask region is used as the reference point of the mask.

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 A corresponds to the largest gray value within the mask. Here, A denotes the area of MaskMaskMaskMaskMaskmask (see area_centerarea_centerAreaCenterarea_centerAreaCenterAreaCenter). For RankRankRankRankRankrank = (A - 1) / 2 + 1, rank_imagerank_imageRankImagerank_imageRankImageRankImage returns the median gray value (see median_imagemedian_imageMedianImagemedian_imageMedianImageMedianImage). For RankRankRankRankRankrank = 1, rank_imagerank_imageRankImagerank_imageRankImageRankImage 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 = A rank_imagerank_imageRankImagerank_imageRankImageRankImage 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_imagerank_imageRankImagerank_imageRankImageRankImage can be used, for example, to suppress noise or to suppress unwanted objects that are smaller than the mask. Furthermore, rank_imagerank_imageRankImagerank_imageRankImageRankImage 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 A, slightly larger or smaller values should be selected for RankRankRankRankRankrank.

Several border treatments can be chosen for filtering via the parameter MarginMarginMarginMarginMarginmargin:

    gray value   Pixels outside of the image borders are assumed to
                 be constant (with the specified gray value).
    'continued'  Continuation of border pixels.
    'cyclic'     Cyclic continuation of image borders.
    'mirrored'   Reflection of pixels at the image borders.


rank_imagerank_imageRankImagerank_imageRankImageRankImage uses an algorithm with a runtime per pixel that depends on the number of runs in the mask MaskMaskMaskMaskMaskmask. Therefore, rank_imagerank_imageRankImagerank_imageRankImageRankImage is slower than rank_rectrank_rectRankRectrank_rectRankRectRankRect for rectangular masks with a large mask height. The precise mask height for which rank_rectrank_rectRankRectrank_rectRankRectRankRect will become faster than rank_imagerank_imageRankImagerank_imageRankImageRankImage depends on the computer architecture (processor type, availability of SIMD instructions like SSE2 or MMX, cache size and throughput, memory throughput). Typically, this is the case for mask heights > 15, but can also be the case only 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 mask heights.

rank_imagerank_imageRankImagerank_imageRankImageRankImage should neither be used with RankRankRankRankRankrank = 1 to perform a gray value erosion nor with RankRankRankRankRankrank = A to perform a gray value dilation. In these cases, the operators gray_erosion_rectgray_erosion_rectGrayErosionRectgray_erosion_rectGrayErosionRectGrayErosionRect, gray_erosion_shapegray_erosion_shapeGrayErosionShapegray_erosion_shapeGrayErosionShapeGrayErosionShape, or gray_erosiongray_erosionGrayErosiongray_erosionGrayErosionGrayErosion and gray_dilation_rectgray_dilation_rectGrayDilationRectgray_dilation_rectGrayDilationRectGrayDilationRect, gray_dilation_shapegray_dilation_shapeGrayDilationShapegray_dilation_shapeGrayDilationShapeGrayDilationShape, or gray_dilationgray_dilationGrayDilationgray_dilationGrayDilationGrayDilation, respectively, are typically faster than rank_imagerank_imageRankImagerank_imageRankImageRankImage.

Note that filter operators may return unexpected results if an image with a reduced domain is used as input. Please refer to the chapter Filters.



ImageImageImageImageImageimage (input_object)  (multichannel-)image(-array) objectHImageHImageHImageHImageXHobject (byte / int2 / uint2 / int4 / real)

Image to be filtered.

MaskMaskMaskMaskMaskmask (input_object)  region objectHRegionHRegionHRegionHRegionXHobject

Filter mask.

ImageRankImageRankImageRankImageRankImageRankimageRank (output_object)  multichannel-image(-array) objectHImageHImageHImageHImageXHobject * (byte / int2 / uint2 / int4 / real)

Filtered image.

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

Typical range of values: 1 ≤ Rank Rank Rank Rank Rank rank ≤ 4095

Minimum increment: 1

Recommended increment: 2

MarginMarginMarginMarginMarginmargin (input_control)  string HTupleHTupleHTupleVARIANTHtuple (string / integer / real) (string / int / long / double) (HString / Hlong / double) (char* / Hlong / double) (BSTR / Hlong / double) (char* / Hlong / double)

Border treatment.

Default value: 'mirrored' "mirrored" "mirrored" "mirrored" "mirrored" "mirrored"

Suggested values: 'mirrored'"mirrored""mirrored""mirrored""mirrored""mirrored", 'cyclic'"cyclic""cyclic""cyclic""cyclic""cyclic", 'continued'"continued""continued""continued""continued""continued", 0, 30, 60, 90, 120, 150, 180, 210, 240, 255

Example (HDevelop)

read_image (Image, 'fabrik')
draw_region (Region, WindowHandle)
rank_image (Image, Region, ImageRank, 5, 'mirrored')


For each pixel: O(N), where N is the number of runs of MaskMaskMaskMaskMaskmask (see runlength_featuresrunlength_featuresRunlengthFeaturesrunlength_featuresRunlengthFeaturesRunlengthFeatures).


If the parameter values are correct the operator rank_imagerank_imageRankImagerank_imageRankImageRankImage returns the value 2 (H_MSG_TRUE). The behavior in case of empty input (no input images available) is set via the operator 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, draw_regiondraw_regionDrawRegiondraw_regionDrawRegionDrawRegion, gen_circlegen_circleGenCirclegen_circleGenCircleGenCircle, gen_rectangle1gen_rectangle1GenRectangle1gen_rectangle1GenRectangle1GenRectangle1, gen_rectangle2gen_rectangle2GenRectangle2gen_rectangle2GenRectangle2GenRectangle2

Possible Successors

thresholdthresholdThresholdthresholdThresholdThreshold, dyn_thresholddyn_thresholdDynThresholddyn_thresholdDynThresholdDynThreshold, regiongrowingregiongrowingRegiongrowingregiongrowingRegiongrowingRegiongrowing


rank_rectrank_rectRankRectrank_rectRankRectRankRect, median_imagemedian_imageMedianImagemedian_imageMedianImageMedianImage, median_rectmedian_rectMedianRectmedian_rectMedianRectMedianRect

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


T.S. Huang, G.J. Yang, G.Y. Tang; “A Fast Two-Dimensional Median Filtering Algorithm”; IEEE Transactions on Acoustics, Speech, and Signal Processing, vol. 27, no. 1, pp. 13-18, 1979.
R. Haralick, L. Shapiro; “Computer and Robot Vision”; Addison-Wesley, 1992, pp. 318-320.



ClassesClassesClassesClasses | | | | Operators