XISF.h

Go to the documentation of this file.

//     ____   ______ __
//    / __ \ / ____// /
//   / /_/ // /    / /
//  / ____// /___ / /___   PixInsight Class Library
// /_/     \____//_____/   PCL 2.9.3
// ----------------------------------------------------------------------------
// pcl/XISF.h - Released 2025-02-21T12:13:32Z
// ----------------------------------------------------------------------------
// This file is part of the PixInsight Class Library (PCL).
// PCL is a multiplatform C++ framework for development of PixInsight modules.
//
// Copyright (c) 2003-2025 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_XISF_h
#define __PCL_XISF_h
 
 
#include <pcl/Defs.h>
 
#include <pcl/AutoPointer.h>
#include <pcl/ColorFilterArray.h>
#include <pcl/DisplayFunction.h>
#include <pcl/FITSHeaderKeyword.h>
#include <pcl/ICCProfile.h>
#include <pcl/Image.h>
#include <pcl/ImageInfo.h>
#include <pcl/ImageOptions.h>
#include <pcl/Property.h>
#include <pcl/XML.h>
 
namespace pcl
{
 
// ----------------------------------------------------------------------------
 
// ----------------------------------------------------------------------------
 
class XISFReaderEngine;
class XISFWriterEngine;
 
class PCL_CLASS Compression;
class PCL_CLASS CryptographicHash;
 
// ----------------------------------------------------------------------------
 
namespace XISFChecksum
{
   enum value_type
   {
      Unknown = -1,
      None = 0,
      SHA1,
      SHA256,
      SHA512,
      NumberOfSupportedAlgorithms
   };
}
 
// ----------------------------------------------------------------------------
 
namespace XISFCompression
{
   enum value_type
   {
      Unknown = -1,
      None = 0,
      Zlib,
      LZ4,
      LZ4HC,
      Zstd,
      Zlib_Sh,
      LZ4_Sh,
      LZ4HC_Sh,
      Zstd_Sh,
      NumberOfSupportedCodecs
   };
}
 
// ----------------------------------------------------------------------------
 
namespace XISFByteOrder
{
   enum value_type
   {
      LittleEndian,
      BigEndian
   };
}
 
// ----------------------------------------------------------------------------
 
class PCL_CLASS XISF
{
public:
 
   using property_type = VariantType::value_type;
 
   using image_type = ImageType::value_type;
 
   using color_space = ColorSpace::value_type;
 
   using block_checksum = XISFChecksum::value_type;
 
   using block_compression = XISFCompression::value_type;
 
   using block_endianness = XISFByteOrder::value_type;
 
   XISF() = delete;
 
   XISF( const XISF& ) = delete;
 
   XISF& operator =( const XISF& ) = delete;
 
   ~XISF() = delete;
 
   /*
    * ### N.B.: As of version 1.8.5.1309: Clang on macOS does not know how to
    * compile the following constexpr static members, giving buggy 'Undefined
    * symbols for architecture x86_64' errors on some modules...
    */
#ifndef __clang__
 
   constexpr static fsize_type DefaultBlockAlignSize = 4096;
 
   constexpr static fsize_type DefaultMaxBlockInlineSize = 3072; // 3072*4/3 = 4096 (base64)
 
   constexpr static int MaxThumbnailSize = 1024;
 
   constexpr static block_checksum DefaultChecksum = XISFChecksum::None;
 
   constexpr static block_compression DefaultCompression = XISFCompression::None;
 
   constexpr static int DefaultCompressionLevel = 0;
 
   constexpr static int MaxCompressionLevel = 100;
 
   constexpr static int DefaultVerbosity = 1;
 
   constexpr static bool DefaultFixNonFinite = true;
 
   constexpr static double DefaultOutputLowerBound = 0.0;
 
   constexpr static double DefaultOutputUpperBound = 1.0;
 
   constexpr static bool DefaultStoreFITSKeywords = true;
 
   constexpr static bool DefaultIgnoreFITSKeywords = false;
 
   constexpr static bool DefaultImportFITSKeywords = false;
 
   constexpr static bool DefaultIgnoreEmbeddedData = false;
 
   constexpr static bool DefaultIgnoreProperties = false;
 
   constexpr static bool DefaultAutoMetadata = true;
 
   constexpr static bool DefaultNoWarnings = false;
 
   constexpr static bool DefaultWarningsAreErrors = false;
 
   constexpr static const char* InternalNamespacePrefix = "XISF:";
 
   constexpr static int InternalNamespacePrefixLength = 5;
 
#else
 
   static const fsize_type DefaultBlockAlignSize;
   static const fsize_type DefaultMaxBlockInlineSize;
   static const int MaxThumbnailSize;
   static const block_checksum DefaultChecksum;
   static const block_compression DefaultCompression;
   static const int DefaultCompressionLevel;
   static const int MaxCompressionLevel;
   static const int DefaultVerbosity;
   static const bool DefaultFixNonFinite;
   static const double DefaultOutputLowerBound;
   static const double DefaultOutputUpperBound;
   static const bool DefaultStoreFITSKeywords;
   static const bool DefaultIgnoreFITSKeywords;
   static const bool DefaultImportFITSKeywords;
   static const bool DefaultIgnoreEmbeddedData;
   static const bool DefaultIgnoreProperties;
   static const bool DefaultAutoMetadata;
   static const bool DefaultNoWarnings;
   static const bool DefaultWarningsAreErrors;
   static const char* InternalNamespacePrefix;
   static const int InternalNamespacePrefixLength;
 
#endif // !__clang__
 
   static const char* SampleFormatId( int bitsPerSample, bool floatSample, bool complexSample );
 
   template <class P>
   static const char* SampleFormatId( const GenericImage<P>& image )
   {
      return SampleFormatId( P::BitsPerSample(), P::IsFloatSample(), P::IsComplexSample() );
   }
 
   static bool GetSampleFormatFromId( int& bitsPerSample, bool& floatSample, bool& complexSample, const String& id );
 
   static const char* ColorSpaceId( color_space colorSpace );
 
   static const char* ColorSpaceId( const AbstractImage& image )
   {
      return ColorSpaceId( image.ColorSpace() );
   }
 
   static color_space ColorSpaceFromId( const String& id );
 
   static const char* PropertyTypeId( property_type type );
 
   static property_type PropertyTypeFromId( const String& id );
 
   static const char* CompressionCodecId( block_compression codec );
 
   static block_compression CompressionCodecFromId( const String& id );
 
   static Compression* NewCompression( block_compression codec, size_type itemSize = 1 );
 
   static int CompressionLevelForMethod( block_compression codec, int level );
 
   static bool CompressionUsesByteShuffle( block_compression codec );
 
   static block_compression CompressionCodecNoShuffle( block_compression codec );
 
   static bool CompressionNeedsItemSize( block_compression codec );
 
   static const char* ChecksumAlgorithmId( block_checksum algorithm );
 
   static block_checksum ChecksumAlgorithmFromId( const String& id );
 
   static size_type ChecksumLength( block_checksum algorithm );
 
   static CryptographicHash* NewCryptographicHash( block_checksum algorithm );
 
   static const char* ImageTypeId( image_type type );
 
   static image_type ImageTypeFromId( const String& id );
 
   static bool IsValidPropertyId( const IsoString& id )
   {
      return Property::IsValidIdentifier( id );
   }
 
   static bool IsValidPropertyId( const IsoString::ustring_base& id )
   {
      return IsValidPropertyId( IsoString( id ) );
   }
 
   static bool IsInternalPropertyId( const IsoString& id )
   {
      return id.StartsWith( InternalNamespacePrefix );
   }
 
   static bool IsInternalPropertyId( const IsoString::ustring_base& id )
   {
      return IsInternalPropertyId( IsoString( id ) );
   }
 
   static IsoString InternalPropertyId( const IsoString& id )
   {
      if ( !IsInternalPropertyId( id ) )
         return InternalNamespacePrefix + id;
      return id;
   }
 
   static IsoString InternalPropertyId( const IsoString::ustring_base& id )
   {
      return InternalPropertyId( IsoString( id ) );
   }
 
   static bool IsReservedImagePropertyId( const IsoString& id )
   {
      if ( id.StartsWith( "Image:" ) )
      {
         const char* name = id.At( 6 );
         return ::strcmp( name, "Id" ) == 0
             || ::strcmp( name, "Type" ) == 0;
      }
      return false;
   }
 
   static void EnsurePTLUTInitialized();
};
 
// ----------------------------------------------------------------------------
 
class PCL_CLASS XISFOptions
{
public:
 
   bool                    storeFITSKeywords  : 1;  
   bool                    ignoreFITSKeywords : 1;  
   bool                    importFITSKeywords : 1;  
   bool                    ignoreEmbeddedData : 1;  
   bool                    ignoreProperties   : 1;  
   bool                    autoMetadata       : 1;  
   bool                    noWarnings         : 1;  
   bool                    warningsAreErrors  : 1;  
   XISF::block_checksum    checksumAlgorithm  : 4;  
   XISF::block_compression compressionCodec   : 5;  
   uint8                   compressionLevel   : 7;  
   uint8                   verbosity          : 3;  
   bool                    fixNonFinite       : 1;  
   uint16                  blockAlignmentSize;      
   uint16                  maxInlineBlockSize;      
   double                  outputLowerBound;        
   double                  outputUpperBound;        
 
   XISFOptions()
   {
      Reset();
   }
 
   XISFOptions( const XISFOptions& ) = default;
 
   XISFOptions& operator =( const XISFOptions& ) = default;
 
   void Reset()
   {
      storeFITSKeywords  = XISF::DefaultStoreFITSKeywords;
      ignoreFITSKeywords = XISF::DefaultIgnoreFITSKeywords;
      importFITSKeywords = XISF::DefaultImportFITSKeywords;
      ignoreEmbeddedData = XISF::DefaultIgnoreEmbeddedData;
      ignoreProperties   = XISF::DefaultIgnoreProperties;
      autoMetadata       = XISF::DefaultAutoMetadata;
      noWarnings         = XISF::DefaultNoWarnings;
      warningsAreErrors  = XISF::DefaultWarningsAreErrors;
      checksumAlgorithm  = XISF::DefaultChecksum;
      compressionCodec   = XISF::DefaultCompression;
      compressionLevel   = XISF::DefaultCompressionLevel;
      verbosity          = XISF::DefaultVerbosity;
      fixNonFinite       = XISF::DefaultFixNonFinite;
      blockAlignmentSize = XISF::DefaultBlockAlignSize;
      maxInlineBlockSize = XISF::DefaultMaxBlockInlineSize;
      outputLowerBound   = XISF::DefaultOutputLowerBound;
      outputUpperBound   = XISF::DefaultOutputUpperBound;
   }
};
 
// ----------------------------------------------------------------------------
 
struct PCL_CLASS XISFFileSignature
{
   uint8  magic[ 8 ]   = { 'X', 'I', 'S', 'F', '0', '1', '0', '0' };
   uint32 headerLength = 0;  // length in bytes of the XML file header
   uint32 reserved     = 0;  // reserved - must be zero
 
   XISFFileSignature() = default;
 
   XISFFileSignature( const XISFFileSignature& ) = default;
 
   XISFFileSignature& operator =( const XISFFileSignature& ) = default;
 
   XISFFileSignature( uint32 length )
      : headerLength( length )
   {
   }
 
   void Validate() const;
};
 
// ----------------------------------------------------------------------------
 
namespace XISFMessageType
{
   enum value_type
   {
      Informative,
      Note,
      Warning,
      RecoverableError
   };
}
 
// ----------------------------------------------------------------------------
 
class PCL_CLASS XISFLogHandler
{
public:
 
   using message_type = XISFMessageType::value_type;
 
   XISFLogHandler() = default;
 
   virtual ~XISFLogHandler()
   {
   }
 
   virtual void Init( const String& filePath, bool writing )
   {
   }
 
   virtual void Log( const String& text, message_type type )
   {
   }
 
   virtual void Close()
   {
   }
};
 
// ----------------------------------------------------------------------------
 
class PCL_CLASS XISFReader
{
public:
 
   XISFReader();
 
   virtual ~XISFReader() noexcept( false );
 
   /*
    * Copy constructor. This constructor is disabled because %XISF streams are
    * unique objects.
    */
   XISFReader( const XISFReader& ) = delete;
 
   /*
    * Copy assignment. This operator is disabled because %XISF streams are
    * unique objects.
    */
   XISFReader& operator =( const XISFReader& ) = delete;
 
   void SetOptions( const pcl::XISFOptions& options );
 
   pcl::XISFOptions Options() const
   {
      return m_options;
   }
 
   void SetHints( const IsoString& );
 
   void SetLogHandler( XISFLogHandler* handler );
 
   bool IsOpen() const;
 
   void Open( const String& path );
 
   void Close();
 
   String FilePath() const;
 
   int NumberOfImages() const;
 
   void SelectImage( int index );
 
   int SelectedImageIndex() const;
 
   pcl::ImageInfo ImageInfo() const;
 
   pcl::ImageOptions ImageOptions() const;
 
   void SetImageOptions( const pcl::ImageOptions& options );
 
   IsoString ImageId() const;
 
   FITSKeywordArray ReadFITSKeywords();
 
   ICCProfile ReadICCProfile();
 
   UInt8Image ReadThumbnail();
 
   RGBColorSystem ReadRGBWorkingSpace();
 
   DisplayFunction ReadDisplayFunction();
 
   ColorFilterArray ReadColorFilterArray();
 
   PropertyDescriptionArray ImagePropertyDescriptions() const;
 
   Variant ReadImageProperty( const IsoString& identifier );
 
   PropertyArray ReadImageProperties();
 
   PropertyDescriptionArray PropertyDescriptions() const;
 
   Variant ReadProperty( const IsoString& identifier );
 
   PropertyArray ReadProperties();
 
   void ReadImage( FImage& image );
 
   void ReadImage( DImage& image );
 
   void ReadImage( ComplexImage& image );
 
   void ReadImage( DComplexImage& image );
 
   void ReadImage( UInt8Image& image );
 
   void ReadImage( UInt16Image& image );
 
   void ReadImage( UInt32Image& image );
 
   bool ImplementsIncrementalRead() const;
 
   void ReadSamples( FImage::sample* buffer, int startRow, int rowCount, int channel );
 
   void ReadSamples( DImage::sample* buffer, int startRow, int rowCount, int channel );
 
   void ReadSamples( ComplexImage::sample* buffer, int startRow, int rowCount, int channel );
 
   void ReadSamples( DComplexImage::sample* buffer, int startRow, int rowCount, int channel );
 
   void ReadSamples( UInt8Image::sample* buffer, int startRow, int rowCount, int channel );
 
   void ReadSamples( UInt16Image::sample* buffer, int startRow, int rowCount, int channel );
 
   void ReadSamples( UInt32Image::sample* buffer, int startRow, int rowCount, int channel );
 
   static XMLDocument* ExtractHeader( const String& path, XMLParserOptions options = XMLParserOptions() );
 
private:
 
   AutoPointer<XISFReaderEngine> m_engine;
   AutoPointer<XISFLogHandler>   m_logHandler;
   XISFOptions                   m_options;
   IsoString                     m_hints;
 
   void CheckOpenStream( const char* ) const;
   void CheckClosedStream( const char* ) const;
};
 
// ----------------------------------------------------------------------------
 
class PCL_CLASS XISFWriter
{
public:
 
   XISFWriter();
 
   virtual ~XISFWriter() noexcept( false );
 
   /*
    * Copy constructor. This constructor is disabled because %XISF streams are
    * unique objects.
    */
   XISFWriter( const XISFWriter& ) = delete;
 
   /*
    * Copy assignment. This operator is disabled because %XISF streams are
    * unique objects.
    */
   XISFWriter& operator =( const XISFWriter& ) = delete;
 
   void SetOptions( const pcl::XISFOptions& options );
 
   pcl::XISFOptions Options() const
   {
      return m_options;
   }
 
   void SetHints( const IsoString& );
 
   void SetLogHandler( XISFLogHandler* handler );
 
   void SetCreatorApplication( const String& appName );
 
   void SetCreatorModule( const String& modName );
 
   bool IsOpen() const;
 
   void Create( const String& path, int count );
 
   void Close();
 
   String FilePath() const;
 
   void SetImageOptions( const ImageOptions& options );
 
   void SetImageId( const IsoString& id );
 
   void WriteFITSKeywords( const FITSKeywordArray& keywords );
 
   const FITSKeywordArray& FITSKeywords() const;
 
   void WriteICCProfile( const ICCProfile& profile );
 
   void WriteThumbnail( const UInt8Image& thumbnail );
 
   void WriteRGBWorkingSpace( const RGBColorSystem& rgbws );
 
   void WriteDisplayFunction( const DisplayFunction& df );
 
   void WriteColorFilterArray( const ColorFilterArray& cfa );
 
   void WriteImageProperty( const IsoString& identifier, const Variant& value );
 
   void WriteImageProperties( const PropertyArray& properties );
 
   void RemoveImageProperty( const IsoString& identifier );
 
   void WriteProperty( const IsoString& identifier, const Variant& value );
 
   void WriteProperties( const PropertyArray& properties );
 
   void RemoveProperty( const IsoString& identifier );
 
   void WriteImage( const Image& image );
 
   void WriteImage( const DImage& image );
 
   void WriteImage( const ComplexImage& image );
 
   void WriteImage( const DComplexImage& image );
 
   void WriteImage( const UInt8Image& image );
 
   void WriteImage( const UInt16Image& image );
 
   void WriteImage( const UInt32Image& image );
 
   void WriteImage( const ImageVariant& image );
 
   void CreateImage( const ImageInfo& info );
 
   void WriteSamples( const FImage::sample* buffer, int startRow, int rowCount, int channel );
 
   void WriteSamples( const DImage::sample* buffer, int startRow, int rowCount, int channel );
 
   void WriteSamples( const ComplexImage::sample* buffer, int startRow, int rowCount, int channel );
 
   void WriteSamples( const DComplexImage::sample* buffer, int startRow, int rowCount, int channel );
 
   void WriteSamples( const UInt8Image::sample* buffer, int startRow, int rowCount, int channel );
 
   void WriteSamples( const UInt16Image::sample* buffer, int startRow, int rowCount, int channel );
 
   void WriteSamples( const UInt32Image::sample* buffer, int startRow, int rowCount, int channel );
 
   void CloseImage();
 
private:
 
   AutoPointer<XISFWriterEngine> m_engine;
   AutoPointer<XISFLogHandler>   m_logHandler;
   XISFOptions                   m_options;
   IsoString                     m_hints;
   String                        m_creatorApplication;
   String                        m_creatorModule;
 
   void CheckOpenStream( const char* ) const;
   void CheckClosedStream( const char* ) const;
};
 
// ----------------------------------------------------------------------------
 
} // pcl
 
#endif   // __PCL_XISF_h
 
// ----------------------------------------------------------------------------
// EOF pcl/XISF.h - Released 2025-02-21T12:13:32Z