Local Minima and Maxima

Classes
class	LocalMinmaxOptions
	Options object for localMinima() and localMaxima(). More...

Functions
template<... >
void	extendedLocalMaxima (...)
	Find local maximal regions in an array. More...
template<... >
void	extendedLocalMaxima3D (...)
	Find local maximal regions in 3D multi array. More...
template<... >
void	extendedLocalMinima (...)
	Find local minimal regions (plateaus) in an array. More...
template<... >
void	extendedLocalMinima3D (...)
	Find local minimal regions in a volume. More...
template<... >
void	localMaxima (...)
	Find local maxima in an image or multi-dimensional array. More...
template<... >
void	localMaxima3D (...)
	Find local maxima in a 3D multi array. More...
template<... >
void	localMinima (...)
	Find local minima in an image or multi-dimensional array. More...
template<... >
void	localMinima3D (...)
	Find local minima in a 3D multi array. More...

Detailed Description

Detect local minima and maxima in a gray level image, including extremal plateaus larger than 1 pixel

Function Documentation

void vigra::localMinima

(

...

)

Find local minima in an image or multi-dimensional array.

By default, minima are defined as points which are not at the array border and whose value is lower than the value of all indirect neighbors (i.e. 8-neighbors in 2D, 26-neighbors in 3D, 3^N-1 neighbors in N-D). The detected points will be marked with the default value 1 in the destination array.

The defaults can be overridden in various ways by providing LocalMinmaxOptions : you can switch to the direct neighborhood (i.e. 4-neighborhood in 2D, 6-neighborhood in 3D, 2*N neighborhood in N-D), allow minima at the border, discard minima where the function value is not below a given threshold, allow extended minima (i.e. minima that form minimal plateaus rather than isolated pixels – note that this option is only supported for 2D images), and change the marker in the destination image. See usage examples below for details.

There are also variants of the localMinima() function where parameters are passed explicitly rather than via an option object. These versions of the function are deprecated, but will be kept for compatibility.

Declarations:

use arbitrary-dimensional arrays:

namespace vigra {
    template <unsigned int N, class T1, class C1, class T2, class C2>
    void
    localMinima(MultiArrayView<N, T1, C1> src,
                MultiArrayView<N, T2, C2> dest,
                LocalMinmaxOptions const & options = LocalMinmaxOptions());
}

show deprecated declarations

pass Image Iterators and Data Accessors :

namespace vigra {
    template <class SrcIterator, class SrcAccessor,
              class DestIterator, class DestAccessor>
    void
    localMinima(SrcIterator sul, SrcIterator slr, SrcAccessor sa,
                DestIterator dul, DestAccessor da,
                LocalMinmaxOptions const & options = LocalMinmaxOptions());
}

use argument objects in conjunction with Argument Object Factories :

namespace vigra {
    template <class SrcIterator, class SrcAccessor,
              class DestIterator, class DestAccessor>
    void
    localMinima(triple<SrcIterator, SrcIterator, SrcAccessor> src,
                pair<DestIterator, DestAccessor> dest,
                LocalMinmaxOptions const & options = LocalMinmaxOptions());
}

Usage:

#include <vigra/localminmax.hxx>
#include <vigra/multi_localminmax.hxx>
Namespace: vigra

// 3D examples (other dimensions work likewise)
Shape3 shape(w,h,d);
MultiArray<3, unsigned char> src(shape), minima(shape);
... // fill src

// use default parameterisation
localMinima(src, minima);

// reset destination image
minima = 0;

// use direct neighborhood (i.e. 6-neighborhood since we are in 3D) 
// and allow minima at the image border
localMinima(src, minima,
            LocalMinmaxOptions().neighborhood(0).allowAtBorder());

show deprecated examples

// 2D examples using BasicImage
BImage src(w,h), minima(w,h);
... // fill src

// use default parameterisation
localMinima(srcImageRange(src), destImage(minima));

// reset destination image
minima = 0;

// use 4-neighborhood and allow minima at the image border
localMinima(srcImageRange(src), destImage(minima),
                   LocalMinmaxOptions().neighborhood(4).allowAtBorder());

// reset destination image
minima = 0;

// allow extended minima (minimal plateaus) and use value '255' as a marker
localMinima(srcImageRange(src), destImage(minima),
                   LocalMinmaxOptions().allowPlateaus().markWith(255));

Required Interface:

SrcIterator src_upperleft, src_lowerright;
DestIterator dest_upperleft;

SrcAccessor src_accessor;
DestAccessor dest_accessor;

SrcAccessor::value_type u = src_accessor(src_upperleft);

u < u

void vigra::localMinima3D

(

...

)

Find local minima in a 3D multi array.

Deprecated, use localMinima() instead.

void vigra::localMaxima

(

...

)

Find local maxima in an image or multi-dimensional array.

By default, maxima are defined as points which are not at the array border and whose value is higher than the value of all indirect neighbors (i.e. 8-neighbors in 2D, 26-neighbors in 3D, 3^N-1 neighbors in N-D). The detected points will be marked with the default value 1 in the destination array.

The defaults can be overridden in various ways by providing LocalMinmaxOptions : you can switch to the direct neighborhood (i.e. 4-neighborhood in 2D, 6-neighborhood in 3D, 2*N neighborhood in N-D), allow maxima at the border, discard maxima where the function value is not above a given threshold, allow extended maxima (i.e. maxima that form maximal plateaus rather than isolated pixels – note that this option is only supported for 2D images), and change the marker in the destination image. See usage examples below for details.

There are also variants of the localMaxima() function where parameters are passed explicitly rather than via an option object. These versions of the function are deprecated, but will be kept for compatibility.

Declarations:

use arbitrary-dimensional arrays:

namespace vigra {
    template <unsigned int N, class T1, class C1, class T2, class C2>
    void
    localMaxima(MultiArrayView<N, T1, C1> src,
                MultiArrayView<N, T2, C2> dest,
                LocalMinmaxOptions const & options = LocalMinmaxOptions());
}

show deprecated declarations

pass Image Iterators and Data Accessors :

namespace vigra {
    template <class SrcIterator, class SrcAccessor,
              class DestIterator, class DestAccessor>
    void
    localMaxima(SrcIterator sul, SrcIterator slr, SrcAccessor sa,
                DestIterator dul, DestAccessor da,
                LocalMinmaxOptions const & options = LocalMinmaxOptions());
}

use argument objects in conjunction with Argument Object Factories :

namespace vigra {
    template <class SrcIterator, class SrcAccessor,
              class DestIterator, class DestAccessor>
    void
    localMaxima(triple<SrcIterator, SrcIterator, SrcAccessor> src,
                pair<DestIterator, DestAccessor> dest,
                LocalMinmaxOptions const & options = LocalMinmaxOptions());
}

Usage:

#include <vigra/localminmax.hxx>
#include <vigra/multi_localminmax.hxx>
Namespace: vigra

// 3D examples (other dimensions work likewise)
Shape3 shape(w,h,d);
MultiArray<3, unsigned char> src(shape), maxima(shape);
... // fill src

// use default parameterisation
localMaxima(src, maxima);

// reset destination image
maxima = 0;

// use direct neighborhood (i.e. 6-neighborhood sine we are in 3D)
// and allow maxima at the image border
localMaxima(src, maxima,
            LocalMinmaxOptions().neighborhood(0).allowAtBorder());

show deprecated examples

// 2D examples using BasicImage
BImage src(w,h), maxima(w,h);
... // fill src

// use default parameterisation
localMaxima(srcImageRange(src), destImage(maxima));

// reset destination image
maxima = 0;

// use 4-neighborhood and allow maxima at the image border
localMaxima(srcImageRange(src), destImage(maxima),
                   LocalMinmaxOptions().neighborhood(4).allowAtBorder());

// reset destination image
maxima = 0;

// allow extended maxima (maximal plateaus) and use value '255' as a marker
localMaxima(srcImageRange(src), destImage(maxima),
                   LocalMinmaxOptions().allowPlateaus().markWith(255));

Required Interface:

SrcIterator src_upperleft, src_lowerright;
DestIterator dest_upperleft;

SrcAccessor src_accessor;
DestAccessor dest_accessor;

SrcAccessor::value_type u = src_accessor(src_upperleft);

u < u

void vigra::localMaxima3D

(

...

)

Find local maxima in a 3D multi array.

Deprecated, use localMaxima() instead.

void vigra::extendedLocalMinima

(

...

)

Find local minimal regions (plateaus) in an array.

This function is only needed when you want to pass a non-standard equality predicate via EqualityFunctor. Otherwise (i.e. when equality is defined by the '==' operator of the source value type T1), you can simply call localMinima() with the option LocalMinmaxOptions::allowPlateaus().

This function finds regions of uniform pixel values whose neighboring regions all have larger values, i.e. it finds minimal plateaus of arbitrary size (including size 1). The EqualityFunctor determines when pixels are considered equal, so that one can allow for plateaus that are not quite constant (this is often necessary with float pixel values). Otherwise, the functionality is identical to localMinima().

Declarations:

use arbitrary-dimensional arrays:

namespace vigra {
    template <unsigned int N, class T1, class S1,
                              class T2, class S2,
              class EqualityFunctor>
    unsigned int
    extendedLocalMinima(MultiArrayView<N, T1, S1> const & src,
                        MultiArrayView<N, T2, S2> dest,
                        EqualityFunctor const & equal,
                        LocalMinmaxOptions options = LocalMinmaxOptions());

show deprecated declarations

pass Image Iterators and Data Accessors :

namespace vigra {
    template <class SrcIterator, class SrcAccessor,
              class DestIterator, class DestAccessor,
              class DestValue = DestAccessor::value_type,
              class Neighborhood = EightNeighborCode,
              class EqualityFunctor = std::equal_to<typename SrcAssessor::value_type> >
    void
    extendedLocalMinima(SrcIterator sul, SrcIterator slr, SrcAccessor sa,
                        DestIterator dul, DestAccessor da,
                        DestValue marker = NumericTraits<DestValue>::one(),
                        Neighborhood neighborhood = EightNeighborCode(),
                        EqualityFunctor equal = EqualityFunctor());
                        
    template<class SrcIterator, class SrcShape, class SrcAccessor,
             class DestIterator, class DestAccessor,
             class Neighborhood = NeighborCode3DSix,
             class EqualityFunctor = std::equal_to<typename SrcAssessor::value_type> >
    void 
    extendedLocalMinima3D(SrcIterator sul, SrcShape slr, SrcAccessor sa,
                          DestIterator dul, DestAccessor da,
                          typename DestAccessor::value_type marker,
                          Neighborhood neighborhood = Neighborhood(),
                          EqualityFunctor equal = EqualityFunctor());
}

use argument objects in conjunction with Argument Object Factories :

namespace vigra {
    template <class SrcIterator, class SrcAccessor,
              class DestIterator, class DestAccessor,
              class DestValue = DestAccessor::value_type,
              class Neighborhood = EightNeighborCode,
              class EqualityFunctor = std::equal_to<typename SrcAssessor::value_type> >
    void
    extendedLocalMinima(triple<SrcIterator, SrcIterator, SrcAccessor> src,
                        pair<DestIterator, DestAccessor> dest,
                        DestValue marker = NumericTraits<DestValue>::one(),
                        Neighborhood neighborhood = EightNeighborCode(),
                        EqualityFunctor equal = EqualityFunctor());
                        
    template<class SrcIterator, class SrcAccessor, class SrcShape,
             class DestIterator, class DestAccessor, 
             class Neighborhood>
    void 
    extendedLocalMinima3D(triple<SrcIterator, SrcShape, SrcAccessor> src,
                          pair<DestIterator, DestAccessor> dest,
                          typename DestAccessor::value_type marker,
                          Neighborhood neighborhood);
}

Usage:

#include <vigra/localminmax.hxx>
Namespace: vigra

// define an equality functor
template <class T>
struct EqualWithToleranceFunctor
{
    EqualWithToleranceFunctor(T tolerance)
    : t(tolerance)
    {}

    bool operator()(T l, T r) const
    {
        return abs(l-r) <= t;
    }

    T t;
};

MultiArray<2, unsigned char> src(w,h), minima(w,h);

// allow plateaus
localMinima(src, minima, LocalMinmaxOptions().allowPlateaus());

// reset result image
minima.init(0);
// allow plateaus with tolerance (grayvalues may differ by one)
extendedLocalMinima(src, minima, EqualWithToleranceFunctor<unsigned char>(1));

show deprecated examples

// optional: define an equality functor
template <class T>
struct EqualWithToleranceFunctor
{
    EqualWithToleranceFunctor(T tolerance)
    : t(tolerance)
    {}

    bool operator()(T l, T r) const
    {
        return abs(l-r) <= t;
    }

    T t;
};

BImage src(w,h), minima(w,h);

// init destiniation image
minima.init(0);

extendedLocalMinima(srcImageRange(src), destImage(minima));

// allow plateaus with tolerance
minima.init(0);
extendedLocalMinima(srcImageRange(src), destImage(minima), 1.0,
                           FourNeighborCode(),
                           EqualWithToleranceFunctor<unsigned char>(1));

Required Interface:

SrcImageIterator src_upperleft, src_lowerright;
DestImageIterator dest_upperleft;

SrcAccessor src_accessor;
DestAccessor dest_accessor;

SrcAccessor::value_type u = src_accessor(src_upperleft);

EqualityFunctor equal;
u == u
equal(u, u);
u < u

DestValue marker;
dest_accessor.set(marker, dest_upperleft);

void vigra::extendedLocalMinima3D

(

...

)

Find local minimal regions in a volume.

See extendedLocalMinima().

void vigra::extendedLocalMaxima

(

...

)

Find local maximal regions in an array.

This function is only needed when you want to pass a non-standard equality predicate via EqualityFunctor. Otherwise (i.e. when equality is defined by the '==' operator of the source value type T1), you can simply call localMaxima() with the option LocalMinmaxOptions::allowPlateaus().

This function finds regions of uniform pixel values whose neighboring regions all have smaller values, i.e. it finds maximal plateaus of arbitrary size (including size 1). The EqualityFunctor determines when pixels are considered equal, so that one can allow for plateaus that are not quite constant (this is often necessary with float pixel values). Otherwise, the functionality is identical to localMaxima().

Declarations:

use arbitrary-dimensional arrays:

namespace vigra {
    template <unsigned int N, class T1, class S1,
                              class T2, class S2>
    unsigned int // return number of maxima
    extendedLocalMaxima(MultiArrayView<N, T1, S1> const & src,
                        MultiArrayView<N, T2, S2> dest,
                        LocalMinmaxOptions options = LocalMinmaxOptions());

show deprecated declarations

pass Image Iterators and Data Accessors :

namespace vigra {
    template <class SrcIterator, class SrcAccessor,
              class DestIterator, class DestAccessor,
              class DestValue = DestAccessor::value_type,
              class Neighborhood = EightNeighborCode,
              class EqualityFunctor = std::equal_to<typename SrcAssessor::value_type> >
    void
    extendedLocalMaxima(SrcIterator sul, SrcIterator slr, SrcAccessor sa,
                        DestIterator dul, DestAccessor da,
                        DestValue marker = NumericTraits<DestValue>::one(),
                        Neighborhood neighborhood = EightNeighborCode(),
                        EqualityFunctor equal = EqualityFunctor())
                        
    template<class SrcIterator, class SrcShape, class SrcAccessor,
             class DestIterator, class DestAccessor,
             class Neighborhood = NeighborCode3DSix,
             class EqualityFunctor = std::equal_to<typename SrcAssessor::value_type> >
    void 
    extendedLocalMaxima3D(SrcIterator sul, SrcShape slr, SrcAccessor sa,
                          DestIterator dul, DestAccessor da,
                          typename DestAccessor::value_type marker,
                          Neighborhood neighborhood = Neighborhood(),
                          EqualityFunctor equal = EqualityFunctor());
}

use argument objects in conjunction with Argument Object Factories :

namespace vigra {
    template <class SrcIterator, class SrcAccessor,
              class DestIterator, class DestAccessor,
              class DestValue = DestAccessor::value_type,
              class Neighborhood = EightNeighborCode,
              class EqualityFunctor = std::equal_to<typename SrcAssessor::value_type> >
    void
    extendedLocalMaxima(triple<SrcIterator, SrcIterator, SrcAccessor> src,
                        pair<DestIterator, DestAccessor> dest,
                        DestValue marker = NumericTraits<DestValue>::one(),
                        Neighborhood neighborhood = EightNeighborCode(),
                        EqualityFunctor equal = EqualityFunctor())
                        
    template<class SrcIterator, class SrcAccessor, class SrcShape,
             class DestIterator, class DestAccessor, 
             class Neighborhood>
    void 
    extendedLocalMaxima3D(triple<SrcIterator, SrcShape, SrcAccessor> src,
                          pair<DestIterator, DestAccessor> dest,
                          typename DestAccessor::value_type marker,
                          Neighborhood neighborhood);
}

Usage:

#include <vigra/localminmax.hxx>
Namespace: vigra

// define an equality functor
template <class T>
struct EqualWithToleranceFunctor
{
    EqualWithToleranceFunctor(T tolerance)
    : t(tolerance)
    {}

    bool operator()(T l, T r) const
    {
        return abs(l-r) <= t;
    }

    T t;
};

MultiArray<2, unsigned char> src(w,h), maxima(w,h);

// allow plateaus
localMaxima(src, maxima, LocalMinmaxOptions().allowPlateaus());

// reset result image
maxima.init(0);
// allow plateaus with tolerance (grayvalues may differ by one)
extendedLocalMaxima(src, maxima, EqualWithToleranceFunctor<unsigned char>(1));

show deprecated examples

// optional: define an equality functor
template <class T>
struct EqualWithToleranceFunctor
{
    EqualWithToleranceFunctor(T tolerance)
    : t(tolerance)
    {}

    bool operator()(T l, T r) const
    {
        return abs(l-r) <= t;
    }

    T t;
};

BImage src(w,h), maxima(w,h);

// init destiniation image
maxima.init(0);

extendedLocalMaxima(srcImageRange(src), destImage(maxima));

// allow plateaus with tolerance
maxima.init(0);
extendedLocalMaxima(srcImageRange(src), destImage(maxima), 1.0,
                           FourNeighborCode(),
                           EqualWithToleranceFunctor<unsigned char>(1));

Required Interface:

SrcImageIterator src_upperleft, src_lowerright;
DestImageIterator dest_upperleft;

SrcAccessor src_accessor;
DestAccessor dest_accessor;

SrcAccessor::value_type u = src_accessor(src_upperleft);

EqualityFunctor equal;
u == u
equal(u, u);
u < u

DestValue marker;
dest_accessor.set(marker, dest_upperleft);

void vigra::extendedLocalMaxima3D

(

...

)

Find local maximal regions in 3D multi array.

See extendedLocalMaxima().