cvrNoise.h

Go to the documentation of this file.

/*
 * Copyright (C) 2007
 * ITCR, Pablo Alvarado
 *
 *
 * 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   cvrNoise.h
 *         Contains the class cvr::noise, used to add noise to matrices, images
 *         channels or vectors in a controlled way.
 * \author Pablo Alvarado
 * \date   27.09.2007
 *
 * revisions ..: $Id: cvrNoise.h,v 1.2 2007/09/29 00:37:11 alvarado Exp $
 */

#ifndef _CVR_NOISE_H_
#define _CVR_NOISE_H_

#include "cvrMatrix.h"
#include "cvrMatrixProcessingInterface.h"
#include "cvrUnivariateContinuousDistribution.h"
#include "cvrUniformDiscreteDistribution.h"
#include "cvrFunctor.h"

namespace cvr {

  /**
   * Class noise.
   *
   * This class is used to add noise to an image.  In its default configuration
   * gaussian white noise is added to all pixels of the image.
   *
   * The random number generators provided to this class have to be continuous
   * distributions, which means they generate floating point values.  For the
   * fixed point types, like \c int and \c ubyte, the normalization constants
   * provided by cvr::typeInfo<T>::suggestedNorm() are multiplied to the values
   * generated by the distribution, prior to the addition to the actual value
   * of each matrix element.
   *
   * You can indicate with the parameter coverage how much of the pixels do you
   * want to be altered with noise, where the specific pixels chosen for
   * modification (if less than 100%) are also taken randomly.
   *
   * The following example uses noise to generate a sample image with different
   * degrees of noise.
   *
   * \code
   *   #include "cvrViewer2D.h"
   *   #include "cvrMath.h"
   *   #include "cvrNoise.h"
   *   #include "cvrNormalDistribution.h"
   *
   *   // ...
   *
   *   channel chnl,chnl2,nchnl;
   *   viewer2D view("Original");
   *
   *   noise noiser;
   *
   *   // create a black background with a grey square on which a
   *   // white square lies.
   *   chnl.assign(100,100,0.0f);   // 100x100 with black
   *   chnl.fill(0.5f,20,20,79,79); // leave a border of 20
   *   chnl.fill(1.0f,40,40,59,59); // the white square
   *
   *   // a large canvas to place 5x5 images like the channel just created
   *   chnl2.allocate(chnl.rows()*5,chnl.columns()*5);
   *
   *   // use a normal distribution
   *   normalDistribution nd;
   *   normalDistribution::parameters ndp;
   *
   *   for (int y=0;y<5;++y) {
   *     for (int x=0;x<5;++x) {
   *       ndp.sigma = (y*5 + x)/50.0;   // set the standard deviation
   *       nd.setParameters(ndp);        // into the normal distribution
   *       noiser.setNoiseGenerator(nd); // which has to be used
   *
   *       noiser.apply(chnl,nchnl);     // add the noise
   *
   *       // place the new noisy patch on the canvas
   *       chnl2.fill(nchnl,y*chnl.rows(),x*chnl.columns());
   *     }
   *   }
   *
   *   // show the canvas
   *   view.show(chnl2);
   * \endcode
   *
   * @see noise::parameters.
   *
   * @ingroup gNonLinearFilters
   */
  class noise : public functor,
                public matrixProcessingInterface<float>,
                public matrixProcessingInterface<double>,
                public matrixProcessingInterface<int>,
                public matrixProcessingInterface<ubyte> {
  public:
    /**
     * The parameters for the class noise
     */
    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();

      /**
       * 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 the complete name of the parameters class.
       */
      virtual const std::string& name() const;

      /**
       * 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
      // ------------------------------------------------

      /**
       * Percentage of the container elements that are selected for
       * modification.  The value has to be between 0.0f and 100.0f.
       *
       * If the value is greater than or equal to 100.0f, then all container
       * elements are subject to modification.  If the value is less than, or
       * equal to zero, then nothing is done to the container.
       *
       * Default value: 100.0f
       */
      float coverage;

      /**
       * Crop values.
       *
       * If crop is true, then the resulting values below zero are set
       * to zero, and the values above 1.0 for float and double, or
       * 255 for ubyte, or 65535 for int are set to those values.
       *
       * Default value: true
       */
      bool crop;


      /**
       * Parameters for the container element selector
       *
       * If \c coverage is less than 100%, then a uniform random number
       * generator is employed to select the container elements to be modified.
       * These are the parameters for the uniform discrete distribution class
       * employed in the pixel selection.
       *
       * The \c min and \c max members will be ignored, as they have to be set
       * new in each apply method, due to the possible container size change.
       *
       * Default value: default parameters.
       */
      uniformDiscreteDistribution::parameters selectorParameters;

      /**
       * Set the random number generator to be used.
       *
       * A copy of the given generator will be done.
       *
       * The default value is a normalDistribution with zero mean and a
       * standard deviation of 0.25.
       */
      bool setNoiseGenerator(univariateContinuousDistribution& generator);

      /**
       * Get the random number generator to be used.
       *
       * The default value is a normalDistribution with zero mean and a
       * standard deviation of 0.25.
       */
      univariateContinuousDistribution* getNoiseGenerator();

    protected:
      /**
       * Pointer to an instance of a continuous distribution instance.
       *
       * This instance is initialized with a normalDistribution object.
       */
      univariateContinuousDistribution* generator_;

    };

    /**
     * Default constructor
     */
    noise();

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

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

    /**
     * Destructor
     */
    virtual ~noise();

    /**
     * Operates on the given argument.
     *
     * @param srcdest fmatrix with the source data. The result
     *                will be left here too.
     * @return true if apply successful or false otherwise.
     */
    bool apply(fmatrix& srcdest) const;

    /**
     * Operates on the given argument.
     *
     * @param srcdest dmatrix with the source data. The result
     *                will be left here too.
     * @return true if apply successful or false otherwise.
     */
    bool apply(dmatrix& srcdest) const;

    /**
     * Operates on the given argument.
     *
     * @param srcdest imatrix with the source data. The result
     *                will be left here too.
     * @return true if apply successful or false otherwise.
     */
    bool apply(imatrix& srcdest) const;

    /**
     * Operates on the given argument.
     *
     * @param srcdest matrix<ubyte> with the source data. The result
     *                will be left here too.
     * @return true if apply successful or false otherwise.
     */
    bool apply(matrix<ubyte>& srcdest) const;

    /**
     * Operates on the given argument.
     *
     * @param srcdest fvector with the source data. The result
     *                will be left here too.
     * @return true if apply successful or false otherwise.
     */
    bool apply(fvector& srcdest) const;

    /**
     * Operates on the given argument.
     *
     * @param srcdest dvector with the source data. The result
     *                will be left here too.
     * @return true if apply successful or false otherwise.
     */
    bool apply(dvector& srcdest) const;

    /**
     * Operates on the given argument.
     *
     * @param srcdest ivector with the source data. The result
     *                will be left here too.
     * @return true if apply successful or false otherwise.
     */
    bool apply(ivector& srcdest) const;

    /**
     * Operates on a copy of the given arguments.
     *
     * @param src fmatrix with the source data.
     * @param dest fmatrix where the result will be left.
     * @return true if apply successful or false otherwise.
     */
    bool apply(const fmatrix& src, fmatrix& dest) const;

    /**
     * Operates on a copy of the given arguments.
     *
     * @param src dmatrix with the source data.
     * @param dest dmatrix where the result will be left.
     * @return true if apply successful or false otherwise.
     */
    bool apply(const dmatrix& src, dmatrix& dest) const;

    /**
     * Operates on a copy of the given arguments.
     *
     * @param src imatrix with the source data.
     * @param dest imatrix where the result will be left.
     * @return true if apply successful or false otherwise.
     */
    bool apply(const imatrix& src, imatrix& dest) const;

    /**
     * Operates on a copy of the given arguments.
     *
     * @param src matrix<ubyte> with the source data.
     * @param dest matrix<ubyte> where the result will be left.
     * @return true if apply successful or false otherwise.
     */
    bool apply(const matrix<ubyte>& src, matrix<ubyte>& dest) const;

    /**
     * Operates on a copy of the given arguments.
     *
     * @param src fvector with the source data.
     * @param dest fvector where the result will be left.
     * @return true if apply successful or false otherwise.
     */
    bool apply(const fvector& src, fvector& dest) const;

    /**
     * Operates on a copy of the given arguments.
     *
     * @param src dvector with the source data.
     * @param dest dvector where the result will be left.
     * @return true if apply successful or false otherwise.
     */
    bool apply(const dvector& src, dvector& dest) const;

    /**
     * Operates on a copy of the given arguments.
     *
     * @param src ivector with the source data.
     * @param dest ivector where the result will be left.
     * @return true if apply successful or false otherwise.
     */
    bool apply(const ivector& src, ivector& dest) const;


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

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

    /**
     * Returns the complete name of the functor class
     */
    virtual const std::string& name() const;

    /**
     * Returns a pointer to a clone of this functor.
     */
    virtual noise* clone() const;

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

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

    /**
     * Update parameters when new set is given.
     */
    bool updateParameters();

    /**
     * Set the random number generator to be used.
     */
    bool setNoiseGenerator(univariateContinuousDistribution& generator);

    /**
     * Get the random number generator to be used.
     *
     * The default value is a normalDistribution with zero mean and a
     * standard deviation of 0.25.
     */
    univariateContinuousDistribution* getNoiseGenerator();

  protected:
    /**
     * Returns used parameters
     */
    parameters& getParameters();

    /**
     * The noise generator
     */
    mutable univariateContinuousDistribution* generator_;

    /**
     * The generator for the coordinates
     */
    mutable uniformDiscreteDistribution uniform_;

  private:
    /**
     * The real thing!
     *
     * This method is the one used to add noise to all pixels
     *
     * @param srcdest the input image, on which noise will be added.
     */
    template<typename T>
    inline bool addNoise(matrix<T>& srcdest) const;

    /**
     * The real thing!
     *
     * This method is the one used to add noise to all pixels
     *
     * @param srcdest the input image, on which noise will be added.
     */
    template<typename T>
    inline bool addNoise(vector<T>& srcdest) const;

    /**
     * Crop the given value to the limits given by
     * cvr::typeInfo<T>::suggestedNorm()
     */
    template<typename T,typename U>
    inline T crop(const U val) const;

  };
}

#endif