EphemerisFile.h

Go to the documentation of this file.

//     ____   ______ __
//    / __ \ / ____// /
//   / /_/ // /    / /
//  / ____// /___ / /___   PixInsight Class Library
// /_/     \____//_____/   PCL 2.7.0
// ----------------------------------------------------------------------------
// pcl/EphemerisFile.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_EphemerisFile_h
#define __PCL_EphemerisFile_h
 
 
#include <pcl/Defs.h>
 
#include <pcl/Atomic.h>
#include <pcl/AutoLock.h>
#include <pcl/AutoPointer.h>
#include <pcl/ChebyshevFit.h>
#include <pcl/File.h>
#include <pcl/Mutex.h>
#include <pcl/Optional.h>
#include <pcl/Thread.h>
#include <pcl/TimePoint.h>
 
#ifdef __PCL_BUILDING_PIXINSIGHT_APPLICATION
namespace pi
{
   class JSEphemerisFileObject;
   class JSEphemerisHandleObject;
}
#endif
 
namespace pcl
{
 
// ----------------------------------------------------------------------------
 
class PCL_CLASS XMLElement;
 
// ----------------------------------------------------------------------------
 
struct PCL_CLASS EphemerisMetadata
{
   TimePoint creationTime;       
   String    creatorOS;          
   String    creatorApplication; 
   String    title;              
   String    briefDescription;   
   String    description;        
   String    organizationName;   
   String    authors;            
   String    copyright;          
};
 
// ----------------------------------------------------------------------------
 
struct PCL_CLASS EphemerisConstant
{
   IsoString name;   
   double    value;  
 
   EphemerisConstant( const IsoString& n = IsoString(), double v = 0 )
      : name( n )
      , value( v )
   {
   }
 
   EphemerisConstant( const EphemerisConstant& ) = default;
 
   EphemerisConstant( EphemerisConstant&& ) = default;
 
   EphemerisConstant& operator =( const EphemerisConstant& ) = default;
 
   EphemerisConstant& operator =( EphemerisConstant&& ) = default;
 
   bool operator ==( const EphemerisConstant& x ) const
   {
      return name.CompareIC( x.name ) == 0;
   }
 
   bool operator <( const EphemerisConstant& x ) const
   {
      return name.CompareIC( x.name ) < 0;
   }
};
 
using EphemerisConstantList = Array<EphemerisConstant>;
 
// ----------------------------------------------------------------------------
 
struct PCL_CLASS SerializableEphemerisData
{
   TimePoint    startTime;
 
   ChebyshevFit expansion;
 
   SerializableEphemerisData( TimePoint t, const ChebyshevFit& T )
      : startTime( t )
      , expansion( T )
   {
   }
 
   SerializableEphemerisData( const SerializableEphemerisData& ) = default;
 
   SerializableEphemerisData( SerializableEphemerisData&& ) = default;
 
   SerializableEphemerisData& operator =( const SerializableEphemerisData& ) = default;
 
   SerializableEphemerisData& operator =( SerializableEphemerisData&& ) = default;
};
 
using SerializableEphemerisDataList = Array<SerializableEphemerisData>;
 
// ----------------------------------------------------------------------------
 
struct PCL_CLASS SerializableEphemerisObjectData
{
   IsoString                     objectId;
 
   IsoString                     originId;
 
   String                        objectName;
 
   String                        description;
 
   SerializableEphemerisDataList data[ 2 ];
 
   Optional<double>              H;
 
   Optional<double>              G;
 
   Optional<double>              M1;
 
   Optional<double>              K1;
 
   Optional<double>              M2;
 
   Optional<double>              K2;
 
   Optional<double>              PC;
 
   Optional<double>              B_V;
 
   Optional<double>              U_B;
 
   Optional<double>              I_R;
 
   Optional<double>              D;
 
   Optional<double>              A1;
 
   Optional<double>              A2;
 
   Optional<double>              A3;
 
   Optional<double>              DT;
 
   SerializableEphemerisObjectData( const IsoString& id,
                                    const IsoString& origin,
                                    const String& name = String(),
                                    const String& desc = String() )
      : objectId( id.Trimmed() )
      , originId( origin.Trimmed() )
      , objectName( name.Trimmed() )
      , description( desc )
   {
   }
 
   SerializableEphemerisObjectData() = default;
 
   SerializableEphemerisObjectData( const SerializableEphemerisObjectData& ) = default;
 
   SerializableEphemerisObjectData( SerializableEphemerisObjectData&& ) = default;
 
   SerializableEphemerisObjectData& operator =( const SerializableEphemerisObjectData& ) = default;
 
   SerializableEphemerisObjectData& operator =( SerializableEphemerisObjectData&& ) = default;
};
 
using SerializableEphemerisObjectDataList = Array<SerializableEphemerisObjectData>;
 
// ----------------------------------------------------------------------------
 
struct PCL_CLASS EphemerisObject
{
   IsoString                     objectId;
 
   IsoString                     originId;
 
   String                        objectName;
 
   String                        objectDescription;
 
   Optional<double>              H;
 
   Optional<double>              G;
 
   Optional<double>              M1;
 
   Optional<double>              K1;
 
   Optional<double>              M2;
 
   Optional<double>              K2;
 
   Optional<double>              PC;
 
   Optional<double>              B_V;
 
   Optional<double>              U_B;
 
   Optional<double>              I_R;
 
   Optional<double>              D;
 
   Optional<double>              A1;
 
   Optional<double>              A2;
 
   Optional<double>              A3;
 
   Optional<double>              DT;
 
   EphemerisObject( const IsoString& a_objectId,
                    const IsoString& a_originId,
                    const String&    a_objectName = String(),
                    const String&    a_objectDescription = String(),
                    Optional<double> a_H = Optional<double>(),
                    Optional<double> a_G = Optional<double>(),
                    Optional<double> a_M1 = Optional<double>(),
                    Optional<double> a_K1 = Optional<double>(),
                    Optional<double> a_M2 = Optional<double>(),
                    Optional<double> a_K2 = Optional<double>(),
                    Optional<double> a_PC = Optional<double>(),
                    Optional<double> a_B_V = Optional<double>(),
                    Optional<double> a_U_B = Optional<double>(),
                    Optional<double> a_I_R = Optional<double>(),
                    Optional<double> a_D = Optional<double>(),
                    Optional<double> a_A1 = Optional<double>(),
                    Optional<double> a_A2 = Optional<double>(),
                    Optional<double> a_A3 = Optional<double>(),
                    Optional<double> a_DT = Optional<double>() )
      : objectId( a_objectId )
      , originId( a_originId )
      , objectName( a_objectName )
      , objectDescription( a_objectDescription )
      , H( a_H )
      , G( a_G )
      , M1( a_M1 )
      , K1( a_K1 )
      , M2( a_M2 )
      , K2( a_K2 )
      , PC( a_PC )
      , B_V( a_B_V )
      , U_B( a_U_B )
      , I_R( a_I_R )
      , D( a_D )
      , A1( a_A1 )
      , A2( a_A2 )
      , A3( a_A3 )
      , DT( a_DT )
   {
   }
 
   EphemerisObject( const EphemerisObject& ) = default;
 
   EphemerisObject( EphemerisObject&& ) = default;
 
   EphemerisObject& operator =( const EphemerisObject& ) = default;
 
   EphemerisObject& operator =( EphemerisObject&& ) = default;
};
 
using EphemerisObjectList = Array<EphemerisObject>;
 
// ----------------------------------------------------------------------------
 
class PCL_CLASS EphemerisFile
{
public:
 
   EphemerisFile() = default;
 
   EphemerisFile( const String& filePath )
   {
      Open( filePath );
   }
 
   EphemerisFile( EphemerisFile&& x )
      : m_file( std::move( x.m_file ) )
      , m_startTime( x.m_startTime )
      , m_endTime( x.m_endTime )
      , m_constants( std::move( x.m_constants ) )
      , m_index( std::move( x.m_index ) )
   {
   }
 
   EphemerisFile& operator =( EphemerisFile&& x )
   {
      m_file = std::move( x.m_file );
      m_startTime = x.m_startTime;
      m_endTime = x.m_endTime;
      m_constants = std::move( x.m_constants );
      m_index = std::move( x.m_index );
      return *this;
   }
 
   EphemerisFile( const EphemerisFile& ) = delete;
 
   EphemerisFile& operator =( const EphemerisFile& ) = delete;
 
   virtual ~EphemerisFile() noexcept( false );
 
   void Open( const String& filePath );
 
   void Close();
 
   bool IsOpen() const
   {
      return m_file.IsOpen();
   }
 
   const String& FilePath() const
   {
      return m_file.FilePath();
   }
 
   TimePoint StartTime() const
   {
      return m_startTime;
   }
 
   TimePoint EndTime() const
   {
      return m_endTime;
   }
 
   const EphemerisConstantList& Constants() const
   {
      return m_constants;
   }
 
   bool IsConstantAvailable( const IsoString& name ) const
   {
      return BinarySearch( m_constants.Begin(), m_constants.End(),
                           EphemerisConstant( name ) ) != m_constants.End();
   }
 
   double ConstantValue( const IsoString& name ) const
   {
      EphemerisConstantList::const_iterator i =
         BinarySearch( m_constants.Begin(), m_constants.End(), EphemerisConstant( name ) );
      if ( i == m_constants.End() )
         throw Error( "Undefined ephemeris constant '" + name + '\'' );
      return i->value;
   }
 
   EphemerisObjectList Objects() const
   {
      EphemerisObjectList objects;
      for ( const Index& ix : m_index )
         objects << EphemerisObject( ix.objectId, ix.originId,
                                     ix.objectName, ix.objectDescription,
                                     ix.H, ix.G, ix.M1, ix.K1, ix.M2, ix.K2, ix.PC, ix.B_V, ix.U_B, ix.I_R, ix.D,
                                     ix.A1, ix.A2, ix.A3, ix.DT );
      return objects;
   }
 
   IsoStringList ObjectIds() const
   {
      IsoStringList ids;
      for ( const Index& ix : m_index )
         ids << ix.objectId;
      return ids;
   }
 
   StringList ObjectNames() const
   {
      StringList names;
      for ( const Index& ix : m_index )
         names << ix.objectName;
      return names;
   }
 
   bool IsObjectAvailable( const IsoString& object, const IsoString& origin = IsoString() ) const
   {
      Array<Index>::const_iterator i = BinarySearch( m_index.Begin(), m_index.End(), Index( object, origin ) );
      if ( i != m_index.End() )
         return true;
      String name = object.UTF8ToUTF16();
      for ( const Index& index : m_index )
         if ( index.objectName.CompareIC( name ) == 0 )
            if ( origin.IsEmpty() || index.originId == origin )
               return true;
      return false;
   }
 
   String ObjectName( const IsoString& object, const IsoString& origin = IsoString() ) const
   {
      Array<Index>::const_iterator i = BinarySearch( m_index.Begin(), m_index.End(), Index( object, origin ) );
      if ( i != m_index.End() )
         return i->objectName;
      return String();
   }
 
   const EphemerisMetadata& Metadata() const
   {
      return m_metadata;
   }
 
   int NumberOfHandles() const
   {
      return m_handleCount.Load();
   }
 
   static void Serialize( const String& filePath,
                          TimePoint startTime, TimePoint endTime,
                          const SerializableEphemerisObjectDataList& data,
                          const EphemerisMetadata& metadata = EphemerisMetadata(),
                          const EphemerisConstantList& constants = EphemerisConstantList() );
 
   static const EphemerisFile& FundamentalEphemerides();
 
   static const EphemerisFile& ShortTermFundamentalEphemerides();
 
   static const EphemerisFile& AsteroidEphemerides();
 
   static const EphemerisFile& ShortTermAsteroidEphemerides();
 
   static const EphemerisFile& KBOEphemerides();
 
   static const EphemerisFile& ShortTermKBOEphemerides();
 
   static const EphemerisFile& NutationModel();
 
   static const EphemerisFile& ShortTermNutationModel();
 
   static String DeltaTDataFilePath();
 
   static String DeltaATDataFilePath();
 
   static String CIP_ITRSDataFilePath();
 
   static void OverrideFundamentalEphemerides( const String& filePath );
 
   static void OverrideShortTermFundamentalEphemerides( const String& filePath );
 
   static void OverrideAsteroidEphemerides( const String& filePath );
 
   static void OverrideShortTermAsteroidEphemerides( const String& filePath );
 
   static void OverrideKBOEphemerides( const String& filePath );
 
   static void OverrideShortTermKBOEphemerides( const String& filePath );
 
   static void OverrideNutationModel( const String& filePath );
 
   static void OverrideShortTermNutationModel( const String& filePath );
 
   static void OverrideDeltaTDataFilePath( const String& filePath );
 
   static void OverrideDeltaATDataFilePath( const String& filePath );
 
   static void OverrideCIP_ITRSDataFilePath( const String& filePath );
 
private:
 
   struct IndexNode
   {
      int32 jdi = 0;      // Starting point of time span covered by this expansion, int( JD ).
      float jdf = 0;      // Ditto, frac( JD ).
      uint8 n[ 4 ] = {};  // For each component: number of Chebyshev coefficients in this expansion.
      int64 position = 0; // File byte position of first Chebyshev coefficient.
 
      constexpr bool operator ==( const IndexNode& n ) const
      {
         return jdi == n.jdi && jdf == n.jdf;
      }
 
      constexpr bool operator <( const IndexNode& n ) const
      {
         return jdi < n.jdi || jdi == n.jdi && jdf < n.jdf;
      }
 
      constexpr int NumberOfComponents() const
      {
         return (n[0] > 0) ? ((n[1] > 0) ? ((n[2] > 0) ? ((n[3] > 0) ? 4 : 3) : 2) : 1) : 0;
      }
 
      constexpr int NumberOfCoefficients() const
      {
         return n[0] + n[1] + n[2] + n[3];
      }
 
      TimePoint StartTime() const
      {
         return TimePoint( jdi, jdf );
      }
   };
 
   struct Index
   {
      IsoString        objectId;          // Object identifier (mandatory, case-sensitive).
      IsoString        originId;          // Identifier of the origin of coordinates (mandatory, case-sensitive).
      String           objectName;        // Object name (optional, case-insensitive).
      String           objectDescription; // Object description (optional, arbitrary)
      Optional<double> H;                 // Asteroid absolute magnitude.
      Optional<double> G;                 // Asteroid magnitude slope parameter.
      Optional<double> M1;                // Comet total absolute magnitude.
      Optional<double> K1;                // Comet total magnitude slope parameter.
      Optional<double> M2;                // Comet nuclear absolute magnitude.
      Optional<double> K2;                // Comet nuclear magnitude slope parameter.
      Optional<double> PC;                // Comet nuclear magnitude phase coefficient parameter.
      Optional<double> B_V;               // Color index B-V in magnitudes.
      Optional<double> U_B;               // Color index U-B in magnitudes.
      Optional<double> I_R;               // Color index I-R in magnitudes.
      Optional<double> D;                 // Diameter of the object in km.
      Optional<double> A1;                // Comet non-gravitational acceleration, radial component (au/day^2).
      Optional<double> A2;                // Comet non-gravitational acceleration, transverse component (au/day^2).
      Optional<double> A3;                // Comet non-gravitational acceleration, normal component (au/day^2).
      Optional<double> DT;                // Comet non-gravitational acceleration, perihelion time offset (days).
      Array<IndexNode> nodes[ 2 ];        // Expansion indexes: 0=function 1=derivative.
 
      Index( const IsoString& objectId_,
             const IsoString& originId_ = IsoString(),
             const String& objectName_ = String(),
             const String& objectDescription_ = String() )
         : objectId( objectId_.Trimmed() )
         , originId( originId_.Trimmed() )
         , objectName( objectName_.Trimmed() )
         , objectDescription( objectDescription_.Trimmed() )
      {
      }
 
      bool operator ==( const Index& x ) const
      {
         return objectId == x.objectId && originId == x.originId;
      }
 
      bool operator <( const Index& x ) const
      {
         return (objectId != x.objectId) ? objectId < x.objectId : originId < x.originId;
      }
 
      bool HasDerivative() const
      {
         return !nodes[1].IsEmpty();
      }
   };
 
   mutable File                  m_file;
   mutable AtomicInt             m_handleCount;
   mutable Mutex                 m_mutex;
           TimePoint             m_startTime;
           TimePoint             m_endTime;
           EphemerisMetadata     m_metadata;
           EphemerisConstantList m_constants;
           Array<Index>          m_index;
 
   // Current data files.
   // If empty, i.e. if not overridden, use platform defaults.
   static String s_ephFilePath;
   static String s_ephFilePath_s;
   static String s_astFilePath;
   static String s_astFilePath_s;
   static String s_kboFilePath;
   static String s_kboFilePath_s;
   static String s_nutFilePath;
   static String s_nutFilePath_s;
   static String s_deltaTFilePath;
   static String s_deltaATFilePath;
   static String s_cipITRSFilePath;
 
   const Index* FindObject( const IsoString& object, const IsoString& origin ) const
   {
      if ( origin.IsEmpty() )
      {
         for ( const Index& index : m_index )
            if ( index.objectId == object )
               return &index;
      }
      else
      {
         Array<Index>::const_iterator i = BinarySearch( m_index.Begin(), m_index.End(), Index( object, origin ) );
         if ( i != m_index.End() )
            return i;
      }
      String name = object.UTF8ToUTF16();
      for ( const Index& index : m_index )
         if ( index.objectName.CompareIC( name ) == 0 )
            if ( origin.IsEmpty() || index.originId == origin )
               return &index;
      throw Error( "Unavailable object '" + name + "\' with origin '" + String( origin ) + "'." );
   }
 
public:
 
   class PCL_CLASS Handle
   {
   public:
 
      Handle() = default;
 
      Handle( const EphemerisFile& parent, const IsoString& object, const IsoString& origin = IsoString() )
      {
         if ( !parent.IsOpen() )
            throw Error( "Cannot create a handle to a closed ephemeris file." );
         m_parent = &parent;
         m_parent->m_handleCount.Increment();
         m_index = m_parent->FindObject( object, origin );
      }
 
      Handle( const Handle& x )
      {
         if ( m_parent != nullptr )
            m_parent->m_handleCount.Decrement();
         m_parent = x.m_parent;
         m_index = x.m_index;
         m_node[0] = x.m_node[0];
         m_node[1] = x.m_node[1];
         m_node[2] = x.m_node[2];
         if ( m_parent != nullptr )
            m_parent->m_handleCount.Increment();
      }
 
      Handle( Handle&& x )
      {
         m_parent = x.m_parent;
         x.m_parent = nullptr;
         m_index = x.m_index;
         m_node[0] = x.m_node[0];
         m_node[1] = x.m_node[1];
         m_node[2] = x.m_node[2];
      }
 
      virtual ~Handle()
      {
         if ( m_parent != nullptr )
            m_parent->m_handleCount.Decrement();
      }
 
      Handle& operator =( const Handle& x )
      {
         if ( m_parent != nullptr )
            m_parent->m_handleCount.Decrement();
         m_parent = x.m_parent;
         m_index = x.m_index;
         m_node[0] = x.m_node[0];
         m_node[1] = x.m_node[1];
         m_node[2] = x.m_node[2];
         if ( m_parent != nullptr )
            m_parent->m_handleCount.Increment();
         return *this;
      }
 
      Handle& operator =( Handle&& x )
      {
         if ( m_parent != nullptr )
            m_parent->m_handleCount.Decrement();
         m_parent = x.m_parent;
         x.m_parent = nullptr;
         m_index = x.m_index;
         m_node[0] = x.m_node[0];
         m_node[1] = x.m_node[1];
         m_node[2] = x.m_node[2];
         return *this;
      }
 
      void ComputeState( Vector& p, TimePoint t )
      {
         Update( t, 0 );
         p = m_node[0].expansion( t - m_node[0].startTime );
      }
 
      void ComputeState( Vector& p, Vector& v, TimePoint t )
      {
         ComputeState( p, t );
         ComputeFirstDerivative( v, t );
      }
 
      void ComputeFirstDerivative( Vector& v, TimePoint t )
      {
         if ( HasDerivative() )
            Update( t, 1 );
         else if ( m_node[1].current != m_node[0].current )
         {
            m_node[1].current = m_node[0].current;
            m_node[1].startTime = m_node[0].startTime;
            m_node[1].endTime = m_node[0].endTime;
            m_node[1].expansion = m_node[0].expansion.Derivative();
         }
         v = m_node[1].expansion( t - m_node[1].startTime );
      }
 
      void ComputeSecondDerivative( Vector& a, TimePoint t )
      {
         if ( HasDerivative() )
            Update( t, 1 );
         else if ( m_node[1].current != m_node[0].current )
         {
            m_node[1].current = m_node[0].current;
            m_node[1].startTime = m_node[0].startTime;
            m_node[1].endTime = m_node[0].endTime;
            m_node[1].expansion = m_node[0].expansion.Derivative();
         }
         if ( m_node[2].current != m_node[0].current )
         {
            m_node[2].current = m_node[0].current;
            m_node[2].startTime = m_node[0].startTime;
            m_node[2].endTime = m_node[0].endTime;
            m_node[2].expansion = m_node[1].expansion.Derivative();
         }
         a = m_node[2].expansion( t - m_node[2].startTime );
      }
 
      Vector StateVector( TimePoint t )
      {
         Vector p;
         ComputeState( p, t );
         return p;
      }
 
      MultiVector StateVectors( TimePoint t )
      {
         Vector p, v;
         ComputeState( p, v, t );
         return MultiVector( p, v );
      }
 
      Vector FirstDerivative( TimePoint t )
      {
         Vector v;
         ComputeFirstDerivative( v, t );
         return v;
      }
 
      Vector SecondDerivative( TimePoint t )
      {
         Vector v;
         ComputeSecondDerivative( v, t );
         return v;
      }
 
      const EphemerisFile& ParentFile() const
      {
         return *m_parent;
      }
 
      const IsoString& ObjectId() const
      {
         return m_index->objectId;
      }
 
      const IsoString& OriginId() const
      {
         return m_index->originId;
      }
 
      const String& ObjectName() const
      {
         return m_index->objectName;
      }
 
      TimePoint StartTime( int i = 0 ) const
      {
         return m_node[Range( i, 0, 1 )].startTime;
      }
 
      TimePoint EndTime( int i = 0 ) const
      {
         return m_node[Range( i, 0, 1 )].endTime;
      }
 
      bool HasDerivative() const
      {
         return m_index->HasDerivative();
      }
 
      const Optional<double>& H() const
      {
         return m_index->H;
      }
 
      const Optional<double>& G() const
      {
         return m_index->G;
      }
 
      const Optional<double>& M1() const
      {
         return m_index->M1;
      }
 
      const Optional<double>& K1() const
      {
         return m_index->K1;
      }
 
      const Optional<double>& M2() const
      {
         return m_index->M2;
      }
 
      const Optional<double>& K2() const
      {
         return m_index->K2;
      }
 
      const Optional<double>& PC() const
      {
         return m_index->PC;
      }
 
      const Optional<double>& B_V() const
      {
         return m_index->B_V;
      }
 
      const Optional<double>& U_B() const
      {
         return m_index->U_B;
      }
 
      const Optional<double>& I_R() const
      {
         return m_index->I_R;
      }
 
      const Optional<double>& D() const
      {
         return m_index->D;
      }
 
      const Optional<double>& A1() const
      {
         return m_index->A1;
      }
 
      const Optional<double>& A2() const
      {
         return m_index->A2;
      }
 
      const Optional<double>& A3() const
      {
         return m_index->A3;
      }
 
      const Optional<double>& DT() const
      {
         return m_index->DT;
      }
 
   private:
 
      struct NodeInfo
      {
         int          current = -1;
         TimePoint    startTime;
         TimePoint    endTime;
         ChebyshevFit expansion;
      };
 
      const EphemerisFile*        m_parent = nullptr;
      const EphemerisFile::Index* m_index = nullptr;
            NodeInfo              m_node[ 3 ];
            uint64                m_uniqueId = UniqueId();
 
      static uint64 UniqueId();
 
      void Update( TimePoint t, int index )
      {
         if ( !t.IsValid() )
            throw Error( "Invalid time point." );
         if ( t < m_parent->StartTime() || t > m_parent->EndTime() )
            throw Error( "Time point out of range: " + t.ToString() );
 
         const Array<IndexNode>& nodes = m_index->nodes[index];
         NodeInfo& info = m_node[index];
 
         for ( int N = int( nodes.Length() ), l = 0, r = N-1; ; )
         {
            int m = (l + r) >> 1;
            const IndexNode& node = nodes[m];
            TimePoint t0 = node.StartTime();
            if ( t < t0 )
               r = m;
            else
            {
               if ( m == N-1 || t < nodes[m+1].StartTime() )
               {
                  if ( m != info.current )
                  {
                     ChebyshevFit::coefficient_series coefficients;
                     {
                        volatile AutoLock lock( m_parent->m_mutex );
                        m_parent->m_file.SetPosition( node.position );
                        for ( int i = 0, n = node.NumberOfComponents(); i < n; ++i )
                        {
                           Vector c( node.n[i] );
                           m_parent->m_file.Read( reinterpret_cast<void*>( c.Begin() ), c.Size() );
                           coefficients << c;
                        }
                     }
                     info.current = m;
                     info.startTime = t0;
                     info.endTime = (m < N-1) ? nodes[m+1].StartTime() : m_parent->EndTime();
                     info.expansion = ChebyshevFit( coefficients, 0, info.endTime - info.startTime );
                  }
                  break;
               }
 
               l = m + 1;
            }
         }
      }
 
      friend class PCL_CLASS Position;
   };
 
private:
 
#if defined( __clang__ )
# pragma GCC diagnostic ignored "-Wunused-private-field"
#endif
 
   /*
    * For the core JavaScript engine we need garbage-collector-safe
    * asynchronous destruction of these objects.
    */
   mutable bool m_finalized = false;
 
   /*
    * In the core JavaScript engine we must identify static objects that can be
    * shared and must never be destroyed. This includes fundamental
    * ephemerides, nutation, etc.
    */
   mutable bool m_internal = false;
 
#if defined( __clang__ )
# pragma GCC diagnostic warning "-Wunused-private-field"
#endif
 
   class DeserializeObjectThread : public Thread
   {
   public:
 
      DeserializeObjectThread( const Array<const XMLElement*>& elements
                              , File& file, fsize_type fileSize, fsize_type minPos
                              , int startIndex, int endIndex )
         : m_elements( elements )
         , m_startIndex( startIndex )
         , m_endIndex( endIndex )
         , m_file( file )
         , m_fileSize( fileSize )
         , m_minPos( minPos )
      {
      }
 
      void Run() override;
 
      const Array<Index>& Objects() const
      {
         return m_index;
      }
 
      bool Succeeded() const
      {
         return m_success;
      }
 
      const Exception* ExceptionThrown() const
      {
         return m_exception.Ptr();
      }
 
   private:
 
      const Array<const XMLElement*>& m_elements;
            int                       m_startIndex, m_endIndex;
            File&                     m_file;
            fsize_type                m_fileSize, m_minPos;
            Array<Index>              m_index;
            AutoPointer<Exception>    m_exception;
            bool                      m_success = false;
   };
 
#ifdef __PCL_BUILDING_PIXINSIGHT_APPLICATION
   friend class pi::JSEphemerisFileObject;
   friend class pi::JSEphemerisHandleObject;
#endif
};
 
// ----------------------------------------------------------------------------
 
} // pcl
 
#endif  // __PCL_EphemerisFile_h
 
// ----------------------------------------------------------------------------
// EOF pcl/EphemerisFile.h - Released 2024-06-18T15:48:54Z