AstrometricMetadata.h

Go to the documentation of this file.

//     ____   ______ __
//    / __ \ / ____// /
//   / /_/ // /    / /
//  / ____// /___ / /___   PixInsight Class Library
// /_/     \____//_____/   PCL 2.8.5
// ----------------------------------------------------------------------------
// pcl/AstrometricMetadata.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_AstrometricMetadata_h
#define __PCL_AstrometricMetadata_h
 
 
#include <pcl/Defs.h>
 
#include <pcl/AutoPointer.h>
#include <pcl/Optional.h>
#include <pcl/Point.h>
#include <pcl/ProjectionBase.h>
#include <pcl/Property.h>
#include <pcl/SphericalRotation.h>
#include <pcl/TimePoint.h>
#include <pcl/WCSKeywords.h>
#include <pcl/WorldTransformation.h>
 
/*
 * Based on original work contributed by Andrés del Pozo.
 */
 
#ifdef __PCL_BUILDING_PIXINSIGHT_APPLICATION
namespace pi
{
   class ImageWindow;
}
#endif
 
namespace pcl
{
 
// ----------------------------------------------------------------------------
 
// ----------------------------------------------------------------------------
 
#ifndef __PCL_BUILDING_PIXINSIGHT_APPLICATION
class PCL_CLASS ImageWindow;
#endif
 
class PCL_CLASS XISFReader;
class PCL_CLASS XISFWriter;
 
class PCL_CLASS AstrometricMetadata
{
public:
 
   struct DescriptionItems
   {
      String referenceMatrix;
      String wcsTransformationType;
      String controlPoints;
      String splineLengths;
      String splineErrors;
      String projectionName;
      String projectionOrigin;
      String resolution;
      String rotation;
      String referenceSystem;
      String observationStartTime;
      String observationEndTime;
      String observerLocation;
      String focalDistance;
      String pixelSize;
      String fieldOfView;
      String centerCoordinates;
      String topLeftCoordinates;
      String topRightCoordinates;
      String bottomLeftCoordinates;
      String bottomRightCoordinates;
      String referenceCatalog;
      String creationTime;
      String creationSoftware;
   };
 
   AstrometricMetadata() = default;
 
   AstrometricMetadata( const AstrometricMetadata& x )
      : m_projection( x.m_projection->Clone() )
      , m_transformWI( x.m_transformWI->Clone() )
      , m_refSys( x.m_refSys )
      , m_width( x.m_width )
      , m_height( x.m_height )
      , m_pixelSize( x.m_pixelSize )
      , m_obsStartTime( x.m_obsStartTime )
      , m_obsEndTime( x.m_obsEndTime )
      , m_geoLongitude( x.m_geoLongitude )
      , m_geoLatitude( x.m_geoLatitude )
      , m_geoHeight( x.m_geoHeight )
      , m_resolution( x.m_resolution )
      , m_focalLength( x.m_focalLength )
      , m_creationTime( x.m_creationTime )
      , m_catalog( x.m_catalog )
      , m_creatorApp( x.m_creatorApp )
      , m_creatorModule( x.m_creatorModule )
      , m_creatorOS( x.m_creatorOS )
      , m_description( x.m_description )
   {
   }
 
   AstrometricMetadata( AstrometricMetadata&& ) = default;
 
   AstrometricMetadata( ProjectionBase* projection, WorldTransformation* worldTransformation, int width, int height );
 
#ifdef __PCL_BUILDING_PIXINSIGHT_APPLICATION
   // Implemented in /core/Components/ImageWindow/ImageWindow.cpp
   AstrometricMetadata( const pi::ImageWindow* );
#else
   AstrometricMetadata( const ImageWindow& window );
#endif
 
   AstrometricMetadata( XISFReader& reader );
 
   virtual ~AstrometricMetadata()
   {
   }
 
   AstrometricMetadata& operator =( const AstrometricMetadata& x )
   {
      m_projection    = x.m_projection->Clone();
      m_transformWI   = x.m_transformWI->Clone();
      m_refSys        = x.m_refSys;
      m_equinox       = x.m_equinox;
      m_width         = x.m_width;
      m_height        = x.m_height;
      m_pixelSize     = x.m_pixelSize;
      m_obsStartTime  = x.m_obsStartTime;
      m_obsEndTime    = x.m_obsEndTime;
      m_geoLongitude  = x.m_geoLongitude;
      m_geoLatitude   = x.m_geoLatitude;
      m_geoHeight     = x.m_geoHeight;
      m_resolution    = x.m_resolution;
      m_focalLength   = x.m_focalLength;
      m_creationTime  = x.m_creationTime;
      m_catalog       = x.m_catalog;
      m_creatorApp    = x.m_creatorApp;
      m_creatorModule = x.m_creatorModule;
      m_creatorOS     = x.m_creatorOS;
      m_description   = x.m_description;
      return *this;
   }
 
   AstrometricMetadata& operator =( AstrometricMetadata&& ) = default;
 
   bool IsValid() const
   {
      return !m_projection.IsNull() && !m_transformWI.IsNull();
   }
 
   void Verify( DPoint& centerErrors,
                DPoint& topLeftErrors, DPoint& topRightErrors,
                DPoint& bottomLeftErrors, DPoint& bottomRightErrors ) const;
 
   void Validate( double tolerance = 0.01 ) const;
 
   bool HasSplineWorldTransformation() const
   {
      return dynamic_cast<const SplineWorldTransformation*>( m_transformWI.Pointer() ) != nullptr;
   }
 
   bool EnsureSplineGridInterpolationsInitialized( int deltaI = 16 );
 
   AstrometricMetadata Undistorted() const;
 
#ifdef __PCL_BUILDING_PIXINSIGHT_APPLICATION
   // Implemented in /core/Components/ImageWindow/ImageWindow.cpp
   void Write( pi::ImageWindow* window, bool notify = true ) const;
#else
   void Write( ImageWindow& window, bool notify = true ) const;
#endif
 
   void Write( XISFWriter& writer ) const;
 
   IsoString ReferenceSystem() const
   {
      return m_refSys.IsEmpty() ? IsoString( "ICRS" ) : m_refSys;
   }
 
   void SetReferenceSystem( const IsoString& refSys )
   {
      m_refSys = refSys.Trimmed();
   }
 
   static IsoString ReferenceSystemFromMetadata( const PropertyArray& properties, const FITSKeywordArray& keywords );
 
   int Width() const
   {
      return m_width;
   }
 
   int Height() const
   {
      return m_height;
   }
 
   Rect Bounds() const
   {
      return Rect( m_width, m_height );
   }
 
   const ProjectionBase* Projection() const
   {
      return m_projection.Pointer();
   }
 
   const WorldTransformation* WorldTransform() const
   {
      return m_transformWI.Pointer();
   }
 
#ifdef __PCL_BUILDING_PIXINSIGHT_APPLICATION
   WorldTransformation* WorldTransform()
   {
      return m_transformWI.Pointer();
   }
#endif
 
   double ResolutionFromFocal( double focal ) const
   {
      return (focal > 0) ? m_pixelSize.OrElse( 0 )/focal * 0.18/Const<double>::pi() : 0.0;
   }
 
   double FocalFromResolution( double resolution ) const
   {
      return ResolutionFromFocal( resolution );
   }
 
   double Rotation( bool& flipped ) const;
 
   double Resolution() const
   {
      return m_resolution;
   }
 
   template <typename T>
   double ResolutionAt( const GenericPoint<T>& pI ) const
   {
      if ( !IsValid() )
         throw Error( "AstrometricMetadata::ResolutionAt(): No astrometric solution." );
      DPoint pRD1, pRD2, pRD3, pRD4;
      if ( !ImageToCelestial( pRD1, DPoint( pI.x, pI.y - 0.5 ) )
        || !ImageToCelestial( pRD2, DPoint( pI.x, pI.y + 0.5 ) )
        || !ImageToCelestial( pRD3, DPoint( pI.x - 0.5, pI.y ) )
        || !ImageToCelestial( pRD4, DPoint( pI.x + 0.5, pI.y ) ) )
      {
         throw Error( "AstrometricMetadata::ResolutionAt(): Failed to perform coordinate transformation(s)." );
      }
      return 0.5*(m_projection->Distance( pRD1, pRD2 ) + m_projection->Distance( pRD3, pRD4 ));
   }
 
   double SearchRadius() const
   {
      if ( !IsValid() )
         throw Error( "AstrometricMetadata::SearchRadius(): No astrometric solution." );
      DPoint cRD;
      if ( !ImageToCelestial( cRD, DPoint( 0.5*m_width, 0.5*m_height ) ) )
         throw Error( "AstrometricMetadata::SearchRadius(): Failed to perform coordinate transformation." );
      DPoint pRD1, pRD2, pRD3, pRD4;
      if ( !ImageToCelestial( pRD1, DPoint( 0,       0 ) )
        || !ImageToCelestial( pRD2, DPoint( m_width, 0 ) )
        || !ImageToCelestial( pRD3, DPoint( 0,       m_height ) )
        || !ImageToCelestial( pRD4, DPoint( m_width, m_height ) ) )
      {
         return 180;
      }
      return Max( Max( Max( m_projection->Distance( cRD, pRD1 ), m_projection->Distance( cRD, pRD2 ) ),
                       m_projection->Distance( cRD, pRD3 ) ),
                  m_projection->Distance( cRD, pRD4 ) );
   }
 
   Optional<TimePoint> ObservationStartTime() const
   {
      return m_obsStartTime;
   }
 
   void SetObservationStartTime( TimePoint startTime )
   {
      m_obsStartTime = startTime;
   }
 
   Optional<TimePoint> ObservationEndTime() const
   {
      return m_obsEndTime;
   }
 
   void SetObservationEndTime( TimePoint endTime )
   {
      m_obsEndTime = endTime;
   }
 
   Optional<TimePoint> ObservationMiddleTime() const
   {
      if ( !m_obsStartTime.IsDefined() )
         return Optional<TimePoint>();
      if ( !m_obsEndTime.IsDefined() )
         return m_obsStartTime;
      return m_obsStartTime() + (m_obsEndTime() - m_obsStartTime())/2;
   }
 
   Optional<double> LocationLongitude() const
   {
      return m_geoLongitude;
   }
 
   void SetLocationLongitude( double longitude )
   {
      if ( longitude > 180 )
         longitude -= 360;
      else if ( longitude <= -180 )
         longitude += 360;
      if ( longitude < -180 || longitude > +180 )
         throw Error( "AstrometricMetadata::SetLocationLongitude(): Geographic longitude out of range." );
      m_geoLongitude = longitude;
   }
 
   Optional<double> LocationLatitude() const
   {
      return m_geoLatitude;
   }
 
   void SetLocationLatitude( double latitude )
   {
      if ( latitude < -90 || latitude > +90 )
         throw Error( "AstrometricMetadata::SetLocationLatitude(): Geographic latitude out of range." );
      m_geoLatitude = latitude;
   }
 
   Optional<double> LocationHeight() const
   {
      return m_geoHeight;
   }
 
   void SetLocationHeight( double height )
   {
      m_geoHeight = height;
   }
 
   void UndefineObservationLocationMetadata()
   {
      m_geoLongitude.Undefine();
      m_geoLatitude.Undefine();
      m_geoHeight.Undefine();
   }
 
   Optional<double> PixelSize() const
   {
      return m_pixelSize;
   }
 
   void SetPixelSize( double pixelSize )
   {
      m_pixelSize = pixelSize;
      m_focalLength = FocalFromResolution( m_resolution );
   }
 
   Optional<TimePoint> CreationTime() const
   {
      return m_creationTime;
   }
 
   String Catalog() const
   {
      return m_catalog;
   }
 
   String CreatorApplication() const
   {
      return m_creatorApp;
   }
 
   String CreatorModule() const
   {
      return m_creatorModule;
   }
 
   String CreatorOS() const
   {
      return m_creatorOS;
   }
 
   bool ImageToCelestial( DPoint& pRD, const DPoint& pI ) const
   {
      if ( !IsValid() )
         throw Error( "AstrometricMetadata::ImageToCelestial(): No astrometric solution." );
      if ( m_projection->Inverse( pRD, m_transformWI->Inverse( pI ) ) )
      {
         // Constrain right ascension to the [0,360) range.
         if ( pRD.x < 0 )
            pRD.x += 360;
         else if ( pRD.x >= 360 )
            pRD.x -= 360;
         return true;
      }
      return false;
   }
 
   bool RawImageToCelestial( DPoint& pRD, const DPoint& pI ) const
   {
      if ( !IsValid() )
         throw Error( "AstrometricMetadata::RawImageToCelestial(): No astrometric solution." );
      return m_projection->Inverse( pRD, m_transformWI->Inverse( pI ) );
   }
 
   bool ImageCenterToCelestial( DPoint& pRD ) const
   {
      return ImageToCelestial( pRD, DPoint( 0.5*m_width, 0.5*m_height ) );
   }
 
   bool CelestialToImage( DPoint& pI, const DPoint& pRD ) const
   {
      if ( !IsValid() )
         throw Error( "AstrometricMetadata::CelestialToImage(): No astrometric solution." );
      DPoint pW;
      if ( m_projection->Direct( pW, pRD ) )
      {
         pI = m_transformWI->Direct( pW );
         return true;
      }
      return false;
   }
 
   void Build( const PropertyArray& properties, const FITSKeywordArray& keywords, int width, int height, bool regenerate = false );
 
   PropertyArray ToProperties() const;
 
   void UpdateBasicKeywords( FITSKeywordArray& keywords ) const;
 
   void UpdateWCSKeywords( FITSKeywordArray& keywords, bool generate = false ) const;
 
   void UpdateProperties( PropertyArray& properties ) const;
 
   void UndefineTimeAndLocationMetadata()
   {
      m_obsStartTime.Undefine();
      m_obsEndTime.Undefine();
      m_geoLongitude.Undefine();
      m_geoLatitude.Undefine();
      m_geoHeight.Undefine();
   }
 
   void CopyTimeAndLocationMetadata( const AstrometricMetadata& source )
   {
      m_obsStartTime = source.m_obsStartTime;
      m_obsEndTime   = source.m_obsEndTime;
      m_geoLongitude = source.m_geoLongitude;
      m_geoLatitude  = source.m_geoLatitude;
      m_geoHeight    = source.m_geoHeight;
   }
 
   void CopyTimeAndLocationMetadata( const WCSKeywords& wcs )
   {
      if ( wcs.dateobs.IsDefined() )
         m_obsStartTime = TimePoint( wcs.dateobs() );
      else
         m_obsStartTime.Undefine();
 
      if ( wcs.dateend.IsDefined() )
         m_obsEndTime = TimePoint( wcs.dateend() );
      else
         m_obsEndTime.Undefine();
 
      m_geoLongitude = wcs.longobs;
      m_geoLatitude = wcs.latobs;
      m_geoHeight = wcs.altobs;
   }
 
   static void RemoveKeywords( FITSKeywordArray& keywords, bool removeCenterKeywords = true, bool removeScaleKeywords = true );
 
   static void RescalePixelSizeKeywords( FITSKeywordArray& keywords, double scalingFactor );
 
   static void RemoveProperties( PropertyArray& properties, bool removeCenterProperties = true, bool removeScaleProperties = true );
 
   static void RemoveProperties( ImageWindow& window, bool removeCenterProperties = true, bool removeScaleProperties = true );
 
   static void RescalePixelSizeProperties( PropertyArray& properties, double scalingFactor );
 
   static void RescalePixelSizeProperties( ImageWindow& window, double scalingFactor );
 
   String Summary() const;
 
   DescriptionItems Description() const
   {
      UpdateDescription();
      return m_description.IsNull() ? DescriptionItems() : *m_description;
   }
 
   static void RemoveObservationLocationProperties( PropertyArray& properties );
 
   static void RemoveObservationLocationProperties( ImageWindow& window );
 
   static void RemoveSplineWorldTransformationProperties( PropertyArray& );
 
#ifdef __PCL_BUILDING_PIXINSIGHT_APPLICATION
   // Implemented in /core/Components/ImageWindow/ImageWindow.cpp
   static void RemoveSplineWorldTransformationProperties( pi::ImageWindow* );
#else
   static void RemoveSplineWorldTransformationProperties( ImageWindow& );
#endif
 
private:
 
   AutoPointer<ProjectionBase>      m_projection;
   AutoPointer<WorldTransformation> m_transformWI;
   IsoString                        m_refSys;         // ICRS(default) or GCRS
   Optional<double>                 m_equinox;        // years - deprecated
   int                              m_width = 0;      // px
   int                              m_height = 0;     // px
   Optional<double>                 m_pixelSize;      // um
   Optional<TimePoint>              m_obsStartTime;   // UTC
   Optional<TimePoint>              m_obsEndTime;     // UTC
   Optional<double>                 m_geoLongitude;   // deg
   Optional<double>                 m_geoLatitude;    // deg
   Optional<double>                 m_geoHeight;      // m
   double                           m_resolution = 0; // deg/px
   Optional<double>                 m_focalLength;    // mm
   Optional<TimePoint>              m_creationTime;
   String                           m_catalog;
   String                           m_creatorApp;
   String                           m_creatorModule;
   String                           m_creatorOS;
   mutable
   AutoPointer<DescriptionItems>    m_description;
 
   WCSKeywords ComputeWCSKeywords() const;
   void UpdateDescription() const;
};
 
} //pcl
 
#endif // __AstrometricMetadata_h
 
// ----------------------------------------------------------------------------
// EOF pcl/AstrometricMetadata.h - Released 2024-12-28T16:53:48Z