cvrLabelAdjacencyMap.h

Go to the documentation of this file.

/*
 * Copyright (C) 1998
 * Lehrstuhl fuer Technische Informatik, RWTH-Aachen, Germany
 *
 *
 * This file is part of the Computer Vision and Robotics Library (CVR-Lib)
 *
 * The CVR-Lib is free software; you can redistribute it and/or
 * modify it under the terms of the BSD License.
 *
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 * 1. Redistributions of source code must retain the above copyright notice,
 *    this list of conditions and the following disclaimer.
 *
 * 2. Redistributions in binary form must reproduce the above copyright notice,
 *    this list of conditions and the following disclaimer in the documentation
 *    and/or other materials provided with the distribution.
 *
 * 3. Neither the name of the authors nor the names of its contributors may be
 *    used to endorse or promote products derived from this software without
 *    specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 */



/**
 * \file   cvrLabelAdjacencyMap.h
 * \author Pablo Alvarado
 * \date   18.11.2002
 *
 * $Id: cvrLabelAdjacencyMap.h,v 1.8 2006/05/12 15:09:55 doerfler Exp $
 */

#ifndef _CVR_LABEL_ADJACENCY_MAP_H_
#define _CVR_LABEL_ADJACENCY_MAP_H_

#include "cvrFunctor.h"
#include "cvrImage.h"
#include <map>

namespace cvr {

  /**
   * Visualize a label mask in a color image
   *
   * This class draws a color image using as input a labeled mask.  The
   * colors used for each label are chosen based on the adjacency, so that
   * two neighbor labels never get the same color.
   *
   * You can choose the kind of neighborhood used (4 or 8 neighborhood) and
   * the number of colors you want to use.
   *
   * Other classes, like the viewers, may require partial computations, like
   * the adjacency graph, which is a kind of
   *
   * @ingroup gVisualization
   */
  class labelAdjacencyMap : public functor {

  public:

    /**
     * Default color palette
     *
     * {cvr::Black,  cvr::Red,  cvr::Green,   cvr::Blue,
     *  cvr::Yellow, cvr::Cyan, cvr::Magenta, cvr::DarkOrange,
     *  cvr::Lemon,  cvr::Violet}
     */
    static const palette defaultPalette;

    /**
     * The parameters for the class labelAdjacencyMap
     */
    class parameters : public functor::parameters {

    public:

      /**
       * default constructor
       */
      parameters();

      /**
       * copy constructor
       * @param other the parameters object to be copied
       */
      parameters(const parameters& other);

      /**
       * destructor
       */
      ~parameters();

      /**
       * returns name of this type
       */
      virtual const std::string& name() const;

      /**
       * copy the contents of a parameters object
       * @param other the parameters object to be copied
       * @return a reference to this parameters object
       */
      parameters& copy(const parameters& other);

      /**
       * copy the contents of a parameters object
       * @param other the parameters object to be copied
       * @return a reference to this parameters object
       */
      parameters& operator=(const parameters& other);

      /**
       * returns a pointer to a clone of the parameters
       */
      virtual parameters* clone() const;

      /**
       * returns a pointer to a new instance of the parameters
       */
      virtual parameters* newInstance() const;

      /**
       * write the parameters in the given ioHandler
       * @param handler the ioHandler to be used
       * @param complete if true (the default) the enclosing begin/end will
       *        be also written, otherwise only the data block will be written.
       * @return true if write was successful
       */
      virtual bool write(ioHandler& handler,const bool complete=true) const;

      /**
       * read the parameters from the given ioHandler
       * @param handler the ioHandler to be used
       * @param complete if true (the default) the enclosing begin/end will
       *        be also written, otherwise only the data block will be written.
       * @return true if write was successful
       */
      virtual bool read(ioHandler& handler,const bool complete=true);

      // ------------------------------------------------
      // the parameters
      // ------------------------------------------------

      /**
       * If true, the mininum number of colors will be used, which will depend
       * on the neighborhood used.  (a max of 4 colors is required for a
       * 4 neighborhood, and a max of 8 color for a 8 neighborhood).
       *
       * If false, all colors in the palette might be used.
       *
       * Default: false
       */
      bool minColors;

      /**
       * The colors used to denote the labels.  Note that the assigment is not
       * 1 to 1, but will be done depending on the adjacency of the labels.
       *
       * Default: {cvr::Black,cvr::Red,cvr::Green,cvr::Blue,cvr::Yellow,
       *           cvr::Cyan,cvr::Magenta,cvr::DarkOrange,cvr::Lemon,
       *           cvr::Violet}
       *
       * This default palette can be accessed anytime as
       * cvr::labelAdjacencyMap::defaultPalette
       */
      palette thePalette;

      /**
       * Neighborhood used.
       *
       * Valid values are 4 and 8.  Other values will be considered as
       * 8-neighborhood.
       *
       * Default value: 8
       */
      int neighborhood;

    };


    /**
     * This auxiliary class stores a simple adjacency graph between labels, in
     * which only the edges between the nodes contain data.
     *
     * It uses std::map to store in a memory friendly way a sparse
     * "adjacency" matrix.
     *
     * In principle, only the "neighbors_" attribute of the class could also be
     * used as "graph" representation, but this class allows for some common
     * tasks with that container structure.
     */
    class graph {
      friend class labelAdjacencyMap;
    public:
      /**
       * Construct an empty graph
       */
      graph();

      /**
       * Increment the value stored in the edge between the nodes identified by
       * row and col.  If you visualize the graph as a matrix, this increments
       * the element at (row,col).
       */
      void acc(const int row,const int col);

      /**
       * Remove all data of graph
       */
      void clear();

      /**
       * Find the largest row id used
       */
      int findMaxId() const;

      /**
       * Find the largest row id used
       */
      int findMinId() const;

      /**
       * Find the largest row id used
       */
      void findMinMaxIds(int& minRow,int& maxRow) const;

      /**
       * Each node in nodes_ has a "list" of ids of the neighbors of that node.
       * There exist therefore an edge for each element in a list of this type.
       */
      typedef std::map<int,int> edges_type;

      /**
       * Double hash for the neighbors
       */
      typedef std::map<int, edges_type > nodes_type;

    private:
      /**
       * The neighbors is a sort of list of lists of neighbors for each
       * label.
       *
       * The key of the hash is a label/region id, and the data is a
       * hash of the neighbors, also keyed by the region/label id and
       * as data the graph usually will contain the number of elements
       * in common, i.e. the number of times acc() was called.
       */
      nodes_type nodes_;
    };


    /**
     * default constructor
     */
    labelAdjacencyMap();

    /**
     * Construct a functor using the given parameters
     */
    labelAdjacencyMap(const parameters& par);

    /**
     * copy constructor
     * @param other the object to be copied
     */
    labelAdjacencyMap(const labelAdjacencyMap& other);

    /**
     * destructor
     */
    virtual ~labelAdjacencyMap();

    /**
     * returns the name of this type ("labelAdjacencyMap")
     */
    virtual const std::string& name() const;

    /**
     * Compute the adjacency map of the given 8-bit labeled mask.
     *
     * @param src channel8 with the source data.
     * @param dest image where the result will be left.
     * @return true if apply successful or false otherwise.
     */
    bool apply(const matrix<ubyte>& src,image& dest) const;

    /**
     * Compute the adjacency map of the given 32-bit labeled mask.
     *
     * The input data cannot have label ids less than zero and
     * internally a look-up table of the size equal to the maximum
     * value in the input data plus one will be created.  So, it will
     * be assumed that the input mask has all its labels with low positive ids.
     *
     * @param src matrix<int> with the source data.
     * @param dest image where the result will be left.
     * @return true if apply successful or false otherwise.
     */
    bool apply(const matrix<int>& src,image& dest) const;

    /**
     * copy data of "other" functor.
     * @param other the functor to be copied
     * @return a reference to this functor object
     */
    labelAdjacencyMap& copy(const labelAdjacencyMap& other);

    /**
     * alias for copy member
     * @param other the functor to be copied
     * @return a reference to this functor object
     */
    labelAdjacencyMap& operator=(const labelAdjacencyMap& other);

    /**
     * returns a pointer to a clone of this functor.
     */
    virtual labelAdjacencyMap* clone() const;

    /**
     * returns a pointer to a new instance of this functor.
     */
    virtual labelAdjacencyMap* newInstance() const;

    /**
     * returns used parameters
     */
    const parameters& getParameters() const;

    /**
     * Compute the adjacency graph of labels for the given labeled mask.
     */
    bool adjacency(const matrix<ubyte>& mask,graph& dest) const;

    /**
     * Compute the adjacency graph of labels for the given labeled mask.
     */
    bool adjacency(const matrix<int>& mask,graph& dest) const;

    /**
     * Compute a transformation Look-up Table that maps the id of a label to
     * the corresponding entry in the parameters palette.
     */
    bool computePalette(const graph& adj,palette& pal) const;


    /**
     * Compute a transformation Look-up Table that maps the id of a label to
     * the corresponding entry in the parameters palette.
     */
    bool computePalette(const graph& adj,ivector& pal) const;

  protected:

    /**
     * Compute a "palette" from the graph, which can be accessed with the
     * id of a label to get the corresponding color in the map.
     *
     * The minimum number of colors will be used.
     */
    bool computeMinPalette(const graph& adj,palette& pal) const;


    /**
     * Compute a transformation Look-up Table that maps the id of a label to
     * the corresponding entry in the parameters palette.
     *
     * The minimum number of colors will be used.
     */
    bool computeMinPalette(const graph& adj,ivector& pal) const;

    /**
     * Compute a "palette" from the graph, which can be accessed with the
     * id of a label to get the corresponding color in the map.
     *
     * The maximum number of colors will be used.
     */
    bool computeMaxPalette(const graph& adj,palette& pal) const;

    /**
     * Compute a transformation Look-up Table that maps the id of a label to
     * the corresponding entry in the parameters palette.
     *
     * The maximum number of colors will be used.
     */
    bool computeMaxPalette(const graph& adj,ivector& pal) const;

  };
}

#endif