WorldTransformation.h

Go to the documentation of this file.

//     ____   ______ __
//    / __ \ / ____// /
//   / /_/ // /    / /
//  / ____// /___ / /___   PixInsight Class Library
// /_/     \____//_____/   PCL 2.8.5
// ----------------------------------------------------------------------------
// pcl/WorldTransformation.h - Released 2024-12-28T16:53:48Z
// ----------------------------------------------------------------------------
// 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_WorldTransformation_h
#define __PCL_WorldTransformation_h
 
 
#include <pcl/Defs.h>
#include <pcl/Diagnostics.h>
 
#include <pcl/GridInterpolation.h>
#include <pcl/LinearTransformation.h>
#include <pcl/SurfaceSpline.h>
#include <pcl/WCSKeywords.h>
 
/*
 * Based on original work contributed by Andrés del Pozo.
 */
 
namespace pcl
{
 
// ----------------------------------------------------------------------------
 
#define __PCL_WCS_SPLINE_VERSION_CURRENT                     "2.0"
#define __PCL_WCS_SPLINE_VERSION_OLD                         "1.3"
#define __PCL_WCS_MIN_SPLINE_MAX_POINTS                      1000
#define __PCL_WCS_MAX_SPLINE_MAX_DENSE_POINTS                2100
#define __PCL_WCS_MAX_SPLINE_MAX_DDM_POINTS                  25000
#define __PCL_WCS_DEFAULT_SPLINE_MAX_DENSE_POINTS            2100
#define __PCL_WCS_DEFAULT_SPLINE_MAX_DDM_POINTS              4000
#define __PCL_WCS_DEFAULT_SPLINE_MAX_POINTS                  4000
#define __PCL_WCS_DEFAULT_SPLINE_RBF                         RadialBasisFunction::DDMThinPlateSpline
#define __PCL_WCS_DEFAULT_SPLINE_ORDER                       2
#define __PCL_WCS_DEFAULT_SPLINE_SMOOTHNESS                  0.005F
#define __PCL_WCS_DEFAULT_SURFACE_SIMPLIFIER_ENABLED         true
#define __PCL_WCS_DEFAULT_SURFACE_SIMPLIFIER_REJECT_FRACTION 0.10F
 
// ----------------------------------------------------------------------------
 
class PCL_CLASS WorldTransformation
{
public:
 
   WorldTransformation() = default;
 
   WorldTransformation( const WorldTransformation& ) = default;
 
   virtual ~WorldTransformation()
   {
   }
 
   virtual bool IsEmpty() const
   {
      return false;
   }
 
   virtual WorldTransformation* Clone() const = 0;
 
   virtual DPoint Direct( const DPoint& p ) const = 0;
 
   virtual DPoint Inverse( const DPoint& p ) const = 0;
 
   virtual const LinearTransformation& ApproximateLinearTransform() const = 0;
};
 
// ----------------------------------------------------------------------------
 
class PCL_CLASS LinearWorldTransformation : public WorldTransformation
{
public:
 
   LinearWorldTransformation( const LinearTransformation& transIW )
      : m_transWI( transIW.Inverse() )
      , m_transIW( transIW )
   {
   }
 
   LinearWorldTransformation( const LinearWorldTransformation& ) = default;
 
   LinearWorldTransformation( LinearWorldTransformation&& ) = default;
 
   ~LinearWorldTransformation() override
   {
   }
 
   bool IsEmpty() const override
   {
      return false;
   }
 
   WorldTransformation* Clone() const override
   {
      return new LinearWorldTransformation( *this );
   }
 
   DPoint Direct( const DPoint& p ) const override
   {
      return m_transWI.Transform( p );
   }
 
   DPoint Inverse( const DPoint& p ) const override
   {
      return m_transIW.Transform( p );
   }
 
   const LinearTransformation& ApproximateLinearTransform() const override
   {
      return m_transIW;
   }
 
private:
 
   LinearTransformation m_transWI; // world -> image
   LinearTransformation m_transIW; // image -> world
};
 
// ----------------------------------------------------------------------------
 
class PCL_CLASS XMLElement;
 
class PCL_CLASS SplineWorldTransformation : public WorldTransformation
{
public:
 
   using rbf_type = PointSurfaceSpline::rbf_type;
 
   SplineWorldTransformation( const Array<DPoint>& controlPointsW,
                              const Array<DPoint>& controlPointsI,
                              rbf_type rbf = __PCL_WCS_DEFAULT_SPLINE_RBF,
                              float smoothness = __PCL_WCS_DEFAULT_SPLINE_SMOOTHNESS,
                              int order = __PCL_WCS_DEFAULT_SPLINE_ORDER,
                              bool enableSimplifier = __PCL_WCS_DEFAULT_SURFACE_SIMPLIFIER_ENABLED,
                              float simplifierRejectFraction = __PCL_WCS_DEFAULT_SURFACE_SIMPLIFIER_REJECT_FRACTION,
                              const FVector& weights = FVector() )
      : m_controlPointsW( controlPointsW )
      , m_controlPointsI( controlPointsI )
      , m_rbf( rbf )
      , m_order( order )
      , m_smoothness( smoothness )
      , m_useSimplifiers( enableSimplifier )
      , m_simplifierRejectFraction( simplifierRejectFraction )
      , m_weights( weights )
   {
      EnsureValidRBFParameters();
      InitializeSplines();
      CalculateLinearApproximation();
   }
 
   SplineWorldTransformation( const PropertyArray& properties,
                              const LinearTransformation& linearIW = LinearTransformation::Null(), bool regenerate = false );
 
   SplineWorldTransformation( const ByteArray& data, const LinearTransformation& linearIW = LinearTransformation::Null() )
   {
      Deserialize( data );
      EnsureValidRBFParameters();
      InitializeSplines();
      if ( linearIW.IsSingularMatrix() )
         CalculateLinearApproximation();
      else
         m_linearIW = linearIW;
   }
 
   SplineWorldTransformation( const SplineWorldTransformation& ) = default;
 
   SplineWorldTransformation( SplineWorldTransformation&& ) = default;
 
   ~SplineWorldTransformation() override
   {
   }
 
   SplineWorldTransformation& operator =( const SplineWorldTransformation& ) = default;
 
   SplineWorldTransformation& operator =( SplineWorldTransformation&& ) = default;
 
   bool IsEmpty() const override
   {
      return m_controlPointsW.IsEmpty() || m_controlPointsI.IsEmpty();
   }
 
   WorldTransformation* Clone() const override
   {
      return new SplineWorldTransformation( *this );
   }
 
   DPoint Direct( const DPoint& pW ) const override
   {
      if ( m_gridWI.IsValid() )
         if ( m_gridWI.ReferenceRect().IncludesFast( pW ) )
            return m_gridWI( pW );
      return m_splineWI( pW );
   }
 
   DPoint Inverse( const DPoint& pI ) const override
   {
      if ( m_gridIW.IsValid() )
         if ( m_gridIW.ReferenceRect().IncludesFast( pI ) )
            return m_gridIW( pI );
      return m_splineIW( pI );
   }
 
   const LinearTransformation& ApproximateLinearTransform() const override
   {
      return m_linearIW;
   }
 
   const IsoString& Version() const
   {
      return m_version;
   }
 
   void InitializeGridInterpolations( const Rect& rectI, int deltaI = 16 )
   {
      PCL_PRECONDITION( deltaI >= 1 && deltaI <= 64 )
      deltaI = Range( deltaI, 1, 64 );
 
      /*
       * Compute reference region and grid distance in native spherical
       * coordinates.
       */
      DRect rectW( std::numeric_limits<double>::max(), std::numeric_limits<double>::max(),
                   std::numeric_limits<double>::lowest(), std::numeric_limits<double>::lowest() );
      for ( int x = 0; x < rectI.Width(); ++x )
         for ( int p = 0; p < 2; ++p )
         {
            DPoint pW = m_splineIW( DPoint( double( x ), p*(rectI.Height() - 1) ) );
            if ( pW.x < rectW.x0 )
               rectW.x0 = pW.x;
            if ( pW.x > rectW.x1 )
               rectW.x1 = pW.x;
            if ( pW.y < rectW.y0 )
               rectW.y0 = pW.y;
            if ( pW.y > rectW.y1 )
               rectW.y1 = pW.y;
         }
      for ( int y = 0; y < rectI.Height(); ++y )
         for ( int p = 0; p < 2; ++p )
         {
            DPoint pW = m_splineIW( DPoint( p*(rectI.Width() - 1), double( y ) ) );
            if ( pW.x < rectW.x0 )
               rectW.x0 = pW.x;
            if ( pW.x > rectW.x1 )
               rectW.x1 = pW.x;
            if ( pW.y < rectW.y0 )
               rectW.y0 = pW.y;
            if ( pW.y > rectW.y1 )
               rectW.y1 = pW.y;
         }
      double deltaW = m_splineIW( DPoint( -deltaI/2, -deltaI/2 ) ).DistanceTo(
                           m_splineIW( DPoint( +deltaI/2, +deltaI/2 ) ) )/1.4142;
 
      m_gridWI.Initialize( rectW, deltaW, m_splineWI, false/*verbose*/ );
      m_gridIW.Initialize( rectI, deltaI, m_splineIW, false/*verbose*/ );
   }
 
   bool HasGridInterpolations() const
   {
      return m_gridWI.IsValid() && m_gridIW.IsValid();
   }
 
   double GridInterpolationDelta() const
   {
      return HasGridInterpolations() ? m_gridIW.Delta() : 0.0;
   }
 
   static IsoString PropertyPrefix()
   {
      return "PCL:AstrometricSolution:SplineWorldTransformation:";
   }
 
   PropertyArray ToProperties() const;
 
   void Serialize( ByteArray& data ) const;
 
   int NumberOfControlPoints() const
   {
      return int( m_controlPointsW.Length() );
   }
 
   const Array<DPoint>& NativeControlPoints() const
   {
      return m_controlPointsW;
   }
 
   const Array<DPoint>& ImageControlPoints() const
   {
      return m_controlPointsI;
   }
 
   rbf_type RBFType() const
   {
      return m_rbf;
   }
 
   int SplineOrder() const
   {
      return m_order;
   }
 
   IsoString RBFTypeName() const;
 
   int MaxSplinePoints() const
   {
      return m_maxSplinePoints;
   }
 
   void GetSplineLengths( int& xWI, int& yWI, int& xIW, int& yIW ) const
   {
      xWI = m_splineWI.SplineX().Length();
      yWI = m_splineWI.SplineY().Length();
      xIW = m_splineIW.SplineX().Length();
      yIW = m_splineIW.SplineY().Length();
   }
 
   bool TruncatedControlPoints() const
   {
      return m_truncated; // fetched during initialization
   }
 
   bool SimplifiersEnabled() const
   {
      return m_useSimplifiers;
   }
 
   float SimplifierRejectFraction() const
   {
      return m_simplifierRejectFraction;
   }
 
   void GetSplineErrors( double& xWI, double& yWI, double& xIW, double& yIW ) const
   {
      xWI = m_splineWI.ErrorX();
      yWI = m_splineWI.ErrorY();
      xIW = m_splineIW.ErrorX();
      yIW = m_splineIW.ErrorY();
   }
 
private:
 
   IsoString              m_version = __PCL_WCS_SPLINE_VERSION_CURRENT;
   Array<DPoint>          m_controlPointsW;
   Array<DPoint>          m_controlPointsI;
   rbf_type               m_rbf = __PCL_WCS_DEFAULT_SPLINE_RBF;
   int                    m_order = __PCL_WCS_DEFAULT_SPLINE_ORDER;
   float                  m_smoothness = __PCL_WCS_DEFAULT_SPLINE_SMOOTHNESS;
   int                    m_maxSplinePoints = __PCL_WCS_DEFAULT_SPLINE_MAX_POINTS;
   bool                   m_useSimplifiers = __PCL_WCS_DEFAULT_SURFACE_SIMPLIFIER_ENABLED;
   float                  m_simplifierRejectFraction = __PCL_WCS_DEFAULT_SURFACE_SIMPLIFIER_REJECT_FRACTION;
   FVector                m_weights;
   bool                   m_truncated = false; // true => truncated control point vectors
   Homography             m_projectiveWI;
   Homography             m_projectiveIW;
   PointSurfaceSpline     m_splineWI;
   PointSurfaceSpline     m_splineIW;
   PointGridInterpolation m_gridWI;
   PointGridInterpolation m_gridIW;
   LinearTransformation   m_linearIW;
 
   static PointSurfaceSpline PointSurfaceSplineFromProperties( const PropertyArray&, const IsoString& version );
   static PropertyArray PointSurfaceSplineToProperties( const PointSurfaceSpline&, const IsoString& );
 
   static SurfaceSpline<double> SurfaceSplineFromProperties( const PropertyArray&, const IsoString& version );
   static PropertyArray SurfaceSplineToProperties( const SurfaceSpline<double>&, const IsoString& );
 
   static PointGridInterpolation PointGridInterpolationFromProperties( const PropertyArray&, const IsoString& version );
   static PropertyArray PointGridInterpolationToProperties( const PointGridInterpolation&, const IsoString& );
 
   void Deserialize( const ByteArray& );
   void EnsureValidRBFParameters();
   void InitializeSplines();
   void CalculateLinearApproximation();
};
 
// ----------------------------------------------------------------------------
 
} // pcl
 
#endif   // __PCL_WorldTransformation_h
 
// ----------------------------------------------------------------------------
// EOF pcl/WorldTransformation.h - Released 2024-12-28T16:53:48Z