ImageDistribution.hh

/*
This file is part of the BIAS library (Basic ImageAlgorithmS).

Copyright (C) 2003-2009    (see file CONTACT for details)
  Multimediale Systeme der Informationsverarbeitung
  Institut fuer Informatik
  Christian-Albrechts-Universitaet Kiel


BIAS is free software; you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation; either version 2.1 of the License, or
(at your option) any later version.

BIAS is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License
along with BIAS; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
*/

#ifndef __IMAGE_DISTRIBUTION_HH__
#define __IMAGE_DISTRIBUTION_HH__

// std
#include <iostream>
#include <math.h>
#include <vector>

// BIAS
#include <Base/Math/Vector2.hh>
#include <Base/Image/Image.hh>
#include <Base/Image/ImageIO.hh>

namespace BIAS
{
  /**
   * @brief Maps a set of input images to a given output image so that the space
   *        in the output image area is optimally used.
   *
   * The images are aligned in a grid so that minimal space is wasted. The
   * intended use of this class is texture fusion.
   *
   * @author rwulff
   * @date   03/2011
   */
  class BIASImageUtilsBase_EXPORT ImageDistribution
  {

  public:

    /**
     * @brief Maps the given images to the output image, which is of a fixed
     *        size.
     *
     * Scaling is performed by nearest neighbour backward mapping.
     *
     * @warning Assumes that all input images have the same size and channel
     *          count. This is not checked!!!
     *
     * @param[in]  inputImages
     *             the input images. must all have the same size and channel
     *             count (not checked!)
     * @param[out] outputImage
     *             the destination image. must have (width, height > 0). channel
     *             count must be same as input images.
     * @param[out] imagePositionsPixel
     *             upper left corner of each input image in the output image
     */
    static
    void MapImagesToFixedSize(std::vector<Image<unsigned char> > &inputImages,
                              Image<unsigned char> &outputImage,
                              std::vector<Vector2<unsigned int> > &imagePositionsPixel);
    static
    void MapImagesToFixedSize(const std::vector<Image<unsigned char>*> &inputImages,
                              Image<unsigned char> &outputImage,
                              std::vector<Vector2<unsigned int> > &imagePositionsPixel);
    /**
     * @brief Maps the given images to a square without scaling the images.
     *
     * The images are distributed to utilize a square area optimally. The output
     * image will be sized so that it can hold all images.
     *
     * @warning Assumes that all input images have the same size and channel
     *          count. This is not checked!!!
     *
     * @param[in]  inputImages
     *             the input images. must all have the same size and channel
     *             count (not checked!)
     * @param[out] outputImage
     *             the destination image. size is ignored. channel count must be
     *             same as input images
     * @param[out] imagePositionsPixel
     *             upper left corner of each input image in the output image
     */
    static
    void MapImagesToSquare(std::vector<Image<unsigned char> > &inputImages,
                           Image<unsigned char> &outputImage,
                           std::vector<Vector2<unsigned int> > &imagePositionsPixel);
    static
    void MapImagesToSquare(const std::vector<Image<unsigned char>*> &inputImage,
                           Image<unsigned char> &outputImage,
                           std::vector<Vector2<unsigned int> > &imagePositionsPixel);
    
  private:

    /**
     * @brief Computes the number of rows and columns of the grid and the scale
     *        factor.
     *
     * @todo early termination possible when scales lower again
     * @todo iteration in the other direction will find the maximum earlier if
     *       early termination is used
     *
     * @param[in]  numImages
     *             number of input images
     * @param[in]  widthIn
     *             width of each input image
     * @param[in]  heightIn
     *             height of each input image
     * @param[in]  heightOut
     *             height of the output image
     * @param[in]  heightOut
     *             height of the output image
     * @param[out] numCols
     *             the number of columns in the grid
     * @param[out] numRows
     *             the number of rows in the grid
     * @param[out] scale
     *             the scale factor
     */
    static
    void ComputeGridAndScale(unsigned int numImages,
                             unsigned int widthIn,
                             unsigned int heightIn,
                             unsigned int widthOut,
                             unsigned int heightOut,
                             unsigned int &numCols,
                             unsigned int &numRows,
                             float &scale);

    /**
     * @brief For each input image computes the upper left corner in the output
     *        image.
     *
     * @param[in]  numImages
     *             number of input images
     * @param[in]  widthIn
     *             width of each input image
     * @param[in]  heightIn
     *             height of each input image
     * @param[in]  numCols
     *             the number of columns in the grid
     * @param[in]  numRows
     *             the number of rows in the grid
     * @param[in]  scale
     *             the scale factor
     * @param[out] imagePositionsGrid
     *             abstract position of each input image in the grid (col, row)
     * @param[out] imagePositionsPixel
     *             upper left corner position of each input image in pixels
     * @param[out] imageIndices
     *             inverse mapping of imagePositionsGrid: stores corresponding
     *             image index for each grid position. -1 == no image at this
     *             position. first index is row, second is column
     */
    static
    void ComputeImagePositions(unsigned int numImages,
                               unsigned int widthIn,
                               unsigned int heightIn,
                               unsigned int numRows,
                               unsigned int numCols,
                               float scale,
                               std::vector<Vector2<unsigned int> > &imagePositionsGrid,
                               std::vector<Vector2<unsigned int> > &imagePositionsPixel,
                               std::vector<std::vector<int> > &imageIndices);

  }; // end of class
} // end of namespace

#endif // __IMAGE_DISTRIBUTION_HH__