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

details Local Minima and Maxima VIGRA

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.8.0 (20 Sep 2011)