DrizzleData.h

Go to the documentation of this file.

//     ____   ______ __
//    / __ \ / ____// /
//   / /_/ // /    / /
//  / ____// /___ / /___   PixInsight Class Library
// /_/     \____//_____/   PCL 2.7.0
// ----------------------------------------------------------------------------
// pcl/DrizzleData.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_DrizzleData_h
#define __PCL_DrizzleData_h
 
 
#include <pcl/Defs.h>
 
#include <pcl/File.h>
#include <pcl/GridInterpolation.h>
#include <pcl/MultiVector.h>
#include <pcl/SurfaceSpline.h>
#include <pcl/TimePoint.h>
 
namespace pcl
{
 
// ----------------------------------------------------------------------------
 
namespace DrizzleParserOption
{
   enum mask_type
   {
      IgnoreIntegrationData  = 0x00000001,
      RequireIntegrationData = 0x00000002,
   };
}
 
using DrizzleParserOptions = Flags<DrizzleParserOption::mask_type>;
 
// ----------------------------------------------------------------------------
 
class PCL_CLASS XMLDocument;
class PCL_CLASS XMLElement;
 
class PCL_CLASS DrizzleData
{
public:
 
   using vector_spline = PointSurfaceSpline;
 
   using spline = vector_spline::spline;
 
   using point_list = Array<DPoint>;
 
   using weight_vector = Array<float>;
 
   using rejection_coordinates = Array<Point>;
 
   using rejection_data = Array<rejection_coordinates>;
 
   DrizzleData() = default;
 
   DrizzleData( const DrizzleData& ) = default;
 
   DrizzleData( DrizzleData&& ) = default;
 
   DrizzleData( const String& filePath, DrizzleParserOptions options = DrizzleParserOptions() )
   {
      Parse( filePath, options );
   }
 
   DrizzleData( const XMLDocument& xml, DrizzleParserOptions options = DrizzleParserOptions() )
   {
      Parse( xml, options );
   }
 
   DrizzleData( const XMLElement& element, DrizzleParserOptions options = DrizzleParserOptions() )
   {
      Parse( element, options );
   }
 
   virtual ~DrizzleData()
   {
   }
 
   DrizzleData& operator =( const DrizzleData& ) = default;
 
   DrizzleData& operator =( DrizzleData&& ) = default;
 
   const String& SourceFilePath() const
   {
      return m_sourceFilePath;
   }
 
   void SetSourceFilePath( const String& filePath )
   {
      m_sourceFilePath = File::FullPath( filePath );
   }
 
   const String& CFASourceFilePath() const
   {
      return m_cfaSourceFilePath;
   }
 
   void SetCFASourceFilePath( const String& filePath )
   {
      m_cfaSourceFilePath = File::FullPath( filePath );
   }
 
   const String& CFASourcePattern() const
   {
      return m_cfaSourcePattern;
   }
 
   void SetCFASourcePattern( const String& cfaPattern )
   {
      m_cfaSourcePattern = cfaPattern;
   }
 
   int CFASourceChannel() const
   {
      return m_cfaSourceChannel;
   }
 
   void SetCFASourceChannel( int channel )
   {
      m_cfaSourceChannel = Range( channel, -1, int( int32_max ) );
   }
 
   const String& AlignmentTargetFilePath() const
   {
      return m_alignTargetFilePath;
   }
 
   void SetAlignmentTargetFilePath( const String& filePath )
   {
      m_alignTargetFilePath = File::FullPath( filePath );
   }
 
   int ReferenceWidth() const
   {
      return m_referenceWidth;
   }
 
   int ReferenceHeight() const
   {
      return m_referenceHeight;
   }
 
   void SetReferenceDimensions( int width, int height )
   {
      m_referenceWidth = width;
      m_referenceHeight = height;
   }
 
   int NumberOfChannels() const
   {
      return m_location.Length();
   }
 
   const DPoint& AlignmentOrigin() const
   {
      return m_alignmentOrigin;
   }
 
   void SetAlignmentOrigin( const DPoint& p0 )
   {
      m_alignmentOrigin = p0;
   }
 
   const Matrix& AlignmentMatrix() const
   {
      return m_H;
   }
 
   void SetAlignmentMatrix( const Matrix& H )
   {
      m_H = H;
   }
 
   bool HasAlignmentMatrix() const
   {
      return !m_H.IsEmpty();
   }
 
   const vector_spline& AlignmentSplines() const
   {
      return m_S;
   }
 
   void SetAlignmentSplines( const vector_spline& S )
   {
      m_S = S;
   }
 
   bool HasAlignmentSplines() const
   {
      return m_S.IsValid();
   }
 
   const vector_spline& AlignmentInverseSplines() const
   {
      return m_Sinv;
   }
 
   void SetAlignmentInverseSplines( const vector_spline& Sinv )
   {
      m_Sinv = Sinv;
   }
 
   bool HasAlignmentInverseSplines() const
   {
      return m_Sinv.IsValid();
   }
 
   void GetLocalDistortionModel( point_list& P1, point_list& D2,
                                 point_list& P2, point_list& D1,
                                 weight_vector& W,
                                 int& order, float& regularization, bool& extrapolate )
   {
      P1 = m_LP1;
      D2 = m_LD2;
      P2 = m_LP2;
      D1 = m_LD1;
      W = m_LW;
      order = m_localDistortionOrder;
      regularization = m_localDistortionRegularization;
      extrapolate = m_localDistortionExtrapolation;
   }
 
   bool HasLocalDistortionModel() const
   {
      return !m_LP1.IsEmpty();
   }
 
   const String& Metadata() const
   {
      return m_metadata;
   }
 
   void SetMetadata( const String& metadata )
   {
      m_metadata = metadata.Trimmed();
   }
 
   const DVector& Location() const
   {
      return m_location;
   }
 
   void SetLocation( const DVector& v )
   {
      m_location = v;
   }
 
   const DVector& ReferenceLocation() const
   {
      return m_referenceLocation;
   }
 
   void SetReferenceLocation( const DVector& v )
   {
      m_referenceLocation = v;
   }
 
   const DVector& Scale() const
   {
      if ( !m_scale.IsEmpty() )
         return m_scale;
      if ( m_unitScale.IsEmpty() )
         m_unitScale = DVector( 1.0, NumberOfChannels() );
      return m_unitScale;
   }
 
   void SetScale( const DVector& v )
   {
      m_scale = v;
   }
 
   const point_list& AdaptiveNormalizationCoordinates() const
   {
      return m_adaptiveCoordinates;
   }
 
   void SetAdaptiveNormalizationCoordinates( const point_list& points )
   {
      m_adaptiveCoordinates = points;
   }
 
   const MultiVector& AdaptiveNormalizationLocationVectors() const
   {
      return m_adaptiveLocation;
   }
 
   void SetAdaptiveNormalizationLocationVectors( const MultiVector& m )
   {
      m_adaptiveLocation = m;
   }
 
   void GetAdaptiveNormalizationScaleVectors( MultiVector& sLow, MultiVector& sHigh ) const
   {
      sLow = m_adaptiveScaleLow;
      sHigh = m_adaptiveScaleHigh;
   }
 
   void SetAdaptiveNormalizationScaleVectors( const MultiVector& sLow, const MultiVector& sHigh )
   {
      m_adaptiveScaleLow = sLow;
      m_adaptiveScaleHigh = sHigh;
   }
 
   void GetAdaptiveNormalizationZeroOffsetVectors( MultiVector& mLow, MultiVector& mHigh ) const
   {
      mLow = m_adaptiveZeroOffsetLow;
      mHigh = m_adaptiveZeroOffsetHigh;
   }
 
   void SetAdaptiveNormalizationZeroOffsetVectors( const MultiVector& mLow, const MultiVector& mHigh )
   {
      m_adaptiveZeroOffsetLow = mLow;
      m_adaptiveZeroOffsetHigh = mHigh;
   }
 
   bool HasAdaptiveNormalizationData() const
   {
      return !m_adaptiveCoordinates.IsEmpty() &&
             !m_adaptiveLocation.IsEmpty() &&
             !m_adaptiveScaleLow.IsEmpty() &&
             !m_adaptiveScaleHigh.IsEmpty() &&
             !m_adaptiveZeroOffsetLow.IsEmpty() &&
             !m_adaptiveZeroOffsetHigh.IsEmpty();
   }
 
   double Pedestal() const
   {
      return m_pedestal;
   }
 
   void SetPedestal( double p )
   {
      m_pedestal = Range( p, 0.0, 1.0 );
   }
 
   const DVector& Weight() const
   {
      if ( !m_weight.IsEmpty() )
         return m_weight;
      if ( m_unitWeight.IsEmpty() )
         m_unitWeight = DVector( 1.0, NumberOfChannels() );
      return m_unitWeight;
   }
 
   void SetWeight( const DVector& v )
   {
      m_weight = v;
   }
 
   bool HasIntegrationData() const
   {
      return !m_location.IsEmpty();
   }
 
   bool HasImageWeightsData() const
   {
      return !m_weight.IsEmpty();
   }
 
   const UI64Vector& RejectionLowCount() const
   {
      return m_rejectionLowCount;
   }
 
   const UI64Vector& RejectionHighCount() const
   {
      return m_rejectionHighCount;
   }
 
   const UInt8Image& RejectionMap() const
   {
      return m_rejectionMap;
   }
 
   bool IsRejected( const Point& position, int channel = 0 ) const
   {
      return  m_rejectionMap.Includes( position )
          &&  m_rejectionMap.IsValidChannelIndex( channel )
          && (m_rejectionMap( position, channel ) & 0x3F) != 0;
   }
 
   void SetRejectionMap( const UInt8Image& map )
   {
      m_rejectionMap = map;
   }
 
   bool HasRejectionData() const
   {
      return !m_rejectionMap.IsEmpty();
   }
 
   TimePoint CreationTime() const
   {
      return m_creationTime;
   }
 
   void Clear();
 
   void ClearIntegrationData();
 
   void Parse( const String& filePath, DrizzleParserOptions options = DrizzleParserOptions() );
 
   void Parse( const XMLDocument& xml, DrizzleParserOptions options = DrizzleParserOptions() );
 
   void Parse( const XMLElement& element, DrizzleParserOptions options = DrizzleParserOptions() );
 
   bool IsCompressionEnabled() const
   {
      return m_compressionEnabled;
   }
 
   void EnableCompression( bool enable = true )
   {
      m_compressionEnabled = enable;
   }
 
   void DisableCompression( bool disable = true )
   {
      EnableCompression( !disable );
   }
 
   XMLDocument* Serialize() const;
 
   void SerializeToFile( const String& path ) const;
 
private:
 
           String         m_sourceFilePath;
           String         m_cfaSourceFilePath;
           String         m_cfaSourcePattern;
           int            m_cfaSourceChannel = -1;
           String         m_alignTargetFilePath;
           int            m_referenceWidth  = -1;
           int            m_referenceHeight = -1;
           DPoint         m_alignmentOrigin = 0.5;
           Matrix         m_H;
           vector_spline  m_S;
           vector_spline  m_Sinv;
           point_list     m_LP1;                                   // D* = deprecated
           point_list     m_LD2;                                   // D*
           point_list     m_LP2;                                   // D*
           point_list     m_LD1;                                   // D*
           weight_vector  m_LW;                                    // D*
           int            m_localDistortionOrder = 2;              // D*
           float          m_localDistortionRegularization = 0.01F; // D*
           bool           m_localDistortionExtrapolation = true;   // D*
           String         m_metadata;
           double         m_pedestal = 0.0;
           Vector         m_location;
           Vector         m_referenceLocation;
           Vector         m_scale;
   mutable Vector         m_unitScale;
           Vector         m_weight;
   mutable Vector         m_unitWeight;
           point_list     m_adaptiveCoordinates;
           MultiVector    m_adaptiveLocation;
           MultiVector    m_adaptiveScaleLow;
           MultiVector    m_adaptiveScaleHigh;
           MultiVector    m_adaptiveZeroOffsetLow;
           MultiVector    m_adaptiveZeroOffsetHigh;
           UI64Vector     m_rejectionLowCount;
           UI64Vector     m_rejectionHighCount;
           UInt8Image     m_rejectionMap;
           TimePoint      m_creationTime;
           bool           m_compressionEnabled = true;
 
           // Working data for spline deserialization.
           spline         m_Sx;
           spline         m_Sy;
           Matrix         m_SH;
           spline         m_Sxinv;
           spline         m_Syinv;
           Matrix         m_SinvH;
 
           // Working data for old text format compatibility.
           rejection_data m_rejectLowData;
           rejection_data m_rejectHighData;
 
   void ParseRejectionMap( const XMLElement& );
   void SerializeRejectionMap( XMLElement* ) const;
 
   static void ParseSpline( spline&, const XMLElement& );
   static void SerializeSpline( XMLElement*, const spline& );
 
   static point_list ParsePoints( const XMLElement& );
   void SerializePoints( XMLElement*, const point_list& ) const;
 
   static weight_vector ParseDistortionWeights( const XMLElement& );
   void SerializeDistortionWeights( XMLElement*, const weight_vector& ) const;
 
   static ByteArray ParseMaybeCompressedData( const XMLElement& );
   void SerializeMaybeCompressedData( XMLElement* root,
                        const void* data, size_type size, size_type itemSize = 1 ) const;
 
   class PlainTextDecoder
   {
   public:
 
      PlainTextDecoder( DrizzleData* data, bool ignoreIntegrationData )
         : m_data( data )
         , m_ignoreIntegrationData( ignoreIntegrationData )
      {
      }
 
      virtual ~PlainTextDecoder()
      {
      }
 
      void Decode( IsoString&, size_type start = 0, size_type end = 0 );
 
   protected:
 
      PlainTextDecoder() = default;
 
   private:
 
      DrizzleData* m_data = nullptr;
      bool         m_ignoreIntegrationData = false;
 
      virtual void ProcessBlock( IsoString&, const IsoString&, size_type, size_type );
 
      static rejection_coordinates ParseRejectionCoordinates( IsoString&, size_type, size_type );
      static rejection_data ParseRejectionData( IsoString&, size_type, size_type );
      static spline ParseSurfaceSpline( IsoString&, size_type, size_type );
   };
 
   class PlainTextSplineDecoder : public PlainTextDecoder
   {
   public:
 
      PlainTextSplineDecoder( spline& S )
         : m_S( S )
      {
      }
 
   private:
 
      spline& m_S;
 
      void ProcessBlock( IsoString&, const IsoString&, size_type, size_type ) override;
   };
};
 
// ----------------------------------------------------------------------------
 
} // pcl
 
#endif   // __PCL_DrizzleData_h
 
// ----------------------------------------------------------------------------
// EOF pcl/DrizzleData.h - Released 2024-06-18T15:48:54Z