ClassesClassesClassesClasses | | | | Operators

median_rectmedian_rectMedianRectmedian_rectMedianRectMedianRect (Operator)


median_rectmedian_rectMedianRectmedian_rectMedianRectMedianRect — Compute a median filter with rectangular masks.


median_rect(Image : ImageMedian : MaskWidth, MaskHeight : )

Herror median_rect(const Hobject Image, Hobject* ImageMedian, const Hlong MaskWidth, const Hlong MaskHeight)

Herror T_median_rect(const Hobject Image, Hobject* ImageMedian, const Htuple MaskWidth, const Htuple MaskHeight)

Herror median_rect(Hobject Image, Hobject* ImageMedian, const HTuple& MaskWidth, const HTuple& MaskHeight)

HImage HImage::MedianRect(const HTuple& MaskWidth, const HTuple& MaskHeight) const

HImageArray HImageArray::MedianRect(const HTuple& MaskWidth, const HTuple& MaskHeight) const

void MedianRect(const HObject& Image, HObject* ImageMedian, const HTuple& MaskWidth, const HTuple& MaskHeight)

HImage HImage::MedianRect(Hlong MaskWidth, Hlong MaskHeight) const

void HOperatorSetX.MedianRect(
[in] IHUntypedObjectX* Image, [out] IHUntypedObjectX*ImageMedian, [in] VARIANT MaskWidth, [in] VARIANT MaskHeight)

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

static void HOperatorSet.MedianRect(HObject image, out HObject imageMedian, HTuple maskWidth, HTuple maskHeight)

HImage HImage.MedianRect(int maskWidth, int maskHeight)


median_rectmedian_rectMedianRectmedian_rectMedianRectMedianRect performs a median filter on the input image ImageImageImageImageImageimage with a rectangular mask of size MaskWidthMaskWidthMaskWidthMaskWidthMaskWidthmaskWidth × MaskHeightMaskHeightMaskHeightMaskHeightMaskHeightmaskHeight and returns the filtered image in ImageMedianImageMedianImageMedianImageMedianImageMedianimageMedian.

Conceptually, the median filter sorts all gray values within the mask in ascending order and then selects the median of the gray values. The median is the “middle” one of the sorted gray values, i.e., the gray value with rank (position) (MaskWidthMaskWidthMaskWidthMaskWidthMaskWidthmaskWidth * MaskHeightMaskHeightMaskHeightMaskHeightMaskHeightmaskHeight - 1) / 2 + 1 of the sorted gray values, where the rank 1 corresponds to the smallest gray value and the rank MaskWidthMaskWidthMaskWidthMaskWidthMaskWidthmaskWidth * MaskHeightMaskHeightMaskHeightMaskHeightMaskHeightmaskHeight corresponds to the largest gray value within the mask (see also rank_rectrank_rectRankRectrank_rectRankRectRankRect).

median_rectmedian_rectMedianRectmedian_rectMedianRectMedianRect can be used, for example, to smooth images, to suppress unwanted objects (e.g., point-like or line-like structures) that are smaller than the mask, and can therefore be used to estimate the background illumination for a shading correction or as a preprocessing step for the dynamic threshold operation (see dyn_thresholddyn_thresholdDynThresholddyn_thresholdDynThresholdDynThreshold).

When using a 3x3 or 5x5 filter mask, median_rectmedian_rectMedianRectmedian_rectMedianRectMedianRect can be executed on OpenCL devices.


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

median_rectmedian_rectMedianRectmedian_rectMedianRectMedianRect 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 median_rectmedian_rectMedianRectmedian_rectMedianRectMedianRect is the fastest implementation of the median 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 median_imagemedian_imageMedianImagemedian_imageMedianImageMedianImage and rank_imagerank_imageRankImagerank_imageRankImageRankImage is faster than median_rectmedian_rectMedianRectmedian_rectMedianRectMedianRect. 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 median_rectmedian_rectMedianRectmedian_rectMedianRectMedianRect 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 median_imagemedian_imageMedianImagemedian_imageMedianImageMedianImage and rank_imagerank_imageRankImagerank_imageRankImageRankImage are faster than median_rectmedian_rectMedianRectmedian_rectMedianRectMedianRect even for larger values of MaskHeightMaskHeightMaskHeightMaskHeightMaskHeightmaskHeight.

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*) *allowed for compute devices

Image to be filtered.

ImageMedianImageMedianImageMedianImageMedianImageMedianimageMedian (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

List of values (for compute devices): 3, 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: 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

List of values (for compute devices): 3, 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: 3 ≤ MaskHeight MaskHeight MaskHeight MaskHeight MaskHeight maskHeight ≤ 4095

Minimum increment: 2

Recommended increment: 2


For each pixel: O(1).


If the parameter values are correct the operator median_rectmedian_rectMedianRectmedian_rectMedianRectMedianRect 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


Possible Successors

thresholdthresholdThresholdthresholdThresholdThreshold, dyn_thresholddyn_thresholdDynThresholddyn_thresholdDynThresholdDynThreshold, regiongrowingregiongrowingRegiongrowingregiongrowingRegiongrowingRegiongrowing


median_imagemedian_imageMedianImagemedian_imageMedianImageMedianImage, rank_rectrank_rectRankRectrank_rectRankRectRankRect, rank_imagerank_imageRankImagerank_imageRankImageRankImage

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


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.



ClassesClassesClassesClasses | | | | Operators