PCL
Histogram.h
Go to the documentation of this file.
1 // ____ ______ __
2 // / __ \ / ____// /
3 // / /_/ // / / /
4 // / ____// /___ / /___ PixInsight Class Library
5 // /_/ \____//_____/ PCL 2.7.0
6 // ----------------------------------------------------------------------------
7 // pcl/Histogram.h - Released 2024-06-18T15:48:54Z
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-2024 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 (https://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_Histogram_h
53 #define __PCL_Histogram_h
54 
56 
57 #include <pcl/Defs.h>
58 #include <pcl/Diagnostics.h>
59 
60 #include <pcl/ImageVariant.h>
61 #include <pcl/ParallelProcess.h>
62 #include <pcl/Vector.h>
63 
64 namespace pcl
65 {
66 
67 // ----------------------------------------------------------------------------
68 
75 class PCL_CLASS Histogram : public ParallelProcess
76 {
77 public:
78 
83  using count_type = uint64;
84 
90 
99  Histogram( int resolution = 0x10000L )
100  : m_resolution( pcl::Max( 2, resolution ) )
101  {
102  PCL_PRECONDITION( resolution > 1 )
103  }
104 
116  Histogram( const histogram_type& data )
117  {
118  SetHistogramData( data );
119  }
120 
124  Histogram( const Histogram& ) = default;
125 
129  Histogram( Histogram&& ) = default;
130 
134  ~Histogram() override
135  {
136  }
137 
141  Histogram& operator =( const Histogram& ) = default;
142 
146  Histogram& operator =( Histogram&& ) = default;
147 
151  void Assign( const Histogram& x )
152  {
153  (void)operator =( x );
154  }
155 
160  void Clear()
161  {
162  m_histogram.Clear();
163  m_peakLevel = 0;
164  }
165 
170  bool IsEmpty() const
171  {
172  return m_histogram.IsEmpty();
173  }
174 
183  int Resolution() const
184  {
185  return m_resolution;
186  }
187 
191  int LastLevel() const
192  {
193  return m_resolution-1;
194  }
195 
207  void SetResolution( int resolution )
208  {
209  PCL_PRECONDITION( resolution > 1 )
210  Clear();
211  m_resolution = pcl::Max( 2, resolution );
212  }
213 
222  void Allocate()
223  {
224  if ( m_histogram.IsEmpty() )
225  m_histogram = histogram_type( m_resolution );
226  }
227 
236  int PeakLevel() const
237  {
238  return m_histogram.IsEmpty() ? 0 : m_peakLevel;
239  }
240 
245  double NormalizedPeakLevel() const
246  {
247  return NormalizedLevel( PeakLevel() );
248  }
249 
258  {
259  return m_peakLevel = m_histogram.IsEmpty() ? 0 :
260  int( pcl::MaxItem( m_histogram.Begin(), m_histogram.End() ) - m_histogram.Begin() );
261  }
262 
267  int HistogramLevel( double x ) const
268  {
269  PCL_PRECONDITION( x >= 0 && x <= 1 )
270  return RoundInt( pcl::Range( x, 0.0, 1.0 )*(m_resolution - 1) );
271  }
272 
277  double NormalizedLevel( int i ) const
278  {
279  PCL_PRECONDITION( i >= 0 && i < m_resolution )
280  return double( pcl::Range( i, 0, m_resolution-1 ) )/(m_resolution - 1);
281  }
282 
287  void GetHistogramRange( int& i, int& j, double a, double b ) const
288  {
289  i = HistogramLevel( a );
290  j = HistogramLevel( b );
291  if ( j < i )
292  pcl::Swap( i, j );
293  }
294 
299  void GetNormalizedRange( double& a, double& b, int i, int j ) const
300  {
301  if ( j < i )
302  pcl::Swap( i, j );
303  a = NormalizedLevel( i );
304  b = NormalizedLevel( j );
305  }
306 
313  {
314  return m_histogram.Sum();
315  }
316 
321  count_type Count( int i ) const
322  {
323  PCL_PRECONDITION( i >= 0 && i < m_histogram.Length() )
324  if ( i < 0 || i >= m_histogram.Length() )
325  return 0;
326  return m_histogram[i];
327  }
328 
332  count_type operator []( int i ) const
333  {
334  return Count( i );
335  }
336 
341  count_type Count( int i, int j ) const
342  {
343  PCL_PRECONDITION( i >= 0 && i < m_histogram.Length() )
344  PCL_PRECONDITION( j >= 0 && j < m_histogram.Length() )
345  if ( m_histogram.IsEmpty() )
346  return 0;
347  i = pcl::Range( i, 0, m_histogram.Length()-1 );
348  j = pcl::Range( j, 0, m_histogram.Length()-1 );
349  if ( j < i )
350  pcl::Swap( i, j );
351  return pcl::Sum( m_histogram.At( i ), m_histogram.At( j+1 ) );
352  }
353 
362  {
363  return Count( m_peakLevel );
364  }
365 
370  count_type PeakCount( int i, int j ) const
371  {
372  PCL_PRECONDITION( i >= 0 && i < m_histogram.Length() )
373  PCL_PRECONDITION( j >= 0 && j < m_histogram.Length() )
374  if ( m_histogram.IsEmpty() )
375  return 0;
376  i = pcl::Range( i, 0, m_histogram.Length()-1 );
377  j = pcl::Range( j, 0, m_histogram.Length()-1 );
378  if ( j < i )
379  pcl::Swap( i, j );
380  return *pcl::MaxItem( m_histogram.At( i ), m_histogram.At( j+1 ) );
381  }
382 
392  int ClipLow( count_type n ) const
393  {
394  int i = 0;
395  for ( count_type s = 0; i < m_histogram.Length()-1 && (s += m_histogram[i]) <= n; ++i ) {}
396  return i;
397  }
398 
404  double NormalizedClipLow( count_type n ) const
405  {
406  return NormalizedLevel( ClipLow( n ) );
407  }
408 
418  int ClipHigh( count_type n ) const
419  {
420  int i = m_histogram.Length();
421  for ( count_type s = 0; --i > 0 && (s += m_histogram[i]) <= n; ) {}
422  return i;
423  }
424 
430  double NormalizedClipHigh( count_type n ) const
431  {
432  return NormalizedLevel( ClipHigh( n ) );
433  }
434 
440  {
441  return m_histogram;
442  }
443 
454  void SetHistogramData( const histogram_type& data )
455  {
456  if ( data.Length() < 2 )
457  Clear();
458  else
459  {
460  m_histogram = data;
461  m_resolution = m_histogram.Length();
462  UpdatePeakLevel();
463  }
464  }
465 
471  void GetData( count_type* where, int fromLevel = 0, int toLevel = -1 ) const
472  {
473  PCL_PRECONDITION( where != nullptr )
474  PCL_PRECONDITION( fromLevel >= 0 )
475  if ( where != nullptr )
476  if ( !m_histogram.IsEmpty() )
477  {
478  fromLevel = pcl::Range( fromLevel, 0, m_histogram.Length()-1 );
479  toLevel = (toLevel < 0) ? m_histogram.Length()-1 : pcl::Range( toLevel, 0, m_histogram.Length()-1 );
480  if ( toLevel < fromLevel )
481  pcl::Swap( fromLevel, toLevel );
482  ::memcpy( where, m_histogram.At( fromLevel ), (1+toLevel-fromLevel)*sizeof( count_type ) );
483  }
484  }
485 
500  void Resample( Histogram& h ) const
501  {
502  if ( h.m_resolution == m_resolution )
503  h = *this;
504  else
505  {
506  if ( m_histogram.IsEmpty() )
507  h.Clear();
508  else
509  {
510  h.Allocate();
511  h.m_histogram = 0;
512  double k = double( h.m_histogram.Length() - 1 )/(m_histogram.Length() - 1);
513  for ( int i = 0; i < m_histogram.Length(); ++i )
514  h.m_histogram[pcl::RoundInt( i*k )] += m_histogram[i];
515  h.m_peakLevel = int( pcl::MaxItem( h.m_histogram.Begin(), h.m_histogram.End() ) - h.m_histogram.Begin() );
516  }
517  }
518  }
519 
527  double Entropy() const
528  {
529  double H = 0;
530  count_type n = Count();
531  if ( n > 0 )
532  for ( int i = 0; i < m_histogram.Length(); ++i )
533  if ( m_histogram[i] > 0 )
534  {
535  double f = double( m_histogram[i] )/n;
536  H -= f*Log( f );
537  }
538  return H;
539  }
540 
544  const Image& operator <<( const Image& );
545 
549  const DImage& operator <<( const DImage& );
550 
555 
560 
565 
571 
578  const Rect& SelectedRectangle() const
579  {
580  return m_rect;
581  }
582 
591  void SelectRectangle( const Rect& r )
592  {
593  m_rect = r;
594  }
595 
603  {
604  m_rect = Rect( 0 );
605  }
606 
613  int SelectedChannel() const
614  {
615  return m_channel;
616  }
617 
625  void SelectChannel( int channel )
626  {
627  m_channel = pcl::Max( -1, channel );
628  }
629 
637  {
638  m_channel = -1;
639  }
640 
641 protected:
642 
643  histogram_type m_histogram; // Discrete histogram levels
644  int m_resolution = 0x10000L; // Number of histogram levels
645  int m_peakLevel = 0; // Maximum level (index of maximum count)
646  Rect m_rect = 0; // ROI, Rect( 0 ) to use target image's selection
647  int m_channel = -1; // < 0 to use target image's selection
648 
649  friend class View;
650  friend class HistogramTransformation;
651 };
652 
653 // ----------------------------------------------------------------------------
654 
655 } // pcl
656 
657 #endif // __PCL_Histogram_h
658 
659 // ----------------------------------------------------------------------------
660 // EOF pcl/Histogram.h - Released 2024-06-18T15:48:54Z
Implements a generic, two-dimensional, shared or local image.
Definition: Image.h:278
A generic rectangle in the two-dimensional space.
Definition: Rectangle.h:314
iterator Begin()
Definition: Vector.h:1900
iterator End()
Definition: Vector.h:1959
int Length() const noexcept
Definition: Vector.h:1784
Multiple histogram transformation.
Discrete image histogram function.
Definition: Histogram.h:76
int HistogramLevel(double x) const
Definition: Histogram.h:267
~Histogram() override
Definition: Histogram.h:134
void GetHistogramRange(int &i, int &j, double a, double b) const
Definition: Histogram.h:287
uint64 count_type
Definition: Histogram.h:83
void Assign(const Histogram &x)
Definition: Histogram.h:151
count_type Count() const
Definition: Histogram.h:312
count_type PeakCount(int i, int j) const
Definition: Histogram.h:370
void Allocate()
Definition: Histogram.h:222
count_type Count(int i) const
Definition: Histogram.h:321
Histogram(int resolution=0x10000L)
Definition: Histogram.h:99
void ClearRectangle()
Definition: Histogram.h:602
void Clear()
Definition: Histogram.h:160
void GetData(count_type *where, int fromLevel=0, int toLevel=-1) const
Definition: Histogram.h:471
int PeakLevel() const
Definition: Histogram.h:236
double Entropy() const
Definition: Histogram.h:527
int SelectedChannel() const
Definition: Histogram.h:613
int LastLevel() const
Definition: Histogram.h:191
int UpdatePeakLevel()
Definition: Histogram.h:257
count_type Count(int i, int j) const
Definition: Histogram.h:341
bool IsEmpty() const
Definition: Histogram.h:170
void SetHistogramData(const histogram_type &data)
Definition: Histogram.h:454
void ClearSelectedChannel()
Definition: Histogram.h:636
const Rect & SelectedRectangle() const
Definition: Histogram.h:578
int ClipLow(count_type n) const
Definition: Histogram.h:392
int Resolution() const
Definition: Histogram.h:183
double NormalizedClipLow(count_type n) const
Definition: Histogram.h:404
int ClipHigh(count_type n) const
Definition: Histogram.h:418
double NormalizedPeakLevel() const
Definition: Histogram.h:245
void SelectRectangle(const Rect &r)
Definition: Histogram.h:591
count_type PeakCount() const
Definition: Histogram.h:361
Histogram(const histogram_type &data)
Definition: Histogram.h:116
const histogram_type & HistogramData() const
Definition: Histogram.h:439
Histogram(const Histogram &)=default
void SetResolution(int resolution)
Definition: Histogram.h:207
void Resample(Histogram &h) const
Definition: Histogram.h:500
double NormalizedLevel(int i) const
Definition: Histogram.h:277
void SelectChannel(int channel)
Definition: Histogram.h:625
void GetNormalizedRange(double &a, double &b, int i, int j) const
Definition: Histogram.h:299
double NormalizedClipHigh(count_type n) const
Definition: Histogram.h:430
Histogram(Histogram &&)=default
Acts like a union for all types of images in PCL, with optional class-wide ownership of transported i...
Definition: ImageVariant.h:322
A process using multiple concurrent execution threads.
High-level interface to a PixInsight view object.
Definition: View.h:213
Array< T, A > & operator<<(Array< T, A > &x, const V &v)
Definition: Array.h:2295
Complex< T > Log(const Complex< T > &c) noexcept
Definition: Complex.h:735
int RoundInt(T x) noexcept
Definition: Math.h:1503
void Swap(GenericPoint< T > &p1, GenericPoint< T > &p2) noexcept
Definition: Point.h:1459
unsigned long long uint64
Definition: Defs.h:682
double Sum(const T *__restrict__ i, const T *__restrict__ j) noexcept
Definition: Math.h:2573
size_type Count(FI i, FI j, const T &v) noexcept
Definition: Utility.h:384
constexpr const T & Range(const T &x, const T &a, const T &b) noexcept
Definition: Utility.h:190
constexpr const T & Max(const T &a, const T &b) noexcept
Definition: Utility.h:119
FI MaxItem(FI i, FI j) noexcept
Definition: Utility.h:479
PCL root namespace.
Definition: AbstractImage.h:77