KernelFilter.h

Go to the documentation of this file.

//     ____   ______ __
//    / __ \ / ____// /
//   / /_/ // /    / /
//  / ____// /___ / /___   PixInsight Class Library
// /_/     \____//_____/   PCL 2.7.0
// ----------------------------------------------------------------------------
// pcl/KernelFilter.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_KernelFilter_h
#define __PCL_KernelFilter_h
 
 
#include <pcl/Defs.h>
#include <pcl/Diagnostics.h>
 
#include <pcl/Math.h>
#include <pcl/Matrix.h>
#include <pcl/SeparableFilter.h>
#include <pcl/String.h>
 
namespace pcl
{
 
// ----------------------------------------------------------------------------
 
#define __PCL_DEFAULT_FILTER_SEPARABILITY_TOLERANCE 1.0e-06F
 
class PCL_CLASS KernelFilter
{
public:
 
   using coefficient = float;
 
   using coefficient_matrix = GenericMatrix<coefficient>;
 
   KernelFilter( const String& name = String() )
      : filterName( name )
   {
   }
 
   KernelFilter( int n, const String& name = String() )
      : coefficients( PCL_VALID_KERNEL_SIZE( n ), PCL_VALID_KERNEL_SIZE( n ) )
      , filterName( name )
   {
      PCL_PRECONDITION( n == 0 || n >= 3 )
      PCL_PRECONDITION( n == 0 || (n & 1) )
   }
 
   template <typename T>
   KernelFilter( int n, const T& x, const String& name = String() )
      : coefficients( x, PCL_VALID_KERNEL_SIZE( n ), PCL_VALID_KERNEL_SIZE( n ) )
      , filterName( name )
   {
      PCL_PRECONDITION( n == 0 || n >= 3 )
      PCL_PRECONDITION( n == 0 || (n & 1) )
   }
 
   KernelFilter( const coefficient_matrix& F, const String& name = String() )
      : filterName( name )
   {
      if ( !F.IsEmpty() && (F.Rows() != F.Cols() || (F.Rows() & 1) == 0) )
         throw Error( "KernelFilter: Invalid coefficient matrix in constructor." );
      coefficients = F;
   }
 
   template <typename T>
   KernelFilter( const T* k, int n, const String& name = String() )
      : coefficients( k, PCL_VALID_KERNEL_SIZE( n ), PCL_VALID_KERNEL_SIZE( n ) )
      , filterName( name )
   {
      PCL_PRECONDITION( n == 0 || n >= 3 )
      PCL_PRECONDITION( n == 0 || (n & 1) )
   }
 
   KernelFilter( const KernelFilter& ) = default;
 
   KernelFilter( KernelFilter&& ) = default;
 
   virtual ~KernelFilter()
   {
   }
 
   virtual KernelFilter* Clone() const
   {
      return new KernelFilter( *this );
   }
 
   virtual SeparableFilter AsSeparableFilter( float tolerance = __PCL_DEFAULT_FILTER_SEPARABILITY_TOLERANCE ) const;
 
   virtual bool IsSeparable() const
   {
      return !AsSeparableFilter().IsEmpty();
   }
 
   KernelFilter& operator =( const KernelFilter& ) = default;
 
   KernelFilter& operator =( KernelFilter&& ) = default;
 
   KernelFilter& operator =( const coefficient_matrix& F )
   {
      if ( !F.IsEmpty() && (F.Rows() != F.Cols() || (F.Rows() & 1) == 0) )
         throw Error( "KernelFilter: Invalid coefficient matrix assignment." );
      coefficients = F;
      flipped = false;
      return *this;
   }
 
   KernelFilter& operator =( const coefficient& x )
   {
      coefficients = x;
      flipped = false;
      return *this;
   }
 
   bool operator ==( const KernelFilter& f ) const
   {
      return Name() == f.Name() && SameCoefficients( f );
   }
 
   String Name() const
   {
      return filterName;
   }
 
   virtual void Rename( const String& newName )
   {
      filterName = newName.Trimmed();
   }
 
   int Size() const
   {
      return coefficients.Rows(); // coefficients *must* be a square matrix
   }
 
   virtual void Resize( int n )
   {
      PCL_PRECONDITION( n == 0 || n >= 3 )
      PCL_PRECONDITION( n == 0 || (n & 1) )
      if ( n == 0 )
         coefficients = coefficient_matrix();
      else
      {
         n = PCL_VALID_KERNEL_SIZE( n );
         coefficients = coefficient_matrix( n, n );
      }
      flipped = false;
   }
 
   bool IsEmpty() const
   {
      return coefficients.IsEmpty();
   }
 
   operator bool() const
   {
      return !IsEmpty();
   }
 
   int NumberOfCoefficients() const
   {
      return coefficients.Rows()*coefficients.Cols();
   }
 
   coefficient_matrix Coefficients() const
   {
      return coefficients;
   }
 
   const coefficient* Begin() const
   {
      return coefficients.Begin();
   }
 
   const coefficient* End() const
   {
      return coefficients.End();
   }
 
#ifndef __PCL_NO_STL_COMPATIBLE_ITERATORS
   const coefficient* begin() const
   {
      return Begin();
   }
 
   const coefficient* end() const
   {
      return End();
   }
#endif   // !__PCL_NO_STL_COMPATIBLE_ITERATORS
 
   const coefficient* operator[]( int row ) const
   {
      return coefficients[row];
   }
 
   double Weight() const
   {
      return coefficients.Sum();
   }
 
   double Modulus() const
   {
      return coefficients.Modulus();
   }
 
   void Normalize()
   {
      double m = Modulus();
      if ( 1 + m != 1 )
         coefficients /= m;
   }
 
   KernelFilter Normalized() const
   {
      KernelFilter f( *this );
      f.Normalize();
      return f;
   }
 
   void Flip()
   {
      coefficients.Flip();
      flipped = !flipped;
   }
 
   KernelFilter Flipped() const
   {
      KernelFilter f( *this );
      f.Flip();
      return f;
   }
 
   bool IsFlipped() const
   {
      return flipped;
   }
 
   bool IsHighPassFilter() const
   {
      const coefficient* a = coefficients.Begin();
      const coefficient* b = coefficients.End();
      //while ( a < b )
      //   if ( *a++ < 0 || *--b < 0 )
      // The above loop is better for nonsymmetrical filters, which are seldom used.
      while ( a < b )
         if ( *a++ < 0 )
            return true;
      return false;
   }
 
   bool SameCoefficients( const KernelFilter& f ) const
   {
      return coefficients.SameElements( f.coefficients );
   }
 
   virtual void Clear()
   {
      coefficients = coefficient_matrix();
      flipped = false;
   }
 
#ifndef __PCL_NO_MATRIX_IMAGE_RENDERING
 
   template <class P>
   void ToImage( GenericImage<P>& image ) const
   {
      coefficients.ToImage( image );
   }
 
   void ToImage( ImageVariant& v ) const
   {
      coefficients.ToImage( v );
   }
 
#endif   // !__PCL_NO_MATRIX_IMAGE_RENDERING
 
protected:
 
   coefficient_matrix coefficients;    // filter coefficients, size*size elements
   String             filterName;      // identifying name
   bool               flipped = false; // flag true when filter rotated
};
 
// ----------------------------------------------------------------------------
 
} // pcl
 
#endif   // __PCL_KernelFilter_h
 
// ----------------------------------------------------------------------------
// EOF pcl/KernelFilter.h - Released 2024-06-18T15:48:54Z