You are here: Start » Function Reference » Image » Image Features » ImageLocalMinima

ImageLocalMinima

Header:	FIL.h
Namespace:	fil
Module:	FoundationBasic

Finds image locations characterized by locally minimal pixel values.

Applications: Detection of characteristic points, usually after some image transformations.

Syntax

void fil::ImageLocalMinima
(
	const fil::Image& inImage,
	ftl::Optional<const fil::Region&> inRoi,
	bool inConsiderLowlands,
	ftl::Optional<float> inMinValue,
	ftl::Optional<float> inMaxValue,
	float inMinDistance,
	ftl::Optional<const fil::ImageLocalExtremaVerification&> inMinimaVerification,
	ftl::Optional<ftl::Array<fil::Extremum2D>&> outLocalMinima,
	ftl::Optional<ftl::Array<fil::Region>&> outMinimaRegions = ftl::NIL
)

Parameters

Name	Type	Range	Default	Description
inImage	const Image&			Input image
inRoi	Optional<const Region&>		NIL	Range of pixels to be processed
inConsiderLowlands	bool			Consider multi-pixel minima (lowlands) or not
inMinValue	Optional<float>		NIL	Minimal value of minimum to be considered
inMaxValue	Optional<float>		NIL	Maximal value of minimum to be considered
inMinDistance	float	0.0 -		Minimal distance between two found minima
inMinimaVerification	Optional<const ImageLocalExtremaVerification&>		NIL	Minima verification structure
outLocalMinima	Optional<Array<Extremum2D>&>			Found local minima
outMinimaRegions	Optional<Array<Region>&>		NIL	Regions of local minima (plateaus and singletons)

Optional Outputs

The computation of following outputs can be switched off by passing value ftl::NIL to these parameters: outLocalMinima, outMinimaRegions.

Description

The operation finds local minima on the image inImage within specific region inRoi.

It returns three arrays of the same length:

Subpixel precise positions of the minima
Values of the minima
Regions of equally bright pixels around the minima

If the given image consists of more than one channel, they are averaged to obtain monochromatic image, so that the values of the extrema are of type float.

There are two types of local extrema:

Peak/hole: single pixel (strictly) brighter/darker than its neighbourhood (eight pixels). The extremum's position is determined with subpixel precision using gradient method with Sobel gradient. Returned region contains only one pixel.
Plateau/lowland: a connected set of equally bright pixels (strictly) brighter/darker from their neighbourhood. Returned position for this extremum is the center of mass of the plateau.

If parameter inConsiderLowlands is set to true, the filter finds both types. Otherwise, it finds only strict minima.

Parameter inMaxValue determines the maximal value of the minimum to be considered.

Hints

If some points are not detected, try decreasing inMaxValue or setting inConsiderLowlands to True.
Consider adding some Gaussian smoothing before this function.

Examples

Example image

Output for example image

Remarks

If a plateau/lowland is concave, it's center of mass may lie outside it. In such case, the value of the extremum (which is equal to the common value of its pixels) may be different from the value of pixel indicated by position of the extremum.

Errors

List of possible exceptions:

Error type	Description
DomainError	Region exceeds an input image in ImageLocalMinima.