/*****************************************************************************/

// Copyright 2008 Adobe Systems Incorporated

// All Rights Reserved.

//

// NOTICE:  Adobe permits you to use, modify, and distribute this file in

// accordance with the terms of the Adobe license agreement accompanying it.

/*****************************************************************************/

/* $Id: //mondo/dng_sdk_1_4/dng_sdk/source/dng_lens_correction.h#2 $ */ 

/* $DateTime: 2012/08/02 06:09:06 $ */

/* $Change: 841096 $ */

/* $Author: erichan $ */

/** \file

 * Opcodes to fix lens aberrations such as geometric distortion, lateral chromatic

 * aberration, and vignetting (peripheral illumination falloff).

 */

/*****************************************************************************/

#ifndef __dng_lens_correction__

#define __dng_lens_correction__

/*****************************************************************************/

#include "dng_1d_function.h"

#include "dng_matrix.h"

#include "dng_memory.h"

#include "dng_opcodes.h"

#include "dng_pixel_buffer.h"

#include "dng_point.h"

#include "dng_resample.h"

#include "dng_sdk_limits.h"

#include <vector>

/*****************************************************************************/

/// \brief Abstract base class holding common warp opcode parameters (e.g.,

/// number of planes, optical center) and common warp routines.

class dng_warp_params

  {

  public:

    // Number of planes to be warped. Must be either 1 or equal to the

    // number of planes of the image to be processed. If set to 1, then a

    // single set of warp parameters applies to all planes of the image.

    // fPlanes must be at least 1 and no greater than kMaxColorPlanes (see

    // dng_sdk_limits.h).

    uint32 fPlanes;

    // The optical center of the lens in normalized [0,1] coordinates with

    // respect to the image's active area. For example, a value of (0.5,

    // 0.5) indicates that the optical center of the lens is at the center

    // of the image's active area. A normalized radius of 1.0 corresponds to

    // the distance from fCenter to the farthest corner of the image's

    // active area. Each component of fCenter must lie in the range [0,1].

    dng_point_real64 fCenter;

  public:

    /// Create empty (invalid) warp parameters.

    dng_warp_params ();

    /// Create warp parameters with specified number of planes and image

    /// center.

    ///

    /// \param planes The number of planes of parameters specified: It must

    /// be either 1 or equal to the number of planes of the image to be

    /// processed.

    ///

    /// \param fCenter The image center in relative coordinates.

    dng_warp_params (uint32 planes,

             const dng_point_real64 &fCenter);

    virtual ~dng_warp_params ();

    /// Is the entire correction a NOP for all planes?

    virtual bool IsNOPAll () const;

    /// Is the entire correction a NOP for the specified plane?

    virtual bool IsNOP (uint32 plane) const;

    /// Is the radial correction a NOP for all planes?

    virtual bool IsRadNOPAll () const;

    /// Is the radial correction a NOP for the specified plane?

    virtual bool IsRadNOP (uint32 plane) const;

    /// Is the tangential correction a NOP for all planes?

    virtual bool IsTanNOPAll () const;

    /// Is the tangential correction a NOP for the specified plane?

    virtual bool IsTanNOP (uint32 plane) const;

    /// Do these warp params appear valid?

    virtual bool IsValid () const;

    /// Are these warp params valid for the specified negative?

    virtual bool IsValidForNegative (const dng_negative &negative) const;

    /// Propagate warp parameters from first plane to all other planes.

    virtual void PropagateToAllPlanes (uint32 totalPlanes) = 0;

    /// Evaluate the 1D radial warp function for the specified plane.

    /// Parameter r is the destination (i.e., corrected) normalized radius,

    /// i.e., the normalized Euclidean distance between a corrected pixel

    /// position and the optical center in the image. r lies in the range

    /// [0,1]. The returned result is non-negative.

    virtual real64 Evaluate (uint32 plane,

                 real64 r) const = 0;

    /// Compute and return the inverse of Evaluate () above. The base

    /// implementation uses Newton's method to perform the inversion.

    /// Parameter r is the source (i.e., uncorrected) normalized radius,

    /// i.e., normalized Euclidean distance between a corrected pixel

    /// position and the optical center in the image. Both r and the

    /// computed result are non-negative.

    virtual real64 EvaluateInverse (uint32 plane,

                    real64 r) const;

    /// Evaluate the 1D radial warp ratio function for the specified plane.

    /// Parameter r2 is the square of the destination (i.e., corrected)

    /// normalized radius, i.e., the square of the normalized Euclidean

    /// distance between a corrected pixel position and the optical center

    /// in the image. r2 must lie in the range [0,1]. Note that this is

    /// different than the Evaluate () function, above, in that the argument

    /// to EvaluateRatio () is the square of the radius, not the radius

    /// itself. The returned result is non-negative. Mathematically,

    /// EvaluateRatio (r * r) is the same as Evaluate (r) / r.

    virtual real64 EvaluateRatio (uint32 plane,

                    real64 r2) const = 0;

    /// Evaluate the 2D tangential warp for the specified plane. Parameter

    /// r2 is the square of the destination (i.e., corrected) normalized

    /// radius, i.e., the square of the normalized Euclidean distance

    /// between a corrected pixel position P and the optical center in the

    /// image. r2 must lie in the range [0,1]. diff contains the vertical

    /// and horizontal Euclidean distances (in pixels) between P and the

    /// optical center. diff2 contains the squares of the vertical and

    /// horizontal Euclidean distances (in pixels) between P and the optical

    /// center. The returned result is the tangential warp offset, measured

    /// in pixels.

    virtual dng_point_real64 EvaluateTangential (uint32 plane,

                           real64 r2,

                           const dng_point_real64 &diff,

                           const dng_point_real64 &diff2) const = 0;

    /// Evaluate the 2D tangential warp for the specified plane. diff

    /// contains the vertical and horizontal Euclidean distances (in pixels)

    /// between the destination (i.e., corrected) pixel position and the

    /// optical center in the image. The returned result is the tangential

    /// warp offset, measured in pixels.

    dng_point_real64 EvaluateTangential2 (uint32 plane,

                        const dng_point_real64 &diff) const;

    /// Evaluate the 2D tangential warp for the specified plane. Parameter

    /// r2 is the square of the destination (i.e., corrected) normalized

    /// radius, i.e., the square of the normalized Euclidean distance

    /// between a corrected pixel position P and the optical center in the

    /// image. r2 must lie in the range [0,1]. diff contains the vertical

    /// and horizontal Euclidean distances (in pixels) between P and the

    /// optical center. The returned result is the tangential warp offset,

    /// measured in pixels.

    dng_point_real64 EvaluateTangential3 (uint32 plane,

                        real64 r2,

                        const dng_point_real64 &diff) const;

    /// Compute and return the maximum warped radius gap. Let D be a

    /// rectangle in a destination (corrected) image. Let rDstFar and

    /// rDstNear be the farthest and nearest points to the image center,

    /// respectively. Then the specified parameter maxDstGap is the

    /// Euclidean distance between rDstFar and rDstNear. Warp D through this

    /// warp function to a closed and bounded (generally not rectangular)

    /// region S. Let rSrcfar and rSrcNear be the farthest and nearest

    /// points to the image center, respectively. This routine returns a

    /// value that is at least (rSrcFar - rSrcNear).

    virtual real64 MaxSrcRadiusGap (real64 maxDstGap) const = 0;

    /// Compute and return the maximum warped tangential gap. minDst is the

    /// top-left pixel of the image in normalized pixel coordinates. maxDst

    /// is the bottom-right pixel of the image in normalized pixel

    /// coordinates. MaxSrcTanGap () computes the maximum absolute shift in

    /// normalized pixels in the horizontal and vertical directions that can

    /// occur as a result of the tangential warp.

    virtual dng_point_real64 MaxSrcTanGap (dng_point_real64 minDst,

                         dng_point_real64 maxDst) const = 0;

    /// Debug parameters.

    virtual void Dump () const;

  };

/*****************************************************************************/

/// \brief Warp parameters for pinhole perspective rectilinear (not fisheye)

/// camera model. Supports radial and tangential (decentering) distortion

/// correction parameters.

///

/// Note the restrictions described below.

class dng_warp_params_rectilinear: public dng_warp_params

  {

  public:

    // Radial and tangential polynomial coefficients. These define a warp

    // from corrected pixel coordinates (xDst, yDst) to uncorrected pixel

    // coordinates (xSrc, ySrc) for each plane P as follows:

    //

    // Let kr0 = fRadParams [P][0]

    //     kr1 = fRadParams [P][1]

    //     kr2 = fRadParams [P][2]

    //     kr3 = fRadParams [P][3]

    //

    //     kt0 = fTanParams [P][0]

    //     kt1 = fTanParams [P][1]

    //

    // Let (xCenter, yCenter) be the optical image center (see fCenter,

    // below) expressed in pixel coordinates. Let maxDist be the Euclidean

    // distance (in pixels) from (xCenter, yCenter) to the farthest image

    // corner.

    //

    // First, compute the normalized distance of the corrected pixel

    // position (xDst, yDst) from the image center:

    //

    //     dx = (xDst - xCenter) / maxDist

    //     dy = (yDst - yCenter) / maxDist

    //

    //     r^2 = dx^2 + dy^2

    //

    // Compute the radial correction term:

    //

    //     ratio = kr0 + (kr1 * r^2) + (kr2 * r^4) + (kr3 * r^6)

    //

    //     dxRad = dx * ratio

    //     dyRad = dy * ratio

    //

    // Compute the tangential correction term:

    //

    //     dxTan = (2 * kt0 * dx * dy) + kt1 * (r^2 + 2 * dx^2)

    //     dyTan = (2 * kt1 * dx * dy) + kt0 * (r^2 + 2 * dy^2)

    //

    // Compute the uncorrected pixel position (xSrc, ySrc):

    //

    //     xSrc = xCenter + (dxRad + dxTan) * maxDist

    //     ySrc = yCenter + (dyRad + dyTan) * maxDist

    //

    // Mathematical definitions and restrictions:

    //

    // Let { xSrc, ySrc } = f (xDst, yDst) be the warp function defined

    // above.

    //

    // Let xSrc = fx (xDst, yDst) be the x-component of the warp function.

    // Let ySrc = fy (xDst, yDst) be the y-component of the warp function.

    //

    // f (x, y) must be an invertible function.

    //

    // fx (x, y) must be an increasing function of x.

    // fy (x, y) must be an increasing function of x.

    //

    // The parameters kr0, kr1, kr2, and kr3 must define an increasing

    // radial warp function. Specifically, let w (r) be the radial warp

    // function:

    //

    //     w (r) = (kr0 * r) + (kr1 * r^3) + (kr2 * r^5) + (kr3 * r^7).

    //

    // w (r) must be an increasing function.

    dng_vector fRadParams [kMaxColorPlanes];

    dng_vector fTanParams [kMaxColorPlanes];

  public:

    /// Create empty (invalid) rectilinear warp parameters.

    dng_warp_params_rectilinear ();

    /// Create rectilinear warp parameters with the specified number of

    /// planes, radial component terms, tangential component terms, and

    /// image center in relative coordinates.

    dng_warp_params_rectilinear (uint32 planes,

                   const dng_vector radParams [],

                   const dng_vector tanParams [],

                   const dng_point_real64 &fCenter);

    virtual ~dng_warp_params_rectilinear ();

    // Overridden methods.

    virtual bool IsRadNOP (uint32 plane) const;

    virtual bool IsTanNOP (uint32 plane) const;

    virtual bool IsValid () const;

    virtual void PropagateToAllPlanes (uint32 totalPlanes);

    virtual real64 Evaluate (uint32 plane,

                 real64 r) const;

    virtual real64 EvaluateRatio (uint32 plane,

                    real64 r2) const;

    virtual dng_point_real64 EvaluateTangential (uint32 plane,

                           real64 r2,

                           const dng_point_real64 &diff,

                           const dng_point_real64 &diff2) const;

    virtual real64 MaxSrcRadiusGap (real64 maxDstGap) const;

    virtual dng_point_real64 MaxSrcTanGap (dng_point_real64 minDst,

                         dng_point_real64 maxDst) const;

    virtual void Dump () const;

  };

/*****************************************************************************/

/// \brief Warp parameters for fisheye camera model (radial component only).

/// Note the restrictions described below.

class dng_warp_params_fisheye: public dng_warp_params

  {

  public:

    // Radial warp coefficients. These define a warp from corrected pixel

    // coordinates (xDst, yDst) to uncorrected pixel coordinates (xSrc,

    // ySrc) for each plane P as follows:

    //

    // Let kr0 = fRadParams [P][0]

    //     kr1 = fRadParams [P][1]

    //     kr2 = fRadParams [P][2]

    //     kr3 = fRadParams [P][3]

    //

    // Let (xCenter, yCenter) be the optical image center (see fCenter,

    // below) expressed in pixel coordinates. Let maxDist be the Euclidean

    // distance (in pixels) from (xCenter, yCenter) to the farthest image

    // corner.

    //

    // First, compute the normalized distance of the corrected pixel

    // position (xDst, yDst) from the image center:

    //

    //     dx = (xDst - xCenter) / maxDist

    //     dy = (yDst - yCenter) / maxDist

    //

    //     r = sqrt (dx^2 + dy^2)

    //

    // Compute the radial correction term:

    //

    //     t = atan (r)

    //

    //     rWarp = (kr0 * t) + (kr1 * t^3) + (kr2 * t^5) + (kr3 * t^7)

    //

    //     ratio = rWarp / r

    //

    //     dxRad = dx * ratio

    //     dyRad = dy * ratio

    //

    // Compute the uncorrected pixel position (xSrc, ySrc):

    //

    //     xSrc = xCenter + (dxRad * maxDist)

    //     ySrc = yCenter + (dyRad * maxDist)

    //

    // The parameters kr0, kr1, kr2, and kr3 must define an increasing

    // radial warp function. Specifically, let w (r) be the radial warp

    // function:

    //

    //     t = atan (r)

    //

    //     w (r) = (kr0 * t) + (kr1 * t^3) + (kr2 * t^5) + (kr3 * t^7).

    //

    // w (r) must be an increasing function.

    dng_vector fRadParams [kMaxColorPlanes];

  public:

    /// Create empty (invalid) fisheye warp parameters.

    dng_warp_params_fisheye ();

    /// Create rectilinear warp parameters with the specified number of

    /// planes, radial component terms, and image center in relative

    /// coordinates.

    dng_warp_params_fisheye (uint32 planes,

                 const dng_vector radParams [],

                 const dng_point_real64 &fCenter);

    virtual ~dng_warp_params_fisheye ();

    // Overridden methods.

    virtual bool IsRadNOP (uint32 plane) const;

    virtual bool IsTanNOP (uint32 plane) const;

    virtual bool IsValid () const;

    virtual void PropagateToAllPlanes (uint32 totalPlanes);

    virtual real64 Evaluate (uint32 plane,

                 real64 r) const;

    virtual real64 EvaluateRatio (uint32 plane,

                    real64 r2) const;

    virtual dng_point_real64 EvaluateTangential (uint32 plane,

                           real64 r2,

                           const dng_point_real64 &diff,

                           const dng_point_real64 &diff2) const;

    virtual real64 MaxSrcRadiusGap (real64 maxDstGap) const;

    virtual dng_point_real64 MaxSrcTanGap (dng_point_real64 minDst,

                         dng_point_real64 maxDst) const;

    virtual void Dump () const;

  };

/*****************************************************************************/

/// \brief Warp opcode for pinhole perspective (rectilinear) camera model.

class dng_opcode_WarpRectilinear: public dng_opcode

  {

  protected:

    dng_warp_params_rectilinear fWarpParams;

  public:

    dng_opcode_WarpRectilinear (const dng_warp_params_rectilinear &params,

                  uint32 flags);

    explicit dng_opcode_WarpRectilinear (dng_stream &stream);

    // Overridden methods.

    virtual bool IsNOP () const;

    virtual bool IsValidForNegative (const dng_negative &negative) const;

    virtual void PutData (dng_stream &stream) const;

    virtual void Apply (dng_host &host,

              dng_negative &negative,

              AutoPtr<dng_image> &image);

  protected:

    static uint32 ParamBytes (uint32 planes);

  };

/*****************************************************************************/

/// \brief Warp opcode for fisheye camera model.

class dng_opcode_WarpFisheye: public dng_opcode

  {

  protected:

    dng_warp_params_fisheye fWarpParams;

  public:

    dng_opcode_WarpFisheye (const dng_warp_params_fisheye &params,

                uint32 flags);

    explicit dng_opcode_WarpFisheye (dng_stream &stream);

    // Overridden methods.

    virtual bool IsNOP () const;

    virtual bool IsValidForNegative (const dng_negative &negative) const;

    virtual void PutData (dng_stream &stream) const;

    virtual void Apply (dng_host &host,

              dng_negative &negative,

              AutoPtr<dng_image> &image);

  protected:

    static uint32 ParamBytes (uint32 planes);

  };

/*****************************************************************************/

/// \brief Radially-symmetric vignette (peripheral illuminational falloff)

/// correction parameters.

class dng_vignette_radial_params

  {

  public:

    static const uint32 kNumTerms = 5;

  public:

    // Let v be an uncorrected pixel value of a pixel p in linear space.

    //

    // Let r be the Euclidean distance between p and the optical center.

    //

    // Compute corrected pixel value v' = v * g, where g is the gain.

    //

    // Let k0 = fParams [0]

    // Let k1 = fParams [1]

    // Let k2 = fParams [2]

    // Let k3 = fParams [3]

    // Let k4 = fParams [4]

    //

    // Gain g = 1 + (k0 * r^2) + (k1 * r^4) + (k2 * r^6) + (k3 * r^8) + (k4 * r^10)

    dng_std_vector<real64> fParams;

    dng_point_real64 fCenter;

  public:

    dng_vignette_radial_params ();

    dng_vignette_radial_params (const dng_std_vector<real64> &params,

                  const dng_point_real64 &center);

    bool IsNOP () const;

    bool IsValid () const;

    // For debugging.

    void Dump () const;

  };

/*****************************************************************************/

/// \brief Radially-symmetric lens vignette correction opcode.

class dng_opcode_FixVignetteRadial: public dng_inplace_opcode

  {

  protected:

    dng_vignette_radial_params fParams;

    uint32 fImagePlanes;

    int64 fSrcOriginH;

    int64 fSrcOriginV;

    int64 fSrcStepH;

    int64 fSrcStepV;

    uint32 fTableInputBits;

    uint32 fTableOutputBits;

    AutoPtr<dng_memory_block> fGainTable;

    AutoPtr<dng_memory_block> fMaskBuffers [kMaxMPThreads];

  public:

    dng_opcode_FixVignetteRadial (const dng_vignette_radial_params &params,

                    uint32 flags);

    explicit dng_opcode_FixVignetteRadial (dng_stream &stream);

    virtual bool IsNOP () const;

    virtual bool IsValidForNegative (const dng_negative &) const;

    virtual void PutData (dng_stream &stream) const;

    virtual uint32 BufferPixelType (uint32 /* imagePixelType */)

      {

      return ttFloat;

      }

    virtual void Prepare (dng_negative &negative,

                uint32 threadCount,

                const dng_point &tileSize,

                const dng_rect &imageBounds,

                uint32 imagePlanes,

                uint32 bufferPixelType,

                dng_memory_allocator &allocator);

    virtual void ProcessArea (dng_negative &negative,

                  uint32 threadIndex,

                  dng_pixel_buffer &buffer,

                  const dng_rect &dstArea,

                  const dng_rect &imageBounds);

  protected:

    static uint32 ParamBytes ();

  };

/*****************************************************************************/

#endif

/*****************************************************************************/