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 image or volume.
template<... >
void | extendedLocalMaxima3D (...)
| Find local maximal regions in 3D multi array.
template<... >
void | extendedLocalMinima (...)
| Find local minimal regions in an image or volume.
template<... >
void | extendedLocalMinima3D (...)
| Find local minimal regions in a volume.
template<... >
void | localMaxima (...)
| Find local maxima in an image or multi-dimensional array.
template<... >
void | localMaxima3D (...)
| Find local maxima in a 3D multi array.
template<... >
void | localMinima (...)
| Find local minima in an image or multi-dimensional array.
template<... >
void | localMinima3D (...)
| Find local minima in a 3D multi array.

## 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.

Note: the function is not yet implemented for arbitrary dimensional arrays, but see localMinima3D() for 3D.

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());
        }

pass image iterators explicitly:

        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 using MultiArray
        vigra::MultiArrayShape<3>::type shape(w,h,d);
        vigra::MultiArray<3, unsigned char> src(shape), minima(shape);
        ... // fill src

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

        // reset destination image
        minima = 0;

        // use 6-neighborhood and allow minima at the image border
        vigra::localMinima(src, minima,
                           vigra::LocalMinmaxOptions().neighborhood(6).allowAtBorder());

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

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

        // reset destination image
        minima = 0;

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

        // reset destination image
        minima = 0;

        // allow extended minima (minimal plateaus) and use value '255' as a marker
        vigra::localMinima(srcImageRange(src), destImage(minima),
                           vigra::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.

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. The detected points will be marked. See localMinima() for more details.

void vigra::localMaxima | ( |  | ... | ) |

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

Note: the function is not yet implemented for arbitrary dimensional arrays, but see localMaxima3D() for 3D.

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());
        }

pass image iterators explicitly:

        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 using MultiArray
        vigra::MultiArrayShape<3>::type shape(w,h,d);
        vigra::MultiArray<3, unsigned char> src(shape), maxima(shape);
        ... // fill src

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

        // reset destination image
        maxima = 0;

        // use 6-neighborhood and allow maxima at the image border
        vigra::localMaxima(src, maxima,
                           vigra::LocalMinmaxOptions().neighborhood(6).allowAtBorder());

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

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

        // reset destination image
        maxima = 0;

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

        // reset destination image
        maxima = 0;

        // allow extended maxima (maximal plateaus) and use value '255' as a marker
        vigra::localMaxima(srcImageRange(src), destImage(maxima),
                           vigra::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.

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. The detected points will be marked as specified. See localMaxima() for mor details.

void vigra::extendedLocalMinima | ( |  | ... | ) |

Find local minimal regions in an image or volume.

Note: the function is not yet implemented for arbitrary dimensional arrays, but see extendedLocalMinima3D() for 3D.

This function finds regions of uniform pixel value whose neighboring regions are all have smaller values (minimal plateaus of arbitrary size). By default, the pixels in a plateau have exactly identical values. By passing an `EqualityFunctor` with tolerance, one can allow for plateaus that are not quite constant (this is often necessary with float pixel values). Pass vigra::EightNeighborCode or vigra::FourNeighborCode to determine the neighborhood where pixel values are compared.

Minimal regions are marked in the destination image with the given marker value (default is 1), all other destination pixels remain unchanged. `SrcAccessor::value_type` must be equality-comparable and less-comparable. A pixel or region touching the image border will never be marked as minimum or minimal plateau. Use localMinima() with the appropriate options if you need that functionality. Likewise if you want to apply a threshold onl the fly. In fact, all functionality except for 'equality with tolerance' can be accessed via that function in a more readable way, so localMinima() should be preferred. The function uses accessors.

Declarations:

use 3-dimensional arrays:

        namespace vigra {
            template <class T1, class C1, class T2, class C2,
                      class Neighborhood>
            void
            extendedLocalMinima(MultiArrayView<3, T1, C1> src,
                                MultiArrayView<3, T2, C2> dest,
                                LocalMinmaxOptions const & options = LocalMinmaxOptions());

pass image iterators explicitly:

        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());
        }

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());
        }

Usage:

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

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

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

            T t;
        };

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

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

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

        // allow plateaus with tolerance
        minima.init(0);
        vigra::extendedLocalMinima(srcImageRange(src), destImage(minima), 1.0,
                                   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);

Examples:
  watershed.cxx.

void vigra::extendedLocalMinima3D | ( |  | ... | ) |

Find local minimal regions in a volume.

This function finds regions of uniform pixel value whose neighboring regions are all have smaller values (minimal plateaus of arbitrary size). By default, the pixels in a plateau have exactly identical values. By passing an `EqualityFunctor` with tolerance, one can allow for plateaus that are not quite constant (this is often necessary with float pixel values). Pass the neighborhood where pixel values are compared. See extendedLocalMinima() for more details.

void vigra::extendedLocalMaxima | ( |  | ... | ) |

Find local maximal regions in an image or volume.

Note: the function is not yet implemented for arbitrary dimensional arrays, but see extendedLocalMaxima3D() for 3D.

This function finds regions of uniform pixel value whose neighboring regions are all have smaller values (maximal plateaus of arbitrary size). By default, the pixels in a plateau have exactly identical values. By passing an `EqualityFunctor` with tolerance, one can allow for plateaus that are not quite constant (this is often necessary with float pixel values). Pass vigra::EightNeighborCode or vigra::FourNeighborCode to determine the neighborhood where pixel values are compared.

Maximal regions are marked in the destination image with the given marker value (default is 1), all other destination pixels remain unchanged. `SrcAccessor::value_type` must be equality-comparable and less-comparable. A pixel or region touching the image border will never be marked as maximum or maximal plateau. Use localMaxima() with the appropriate options if you need that functionality. Likewise if you want to apply a threshold onl the fly. In fact, all functionality except for 'equality with tolerance' can be accessed via that function in a more readable way, so localMaxima() should be preferred. The function uses accessors.

Declarations:

use 3-dimensional arrays:

        namespace vigra {
            template <class T1, class C1, class T2, class C2,
                      class Neighborhood>
            void
            extendedLocalMaxima(MultiArrayView<3, T1, C1> src,
                                MultiArrayView<3, T2, C2> dest,
                                LocalMinmaxOptions const & options = LocalMinmaxOptions());

pass image iterators explicitly:

        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())
        }

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())
        }

Usage:

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

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

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

            T t;
        };

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

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

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

        // allow plateaus with tolerance
        maxima.init(0);
        vigra::extendedLocalMaxima(srcImageRange(src), destImage(maxima), 1.0,
                                   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.

This function finds regions of uniform pixel value whose neighboring regions are all have smaller values (maximal plateaus of arbitrary size). By default, the pixels in a plateau have exactly identical values. By passing an `EqualityFunctor` with tolerance, one can allow for plateaus that are not quite constant (this is often necessary with float pixel values). Pass the neighborhood where pixel values are compared. See extendedLocalMaxima() for more details.

© 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.9.0 (Tue Nov 6 2012)