ClassesClassesClassesClasses | | | | Operators

median_imagemedian_imageMedianImagemedian_imageMedianImageMedianImage (Operator)

Name

median_imagemedian_imageMedianImagemedian_imageMedianImageMedianImage — Compute a median filter with various masks.

Signature

median_image(Image : ImageMedian : MaskType, Radius, Margin : )

Herror median_image(const Hobject Image, Hobject* ImageMedian, const char* MaskType, const Hlong Radius, const char* Margin)

Herror T_median_image(const Hobject Image, Hobject* ImageMedian, const Htuple MaskType, const Htuple Radius, const Htuple Margin)

Herror median_image(Hobject Image, Hobject* ImageMedian, const HTuple& MaskType, const HTuple& Radius, const HTuple& Margin)

HImage HImage::MedianImage(const HTuple& MaskType, const HTuple& Radius, const HTuple& Margin) const

HImageArray HImageArray::MedianImage(const HTuple& MaskType, const HTuple& Radius, const HTuple& Margin) const

void MedianImage(const HObject& Image, HObject* ImageMedian, const HTuple& MaskType, const HTuple& Radius, const HTuple& Margin)

HImage HImage::MedianImage(const HString& MaskType, Hlong Radius, const HTuple& Margin) const

HImage HImage::MedianImage(const HString& MaskType, Hlong Radius, const HString& Margin) const

HImage HImage::MedianImage(const char* MaskType, Hlong Radius, const char* Margin) const

void HOperatorSetX.MedianImage(
[in] IHUntypedObjectX* Image, [out] IHUntypedObjectX*ImageMedian, [in] VARIANT MaskType, [in] VARIANT Radius, [in] VARIANT Margin)

IHImageX* HImageX.MedianImage(
[in] BSTR MaskType, [in] Hlong Radius, [in] VARIANT Margin)

static void HOperatorSet.MedianImage(HObject image, out HObject imageMedian, HTuple maskType, HTuple radius, HTuple margin)

HImage HImage.MedianImage(string maskType, int radius, HTuple margin)

HImage HImage.MedianImage(string maskType, int radius, string margin)

Description

median_imagemedian_imageMedianImagemedian_imageMedianImageMedianImage performs a median filter on the input image ImageImageImageImageImageimage with a square or circular mask and returns the filtered image in ImageMedianImageMedianImageMedianImageMedianImageMedianimageMedian. The shape of the mask can be selected with MaskTypeMaskTypeMaskTypeMaskTypeMaskTypemaskType. The radius of the mask can be selected with RadiusRadiusRadiusRadiusRadiusradius.

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) (A - 1) / 2 + 1 of the sorted gray values, where A denotes the area of the filter mask selected with MaskTypeMaskTypeMaskTypeMaskTypeMaskTypemaskType and RadiusRadiusRadiusRadiusRadiusradius. Here, the rank 1 corresponds to the smallest gray value and the rank A corresponds to the largest gray value within the mask (see also rank_imagerank_imageRankImagerank_imageRankImageRankImage).

median_imagemedian_imageMedianImagemedian_imageMedianImageMedianImage 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).

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.

When using a 3x3 or 5x5 rectangular filter mask and the border treatment 'mirrored'"mirrored""mirrored""mirrored""mirrored""mirrored", median_imagemedian_imageMedianImagemedian_imageMedianImageMedianImage can be executed on OpenCL devices.

Attention

median_imagemedian_imageMedianImagemedian_imageMedianImageMedianImage uses an algorithm with a runtime per pixel that depends on the mask height 2 * RadiusRadiusRadiusRadiusRadiusradius + 1. Therefore, median_imagemedian_imageMedianImagemedian_imageMedianImageMedianImage is slower than median_rectmedian_rectMedianRectmedian_rectMedianRectMedianRect for square masks with a large mask height. The precise mask height for which median_rectmedian_rectMedianRectmedian_rectMedianRectMedianRect will become faster than median_imagemedian_imageMedianImagemedian_imageMedianImageMedianImage 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 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 is faster than median_rectmedian_rectMedianRectmedian_rectMedianRectMedianRect even for larger mask heights.

Parallelization

Parameters

ImageImageImageImageImageimage (input_object)  (multichannel-)image(-array) objectHImageHImageHImageHImageXHobject (byte* / int2* / uint2* / int4* / real*) *allowed for compute devices

Image to be filtered.

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

Filtered image.

MaskTypeMaskTypeMaskTypeMaskTypeMaskTypemaskType (input_control)  string HTupleHTupleHTupleVARIANTHtuple (string) (string) (HString) (char*) (BSTR) (char*)

Filter mask type.

Default value: 'circle' "circle" "circle" "circle" "circle" "circle"

List of values: 'circle'"circle""circle""circle""circle""circle", 'square'"square""square""square""square""square"

List of values (for compute devices): 'square'"square""square""square""square""square"

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

Radius of the filter mask.

Default value: 1

List of values (for compute devices): 1, 2

Suggested values: 1, 2, 3, 4, 5, 6, 7, 8, 9, 11, 15, 19, 25, 31, 39, 47, 59

Typical range of values: 1 ≤ Radius Radius Radius Radius Radius radius ≤ 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"

List of values (for compute devices): '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')
median_image (Image, Median, 'circle', 3, 'continued')
disp_image (MedianWeighted, WindowHandle)

Complexity

For each pixel: O(2 * RadiusRadiusRadiusRadiusRadiusradius + 1).

Result

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

Possible Successors

thresholdthresholdThresholdthresholdThresholdThreshold, dyn_thresholddyn_thresholdDynThresholddyn_thresholdDynThresholdDynThreshold, regiongrowingregiongrowingRegiongrowingregiongrowingRegiongrowingRegiongrowing

Alternatives

median_rectmedian_rectMedianRectmedian_rectMedianRectMedianRect, rank_imagerank_imageRankImagerank_imageRankImageRankImage, rank_rectrank_rectRankRectrank_rectRankRectRankRect

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

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.

Module

Foundation


ClassesClassesClassesClasses | | | | Operators