BicubicInterpolation.h

Go to the documentation of this file.

//     ____   ______ __
//    / __ \ / ____// /
//   / /_/ // /    / /
//  / ____// /___ / /___   PixInsight Class Library
// /_/     \____//_____/   PCL 2.7.0
// ----------------------------------------------------------------------------
// pcl/BicubicInterpolation.h - Released 2024-06-18T15:48:54Z
// ----------------------------------------------------------------------------
// This file is part of the PixInsight Class Library (PCL).
// PCL is a multiplatform C++ framework for development of PixInsight modules.
//
// Copyright (c) 2003-2024 Pleiades Astrophoto S.L. All Rights Reserved.
//
// Redistribution and use in both source and binary forms, with or without
// modification, is permitted provided that the following conditions are met:
//
// 1. All redistributions of source code must retain the above copyright
//    notice, this list of conditions and the following disclaimer.
//
// 2. All 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 names "PixInsight" and "Pleiades Astrophoto", nor the names
//    of their contributors, may be used to endorse or promote products derived
//    from this software without specific prior written permission. For written
//    permission, please contact info@pixinsight.com.
//
// 4. All products derived from this software, in any form whatsoever, must
//    reproduce the following acknowledgment in the end-user documentation
//    and/or other materials provided with the product:
//
//    "This product is based on software from the PixInsight project, developed
//    by Pleiades Astrophoto and its contributors (https://pixinsight.com/)."
//
//    Alternatively, if that is where third-party acknowledgments normally
//    appear, this acknowledgment must be reproduced in the product itself.
//
// THIS SOFTWARE IS PROVIDED BY PLEIADES ASTROPHOTO AND ITS 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 PLEIADES ASTROPHOTO OR ITS
// CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
// EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, BUSINESS
// INTERRUPTION; PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; AND LOSS OF USE,
// DATA OR PROFITS) 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.
// ----------------------------------------------------------------------------
 
#ifndef __PCL_BicubicInterpolation_h
#define __PCL_BicubicInterpolation_h
 
 
#include <pcl/Defs.h>
#include <pcl/Diagnostics.h>
 
#include <pcl/BidimensionalInterpolation.h>
#include <pcl/Math.h>
#include <pcl/Utility.h>
 
namespace pcl
{
 
#define m_width      this->m_width
#define m_height     this->m_height
#define m_fillBorder this->m_fillBorder
#define m_fillValue  this->m_fillValue
#define m_data       this->m_data
 
// ----------------------------------------------------------------------------
 
template <typename T>
class PCL_CLASS BicubicInterpolationBase : public BidimensionalInterpolation<T>
{
public:
 
   BicubicInterpolationBase() = default;
 
   BicubicInterpolationBase( const BicubicInterpolationBase& ) = default;
 
protected:
 
   void InitXY( int& i1, int& j1, double* p0, double* p1, double* p2, double* p3, double x, double y ) const noexcept
   {
      PCL_PRECONDITION( int( x ) >= 0 )
      PCL_PRECONDITION( int( x ) < m_width )
      PCL_PRECONDITION( int( y ) >= 0 )
      PCL_PRECONDITION( int( y ) < m_height )
 
      // Central grid coordinates
      i1 = pcl::Range( TruncInt( y ), 0, m_height-1 );
      j1 = pcl::Range( TruncInt( x ), 0, m_width-1 );
 
      // Set up source matrix
 
      int j0 = j1 - 1;
      int i0 = i1 - 1;
 
      int j2 = j1 + 1;
      int i2 = i1 + 1;
 
      int j3 = j1 + 2;
      int i3 = i1 + 2;
 
      const T* fp = m_data + (int64( i0 )*m_width + j0);
 
         // Row 0
 
      if ( i0 < 0 )
      {
         fp += m_width;
 
         if ( m_fillBorder )
         {
            p0[0] = p0[1] = p0[2] = p0[3] = m_fillValue;
            goto __row1;
         }
      }
 
      GetRow( p0, fp, j0, j2, j3 );
 
      if ( i0 >= 0 )
         fp += m_width;
 
__row1:  // Row 1
 
      GetRow( p1, fp, j0, j2, j3 );
 
         // Row 2
 
      if ( i2 < m_height )
         fp += m_width;
 
      GetRow( p2, fp, j0, j2, j3 );
 
         // Row 3
 
      if ( i3 < m_height )
         fp += m_width;
      else if ( m_fillBorder )
      {
         p3[0] = p3[1] = p3[2] = p3[3] = m_fillValue;
         goto __done;
      }
 
      GetRow( p3, fp, j0, j2, j3 );
 
__done:
      ;
   }
 
   void InitYX( int& i1, int& j1, double* p0, double* p1, double* p2, double* p3, double x, double y ) const noexcept
   {
      PCL_PRECONDITION( int( x ) >= 0 )
      PCL_PRECONDITION( int( x ) < m_width )
      PCL_PRECONDITION( int( y ) >= 0 )
      PCL_PRECONDITION( int( y ) < m_height )
 
      // Central grid coordinates
      i1 = pcl::Range( TruncInt( y ), 0, m_height-1 );
      j1 = pcl::Range( TruncInt( x ), 0, m_width-1 );
 
      // Set up source matrix
 
      int j0 = j1 - 1;
      int i0 = i1 - 1;
 
      int j2 = j1 + 1;
      int i2 = i1 + 1;
 
      int j3 = j1 + 2;
      int i3 = i1 + 2;
 
      const T* fp = m_data + (int64( i0 )*m_width + j0);
 
         // Column 0
 
      if ( j0 < 0 )
      {
         ++fp;
 
         if ( m_fillBorder )
         {
            p0[0] = p0[1] = p0[2] = p0[3] = m_fillValue;
            goto __col1;
         }
      }
 
      GetColumn( p0, fp, i0, i2, i3 );
 
      if ( j0 >= 0 )
         ++fp;
 
__col1:  // Column 1
 
      GetColumn( p1, fp, i0, i2, i3 );
 
         // Column 2
 
      if ( j2 < m_width )
         ++fp;
 
      GetColumn( p2, fp, i0, i2, i3 );
 
         // Column 3
 
      if ( j3 < m_width )
         ++fp;
      else if ( m_fillBorder )
      {
         p3[0] = p3[1] = p3[2] = p3[3] = m_fillValue;
         goto __done;
      }
 
      GetColumn( p3, fp, i0, i2, i3 );
 
__done:
      ;
   }
 
private:
 
   void GetRow( double* p, const T* fp, int j0, int j2, int j3 ) const noexcept
   {
      if ( m_fillBorder )
      {
           *p = (j0 >= 0) ? *fp : m_fillValue;
         *++p = *++fp;
 
         if ( j2 < m_width )
         {
            *++p = *++fp;
            *++p = (j3 < m_width) ? *++fp : m_fillValue;
         }
         else
            p[1] = p[2] = m_fillValue;
      }
      else
      {
         if ( j0 < 0 )
            ++fp;
         *p = *fp;
         if ( j0 >= 0 )
            ++fp;
         *++p = *fp;
 
         if ( j2 < m_width )
         {
            *++p = *++fp;
            if ( j3 < m_width )
               ++fp;
            *++p = *fp;
         }
         else
         {
            *++p = *fp;
            *++p = *(fp - 1);
         }
      }
   }
 
   void GetColumn( double* p, const T* fp, int i0, int i2, int i3 ) const noexcept
   {
      if ( m_fillBorder )
      {
           *p = (i0 >= 0) ? *fp : m_fillValue;
         *++p = *(fp += m_width);
 
         if ( i2 < m_height )
         {
            *++p = *(fp += m_width);
            *++p = (i3 < m_height) ? *(fp += m_width) : m_fillValue;
         }
         else
            p[1] = p[2] = m_fillValue;
      }
      else
      {
         if ( i0 < 0 )
            fp += m_width;
         *p = *fp;
         if ( i0 >= 0 )
            fp += m_width;
         *++p = *fp;
 
         if ( i2 < m_height )
         {
            *++p = *(fp += m_width);
            if ( i3 < m_height )
               fp += m_width;
            *++p = *fp;
         }
         else
         {
            *++p = *fp;
            *++p = *(fp - m_width);
         }
      }
   }
};
 
// ----------------------------------------------------------------------------
 
#define InitXY this->InitXY
#define InitYX this->InitYX
 
/*
 * Undefine the following to use any free constant value a != -1/2
 */
#define __PCL_BICUBIC_SPLINE_A_IS_MINUS_ONE_HALF   1
 
/*
 * The "a" constant controls the depth of the negative lobes in the bicubic
 * spline interpolation function, -1 <= a < 0. Larger values of a (in absolute
 * value) lead to more ringing (sharpness). The default is -1/2, as recommended
 * in [Keys 1981].
 */
#define __PCL_BICUBIC_SPLINE_A                    -0.5
 
/*
 * Default clamping threshold for linear images. This value has been optimized
 * for a = -1/2. If you use another value for a, this must also be fine tuned.
 */
#ifndef __PCL_BICUBIC_SPLINE_CLAMPING_THRESHOLD
#define __PCL_BICUBIC_SPLINE_CLAMPING_THRESHOLD    0.3F
#endif
 
template <typename T>
class PCL_CLASS BicubicSplineInterpolation : public BicubicInterpolationBase<T>
{
public:
 
   BicubicSplineInterpolation( float clamp = __PCL_BICUBIC_SPLINE_CLAMPING_THRESHOLD )
      : m_clamp( Range( clamp, 0.0F, 1.0F ) )
   {
      PCL_PRECONDITION( 0 <= clamp && clamp <= 1 )
   }
 
   BicubicSplineInterpolation( const BicubicSplineInterpolation& ) = default;
 
   ~BicubicSplineInterpolation() override
   {
   }
 
   double operator()( double x, double y ) const override
   {
      PCL_PRECONDITION( m_data != nullptr )
      PCL_PRECONDITION( m_width > 0 && m_height > 0 )
 
      // Initialize grid coordinates and source matrix
      int i1, j1;
      double p0[ 4 ], p1[ 4 ], p2[ 4 ], p3[ 4 ];
      InitXY( i1, j1, p0, p1, p2, p3, x, y );
 
      // Cubic spline coefficients
      double C[ 4 ];
      GetSplineCoefficients( C, x-j1 );
 
      // Interpolate neighbor rows
      double c[ 4 ];
      c[0] = Interpolate( p0, C );
      c[1] = Interpolate( p1, C );
      c[2] = Interpolate( p2, C );
      c[3] = Interpolate( p3, C );
 
      // Interpolate result vertically
      GetSplineCoefficients( C, y-i1 );
      return Interpolate( c, C );
   }
 
   void InterpolateX( double fx[], double x, double y ) const noexcept
   {
      PCL_PRECONDITION( m_data != nullptr )
      PCL_PRECONDITION( m_width > 0 && m_height > 0 )
 
      // Initialize grid coordinates and source matrix
      int i1, j1;
      double p0[ 4 ], p1[ 4 ], p2[ 4 ], p3[ 4 ];
      InitXY( i1, j1, p0, p1, p2, p3, x, y );
 
      // Cubic spline coefficients
      double C[ 4 ];
      GetSplineCoefficients( C, x-j1 );
 
      // Interpolate neighbor rows
      fx[0] = Interpolate( p0, C );
      fx[1] = Interpolate( p1, C );
      fx[2] = Interpolate( p2, C );
      fx[3] = Interpolate( p3, C );
   }
 
   void InterpolateY( double fy[], double x, double y ) const noexcept
   {
      PCL_PRECONDITION( m_data != nullptr )
      PCL_PRECONDITION( m_width > 0 && m_height > 0 )
 
      // Initialize grid coordinates and source matrix
      int i1, j1;
      double p0[ 4 ], p1[ 4 ], p2[ 4 ], p3[ 4 ];
      InitYX( i1, j1, p0, p1, p2, p3, x, y );
 
      // Cubic spline coefficients
      double C[ 4 ];
      GetSplineCoefficients( C, y-i1 );
 
      // Interpolate neighbor columns
      fy[0] = Interpolate( p0, C );
      fy[1] = Interpolate( p1, C );
      fy[2] = Interpolate( p2, C );
      fy[3] = Interpolate( p3, C );
   }
 
   double InterpolateVector( const double c[], double dx ) const noexcept
   {
      double C[ 4 ];
      GetSplineCoefficients( C, dx );
      return Interpolate( c, C );
   }
 
   float ClampingThreshold() const noexcept
   {
      return m_clamp;
   }
 
   void SetClampingThreshold( float c ) noexcept
   {
      PCL_PRECONDITION( 0 <= c && c <= 1 )
      m_clamp = Range( c, 0.0F, 1.0F );
   }
 
private:
 
   double m_clamp;
 
   PCL_HOT_FUNCTION
   double Interpolate( const double* __restrict__ p, const double* __restrict__ C ) const noexcept
   {
      // Unclamped code:
      //return p[0]*C[0] + p[1]*C[1] + p[2]*C[2] + p[3]*C[3];
      double f12 = p[1]*C[1] + p[2]*C[2];
      double f03 = p[0]*C[0] + p[3]*C[3];
      return (-f03 < f12*m_clamp) ? f12 + f03 : f12/(C[1] + C[2]);
   }
 
   PCL_HOT_FUNCTION
   void GetSplineCoefficients( double* __restrict__ C, double dx ) const noexcept
   {
      double dx2 = dx*dx;
      double dx3 = dx2*dx;
 
#ifdef __PCL_BICUBIC_SPLINE_A_IS_MINUS_ONE_HALF
      // Optimized code for a = -1/2
      // We *really* need optimization here since this routine is called twice
      // for each interpolated pixel.
      double dx1_2 = dx/2;
      double dx2_2 = dx2/2;
      double dx3_2 = dx3/2;
      double dx22 = dx2 + dx2;
      double dx315 = dx3 + dx3_2;
      C[0] =  dx2 - dx3_2 - dx1_2;
      C[1] =  dx315 - dx22 - dx2_2 + 1;
      C[2] =  dx22 - dx315 + dx1_2;
      C[3] =  dx3_2 - dx2_2;
#else
#  define a (__PCL_BICUBIC_SPLINE_A)
      C[0] =        a*dx3 -       2*a*dx2 + a*dx;
      C[1] =  (a + 2)*dx3 -   (a + 3)*dx2         + 1;
      C[2] = -(a + 2)*dx3 + (2*a + 3)*dx2 - a*dx;
      C[3] =       -a*dx3 +         a*dx2;
#  undef a
#endif
   }
};
 
template <typename T>
class PCL_CLASS BicubicInterpolation : public BicubicSplineInterpolation<T>
{
public:
 
   BicubicInterpolation() = default;
 
   BicubicInterpolation( const BicubicInterpolation& ) = default;
 
   ~BicubicInterpolation() override
   {
   }
};
 
// ----------------------------------------------------------------------------
 
template <typename T>
class PCL_CLASS BicubicBSplineInterpolation : public BicubicInterpolationBase<T>
{
public:
 
   BicubicBSplineInterpolation() = default;
 
   BicubicBSplineInterpolation( const BicubicBSplineInterpolation& ) = default;
 
   ~BicubicBSplineInterpolation() override
   {
   }
 
   double operator()( double x, double y ) const override
   {
      PCL_PRECONDITION( f != 0 )
      PCL_PRECONDITION( m_width > 0 && m_height > 0 )
 
      // Initialize grid coordinates and source matrix
      int i1, j1;
      double p0[ 4 ], p1[ 4 ], p2[ 4 ], p3[ 4 ];
      InitXY( i1, j1, p0, p1, p2, p3, x, y );
 
      // Bicubic B-Spline interpolation functions
 
      double dx  =  x - j1;
      double dx0 = -1 - dx;
      double dx1 =     -dx;
      double dx2 =  1 - dx;
      double dx3 =  2 - dx;
 
      double dy  =  y - i1;
      double dy0 = -1 - dy;
      double dy1 =     -dy;
      double dy2 =  1 - dy;
      double dy3 =  2 - dy;
 
      return
      BXY( p0, 0, dx0, dy0 ) +
      BXY( p0, 1, dx1, dy0 ) +
      BXY( p0, 2, dx2, dy0 ) +
      BXY( p0, 3, dx3, dy0 ) +
      BXY( p1, 0, dx0, dy1 ) +
      BXY( p1, 1, dx1, dy1 ) +
      BXY( p1, 2, dx2, dy1 ) +
      BXY( p1, 3, dx3, dy1 ) +
      BXY( p2, 0, dx0, dy2 ) +
      BXY( p2, 1, dx1, dy2 ) +
      BXY( p2, 2, dx2, dy2 ) +
      BXY( p2, 3, dx3, dy2 ) +
      BXY( p3, 0, dx0, dy3 ) +
      BXY( p3, 1, dx1, dy3 ) +
      BXY( p3, 2, dx2, dy3 ) +
      BXY( p3, 3, dx3, dy3 );
   }
 
private:
 
   double BXY( const double* __restrict__ p, int j, double x, double y ) const noexcept
   {
      return p[j]*B( x )*B( y );
   }
 
   double B( double x ) const noexcept
   {
      double fx = (x > 0) ? x*x*x : 0;
 
      double fxp1 = x + 1;
      fxp1 = (fxp1 > 0) ? fxp1*fxp1*fxp1 : 0;
 
      double fxp2 = x + 2;
      fxp2 = (fxp2 > 0) ? fxp2*fxp2*fxp2 : 0;
 
      double fxm1 = x - 1;
      fxm1 = (fxm1 > 0) ? fxm1*fxm1*fxm1 : 0;
 
      return (fxp2 - 4*fxp1 + 6*fx - 4*fxm1)/6;
   }
};
 
// ----------------------------------------------------------------------------
 
#undef InitXY
#undef InitYX
 
// ----------------------------------------------------------------------------
 
#undef m_width
#undef m_height
#undef m_fillBorder
#undef m_fillValue
#undef m_data
 
// ----------------------------------------------------------------------------
 
} // pcl
 
#endif   // __PCL_BicubicInterpolation_h
 
// ----------------------------------------------------------------------------
// EOF pcl/BicubicInterpolation.h - Released 2024-06-18T15:48:54Z