PCL
KernelFilter.h
Go to the documentation of this file.
1 // ____ ______ __
2 // / __ \ / ____// /
3 // / /_/ // / / /
4 // / ____// /___ / /___ PixInsight Class Library
5 // /_/ \____//_____/ PCL 2.1.19
6 // ----------------------------------------------------------------------------
7 // pcl/KernelFilter.h - Released 2019-11-07T10:59:34Z
8 // ----------------------------------------------------------------------------
9 // This file is part of the PixInsight Class Library (PCL).
10 // PCL is a multiplatform C++ framework for development of PixInsight modules.
11 //
12 // Copyright (c) 2003-2019 Pleiades Astrophoto S.L. All Rights Reserved.
13 //
14 // Redistribution and use in both source and binary forms, with or without
15 // modification, is permitted provided that the following conditions are met:
16 //
17 // 1. All redistributions of source code must retain the above copyright
18 // notice, this list of conditions and the following disclaimer.
19 //
20 // 2. All redistributions in binary form must reproduce the above copyright
21 // notice, this list of conditions and the following disclaimer in the
22 // documentation and/or other materials provided with the distribution.
23 //
24 // 3. Neither the names "PixInsight" and "Pleiades Astrophoto", nor the names
25 // of their contributors, may be used to endorse or promote products derived
26 // from this software without specific prior written permission. For written
27 // permission, please contact info@pixinsight.com.
28 //
29 // 4. All products derived from this software, in any form whatsoever, must
30 // reproduce the following acknowledgment in the end-user documentation
31 // and/or other materials provided with the product:
32 //
33 // "This product is based on software from the PixInsight project, developed
34 // by Pleiades Astrophoto and its contributors (http://pixinsight.com/)."
35 //
36 // Alternatively, if that is where third-party acknowledgments normally
37 // appear, this acknowledgment must be reproduced in the product itself.
38 //
39 // THIS SOFTWARE IS PROVIDED BY PLEIADES ASTROPHOTO AND ITS CONTRIBUTORS
40 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
41 // TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
42 // PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL PLEIADES ASTROPHOTO OR ITS
43 // CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
44 // EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, BUSINESS
45 // INTERRUPTION; PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; AND LOSS OF USE,
46 // DATA OR PROFITS) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
47 // CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
48 // ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
49 // POSSIBILITY OF SUCH DAMAGE.
50 // ----------------------------------------------------------------------------
51 
52 #ifndef __PCL_KernelFilter_h
53 #define __PCL_KernelFilter_h
54 
56 
57 #include <pcl/Defs.h>
58 #include <pcl/Diagnostics.h>
59 
60 #include <pcl/Math.h>
61 #include <pcl/Matrix.h>
62 #include <pcl/SeparableFilter.h>
63 #include <pcl/String.h>
64 
65 namespace pcl
66 {
67 
68 // ----------------------------------------------------------------------------
69 
70 #define __PCL_DEFAULT_FILTER_SEPARABILITY_TOLERANCE 1.0e-06F
71 
89 class PCL_CLASS KernelFilter
90 {
91 public:
92 
96  typedef float coefficient;
97 
102 
106  KernelFilter( const String& name = String() ) :
107  filterName( name )
108  {
109  }
110 
119  KernelFilter( int n, const String& name = String() ) :
120  coefficients( PCL_VALID_KERNEL_SIZE( n ), PCL_VALID_KERNEL_SIZE( n ) ),
121  filterName( name )
122  {
123  PCL_PRECONDITION( n == 0 || n >= 3 )
124  PCL_PRECONDITION( n == 0 || (n & 1) )
125  }
126 
131  template <typename T>
132  KernelFilter( int n, const T& x, const String& name = String() ) :
133  coefficients( x, PCL_VALID_KERNEL_SIZE( n ), PCL_VALID_KERNEL_SIZE( n ) ),
134  filterName( name )
135  {
136  PCL_PRECONDITION( n == 0 || n >= 3 )
137  PCL_PRECONDITION( n == 0 || (n & 1) )
138  }
139 
144  KernelFilter( const coefficient_matrix& F, const String& name = String() ) :
145  coefficients( F ),
146  filterName( name )
147  {
148  }
149 
155  template <typename T>
156  KernelFilter( const T* k, int n, const String& name = String() ) :
157  coefficients( k, PCL_VALID_KERNEL_SIZE( n ), PCL_VALID_KERNEL_SIZE( n ) ),
158  filterName( name )
159  {
160  PCL_PRECONDITION( n == 0 || n >= 3 )
161  PCL_PRECONDITION( n == 0 || (n & 1) )
162  }
163 
167  KernelFilter( const KernelFilter& ) = default;
168 
172  KernelFilter( KernelFilter&& ) = default;
173 
177  virtual ~KernelFilter()
178  {
179  }
180 
188  virtual KernelFilter* Clone() const
189  {
190  return new KernelFilter( *this );
191  }
192 
211  virtual SeparableFilter AsSeparableFilter( float tolerance = __PCL_DEFAULT_FILTER_SEPARABILITY_TOLERANCE ) const;
212 
225  virtual bool IsSeparable() const
226  {
227  return !AsSeparableFilter().IsEmpty();
228  }
229 
233  KernelFilter& operator =( const KernelFilter& ) = default;
234 
238  KernelFilter& operator =( KernelFilter&& ) = default;
239 
248  KernelFilter& operator =( const coefficient_matrix& F )
249  {
250  if ( !F.IsEmpty() && (F.Rows() != F.Cols() || (F.Rows() & 1) == 0) )
251  throw Error( "KernelFilter: Invalid coefficient matrix assignment." );
252  coefficients = F;
253  flipped = false;
254  return *this;
255  }
256 
261  KernelFilter& operator =( const coefficient& x )
262  {
263  coefficients = x;
264  flipped = false;
265  return *this;
266  }
267 
273  bool operator ==( const KernelFilter& f ) const
274  {
275  return Name() == f.Name() && SameCoefficients( f );
276  }
277 
281  String Name() const
282  {
283  return filterName;
284  }
285 
289  virtual void Rename( const String& newName )
290  {
291  filterName = newName.Trimmed();
292  }
293 
297  int Size() const
298  {
299  return coefficients.Rows(); // coefficients *must* be a square matrix
300  }
301 
307  virtual void Resize( int n )
308  {
309  PCL_PRECONDITION( n == 0 || n >= 3 )
310  PCL_PRECONDITION( n == 0 || (n & 1) )
311  if ( n == 0 )
312  coefficients = coefficient_matrix();
313  else
314  {
315  n = PCL_VALID_KERNEL_SIZE( n );
316  coefficients = coefficient_matrix( n, n );
317  }
318  flipped = false;
319  }
320 
325  bool IsEmpty() const
326  {
327  return coefficients.IsEmpty();
328  }
329 
333  operator bool() const
334  {
335  return !IsEmpty();
336  }
337 
342  {
343  return coefficients.Rows()*coefficients.Cols();
344  }
345 
349  coefficient_matrix Coefficients() const
350  {
351  return coefficients;
352  }
353 
363  const coefficient* Begin() const
364  {
365  return coefficients.Begin();
366  }
367 
378  const coefficient* End() const
379  {
380  return coefficients.End();
381  }
382 
383 #ifndef __PCL_NO_STL_COMPATIBLE_ITERATORS
384 
387  const coefficient* begin() const
388  {
389  return Begin();
390  }
391 
395  const coefficient* end() const
396  {
397  return End();
398  }
399 #endif // !__PCL_NO_STL_COMPATIBLE_ITERATORS
400 
406  const coefficient* operator[]( int row ) const
407  {
408  return coefficients[row];
409  }
410 
415  double Weight() const
416  {
417  return coefficients.Sum();
418  }
419 
423  double Modulus() const
424  {
425  return coefficients.Modulus();
426  }
427 
433  void Normalize()
434  {
435  double m = Modulus();
436  if ( 1 + m != 1 )
437  coefficients /= m;
438  }
439 
446  {
447  KernelFilter f( *this );
448  f.Normalize();
449  return f;
450  }
451 
456  void Flip()
457  {
458  coefficients.Flip();
459  flipped = !flipped;
460  }
461 
467  {
468  KernelFilter f( *this );
469  f.Flip();
470  return f;
471  }
472 
478  bool IsFlipped() const
479  {
480  return flipped;
481  }
482 
491  bool IsHighPassFilter() const
492  {
493  const coefficient* a = coefficients.Begin();
494  const coefficient* b = coefficients.End();
495  //while ( a < b )
496  // if ( *a++ < 0 || *--b < 0 )
497  // The above loop is better for nonsymmetrical filters, which are seldom used.
498  while ( a < b )
499  if ( *a++ < 0 )
500  return true;
501  return false;
502  }
503 
508  bool SameCoefficients( const KernelFilter& f ) const
509  {
510  return coefficients.SameElements( f.coefficients );
511  }
512 
517  virtual void Clear()
518  {
519  coefficients = coefficient_matrix();
520  flipped = false;
521  }
522 
523 #ifndef __PCL_NO_MATRIX_IMAGE_RENDERING
524 
541  template <class P>
542  void ToImage( GenericImage<P>& image ) const
543  {
544  coefficients.ToImage( image );
545  }
546 
560  void ToImage( ImageVariant& v ) const
561  {
562  coefficients.ToImage( v );
563  }
564 
565 #endif // !__PCL_NO_MATRIX_IMAGE_RENDERING
566 
567 protected:
568 
569  coefficient_matrix coefficients; // filter coefficients, size*size elements
570  String filterName; // identifying name
571  bool flipped = false; // flag true when filter rotated
572 };
573 
574 // ----------------------------------------------------------------------------
575 
576 } // pcl
577 
578 #endif // __PCL_KernelFilter_h
579 
580 // ----------------------------------------------------------------------------
581 // EOF pcl/KernelFilter.h - Released 2019-11-07T10:59:34Z
KernelFilter(int n, const String &name=String())
Definition: KernelFilter.h:119
const coefficient * begin() const
Definition: KernelFilter.h:387
const coefficient * end() const
Definition: KernelFilter.h:395
coefficient_matrix Coefficients() const
Definition: KernelFilter.h:349
virtual bool IsSeparable() const
Definition: KernelFilter.h:225
virtual void Clear()
Definition: KernelFilter.h:517
PCL root namespace.
Definition: AbstractImage.h:76
virtual KernelFilter * Clone() const
Definition: KernelFilter.h:188
GenericMatrix< coefficient > coefficient_matrix
Definition: KernelFilter.h:101
int Rows() const
Definition: Matrix.h:907
Separable filter in two dimensions.
Implements a generic, two-dimensional, shared or local image.
Definition: Image.h:275
const coefficient * Begin() const
Definition: KernelFilter.h:363
KernelFilter Normalized() const
Definition: KernelFilter.h:445
Acts like a union for all types of images in PCL, with optional class-wide ownership of transported i...
Definition: ImageVariant.h:317
bool SameCoefficients(const KernelFilter &f) const
Definition: KernelFilter.h:508
const coefficient * End() const
Definition: KernelFilter.h:378
Unicode (UTF-16) string.
Definition: String.h:7911
KernelFilter(const T *k, int n, const String &name=String())
Definition: KernelFilter.h:156
int Cols() const
Definition: Matrix.h:916
KernelFilter(const coefficient_matrix &F, const String &name=String())
Definition: KernelFilter.h:144
bool IsHighPassFilter() const
Definition: KernelFilter.h:491
virtual void Rename(const String &newName)
Definition: KernelFilter.h:289
bool IsEmpty() const
Definition: KernelFilter.h:325
KernelFilter Flipped() const
Definition: KernelFilter.h:466
A simple exception with an associated error message.
Definition: Exception.h:213
virtual void Resize(int n)
Definition: KernelFilter.h:307
String Name() const
Definition: KernelFilter.h:281
Kernel filter in two dimensions.
Definition: KernelFilter.h:89
double Modulus() const
Definition: KernelFilter.h:423
String Name(int colorSpace)
KernelFilter(const String &name=String())
Definition: KernelFilter.h:106
const coefficient * operator[](int row) const
Definition: KernelFilter.h:406
int Size() const
Definition: KernelFilter.h:297
bool operator==(const Array< T, A > &x1, const Array< T, A > &x2)
Definition: Array.h:2075
KernelFilter(int n, const T &x, const String &name=String())
Definition: KernelFilter.h:132
bool IsFlipped() const
Definition: KernelFilter.h:478
double Modulus(const T *i, const T *j)
Definition: Math.h:2259
void ToImage(GenericImage< P > &image) const
Definition: KernelFilter.h:542
virtual ~KernelFilter()
Definition: KernelFilter.h:177
void ToImage(ImageVariant &v) const
Definition: KernelFilter.h:560
bool IsEmpty() const
Definition: Matrix.h:956
int NumberOfCoefficients() const
Definition: KernelFilter.h:341
double Weight() const
Definition: KernelFilter.h:415