median_image — Compute a median filter with various masks.
median_image performs a median filter on the input image Image with a square or circular mask and returns the filtered image in ImageMedian. The shape of the mask can be selected with MaskType. The radius of the mask can be selected with Radius.
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) (N - 1) / 2 + 1 of the sorted gray values, where N denotes the number of pixels covered by the filter mask. Here, the rank 1 corresponds to the smallest gray value and the rank N corresponds to the largest gray value within the mask (see also rank_image).
The filter mask is determined by Radius, defining the size, and MaskType, defining the shape of the mask. For latter one, the following options are available:
'circle': The mask consists of the pixel within a circle with Radius around the pixel of the mask center.
'square': The mask consists of the pixel within a square with an edge length of Radius pixel.
median_image 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_threshold).
Several border treatments can be chosen for filtering via the parameter Margin:
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 the MaskType 'square' with Radius 1 or 2 (resulting in a 3x3 or 5x5 pixel filter mask) and the border treatment 'mirrored', median_image can be executed on OpenCL devices.
median_image uses an algorithm with a runtime per pixel that depends on the mask height 2 * Radius + 1. Therefore, median_image is slower than median_rect for square masks with a large mask height. The precise mask height for which median_rect will become faster than median_image 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_rect 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_image is faster than median_rect even for larger mask heights.
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.
Image to be filtered.
Filter mask type.
Default value: 'circle'
List of values: 'circle', 'square'
List of values (for compute devices): 'square'
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 ≤ 4095
Minimum increment: 1
Recommended increment: 2
Default value: 'mirrored'
List of values (for compute devices): 'mirrored'
Suggested values: 'mirrored', 'cyclic', 'continued', 0, 30, 60, 90, 120, 150, 180, 210, 240, 255
read_image (Image, 'fabrik') median_image (Image, Median, 'circle', 3, 'continued') dev_display(Median)
For each pixel: O(2 * Radius + 1).
If the parameter values are correct the operator median_image 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>). If necessary, an exception is raised.
threshold, dyn_threshold, regiongrowing
median_rect, rank_image, rank_rect
gray_erosion_rect, gray_dilation_rect, gray_erosion_shape, gray_dilation_shape, gray_erosion, gray_dilation
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.