FileFormatImplementation.h

Go to the documentation of this file.

//     ____   ______ __
//    / __ \ / ____// /
//   / /_/ // /    / /
//  / ____// /___ / /___   PixInsight Class Library
// /_/     \____//_____/   PCL 2.7.0
// ----------------------------------------------------------------------------
// pcl/FileFormatImplementation.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_FileFormat_h
#define __PCL_FileFormat_h
 
 
#ifndef __PCL_BUILDING_PIXINSIGHT_APPLICATION
 
#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/ImageDescription.h>
#include <pcl/ImageVariant.h>
#include <pcl/MetaFileFormat.h>
#include <pcl/PropertyDescription.h>
#include <pcl/RGBColorSystem.h>
 
namespace pcl
{
 
struct FileFormatImplementationPrivate;
 
// ----------------------------------------------------------------------------
 
class PCL_CLASS FileFormatImplementation
{
public:
 
   FileFormatImplementation( const MetaFileFormat* m );
 
   virtual ~FileFormatImplementation() noexcept( false );
 
   /*
    * FileFormatImplementation instances (e.g., image files) are unique.
    */
 
   FileFormatImplementation( const FileFormatImplementation& x ) = delete;
 
   FileFormatImplementation& operator =( const FileFormatImplementation& ) = delete;
 
   const MetaFileFormat* Meta() const
   {
      return meta;
   }
 
   virtual void Close();
 
   virtual bool IsOpen() const;
 
   virtual String FilePath() const;
 
   // Reader functionality
 
   virtual ImageDescriptionArray Open( const String& filePath, const IsoString& hints );
 
   virtual void SelectImage( int index );
 
   virtual int SelectedImageIndex() const;
 
   virtual void* FormatSpecificData() const;
 
   virtual String ImageFormatInfo() const
   {
      return String();
   }
 
   virtual ICCProfile ReadICCProfile();
 
   virtual RGBColorSystem ReadRGBWorkingSpace();
 
   virtual DisplayFunction ReadDisplayFunction();
 
   virtual ColorFilterArray ReadColorFilterArray();
 
   virtual UInt8Image ReadThumbnail();
 
   virtual FITSKeywordArray ReadFITSKeywords();
 
   virtual PropertyDescriptionArray PropertyDescriptions();
 
   virtual Variant ReadProperty( const IsoString& property );
 
   virtual PropertyDescriptionArray ImagePropertyDescriptions();
 
   virtual Variant ReadImageProperty( const IsoString& property );
 
   virtual void ReadImage( pcl::Image& image );
 
   virtual void ReadImage( pcl::DImage& image );
 
   virtual void ReadImage( UInt8Image& image );
 
   virtual void ReadImage( UInt16Image& image );
 
   virtual void ReadImage( UInt32Image& image );
 
   virtual bool CanReadIncrementally() const
   {
      return true; // allow incremental reads if the format supports them
   }
 
   virtual void ReadSamples( pcl::Image::sample* buffer, int startRow, int rowCount, int channel );
 
   virtual void ReadSamples( pcl::DImage::sample* buffer, int startRow, int rowCount, int channel );
 
   virtual void ReadSamples( UInt8Image::sample* buffer, int startRow, int rowCount, int channel );
 
   virtual void ReadSamples( UInt16Image::sample* buffer, int startRow, int rowCount, int channel );
 
   virtual void ReadSamples( UInt32Image::sample* buffer, int startRow, int rowCount, int channel );
 
   virtual bool WasInexactRead() const
   {
      return false;  // exact read operations assumed by default
   }
 
   // Writer functionality
 
   virtual bool QueryOptions( Array<ImageOptions>& options, Array<void*>& formatOptions )
   {
      return true;
   }
 
   virtual void Create( const String& filePath, int numberOfImages, const IsoString& hints );
 
   virtual void SetId( const IsoString& id )
   {
   }
 
   virtual void SetOptions( const ImageOptions& options )
   {
   }
 
   virtual void SetFormatSpecificData( const void* data );
 
   virtual void WriteICCProfile( const ICCProfile& icc );
 
   virtual void WriteRGBWorkingSpace( const RGBColorSystem& rgbws );
 
   virtual void WriteDisplayFunction( const DisplayFunction& df );
 
   virtual void WriteColorFilterArray( const ColorFilterArray& cfa );
 
   virtual void WriteThumbnail( const pcl::UInt8Image& image );
 
   virtual void WriteFITSKeywords( const FITSKeywordArray& keywords );
 
   virtual void WriteProperty( const IsoString& property, const Variant& value );
 
   virtual void WriteImageProperty( const IsoString& property, const Variant& value );
 
   virtual void WriteImage( const pcl::Image& image );
 
   virtual void WriteImage( const pcl::DImage& image );
 
   virtual void WriteImage( const UInt8Image& image );
 
   virtual void WriteImage( const UInt16Image& image );
 
   virtual void WriteImage( const UInt32Image& image );
 
   virtual void CreateImage( const ImageInfo& info );
 
   virtual void CloseImage();
 
   virtual bool CanWriteIncrementally() const
   {
      return true; // allow incremental writes if the format supports them
   }
 
   virtual void WriteSamples( const pcl::Image::sample* buffer, int startRow, int rowCount, int channel );
 
   virtual void WriteSamples( const pcl::DImage::sample* buffer, int startRow, int rowCount, int channel );
 
   virtual void WriteSamples( const UInt8Image::sample* buffer, int startRow, int rowCount, int channel );
 
   virtual void WriteSamples( const UInt16Image::sample* buffer, int startRow, int rowCount, int channel );
 
   virtual void WriteSamples( const UInt32Image::sample* buffer, int startRow, int rowCount, int channel );
 
   virtual bool WasLossyWrite() const
   {
      return false;  // lossless write operations assumed by default
   }
 
protected:
 
   /*
    * The file format to which this instance belongs.
    */
   const MetaFileFormat* meta = nullptr;
 
private:
 
   /*
    * Internal stuff to automate low-level C API communication.
    */
   AutoPointer<FileFormatImplementationPrivate> m_data;
 
   ImageDescriptionArray m_description; // used exclusively by FileFormatDispatcher
 
   void BeginPrivate();
 
   void BeginICCProfileExtraction();
   const ICCProfile& GetICCProfile() const;
   void EndICCProfileExtraction();
 
   void BeginRGBWSExtraction();
   const RGBColorSystem& GetRGBWS() const;
   void EndRGBWSExtraction();
 
   void BeginDisplayFunctionExtraction();
   const DisplayFunction& GetDisplayFunction() const;
   void EndDisplayFunctionExtraction();
 
   void BeginColorFilterArrayExtraction();
   const ColorFilterArray& GetColorFilterArray() const;
   void EndColorFilterArrayExtraction();
 
   void BeginThumbnailExtraction();
   const UInt8Image& GetThumbnail() const;
   void EndThumbnailExtraction();
 
   void BeginKeywordExtraction();
   size_type NumberOfKeywords() const;
   bool GetNextKeyword( FITSHeaderKeyword& ) const;
   void EndKeywordExtraction();
 
   void BeginPropertyExtraction();
   const Variant& GetProperty( const IsoString& );
   void EndPropertyExtraction();
 
   void BeginImagePropertyExtraction();
   const Variant& GetImageProperty( const IsoString& );
   void EndImagePropertyExtraction();
 
   void BeginICCProfileEmbedding();
   void SetICCProfile( const ICCProfile& );
   void EndICCProfileEmbedding();
 
   void BeginRGBWSEmbedding();
   void SetRGBWS( const RGBColorSystem& );
   void EndRGBWSEmbedding();
 
   void BeginDisplayFunctionEmbedding();
   void SetDisplayFunction( const DisplayFunction& );
   void EndDisplayFunctionEmbedding();
 
   void BeginColorFilterArrayEmbedding();
   void SetColorFilterArray( const ColorFilterArray& );
   void EndColorFilterArrayEmbedding();
 
   void BeginThumbnailEmbedding();
   void SetThumbnail( const UInt8Image& );
   void EndThumbnailEmbedding();
 
   void BeginKeywordEmbedding();
   void AddKeyword( const FITSHeaderKeyword& );
   void EndKeywordEmbedding();
 
   void BeginPropertyEmbedding();
   void SetProperty( const IsoString&, const Variant& );
   void EndPropertyEmbedding();
 
   void BeginImagePropertyEmbedding();
   void SetImageProperty( const IsoString&, const Variant& );
   void EndImagePropertyEmbedding();
 
   friend class FileFormatDispatcher;
};
 
// ----------------------------------------------------------------------------
 
} // pcl
 
#endif   // __PCL_BUILDING_PIXINSIGHT_APPLICATION
 
#endif   // __PCL_FileFormat_h
 
// ----------------------------------------------------------------------------
// EOF pcl/FileFormatImplementation.h - Released 2024-06-18T15:48:54Z