cvrGeometricTransform.h

Go to the documentation of this file.

/*
 * Copyright (C) 2007
 * 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   cvrGeometricTransform.h
 *         Contains the classes cvr::geometricTransform<T> and
 *         cvr::geometricTransformBase,
 *         which are the parent classes of all geometric transformation
 *         classes, like rotation, scale, translation, etc.
 * \author Pablo Alvarado
 * \date   08.09.2007
 *
 * revisions ..: $Id: cvrGeometricTransform.h,v 1.3 2007/12/19 02:58:28 alvarado Exp $
 */

#ifndef _CVR_GEOMETRIC_TRANSFORM_H_
#define _CVR_GEOMETRIC_TRANSFORM_H_

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

namespace cvr {

  /**
   * Class geometricTransformBase.
   *
   * This is an abstract class parent of all functors that achieve geometric
   * transformation of images, like affine or homogeneous transformations.  It
   * contains the basic parameters that are not template dependent.
   *
   * @see geometricTransformBase::parameters.
   *
   * @ingroup gGeometricTrans
   */
  class geometricTransformBase : public functor {
  public:

    /**
     * Enumeration to specified how the dimensions of the resulting image
     * has to be computed
     */
    enum eResizeMode {
      KeepDimensions, /**< Keep the dimensions of the original image, including
                       *   the relative position of the origin.
                       */
      KeepOrigin,     /**< Keep the origin relative position, but adjust the
                       *   rest of the dimensions to hold the complete
                       *   transformed image.
                       */
      AdjustDimensions /**< Adjust the dimension of the resulting image to
                        *   contain the whole transformed image.  This implies
                        *   loosing the relative position of the origin.
                        */

    };

    /**
     * The parameters for the class geometricTransform
     */
    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
      // ------------------------------------------------
      /**
       * Resize mode.
       *
       * Choose how to deal with the final result dimensions.
       *
       * Default value: KeepDimensions
       */
      eResizeMode resizeMode;
    };

    /**
     * Default constructor
     */
    geometricTransformBase();

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

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

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

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

    /**
     * Alias for copy member
     * @param other the functor to be copied
     * @return a reference to this functor object
     */
    geometricTransformBase& operator=(const geometricTransformBase& 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 geometricTransformBase* clone() const = 0;

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

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

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

  };

  /**
   * Class geometricTransform.
   *
   * This is an abstract template class, parent of all functors that achieve
   * geometric transformation of images, like affine or homogeneous
   * transformations.
   *
   * The template parameter I indicates the interpolator type to be used.
   * The class provided must be inherited from cvr::fixedGridInterpolation.
   * Note that the interpolator works for one type of containers only, and
   * only that type will be supported by this class too.
   *
   * @see geometricTransform<I>::parameters.
   *
   * @ingroup gGeometricTrans
   */
  template<class I>
  class geometricTransform : public geometricTransformBase,
                             public matrixProcessingInterface<typename I::value_type> {
  public:
    typedef I interpolator_type;
    typedef typename I::value_type value_type;

    /**
     * The parameters for the class geometricTransform
     */
    class parameters : public geometricTransformBase::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 = 0;

      /**
       * Returns a pointer to a new instance of the parameters.
       */
      virtual parameters* newInstance() const = 0;

      /**
       * 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
      // ------------------------------------------------
      /**
       * Instance of the interpolator parameters to be used.
       *
       * Default value: default parameters instance
       */
      typename interpolator_type::parameters interpolatorParams;
    };

    /**
     * Default constructor
     */
    geometricTransform();

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

    /**
     * Copy constructor
     * @param other the object to be copied
     */
    geometricTransform(const geometricTransform<I>& other);

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

    /**
     * Transform geometrically the given image and leave the result on the
     * same container.
     *
     * @param srcdest matrix<T> with the source data. The result
     *                will be left here too.
     * @return true if apply successful or false otherwise.
     */
    virtual bool apply(matrix<value_type>& srcdest) const;

    /**
     * Transform geometrically the source image and leave the result on the
     * destination container.
     *
     * Operates on a copy of the given %parameters.
     *
     * @param src matrix<value_type> with the source data.
     * @param dest matrix<value_type> where the result will be left.
     * @return true if apply successful or false otherwise.
     */
    virtual bool apply(const matrix<value_type>& src,
                             matrix<value_type>& dest) const = 0;


    /**
     * Transform geometrically the given image and leave the result on the
     * same container.
     *
     * If the parameters specify to AdjustDimensions, then the offset
     * value will contain the relative position of the \a srcdest
     * origin with respect to the original image coordinate system.
     * To all other resize policies, the value of offset is set to
     * (0,0).
     *
     * @param srcdest matrix<T> with the source data. The result
     *                will be left here too.
     * @param offset position of the origin of the result with respect to the
     *               coordinate system of the original image.
     * @return true if apply successful or false otherwise.
     */
    virtual bool apply(matrix<value_type>& srcdest,
                       fpoint& offset) const;

    /**
     * Transform geometrically the source image and leave the result on the
     * destination container.
     *
     *
     * If the parameters specify to AdjustDimensions, then the offset
     * value will contain the relative position of the \a srcdest
     * origin with respect to the original image coordinate system.
     * To all other resize policies, the value of offset is set to
     * (0,0).
     *
     * @param src matrix<value_type> with the source data.
     * @param dest matrix<value_type> where the result will be left.
     * @param offset position of the origin of the result with respect to the
     *               coordinate system of the original image.
     * @return true if apply successful or false otherwise.
     */
    virtual bool apply(const matrix<value_type>& src,
                             matrix<value_type>& dest,
                             fpoint& offset) const = 0;

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

    /**
     * Alias for copy member
     * @param other the functor to be copied
     * @return a reference to this functor object
     */
    geometricTransform& operator=(const geometricTransform<I>& 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 geometricTransform<I>* clone() const = 0;

    /**
     * Returns a pointer to a new instance of this functor.
     */
    virtual geometricTransform<I>* newInstance() const = 0;

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

    /**
     * Update parameters instance
     */
    virtual bool updateParameters();

    /**
     * Return a read-writable reference to the internal interpolator object.
     */
    interpolator_type& getInterpolator();

    /**
     * Return a read-only reference to the internal interpolator object.
     */
    const interpolator_type& getInterpolator() const;

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

    /**
     * Interpolator instance with the appropriate parameters.
     *
     * The updateParameters method will ensure that the interpolator
     * parameters are set appropriatelly
     */
    interpolator_type interpolator_;

  }; // class geometricTransform<I>

  /**
   * Read the resize mode
   *
   * @ingroup gStorable
   */
  bool read(ioHandler& handler,geometricTransformBase::eResizeMode& data);

  /**
   * Write the resize mode
   *
   * @ingroup gStorable
   */
  bool write(ioHandler& handler,
             const geometricTransformBase::eResizeMode& data);
} // namespace cvr

#include "cvrGeometricTransform_template.h"

#endif