vigra - Local Minima and Maxima

[ VIGRA Homepage | Function Index | Class Index | Namespaces | File List | Main Page ]

| 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, 3N-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, 3N-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().

© Ullrich Köthe (ullrich.koethe@iwr.uni-heidelberg.de) Heidelberg Collaboratory for Image Processing, University of Heidelberg, Germany | html generated using doxygen and Python vigra 1.10.0 (Mon Nov 18 2013)